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

src/cli.py

@@ -38,7 +38,11 @@ logger = logging.getLogger(__name__)
 def format_option(func):
     """Add --format option to a command for output format selection."""
     return click.option(
-        "--format", "-f", type=click.Choice(["text", "json"]), default="text", help="Output format"
+        "--format",
+        "-f",
+        type=click.Choice(["text", "json", "sarif"]),
+        default="text",
+        help="Output format",
     )(func)
 
 
@@ -1661,5 +1665,118 @@ def _execute_print_statements_lint(  # pylint: disable=too-many-arguments,too-ma
     sys.exit(1 if print_statements_violations else 0)
 
 
+# File Header Command Helper Functions
+
+
+def _setup_file_header_orchestrator(
+    path_objs: list[Path], config_file: str | None, verbose: bool, project_root: Path | None = None
+):
+    """Set up orchestrator for file-header command."""
+    from src.orchestrator.core import Orchestrator
+    from src.utils.project_root import get_project_root
+
+    # Use provided project_root or fall back to auto-detection
+    if project_root is None:
+        first_path = path_objs[0] if path_objs else Path.cwd()
+        search_start = first_path if first_path.is_dir() else first_path.parent
+        project_root = get_project_root(search_start)
+
+    orchestrator = Orchestrator(project_root=project_root)
+
+    if config_file:
+        _load_config_file(orchestrator, config_file, verbose)
+
+    return orchestrator
+
+
+def _run_file_header_lint(orchestrator, path_objs: list[Path], recursive: bool):
+    """Execute file-header lint on files or directories."""
+    all_violations = _execute_linting_on_paths(orchestrator, path_objs, recursive)
+    return [v for v in all_violations if "file-header" in v.rule_id]
+
+
+@cli.command("file-header")
+@click.argument("paths", nargs=-1, type=click.Path())
+@click.option("--config", "-c", "config_file", type=click.Path(), help="Path to config file")
+@format_option
+@click.option("--recursive/--no-recursive", default=True, help="Scan directories recursively")
+@click.pass_context
+def file_header(
+    ctx,
+    paths: tuple[str, ...],
+    config_file: str | None,
+    format: str,
+    recursive: bool,
+):
+    """Check file headers for mandatory fields and atemporal language.
+
+    Validates that source files have proper documentation headers containing
+    required fields (Purpose, Scope, Overview, etc.) and don't use temporal
+    language (dates, "currently", "now", etc.).
+
+    Supports Python, TypeScript, JavaScript, Bash, Markdown, and CSS files.
+
+    PATHS: Files or directories to lint (defaults to current directory if none provided)
+
+    Examples:
+
+        \b
+        # Check current directory (all files recursively)
+        thai-lint file-header
+
+        \b
+        # Check specific directory
+        thai-lint file-header src/
+
+        \b
+        # Check single file
+        thai-lint file-header src/cli.py
+
+        \b
+        # Check multiple files
+        thai-lint file-header src/cli.py src/api.py tests/
+
+        \b
+        # Get JSON output
+        thai-lint file-header --format json .
+
+        \b
+        # Get SARIF output for CI/CD integration
+        thai-lint file-header --format sarif src/
+
+        \b
+        # Use custom config file
+        thai-lint file-header --config .thailint.yaml src/
+    """
+    verbose = ctx.obj.get("verbose", False)
+    project_root = _get_project_root_from_context(ctx)
+
+    # Default to current directory if no paths provided
+    if not paths:
+        paths = (".",)
+
+    path_objs = [Path(p) for p in paths]
+
+    try:
+        _execute_file_header_lint(path_objs, config_file, format, recursive, verbose, project_root)
+    except Exception as e:
+        _handle_linting_error(e, verbose)
+
+
+def _execute_file_header_lint(  # pylint: disable=too-many-arguments,too-many-positional-arguments
+    path_objs, config_file, format, recursive, verbose, project_root=None
+):
+    """Execute file-header lint."""
+    _validate_paths_exist(path_objs)
+    orchestrator = _setup_file_header_orchestrator(path_objs, config_file, verbose, project_root)
+    file_header_violations = _run_file_header_lint(orchestrator, path_objs, recursive)
+
+    if verbose:
+        logger.info(f"Found {len(file_header_violations)} file header violation(s)")
+
+    format_violations(file_header_violations, format)
+    sys.exit(1 if file_header_violations else 0)
+
+
 if __name__ == "__main__":
     cli()

src/core/cli_utils.py

@@ -146,10 +146,12 @@ def format_violations(violations: list, output_format: str) -> None:
 
     Args:
         violations: List of violation objects with rule_id, file_path, line, column, message, severity
-        output_format: Output format ("text" or "json")
+        output_format: Output format ("text", "json", or "sarif")
     """
     if output_format == "json":
         _output_json(violations)
+    elif output_format == "sarif":
+        _output_sarif(violations)
     else:
         _output_text(violations)
 
@@ -177,6 +179,19 @@ def _output_json(violations: list) -> None:
     click.echo(json.dumps(output, indent=2))
 
 
+def _output_sarif(violations: list) -> None:
+    """Output violations in SARIF v2.1.0 format.
+
+    Args:
+        violations: List of violation objects
+    """
+    from src.formatters.sarif import SarifFormatter
+
+    formatter = SarifFormatter()
+    sarif_doc = formatter.format(violations)
+    click.echo(json.dumps(sarif_doc, indent=2))
+
+
 def _output_text(violations: list) -> None:
     """Output violations in human-readable text format.
 

src/core/registry.py

@@ -6,7 +6,7 @@ Scope: Dynamic rule management and discovery across all linter plugin packages
 Overview: Implements rule registry that maintains a collection of registered linting rules indexed
     by rule_id. Provides methods to register individual rules, retrieve rules by identifier, list
     all available rules, and discover rules from packages using the RuleDiscovery helper. Enables
-    the extensible plugin architecture by allowing rules to be added dynamically without framework
+    the extensible plugin architecture by allowing dynamic rule registration without framework
     modifications. Validates rule uniqueness and handles registration errors gracefully.
 
 Dependencies: BaseLintRule, RuleDiscovery

src/formatters/__init__.py

@@ -0,0 +1,22 @@
+"""
+Purpose: SARIF formatter package for thai-lint output
+
+Scope: SARIF v2.1.0 formatter implementation and package exports
+
+Overview: Formatters package providing SARIF (Static Analysis Results Interchange Format) v2.1.0
+    output generation from thai-lint Violation objects. Enables integration with GitHub Code
+    Scanning, Azure DevOps, VS Code SARIF Viewer, and other industry-standard CI/CD platforms.
+    Provides the SarifFormatter class for converting violations to SARIF JSON documents.
+
+Dependencies: sarif module for SarifFormatter class
+
+Exports: SarifFormatter class from sarif.py module
+
+Interfaces: from src.formatters.sarif import SarifFormatter
+
+Implementation: Package initialization with SarifFormatter export
+"""
+
+from src.formatters.sarif import SarifFormatter
+
+__all__ = ["SarifFormatter"]

src/formatters/sarif.py

@@ -0,0 +1,202 @@
+"""
+Purpose: SARIF v2.1.0 formatter for converting Violation objects to SARIF JSON documents
+
+Scope: SARIF document generation, tool metadata, result conversion, location mapping
+
+Overview: Implements SarifFormatter class that converts thai-lint Violation objects to SARIF
+    (Static Analysis Results Interchange Format) v2.1.0 compliant JSON documents. Produces
+    output compatible with GitHub Code Scanning, Azure DevOps, VS Code SARIF Viewer, and
+    other industry-standard static analysis tools. Handles proper field mapping including
+    1-indexed column conversion, rule metadata deduplication, and tool versioning.
+
+Dependencies: src (for __version__), src.core.types (Violation, Severity)
+
+Exports: SarifFormatter class with format() method
+
+Interfaces: SarifFormatter.format(violations: list[Violation]) -> dict
+
+Implementation: Converts Violation objects to SARIF structure with proper indexing and metadata
+"""
+
+from typing import Any
+
+from src import __version__
+from src.core.types import Violation
+
+
+class SarifFormatter:
+    """Formats Violation objects as SARIF v2.1.0 JSON documents.
+
+    SARIF (Static Analysis Results Interchange Format) is the OASIS standard
+    for static analysis tool output, enabling integration with GitHub Code
+    Scanning, Azure DevOps, and other CI/CD platforms.
+
+    Attributes:
+        tool_name: Name of the tool in SARIF output (default: "thai-lint")
+        tool_version: Version string for the tool (default: package version)
+        information_uri: URL for tool documentation
+    """
+
+    SARIF_VERSION = "2.1.0"
+    SARIF_SCHEMA = (
+        "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/"
+        "main/sarif-2.1/schema/sarif-schema-2.1.0.json"
+    )
+    DEFAULT_INFORMATION_URI = "https://github.com/be-wise-be-kind/thai-lint"
+
+    def __init__(
+        self,
+        tool_name: str = "thai-lint",
+        tool_version: str | None = None,
+        information_uri: str | None = None,
+    ) -> None:
+        """Initialize SarifFormatter with tool metadata.
+
+        Args:
+            tool_name: Name of the tool (default: "thai-lint")
+            tool_version: Version string (default: package __version__)
+            information_uri: URL for tool documentation
+        """
+        self.tool_name = tool_name
+        self.tool_version = tool_version or __version__
+        self.information_uri = information_uri or self.DEFAULT_INFORMATION_URI
+
+    def format(self, violations: list[Violation]) -> dict[str, Any]:
+        """Convert violations to SARIF v2.1.0 document.
+
+        Args:
+            violations: List of Violation objects to format
+
+        Returns:
+            SARIF v2.1.0 compliant dictionary ready for JSON serialization
+        """
+        return {
+            "version": self.SARIF_VERSION,
+            "$schema": self.SARIF_SCHEMA,
+            "runs": [self._create_run(violations)],
+        }
+
+    def _create_run(self, violations: list[Violation]) -> dict[str, Any]:
+        """Create a SARIF run object containing tool and results.
+
+        Args:
+            violations: List of violations for this run
+
+        Returns:
+            SARIF run object with tool and results
+        """
+        return {
+            "tool": self._create_tool(violations),
+            "results": [self._create_result(v) for v in violations],
+        }
+
+    def _create_tool(self, violations: list[Violation]) -> dict[str, Any]:
+        """Create SARIF tool object with driver metadata.
+
+        Args:
+            violations: List of violations to extract rule metadata from
+
+        Returns:
+            SARIF tool object with driver
+        """
+        return {
+            "driver": {
+                "name": self.tool_name,
+                "version": self.tool_version,
+                "informationUri": self.information_uri,
+                "rules": self._create_rules(violations),
+            }
+        }
+
+    def _create_rules(self, violations: list[Violation]) -> list[dict[str, Any]]:
+        """Create deduplicated SARIF rules array from violations.
+
+        Args:
+            violations: List of violations to extract unique rules from
+
+        Returns:
+            List of SARIF rule objects with unique IDs
+        """
+        seen_rule_ids: set[str] = set()
+        rules: list[dict[str, Any]] = []
+
+        for violation in violations:
+            if violation.rule_id not in seen_rule_ids:
+                seen_rule_ids.add(violation.rule_id)
+                rules.append(self._create_rule(violation))
+
+        return rules
+
+    def _create_rule(self, violation: Violation) -> dict[str, Any]:
+        """Create SARIF rule object from violation.
+
+        Args:
+            violation: Violation to extract rule metadata from
+
+        Returns:
+            SARIF rule object with id and shortDescription
+        """
+        # Extract rule category from rule_id (e.g., "nesting" from "nesting.excessive-depth")
+        parts = violation.rule_id.split(".")
+        category = parts[0] if parts else violation.rule_id
+
+        descriptions: dict[str, str] = {
+            "file-placement": "File placement violation",
+            "nesting": "Nesting depth violation",
+            "srp": "Single Responsibility Principle violation",
+            "dry": "Don't Repeat Yourself violation",
+            "magic-number": "Magic number violation",
+            "magic-numbers": "Magic number violation",
+            "file-header": "File header violation",
+            "print-statements": "Print statement violation",
+        }
+
+        description = descriptions.get(category, f"Rule: {violation.rule_id}")
+
+        return {
+            "id": violation.rule_id,
+            "shortDescription": {
+                "text": description,
+            },
+        }
+
+    def _create_result(self, violation: Violation) -> dict[str, Any]:
+        """Create SARIF result object from violation.
+
+        Args:
+            violation: Violation to convert to SARIF result
+
+        Returns:
+            SARIF result object with ruleId, level, message, locations
+        """
+        # thai-lint uses binary severity (ERROR only), map all to "error" level
+        return {
+            "ruleId": violation.rule_id,
+            "level": "error",
+            "message": {
+                "text": violation.message,
+            },
+            "locations": [self._create_location(violation)],
+        }
+
+    def _create_location(self, violation: Violation) -> dict[str, Any]:
+        """Create SARIF location object from violation.
+
+        Args:
+            violation: Violation with location information
+
+        Returns:
+            SARIF location object with physicalLocation
+        """
+        return {
+            "physicalLocation": {
+                "artifactLocation": {
+                    "uri": violation.file_path,
+                },
+                "region": {
+                    "startLine": violation.line,
+                    # SARIF uses 1-indexed columns, Violation uses 0-indexed
+                    "startColumn": violation.column + 1,
+                },
+            }
+        }

src/linters/file_header/atemporal_detector.py

@@ -1,21 +1,21 @@
 """
-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
+Scope: File header validation for atemporal language compliance
+
+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.
+    Uses four pattern categories (dates, temporal qualifiers, state changes, future references)
+    to identify violations and returns detailed information for each match.
+
+Dependencies: re module for regex-based pattern matching
+
+Exports: AtemporalDetector class with detect_violations method
 
-Usage:
-    detector = AtemporalDetector()
-    violations = detector.detect_violations(header_text)
+Interfaces: detect_violations(text) -> list[tuple[str, str, int]] returns pattern matches with line numbers
 
-Notes: Four pattern categories - dates, temporal qualifiers, state changes, future references
+Implementation: Regex-based pattern matching with predefined patterns organized by category
 """
 
 import re

src/linters/file_header/base_parser.py

@@ -0,0 +1,89 @@
+"""
+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
+"""
+
+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,58 @@
+"""
+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
+"""
+
+from src.linters.file_header.base_parser import BaseHeaderParser
+
+
+class BashHeaderParser(BaseHeaderParser):
+    """Extracts and parses Bash file headers from comment blocks."""
+
+    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