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

src/linters/file_header/base_parser.py

@@ -0,0 +1,93 @@
+"""
+Purpose: Base class for file header parsers with common field parsing logic
+
+Scope: File header parsing infrastructure for all language-specific parsers
+
+Overview: Provides common field parsing functionality shared across all language-specific
+    header parsers. Implements the parse_fields method and helper methods for
+    detecting field lines and saving fields. Uses template method pattern where subclasses
+    implement extract_header for language-specific header extraction while this base class
+    handles field parsing logic. Supports multi-line field values and field continuation.
+
+Dependencies: re module for field pattern matching, abc module for abstract base class
+
+Exports: BaseHeaderParser abstract base class
+
+Interfaces: extract_header(code) abstract method, parse_fields(header) -> dict[str, str] for field extraction
+
+Implementation: Template method pattern with shared field parsing and language-specific extraction
+
+Suppressions:
+    - nesting: parse_fields uses nested loops for multi-line field processing. Extracting
+        would fragment the field-building logic without improving clarity.
+"""
+
+import re
+from abc import ABC, abstractmethod
+
+
+class BaseHeaderParser(ABC):
+    """Base class for file header parsers with common field parsing logic."""
+
+    # Pattern to match field names (word characters and /)
+    FIELD_NAME_PATTERN = re.compile(r"^[\w/]+$")
+
+    @abstractmethod
+    def extract_header(self, code: str) -> str | None:
+        """Extract header from source code.
+
+        Args:
+            code: Source code
+
+        Returns:
+            Header content or None if not found
+        """
+
+    def parse_fields(self, header: str) -> dict[str, str]:  # thailint: ignore[nesting]
+        """Parse structured fields from header text.
+
+        Args:
+            header: Header 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_field_line(line):
+                self._save_field(fields, current_field, current_value)
+                current_field, current_value = self._start_new_field(line)
+            elif current_field:
+                current_value.append(line.strip())
+
+        self._save_field(fields, current_field, current_value)
+        return fields
+
+    def _is_field_line(self, line: str) -> bool:
+        """Check if line starts a new field."""
+        if ":" not in line:
+            return False
+
+        colon_pos = line.find(":")
+        if colon_pos <= 0:
+            return False
+
+        field_name = line[:colon_pos].strip()
+        return bool(self.FIELD_NAME_PATTERN.match(field_name))
+
+    def _start_new_field(self, line: str) -> tuple[str, list[str]]:
+        """Parse a field line and start tracking its value."""
+        parts = line.split(":", 1)
+        field_name = parts[0].strip()
+        initial_value = parts[1].strip() if len(parts) > 1 else ""
+        return field_name, [initial_value] if initial_value else []
+
+    def _save_field(
+        self, fields: dict[str, str], field_name: str | None, value_lines: list[str]
+    ) -> None:
+        """Save accumulated field value to fields dict."""
+        if field_name:
+            fields[field_name] = "\n".join(value_lines).strip()

src/linters/file_header/bash_parser.py

@@ -0,0 +1,66 @@
+"""
+Purpose: Bash shell script comment header extraction and parsing
+
+Scope: Bash and shell script file header parsing
+
+Overview: Extracts hash comment headers from Bash shell scripts. Handles shebang lines
+    (#!/bin/bash, #!/usr/bin/env bash, etc.) by skipping them and extracting the
+    comment block that follows. Parses structured header fields from comment content.
+    Extracts contiguous comment blocks from the start of the file and processes them
+    into structured fields for validation.
+
+Dependencies: base_parser.BaseHeaderParser for common field parsing functionality
+
+Exports: BashHeaderParser class
+
+Interfaces: extract_header(code) -> str | None for comment extraction, parse_fields(header) inherited from base
+
+Implementation: Skips shebang and preamble, then extracts contiguous hash comment block
+
+Suppressions:
+    - nesting: _skip_preamble uses conditional loops for shebang/preamble detection.
+        Sequential line processing requires nested state checks.
+"""
+
+from src.linters.file_header.base_parser import BaseHeaderParser
+
+
+class BashHeaderParser(BaseHeaderParser):
+    """Extracts and parses Bash file headers from comment blocks."""
+
+    def __init__(self) -> None:
+        """Initialize the Bash header parser."""
+        pass  # BaseHeaderParser has no __init__, but we need this for stateless-class
+
+    def extract_header(self, code: str) -> str | None:
+        """Extract comment header from Bash script."""
+        if not code or not code.strip():
+            return None
+
+        lines = self._skip_preamble(code.split("\n"))
+        header_lines = self._extract_comment_block(lines)
+
+        return "\n".join(header_lines) if header_lines else None
+
+    def _skip_preamble(self, lines: list[str]) -> list[str]:  # thailint: ignore[nesting]
+        """Skip shebang and leading empty lines."""
+        result = []
+        skipping = True
+        for line in lines:
+            stripped = line.strip()
+            if skipping:
+                if stripped.startswith("#!") or not stripped:
+                    continue
+                skipping = False
+            result.append(stripped)
+        return result
+
+    def _extract_comment_block(self, lines: list[str]) -> list[str]:
+        """Extract contiguous comment lines from start of input."""
+        result = []
+        for line in lines:
+            if line.startswith("#"):
+                result.append(line[1:].strip())
+            else:
+                break
+        return result

src/linters/file_header/config.py

@@ -0,0 +1,140 @@
+"""
+Purpose: Configuration model for file header linter
+
+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
+    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
+
+Interfaces: from_dict(config_dict, language) -> FileHeaderConfig for configuration loading
+
+Implementation: Dataclass with language-specific field lists and factory method for config loading
+"""
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class FileHeaderConfig:
+    """Configuration for file header linting."""
+
+    # Required fields by language - Python
+    required_fields_python: list[str] = field(
+        default_factory=lambda: [
+            "Purpose",
+            "Scope",
+            "Overview",
+            "Dependencies",
+            "Exports",
+            "Interfaces",
+            "Implementation",
+        ]
+    )
+
+    # 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
+
+    # 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
+        """
+        defaults = cls()
+        required_fields = config_dict.get("required_fields", {})
+
+        # Handle both list format (applies to all languages) and dict format (language-specific)
+        if isinstance(required_fields, list):
+            # Simple list format: apply same fields to all languages
+            return cls(
+                required_fields_python=required_fields,
+                required_fields_typescript=required_fields,
+                required_fields_bash=required_fields,
+                required_fields_markdown=required_fields,
+                required_fields_css=required_fields,
+                enforce_atemporal=config_dict.get("enforce_atemporal", True),
+                ignore=config_dict.get("ignore", defaults.ignore),
+            )
+
+        # Dict format: language-specific fields
+        return cls(
+            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", 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

@@ -0,0 +1,72 @@
+"""
+Purpose: Validates mandatory fields in file headers
+
+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
+    for missing or empty fields. Uses configuration-driven validation to support
+    different field requirements per language type.
+
+Dependencies: FileHeaderConfig for language-specific field requirements
+
+Exports: FieldValidator class
+
+Interfaces: validate_fields(fields, language) -> list[tuple[str, str]] returns field violations
+
+Implementation: Configuration-driven validation with field presence and emptiness checking
+"""
+
+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(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
+        """
+        required_fields = self._get_required_fields(language)
+        return [
+            error
+            for field_name in required_fields
+            if (error := self._check_field(fields, field_name))
+        ]
+
+    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}")
+
+        if not fields[field_name] or not fields[field_name].strip():
+            return (field_name, f"Empty mandatory field: {field_name}")
+
+        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, [])