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

src/linters/file_header/linter.py

@@ -0,0 +1,309 @@
+"""
+Purpose: Main file header linter rule implementation
+
+Scope: File header validation for Python, TypeScript, JavaScript, Bash, Markdown, and CSS files
+
+Overview: Orchestrates file header validation for multiple languages using focused helper classes.
+    Coordinates header extraction, field validation, atemporal language detection, and
+    violation building. Supports configuration from .thailint.yaml and ignore directives
+    including file-level and line-level ignore markers. Validates headers against mandatory
+    field requirements and atemporal language standards. Handles language-specific parsing
+    and special Markdown prose field extraction for atemporal checking.
+
+Dependencies: BaseLintRule and BaseLintContext from core, language-specific parsers,
+    FieldValidator, AtemporalDetector, ViolationBuilder
+
+Exports: FileHeaderRule class implementing BaseLintRule interface
+
+Interfaces: check(context) -> list[Violation] for rule validation, standard rule properties
+    (rule_id, rule_name, description)
+
+Implementation: Composition pattern with helper classes for parsing, validation,
+    and violation building
+
+Suppressions:
+    - type:ignore[type-var]: Protocol pattern with generic type matching
+    - srp: Rule class coordinates parsing, validation, and violation building for multiple
+        languages. Methods support single responsibility of file header validation.
+"""
+
+from contextlib import suppress
+from pathlib import Path
+from typing import Protocol
+
+from src.core.base import BaseLintContext, BaseLintRule
+from src.core.constants import HEADER_SCAN_LINES, Language
+from src.core.linter_utils import load_linter_config
+from src.core.types import Violation
+from src.linter_config.directive_markers import check_general_ignore, has_ignore_directive_marker
+from src.linter_config.ignore import _check_specific_rule_ignore, get_ignore_parser
+
+from .atemporal_detector import AtemporalDetector
+from .bash_parser import BashHeaderParser
+from .config import FileHeaderConfig
+from .css_parser import CssHeaderParser
+from .field_validator import FieldValidator
+from .markdown_parser import MarkdownHeaderParser
+from .python_parser import PythonHeaderParser
+from .typescript_parser import TypeScriptHeaderParser
+from .violation_builder import ViolationBuilder
+
+
+class HeaderParser(Protocol):
+    """Protocol for header parsers."""
+
+    def extract_header(self, code: str) -> str | None:
+        """Extract header from source code."""
+
+    def parse_fields(self, header: str) -> dict[str, str]:
+        """Parse fields from header."""
+
+
+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).
+    """
+
+    # Parser instances for each language
+    _parsers: dict[str, HeaderParser] = {
+        "python": PythonHeaderParser(),
+        "typescript": TypeScriptHeaderParser(),
+        "javascript": TypeScriptHeaderParser(),
+        "bash": BashHeaderParser(),
+        "markdown": MarkdownHeaderParser(),
+        "css": CssHeaderParser(),
+    }
+
+    def __init__(self) -> None:
+        """Initialize the file header rule."""
+        self._violation_builder = ViolationBuilder(self.rule_id)
+        self._ignore_parser = get_ignore_parser()
+
+    @property
+    def rule_id(self) -> str:
+        """Unique identifier for this rule."""
+        return "file-header.validation"
+
+    @property
+    def rule_name(self) -> str:
+        """Human-readable name for this rule."""
+        return "File Header Validation"
+
+    @property
+    def description(self) -> str:
+        """Description of what this rule checks."""
+        return "Validates file headers for mandatory fields and atemporal language"
+
+    def check(self, context: BaseLintContext) -> list[Violation]:
+        """Check file header for violations."""
+        if self._has_file_ignore(context):
+            return []
+
+        config = self._load_config(context)
+
+        if self._should_ignore_file(context, config):
+            return []
+
+        return self._check_language_header(context, config)
+
+    def _check_language_header(
+        self, context: BaseLintContext, config: FileHeaderConfig
+    ) -> list[Violation]:
+        """Dispatch to language-specific header checking."""
+        parser = self._parsers.get(context.language)
+        if not parser:
+            return []
+
+        # Markdown has special atemporal handling
+        if context.language == Language.MARKDOWN:
+            return self._check_markdown_header(parser, context, config)
+
+        return self._check_header_with_parser(parser, context, config)
+
+    def _check_header_with_parser(
+        self, parser: HeaderParser, context: BaseLintContext, config: FileHeaderConfig
+    ) -> list[Violation]:
+        """Check header using the given parser."""
+        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 _check_markdown_header(
+        self, parser: HeaderParser, context: BaseLintContext, config: FileHeaderConfig
+    ) -> list[Violation]:
+        """Check Markdown file header with special prose-only atemporal checking."""
+        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)
+
+        # For Markdown, only check atemporal language in prose fields
+        prose_content = self._extract_markdown_prose_fields(fields)
+        violations.extend(self._check_atemporal_violations(prose_content, context, config))
+
+        return self._filter_ignored_violations(violations, context)
+
+    def _has_file_ignore(self, context: BaseLintContext) -> bool:
+        """Check if file has file-level ignore 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:
+        """Check standard ignore parser for file-level ignores."""
+        first_lines = file_content.splitlines()[:HEADER_SCAN_LINES]
+        return any(self._line_has_matching_ignore(line) for line in first_lines)
+
+    def _line_has_matching_ignore(self, line: str) -> bool:
+        """Check if line has matching ignore directive for this rule."""
+        if not has_ignore_directive_marker(line):
+            return False
+        return _check_specific_rule_ignore(line, self.rule_id) or check_general_ignore(line)
+
+    def _has_custom_ignore_syntax(self, file_content: str) -> bool:
+        """Check custom file-level ignore syntax."""
+        first_lines = file_content.splitlines()[:HEADER_SCAN_LINES]
+        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."""
+        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]
+
+        return FileHeaderConfig()
+
+    def _should_ignore_file(self, context: BaseLintContext, config: FileHeaderConfig) -> bool:
+        """Check if file matches ignore patterns."""
+        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 _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."""
+        file_content = context.file_content or ""
+        lines = file_content.splitlines()
+
+        non_ignored = (
+            v
+            for v in violations
+            if not self._ignore_parser.should_ignore_violation(v, file_content)
+            and not self._has_line_level_ignore(lines, v)
+        )
+        return list(non_ignored)
+
+    def _has_line_level_ignore(self, lines: list[str], violation: Violation) -> bool:
+        """Check for thailint-ignore-line directive."""
+        if violation.line <= 0 or violation.line > len(lines):
+            return False
+
+        line_content = lines[violation.line - 1]
+        return "# thailint-ignore-line:" in line_content.lower()
+
+    def _extract_markdown_prose_fields(self, fields: dict[str, str]) -> str:
+        """Extract prose fields from Markdown frontmatter for atemporal checking."""
+        prose_fields = ["purpose", "scope", "overview"]
+        prose_parts = []
+
+        for field_name in prose_fields:
+            with suppress(KeyError):
+                prose_parts.append(f"{field_name}: {fields[field_name]}")
+
+        return "\n".join(prose_parts)

src/linters/file_header/markdown_parser.py

@@ -0,0 +1,130 @@
+"""
+Purpose: Markdown YAML frontmatter extraction and parsing
+
+Scope: Markdown file header parsing from YAML frontmatter
+
+Overview: Extracts YAML frontmatter from Markdown files. Frontmatter must be at the
+    start of the file, enclosed in --- markers. Parses YAML content to extract
+    field values using PyYAML when available, falling back to regex parsing if not.
+    Handles both simple key-value pairs and complex YAML structures including lists.
+    Flattens nested structures into string representations for field validation.
+
+Dependencies: re module for frontmatter pattern matching, yaml module (optional) for parsing, logging module
+
+Exports: MarkdownHeaderParser class
+
+Interfaces: extract_header(code) -> str | None for frontmatter extraction,
+    parse_fields(header) -> dict[str, str] for field parsing
+
+Implementation: YAML frontmatter extraction with PyYAML parsing and regex fallback for robustness
+
+Suppressions:
+    - BLE001: Broad exception catch for YAML parsing fallback (any exception triggers regex fallback)
+    - srp: Class coordinates YAML extraction, parsing, and field validation for Markdown.
+        Method count exceeds limit due to complexity refactoring.
+    - nesting,dry: _parse_simple_yaml uses nested loops for YAML structure traversal.
+"""
+
+import logging
+import re
+
+logger = logging.getLogger(__name__)
+
+
+class MarkdownHeaderParser:  # thailint: ignore[srp]
+    """Extracts and parses Markdown file headers from YAML frontmatter.
+
+    Method count (10) exceeds SRP guideline (8) because proper A-grade complexity
+    refactoring requires extracting small focused helper methods. Class maintains
+    single responsibility of YAML frontmatter parsing - all methods support this
+    core purpose through either PyYAML or simple regex parsing fallback.
+    """
+
+    # Pattern to match YAML frontmatter at start of file
+    FRONTMATTER_PATTERN = re.compile(r"^---\s*\n(.*?)\n---", re.DOTALL)
+
+    def extract_header(self, code: str) -> str | None:
+        """Extract YAML frontmatter from Markdown file."""
+        if not code or not code.strip():
+            return None
+
+        match = self.FRONTMATTER_PATTERN.match(code)
+        return match.group(1).strip() if match else None
+
+    def parse_fields(self, header: str) -> dict[str, str]:
+        """Parse YAML frontmatter into field dictionary."""
+        yaml_result = self._try_yaml_parse(header)
+        if yaml_result is not None:
+            return yaml_result
+
+        return self._parse_simple_yaml(header)
+
+    def _try_yaml_parse(self, header: str) -> dict[str, str] | None:
+        """Try to parse with PyYAML, returning None if unavailable or failed."""
+        try:
+            import yaml
+
+            data = yaml.safe_load(header)
+            if isinstance(data, dict):
+                return self._flatten_yaml_dict(data)
+        except ImportError:
+            logger.debug("PyYAML not available, using simple parser")
+        except Exception:  # noqa: BLE001
+            logger.debug("YAML parsing failed, falling back to simple parser")
+        return None
+
+    def _flatten_yaml_dict(self, data: dict) -> dict[str, str]:
+        """Convert YAML dict to string values."""
+        result: dict[str, str] = {}
+        for key, value in data.items():
+            result[str(key)] = self._convert_value(value)
+        return result
+
+    def _convert_value(self, value: object) -> str:
+        """Convert a single YAML value to string."""
+        if isinstance(value, list):
+            return ", ".join(str(v) for v in value)
+        if value is not None:
+            return str(value)
+        return ""
+
+    def _parse_simple_yaml(  # thailint: ignore[nesting,dry]
+        self, header: str
+    ) -> dict[str, str]:
+        """Simple regex-based YAML parsing fallback."""
+        fields: dict[str, str] = {}
+        current_field: str | None = None
+        current_value: list[str] = []
+
+        for line in header.split("\n"):
+            if self._is_field_start(line):
+                self._save_field(fields, current_field, current_value)
+                current_field, current_value = self._start_field(line)
+            elif current_field and line.strip():
+                current_value.append(self._process_continuation(line))
+
+        self._save_field(fields, current_field, current_value)
+        return fields
+
+    def _is_field_start(self, line: str) -> bool:
+        """Check if line starts a new field (not indented, has colon)."""
+        return not line.startswith(" ") and ":" in line
+
+    def _start_field(self, line: str) -> tuple[str, list[str]]:
+        """Parse field start and return field name and initial value."""
+        parts = line.split(":", 1)
+        field_name = parts[0].strip()
+        value = parts[1].strip() if len(parts) > 1 else ""
+        return field_name, [value] if value else []
+
+    def _process_continuation(self, line: str) -> str:
+        """Process a continuation line (list item or multiline value)."""
+        stripped = line.strip()
+        return stripped[2:] if stripped.startswith("- ") else stripped
+
+    def _save_field(
+        self, fields: dict[str, str], field_name: str | None, values: list[str]
+    ) -> None:
+        """Save field to dictionary if field name exists."""
+        if field_name:
+            fields[field_name] = "\n".join(values).strip()

src/linters/file_header/python_parser.py

@@ -0,0 +1,42 @@
+"""
+Purpose: Python docstring extraction and parsing for file headers
+
+Scope: Python file header parsing from module-level docstrings
+
+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. Uses ast.get_docstring() for reliable extraction
+    and gracefully handles syntax errors in source code.
+
+Dependencies: Python ast module for AST parsing, base_parser.BaseHeaderParser for field parsing
+
+Exports: PythonHeaderParser class
+
+Interfaces: extract_header(code) -> str | None for docstring extraction, parse_fields(header) inherited from base
+
+Implementation: AST-based docstring extraction with syntax error handling
+"""
+
+import ast
+
+from src.linters.file_header.base_parser import BaseHeaderParser
+
+
+class PythonHeaderParser(BaseHeaderParser):
+    """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

src/linters/file_header/typescript_parser.py

@@ -0,0 +1,73 @@
+"""
+Purpose: TypeScript/JavaScript JSDoc comment extraction and parsing
+
+Scope: TypeScript and JavaScript file header parsing from JSDoc comments
+
+Overview: Extracts JSDoc-style comments (/** ... */) from TypeScript and JavaScript files.
+    Parses structured header fields from JSDoc content and handles both single-line
+    and multi-line field values. Distinguishes JSDoc comments from regular block
+    comments (/* ... */) by requiring the double asterisk syntax. Cleans formatting
+    characters including leading asterisks from content lines.
+
+Dependencies: re module for regex-based JSDoc pattern matching, base_parser.BaseHeaderParser for field parsing
+
+Exports: TypeScriptHeaderParser class
+
+Interfaces: extract_header(code) -> str | None for JSDoc extraction, parse_fields(header) inherited from base
+
+Implementation: Regex-based JSDoc extraction with content cleaning and formatting removal
+"""
+
+import re
+
+from src.linters.file_header.base_parser import BaseHeaderParser
+
+
+class TypeScriptHeaderParser(BaseHeaderParser):
+    """Extracts and parses TypeScript/JavaScript file headers from JSDoc comments."""
+
+    # Pattern to match JSDoc comment at start of file (allowing whitespace before)
+    JSDOC_PATTERN = re.compile(r"^\s*/\*\*\s*(.*?)\s*\*/", re.DOTALL)
+
+    def extract_header(self, code: str) -> str | None:
+        """Extract JSDoc comment from TypeScript/JavaScript code.
+
+        Args:
+            code: TypeScript/JavaScript source code
+
+        Returns:
+            JSDoc content or None if not found
+        """
+        if not code or not code.strip():
+            return None
+
+        match = self.JSDOC_PATTERN.match(code)
+        if not match:
+            return None
+
+        # Extract the content inside the JSDoc
+        jsdoc_content = match.group(1)
+
+        # Clean up the JSDoc content - remove leading * from each line
+        return self._clean_jsdoc_content(jsdoc_content)
+
+    def _clean_jsdoc_content(self, content: str) -> str:
+        """Remove JSDoc formatting (leading asterisks) from content.
+
+        Args:
+            content: Raw JSDoc content
+
+        Returns:
+            Cleaned content without leading asterisks
+        """
+        lines = content.split("\n")
+        cleaned_lines = []
+
+        for line in lines:
+            # Remove leading whitespace and asterisk
+            stripped = line.strip()
+            if stripped.startswith("*"):
+                stripped = stripped[1:].strip()
+            cleaned_lines.append(stripped)
+
+        return "\n".join(cleaned_lines)

src/linters/file_header/violation_builder.py

@@ -0,0 +1,79 @@
+"""
+Purpose: Builds violation messages for file header linter
+
+Scope: Violation message creation for file header validation failures
+
+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
+    including rule_id, message, location, severity, and helpful suggestions. Supports
+    multiple violation types with appropriate error messages and remediation guidance.
+
+Dependencies: Violation and Severity types from core.types module
+
+Exports: ViolationBuilder class
+
+Interfaces: build_missing_field(field_name, file_path, line) -> Violation,
+    build_atemporal_violation(pattern, description, file_path, line) -> Violation
+
+Implementation: Builder pattern with message templates for different violation types
+"""
+
+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

@@ -23,6 +23,8 @@ from typing import Any
 
 import yaml
 
+from src.core.constants import CONFIG_EXTENSIONS
+
 
 class ConfigLoader:
     """Loads configuration files for file placement linter."""
@@ -79,7 +81,7 @@ class ConfigLoader:
             ValueError: If file format is unsupported
         """
         with config_path.open(encoding="utf-8") as f:
-            if config_path.suffix in [".yaml", ".yml"]:
+            if config_path.suffix in CONFIG_EXTENSIONS:
                 return yaml.safe_load(f) or {}
             if config_path.suffix == ".json":
                 return json.load(f)

src/linters/file_placement/directory_matcher.py

@@ -23,6 +23,10 @@ from typing import Any
 class DirectoryMatcher:
     """Finds matching directory rules based on path prefixes."""
 
+    def __init__(self) -> None:
+        """Initialize the directory matcher."""
+        pass  # Stateless matcher for directory rules
+
     def find_matching_rule(
         self, path_str: str, directories: dict[str, Any]
     ) -> tuple[dict[str, Any] | None, str | None]: