thailint 0.5.0__tar.gz → 0.8.0__tar.gz

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

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: thailint
-Version: 0.5.0
+Version: 0.8.0
 Summary: The AI Linter - Enterprise-grade linting and governance for AI-generated code across multiple languages
 License: MIT
 License-File: LICENSE
 Keywords: linter,ai,code-quality,static-analysis,file-placement,governance,multi-language,cli,docker,python
 Author: Steve Jackson
 Requires-Python: >=3.11,<4.0
-Classifier: Development Status :: 3 - Alpha
+Classifier: Development Status :: 4 - Beta
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT 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-682%2F682%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)
@@ -92,6 +98,12 @@ thailint complements your existing linting stack by catching the patterns AI too
   - Configurable thresholds (lines, tokens, occurrences)
   - Language-specific detection (Python, TypeScript, JavaScript)
   - False positive filtering (keyword args, imports)
+- **Method Property Linting** - Detect methods that should be @property decorators
+  - Python AST-based detection
+  - get_* prefix detection (Java-style getters)
+  - Simple computed value detection
+  - Action verb exclusion (to_*, finalize, serialize)
+  - Test file detection
 - **Pluggable Architecture** - Easy to extend with custom linters
 - **Multi-Language Support** - Python, TypeScript, JavaScript, and more
 - **Flexible Configuration** - YAML/JSON configs with pattern matching
@@ -158,11 +170,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 +887,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 +1301,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 +1318,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.8.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-682%2F682%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)
@@ -57,6 +63,12 @@ thailint complements your existing linting stack by catching the patterns AI too
   - Configurable thresholds (lines, tokens, occurrences)
   - Language-specific detection (Python, TypeScript, JavaScript)
   - False positive filtering (keyword args, imports)
+- **Method Property Linting** - Detect methods that should be @property decorators
+  - Python AST-based detection
+  - get_* prefix detection (Java-style getters)
+  - Simple computed value detection
+  - Action verb exclusion (to_*, finalize, serialize)
+  - Test file detection
 - **Pluggable Architecture** - Easy to extend with custom linters
 - **Multi-Language Support** - Python, TypeScript, JavaScript, and more
 - **Flexible Configuration** - YAML/JSON configs with pattern matching
@@ -123,11 +135,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 +852,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 +1266,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 +1283,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.8.0}/pyproject.toml

@@ -17,7 +17,7 @@ build-backend = "poetry.core.masonry.api"
 
 [tool.poetry]
 name = "thailint"
-version = "0.5.0"
+version = "0.8.0"
 description = "The AI Linter - Enterprise-grade linting and governance for AI-generated code across multiple languages"
 authors = ["Steve Jackson"]
 license = "MIT"
@@ -38,7 +38,7 @@ keywords = [
     "python",
 ]
 classifiers = [
-    "Development Status :: 3 - Alpha",
+    "Development Status :: 4 - Beta",
     "Intended Audience :: Developers",
     "License :: OSI Approved :: MIT License",
     "Programming Language :: Python :: 3",