thailint 0.1.5__py3-none-any.whl → 0.5.0__py3-none-any.whl

src/linters/file_header/linter.py

@@ -0,0 +1,313 @@
+"""
+File: src/linters/file_header/linter.py
+Purpose: Main file header linter rule implementation
+Exports: FileHeaderRule class
+Depends: BaseLintRule, PythonHeaderParser, FieldValidator, AtemporalDetector, ViolationBuilder
+Implements: Composition pattern with helper classes, AST-based Python parsing
+Related: config.py for configuration, python_parser.py for extraction
+
+Overview:
+    Orchestrates file header validation for Python files using focused helper classes.
+    Coordinates docstring extraction, field validation, atemporal language detection, and
+    violation building. Supports configuration from .thailint.yaml and ignore directives.
+    Validates headers against mandatory field requirements and atemporal language standards.
+
+Usage:
+    rule = FileHeaderRule()
+    violations = rule.check(context)
+
+Notes: Follows composition pattern from magic_numbers linter for maintainability
+"""
+
+from pathlib import Path
+
+from src.core.base import BaseLintContext, BaseLintRule
+from src.core.linter_utils import load_linter_config
+from src.core.types import Violation
+from src.linter_config.ignore import IgnoreDirectiveParser
+
+from .atemporal_detector import AtemporalDetector
+from .config import FileHeaderConfig
+from .field_validator import FieldValidator
+from .python_parser import PythonHeaderParser
+from .violation_builder import ViolationBuilder
+
+
+class FileHeaderRule(BaseLintRule):  # thailint: ignore[srp]
+    """Validates file headers for mandatory fields and atemporal language.
+
+    Method count (17) exceeds SRP guideline (8) because proper A-grade complexity
+    refactoring requires extracting helper methods. Class maintains single responsibility
+    of file header validation - all methods support this core purpose through composition
+    pattern with focused helper classes (parser, validator, detector, builder).
+    """
+
+    def __init__(self) -> None:
+        """Initialize the file header rule."""
+        self._violation_builder = ViolationBuilder(self.rule_id)
+        self._ignore_parser = IgnoreDirectiveParser()
+
+    @property
+    def rule_id(self) -> str:
+        """Unique identifier for this rule.
+
+        Returns:
+            Rule identifier string
+        """
+        return "file-header.validation"
+
+    @property
+    def rule_name(self) -> str:
+        """Human-readable name for this rule.
+
+        Returns:
+            Rule name string
+        """
+        return "File Header Validation"
+
+    @property
+    def description(self) -> str:
+        """Description of what this rule checks.
+
+        Returns:
+            Rule description string
+        """
+        return "Validates file headers for mandatory fields and atemporal language"
+
+    def check(self, context: BaseLintContext) -> list[Violation]:
+        """Check file header for violations.
+
+        Args:
+            context: Lint context with file information
+
+        Returns:
+            List of violations found in file header
+        """
+        # Only Python for now (PR3), multi-language in PR5
+        if context.language != "python":
+            return []
+
+        # Check for file-level ignore directives first
+        if self._has_file_ignore(context):
+            return []
+
+        # Load configuration
+        config = self._load_config(context)
+
+        # Check if file should be ignored by pattern
+        if self._should_ignore_file(context, config):
+            return []
+
+        # Extract and validate header
+        return self._check_python_header(context, config)
+
+    def _has_file_ignore(self, context: BaseLintContext) -> bool:
+        """Check if file has file-level ignore directive.
+
+        Args:
+            context: Lint context
+
+        Returns:
+            True if file has ignore-file directive
+        """
+        file_content = context.file_content or ""
+
+        if self._has_standard_ignore(file_content):
+            return True
+
+        return self._has_custom_ignore_syntax(file_content)
+
+    def _has_standard_ignore(self, file_content: str) -> bool:  # thailint: ignore[nesting]
+        """Check standard ignore parser for file-level ignores."""
+        # Check first 10 lines for standard ignore directives
+        first_lines = file_content.splitlines()[:10]
+        for line in first_lines:
+            if self._ignore_parser._has_ignore_directive_marker(line):  # pylint: disable=protected-access
+                if self._ignore_parser._check_specific_rule_ignore(line, self.rule_id):  # pylint: disable=protected-access
+                    return True
+                if self._ignore_parser._check_general_ignore(line):  # pylint: disable=protected-access
+                    return True
+        return False
+
+    def _has_custom_ignore_syntax(self, file_content: str) -> bool:
+        """Check custom file-level ignore syntax."""
+        first_lines = file_content.splitlines()[:10]
+        return any(self._is_ignore_line(line) for line in first_lines)
+
+    def _is_ignore_line(self, line: str) -> bool:
+        """Check if line contains ignore directive."""
+        line_lower = line.lower()
+        return "# thailint-ignore-file:" in line_lower or "# thailint-ignore" in line_lower
+
+    def _load_config(self, context: BaseLintContext) -> FileHeaderConfig:
+        """Load configuration from context.
+
+        Args:
+            context: Lint context
+
+        Returns:
+            FileHeaderConfig with loaded or default values
+        """
+        # Try production config first
+        if hasattr(context, "metadata") and isinstance(context.metadata, dict):
+            if "file_header" in context.metadata:
+                return load_linter_config(context, "file_header", FileHeaderConfig)  # type: ignore[type-var]
+
+        # Use defaults
+        return FileHeaderConfig()
+
+    def _should_ignore_file(self, context: BaseLintContext, config: FileHeaderConfig) -> bool:
+        """Check if file matches ignore patterns.
+
+        Args:
+            context: Lint context
+            config: File header configuration
+
+        Returns:
+            True if file should be ignored
+        """
+        if not context.file_path:
+            return False
+
+        file_path = Path(context.file_path)
+        return any(self._matches_ignore_pattern(file_path, p) for p in config.ignore)
+
+    def _matches_ignore_pattern(self, file_path: Path, pattern: str) -> bool:
+        """Check if file path matches a single ignore pattern."""
+        if file_path.match(pattern):
+            return True
+
+        if self._matches_directory_pattern(file_path, pattern):
+            return True
+
+        if self._matches_file_pattern(file_path, pattern):
+            return True
+
+        return pattern in str(file_path)
+
+    def _matches_directory_pattern(self, file_path: Path, pattern: str) -> bool:
+        """Match directory patterns like **/migrations/**."""
+        if pattern.startswith("**/") and pattern.endswith("/**"):
+            dir_name = pattern[3:-3]
+            return dir_name in file_path.parts
+        return False
+
+    def _matches_file_pattern(self, file_path: Path, pattern: str) -> bool:
+        """Match file patterns like **/__init__.py."""
+        if pattern.startswith("**/"):
+            filename_pattern = pattern[3:]
+            path_str = str(file_path)
+            return file_path.name == filename_pattern or path_str.endswith(filename_pattern)
+        return False
+
+    def _check_python_header(
+        self, context: BaseLintContext, config: FileHeaderConfig
+    ) -> list[Violation]:
+        """Check Python file header.
+
+        Args:
+            context: Lint context
+            config: Configuration
+
+        Returns:
+            List of violations filtered through ignore directives
+        """
+        parser = PythonHeaderParser()
+        header = parser.extract_header(context.file_content or "")
+
+        if not header:
+            return self._build_missing_header_violations(context)
+
+        fields = parser.parse_fields(header)
+        violations = self._validate_header_fields(fields, context, config)
+        violations.extend(self._check_atemporal_violations(header, context, config))
+
+        return self._filter_ignored_violations(violations, context)
+
+    def _build_missing_header_violations(self, context: BaseLintContext) -> list[Violation]:
+        """Build violations for missing header."""
+        return [
+            self._violation_builder.build_missing_field(
+                "docstring", str(context.file_path or ""), 1
+            )
+        ]
+
+    def _validate_header_fields(
+        self, fields: dict[str, str], context: BaseLintContext, config: FileHeaderConfig
+    ) -> list[Violation]:
+        """Validate mandatory header fields."""
+        violations = []
+        field_validator = FieldValidator(config)
+        field_violations = field_validator.validate_fields(fields, context.language)
+
+        for field_name, _error_message in field_violations:
+            violations.append(
+                self._violation_builder.build_missing_field(
+                    field_name, str(context.file_path or ""), 1
+                )
+            )
+        return violations
+
+    def _check_atemporal_violations(
+        self, header: str, context: BaseLintContext, config: FileHeaderConfig
+    ) -> list[Violation]:
+        """Check for atemporal language violations."""
+        if not config.enforce_atemporal:
+            return []
+
+        violations = []
+        atemporal_detector = AtemporalDetector()
+        atemporal_violations = atemporal_detector.detect_violations(header)
+
+        for pattern, description, line_num in atemporal_violations:
+            violations.append(
+                self._violation_builder.build_atemporal_violation(
+                    pattern, description, str(context.file_path or ""), line_num
+                )
+            )
+        return violations
+
+    def _filter_ignored_violations(
+        self, violations: list[Violation], context: BaseLintContext
+    ) -> list[Violation]:
+        """Filter out violations that should be ignored.
+
+        Args:
+            violations: List of violations to filter
+            context: Lint context with file content
+
+        Returns:
+            Filtered list of violations
+        """
+        file_content = context.file_content or ""
+        lines = file_content.splitlines()
+
+        filtered = []
+        for v in violations:
+            # Check standard ignore directives
+            if self._ignore_parser.should_ignore_violation(v, file_content):
+                continue
+
+            # Check custom line-level ignore syntax: # thailint-ignore-line:
+            if self._has_line_level_ignore(lines, v):
+                continue
+
+            filtered.append(v)
+
+        return filtered
+
+    def _has_line_level_ignore(self, lines: list[str], violation: Violation) -> bool:
+        """Check for thailint-ignore-line directive.
+
+        Args:
+            lines: File content split into lines
+            violation: Violation to check
+
+        Returns:
+            True if line has ignore directive
+        """
+        if violation.line <= 0 or violation.line > len(lines):
+            return False
+
+        line_content = lines[violation.line - 1]  # Convert to 0-indexed
+        return "# thailint-ignore-line:" in line_content.lower()

src/linters/file_header/python_parser.py

@@ -0,0 +1,86 @@
+"""
+File: src/linters/file_header/python_parser.py
+Purpose: Python docstring extraction and parsing for file headers
+Exports: PythonHeaderParser class
+Depends: Python ast module
+Implements: AST-based docstring extraction with field parsing
+Related: linter.py for parser usage, field_validator.py for field validation
+
+Overview:
+    Extracts module-level docstrings from Python files using AST parsing.
+    Parses structured header fields from docstring content and handles both
+    well-formed and malformed headers. Provides field extraction and validation
+    support for FileHeaderRule.
+
+Usage:
+    parser = PythonHeaderParser()
+    header = parser.extract_header(code)
+    fields = parser.parse_fields(header)
+
+Notes: Uses ast.get_docstring() for reliable module-level docstring extraction
+"""
+
+import ast
+
+
+class PythonHeaderParser:
+    """Extracts and parses Python file headers from docstrings."""
+
+    def extract_header(self, code: str) -> str | None:
+        """Extract module-level docstring from Python code.
+
+        Args:
+            code: Python source code
+
+        Returns:
+            Module docstring or None if not found or parse error
+        """
+        try:
+            tree = ast.parse(code)
+            return ast.get_docstring(tree)
+        except SyntaxError:
+            return None
+
+    def parse_fields(self, header: str) -> dict[str, str]:  # thailint: ignore[nesting]
+        """Parse structured fields from header text.
+
+        Args:
+            header: Header docstring text
+
+        Returns:
+            Dictionary mapping field_name -> field_value
+        """
+        fields: dict[str, str] = {}
+        current_field: str | None = None
+        current_value: list[str] = []
+
+        for line in header.split("\n"):
+            if self._is_new_field_line(line):
+                current_field = self._save_and_start_new_field(
+                    fields, current_field, current_value, line
+                )
+                current_value = [line.split(":", 1)[1].strip()]
+            elif current_field:
+                current_value.append(line.strip())
+
+        self._save_current_field(fields, current_field, current_value)
+        return fields
+
+    def _is_new_field_line(self, line: str) -> bool:
+        """Check if line starts a new field."""
+        return ":" in line and not line.startswith(" ")
+
+    def _save_and_start_new_field(
+        self, fields: dict[str, str], current_field: str | None, current_value: list[str], line: str
+    ) -> str:
+        """Save current field and start new one."""
+        if current_field:
+            fields[current_field] = "\n".join(current_value).strip()
+        return line.split(":", 1)[0].strip()
+
+    def _save_current_field(
+        self, fields: dict[str, str], current_field: str | None, current_value: list[str]
+    ) -> None:
+        """Save the last field."""
+        if current_field:
+            fields[current_field] = "\n".join(current_value).strip()

src/linters/file_header/violation_builder.py

@@ -0,0 +1,78 @@
+"""
+File: src/linters/file_header/violation_builder.py
+Purpose: Builds violation messages for file header linter
+Exports: ViolationBuilder class
+Depends: Violation type from core
+Implements: Message templates with context-specific details
+Related: linter.py for builder usage, atemporal_detector.py for temporal violations
+
+Overview:
+    Creates formatted violation messages for file header validation failures.
+    Handles missing fields, atemporal language, and other header issues with clear,
+    actionable messages. Provides consistent violation format across all validation types.
+
+Usage:
+    builder = ViolationBuilder("file-header.validation")
+    violation = builder.build_missing_field("Purpose", "test.py", 1)
+
+Notes: Follows standard violation format with rule_id, message, location, severity, suggestion
+"""
+
+from src.core.types import Severity, Violation
+
+
+class ViolationBuilder:
+    """Builds violation messages for file header issues."""
+
+    def __init__(self, rule_id: str):
+        """Initialize with rule ID.
+
+        Args:
+            rule_id: Rule identifier for violations
+        """
+        self.rule_id = rule_id
+
+    def build_missing_field(self, field_name: str, file_path: str, line: int = 1) -> Violation:
+        """Build violation for missing mandatory field.
+
+        Args:
+            field_name: Name of missing field
+            file_path: Path to file
+            line: Line number (default 1 for header)
+
+        Returns:
+            Violation object describing missing field
+        """
+        return Violation(
+            rule_id=self.rule_id,
+            message=f"Missing mandatory field: {field_name}",
+            file_path=file_path,
+            line=line,
+            column=1,
+            severity=Severity.ERROR,
+            suggestion=f"Add '{field_name}:' field to file header",
+        )
+
+    def build_atemporal_violation(
+        self, pattern: str, description: str, file_path: str, line: int
+    ) -> Violation:
+        """Build violation for temporal language.
+
+        Args:
+            pattern: Matched regex pattern
+            description: Description of temporal language
+            file_path: Path to file
+            line: Line number of violation
+
+        Returns:
+            Violation object describing temporal language issue
+        """
+        return Violation(
+            rule_id=self.rule_id,
+            message=f"Temporal language detected: {description}",
+            file_path=file_path,
+            line=line,
+            column=1,
+            severity=Severity.ERROR,
+            suggestion="Use present-tense factual descriptions without temporal references",
+        )

src/linters/file_placement/config_loader.py

@@ -0,0 +1,86 @@
+"""
+Purpose: Configuration file loading for file placement linter
+
+Scope: Handles loading and parsing of JSON/YAML configuration files
+
+Overview: Provides configuration file loading functionality for the file placement linter.
+    Supports both JSON and YAML config formats, handles path resolution relative to project
+    root, and provides safe defaults when config files are missing or invalid. Isolates
+    file I/O concerns from business logic to maintain single responsibility.
+
+Dependencies: pathlib, json, yaml
+
+Exports: ConfigLoader
+
+Interfaces: load_config_file(config_file, project_root) -> dict
+
+Implementation: Uses standard library JSON and PyYAML for parsing, returns empty dict on errors
+"""
+
+import json
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+class ConfigLoader:
+    """Loads configuration files for file placement linter."""
+
+    def __init__(self, project_root: Path):
+        """Initialize config loader.
+
+        Args:
+            project_root: Project root directory
+        """
+        self.project_root = project_root
+
+    def load_config_file(self, config_file: str) -> dict[str, Any]:
+        """Load configuration from file.
+
+        Args:
+            config_file: Path to config file
+
+        Returns:
+            Loaded configuration dict, or empty dict if file doesn't exist
+
+        Raises:
+            ValueError: If config file format is unsupported
+        """
+        config_path = self._resolve_path(config_file)
+        if not config_path.exists():
+            return {}
+        return self._parse_file(config_path)
+
+    def _resolve_path(self, config_file: str) -> Path:
+        """Resolve config file path relative to project root.
+
+        Args:
+            config_file: Config file path (relative or absolute)
+
+        Returns:
+            Resolved absolute path
+        """
+        config_path = Path(config_file)
+        if not config_path.is_absolute():
+            config_path = self.project_root / config_path
+        return config_path
+
+    def _parse_file(self, config_path: Path) -> dict[str, Any]:
+        """Parse config file based on extension.
+
+        Args:
+            config_path: Path to config file
+
+        Returns:
+            Parsed configuration dict
+
+        Raises:
+            ValueError: If file format is unsupported
+        """
+        with config_path.open(encoding="utf-8") as f:
+            if config_path.suffix in [".yaml", ".yml"]:
+                return yaml.safe_load(f) or {}
+            if config_path.suffix == ".json":
+                return json.load(f)
+            raise ValueError(f"Unsupported config format: {config_path.suffix}")

src/linters/file_placement/directory_matcher.py

@@ -0,0 +1,80 @@
+"""
+Purpose: Directory rule matching for file placement linter
+
+Scope: Finds most specific directory rule matching a file path
+
+Overview: Provides directory matching functionality for the file placement linter. Implements
+    most-specific-directory matching logic by comparing path prefixes and calculating directory
+    depth. Handles special case of root directory matching. Returns matched rule and path for
+    further processing. Isolates directory matching logic from rule checking and pattern matching.
+
+Dependencies: typing
+
+Exports: DirectoryMatcher
+
+Interfaces: find_matching_rule(path_str, directories) -> (rule_dict, matched_path)
+
+Implementation: Prefix matching with depth-based precedence, root directory special case
+"""
+
+from typing import Any
+
+
+class DirectoryMatcher:
+    """Finds matching directory rules based on path prefixes."""
+
+    def find_matching_rule(
+        self, path_str: str, directories: dict[str, Any]
+    ) -> tuple[dict[str, Any] | None, str | None]:
+        """Find most specific directory rule matching the path.
+
+        Args:
+            path_str: File path string
+            directories: Directory rules
+
+        Returns:
+            Tuple of (rule_dict, matched_path)
+        """
+        best_match = None
+        best_path = None
+        best_depth = -1
+
+        for dir_path, rules in directories.items():
+            matches, depth = self._check_path_match(dir_path, path_str)
+            if matches and depth > best_depth:
+                best_match = rules
+                best_path = dir_path
+                best_depth = depth
+
+        return best_match, best_path
+
+    def _check_path_match(self, dir_path: str, path_str: str) -> tuple[bool, int]:
+        """Check if path matches directory rule.
+
+        Args:
+            dir_path: Directory path pattern
+            path_str: File path string
+
+        Returns:
+            Tuple of (matches, depth) where depth is directory nesting level
+        """
+        if dir_path == "/":
+            return self._check_root_match(dir_path, path_str)
+        if path_str.startswith(dir_path):
+            depth = len(dir_path.split("/"))
+            return True, depth
+        return False, -1
+
+    def _check_root_match(self, dir_path: str, path_str: str) -> tuple[bool, int]:
+        """Check if path matches root directory rule.
+
+        Args:
+            dir_path: Directory path (should be "/")
+            path_str: File path string
+
+        Returns:
+            Tuple of (matches, depth)
+        """
+        if dir_path == "/" and "/" not in path_str:
+            return True, 0
+        return False, -1