thailint 0.2.1__tar.gz → 0.3.1__tar.gz

{thailint-0.2.1 → thailint-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: thailint
-Version: 0.2.1
+Version: 0.3.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
@@ -48,6 +48,11 @@ thailint is a modern, enterprise-ready multi-language linter designed specifical
 
 ### Core Capabilities
 - **File Placement Linting** - Enforce project structure and organization
+- **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)
+  - Configurable allowed numbers and thresholds
+  - Helpful suggestions for extracting to named constants
 - **Nesting Depth Linting** - Detect excessive code nesting with AST analysis
   - Python and TypeScript support with tree-sitter
   - Configurable max depth (default: 4, recommended: 3)
@@ -57,8 +62,8 @@ thailint is a modern, enterprise-ready multi-language linter designed specifical
   - 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)
+  - Token-based hash detection with SQLite storage
+  - Fast duplicate detection (in-memory or disk-backed)
   - Configurable thresholds (lines, tokens, occurrences)
   - Language-specific detection (Python, TypeScript, JavaScript)
   - False positive filtering (keyword args, imports)
@@ -125,6 +130,9 @@ thailint nesting src/
 # Check for duplicate code
 thailint dry .
 
+# Check for magic numbers
+thailint magic-numbers src/
+
 # With config file
 thailint dry --config .thailint.yaml src/
 
@@ -228,14 +236,19 @@ dry:
   python:
     min_occurrences: 3           # Python: require 3+ occurrences
 
-  # Cache settings (SQLite)
-  cache_enabled: true
-  cache_path: ".thailint-cache/dry.db"
+  # Storage settings (SQLite)
+  storage_mode: "memory"         # Options: "memory" (default) or "tempfile"
 
   # Ignore patterns
   ignore:
     - "tests/"
     - "__init__.py"
+
+# Magic numbers linter configuration
+magic-numbers:
+  enabled: true
+  allowed_numbers: [-1, 0, 1, 2, 10, 100, 1000]  # Numbers allowed without constants
+  max_small_integer: 10  # Max value allowed in range() or enumerate()
 ```
 
 **JSON format also supported** (`.thailint.json`):
@@ -268,15 +281,21 @@ dry:
     "python": {
       "min_occurrences": 3
     },
-    "cache_enabled": true,
-    "cache_path": ".thailint-cache/dry.db",
+    "storage_mode": "memory",
     "ignore": ["tests/", "__init__.py"]
+  },
+  "magic-numbers": {
+    "enabled": true,
+    "allowed_numbers": [-1, 0, 1, 2, 10, 100, 1000],
+    "max_small_integer": 10
   }
 }
 ```
 
 See [Configuration Guide](docs/configuration.md) for complete reference.
 
+**Need help with ignores?** See **[How to Ignore Violations](docs/how-to-ignore-violations.md)** for complete guide to all ignore levels (line, method, class, file, repository).
+
 ## Nesting Depth Linter
 
 ### Overview
@@ -484,7 +503,7 @@ See [SRP Linter Guide](docs/srp-linter.md) for comprehensive documentation and r
 
 ### 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.
+The DRY linter detects duplicate code blocks across your entire project using token-based hashing with SQLite storage. It identifies identical or near-identical code that violates the Don't Repeat Yourself (DRY) principle, helping maintain code quality at scale.
 
 ### Quick Start
 
@@ -495,8 +514,8 @@ thailint dry .
 # Use custom thresholds
 thailint dry --min-lines 5 src/
 
-# Clear cache and re-scan
-thailint dry --clear-cache src/
+# Use tempfile storage for large projects
+thailint dry --storage-mode tempfile src/
 
 # Get JSON output
 thailint dry --format json src/
@@ -519,10 +538,8 @@ dry:
   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
+  # Storage settings
+  storage_mode: "memory"         # Options: "memory" (default) or "tempfile"
 
   # Ignore patterns
   ignore:
@@ -543,11 +560,11 @@ dry:
 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)
+**SQLite Storage:**
+- In-memory mode (default): Stores in RAM for best performance
+- Tempfile mode: Stores in temporary disk file for large projects
+- Fresh analysis on every run (no persistence between runs)
+- Fast duplicate detection using B-tree indexes
 
 ### Example Violation
 
@@ -605,31 +622,14 @@ 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 |
+| Operation | Performance | Storage Mode |
 |-----------|-------------|--------------|
-| First scan (1000 files) | 1-3s | Cache write |
-| Unchanged files | 0.1-0.5s | Cache hit |
-| 50 changed files | 0.5-1s | Partial cache |
+| Scan (1000 files) | 1-3s | Memory (default) |
+| Large project (5000+ files) | Use tempfile mode | Tempfile |
 
-**Speedup**: 3-10x for incremental scans with cache
+**Note**: Every run analyzes files fresh - no persistence between runs ensures accurate results
 
 ### Language Support
 
@@ -650,7 +650,159 @@ Built-in filters automatically exclude common non-duplication patterns:
 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.
+See [DRY Linter Guide](docs/dry-linter.md) for comprehensive documentation, storage modes, and refactoring patterns.
+
+## Magic Numbers Linter
+
+### Overview
+
+The magic numbers linter detects unnamed numeric literals (magic numbers) that should be extracted to named constants. It uses AST analysis to identify numeric literals that lack meaningful context.
+
+### What are Magic Numbers?
+
+**Magic numbers** are unnamed numeric literals in code without explanation:
+
+```python
+# Bad - Magic numbers
+timeout = 3600  # What is 3600?
+max_retries = 5  # Why 5?
+
+# Good - Named constants
+TIMEOUT_SECONDS = 3600
+MAX_RETRY_ATTEMPTS = 5
+```
+
+### Quick Start
+
+```bash
+# Check for magic numbers in current directory
+thailint magic-numbers .
+
+# Check specific directory
+thailint magic-numbers src/
+
+# Get JSON output
+thailint magic-numbers --format json src/
+```
+
+### Configuration
+
+Add to `.thailint.yaml`:
+
+```yaml
+magic-numbers:
+  enabled: true
+  allowed_numbers: [-1, 0, 1, 2, 10, 100, 1000]
+  max_small_integer: 10  # Max for range() to be acceptable
+```
+
+### Example Violation
+
+**Code with magic numbers:**
+```python
+def calculate_timeout():
+    return 3600  # Magic number - what is 3600?
+
+def process_items(items):
+    for i in range(100):  # Magic number - why 100?
+        items[i] *= 1.5  # Magic number - what is 1.5?
+```
+
+**Violation messages:**
+```
+src/example.py:2 - Magic number 3600 should be a named constant
+src/example.py:5 - Magic number 100 should be a named constant
+src/example.py:6 - Magic number 1.5 should be a named constant
+```
+
+**Refactored code:**
+```python
+TIMEOUT_SECONDS = 3600
+MAX_ITEMS = 100
+PRICE_MULTIPLIER = 1.5
+
+def calculate_timeout():
+    return TIMEOUT_SECONDS
+
+def process_items(items):
+    for i in range(MAX_ITEMS):
+        items[i] *= PRICE_MULTIPLIER
+```
+
+### Acceptable Contexts
+
+The linter **does not** flag numbers in these contexts:
+
+| Context | Example | Why Acceptable |
+|---------|---------|----------------|
+| Constants | `MAX_SIZE = 100` | UPPERCASE name provides context |
+| Small `range()` | `range(5)` | Small loop bounds are clear |
+| Test files | `test_*.py` | Test data can be literal |
+| Allowed numbers | `-1, 0, 1, 2, 10` | Common values are self-explanatory |
+
+### Refactoring Patterns
+
+**Pattern 1: Extract to Module Constants**
+```python
+# Before
+def connect():
+    timeout = 30
+    retries = 3
+
+# After
+DEFAULT_TIMEOUT_SECONDS = 30
+DEFAULT_MAX_RETRIES = 3
+
+def connect():
+    timeout = DEFAULT_TIMEOUT_SECONDS
+    retries = DEFAULT_MAX_RETRIES
+```
+
+**Pattern 2: Extract with Units in Name**
+```python
+# Before
+delay = 3600  # Is this seconds? Minutes?
+
+# After
+TASK_DELAY_SECONDS = 3600  # Clear unit
+
+delay = TASK_DELAY_SECONDS
+```
+
+**Pattern 3: Use Standard Library**
+```python
+# Before
+if status == 200:
+    return "success"
+
+# After
+from http import HTTPStatus
+
+if status == HTTPStatus.OK:
+    return "success"
+```
+
+### Language Support
+
+- **Python**: Full support (int, float, scientific notation)
+- **TypeScript**: Full support (int, float, scientific notation)
+- **JavaScript**: Supported via TypeScript parser
+
+### Ignoring Violations
+
+```python
+# Line-level ignore
+timeout = 3600  # thailint: ignore[magic-numbers] - Industry standard
+
+# Method-level ignore
+def get_ports():  # thailint: ignore[magic-numbers] - Standard ports
+    return {80: "HTTP", 443: "HTTPS"}
+
+# File-level ignore
+# thailint: ignore-file[magic-numbers]
+```
+
+See **[How to Ignore Violations](docs/how-to-ignore-violations.md)** and **[Magic Numbers Linter Guide](docs/magic-numbers-linter.md)** for complete documentation.
 
 ## Pre-commit Hooks
 
@@ -844,10 +996,12 @@ docker run --rm -v $(pwd):/data \
 
 - **[Getting Started](docs/getting-started.md)** - Installation, first lint, basic config
 - **[Configuration Reference](docs/configuration.md)** - Complete config options (YAML/JSON)
+- **[How to Ignore Violations](docs/how-to-ignore-violations.md)** - Complete guide to all ignore levels
 - **[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
+- **[Magic Numbers Linter](docs/magic-numbers-linter.md)** - Magic numbers detection 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

{thailint-0.2.1 → thailint-0.3.1}/README.md

@@ -15,6 +15,11 @@ thailint is a modern, enterprise-ready multi-language linter designed specifical
 
 ### Core Capabilities
 - **File Placement Linting** - Enforce project structure and organization
+- **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)
+  - Configurable allowed numbers and thresholds
+  - Helpful suggestions for extracting to named constants
 - **Nesting Depth Linting** - Detect excessive code nesting with AST analysis
   - Python and TypeScript support with tree-sitter
   - Configurable max depth (default: 4, recommended: 3)
@@ -24,8 +29,8 @@ thailint is a modern, enterprise-ready multi-language linter designed specifical
   - 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)
+  - Token-based hash detection with SQLite storage
+  - Fast duplicate detection (in-memory or disk-backed)
   - Configurable thresholds (lines, tokens, occurrences)
   - Language-specific detection (Python, TypeScript, JavaScript)
   - False positive filtering (keyword args, imports)
@@ -92,6 +97,9 @@ thailint nesting src/
 # Check for duplicate code
 thailint dry .
 
+# Check for magic numbers
+thailint magic-numbers src/
+
 # With config file
 thailint dry --config .thailint.yaml src/
 
@@ -195,14 +203,19 @@ dry:
   python:
     min_occurrences: 3           # Python: require 3+ occurrences
 
-  # Cache settings (SQLite)
-  cache_enabled: true
-  cache_path: ".thailint-cache/dry.db"
+  # Storage settings (SQLite)
+  storage_mode: "memory"         # Options: "memory" (default) or "tempfile"
 
   # Ignore patterns
   ignore:
     - "tests/"
     - "__init__.py"
+
+# Magic numbers linter configuration
+magic-numbers:
+  enabled: true
+  allowed_numbers: [-1, 0, 1, 2, 10, 100, 1000]  # Numbers allowed without constants
+  max_small_integer: 10  # Max value allowed in range() or enumerate()
 ```
 
 **JSON format also supported** (`.thailint.json`):
@@ -235,15 +248,21 @@ dry:
     "python": {
       "min_occurrences": 3
     },
-    "cache_enabled": true,
-    "cache_path": ".thailint-cache/dry.db",
+    "storage_mode": "memory",
     "ignore": ["tests/", "__init__.py"]
+  },
+  "magic-numbers": {
+    "enabled": true,
+    "allowed_numbers": [-1, 0, 1, 2, 10, 100, 1000],
+    "max_small_integer": 10
   }
 }
 ```
 
 See [Configuration Guide](docs/configuration.md) for complete reference.
 
+**Need help with ignores?** See **[How to Ignore Violations](docs/how-to-ignore-violations.md)** for complete guide to all ignore levels (line, method, class, file, repository).
+
 ## Nesting Depth Linter
 
 ### Overview
@@ -451,7 +470,7 @@ See [SRP Linter Guide](docs/srp-linter.md) for comprehensive documentation and r
 
 ### 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.
+The DRY linter detects duplicate code blocks across your entire project using token-based hashing with SQLite storage. It identifies identical or near-identical code that violates the Don't Repeat Yourself (DRY) principle, helping maintain code quality at scale.
 
 ### Quick Start
 
@@ -462,8 +481,8 @@ thailint dry .
 # Use custom thresholds
 thailint dry --min-lines 5 src/
 
-# Clear cache and re-scan
-thailint dry --clear-cache src/
+# Use tempfile storage for large projects
+thailint dry --storage-mode tempfile src/
 
 # Get JSON output
 thailint dry --format json src/
@@ -486,10 +505,8 @@ dry:
   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
+  # Storage settings
+  storage_mode: "memory"         # Options: "memory" (default) or "tempfile"
 
   # Ignore patterns
   ignore:
@@ -510,11 +527,11 @@ dry:
 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)
+**SQLite Storage:**
+- In-memory mode (default): Stores in RAM for best performance
+- Tempfile mode: Stores in temporary disk file for large projects
+- Fresh analysis on every run (no persistence between runs)
+- Fast duplicate detection using B-tree indexes
 
 ### Example Violation
 
@@ -572,31 +589,14 @@ 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 |
+| Operation | Performance | Storage Mode |
 |-----------|-------------|--------------|
-| First scan (1000 files) | 1-3s | Cache write |
-| Unchanged files | 0.1-0.5s | Cache hit |
-| 50 changed files | 0.5-1s | Partial cache |
+| Scan (1000 files) | 1-3s | Memory (default) |
+| Large project (5000+ files) | Use tempfile mode | Tempfile |
 
-**Speedup**: 3-10x for incremental scans with cache
+**Note**: Every run analyzes files fresh - no persistence between runs ensures accurate results
 
 ### Language Support
 
@@ -617,7 +617,159 @@ Built-in filters automatically exclude common non-duplication patterns:
 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.
+See [DRY Linter Guide](docs/dry-linter.md) for comprehensive documentation, storage modes, and refactoring patterns.
+
+## Magic Numbers Linter
+
+### Overview
+
+The magic numbers linter detects unnamed numeric literals (magic numbers) that should be extracted to named constants. It uses AST analysis to identify numeric literals that lack meaningful context.
+
+### What are Magic Numbers?
+
+**Magic numbers** are unnamed numeric literals in code without explanation:
+
+```python
+# Bad - Magic numbers
+timeout = 3600  # What is 3600?
+max_retries = 5  # Why 5?
+
+# Good - Named constants
+TIMEOUT_SECONDS = 3600
+MAX_RETRY_ATTEMPTS = 5
+```
+
+### Quick Start
+
+```bash
+# Check for magic numbers in current directory
+thailint magic-numbers .
+
+# Check specific directory
+thailint magic-numbers src/
+
+# Get JSON output
+thailint magic-numbers --format json src/
+```
+
+### Configuration
+
+Add to `.thailint.yaml`:
+
+```yaml
+magic-numbers:
+  enabled: true
+  allowed_numbers: [-1, 0, 1, 2, 10, 100, 1000]
+  max_small_integer: 10  # Max for range() to be acceptable
+```
+
+### Example Violation
+
+**Code with magic numbers:**
+```python
+def calculate_timeout():
+    return 3600  # Magic number - what is 3600?
+
+def process_items(items):
+    for i in range(100):  # Magic number - why 100?
+        items[i] *= 1.5  # Magic number - what is 1.5?
+```
+
+**Violation messages:**
+```
+src/example.py:2 - Magic number 3600 should be a named constant
+src/example.py:5 - Magic number 100 should be a named constant
+src/example.py:6 - Magic number 1.5 should be a named constant
+```
+
+**Refactored code:**
+```python
+TIMEOUT_SECONDS = 3600
+MAX_ITEMS = 100
+PRICE_MULTIPLIER = 1.5
+
+def calculate_timeout():
+    return TIMEOUT_SECONDS
+
+def process_items(items):
+    for i in range(MAX_ITEMS):
+        items[i] *= PRICE_MULTIPLIER
+```
+
+### Acceptable Contexts
+
+The linter **does not** flag numbers in these contexts:
+
+| Context | Example | Why Acceptable |
+|---------|---------|----------------|
+| Constants | `MAX_SIZE = 100` | UPPERCASE name provides context |
+| Small `range()` | `range(5)` | Small loop bounds are clear |
+| Test files | `test_*.py` | Test data can be literal |
+| Allowed numbers | `-1, 0, 1, 2, 10` | Common values are self-explanatory |
+
+### Refactoring Patterns
+
+**Pattern 1: Extract to Module Constants**
+```python
+# Before
+def connect():
+    timeout = 30
+    retries = 3
+
+# After
+DEFAULT_TIMEOUT_SECONDS = 30
+DEFAULT_MAX_RETRIES = 3
+
+def connect():
+    timeout = DEFAULT_TIMEOUT_SECONDS
+    retries = DEFAULT_MAX_RETRIES
+```
+
+**Pattern 2: Extract with Units in Name**
+```python
+# Before
+delay = 3600  # Is this seconds? Minutes?
+
+# After
+TASK_DELAY_SECONDS = 3600  # Clear unit
+
+delay = TASK_DELAY_SECONDS
+```
+
+**Pattern 3: Use Standard Library**
+```python
+# Before
+if status == 200:
+    return "success"
+
+# After
+from http import HTTPStatus
+
+if status == HTTPStatus.OK:
+    return "success"
+```
+
+### Language Support
+
+- **Python**: Full support (int, float, scientific notation)
+- **TypeScript**: Full support (int, float, scientific notation)
+- **JavaScript**: Supported via TypeScript parser
+
+### Ignoring Violations
+
+```python
+# Line-level ignore
+timeout = 3600  # thailint: ignore[magic-numbers] - Industry standard
+
+# Method-level ignore
+def get_ports():  # thailint: ignore[magic-numbers] - Standard ports
+    return {80: "HTTP", 443: "HTTPS"}
+
+# File-level ignore
+# thailint: ignore-file[magic-numbers]
+```
+
+See **[How to Ignore Violations](docs/how-to-ignore-violations.md)** and **[Magic Numbers Linter Guide](docs/magic-numbers-linter.md)** for complete documentation.
 
 ## Pre-commit Hooks
 
@@ -811,10 +963,12 @@ docker run --rm -v $(pwd):/data \
 
 - **[Getting Started](docs/getting-started.md)** - Installation, first lint, basic config
 - **[Configuration Reference](docs/configuration.md)** - Complete config options (YAML/JSON)
+- **[How to Ignore Violations](docs/how-to-ignore-violations.md)** - Complete guide to all ignore levels
 - **[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
+- **[Magic Numbers Linter](docs/magic-numbers-linter.md)** - Magic numbers detection 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