thailint 0.1.6__py3-none-any.whl → 0.2.1__py3-none-any.whl

{thailint-0.1.6.dist-info → thailint-0.2.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: thailint
-Version: 0.1.6
+Version: 0.2.1
 Summary: The AI Linter - Enterprise-grade linting and governance for AI-generated code across multiple languages
 License: MIT
 Keywords: linter,ai,code-quality,static-analysis,file-placement,governance,multi-language,cli,docker,python
@@ -22,6 +22,7 @@ Classifier: Topic :: Software Development :: Testing
 Classifier: Topic :: Utilities
 Classifier: Typing :: Typed
 Requires-Dist: click (>=8.1.0,<9.0.0)
+Requires-Dist: pyprojroot (>=0.3.0,<0.4.0)
 Requires-Dist: pyyaml (>=6.0,<7.0)
 Requires-Dist: tree-sitter (>=0.25.2,<0.26.0)
 Requires-Dist: tree-sitter-typescript (>=0.23.2,<0.24.0)
@@ -43,30 +44,40 @@ The AI Linter - Enterprise-ready linting and governance for AI-generated code ac
 
 thailint is a modern, enterprise-ready multi-language linter designed specifically for AI-generated code. It enforces project structure, file placement rules, and coding standards across Python, TypeScript, and other languages.
 
-## ✨ Features
+## Features
 
 ### Core Capabilities
-- 🎯 **File Placement Linting** - Enforce project structure and organization
-- 🔄 **Nesting Depth Linting** - Detect excessive code nesting with AST analysis
+- **File Placement Linting** - Enforce project structure and organization
+- **Nesting Depth Linting** - Detect excessive code nesting with AST analysis
   - Python and TypeScript support with tree-sitter
   - Configurable max depth (default: 4, recommended: 3)
   - Helpful refactoring suggestions (guard clauses, extract method)
-- 🔌 **Pluggable Architecture** - Easy to extend with custom linters
-- 🌍 **Multi-Language Support** - Python, TypeScript, JavaScript, and more
-- ⚙️ **Flexible Configuration** - YAML/JSON configs with pattern matching
-- 🚫 **5-Level Ignore System** - Repo, directory, file, method, and line-level ignores
+- **SRP Linting** - Detect Single Responsibility Principle violations
+  - Heuristic-based analysis (method count, LOC, keywords)
+  - Language-specific thresholds (Python, TypeScript, JavaScript)
+  - Refactoring patterns from real-world examples
+- **DRY Linting** - Detect duplicate code across projects
+  - Token-based hash detection with SQLite caching
+  - Fast incremental scans (10-50x speedup with cache)
+  - Configurable thresholds (lines, tokens, occurrences)
+  - Language-specific detection (Python, TypeScript, JavaScript)
+  - False positive filtering (keyword args, imports)
+- **Pluggable Architecture** - Easy to extend with custom linters
+- **Multi-Language Support** - Python, TypeScript, JavaScript, and more
+- **Flexible Configuration** - YAML/JSON configs with pattern matching
+- **5-Level Ignore System** - Repo, directory, file, method, and line-level ignores
 
 ### Deployment Modes
-- 💻 **CLI Mode** - Full-featured command-line interface
-- 📚 **Library API** - Python library for programmatic integration
-- 🐳 **Docker Support** - Containerized deployment for CI/CD
+- **CLI Mode** - Full-featured command-line interface
+- **Library API** - Python library for programmatic integration
+- **Docker Support** - Containerized deployment for CI/CD
 
 ### Enterprise Features
-- 📊 **Performance** - <100ms for single files, <5s for 1000 files
-- 🔒 **Type Safety** - Full type hints and MyPy strict mode
-- 🧪 **Test Coverage** - 90% coverage with 317 tests
-- 📈 **CI/CD Ready** - Proper exit codes and JSON output
-- 📝 **Comprehensive Docs** - Complete documentation and examples
+- **Performance** - <100ms for single files, <5s for 1000 files
+- **Type Safety** - Full type hints and MyPy strict mode
+- **Test Coverage** - 90% coverage with 317 tests
+- **CI/CD Ready** - Proper exit codes and JSON output
+- **Comprehensive Docs** - Complete documentation and examples
 
 ## Installation
 
@@ -105,14 +116,20 @@ docker run --rm washad/thailint:latest --help
 # Check file placement
 thailint file-placement .
 
-# Check nesting depth
+# Check multiple files
+thailint nesting file1.py file2.py file3.py
+
+# Check specific directory
 thailint nesting src/
 
+# Check for duplicate code
+thailint dry .
+
 # With config file
-thailint nesting --config .thailint.yaml src/
+thailint dry --config .thailint.yaml src/
 
 # JSON output for CI/CD
-thailint nesting --format json src/
+thailint dry --format json src/
 ```
 
 ### Library Mode
@@ -135,13 +152,21 @@ if violations:
 ### Docker Mode
 
 ```bash
-# Run with volume mount
+# Lint directory (recommended - lints all files inside)
 docker run --rm -v $(pwd):/data \
   washad/thailint:latest file-placement /data
 
-# Check nesting depth
+# Lint single file
+docker run --rm -v $(pwd):/data \
+  washad/thailint:latest file-placement /data/src/app.py
+
+# Lint multiple specific files
+docker run --rm -v $(pwd):/data \
+  washad/thailint:latest nesting /data/src/file1.py /data/src/file2.py
+
+# Check nesting depth in subdirectory
 docker run --rm -v $(pwd):/data \
-  washad/thailint:latest nesting /data
+  washad/thailint:latest nesting /data/src
 ```
 
 ## Configuration
@@ -191,6 +216,26 @@ nesting:
       max_depth: 4
     javascript:
       max_depth: 4
+
+# DRY linter configuration
+dry:
+  enabled: true
+  min_duplicate_lines: 4         # Minimum lines to consider duplicate
+  min_duplicate_tokens: 30       # Minimum tokens to consider duplicate
+  min_occurrences: 2             # Report if appears 2+ times
+
+  # Language-specific thresholds
+  python:
+    min_occurrences: 3           # Python: require 3+ occurrences
+
+  # Cache settings (SQLite)
+  cache_enabled: true
+  cache_path: ".thailint-cache/dry.db"
+
+  # Ignore patterns
+  ignore:
+    - "tests/"
+    - "__init__.py"
 ```
 
 **JSON format also supported** (`.thailint.json`):
@@ -214,6 +259,18 @@ nesting:
       "python": { "max_depth": 4 },
       "typescript": { "max_depth": 4 }
     }
+  },
+  "dry": {
+    "enabled": true,
+    "min_duplicate_lines": 4,
+    "min_duplicate_tokens": 30,
+    "min_occurrences": 2,
+    "python": {
+      "min_occurrences": 3
+    },
+    "cache_enabled": true,
+    "cache_path": ".thailint-cache/dry.db",
+    "ignore": ["tests/", "__init__.py"]
   }
 }
 ```
@@ -280,7 +337,7 @@ def process_data(items):
 
 ### Refactoring Patterns
 
-Common patterns to reduce nesting (used to fix 23 violations in thai-lint):
+Common patterns to reduce nesting:
 
 1. **Guard Clauses (Early Returns)**
    - Replace `if x: do_something()` with `if not x: return`
@@ -300,19 +357,300 @@ Common patterns to reduce nesting (used to fix 23 violations in thai-lint):
 
 ### Language Support
 
-- ✅ **Python**: Full support (if/for/while/with/try/match)
-- ✅ **TypeScript**: Full support (if/for/while/try/switch)
-- ✅ **JavaScript**: Supported via TypeScript parser
+- **Python**: Full support (if/for/while/with/try/match)
+- **TypeScript**: Full support (if/for/while/try/switch)
+- **JavaScript**: Supported via TypeScript parser
 
-### Refactoring Case Study
+See [Nesting Linter Guide](docs/nesting-linter.md) for comprehensive documentation and refactoring patterns.
 
-The thai-lint codebase serves as a validation of the nesting linter:
-- Identified: 23 functions requiring refactoring (depth 4 → depth ≤3)
-- Refactored using documented patterns
-- Time estimate: ~10 minutes per function
-- Result: Zero violations, improved readability
+## Single Responsibility Principle (SRP) Linter
 
-See [Nesting Linter Guide](docs/nesting-linter.md) for comprehensive documentation and refactoring patterns.
+### Overview
+
+The SRP linter detects classes that violate the Single Responsibility Principle by having too many methods, too many lines of code, or generic naming patterns. It uses AST analysis with configurable heuristics to identify classes that likely handle multiple responsibilities.
+
+### Quick Start
+
+```bash
+# Check SRP violations in current directory
+thailint srp .
+
+# Use custom thresholds
+thailint srp --max-methods 10 --max-loc 300 src/
+
+# Get JSON output
+thailint srp --format json src/
+```
+
+### Configuration
+
+Add to `.thailint.yaml`:
+
+```yaml
+srp:
+  enabled: true
+  max_methods: 7    # Maximum methods per class
+  max_loc: 200      # Maximum lines of code per class
+
+  # Language-specific thresholds
+  python:
+    max_methods: 8
+    max_loc: 200
+
+  typescript:
+    max_methods: 10  # TypeScript more verbose
+    max_loc: 250
+```
+
+### Detection Heuristics
+
+The SRP linter uses three heuristics to detect violations:
+
+1. **Method Count**: Classes with >7 methods (default) likely have multiple responsibilities
+2. **Lines of Code**: Classes with >200 LOC (default) are often doing too much
+3. **Responsibility Keywords**: Names containing "Manager", "Handler", "Processor", etc.
+
+### Example Violation
+
+**Code with SRP violation:**
+```python
+class UserManager:  # 8 methods, contains "Manager" keyword
+    def create_user(self): pass
+    def update_user(self): pass
+    def delete_user(self): pass
+    def send_email(self): pass      # ← Different responsibility
+    def log_action(self): pass      # ← Different responsibility
+    def validate_data(self): pass   # ← Different responsibility
+    def generate_report(self): pass # ← Different responsibility
+    def export_data(self): pass     # ← Violation at method 8
+```
+
+**Refactored following SRP:**
+```python
+class UserRepository:  # 3 methods ✓
+    def create(self, user): pass
+    def update(self, user): pass
+    def delete(self, user): pass
+
+class EmailService:  # 1 method ✓
+    def send(self, user, template): pass
+
+class UserAuditLog:  # 1 method ✓
+    def log(self, action, user): pass
+
+class UserValidator:  # 1 method ✓
+    def validate(self, data): pass
+
+class ReportGenerator:  # 1 method ✓
+    def generate(self, users): pass
+```
+
+### Refactoring Patterns
+
+Common patterns to fix SRP violations (discovered during dogfooding):
+
+1. **Extract Class**
+   - Split god classes into focused classes
+   - Each class handles one responsibility
+
+2. **Split Configuration and Logic**
+   - Separate config loading from business logic
+   - Create dedicated ConfigLoader classes
+
+3. **Extract Language-Specific Logic**
+   - Separate Python/TypeScript analysis
+   - Use analyzer classes per language
+
+4. **Utility Module Pattern**
+   - Group related helper methods
+   - Create focused utility classes
+
+### Language Support
+
+- **Python**: Full support with method counting and LOC analysis
+- **TypeScript**: Full support with tree-sitter parsing
+- **JavaScript**: Supported via TypeScript parser
+
+### Real-World Example
+
+**Large class refactoring:**
+- **Before**: FilePlacementLinter (33 methods, 382 LOC) - single class handling config, patterns, validation
+- **After**: Extract Class pattern applied - 5 focused classes (ConfigLoader, PatternValidator, RuleChecker, PathResolver, FilePlacementLinter)
+- **Result**: Each class ≤8 methods, ≤150 LOC, single responsibility
+
+See [SRP Linter Guide](docs/srp-linter.md) for comprehensive documentation and refactoring patterns.
+
+## DRY Linter (Don't Repeat Yourself)
+
+### Overview
+
+The DRY linter detects duplicate code blocks across your entire project using token-based hashing with SQLite caching. It identifies identical or near-identical code that violates the Don't Repeat Yourself (DRY) principle, helping maintain code quality at scale.
+
+### Quick Start
+
+```bash
+# Check for duplicate code in current directory
+thailint dry .
+
+# Use custom thresholds
+thailint dry --min-lines 5 src/
+
+# Clear cache and re-scan
+thailint dry --clear-cache src/
+
+# Get JSON output
+thailint dry --format json src/
+```
+
+### Configuration
+
+Add to `.thailint.yaml`:
+
+```yaml
+dry:
+  enabled: true
+  min_duplicate_lines: 4         # Minimum lines to consider duplicate
+  min_duplicate_tokens: 30       # Minimum tokens to consider duplicate
+  min_occurrences: 2             # Report if appears 2+ times
+
+  # Language-specific thresholds
+  python:
+    min_occurrences: 3           # Python: require 3+ occurrences
+  typescript:
+    min_occurrences: 3           # TypeScript: require 3+ occurrences
+
+  # Cache settings (SQLite for fast incremental scans)
+  cache_enabled: true
+  cache_path: ".thailint-cache/dry.db"
+  cache_max_age_days: 30
+
+  # Ignore patterns
+  ignore:
+    - "tests/"           # Test code often has acceptable duplication
+    - "__init__.py"      # Import-only files exempt
+
+  # False positive filters
+  filters:
+    keyword_argument_filter: true   # Filter function call kwargs
+    import_group_filter: true       # Filter import groups
+```
+
+### How It Works
+
+**Token-Based Detection:**
+1. Parse code into tokens (stripping comments, normalizing whitespace)
+2. Create rolling hash windows of N lines
+3. Store hashes in SQLite database with file locations
+4. Query for hashes appearing 2+ times across project
+
+**SQLite Caching:**
+- First scan: Hash all files (~1-3s for 1000 files)
+- Subsequent scans: Load cached hashes for unchanged files (~0.1-0.5s)
+- 10-50x speedup for incremental scans
+- Mtime-based cache invalidation (automatic and safe)
+
+### Example Violation
+
+**Code with duplication:**
+```python
+# src/auth.py
+def validate_user(user_data):
+    if not user_data:
+        return False
+    if not user_data.get('email'):
+        return False
+    if not user_data.get('password'):
+        return False
+    return True
+
+# src/admin.py
+def validate_admin(admin_data):
+    if not admin_data:
+        return False
+    if not admin_data.get('email'):
+        return False
+    if not admin_data.get('password'):
+        return False
+    return True
+```
+
+**Violation message:**
+```
+src/auth.py:3 - Duplicate code detected (4 lines, 2 occurrences)
+  Locations:
+    - src/auth.py:3-6
+    - src/admin.py:3-6
+  Consider extracting to shared function
+```
+
+**Refactored (DRY):**
+```python
+# src/validators.py
+def validate_credentials(data):
+    if not data:
+        return False
+    if not data.get('email'):
+        return False
+    if not data.get('password'):
+        return False
+    return True
+
+# src/auth.py & src/admin.py
+from src.validators import validate_credentials
+
+def validate_user(user_data):
+    return validate_credentials(user_data)
+
+def validate_admin(admin_data):
+    return validate_credentials(admin_data)
+```
+
+### Cache Management
+
+```bash
+# Normal cached run (default)
+thailint dry src/
+
+# Force re-analysis (ignore cache)
+thailint dry --no-cache src/
+
+# Clear cache before running
+thailint dry --clear-cache src/
+
+# Manual cache cleanup
+rm -rf .thailint-cache/dry.db
+```
+
+### Performance
+
+| Operation | Performance | Cache Status |
+|-----------|-------------|--------------|
+| First scan (1000 files) | 1-3s | Cache write |
+| Unchanged files | 0.1-0.5s | Cache hit |
+| 50 changed files | 0.5-1s | Partial cache |
+
+**Speedup**: 3-10x for incremental scans with cache
+
+### Language Support
+
+- **Python**: Full support with AST-based tokenization
+- **TypeScript**: Full support with tree-sitter parsing
+- **JavaScript**: Supported via TypeScript parser
+
+### False Positive Filtering
+
+Built-in filters automatically exclude common non-duplication patterns:
+- **keyword_argument_filter**: Excludes function calls with keyword arguments
+- **import_group_filter**: Excludes import statement groups
+
+### Refactoring Patterns
+
+1. **Extract Function**: Move repeated logic to shared function
+2. **Extract Base Class**: Create base class for similar implementations
+3. **Extract Utility Module**: Move helper functions to shared utilities
+4. **Template Method**: Use function parameters for variations
+
+See [DRY Linter Guide](docs/dry-linter.md) for comprehensive documentation, cache management, and refactoring patterns.
 
 ## Pre-commit Hooks
 
@@ -335,13 +673,13 @@ pre-commit run --all-files
 ### What You Get
 
 **On every commit:**
-- 🚫 Prevents commits to main/master branch
-- 🎨 Auto-fixes formatting issues
-- ✅ Runs thailint on changed files (fast)
+- Prevents commits to main/master branch
+- Auto-fixes formatting issues
+- Runs thailint on changed files (fast, uses pass_filenames: true)
 
 **On every push:**
-- 🔍 Full linting on entire codebase
-- 🧪 Runs complete test suite
+- Full linting on entire codebase
+- Runs complete test suite
 
 ### Example Configuration
 
@@ -353,7 +691,7 @@ repos:
       # Prevent commits to protected branches
       - id: no-commit-to-main
         name: Prevent commits to main branch
-        entry: bash -c 'branch=$(git rev-parse --abbrev-ref HEAD); if [ "$branch" = "main" ]; then echo "❌ Use a feature branch!"; exit 1; fi'
+        entry: bash -c 'branch=$(git rev-parse --abbrev-ref HEAD); if [ "$branch" = "main" ]; then echo "ERROR: Use a feature branch!"; exit 1; fi'
         language: system
         pass_filenames: false
         always_run: true
@@ -361,16 +699,17 @@ repos:
       # Auto-format code
       - id: format
         name: Auto-fix formatting
-        entry: make format
+        entry: just format
         language: system
         pass_filenames: false
 
-      # Run thailint on changed files
-      - id: lint-changed
+      # Run thailint on changed files (passes filenames directly)
+      - id: thailint-changed
         name: Lint changed files
-        entry: make lint-full FILES=changed
+        entry: thailint nesting
         language: system
-        pass_filenames: false
+        files: \.(py|ts|tsx|js|jsx)$
+        pass_filenames: true
 ```
 
 See **[Pre-commit Hooks Guide](docs/pre-commit-hooks.md)** for complete documentation, troubleshooting, and advanced configuration.
@@ -478,31 +817,43 @@ docker pull washad/thailint:latest
 # Run CLI help
 docker run --rm washad/thailint:latest --help
 
-# Run file-placement linter
+# Lint entire directory (recommended)
 docker run --rm -v $(pwd):/data washad/thailint:latest file-placement /data
 
-# Run nesting linter
-docker run --rm -v $(pwd):/data washad/thailint:latest nesting /data
+# Lint single file
+docker run --rm -v $(pwd):/data washad/thailint:latest file-placement /data/src/app.py
+
+# Lint multiple specific files
+docker run --rm -v $(pwd):/data washad/thailint:latest nesting /data/src/file1.py /data/src/file2.py
+
+# Lint specific subdirectory
+docker run --rm -v $(pwd):/data washad/thailint:latest nesting /data/src
 
 # With custom config
 docker run --rm -v $(pwd):/data \
     washad/thailint:latest nesting --config /data/.thailint.yaml /data
+
+# JSON output for CI/CD
+docker run --rm -v $(pwd):/data \
+    washad/thailint:latest file-placement --format json /data
 ```
 
 ## Documentation
 
 ### Comprehensive Guides
 
-- 📖 **[Getting Started](docs/getting-started.md)** - Installation, first lint, basic config
-- ⚙️ **[Configuration Reference](docs/configuration.md)** - Complete config options (YAML/JSON)
-- 📚 **[API Reference](docs/api-reference.md)** - Library API documentation
-- 💻 **[CLI Reference](docs/cli-reference.md)** - All CLI commands and options
-- 🚀 **[Deployment Modes](docs/deployment-modes.md)** - CLI, Library, and Docker usage
-- 📁 **[File Placement Linter](docs/file-placement-linter.md)** - Detailed linter guide
-- 🔄 **[Nesting Depth Linter](docs/nesting-linter.md)** - Nesting depth analysis guide
-- 🪝 **[Pre-commit Hooks](docs/pre-commit-hooks.md)** - Automated quality checks
-- 📦 **[Publishing Guide](docs/releasing.md)** - Release and publishing workflow
-- ✅ **[Publishing Checklist](docs/publishing-checklist.md)** - Post-publication validation
+- **[Getting Started](docs/getting-started.md)** - Installation, first lint, basic config
+- **[Configuration Reference](docs/configuration.md)** - Complete config options (YAML/JSON)
+- **[API Reference](docs/api-reference.md)** - Library API documentation
+- **[CLI Reference](docs/cli-reference.md)** - All CLI commands and options
+- **[Deployment Modes](docs/deployment-modes.md)** - CLI, Library, and Docker usage
+- **[File Placement Linter](docs/file-placement-linter.md)** - Detailed linter guide
+- **[Nesting Depth Linter](docs/nesting-linter.md)** - Nesting depth analysis guide
+- **[SRP Linter](docs/srp-linter.md)** - Single Responsibility Principle guide
+- **[DRY Linter](docs/dry-linter.md)** - Duplicate code detection guide
+- **[Pre-commit Hooks](docs/pre-commit-hooks.md)** - Automated quality checks
+- **[Publishing Guide](docs/releasing.md)** - Release and publishing workflow
+- **[Publishing Checklist](docs/publishing-checklist.md)** - Post-publication validation
 
 ### Examples
 
@@ -578,10 +929,10 @@ thailint is designed for speed and efficiency:
 
 | Operation | Performance | Target |
 |-----------|-------------|--------|
-| Single file lint | ~20ms | <100ms ✅ |
-| 100 files | ~300ms | <1s ✅ |
-| 1000 files | ~900ms | <5s ✅ |
-| Config loading | ~10ms | <100ms ✅ |
+| Single file lint | ~20ms | <100ms |
+| 100 files | ~300ms | <1s |
+| 1000 files | ~900ms | <5s |
+| Config loading | ~10ms | <100ms |
 
 *Performance benchmarks run on standard hardware, your results may vary.*
 
@@ -596,9 +947,9 @@ thailint uses standard exit codes for CI/CD integration:
 ```bash
 thailint file-placement .
 if [ $? -eq 0 ]; then
-    echo "✅ Linting passed"
+    echo "Linting passed"
 else
-    echo "❌ Linting failed"
+    echo "Linting failed"
 fi
 ```