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

src/linters/file_header/config.py

@@ -1,21 +1,22 @@
 """
-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
+Scope: File header linter configuration for all supported languages
+
+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.
+    FILE_HEADER_STANDARDS.md requirements and supports loading from .thailint.yaml configuration.
+    Supports Python, TypeScript/JavaScript, Bash, Markdown, and CSS file types with
+    language-specific required field sets. Includes atemporal language enforcement
+    configuration and file ignore patterns.
+
+Dependencies: dataclasses module for configuration structure
+
+Exports: FileHeaderConfig dataclass
 
-Usage:
-    config = FileHeaderConfig()
-    config = FileHeaderConfig.from_dict(config_dict, "python")
+Interfaces: from_dict(config_dict, language) -> FileHeaderConfig for configuration loading
 
-Notes: Dataclass with validation and language-specific defaults
+Implementation: Dataclass with language-specific field lists and factory method for config loading
 """
 
 from dataclasses import dataclass, field
@@ -25,7 +26,7 @@ from dataclasses import dataclass, field
 class FileHeaderConfig:
     """Configuration for file header linting."""
 
-    # Required fields by language
+    # Required fields by language - Python
     required_fields_python: list[str] = field(
         default_factory=lambda: [
             "Purpose",
@@ -38,6 +39,56 @@ class FileHeaderConfig:
         ]
     )
 
+    # Required fields by language - TypeScript/JavaScript
+    required_fields_typescript: list[str] = field(
+        default_factory=lambda: [
+            "Purpose",
+            "Scope",
+            "Overview",
+            "Dependencies",
+            "Exports",
+            "Props/Interfaces",
+            "State/Behavior",
+        ]
+    )
+
+    # Required fields by language - Bash
+    required_fields_bash: list[str] = field(
+        default_factory=lambda: [
+            "Purpose",
+            "Scope",
+            "Overview",
+            "Dependencies",
+            "Exports",
+            "Usage",
+            "Environment",
+        ]
+    )
+
+    # Required fields by language - Markdown (lowercase for YAML frontmatter)
+    required_fields_markdown: list[str] = field(
+        default_factory=lambda: [
+            "purpose",
+            "scope",
+            "overview",
+            "audience",
+            "status",
+        ]
+    )
+
+    # Required fields by language - CSS
+    required_fields_css: list[str] = field(
+        default_factory=lambda: [
+            "Purpose",
+            "Scope",
+            "Overview",
+            "Dependencies",
+            "Exports",
+            "Interfaces",
+            "Environment",
+        ]
+    )
+
     # Enforce atemporal language checking
     enforce_atemporal: bool = True
 
@@ -57,10 +108,19 @@ class FileHeaderConfig:
         Returns:
             FileHeaderConfig instance with values from dictionary
         """
+        defaults = cls()
+        required_fields = config_dict.get("required_fields", {})
+
         return cls(
-            required_fields_python=config_dict.get("required_fields", {}).get(
-                "python", cls().required_fields_python
+            required_fields_python=required_fields.get("python", defaults.required_fields_python),
+            required_fields_typescript=required_fields.get(
+                "typescript", defaults.required_fields_typescript
+            ),
+            required_fields_bash=required_fields.get("bash", defaults.required_fields_bash),
+            required_fields_markdown=required_fields.get(
+                "markdown", defaults.required_fields_markdown
             ),
+            required_fields_css=required_fields.get("css", defaults.required_fields_css),
             enforce_atemporal=config_dict.get("enforce_atemporal", True),
-            ignore=config_dict.get("ignore", cls().ignore),
+            ignore=config_dict.get("ignore", defaults.ignore),
         )

src/linters/file_header/css_parser.py

@@ -0,0 +1,70 @@
+"""
+Purpose: CSS block comment header extraction and parsing
+
+Scope: CSS and SCSS file header parsing
+
+Overview: Extracts JSDoc-style block comments (/** ... */) from CSS and SCSS files.
+    Handles @charset declarations by allowing them before the header comment.
+    Parses structured header fields from comment content and cleans formatting
+    characters. Requires JSDoc-style comment (/**) not regular block comment (/*).
+    Processes multi-line comments and removes leading asterisks from content.
+
+Dependencies: re module for regex pattern matching, base_parser.BaseHeaderParser for field parsing
+
+Exports: CssHeaderParser class
+
+Interfaces: extract_header(code) -> str | None for JSDoc comment extraction, parse_fields(header) inherited from base
+
+Implementation: Regex-based JSDoc comment extraction with content cleaning and formatting removal
+"""
+
+import re
+
+from src.linters.file_header.base_parser import BaseHeaderParser
+
+
+class CssHeaderParser(BaseHeaderParser):
+    """Extracts and parses CSS file headers from block comments."""
+
+    # Pattern to match JSDoc-style comment, allowing @charset before
+    JSDOC_PATTERN = re.compile(r'^(?:@charset\s+"[^"]+"\s*;\s*)?\s*/\*\*\s*(.*?)\s*\*/', re.DOTALL)
+
+    def extract_header(self, code: str) -> str | None:
+        """Extract JSDoc-style comment from CSS code.
+
+        Args:
+            code: CSS/SCSS source code
+
+        Returns:
+            Comment 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 and clean the content
+        comment_content = match.group(1)
+        return self._clean_comment_content(comment_content)
+
+    def _clean_comment_content(self, content: str) -> str:
+        """Remove comment formatting (leading asterisks) from content.
+
+        Args:
+            content: Raw comment content
+
+        Returns:
+            Cleaned content without leading asterisks
+        """
+        lines = content.split("\n")
+        cleaned_lines = []
+
+        for line in lines:
+            stripped = line.strip()
+            if stripped.startswith("*"):
+                stripped = stripped[1:].strip()
+            cleaned_lines.append(stripped)
+
+        return "\n".join(cleaned_lines)

src/linters/file_header/field_validator.py

@@ -1,21 +1,21 @@
 """
-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
+Scope: File header field validation for all supported languages
+
+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.
+    Supports language-specific required fields and provides detailed violation messages
+    for missing or empty fields. Uses configuration-driven validation to support
+    different field requirements per language type.
+
+Dependencies: FileHeaderConfig for language-specific field requirements
 
-Usage:
-    validator = FieldValidator(config)
-    violations = validator.validate_fields(fields, "python")
+Exports: FieldValidator class
+
+Interfaces: validate_fields(fields, language) -> list[tuple[str, str]] returns field violations
 
-Notes: Language-specific field requirements defined in config
+Implementation: Configuration-driven validation with field presence and emptiness checking
 """
 
 from .config import FileHeaderConfig
@@ -32,9 +32,7 @@ class FieldValidator:
         """
         self.config = config
 
-    def validate_fields(  # thailint: ignore[nesting]
-        self, fields: dict[str, str], language: str
-    ) -> list[tuple[str, str]]:
+    def validate_fields(self, fields: dict[str, str], language: str) -> list[tuple[str, str]]:
         """Validate all required fields are present.
 
         Args:
@@ -48,22 +46,30 @@ class FieldValidator:
         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}"))
+            error = self._check_field(fields, field_name)
+            if error:
+                violations.append(error)
 
         return violations
 
-    def _get_required_fields(self, language: str) -> list[str]:
-        """Get required fields for language.
+    def _check_field(self, fields: dict[str, str], field_name: str) -> tuple[str, str] | None:
+        """Check a single field for presence and content."""
+        if field_name not in fields:
+            return (field_name, f"Missing mandatory field: {field_name}")
 
-        Args:
-            language: Programming language
+        if not fields[field_name] or not fields[field_name].strip():
+            return (field_name, f"Empty mandatory field: {field_name}")
 
-        Returns:
-            List of required field names for the language
-        """
-        if language == "python":
-            return self.config.required_fields_python
-        return []  # Other languages in PR5
+        return None
+
+    def _get_required_fields(self, language: str) -> list[str]:
+        """Get required fields for language using dictionary lookup."""
+        language_fields = {
+            "python": self.config.required_fields_python,
+            "typescript": self.config.required_fields_typescript,
+            "javascript": self.config.required_fields_typescript,
+            "bash": self.config.required_fields_bash,
+            "markdown": self.config.required_fields_markdown,
+            "css": self.config.required_fields_css,
+        }
+        return language_fields.get(language, [])

src/linters/file_header/linter.py

@@ -1,25 +1,29 @@
 """
-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
+
+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
 """
 
 from pathlib import Path
+from typing import Protocol
 
 from src.core.base import BaseLintContext, BaseLintRule
 from src.core.linter_utils import load_linter_config
@@ -27,12 +31,26 @@ from src.core.types import Violation
 from src.linter_config.ignore import IgnoreDirectiveParser
 
 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.
 
@@ -42,6 +60,16 @@ class FileHeaderRule(BaseLintRule):  # thailint: ignore[srp]
     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)
@@ -49,67 +77,80 @@ class FileHeaderRule(BaseLintRule):  # thailint: ignore[srp]
 
     @property
     def rule_id(self) -> str:
-        """Unique identifier for this rule.
-
-        Returns:
-            Rule identifier string
-        """
+        """Unique identifier for this rule."""
         return "file-header.validation"
 
     @property
     def rule_name(self) -> str:
-        """Human-readable name for this rule.
-
-        Returns:
-            Rule name string
-        """
+        """Human-readable name for this rule."""
         return "File Header Validation"
 
     @property
     def description(self) -> str:
-        """Description of what this rule checks.
-
-        Returns:
-            Rule description string
-        """
+        """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.
-
-        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
+        """Check file header for violations."""
         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)
+        return self._check_language_header(context, config)
 
-    def _has_file_ignore(self, context: BaseLintContext) -> bool:
-        """Check if file has file-level ignore directive.
+    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 == "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)
 
-        Args:
-            context: Lint 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)
 
-        Returns:
-            True if file has ignore-file directive
-        """
+    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):
@@ -119,7 +160,6 @@ class FileHeaderRule(BaseLintRule):  # thailint: ignore[srp]
 
     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
@@ -140,32 +180,15 @@ class FileHeaderRule(BaseLintRule):  # thailint: ignore[srp]
         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
+        """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]
 
-        # 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
-        """
+        """Check if file matches ignore patterns."""
         if not context.file_path:
             return False
 
@@ -200,30 +223,6 @@ class FileHeaderRule(BaseLintRule):  # thailint: ignore[srp]
             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 [
@@ -270,25 +269,15 @@ class FileHeaderRule(BaseLintRule):  # thailint: ignore[srp]
     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
-        """
+        """Filter out violations that should be ignored."""
         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
 
@@ -297,17 +286,20 @@ class FileHeaderRule(BaseLintRule):  # thailint: ignore[srp]
         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
-        """
+        """Check for thailint-ignore-line directive."""
         if violation.line <= 0 or violation.line > len(lines):
             return False
 
-        line_content = lines[violation.line - 1]  # Convert to 0-indexed
+        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:
+            if field_name in fields:
+                prose_parts.append(f"{field_name}: {fields[field_name]}")
+
+        return "\n".join(prose_parts)