thailint 0.5.0__tar.gz → 0.7.0__tar.gz

{thailint-0.5.0 → thailint-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: thailint
-Version: 0.5.0
+Version: 0.7.0
 Summary: The AI Linter - Enterprise-grade linting and governance for AI-generated code across multiple languages
 License: MIT
 License-File: LICENSE
@@ -37,9 +37,10 @@ Description-Content-Type: text/markdown
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
-[![Tests](https://img.shields.io/badge/tests-393%2F393%20passing-brightgreen.svg)](tests/)
+[![Tests](https://img.shields.io/badge/tests-571%2F571%20passing-brightgreen.svg)](tests/)
 [![Coverage](https://img.shields.io/badge/coverage-87%25-brightgreen.svg)](htmlcov/)
 [![Documentation Status](https://readthedocs.org/projects/thai-lint/badge/?version=latest)](https://thai-lint.readthedocs.io/en/latest/?badge=latest)
+[![SARIF 2.1.0](https://img.shields.io/badge/SARIF-2.1.0-orange.svg)](docs/sarif-output.md)
 
 The AI Linter - Enterprise-ready linting and governance for AI-generated code across multiple languages.
 
@@ -73,6 +74,11 @@ thailint complements your existing linting stack by catching the patterns AI too
 
 ### Core Capabilities
 - **File Placement Linting** - Enforce project structure and organization
+- **File Header Linting** - Validate documentation headers in source files
+  - Python, TypeScript, JavaScript, Bash, Markdown, CSS support
+  - Mandatory field validation (Purpose, Scope, Overview)
+  - Atemporal language detection (no dates, "currently", "now")
+  - Language-specific header format parsing
 - **Magic Numbers Linting** - Detect unnamed numeric literals that should be constants
   - Python and TypeScript support with AST analysis
   - Context-aware detection (ignores constants, test files, range() usage)
@@ -158,11 +164,17 @@ thailint dry .
 # Check for magic numbers
 thailint magic-numbers src/
 
+# Check file headers
+thailint file-header src/
+
 # With config file
 thailint dry --config .thailint.yaml src/
 
 # JSON output for CI/CD
 thailint dry --format json src/
+
+# SARIF output for GitHub Code Scanning
+thailint nesting --format sarif src/ > results.sarif
 ```
 
 **New to thailint?** See the **[Quick Start Guide](https://thai-lint.readthedocs.io/en/latest/quick-start/)** for a complete walkthrough including config generation, understanding output, and next steps.
@@ -869,6 +881,136 @@ def get_ports():  # thailint: ignore[magic-numbers] - Standard ports
 
 See **[How to Ignore Violations](https://thai-lint.readthedocs.io/en/latest/how-to-ignore-violations/)** and **[Magic Numbers Linter Guide](https://thai-lint.readthedocs.io/en/latest/magic-numbers-linter/)** for complete documentation.
 
+## File Header Linter
+
+### Overview
+
+The file header linter validates that source files have proper documentation headers containing required fields (Purpose, Scope, Overview) and don't use temporal language (dates, "currently", "now"). It enforces consistent documentation patterns across entire codebases.
+
+### Why File Headers?
+
+File headers serve as **self-documentation** that helps developers (and AI assistants) quickly understand:
+
+- **Purpose**: What does this file do?
+- **Scope**: What area of the system does it cover?
+- **Dependencies**: What does it rely on?
+- **Exports**: What does it provide to other modules?
+
+### Quick Start
+
+```bash
+# Check file headers in current directory
+thailint file-header .
+
+# Check specific directory
+thailint file-header src/
+
+# Get JSON output
+thailint file-header --format json src/
+
+# Get SARIF output for CI/CD
+thailint file-header --format sarif src/ > results.sarif
+```
+
+### Configuration
+
+Add to `.thailint.yaml`:
+
+```yaml
+file-header:
+  enabled: true
+  mandatory_fields:
+    - Purpose
+    - Scope
+    - Overview
+  ignore:
+    - "**/__init__.py"
+    - "**/migrations/**"
+```
+
+### Example Violation
+
+**Code without proper header:**
+```python
+import os
+
+def process_data():
+    pass
+```
+
+**Violation messages:**
+```
+src/utils.py:1 - Missing mandatory field: Purpose
+src/utils.py:1 - Missing mandatory field: Scope
+src/utils.py:1 - Missing mandatory field: Overview
+```
+
+**Refactored with header:**
+```python
+"""
+Purpose: Data processing utilities for ETL pipeline
+
+Scope: Data transformation layer, used by batch processing jobs
+
+Overview: Provides data transformation functions for the ETL pipeline.
+    Handles parsing, validation, and normalization of incoming data.
+
+Dependencies: os, json
+
+Exports: process_data(), validate_input(), transform_record()
+"""
+import os
+
+def process_data():
+    pass
+```
+
+### Atemporal Language Detection
+
+The linter detects temporal language that becomes stale:
+
+**Temporal (flagged):**
+```python
+"""
+Purpose: Authentication module
+
+Overview: Currently handles OAuth. This was recently updated.
+    Created: 2024-01-15. Will be extended in the future.
+"""
+```
+
+**Atemporal (correct):**
+```python
+"""
+Purpose: Authentication module
+
+Overview: Handles OAuth authentication with Google and GitHub.
+    Implements authorization code flow with PKCE for security.
+"""
+```
+
+### Language Support
+
+- **Python**: Module docstrings (`"""..."""`)
+- **TypeScript/JavaScript**: JSDoc comments (`/** ... */`)
+- **Bash**: Hash comments after shebang (`# ...`)
+- **Markdown**: YAML frontmatter (`---...---`)
+- **CSS/SCSS**: Block comments (`/* ... */`)
+
+### Ignoring Violations
+
+```python
+# File-level ignore
+# thailint: ignore-file[file-header]
+
+# Line-level ignore for atemporal violation
+"""
+Overview: Created 2024-01-15.  # thailint: ignore[file-header]
+"""
+```
+
+See **[How to Ignore Violations](https://thai-lint.readthedocs.io/en/latest/how-to-ignore-violations/)** and **[File Header Linter Guide](https://thai-lint.readthedocs.io/en/latest/file-header-linter/)** for complete documentation.
+
 ## Pre-commit Hooks
 
 Automate code quality checks before every commit and push with pre-commit hooks.
@@ -1153,11 +1295,13 @@ docker run --rm -v /path/to/workspace:/workspace \
 - **[CLI Reference](https://thai-lint.readthedocs.io/en/latest/cli-reference/)** - All CLI commands and options
 - **[Deployment Modes](https://thai-lint.readthedocs.io/en/latest/deployment-modes/)** - CLI, Library, and Docker usage
 - **[File Placement Linter](https://thai-lint.readthedocs.io/en/latest/file-placement-linter/)** - Detailed linter guide
+- **[File Header Linter](https://thai-lint.readthedocs.io/en/latest/file-header-linter/)** - File header validation guide
 - **[Magic Numbers Linter](https://thai-lint.readthedocs.io/en/latest/magic-numbers-linter/)** - Magic numbers detection guide
 - **[Nesting Depth Linter](https://thai-lint.readthedocs.io/en/latest/nesting-linter/)** - Nesting depth analysis guide
 - **[SRP Linter](https://thai-lint.readthedocs.io/en/latest/srp-linter/)** - Single Responsibility Principle guide
 - **[DRY Linter](https://thai-lint.readthedocs.io/en/latest/dry-linter/)** - Duplicate code detection guide
 - **[Pre-commit Hooks](https://thai-lint.readthedocs.io/en/latest/pre-commit-hooks/)** - Automated quality checks
+- **[SARIF Output Guide](docs/sarif-output.md)** - SARIF format for GitHub Code Scanning and CI/CD
 - **[Publishing Guide](https://thai-lint.readthedocs.io/en/latest/releasing/)** - Release and publishing workflow
 - **[Publishing Checklist](https://thai-lint.readthedocs.io/en/latest/publishing-checklist/)** - Post-publication validation
 
@@ -1168,6 +1312,8 @@ See [`examples/`](examples/) directory for working code:
 - **[basic_usage.py](examples/basic_usage.py)** - Simple library API usage
 - **[advanced_usage.py](examples/advanced_usage.py)** - Advanced patterns and workflows
 - **[ci_integration.py](examples/ci_integration.py)** - CI/CD integration example
+- **[sarif_usage.py](examples/sarif_usage.py)** - SARIF output format examples
+- **[file_header_usage.py](examples/file_header_usage.py)** - File header validation examples
 
 ## Project Structure
 

{thailint-0.5.0 → thailint-0.7.0}/README.md

@@ -2,9 +2,10 @@
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
-[![Tests](https://img.shields.io/badge/tests-393%2F393%20passing-brightgreen.svg)](tests/)
+[![Tests](https://img.shields.io/badge/tests-571%2F571%20passing-brightgreen.svg)](tests/)
 [![Coverage](https://img.shields.io/badge/coverage-87%25-brightgreen.svg)](htmlcov/)
 [![Documentation Status](https://readthedocs.org/projects/thai-lint/badge/?version=latest)](https://thai-lint.readthedocs.io/en/latest/?badge=latest)
+[![SARIF 2.1.0](https://img.shields.io/badge/SARIF-2.1.0-orange.svg)](docs/sarif-output.md)
 
 The AI Linter - Enterprise-ready linting and governance for AI-generated code across multiple languages.
 
@@ -38,6 +39,11 @@ thailint complements your existing linting stack by catching the patterns AI too
 
 ### Core Capabilities
 - **File Placement Linting** - Enforce project structure and organization
+- **File Header Linting** - Validate documentation headers in source files
+  - Python, TypeScript, JavaScript, Bash, Markdown, CSS support
+  - Mandatory field validation (Purpose, Scope, Overview)
+  - Atemporal language detection (no dates, "currently", "now")
+  - Language-specific header format parsing
 - **Magic Numbers Linting** - Detect unnamed numeric literals that should be constants
   - Python and TypeScript support with AST analysis
   - Context-aware detection (ignores constants, test files, range() usage)
@@ -123,11 +129,17 @@ thailint dry .
 # Check for magic numbers
 thailint magic-numbers src/
 
+# Check file headers
+thailint file-header src/
+
 # With config file
 thailint dry --config .thailint.yaml src/
 
 # JSON output for CI/CD
 thailint dry --format json src/
+
+# SARIF output for GitHub Code Scanning
+thailint nesting --format sarif src/ > results.sarif
 ```
 
 **New to thailint?** See the **[Quick Start Guide](https://thai-lint.readthedocs.io/en/latest/quick-start/)** for a complete walkthrough including config generation, understanding output, and next steps.
@@ -834,6 +846,136 @@ def get_ports():  # thailint: ignore[magic-numbers] - Standard ports
 
 See **[How to Ignore Violations](https://thai-lint.readthedocs.io/en/latest/how-to-ignore-violations/)** and **[Magic Numbers Linter Guide](https://thai-lint.readthedocs.io/en/latest/magic-numbers-linter/)** for complete documentation.
 
+## File Header Linter
+
+### Overview
+
+The file header linter validates that source files have proper documentation headers containing required fields (Purpose, Scope, Overview) and don't use temporal language (dates, "currently", "now"). It enforces consistent documentation patterns across entire codebases.
+
+### Why File Headers?
+
+File headers serve as **self-documentation** that helps developers (and AI assistants) quickly understand:
+
+- **Purpose**: What does this file do?
+- **Scope**: What area of the system does it cover?
+- **Dependencies**: What does it rely on?
+- **Exports**: What does it provide to other modules?
+
+### Quick Start
+
+```bash
+# Check file headers in current directory
+thailint file-header .
+
+# Check specific directory
+thailint file-header src/
+
+# Get JSON output
+thailint file-header --format json src/
+
+# Get SARIF output for CI/CD
+thailint file-header --format sarif src/ > results.sarif
+```
+
+### Configuration
+
+Add to `.thailint.yaml`:
+
+```yaml
+file-header:
+  enabled: true
+  mandatory_fields:
+    - Purpose
+    - Scope
+    - Overview
+  ignore:
+    - "**/__init__.py"
+    - "**/migrations/**"
+```
+
+### Example Violation
+
+**Code without proper header:**
+```python
+import os
+
+def process_data():
+    pass
+```
+
+**Violation messages:**
+```
+src/utils.py:1 - Missing mandatory field: Purpose
+src/utils.py:1 - Missing mandatory field: Scope
+src/utils.py:1 - Missing mandatory field: Overview
+```
+
+**Refactored with header:**
+```python
+"""
+Purpose: Data processing utilities for ETL pipeline
+
+Scope: Data transformation layer, used by batch processing jobs
+
+Overview: Provides data transformation functions for the ETL pipeline.
+    Handles parsing, validation, and normalization of incoming data.
+
+Dependencies: os, json
+
+Exports: process_data(), validate_input(), transform_record()
+"""
+import os
+
+def process_data():
+    pass
+```
+
+### Atemporal Language Detection
+
+The linter detects temporal language that becomes stale:
+
+**Temporal (flagged):**
+```python
+"""
+Purpose: Authentication module
+
+Overview: Currently handles OAuth. This was recently updated.
+    Created: 2024-01-15. Will be extended in the future.
+"""
+```
+
+**Atemporal (correct):**
+```python
+"""
+Purpose: Authentication module
+
+Overview: Handles OAuth authentication with Google and GitHub.
+    Implements authorization code flow with PKCE for security.
+"""
+```
+
+### Language Support
+
+- **Python**: Module docstrings (`"""..."""`)
+- **TypeScript/JavaScript**: JSDoc comments (`/** ... */`)
+- **Bash**: Hash comments after shebang (`# ...`)
+- **Markdown**: YAML frontmatter (`---...---`)
+- **CSS/SCSS**: Block comments (`/* ... */`)
+
+### Ignoring Violations
+
+```python
+# File-level ignore
+# thailint: ignore-file[file-header]
+
+# Line-level ignore for atemporal violation
+"""
+Overview: Created 2024-01-15.  # thailint: ignore[file-header]
+"""
+```
+
+See **[How to Ignore Violations](https://thai-lint.readthedocs.io/en/latest/how-to-ignore-violations/)** and **[File Header Linter Guide](https://thai-lint.readthedocs.io/en/latest/file-header-linter/)** for complete documentation.
+
 ## Pre-commit Hooks
 
 Automate code quality checks before every commit and push with pre-commit hooks.
@@ -1118,11 +1260,13 @@ docker run --rm -v /path/to/workspace:/workspace \
 - **[CLI Reference](https://thai-lint.readthedocs.io/en/latest/cli-reference/)** - All CLI commands and options
 - **[Deployment Modes](https://thai-lint.readthedocs.io/en/latest/deployment-modes/)** - CLI, Library, and Docker usage
 - **[File Placement Linter](https://thai-lint.readthedocs.io/en/latest/file-placement-linter/)** - Detailed linter guide
+- **[File Header Linter](https://thai-lint.readthedocs.io/en/latest/file-header-linter/)** - File header validation guide
 - **[Magic Numbers Linter](https://thai-lint.readthedocs.io/en/latest/magic-numbers-linter/)** - Magic numbers detection guide
 - **[Nesting Depth Linter](https://thai-lint.readthedocs.io/en/latest/nesting-linter/)** - Nesting depth analysis guide
 - **[SRP Linter](https://thai-lint.readthedocs.io/en/latest/srp-linter/)** - Single Responsibility Principle guide
 - **[DRY Linter](https://thai-lint.readthedocs.io/en/latest/dry-linter/)** - Duplicate code detection guide
 - **[Pre-commit Hooks](https://thai-lint.readthedocs.io/en/latest/pre-commit-hooks/)** - Automated quality checks
+- **[SARIF Output Guide](docs/sarif-output.md)** - SARIF format for GitHub Code Scanning and CI/CD
 - **[Publishing Guide](https://thai-lint.readthedocs.io/en/latest/releasing/)** - Release and publishing workflow
 - **[Publishing Checklist](https://thai-lint.readthedocs.io/en/latest/publishing-checklist/)** - Post-publication validation
 
@@ -1133,6 +1277,8 @@ See [`examples/`](examples/) directory for working code:
 - **[basic_usage.py](examples/basic_usage.py)** - Simple library API usage
 - **[advanced_usage.py](examples/advanced_usage.py)** - Advanced patterns and workflows
 - **[ci_integration.py](examples/ci_integration.py)** - CI/CD integration example
+- **[sarif_usage.py](examples/sarif_usage.py)** - SARIF output format examples
+- **[file_header_usage.py](examples/file_header_usage.py)** - File header validation examples
 
 ## Project Structure
 

{thailint-0.5.0 → thailint-0.7.0}/pyproject.toml

@@ -17,7 +17,7 @@ build-backend = "poetry.core.masonry.api"
 
 [tool.poetry]
 name = "thailint"
-version = "0.5.0"
+version = "0.7.0"
 description = "The AI Linter - Enterprise-grade linting and governance for AI-generated code across multiple languages"
 authors = ["Steve Jackson"]
 license = "MIT"

{thailint-0.5.0 → thailint-0.7.0}/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()

{thailint-0.5.0 → thailint-0.7.0}/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.
 

{thailint-0.5.0 → thailint-0.7.0}/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

thailint-0.7.0/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"]