thailint 0.4.6__tar.gz → 0.7.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: thailint
-Version: 0.4.6
+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-356%2F356%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)
@@ -122,7 +128,7 @@ cd thai-lint
 pip install -e ".[dev]"
 ```
 
-### From PyPI (once published)
+### From PyPI
 
 ```bash
 pip install thai-lint
@@ -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.4.6 → 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-356%2F356%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)
@@ -87,7 +93,7 @@ cd thai-lint
 pip install -e ".[dev]"
 ```
 
-### From PyPI (once published)
+### From PyPI
 
 ```bash
 pip install thai-lint
@@ -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.4.6 → thailint-0.7.0}/pyproject.toml

@@ -17,7 +17,7 @@ build-backend = "poetry.core.masonry.api"
 
 [tool.poetry]
 name = "thailint"
-version = "0.4.6"
+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.4.6 → 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)
 
 
@@ -1551,5 +1555,228 @@ def _execute_magic_numbers_lint(  # pylint: disable=too-many-arguments,too-many-
     sys.exit(1 if magic_numbers_violations else 0)
 
 
+# =============================================================================
+# Print Statements Linter Command
+# =============================================================================
+
+
+def _setup_print_statements_orchestrator(
+    path_objs: list[Path], config_file: str | None, verbose: bool, project_root: Path | None = None
+):
+    """Set up orchestrator for print-statements command."""
+    from src.orchestrator.core import Orchestrator
+    from src.utils.project_root import get_project_root
+
+    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_print_statements_lint(orchestrator, path_objs: list[Path], recursive: bool):
+    """Execute print-statements lint on files or directories."""
+    all_violations = _execute_linting_on_paths(orchestrator, path_objs, recursive)
+    return [v for v in all_violations if "print-statement" in v.rule_id]
+
+
+@cli.command("print-statements")
+@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 print_statements(  # pylint: disable=too-many-arguments,too-many-positional-arguments
+    ctx,
+    paths: tuple[str, ...],
+    config_file: str | None,
+    format: str,
+    recursive: bool,
+):
+    """Check for print/console statements in code.
+
+    Detects print() calls in Python and console.log/warn/error/debug/info calls
+    in TypeScript/JavaScript that should be replaced with proper logging.
+
+    PATHS: Files or directories to lint (defaults to current directory if none provided)
+
+    Examples:
+
+        \b
+        # Check current directory (all files recursively)
+        thai-lint print-statements
+
+        \b
+        # Check specific directory
+        thai-lint print-statements src/
+
+        \b
+        # Check single file
+        thai-lint print-statements src/app.py
+
+        \b
+        # Check multiple files
+        thai-lint print-statements src/app.py src/utils.ts tests/test_app.py
+
+        \b
+        # Get JSON output
+        thai-lint print-statements --format json .
+
+        \b
+        # Use custom config file
+        thai-lint print-statements --config .thailint.yaml src/
+    """
+    verbose = ctx.obj.get("verbose", False)
+    project_root = _get_project_root_from_context(ctx)
+
+    if not paths:
+        paths = (".",)
+
+    path_objs = [Path(p) for p in paths]
+
+    try:
+        _execute_print_statements_lint(
+            path_objs, config_file, format, recursive, verbose, project_root
+        )
+    except Exception as e:
+        _handle_linting_error(e, verbose)
+
+
+def _execute_print_statements_lint(  # pylint: disable=too-many-arguments,too-many-positional-arguments
+    path_objs, config_file, format, recursive, verbose, project_root=None
+):
+    """Execute print-statements lint."""
+    _validate_paths_exist(path_objs)
+    orchestrator = _setup_print_statements_orchestrator(
+        path_objs, config_file, verbose, project_root
+    )
+    print_statements_violations = _run_print_statements_lint(orchestrator, path_objs, recursive)
+
+    if verbose:
+        logger.info(f"Found {len(print_statements_violations)} print statement violation(s)")
+
+    format_violations(print_statements_violations, format)
+    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()