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

src/linters/file_header/atemporal_detector.py

@@ -0,0 +1,87 @@
+"""
+File: src/linters/file_header/atemporal_detector.py
+Purpose: Detects temporal language patterns in file headers
+Exports: AtemporalDetector class
+Depends: re module for regex matching
+Implements: Regex-based pattern matching with configurable patterns
+Related: linter.py for detector usage, violation_builder.py for violation creation
+
+Overview:
+    Implements pattern-based detection of temporal language that violates atemporal
+    documentation requirements. Detects dates, temporal qualifiers, state change language,
+    and future references using regex patterns. Provides violation details for each pattern match.
+
+Usage:
+    detector = AtemporalDetector()
+    violations = detector.detect_violations(header_text)
+
+Notes: Four pattern categories - dates, temporal qualifiers, state changes, future references
+"""
+
+import re
+
+
+class AtemporalDetector:
+    """Detects temporal language patterns in text."""
+
+    # Date patterns
+    DATE_PATTERNS = [
+        (r"\d{4}-\d{2}-\d{2}", "ISO date format (YYYY-MM-DD)"),
+        (
+            r"(?:January|February|March|April|May|June|July|August|September|October|November|December)\s+\d{4}",
+            "Month Year format",
+        ),
+        (r"(?:Created|Updated|Modified):\s*\d{4}", "Date metadata"),
+    ]
+
+    # Temporal qualifiers
+    TEMPORAL_QUALIFIERS = [
+        (r"\bcurrently\b", 'temporal qualifier "currently"'),
+        (r"\bnow\b", 'temporal qualifier "now"'),
+        (r"\brecently\b", 'temporal qualifier "recently"'),
+        (r"\bsoon\b", 'temporal qualifier "soon"'),
+        (r"\bfor now\b", 'temporal qualifier "for now"'),
+    ]
+
+    # State change language
+    STATE_CHANGE = [
+        (r"\breplaces?\b", 'state change "replaces"'),
+        (r"\bmigrated from\b", 'state change "migrated from"'),
+        (r"\bformerly\b", 'state change "formerly"'),
+        (r"\bold implementation\b", 'state change "old"'),
+        (r"\bnew implementation\b", 'state change "new"'),
+    ]
+
+    # Future references
+    FUTURE_REFS = [
+        (r"\bwill be\b", 'future reference "will be"'),
+        (r"\bplanned\b", 'future reference "planned"'),
+        (r"\bto be added\b", 'future reference "to be added"'),
+        (r"\bcoming soon\b", 'future reference "coming soon"'),
+    ]
+
+    def detect_violations(  # thailint: ignore[nesting]
+        self, text: str
+    ) -> list[tuple[str, str, int]]:
+        """Detect all temporal language violations in text.
+
+        Args:
+            text: Text to check for temporal language
+
+        Returns:
+            List of (pattern, description, line_number) tuples for each violation
+        """
+        violations = []
+
+        # Check all pattern categories
+        all_patterns = (
+            self.DATE_PATTERNS + self.TEMPORAL_QUALIFIERS + self.STATE_CHANGE + self.FUTURE_REFS
+        )
+
+        lines = text.split("\n")
+        for line_num, line in enumerate(lines, start=1):
+            for pattern, description in all_patterns:
+                if re.search(pattern, line, re.IGNORECASE):
+                    violations.append((pattern, description, line_num))
+
+        return violations

src/linters/file_header/config.py

@@ -0,0 +1,66 @@
+"""
+File: src/linters/file_header/config.py
+Purpose: Configuration model for file header linter
+Exports: FileHeaderConfig dataclass
+Depends: dataclasses, pathlib
+Implements: Configuration with validation and defaults
+Related: linter.py for configuration usage
+
+Overview:
+    Defines configuration structure for file header linter including required fields
+    per language, ignore patterns, and validation options. Provides defaults matching
+    ai-doc-standard.md requirements and supports loading from .thailint.yaml configuration.
+
+Usage:
+    config = FileHeaderConfig()
+    config = FileHeaderConfig.from_dict(config_dict, "python")
+
+Notes: Dataclass with validation and language-specific defaults
+"""
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class FileHeaderConfig:
+    """Configuration for file header linting."""
+
+    # Required fields by language
+    required_fields_python: list[str] = field(
+        default_factory=lambda: [
+            "Purpose",
+            "Scope",
+            "Overview",
+            "Dependencies",
+            "Exports",
+            "Interfaces",
+            "Implementation",
+        ]
+    )
+
+    # Enforce atemporal language checking
+    enforce_atemporal: bool = True
+
+    # Patterns to ignore (file paths)
+    ignore: list[str] = field(
+        default_factory=lambda: ["test/**", "**/migrations/**", "**/__init__.py"]
+    )
+
+    @classmethod
+    def from_dict(cls, config_dict: dict, language: str) -> "FileHeaderConfig":
+        """Create config from dictionary.
+
+        Args:
+            config_dict: Dictionary of configuration values
+            language: Programming language for language-specific config
+
+        Returns:
+            FileHeaderConfig instance with values from dictionary
+        """
+        return cls(
+            required_fields_python=config_dict.get("required_fields", {}).get(
+                "python", cls().required_fields_python
+            ),
+            enforce_atemporal=config_dict.get("enforce_atemporal", True),
+            ignore=config_dict.get("ignore", cls().ignore),
+        )

src/linters/file_header/field_validator.py

@@ -0,0 +1,69 @@
+"""
+File: src/linters/file_header/field_validator.py
+Purpose: Validates mandatory fields in file headers
+Exports: FieldValidator class
+Depends: FileHeaderConfig for field requirements
+Implements: Configuration-driven validation with field presence checking
+Related: linter.py for validator usage, config.py for configuration
+
+Overview:
+    Validates presence and quality of mandatory header fields. Checks that all
+    required fields are present, non-empty, and meet minimum content requirements.
+    Supports language-specific required fields and provides detailed violation messages.
+
+Usage:
+    validator = FieldValidator(config)
+    violations = validator.validate_fields(fields, "python")
+
+Notes: Language-specific field requirements defined in config
+"""
+
+from .config import FileHeaderConfig
+
+
+class FieldValidator:
+    """Validates mandatory fields in headers."""
+
+    def __init__(self, config: FileHeaderConfig):
+        """Initialize validator with configuration.
+
+        Args:
+            config: File header configuration with required fields
+        """
+        self.config = config
+
+    def validate_fields(  # thailint: ignore[nesting]
+        self, fields: dict[str, str], language: str
+    ) -> list[tuple[str, str]]:
+        """Validate all required fields are present.
+
+        Args:
+            fields: Dictionary of parsed header fields
+            language: File language (python, typescript, etc.)
+
+        Returns:
+            List of (field_name, error_message) tuples for missing/invalid fields
+        """
+        violations = []
+        required_fields = self._get_required_fields(language)
+
+        for field_name in required_fields:
+            if field_name not in fields:
+                violations.append((field_name, f"Missing mandatory field: {field_name}"))
+            elif not fields[field_name] or len(fields[field_name].strip()) == 0:
+                violations.append((field_name, f"Empty mandatory field: {field_name}"))
+
+        return violations
+
+    def _get_required_fields(self, language: str) -> list[str]:
+        """Get required fields for language.
+
+        Args:
+            language: Programming language
+
+        Returns:
+            List of required field names for the language
+        """
+        if language == "python":
+            return self.config.required_fields_python
+        return []  # Other languages in PR5

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()