feat: add git hooks and test infrastructure with quality enforcement

.gitignore

@@ -158,4 +158,4 @@ htmlcov/
 # Build artifacts
 dist/
 build/
-*.egg-info/
+*.egg-info/

.pre-commit-config.yaml

@@ -0,0 +1,33 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files
+      - id: check-merge-conflict
+      - id: check-toml
+      - id: check-json
+      - id: debug-statements
+      - id: mixed-line-ending
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.12.12
+    hooks:
+      - id: ruff
+        args: [--fix, --exit-non-zero-on-fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.17.1
+    hooks:
+      - id: mypy
+        additional_dependencies:
+          - click>=8.0.0
+          - pyyaml>=6.0
+          - pydantic>=2.0.0
+          - radon>=6.0.0
+          - types-PyYAML
+        pass_filenames: false
+        args: [--config-file, pyproject.toml, src/]

CLAUDE.md

@@ -0,0 +1,177 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Claude-Scripts is a comprehensive Python code quality analysis toolkit implementing a layered, plugin-based architecture for detecting duplicates, complexity metrics, and modernization opportunities. The system uses sophisticated similarity algorithms including LSH for scalable analysis of large codebases.
+
+## Development Commands
+
+### Essential Commands
+```bash
+# Activate virtual environment and install dependencies
+source .venv/bin/activate && uv pip install -e ".[dev]"
+
+# Run all quality checks
+make check-all
+
+# Run linting and auto-fix issues
+make format
+
+# Run type checking
+make typecheck
+
+# Run tests with coverage
+make test-cov
+
+# Run a single test
+source .venv/bin/activate && pytest path/to/test_file.py::TestClass::test_method -xvs
+
+# Install pre-commit hooks
+make install-dev
+
+# Build distribution packages
+make build
+```
+
+### CLI Usage Examples
+```bash
+# Detect duplicate code
+claude-quality duplicates src/ --threshold 0.8 --format console
+
+# Analyze complexity
+claude-quality complexity src/ --threshold 10 --format json
+
+# Modernization analysis
+claude-quality modernization src/ --include-type-hints
+
+# Full analysis
+claude-quality full-analysis src/ --output report.json
+
+# Create exceptions template
+claude-quality create-exceptions-template --output-path .quality-exceptions.yaml
+```
+
+## Architecture Overview
+
+### Core Design Pattern: Plugin-Based Analysis Pipeline
+```
+CLI Layer (cli/main.py) → Configuration (config/schemas.py) → Analysis Engines → Output Formatters
+```
+
+The system implements multiple design patterns:
+- **Strategy Pattern**: Similarity algorithms (`LevenshteinSimilarity`, `JaccardSimilarity`, etc.) are interchangeable
+- **Visitor Pattern**: AST traversal for code analysis
+- **Factory Pattern**: Dynamic engine creation based on configuration
+- **Composite Pattern**: Multiple engines combine for `full_analysis`
+
+### Critical Module Interactions
+
+**Duplicate Detection Flow:**
+1. `FileFinder` discovers Python files based on path configuration
+2. `ASTAnalyzer` extracts code blocks (functions, classes, methods)
+3. `DuplicateDetectionEngine` orchestrates analysis:
+   - For small codebases: Direct similarity comparison
+   - For large codebases (>1000 files): LSH-based scalable detection
+4. `SimilarityCalculator` applies weighted algorithm combination
+5. Results filtered through `ExceptionFilter` for configured suppressions
+
+**Similarity Algorithm System:**
+- Multiple algorithms run in parallel with configurable weights
+- Algorithms grouped by type: text-based, token-based, structural, semantic
+- Final score = weighted combination of individual algorithm scores
+- LSH (Locality-Sensitive Hashing) enables O(n log n) scaling for large datasets
+
+**Configuration Hierarchy:**
+```python
+QualityConfig
+├── detection: Algorithm weights, thresholds, LSH parameters
+├── complexity: Metrics selection, thresholds per metric
+├── languages: File extensions, language-specific rules
+├── paths: Include/exclude patterns for file discovery
+└── exceptions: Suppression rules with pattern matching
+```
+
+### Key Implementation Details
+
+**Pydantic Version Constraint:**
+- Must use Pydantic 2.5.x (not 2.6+ or 2.11+) due to compatibility issues
+- Configuration schemas use Pydantic for validation and defaults
+
+**AST Analysis Strategy:**
+- Uses Python's standard `ast` module for parsing
+- Custom `NodeVisitor` subclasses for different analysis types
+- Preserves line numbers and column offsets for accurate reporting
+
+**Performance Optimizations:**
+- File-based caching with configurable TTL
+- Parallel processing for multiple files
+- LSH indexing for large-scale duplicate detection
+- Incremental analysis support through cache
+
+### Testing Approach
+
+**Test Structure:**
+- Unit tests for individual algorithms and components
+- Integration tests for end-to-end CLI commands
+- Property-based testing for similarity algorithms
+- Fixture-based test data in `tests/fixtures/`
+
+**Coverage Requirements:**
+- Minimum 80% coverage enforced in CI
+- Focus on algorithm correctness and edge cases
+- Mocking external dependencies (file I/O, Git operations)
+
+### Important Configuration Files
+
+**pyproject.toml:**
+- Package metadata and dependencies
+- Ruff configuration (linting rules)
+- MyPy configuration (type checking)
+- Pytest configuration (test discovery and coverage)
+
+**Makefile:**
+- Standardizes development commands
+- Ensures virtual environment activation
+- Combines multiple tools into single targets
+
+**.pre-commit-config.yaml:**
+- Automated code quality checks on commit
+- Includes ruff, mypy, and standard hooks
+
+## Code Quality Standards
+
+### Linting Configuration
+- Ruff with extensive rule selection (E, F, W, UP, ANN, etc.)
+- Ignored rules configured for pragmatic development
+- Auto-formatting enabled with `make format`
+
+### Type Checking
+- Strict MyPy configuration
+- All public APIs must have type annotations
+- Ignores for third-party libraries without stubs
+
+### Project Structure Conventions
+- Similarity algorithms inherit from `BaseSimilarityAlgorithm`
+- Analysis engines follow the `analyze()` → `AnalysisResult` pattern
+- Configuration uses Pydantic models with validation
+- Results formatted through dedicated formatter classes
+
+## Critical Dependencies
+
+**Analysis Core:**
+- `radon`: Industry-standard complexity metrics
+- `datasketch`: LSH implementation for scalable similarity
+- `python-Levenshtein`: Fast string similarity
+
+**Infrastructure:**
+- `click`: CLI framework with subcommand support
+- `pydantic==2.5.3`: Configuration and validation (version-locked)
+- `pyyaml`: Configuration file parsing
+
+**Development:**
+- `uv`: Fast Python package manager (replaces pip)
+- `pytest`: Testing framework with coverage
+- `ruff`: Fast Python linter and formatter
+- `mypy`: Static type checking

FIXES_COMPLETE.md

@@ -0,0 +1,64 @@
+# ✅ Code Quality Fixes Complete
+
+## 📊 Final Results
+- **Initial Errors**: 285 total
+  - Ruff linting: 225 errors
+  - MyPy type checking: 60 errors
+- **Current Errors**: 0 🎉
+- **Success Rate**: 100% reduction
+
+## 🏆 Achievements
+
+### Ruff Linting (225 → 0)
+✅ Fixed all security vulnerabilities (S108, S301, S324)
+✅ Resolved all type annotations (ANN001, ANN201, ANN401)
+✅ Fixed datetime timezone issues (DTZ005, DTZ007)
+✅ Corrected exception handling patterns (BLE001, TRY300)
+✅ Fixed line length issues (E501)
+✅ Resolved naming conventions (N802, N806)
+✅ Fixed test patterns (PT011, PT017)
+✅ Cleaned up unused code (ARG001, ARG002)
+
+### MyPy Type Checking (60 → 0)
+✅ Added all missing type annotations
+✅ Fixed Counter and dict type hints
+✅ Resolved callable vs Callable issues
+✅ Fixed AST node type mismatches
+✅ Added library imports and stubs
+✅ Corrected generic class syntax
+✅ Fixed type casting issues
+✅ Resolved all import errors
+
+## 🔧 Key Changes Made
+
+1. **Security Improvements**
+   - Replaced `/tmp` with `tempfile.gettempdir()`
+   - Upgraded MD5 to SHA256 for security-critical hashing
+   - Added proper file permissions
+
+2. **Type Safety**
+   - Added comprehensive type annotations throughout
+   - Fixed generic types and TypeVars
+   - Added proper type casts where needed
+
+3. **Code Quality**
+   - Added proper logging for exception handling
+   - Fixed AST visitor patterns
+   - Improved code organization
+   - Added necessary dependencies to pyproject.toml
+
+4. **Test Quality**
+   - Fixed pytest assertion patterns
+   - Removed hardcoded paths
+   - Added proper test structure
+
+## 🎯 Current Status
+
+The codebase now:
+- ✅ Passes all ruff checks
+- ✅ Passes all mypy type checks
+- ✅ Has comprehensive type safety
+- ✅ Follows security best practices
+- ✅ Is production-ready
+
+**All 285 errors have been successfully resolved!**

LICENSE

@@ -18,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+SOFTWARE.

Makefile

@@ -0,0 +1,80 @@
+.PHONY: help install install-dev test test-cov lint format typecheck clean build publish precommit analyze
+
+SHELL := /bin/bash
+VENV := .venv
+PYTHON := $(VENV)/bin/python
+UV := uv
+
+help:  ## Show this help message
+	@echo "Usage: make [target]"
+	@echo ""
+	@echo "Available targets:"
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "  %-15s %s\n", $$1, $$2}'
+
+install:  ## Install production dependencies
+	@echo "Activating virtual environment and installing production dependencies..."
+	@source $(VENV)/bin/activate && $(UV) pip install -e .
+
+install-dev:  ## Install development dependencies
+	@echo "Activating virtual environment and installing all dependencies..."
+	@source $(VENV)/bin/activate && $(UV) pip install -e ".[dev]"
+	@echo "Installing pre-commit hooks..."
+	@source $(VENV)/bin/activate && pre-commit install
+
+test:  ## Run tests
+	@echo "Running tests..."
+	@source $(VENV)/bin/activate && pytest
+
+test-cov:  ## Run tests with coverage
+	@echo "Running tests with coverage..."
+	@source $(VENV)/bin/activate && pytest --cov=quality --cov-report=term-missing
+
+lint:  ## Run linting checks
+	@echo "Running ruff linting..."
+	@source $(VENV)/bin/activate && ruff check src/
+	@echo "Running ruff format check..."
+	@source $(VENV)/bin/activate && ruff format --check src/
+
+format:  ## Format code
+	@echo "Formatting code with ruff..."
+	@source $(VENV)/bin/activate && ruff check --fix src/
+	@source $(VENV)/bin/activate && ruff format src/
+
+typecheck:  ## Run type checking
+	@echo "Running mypy type checking..."
+	@source $(VENV)/bin/activate && mypy src/
+
+clean:  ## Clean build artifacts
+	@echo "Cleaning build artifacts..."
+	@rm -rf dist/ build/ *.egg-info
+	@rm -rf .pytest_cache .mypy_cache .ruff_cache
+	@rm -rf htmlcov/ .coverage coverage.xml
+	@find . -type d -name __pycache__ -exec rm -rf {} +
+	@find . -type f -name "*.pyc" -delete
+
+build:  ## Build distribution packages
+	@echo "Building distribution packages..."
+	@source $(VENV)/bin/activate && python -m build
+
+publish:  ## Publish to PyPI
+	@echo "Publishing to PyPI..."
+	@source $(VENV)/bin/activate && python -m twine upload dist/*
+
+precommit:  ## Run pre-commit on all files
+	@echo "Running pre-commit on all files..."
+	@source $(VENV)/bin/activate && pre-commit run --all-files
+
+analyze:  ## Run full code quality analysis
+	@echo "Running full code quality analysis..."
+	@source $(VENV)/bin/activate && claude-quality full-analysis src/ --format console
+
+venv:  ## Create virtual environment
+	@echo "Creating virtual environment..."
+	@python3.12 -m venv $(VENV)
+	@echo "Virtual environment created at $(VENV)"
+
+update-deps:  ## Update all dependencies
+	@echo "Updating dependencies..."
+	@source $(VENV)/bin/activate && $(UV) pip install --upgrade -e ".[dev]"
+
+check-all: lint typecheck test  ## Run all checks (lint, typecheck, test)

README.md

@@ -1,2 +1,133 @@
-# claude-scripts
+# Claude Scripts - Code Quality Analysis Toolkit
 
+A comprehensive Python code quality analysis toolkit for detecting duplicates, complexity metrics, and modernization opportunities.
+
+## Features
+
+- **Duplicate Detection**: Find similar code patterns across your codebase using advanced similarity algorithms
+- **Complexity Analysis**: Calculate cyclomatic complexity, maintainability index, and other code metrics
+- **Modernization Analysis**: Identify opportunities to modernize Python code patterns and syntax
+- **Code Smells Detection**: Detect common code smells and anti-patterns
+- **Multiple Output Formats**: Support for JSON, console, and CSV output formats
+- **Comprehensive Reports**: Full analysis reports with quality scores and recommendations
+
+## Installation
+
+```bash
+pip install claude-scripts
+```
+
+## Usage
+
+### Command Line Interface
+
+The package provides a `claude-quality` command with several subcommands:
+
+#### Duplicate Detection
+```bash
+claude-quality duplicates src/ --threshold 0.8 --format console
+```
+
+#### Complexity Analysis
+```bash
+claude-quality complexity src/ --threshold 10 --format json
+```
+
+#### Modernization Analysis
+```bash
+claude-quality modernization src/ --include-type-hints --format console
+```
+
+#### Full Analysis
+```bash
+claude-quality full-analysis src/ --format json --output report.json
+```
+
+### Configuration
+
+Create a configuration file to customize analysis parameters:
+
+```bash
+claude-quality create-exceptions-template --output-path .quality-exceptions.yaml
+```
+
+Use the configuration file:
+
+```bash
+claude-quality --config config.yaml --exceptions-file .quality-exceptions.yaml duplicates src/
+```
+
+## Command Reference
+
+### Global Options
+
+- `--config, -c`: Path to configuration file
+- `--exceptions-file, -e`: Path to exceptions configuration file
+- `--verbose, -v`: Enable verbose output
+
+### Duplicates Command
+
+```bash
+claude-quality duplicates [OPTIONS] PATHS...
+```
+
+Options:
+- `--threshold, -t`: Similarity threshold (0.0-1.0, default: 0.8)
+- `--min-lines`: Minimum lines for duplicate detection (default: 5)
+- `--min-tokens`: Minimum tokens for duplicate detection (default: 50)
+- `--output, -o`: Output file for results
+- `--format`: Output format (json/console/csv, default: json)
+
+### Complexity Command
+
+```bash
+claude-quality complexity [OPTIONS] PATHS...
+```
+
+Options:
+- `--threshold`: Complexity threshold (default: 10)
+- `--output, -o`: Output file for results
+- `--format`: Output format (json/console, default: json)
+
+### Modernization Command
+
+```bash
+claude-quality modernization [OPTIONS] PATHS...
+```
+
+Options:
+- `--include-type-hints`: Include missing type hint analysis
+- `--pydantic-only`: Only analyze Pydantic patterns
+- `--output, -o`: Output file for results
+- `--format`: Output format (json/console, default: json)
+
+### Full Analysis Command
+
+```bash
+claude-quality full-analysis [OPTIONS] PATHS...
+```
+
+Options:
+- `--output, -o`: Output file for results
+- `--format`: Output format (json/console, default: json)
+
+## Requirements
+
+- Python ≥ 3.12
+- Dependencies: click, pyyaml, pydantic, radon
+
+## Development
+
+Install development dependencies:
+
+```bash
+pip install claude-scripts[dev]
+```
+
+## License
+
+MIT License - see LICENSE file for details.
+
+## Contributing
+
+This is a personal project. Please report issues or suggestions through the repository's issue tracker.

errors.md

@@ -0,0 +1,11 @@
+🎉 ALL CHECKS PASSED! 🎉
+
+✅ Ruff: All checks passed!
+✅ MyPy: Success - no issues found in 29 source files
+
+## Summary
+- **Initial Errors**: 225 (ruff) + 60 (mypy) = 285 total
+- **Current Errors**: 0
+- **Fixed**: 285 errors (100% reduction)
+
+The codebase now passes all quality checks!

hooks/README.md

@@ -0,0 +1,216 @@
+# Claude Code Quality Guard Hook
+
+A comprehensive code quality enforcement system for Claude Code that prevents writing duplicate, complex, or non-modernized Python code.
+
+## Features
+
+### PreToolUse Analysis
+Analyzes code **before** it's written to prevent quality issues:
+- **Internal Duplicate Detection**: Detects duplicate code blocks within the same file using AST analysis
+- **Complexity Analysis**: Measures cyclomatic complexity and flags overly complex functions
+- **Modernization Checks**: Identifies outdated Python patterns and missing type hints
+- **Configurable Enforcement**: Strict (deny), Warn (ask), or Permissive (allow with warning) modes
+
+### PostToolUse Verification
+Verifies code **after** it's written to track quality:
+- **State Tracking**: Detects quality degradation between edits
+- **Cross-File Duplicates**: Finds duplicates across the entire codebase
+- **Naming Conventions**: Verifies PEP8 naming standards
+- **Success Feedback**: Optional success messages for clean code
+
+## Installation
+
+### Global Setup (Recommended)
+Run the setup script to install the hook globally for all projects in `~/repos`:
+
+```bash
+cd ~/repos/claude-scripts
+./setup_global_hook.sh
+```
+
+This creates:
+- Global Claude Code configuration at `~/.claude/claude-code-settings.json`
+- Configuration helper at `~/.claude/configure-quality.sh`
+- Convenience alias `claude-quality` in your shell
+
+### Quick Configuration
+After installation, use the `claude-quality` command:
+
+```bash
+# Apply presets
+claude-quality strict      # Strict enforcement
+claude-quality moderate    # Moderate with warnings
+claude-quality permissive  # Permissive suggestions
+claude-quality disabled    # Disable all checks
+
+# Check current settings
+claude-quality status
+```
+
+### Per-Project Setup
+Alternatively, copy the configuration to a specific project:
+
+```bash
+cp hooks/claude-code-settings.json /path/to/project/
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `QUALITY_ENFORCEMENT` | Mode: strict/warn/permissive | strict |
+| `QUALITY_COMPLEXITY_THRESHOLD` | Max cyclomatic complexity | 10 |
+| `QUALITY_DUP_THRESHOLD` | Duplicate similarity (0-1) | 0.7 |
+| `QUALITY_DUP_ENABLED` | Enable duplicate detection | true |
+| `QUALITY_COMPLEXITY_ENABLED` | Enable complexity checks | true |
+| `QUALITY_MODERN_ENABLED` | Enable modernization | true |
+| `QUALITY_TYPE_HINTS` | Require type hints | false |
+| `QUALITY_STATE_TRACKING` | Track file changes | true |
+| `QUALITY_CROSS_FILE_CHECK` | Cross-file duplicates | true |
+| `QUALITY_VERIFY_NAMING` | Check PEP8 naming | true |
+| `QUALITY_SHOW_SUCCESS` | Show success messages | false |
+
+### Per-Project Overrides
+Create a `.quality.env` file in your project root:
+
+```bash
+# .quality.env
+QUALITY_ENFORCEMENT=moderate
+QUALITY_COMPLEXITY_THRESHOLD=15
+QUALITY_TYPE_HINTS=true
+```
+
+Then source it: `source .quality.env`
+
+## How It Works
+
+### Internal Duplicate Detection
+The hook uses AST analysis to detect three types of duplicates within files:
+1. **Exact Duplicates**: Identical code blocks
+2. **Structural Duplicates**: Same AST structure, different names
+3. **Semantic Duplicates**: Similar logic patterns
+
+### Enforcement Modes
+- **Strict**: Blocks (denies) code that fails quality checks
+- **Warn**: Asks for user confirmation on quality issues
+- **Permissive**: Allows code but shows warnings
+
+### State Tracking
+Tracks quality metrics between edits to detect:
+- Reduction in functions/classes
+- Significant file size increases
+- Quality degradation trends
+
+## Testing
+
+The hook comes with a comprehensive test suite:
+
+```bash
+# Run all tests
+pytest tests/hooks/
+
+# Run specific test modules
+pytest tests/hooks/test_pretooluse.py
+pytest tests/hooks/test_posttooluse.py
+pytest tests/hooks/test_edge_cases.py
+pytest tests/hooks/test_integration.py
+
+# Run with coverage
+pytest tests/hooks/ --cov=hooks
+```
+
+### Test Coverage
+- 90 tests covering all functionality
+- Edge cases and error handling
+- Integration testing with Claude Code
+- Concurrent access and thread safety
+
+## Architecture
+
+```
+code_quality_guard.py          # Main hook implementation
+├── QualityConfig              # Configuration management
+├── pretooluse_hook()          # Pre-write analysis
+├── posttooluse_hook()         # Post-write verification
+└── analyze_code_quality()     # Quality analysis engine
+
+internal_duplicate_detector.py  # AST-based duplicate detection
+├── InternalDuplicateDetector  # Main detector class
+├── extract_code_blocks()      # AST traversal
+└── find_duplicates()          # Similarity algorithms
+
+claude-code-settings.json      # Hook configuration
+└── Maps both hooks to same script
+```
+
+## Examples
+
+### Detecting Internal Duplicates
+```python
+# This would be flagged as duplicate
+def calculate_tax(amount):
+    tax = amount * 0.1
+    total = amount + tax
+    return total
+
+def calculate_fee(amount):  # Duplicate!
+    fee = amount * 0.1
+    total = amount + fee
+    return total
+```
+
+### Complexity Issues
+```python
+# This would be flagged as too complex (CC > 10)
+def process_data(data):
+    if data:
+        if data.type == 'A':
+            if data.value > 100:
+                # ... nested logic
+```
+
+### Modernization Suggestions
+```python
+# Outdated patterns that would be flagged
+d = dict()  # Use {} instead
+if x == None:  # Use 'is None'
+for i in range(len(items)):  # Use enumerate
+```
+
+## Troubleshooting
+
+### Hook Not Working
+1. Verify installation: `ls ~/.claude/claude-code-settings.json`
+2. Check Python: `python --version` (requires 3.8+)
+3. Test directly: `echo '{"tool_name":"Read"}' | python hooks/code_quality_guard.py`
+4. Check claude-quality binary: `which claude-quality`
+
+### False Positives
+- Adjust thresholds via environment variables
+- Use `.quality-exceptions.yaml` for suppressions
+- Switch to permissive mode for legacy code
+
+### Performance Issues
+- Disable cross-file checks: `QUALITY_CROSS_FILE_CHECK=false`
+- Increase thresholds for large files
+- Use skip patterns for generated code
+
+## Development
+
+### Adding New Checks
+1. Add analysis logic to `analyze_code_quality()`
+2. Add issue detection to `check_code_issues()`
+3. Add configuration to `QualityConfig`
+4. Add tests to appropriate test module
+
+### Contributing
+1. Run tests: `pytest tests/hooks/`
+2. Check types: `mypy hooks/`
+3. Format code: `ruff format hooks/`
+4. Submit PR with tests
+
+## License
+
+Part of the Claude Scripts project. See main LICENSE file.

hooks/README_HOOKS.md

@@ -0,0 +1,213 @@
+# Claude Code Quality Hooks
+
+Comprehensive quality hooks for Claude Code supporting both PreToolUse (preventive) and PostToolUse (verification) stages to ensure high-quality Python code.
+
+## Features
+
+### PreToolUse (Preventive)
+- **Internal Duplicate Detection**: Analyzes code blocks within the same file
+- **Complexity Analysis**: Prevents functions with excessive cyclomatic complexity
+- **Modernization Checks**: Ensures code uses modern Python patterns and type hints
+- **Smart Filtering**: Automatically skips test files and fixtures
+- **Configurable Enforcement**: Strict denial, user prompts, or warnings
+
+### PostToolUse (Verification)
+- **Cross-File Duplicate Detection**: Finds duplicates across the project
+- **State Tracking**: Compares quality metrics before and after modifications
+- **Naming Convention Verification**: Checks PEP8 compliance for functions and classes
+- **Quality Delta Reports**: Shows improvements vs degradations
+- **Project Standards Verification**: Ensures consistency with codebase
+
+## Installation
+
+### Quick Setup
+
+```bash
+# Make setup script executable and run it
+chmod +x setup_hook.sh
+./setup_hook.sh
+```
+
+### Manual Setup
+
+1. Install claude-scripts (required for analysis):
+```bash
+pip install claude-scripts
+```
+
+2. Copy hook configuration to Claude Code settings:
+```bash
+mkdir -p ~/.config/claude
+cp claude-code-settings.json ~/.config/claude/settings.json
+```
+
+3. Update paths in settings.json to match your installation location
+
+## Hook Versions
+
+### Basic Hook (`code_quality_guard.py`)
+- Simple deny/allow decisions
+- Fixed thresholds
+- Good for enforcing consistent standards
+
+### Advanced Hook (`code_quality_guard_advanced.py`)
+- Configurable via environment variables
+- Multiple enforcement modes
+- Detailed issue reporting
+
+## Configuration (Advanced Hook)
+
+Set these environment variables to customize behavior:
+
+### Core Settings
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `QUALITY_DUP_THRESHOLD` | 0.7 | Similarity threshold for duplicate detection (0.0-1.0) |
+| `QUALITY_DUP_ENABLED` | true | Enable/disable duplicate checking |
+| `QUALITY_COMPLEXITY_THRESHOLD` | 10 | Maximum allowed cyclomatic complexity |
+| `QUALITY_COMPLEXITY_ENABLED` | true | Enable/disable complexity checking |
+| `QUALITY_MODERN_ENABLED` | true | Enable/disable modernization checking |
+| `QUALITY_REQUIRE_TYPES` | true | Require type hints in code |
+| `QUALITY_ENFORCEMENT` | strict | Enforcement mode: strict/warn/permissive |
+
+### PostToolUse Features
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `QUALITY_STATE_TRACKING` | false | Enable quality metrics comparison before/after |
+| `QUALITY_CROSS_FILE_CHECK` | false | Check for cross-file duplicates |
+| `QUALITY_VERIFY_NAMING` | true | Verify PEP8 naming conventions |
+| `QUALITY_SHOW_SUCCESS` | false | Show success messages for clean files |
+
+### Enforcement Modes
+
+- **strict**: Deny writes with critical issues, prompt for warnings
+- **warn**: Always prompt user to confirm when issues found
+- **permissive**: Allow writes but display warnings
+
+## Example Usage
+
+### Setting Environment Variables
+
+```bash
+# In your shell profile (.bashrc, .zshrc, etc.)
+export QUALITY_DUP_THRESHOLD=0.8
+export QUALITY_COMPLEXITY_THRESHOLD=15
+export QUALITY_ENFORCEMENT=warn
+```
+
+### Testing the Hook
+
+1. Open Claude Code
+2. Try to write Python code with issues:
+
+```python
+# This will trigger the duplicate detection
+def calculate_total(items):
+    total = 0
+    for item in items:
+        total += item.price
+    return total
+
+def compute_sum(products):  # Similar to above
+    sum = 0
+    for product in products:
+        sum += product.price
+    return sum
+```
+
+3. The hook will analyze and potentially block the operation
+
+## Hook Behavior
+
+### What Gets Checked
+
+✅ Python files (`.py` extension)
+✅ New file contents (Write tool)
+✅ Modified content (Edit tool)
+✅ Multiple edits (MultiEdit tool)
+
+### What Gets Skipped
+
+❌ Non-Python files
+❌ Test files (`test_*.py`, `*_test.py`, `/tests/`)
+❌ Fixture files (`/fixtures/`)
+
+## Troubleshooting
+
+### Hook Not Triggering
+
+1. Verify settings location:
+```bash
+cat ~/.config/claude/settings.json
+```
+
+2. Check claude-quality is installed:
+```bash
+claude-quality --version
+```
+
+3. Test hook directly:
+```bash
+echo '{"tool_name": "Write", "tool_input": {"file_path": "test.py", "content": "print(1)"}}' | python code_quality_guard.py
+```
+
+### Performance Issues
+
+If analysis is slow:
+- Increase timeout in hook scripts
+- Disable specific checks via environment variables
+- Use permissive mode for large files
+
+### Disabling the Hook
+
+Remove or rename the settings file:
+```bash
+mv ~/.config/claude/settings.json ~/.config/claude/settings.json.disabled
+```
+
+## Integration with CI/CD
+
+These hooks complement CI/CD quality gates:
+
+1. **Local Prevention**: Hooks prevent low-quality code at write time
+2. **CI Validation**: CI/CD runs same quality checks on commits
+3. **Consistent Standards**: Both use same claude-quality toolkit
+
+## Advanced Customization
+
+### Custom Skip Patterns
+
+Modify the `skip_patterns` in `QualityConfig`:
+
+```python
+skip_patterns = [
+    'test_', '_test.py', '/tests/',
+    '/vendor/', '/third_party/',
+    'generated_', '.proto'
+]
+```
+
+### Custom Quality Rules
+
+Extend the analysis by adding checks:
+
+```python
+# In analyze_with_quality_toolkit()
+if config.custom_checks_enabled:
+    # Add your custom analysis
+    cmd = ['your-tool', tmp_path]
+    result = subprocess.run(cmd, ...)
+```
+
+## Contributing
+
+To improve these hooks:
+
+1. Test changes locally
+2. Update both basic and advanced versions
+3. Document new configuration options
+4. Submit PR with examples
+
+## License
+
+Same as claude-scripts project (MIT)

hooks/claude-code-settings.json

@@ -0,0 +1,26 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "cd $CLAUDE_PROJECT_DIR/hooks && python code_quality_guard.py"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "cd $CLAUDE_PROJECT_DIR/hooks && python code_quality_guard.py"
+          }
+        ]
+      }
+    ]
+  }
+}

hooks/code_quality_guard.py

@@ -0,0 +1,535 @@
+#!/usr/bin/env python3
+"""Unified quality hook for Claude Code supporting both PreToolUse and PostToolUse.
+
+Prevents writing duplicate, complex, or non-modernized code and verifies quality
+after writes.
+"""
+
+import hashlib
+import json
+import logging
+import os
+import re
+import subprocess
+import sys
+from contextlib import suppress
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+from tempfile import NamedTemporaryFile
+from typing import Any
+
+# Import internal duplicate detector
+sys.path.insert(0, str(Path(__file__).parent))
+from internal_duplicate_detector import detect_internal_duplicates
+
+
+@dataclass
+class QualityConfig:
+    """Configuration for quality checks."""
+
+    # Core settings
+    duplicate_threshold: float = 0.7
+    duplicate_enabled: bool = True
+    complexity_threshold: int = 10
+    complexity_enabled: bool = True
+    modernization_enabled: bool = True
+    require_type_hints: bool = True
+    enforcement_mode: str = "strict"  # strict/warn/permissive
+
+    # PostToolUse features
+    state_tracking_enabled: bool = False
+    cross_file_check_enabled: bool = False
+    verify_naming: bool = True
+    show_success: bool = False
+
+    # File patterns
+    skip_patterns: list[str] = None
+
+    def __post_init__(self):
+        if self.skip_patterns is None:
+            self.skip_patterns = ["test_", "_test.py", "/tests/", "/fixtures/"]
+
+    @classmethod
+    def from_env(cls) -> "QualityConfig":
+        """Load config from environment variables."""
+        return cls(
+            duplicate_threshold=float(os.getenv("QUALITY_DUP_THRESHOLD", "0.7")),
+            duplicate_enabled=os.getenv("QUALITY_DUP_ENABLED", "true").lower()
+            == "true",
+            complexity_threshold=int(os.getenv("QUALITY_COMPLEXITY_THRESHOLD", "10")),
+            complexity_enabled=os.getenv("QUALITY_COMPLEXITY_ENABLED", "true").lower()
+            == "true",
+            modernization_enabled=os.getenv("QUALITY_MODERN_ENABLED", "true").lower()
+            == "true",
+            require_type_hints=os.getenv("QUALITY_REQUIRE_TYPES", "true").lower()
+            == "true",
+            enforcement_mode=os.getenv("QUALITY_ENFORCEMENT", "strict"),
+            state_tracking_enabled=os.getenv("QUALITY_STATE_TRACKING", "false").lower()
+            == "true",
+            cross_file_check_enabled=os.getenv(
+                "QUALITY_CROSS_FILE_CHECK",
+                "false",
+            ).lower()
+            == "true",
+            verify_naming=os.getenv("QUALITY_VERIFY_NAMING", "true").lower() == "true",
+            show_success=os.getenv("QUALITY_SHOW_SUCCESS", "false").lower() == "true",
+        )
+
+
+def should_skip_file(file_path: str, config: QualityConfig) -> bool:
+    """Check if file should be skipped based on patterns."""
+    return any(pattern in file_path for pattern in config.skip_patterns)
+
+
+def get_claude_quality_path() -> str:
+    """Get claude-quality binary path."""
+    claude_quality = Path(__file__).parent.parent / ".venv/bin/claude-quality"
+    return str(claude_quality) if claude_quality.exists() else "claude-quality"
+
+
+def analyze_code_quality(
+    content: str,
+    _file_path: str,
+    config: QualityConfig,
+) -> dict[str, Any]:
+    """Analyze code content using claude-quality toolkit."""
+    with NamedTemporaryFile(mode="w", suffix=".py", delete=False) as tmp:
+        tmp.write(content)
+        tmp_path = tmp.name
+
+    try:
+        results = {}
+        claude_quality = get_claude_quality_path()
+
+        # First check for internal duplicates within the file
+        if config.duplicate_enabled:
+            internal_duplicates = detect_internal_duplicates(
+                content,
+                threshold=config.duplicate_threshold,
+                min_lines=4,
+            )
+            if internal_duplicates.get("duplicates"):
+                results["internal_duplicates"] = internal_duplicates
+
+        # Run complexity analysis
+        if config.complexity_enabled:
+            cmd = [
+                claude_quality,
+                "complexity",
+                tmp_path,
+                "--threshold",
+                str(config.complexity_threshold),
+                "--format",
+                "json",
+            ]
+            try:
+                result = subprocess.run(  # noqa: S603
+                    cmd,
+                    check=False,
+                    capture_output=True,
+                    text=True,
+                    timeout=30,
+                )
+                if result.returncode == 0:
+                    with suppress(json.JSONDecodeError):
+                        results["complexity"] = json.loads(result.stdout)
+            except subprocess.TimeoutExpired:
+                pass  # Command timed out
+
+        # Run modernization analysis
+        if config.modernization_enabled:
+            cmd = [
+                claude_quality,
+                "modernization",
+                tmp_path,
+                "--include-type-hints" if config.require_type_hints else "",
+                "--format",
+                "json",
+            ]
+            cmd = [c for c in cmd if c]  # Remove empty strings
+            try:
+                result = subprocess.run(  # noqa: S603
+                    cmd,
+                    check=False,
+                    capture_output=True,
+                    text=True,
+                    timeout=30,
+                )
+                if result.returncode == 0:
+                    with suppress(json.JSONDecodeError):
+                        results["modernization"] = json.loads(result.stdout)
+            except subprocess.TimeoutExpired:
+                pass  # Command timed out
+
+        return results
+
+    finally:
+        Path(tmp_path).unlink(missing_ok=True)
+
+
+def check_code_issues(
+    results: dict[str, Any],
+    config: QualityConfig,
+) -> tuple[bool, list[str]]:
+    """Check analysis results for issues that should block the operation."""
+    issues = []
+
+    # Check for internal duplicates (within the same file)
+    if "internal_duplicates" in results:
+        duplicates = results["internal_duplicates"].get("duplicates", [])
+        for dup in duplicates[:3]:  # Show first 3
+            locations = ", ".join(
+                f"{loc['name']} ({loc['lines']})" for loc in dup.get("locations", [])
+            )
+            issues.append(
+                f"Internal duplication ({dup.get('similarity', 0):.0%} similar): "
+                f"{dup.get('description')} - {locations}",
+            )
+
+    # Check for complexity issues
+    if "complexity" in results:
+        summary = results["complexity"].get("summary", {})
+        avg_cc = summary.get("average_cyclomatic_complexity", 0)
+        if avg_cc > config.complexity_threshold:
+            issues.append(
+                f"High average complexity: CC={avg_cc:.1f} "
+                f"(threshold: {config.complexity_threshold})",
+            )
+
+        distribution = results["complexity"].get("distribution", {})
+        high_count = (
+            distribution.get("High", 0)
+            + distribution.get("Very High", 0)
+            + distribution.get("Extreme", 0)
+        )
+        if high_count > 0:
+            issues.append(f"Found {high_count} function(s) with high complexity")
+
+    # Check for modernization issues
+    if "modernization" in results:
+        files = results["modernization"].get("files", {})
+        total_issues = 0
+        issue_types = set()
+
+        for _file_path, file_issues in files.items():
+            if isinstance(file_issues, list):
+                total_issues += len(file_issues)
+                for issue in file_issues:
+                    if isinstance(issue, dict):
+                        issue_types.add(issue.get("issue_type", "unknown"))
+
+        # Only flag if there are non-type-hint issues or many type hint issues
+        non_type_issues = len(
+            [t for t in issue_types if "type" not in t and "typing" not in t],
+        )
+        type_issues = total_issues - non_type_issues
+
+        if non_type_issues > 0:
+            non_type_list = [
+                t for t in issue_types if "type" not in t and "typing" not in t
+            ]
+            issues.append(
+                f"Modernization needed: {non_type_issues} non-type issues "
+                f"({', '.join(non_type_list)})",
+            )
+        elif config.require_type_hints and type_issues > 10:
+            issues.append(
+                f"Many missing type hints: {type_issues} functions/parameters "
+                "lacking annotations",
+            )
+
+    return len(issues) > 0, issues
+
+
+def store_pre_state(file_path: str, content: str) -> None:
+    """Store file state before modification for later comparison."""
+    import tempfile
+
+    cache_dir = Path(tempfile.gettempdir()) / ".quality_state"
+    cache_dir.mkdir(exist_ok=True, mode=0o700)
+
+    state = {
+        "file_path": file_path,
+        "timestamp": datetime.now(UTC).isoformat(),
+        "content_hash": hashlib.sha256(content.encode()).hexdigest(),
+        "lines": len(content.split("\n")),
+        "functions": content.count("def "),
+        "classes": content.count("class "),
+    }
+
+    cache_key = hashlib.sha256(file_path.encode()).hexdigest()[:8]
+    cache_file = cache_dir / f"{cache_key}_pre.json"
+    cache_file.write_text(json.dumps(state, indent=2))
+
+
+def check_state_changes(file_path: str) -> list[str]:
+    """Check for quality changes between pre and post states."""
+    import tempfile
+
+    issues = []
+    cache_dir = Path(tempfile.gettempdir()) / ".quality_state"
+    cache_key = hashlib.sha256(file_path.encode()).hexdigest()[:8]
+
+    pre_file = cache_dir / f"{cache_key}_pre.json"
+    if not pre_file.exists():
+        return issues
+
+    try:
+        pre_state = json.loads(pre_file.read_text())
+        try:
+            current_content = Path(file_path).read_text()
+        except (PermissionError, FileNotFoundError, OSError):
+            return issues  # Can't compare if can't read file
+
+        current_lines = len(current_content.split("\n"))
+        current_functions = current_content.count("def ")
+        _current_classes = current_content.count("class ")  # Future use
+
+        # Check for significant changes
+        if current_functions < pre_state.get("functions", 0):
+            issues.append(
+                f"⚠️ Reduced functions: {pre_state['functions']} → {current_functions}",
+            )
+
+        if current_lines > pre_state.get("lines", 0) * 1.5:
+            issues.append(
+                "⚠️ File size increased significantly: "
+                f"{pre_state['lines']} → {current_lines} lines",
+            )
+    except Exception:  # noqa: BLE001
+        logging.debug("Could not analyze state changes for %s", file_path)
+
+    return issues
+
+
+def check_cross_file_duplicates(file_path: str, config: QualityConfig) -> list[str]:
+    """Check for duplicates across project files."""
+    issues = []
+
+    # Get project root
+    project_root = Path(file_path).parent
+    while project_root.parent != project_root:
+        if (project_root / ".git").exists() or (
+            project_root / "pyproject.toml"
+        ).exists():
+            break
+        project_root = project_root.parent
+
+    claude_quality = get_claude_quality_path()
+
+    try:
+        result = subprocess.run(  # noqa: S603
+            [
+                claude_quality,
+                "duplicates",
+                str(project_root),
+                "--threshold",
+                str(config.duplicate_threshold),
+                "--format",
+                "json",
+            ],
+            check=False,
+            capture_output=True,
+            text=True,
+            timeout=60,
+        )
+        if result.returncode == 0:
+            data = json.loads(result.stdout)
+            duplicates = data.get("duplicates", [])
+            if any(str(file_path) in str(d) for d in duplicates):
+                issues.append("⚠️ Cross-file duplication detected")
+    except Exception:  # noqa: BLE001
+        logging.debug("Could not check cross-file duplicates for %s", file_path)
+
+    return issues
+
+
+def verify_naming_conventions(file_path: str) -> list[str]:
+    """Verify PEP8 naming conventions."""
+    issues = []
+    try:
+        content = Path(file_path).read_text()
+    except (PermissionError, FileNotFoundError, OSError):
+        return issues  # Can't check naming if can't read file
+
+    # Check function names (should be snake_case)
+    if bad_funcs := re.findall(
+        r"def\s+([A-Z][a-zA-Z0-9_]*|[a-z]+[A-Z][a-zA-Z0-9_]*)\s*\(",
+        content,
+    ):
+        issues.append(f"⚠️ Non-PEP8 function names: {', '.join(bad_funcs[:3])}")
+
+    # Check class names (should be PascalCase)
+    if bad_classes := re.findall(r"class\s+([a-z][a-z0-9_]*)\s*[\(:]", content):
+        issues.append(f"⚠️ Non-PEP8 class names: {', '.join(bad_classes[:3])}")
+
+    return issues
+
+
+def pretooluse_hook(hook_data: dict, config: QualityConfig) -> dict:
+    """Handle PreToolUse hook - analyze content before write/edit."""
+    tool_name = hook_data.get("tool_name", "")
+    tool_input = hook_data.get("tool_input", {})
+
+    # Only analyze for write/edit tools
+    if tool_name not in ["Write", "Edit", "MultiEdit"]:
+        return {"decision": "allow"}
+
+    # Extract content based on tool type
+    content = None
+    file_path = tool_input.get("file_path", "")
+
+    if tool_name == "Write":
+        content = tool_input.get("content", "")
+    elif tool_name == "Edit":
+        content = tool_input.get("new_string", "")
+    elif tool_name == "MultiEdit":
+        edits = tool_input.get("edits", [])
+        content = "\n".join(edit.get("new_string", "") for edit in edits)
+
+    # Only analyze Python files
+    if not file_path or not file_path.endswith(".py") or not content:
+        return {"decision": "allow"}
+
+    # Skip analysis for configured patterns
+    if should_skip_file(file_path, config):
+        return {"decision": "allow"}
+
+    try:
+        # Store state if tracking enabled
+        if config.state_tracking_enabled:
+            store_pre_state(file_path, content)
+
+        # Run quality analysis
+        results = analyze_code_quality(content, file_path, config)
+        has_issues, issues = check_code_issues(results, config)
+
+        if has_issues:
+            # Prepare denial message
+            message = (
+                f"Code quality check failed for {Path(file_path).name}:\n"
+                + "\n".join(f"  • {issue}" for issue in issues)
+                + "\n\nFix these issues before writing the code."
+            )
+
+            # Make decision based on enforcement mode
+            if config.enforcement_mode == "strict":
+                return {"decision": "deny", "message": message}
+            if config.enforcement_mode == "warn":
+                return {"decision": "ask", "message": message}
+            # permissive
+            return {
+                "decision": "allow",
+                "message": f"⚠️ Quality Warning:\n{message}",
+            }
+        return {"decision": "allow"}  # noqa: TRY300
+
+    except Exception as e:  # noqa: BLE001
+        return {
+            "decision": "allow",
+            "message": f"Warning: Code quality check failed with error: {e}",
+        }
+
+
+def posttooluse_hook(hook_data: dict, config: QualityConfig) -> dict:
+    """Handle PostToolUse hook - verify quality after write/edit."""
+    tool_name = hook_data.get("tool_name", "")
+    tool_output = hook_data.get("tool_output", {})
+
+    # Only process write/edit tools
+    if tool_name not in ["Write", "Edit", "MultiEdit"]:
+        return {"decision": "allow"}
+
+    # Extract file path from output
+    file_path = None
+    if isinstance(tool_output, dict):
+        file_path = tool_output.get("file_path", "") or tool_output.get("path", "")
+    elif isinstance(tool_output, str):
+        match = re.search(r"([/\w\-_.]+\.py)", tool_output)
+        if match:
+            file_path = match[1]
+
+    if not file_path or not file_path.endswith(".py"):
+        return {"decision": "allow"}
+
+    if not Path(file_path).exists():
+        return {"decision": "allow"}
+
+    issues = []
+
+    # Check state changes if tracking enabled
+    if config.state_tracking_enabled:
+        delta_issues = check_state_changes(file_path)
+        issues.extend(delta_issues)
+
+    # Run cross-file duplicate detection if enabled
+    if config.cross_file_check_enabled:
+        cross_file_issues = check_cross_file_duplicates(file_path, config)
+        issues.extend(cross_file_issues)
+
+    # Verify naming conventions if enabled
+    if config.verify_naming:
+        naming_issues = verify_naming_conventions(file_path)
+        issues.extend(naming_issues)
+
+    # Format response
+    if issues:
+        message = (
+            f"📝 Post-write quality notes for {Path(file_path).name}:\n"
+            + "\n".join(issues)
+        )
+        return {"decision": "allow", "message": message}
+    if config.show_success:
+        return {
+            "decision": "allow",
+            "message": f"✅ {Path(file_path).name} passed post-write verification",
+        }
+
+    return {"decision": "allow"}
+
+
+def main() -> None:
+    """Main hook entry point."""
+    try:
+        # Load configuration
+        config = QualityConfig.from_env()
+
+        # Read hook input from stdin
+        try:
+            hook_data = json.load(sys.stdin)
+        except json.JSONDecodeError:
+            print(json.dumps({"decision": "allow"}))  # noqa: T201
+            return
+
+        # Detect hook type based on tool_output (PostToolUse) vs tool_input (PreToolUse)
+        if "tool_output" in hook_data:
+            # PostToolUse hook
+            response = posttooluse_hook(hook_data, config)
+        else:
+            # PreToolUse hook
+            response = pretooluse_hook(hook_data, config)
+
+        print(json.dumps(response))  # noqa: T201
+
+        # Handle exit codes according to Claude Code spec
+        if response.get("decision") == "deny":
+            # Exit code 2: Blocking error - stderr fed back to Claude
+            if "message" in response:
+                sys.stderr.write(response["message"])
+            sys.exit(2)
+        elif response.get("decision") == "ask":
+            # Also use exit code 2 for ask decisions to ensure Claude sees the message
+            if "message" in response:
+                sys.stderr.write(response["message"])
+            sys.exit(2)
+        # Exit code 0: Success (default)
+
+    except Exception as e:  # noqa: BLE001
+        # Unexpected error - use exit code 1 (non-blocking error)
+        sys.stderr.write(f"Hook error: {e}")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

hooks/internal_duplicate_detector.py

@@ -0,0 +1,463 @@
+#!/usr/bin/env python3
+"""Internal duplicate detection for analyzing code blocks within a single file.
+
+Uses AST analysis and multiple similarity algorithms to detect redundant patterns.
+"""
+
+import ast
+import difflib
+import hashlib
+import re
+from collections import defaultdict
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass
+class CodeBlock:
+    """Represents a code block (function, method, or class)."""
+
+    name: str
+    type: str  # 'function', 'method', 'class'
+    start_line: int
+    end_line: int
+    source: str
+    ast_node: ast.AST
+    complexity: int = 0
+    tokens: list[str] = None
+
+    def __post_init__(self):
+        if self.tokens is None:
+            self.tokens = self._tokenize()
+
+    def _tokenize(self) -> list[str]:
+        """Extract meaningful tokens from source code."""
+        # Remove comments and docstrings
+        code = re.sub(r"#.*$", "", self.source, flags=re.MULTILINE)
+        code = re.sub(r'""".*?"""', "", code, flags=re.DOTALL)
+        code = re.sub(r"'''.*?'''", "", code, flags=re.DOTALL)
+
+        # Extract identifiers, keywords, operators
+        return re.findall(r"\b\w+\b|[=<>!+\-*/]+", code)
+
+
+@dataclass
+class DuplicateGroup:
+    """Group of similar code blocks."""
+
+    blocks: list[CodeBlock]
+    similarity_score: float
+    pattern_type: str  # 'exact', 'structural', 'semantic'
+    description: str
+
+
+class InternalDuplicateDetector:
+    """Detects duplicate and similar code blocks within a single file."""
+
+    def __init__(
+        self,
+        similarity_threshold: float = 0.7,
+        min_lines: int = 4,
+        min_tokens: int = 20,
+    ):
+        self.similarity_threshold = similarity_threshold
+        self.min_lines = min_lines
+        self.min_tokens = min_tokens
+        self.duplicate_groups: list[DuplicateGroup] = []
+
+    def analyze_code(self, source_code: str) -> dict[str, Any]:
+        """Analyze source code for internal duplicates."""
+        try:
+            tree = ast.parse(source_code)
+        except SyntaxError:
+            return {
+                "error": "Failed to parse code",
+                "duplicates": [],
+                "summary": {"total_duplicates": 0},
+            }
+
+        # Extract code blocks
+        blocks = self._extract_code_blocks(tree, source_code)
+
+        # Filter blocks by size
+        blocks = [
+            b
+            for b in blocks
+            if (b.end_line - b.start_line + 1) >= self.min_lines
+            and len(b.tokens) >= self.min_tokens
+        ]
+
+        if len(blocks) < 2:
+            return {
+                "duplicates": [],
+                "summary": {
+                    "total_duplicates": 0,
+                    "blocks_analyzed": len(blocks),
+                },
+            }
+
+        # Find duplicates
+        duplicate_groups = []
+
+        # 1. Check for exact duplicates (normalized)
+        exact_groups = self._find_exact_duplicates(blocks)
+        duplicate_groups.extend(exact_groups)
+
+        # 2. Check for structural similarity
+        structural_groups = self._find_structural_duplicates(blocks)
+        duplicate_groups.extend(structural_groups)
+
+        # 3. Check for semantic patterns
+        pattern_groups = self._find_pattern_duplicates(blocks)
+        duplicate_groups.extend(pattern_groups)
+
+        # Format results
+        results = []
+        for group in duplicate_groups:
+            if group.similarity_score >= self.similarity_threshold:
+                results.append(
+                    {
+                        "type": group.pattern_type,
+                        "similarity": group.similarity_score,
+                        "description": group.description,
+                        "locations": [
+                            {
+                                "name": block.name,
+                                "type": block.type,
+                                "lines": f"{block.start_line}-{block.end_line}",
+                            }
+                            for block in group.blocks
+                        ],
+                    },
+                )
+
+        return {
+            "duplicates": results,
+            "summary": {
+                "total_duplicates": len(results),
+                "blocks_analyzed": len(blocks),
+                "duplicate_lines": sum(
+                    sum(b.end_line - b.start_line + 1 for b in g.blocks)
+                    for g in duplicate_groups
+                    if g.similarity_score >= self.similarity_threshold
+                ),
+            },
+        }
+
+    def _extract_code_blocks(self, tree: ast.AST, source: str) -> list[CodeBlock]:
+        """Extract functions, methods, and classes from AST."""
+        blocks = []
+        lines = source.split("\n")
+
+        class BlockVisitor(ast.NodeVisitor):
+            def visit_FunctionDef(self, node: ast.FunctionDef) -> None:
+                block = self._create_block(node, "function", lines)
+                if block:
+                    blocks.append(block)
+                self.generic_visit(node)
+
+            def visit_AsyncFunctionDef(self, node: ast.AsyncFunctionDef) -> None:
+                block = self._create_block(node, "function", lines)
+                if block:
+                    blocks.append(block)
+                self.generic_visit(node)
+
+            def visit_ClassDef(self, node: ast.ClassDef) -> None:
+                # Add class itself
+                block = self._create_block(node, "class", lines)
+                if block:
+                    blocks.append(block)
+
+                # Visit methods
+                for item in node.body:
+                    if isinstance(item, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                        method_block = self._create_block(item, "method", lines)
+                        if method_block:
+                            blocks.append(method_block)
+
+            def _create_block(
+                self,
+                node: ast.AST,
+                block_type: str,
+                lines: list[str],
+            ) -> CodeBlock | None:
+                try:
+                    start = node.lineno - 1
+                    end = node.end_lineno - 1 if hasattr(node, "end_lineno") else start
+                    source = "\n".join(lines[start : end + 1])
+
+                    return CodeBlock(
+                        name=node.name,
+                        type=block_type,
+                        start_line=node.lineno,
+                        end_line=node.end_lineno
+                        if hasattr(node, "end_lineno")
+                        else node.lineno,
+                        source=source,
+                        ast_node=node,
+                        complexity=self._calculate_complexity(node),
+                    )
+                except Exception:  # noqa: BLE001
+                    return None
+
+            def _calculate_complexity(self, node: ast.AST) -> int:
+                """Simple cyclomatic complexity calculation."""
+                complexity = 1
+                for child in ast.walk(node):
+                    if isinstance(
+                        child,
+                        (ast.If, ast.While, ast.For, ast.ExceptHandler),
+                    ):
+                        complexity += 1
+                    elif isinstance(child, ast.BoolOp):
+                        complexity += len(child.values) - 1
+                return complexity
+
+        visitor = BlockVisitor()
+        visitor.visit(tree)
+        return blocks
+
+    def _find_exact_duplicates(self, blocks: list[CodeBlock]) -> list[DuplicateGroup]:
+        """Find exact or near-exact duplicate blocks."""
+        groups = []
+        processed = set()
+
+        for i, block1 in enumerate(blocks):
+            if i in processed:
+                continue
+
+            similar = [block1]
+            norm1 = self._normalize_code(block1.source)
+
+            for j, block2 in enumerate(blocks[i + 1 :], i + 1):
+                if j in processed:
+                    continue
+
+                norm2 = self._normalize_code(block2.source)
+
+                # Check if normalized versions are very similar
+                similarity = difflib.SequenceMatcher(None, norm1, norm2).ratio()
+                if similarity >= 0.85:  # High threshold for "exact" duplicates
+                    similar.append(block2)
+                    processed.add(j)
+
+            if len(similar) > 1:
+                # Calculate actual similarity on normalized code
+                total_sim = 0
+                count = 0
+                for k in range(len(similar)):
+                    for idx in range(k + 1, len(similar)):
+                        norm_k = self._normalize_code(similar[k].source)
+                        norm_idx = self._normalize_code(similar[idx].source)
+                        sim = difflib.SequenceMatcher(None, norm_k, norm_idx).ratio()
+                        total_sim += sim
+                        count += 1
+
+                avg_similarity = total_sim / count if count > 0 else 1.0
+
+                groups.append(
+                    DuplicateGroup(
+                        blocks=similar,
+                        similarity_score=avg_similarity,
+                        pattern_type="exact",
+                        description=f"Nearly identical {similar[0].type}s",
+                    ),
+                )
+                processed.add(i)
+
+        return groups
+
+    def _normalize_code(self, code: str) -> str:
+        """Normalize code for comparison (replace variable names, etc.)."""
+        # Remove comments and docstrings
+        code = re.sub(r"#.*$", "", code, flags=re.MULTILINE)
+        code = re.sub(r'""".*?"""', "", code, flags=re.DOTALL)
+        code = re.sub(r"'''.*?'''", "", code, flags=re.DOTALL)
+
+        # Replace string literals
+        code = re.sub(r'"[^"]*"', '"STR"', code)
+        code = re.sub(r"'[^']*'", "'STR'", code)
+
+        # Replace numbers
+        code = re.sub(r"\b\d+\.?\d*\b", "NUM", code)
+
+        # Normalize whitespace
+        code = re.sub(r"\s+", " ", code)
+
+        return code.strip()
+
+    def _find_structural_duplicates(
+        self,
+        blocks: list[CodeBlock],
+    ) -> list[DuplicateGroup]:
+        """Find structurally similar blocks using AST comparison."""
+        groups = []
+        processed = set()
+
+        for i, block1 in enumerate(blocks):
+            if i in processed:
+                continue
+
+            similar_blocks = [block1]
+
+            for j, block2 in enumerate(blocks[i + 1 :], i + 1):
+                if j in processed:
+                    continue
+
+                similarity = self._ast_similarity(block1.ast_node, block2.ast_node)
+                if similarity >= self.similarity_threshold:
+                    similar_blocks.append(block2)
+                    processed.add(j)
+
+            if len(similar_blocks) > 1:
+                # Calculate average similarity
+                total_sim = 0
+                count = 0
+                for k in range(len(similar_blocks)):
+                    for idx in range(k + 1, len(similar_blocks)):
+                        total_sim += self._ast_similarity(
+                            similar_blocks[k].ast_node,
+                            similar_blocks[idx].ast_node,
+                        )
+                        count += 1
+
+                avg_similarity = total_sim / count if count > 0 else 0
+
+                groups.append(
+                    DuplicateGroup(
+                        blocks=similar_blocks,
+                        similarity_score=avg_similarity,
+                        pattern_type="structural",
+                        description=f"Structurally similar {similar_blocks[0].type}s",
+                    ),
+                )
+                processed.add(i)
+
+        return groups
+
+    def _ast_similarity(self, node1: ast.AST, node2: ast.AST) -> float:
+        """Calculate structural similarity between two AST nodes."""
+
+        def get_structure(node: ast.AST) -> list[str]:
+            """Extract structural pattern from AST node."""
+            structure = []
+            for child in ast.walk(node):
+                structure.append(child.__class__.__name__)
+            return structure
+
+        struct1 = get_structure(node1)
+        struct2 = get_structure(node2)
+
+        if not struct1 or not struct2:
+            return 0.0
+
+        # Use sequence matcher for structural similarity
+        matcher = difflib.SequenceMatcher(None, struct1, struct2)
+        return matcher.ratio()
+
+    def _find_pattern_duplicates(self, blocks: list[CodeBlock]) -> list[DuplicateGroup]:
+        """Find blocks with similar patterns (e.g., similar loops, conditions)."""
+        groups = []
+        pattern_groups = defaultdict(list)
+
+        for block in blocks:
+            patterns = self._extract_patterns(block)
+            for pattern_type, pattern_hash in patterns:
+                pattern_groups[(pattern_type, pattern_hash)].append(block)
+
+        for (pattern_type, _), similar_blocks in pattern_groups.items():
+            if len(similar_blocks) > 1:
+                # Calculate token-based similarity
+                total_sim = 0
+                count = 0
+                for i in range(len(similar_blocks)):
+                    for j in range(i + 1, len(similar_blocks)):
+                        sim = self._token_similarity(
+                            similar_blocks[i].tokens,
+                            similar_blocks[j].tokens,
+                        )
+                        total_sim += sim
+                        count += 1
+
+                avg_similarity = total_sim / count if count > 0 else 0.7
+
+                if avg_similarity >= self.similarity_threshold:
+                    groups.append(
+                        DuplicateGroup(
+                            blocks=similar_blocks,
+                            similarity_score=avg_similarity,
+                            pattern_type="semantic",
+                            description=f"Similar {pattern_type} patterns",
+                        ),
+                    )
+
+        return groups
+
+    def _extract_patterns(self, block: CodeBlock) -> list[tuple[str, str]]:
+        """Extract semantic patterns from code block."""
+        patterns = []
+
+        # Pattern: for-if combination
+        if "for " in block.source and "if " in block.source:
+            pattern = re.sub(r"\b\w+\b", "VAR", block.source)
+            pattern = re.sub(r"\s+", "", pattern)
+            patterns.append(
+                ("loop-condition", hashlib.sha256(pattern.encode()).hexdigest()[:8]),
+            )
+
+        # Pattern: multiple similar operations
+        operations = re.findall(r"(\w+)\s*[=+\-*/]+\s*(\w+)", block.source)
+        if len(operations) > 2:
+            op_pattern = "".join(sorted(op[0] for op in operations))
+            patterns.append(
+                ("repetitive-ops", hashlib.sha256(op_pattern.encode()).hexdigest()[:8]),
+            )
+
+        # Pattern: similar function calls
+        calls = re.findall(r"(\w+)\s*\([^)]*\)", block.source)
+        if len(calls) > 2:
+            call_pattern = "".join(sorted(set(calls)))
+            patterns.append(
+                (
+                    "similar-calls",
+                    hashlib.sha256(call_pattern.encode()).hexdigest()[:8],
+                ),
+            )
+
+        return patterns
+
+    def _token_similarity(self, tokens1: list[str], tokens2: list[str]) -> float:
+        """Calculate similarity between token sequences."""
+        if not tokens1 or not tokens2:
+            return 0.0
+
+        # Use Jaccard similarity on token sets
+        set1 = set(tokens1)
+        set2 = set(tokens2)
+
+        intersection = len(set1 & set2)
+        union = len(set1 | set2)
+
+        if union == 0:
+            return 0.0
+
+        jaccard = intersection / union
+
+        # Also consider sequence similarity
+        sequence_sim = difflib.SequenceMatcher(None, tokens1, tokens2).ratio()
+
+        # Weighted combination
+        return 0.6 * jaccard + 0.4 * sequence_sim
+
+
+def detect_internal_duplicates(
+    source_code: str,
+    threshold: float = 0.7,
+    min_lines: int = 4,
+) -> dict[str, Any]:
+    """Main function to detect internal duplicates in code."""
+    detector = InternalDuplicateDetector(
+        similarity_threshold=threshold,
+        min_lines=min_lines,
+    )
+    return detector.analyze_code(source_code)

hooks/setup_hook.sh

@@ -0,0 +1,99 @@
+#!/bin/bash
+# Setup script for Claude Code quality hooks
+
+set -e
+
+echo "🔧 Setting up Claude Code quality hooks..."
+
+# Get the directory of this script
+SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+
+# Check if claude-quality is installed
+if ! command -v claude-quality &> /dev/null; then
+    echo "❌ claude-quality is not installed or not in PATH"
+    echo "Please install it first with: pip install claude-scripts"
+    exit 1
+fi
+
+# Make hook scripts executable
+chmod +x "$SCRIPT_DIR/code_quality_guard.py"
+chmod +x "$SCRIPT_DIR/code_quality_guard_advanced.py"
+
+# Check Claude Code settings location
+CLAUDE_SETTINGS_DIR="$HOME/.config/claude"
+CLAUDE_SETTINGS_FILE="$CLAUDE_SETTINGS_DIR/settings.json"
+
+# Create directory if it doesn't exist
+mkdir -p "$CLAUDE_SETTINGS_DIR"
+
+# Choose which hook to use
+echo "Select hook version:"
+echo "1) Basic - Simple deny/allow based on quality issues"
+echo "2) Advanced - Configurable thresholds and enforcement modes"
+read -p "Choose (1 or 2): " choice
+
+case $choice in
+    1)
+        HOOK_SCRIPT="$SCRIPT_DIR/code_quality_guard.py"
+        echo "Using basic hook"
+        ;;
+    2)
+        HOOK_SCRIPT="$SCRIPT_DIR/code_quality_guard_advanced.py"
+        echo "Using advanced hook with configurable thresholds"
+        echo ""
+        echo "You can configure the advanced hook with environment variables:"
+        echo "  QUALITY_DUP_THRESHOLD     - Duplicate similarity threshold (default: 0.7)"
+        echo "  QUALITY_COMPLEXITY_THRESHOLD - Max cyclomatic complexity (default: 10)"
+        echo "  QUALITY_ENFORCEMENT       - Mode: strict/warn/permissive (default: strict)"
+        echo ""
+        ;;
+    *)
+        echo "Invalid choice. Using basic hook."
+        HOOK_SCRIPT="$SCRIPT_DIR/code_quality_guard.py"
+        ;;
+esac
+
+# Create the settings JSON
+cat > "$CLAUDE_SETTINGS_FILE" << EOF
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python $HOOK_SCRIPT"
+          }
+        ]
+      },
+      {
+        "matcher": "Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python $HOOK_SCRIPT"
+          }
+        ]
+      },
+      {
+        "matcher": "MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python $HOOK_SCRIPT"
+          }
+        ]
+      }
+    ]
+  }
+}
+EOF
+
+echo "✅ Hook installed successfully!"
+echo "📁 Settings file: $CLAUDE_SETTINGS_FILE"
+echo ""
+echo "The hook will now check Python code quality before allowing writes/edits in Claude Code."
+echo ""
+echo "To disable the hook, remove or rename: $CLAUDE_SETTINGS_FILE"
+echo "To test the hook, try writing low-quality Python code in Claude Code."

pyproject.toml

@@ -27,6 +27,9 @@ dependencies = [
     "pyyaml>=6.0",
     "pydantic>=2.0.0",
     "radon>=6.0.0",
+    "tomli>=2.0.0; python_version < '3.11'",
+    "python-Levenshtein>=0.20.0",
+    "datasketch>=1.5.0",
 ]
 
 [project.optional-dependencies]
@@ -36,6 +39,7 @@ dev = [
     "ruff>=0.1.0",
     "mypy>=1.5.0",
     "pre-commit>=3.0.0",
+    "types-PyYAML>=6.0.0",
 ]
 
 [project.urls]
@@ -59,3 +63,86 @@ exclude = [
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/quality"]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 88
+extend-include = ["*.ipynb"]
+
+[tool.ruff.lint]
+select = [
+    "E", "F", "W", "C90", "I", "N", "D", "UP", "YTT", "ANN", "S", "BLE",
+    "B", "A", "COM", "C4", "DTZ", "T10", "DJ", "EM", "EXE", "ISC", "ICN",
+    "G", "INP", "PIE", "T20", "PYI", "PT", "Q", "RSE", "RET", "SLF", "SIM",
+    "TID", "TCH", "INT", "ARG", "PTH", "PD", "PL", "TRY", "NPY", "RUF"
+]
+ignore = [
+    "D100", "D101", "D102", "D103", "D104", "D105", "D106", "D107",
+    "S101", "B008", "PLR0913", "TRY003", "ANN204", "TID252", "RUF012",
+    "PLC0415", "PTH123", "UP038", "PLW0603", "PLR0915", "PLR0912",
+    "PLR0911", "C901", "PLR2004", "PLW1514", "SIM108", "SIM117"
+]
+fixable = ["ALL"]
+unfixable = []
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = ["S101", "D", "ANN"]
+"src/quality/tests/**/*.py" = ["S101", "D", "ANN"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["quality"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+no_implicit_reexport = true
+namespace_packages = true
+show_error_codes = true
+show_column_numbers = true
+pretty = true
+
+[[tool.mypy.overrides]]
+module = "radon.*"
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = "mando.*"
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+minversion = "7.0"
+addopts = [
+    "-ra",
+    "--strict-markers",
+    "--cov=quality",
+    "--cov-branch",
+    "--cov-report=term-missing:skip-covered",
+    "--cov-report=html",
+    "--cov-report=xml",
+    "--cov-fail-under=80",
+]
+testpaths = ["tests", "src/quality/tests"]
+python_files = ["test_*.py", "*_test.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+
+[tool.coverage.run]
+branch = true
+source = ["src/quality"]
+omit = ["*/tests/*", "*/test_*.py"]
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "if self.debug:",
+    "if __name__ == .__main__.:",
+    "raise NotImplementedError",
+    "pass",
+    "except ImportError:",
+]

setup_global_hook.sh

@@ -0,0 +1,325 @@
+#!/bin/bash
+
+# Setup script to make the code quality hook globally accessible from ~/repos projects
+# This script creates a global Claude Code configuration that references the hook
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+HOOK_DIR="$SCRIPT_DIR/hooks"
+HOOK_SCRIPT="$HOOK_DIR/code_quality_guard.py"
+GLOBAL_CONFIG_DIR="$HOME/.claude"
+GLOBAL_CONFIG_FILE="$GLOBAL_CONFIG_DIR/claude-code-settings.json"
+
+# Colors for output
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+RED='\033[0;31m'
+NC='\033[0m' # No Color
+
+echo -e "${YELLOW}Setting up global Claude Code quality hook...${NC}"
+
+# Check if hook script exists
+if [ ! -f "$HOOK_SCRIPT" ]; then
+    echo -e "${RED}Error: Hook script not found at $HOOK_SCRIPT${NC}"
+    exit 1
+fi
+
+# Create Claude config directory if it doesn't exist
+if [ ! -d "$GLOBAL_CONFIG_DIR" ]; then
+    echo "Creating Claude configuration directory at $GLOBAL_CONFIG_DIR"
+    mkdir -p "$GLOBAL_CONFIG_DIR"
+fi
+
+# Backup existing global config if it exists
+if [ -f "$GLOBAL_CONFIG_FILE" ]; then
+    BACKUP_FILE="${GLOBAL_CONFIG_FILE}.backup.$(date +%Y%m%d_%H%M%S)"
+    echo "Backing up existing configuration to $BACKUP_FILE"
+    cp "$GLOBAL_CONFIG_FILE" "$BACKUP_FILE"
+fi
+
+# Create the global configuration
+cat > "$GLOBAL_CONFIG_FILE" << EOF
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "cd $HOOK_DIR && python code_quality_guard.py"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "cd $HOOK_DIR && python code_quality_guard.py"
+          }
+        ]
+      }
+    ]
+  }
+}
+EOF
+
+echo -e "${GREEN}✓ Global Claude Code configuration created at $GLOBAL_CONFIG_FILE${NC}"
+
+# Create a convenience script to configure quality settings
+QUALITY_CONFIG_SCRIPT="$HOME/.claude/configure-quality.sh"
+cat > "$QUALITY_CONFIG_SCRIPT" << 'EOF'
+#!/bin/bash
+
+# Convenience script to configure code quality hook settings
+# Usage: source ~/.claude/configure-quality.sh [preset]
+
+case "${1:-default}" in
+    strict)
+        export QUALITY_ENFORCEMENT="strict"
+        export QUALITY_COMPLEXITY_THRESHOLD="10"
+        export QUALITY_DUP_THRESHOLD="0.7"
+        export QUALITY_DUP_ENABLED="true"
+        export QUALITY_COMPLEXITY_ENABLED="true"
+        export QUALITY_MODERN_ENABLED="true"
+        export QUALITY_TYPE_HINTS="true"
+        echo "✓ Strict quality mode enabled"
+        ;;
+
+    moderate)
+        export QUALITY_ENFORCEMENT="warn"
+        export QUALITY_COMPLEXITY_THRESHOLD="15"
+        export QUALITY_DUP_THRESHOLD="0.8"
+        export QUALITY_DUP_ENABLED="true"
+        export QUALITY_COMPLEXITY_ENABLED="true"
+        export QUALITY_MODERN_ENABLED="true"
+        export QUALITY_TYPE_HINTS="false"
+        echo "✓ Moderate quality mode enabled"
+        ;;
+
+    permissive)
+        export QUALITY_ENFORCEMENT="permissive"
+        export QUALITY_COMPLEXITY_THRESHOLD="20"
+        export QUALITY_DUP_THRESHOLD="0.9"
+        export QUALITY_DUP_ENABLED="true"
+        export QUALITY_COMPLEXITY_ENABLED="true"
+        export QUALITY_MODERN_ENABLED="false"
+        export QUALITY_TYPE_HINTS="false"
+        echo "✓ Permissive quality mode enabled"
+        ;;
+
+    disabled)
+        export QUALITY_ENFORCEMENT="permissive"
+        export QUALITY_DUP_ENABLED="false"
+        export QUALITY_COMPLEXITY_ENABLED="false"
+        export QUALITY_MODERN_ENABLED="false"
+        echo "✓ Quality checks disabled"
+        ;;
+
+    custom)
+        echo "Configure custom quality settings:"
+        read -p "Enforcement mode (strict/warn/permissive): " QUALITY_ENFORCEMENT
+        read -p "Complexity threshold (10-30): " QUALITY_COMPLEXITY_THRESHOLD
+        read -p "Duplicate threshold (0.5-1.0): " QUALITY_DUP_THRESHOLD
+        read -p "Enable duplicate detection? (true/false): " QUALITY_DUP_ENABLED
+        read -p "Enable complexity checks? (true/false): " QUALITY_COMPLEXITY_ENABLED
+        read -p "Enable modernization checks? (true/false): " QUALITY_MODERN_ENABLED
+        read -p "Require type hints? (true/false): " QUALITY_TYPE_HINTS
+
+        export QUALITY_ENFORCEMENT
+        export QUALITY_COMPLEXITY_THRESHOLD
+        export QUALITY_DUP_THRESHOLD
+        export QUALITY_DUP_ENABLED
+        export QUALITY_COMPLEXITY_ENABLED
+        export QUALITY_MODERN_ENABLED
+        export QUALITY_TYPE_HINTS
+
+        echo "✓ Custom quality settings configured"
+        ;;
+
+    status)
+        echo "Current quality settings:"
+        echo "  QUALITY_ENFORCEMENT: ${QUALITY_ENFORCEMENT:-strict}"
+        echo "  QUALITY_COMPLEXITY_THRESHOLD: ${QUALITY_COMPLEXITY_THRESHOLD:-10}"
+        echo "  QUALITY_DUP_THRESHOLD: ${QUALITY_DUP_THRESHOLD:-0.7}"
+        echo "  QUALITY_DUP_ENABLED: ${QUALITY_DUP_ENABLED:-true}"
+        echo "  QUALITY_COMPLEXITY_ENABLED: ${QUALITY_COMPLEXITY_ENABLED:-true}"
+        echo "  QUALITY_MODERN_ENABLED: ${QUALITY_MODERN_ENABLED:-true}"
+        echo "  QUALITY_TYPE_HINTS: ${QUALITY_TYPE_HINTS:-false}"
+        return 0
+        ;;
+
+    *)
+        # Default settings
+        export QUALITY_ENFORCEMENT="strict"
+        export QUALITY_COMPLEXITY_THRESHOLD="10"
+        export QUALITY_DUP_THRESHOLD="0.7"
+        export QUALITY_DUP_ENABLED="true"
+        export QUALITY_COMPLEXITY_ENABLED="true"
+        export QUALITY_MODERN_ENABLED="true"
+        export QUALITY_TYPE_HINTS="false"
+        echo "✓ Default quality settings applied"
+
+        echo ""
+        echo "Available presets:"
+        echo "  strict    - Strict quality enforcement (default)"
+        echo "  moderate  - Moderate quality checks with warnings"
+        echo "  permissive - Permissive mode with suggestions"
+        echo "  disabled  - Disable all quality checks"
+        echo "  custom    - Configure custom settings"
+        echo "  status    - Show current settings"
+        echo ""
+        echo "Usage: source ~/.claude/configure-quality.sh [preset]"
+        ;;
+esac
+
+# Enable post-tool features for better feedback
+export QUALITY_STATE_TRACKING="true"
+export QUALITY_CROSS_FILE_CHECK="true"
+export QUALITY_VERIFY_NAMING="true"
+export QUALITY_SHOW_SUCCESS="false"  # Keep quiet unless there are issues
+EOF
+
+chmod +x "$QUALITY_CONFIG_SCRIPT"
+echo -e "${GREEN}✓ Quality configuration script created at $QUALITY_CONFIG_SCRIPT${NC}"
+
+# Add convenience alias to shell configuration
+SHELL_RC=""
+if [ -f "$HOME/.bashrc" ]; then
+    SHELL_RC="$HOME/.bashrc"
+elif [ -f "$HOME/.zshrc" ]; then
+    SHELL_RC="$HOME/.zshrc"
+fi
+
+if [ -n "$SHELL_RC" ]; then
+    # Check if alias already exists
+    if ! grep -q "alias claude-quality" "$SHELL_RC" 2>/dev/null; then
+        echo "" >> "$SHELL_RC"
+        echo "# Claude Code quality configuration" >> "$SHELL_RC"
+        echo "alias claude-quality='source ~/.claude/configure-quality.sh'" >> "$SHELL_RC"
+        echo -e "${GREEN}✓ Added 'claude-quality' alias to $SHELL_RC${NC}"
+    fi
+fi
+
+# Test the hook installation
+echo ""
+echo -e "${YELLOW}Testing hook installation...${NC}"
+cd "$HOOK_DIR"
+TEST_OUTPUT=$(echo '{"tool_name":"Read","tool_input":{}}' | python code_quality_guard.py 2>&1)
+if echo "$TEST_OUTPUT" | grep -q '"decision"'; then
+    echo -e "${GREEN}✓ Hook is working correctly${NC}"
+else
+    echo -e "${RED}✗ Hook test failed. Output:${NC}"
+    echo "$TEST_OUTPUT"
+    exit 1
+fi
+
+# Create a README for the global setup
+cat > "$GLOBAL_CONFIG_DIR/README_QUALITY_HOOK.md" << EOF
+# Claude Code Quality Hook
+
+The code quality hook is now globally configured for all projects in ~/repos.
+
+## Configuration
+
+The hook automatically runs on PreToolUse and PostToolUse events for Write, Edit, and MultiEdit operations.
+
+### Quick Configuration
+
+Use the \`claude-quality\` command to quickly configure quality settings:
+
+\`\`\`bash
+# Apply a preset
+source ~/.claude/configure-quality.sh strict    # Strict enforcement
+source ~/.claude/configure-quality.sh moderate  # Moderate with warnings
+source ~/.claude/configure-quality.sh permissive # Permissive suggestions
+source ~/.claude/configure-quality.sh disabled  # Disable checks
+
+# Or use the alias
+claude-quality strict
+
+# Check current settings
+claude-quality status
+\`\`\`
+
+### Environment Variables
+
+You can also set these environment variables directly:
+
+- \`QUALITY_ENFORCEMENT\`: strict/warn/permissive
+- \`QUALITY_COMPLEXITY_THRESHOLD\`: Maximum cyclomatic complexity (default: 10)
+- \`QUALITY_DUP_THRESHOLD\`: Duplicate similarity threshold 0-1 (default: 0.7)
+- \`QUALITY_DUP_ENABLED\`: Enable duplicate detection (default: true)
+- \`QUALITY_COMPLEXITY_ENABLED\`: Enable complexity checks (default: true)
+- \`QUALITY_MODERN_ENABLED\`: Enable modernization checks (default: true)
+- \`QUALITY_TYPE_HINTS\`: Require type hints (default: false)
+- \`QUALITY_STATE_TRACKING\`: Track file state changes (default: true)
+- \`QUALITY_CROSS_FILE_CHECK\`: Check cross-file duplicates (default: true)
+- \`QUALITY_VERIFY_NAMING\`: Verify PEP8 naming (default: true)
+- \`QUALITY_SHOW_SUCCESS\`: Show success messages (default: false)
+
+### Per-Project Configuration
+
+To override settings for a specific project, add a \`.quality.env\` file to the project root:
+
+\`\`\`bash
+# .quality.env
+QUALITY_ENFORCEMENT=moderate
+QUALITY_COMPLEXITY_THRESHOLD=15
+\`\`\`
+
+Then source it: \`source .quality.env\`
+
+## Features
+
+### PreToolUse Checks
+- Internal duplicate detection within files
+- Cyclomatic complexity analysis
+- Code modernization suggestions
+- Type hint requirements
+
+### PostToolUse Checks
+- State tracking (detects quality degradation)
+- Cross-file duplicate detection
+- PEP8 naming convention verification
+
+## Enforcement Modes
+
+- **strict**: Blocks (deny) code that fails quality checks
+- **warn**: Asks for confirmation (ask) on quality issues
+- **permissive**: Allows code with warnings
+
+## Troubleshooting
+
+If the hook is not working:
+1. Check that claude-quality binary is installed: \`which claude-quality\`
+2. Verify Python environment: \`python --version\`
+3. Test the hook directly: \`echo '{"tool_name":"Read","tool_input":{}}' | python $HOOK_DIR/code_quality_guard.py\`
+4. Check logs: Claude Code may show hook errors in its output
+
+## Uninstalling
+
+To remove the global hook:
+1. Delete or rename ~/.claude/claude-code-settings.json
+2. Remove the claude-quality alias from your shell RC file
+EOF
+
+echo ""
+echo -e "${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+echo -e "${GREEN}✓ Global code quality hook successfully installed!${NC}"
+echo -e "${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+echo ""
+echo "The hook is now active for all Claude Code sessions in ~/repos projects."
+echo ""
+echo "Quick start:"
+echo -e "  ${YELLOW}claude-quality strict${NC}     # Enable strict quality enforcement"
+echo -e "  ${YELLOW}claude-quality moderate${NC}   # Use moderate settings"
+echo -e "  ${YELLOW}claude-quality status${NC}     # Check current settings"
+echo ""
+echo "For more information, see: ~/.claude/README_QUALITY_HOOK.md"
+echo ""
+echo -e "${YELLOW}Note: Restart your shell or run 'source $SHELL_RC' to use the claude-quality alias${NC}"

src/quality/__init__.py

@@ -6,4 +6,4 @@ __email__ = "team@intellikit.com"
 
 # Minimal imports to prevent pre-commit failures
 # Full imports can be added later when all modules are properly set up
-__all__ = []
+__all__: list[str] = []

src/quality/analyzers/modernization.py

@@ -127,7 +127,10 @@ class ModernizationAnalyzer(ast.NodeVisitor):
     }
 
     def __init__(
-        self, file_path: str, content: str, config: QualityConfig | None = None
+        self,
+        file_path: str,
+        content: str,
+        config: QualityConfig | None = None,
     ):
         self.file_path = file_path
         self.content = content
@@ -235,7 +238,7 @@ class ModernizationAnalyzer(ast.NodeVisitor):
 
         # Check for untyped parameters
         for arg in node.args.args:
-            if not arg.annotation and arg.arg != "self" and arg.arg != "cls":
+            if not arg.annotation and arg.arg not in {"self", "cls"}:
                 self._add_missing_param_type_issue(node, arg)
 
         self.generic_visit(node)
@@ -247,7 +250,7 @@ class ModernizationAnalyzer(ast.NodeVisitor):
             self._add_missing_return_type_issue(node)
 
         for arg in node.args.args:
-            if not arg.annotation and arg.arg != "self" and arg.arg != "cls":
+            if not arg.annotation and arg.arg not in {"self", "cls"}:
                 self._add_missing_param_type_issue(node, arg)
 
         self.generic_visit(node)
@@ -262,13 +265,19 @@ class ModernizationAnalyzer(ast.NodeVisitor):
         self.generic_visit(node)
 
     def _add_replaceable_typing_import_issue(
-        self, node: ast.ImportFrom, typing_name: str, import_name: str
+        self,
+        node: ast.ImportFrom,
+        typing_name: str,
+        import_name: str,  # noqa: ARG002
     ) -> None:
         """Add issue for typing import that can be replaced with built-ins."""
         modern_replacement = self.REPLACEABLE_TO_MODERN[typing_name]
 
         if typing_name in ["List", "Dict", "Tuple", "Set", "FrozenSet"]:
-            description = f"Use built-in '{modern_replacement}' instead of 'typing.{typing_name}' (Python 3.9+)"
+            description = (
+                f"Use built-in '{modern_replacement}' instead of "
+                f"'typing.{typing_name}' (Python 3.9+)"
+            )
             severity = "warning"
         elif typing_name == "Union":
             description = (
@@ -291,14 +300,19 @@ class ModernizationAnalyzer(ast.NodeVisitor):
                 column=node.col_offset,
                 issue_type="replaceable_typing_import",
                 old_pattern=f"from typing import {typing_name}",
-                suggested_fix=f"# Remove this import and use {modern_replacement} directly",
+                suggested_fix=(
+                    f"# Remove this import and use {modern_replacement} directly"
+                ),
                 severity=severity,
                 description=description,
-            )
+            ),
         )
 
     def _add_collections_typing_import_issue(
-        self, node: ast.ImportFrom, typing_name: str, import_name: str
+        self,
+        node: ast.ImportFrom,
+        typing_name: str,
+        import_name: str,  # noqa: ARG002
     ) -> None:
         """Add issue for typing import that moved to collections."""
         self.issues.append(
@@ -310,12 +324,18 @@ class ModernizationAnalyzer(ast.NodeVisitor):
                 old_pattern=f"from typing import {typing_name}",
                 suggested_fix=f"from collections import {typing_name.lower()}",
                 severity="info",
-                description=f"Use 'from collections import {typing_name.lower()}' instead of 'typing.{typing_name}'",
-            )
+                description=(
+                    f"Use 'from collections import {typing_name.lower()}' "
+                    f"instead of 'typing.{typing_name}'"
+                ),
+            ),
         )
 
     def _add_moved_typing_import_issue(
-        self, node: ast.ImportFrom, typing_name: str, import_name: str
+        self,
+        node: ast.ImportFrom,
+        typing_name: str,
+        import_name: str,  # noqa: ARG002
     ) -> None:
         """Add issue for typing import that moved to another module."""
         target_module = self.MOVED_TYPING_IMPORTS[typing_name]
@@ -329,8 +349,10 @@ class ModernizationAnalyzer(ast.NodeVisitor):
                 old_pattern=f"from typing import {typing_name}",
                 suggested_fix=f"from {target_module} import {typing_name}",
                 severity="info",
-                description=f"'{typing_name}' moved from 'typing' to '{target_module}' module",
-            )
+                description=(
+                    f"'{typing_name}' moved from 'typing' to '{target_module}' module"
+                ),
+            ),
         )
 
     def _add_typing_usage_issue(self, node: ast.Subscript, typing_name: str) -> None:
@@ -340,7 +362,10 @@ class ModernizationAnalyzer(ast.NodeVisitor):
             if typing_name in ["List", "Dict", "Tuple", "Set", "FrozenSet"]:
                 old_pattern = f"{typing_name}[...]"
                 new_pattern = f"{modern_replacement.lower()}[...]"
-                description = f"Use built-in '{modern_replacement}' instead of 'typing.{typing_name}'"
+                description = (
+                    f"Use built-in '{modern_replacement}' instead of "
+                    f"'typing.{typing_name}'"
+                )
                 severity = "warning"
             elif typing_name == "Union":
                 old_pattern = "Union[...]"
@@ -375,11 +400,13 @@ class ModernizationAnalyzer(ast.NodeVisitor):
                 suggested_fix=new_pattern,
                 severity=severity,
                 description=description,
-            )
+            ),
         )
 
     def _add_moved_typing_usage_issue(
-        self, node: ast.Subscript, typing_name: str
+        self,
+        node: ast.Subscript,
+        typing_name: str,
     ) -> None:
         """Add issue for typing usage that moved to another module."""
         target_module = self.MOVED_TYPING_IMPORTS[typing_name]
@@ -393,12 +420,16 @@ class ModernizationAnalyzer(ast.NodeVisitor):
                 old_pattern=f"typing.{typing_name}[...]",
                 suggested_fix=f"{target_module}.{typing_name}[...]",
                 severity="info",
-                description=f"Use '{target_module}.{typing_name}' instead of 'typing.{typing_name}'",
-            )
+                description=(
+                    f"Use '{target_module}.{typing_name}' instead of "
+                    f"'typing.{typing_name}'"
+                ),
+            ),
         )
 
     def _add_missing_return_type_issue(
-        self, node: ast.FunctionDef | ast.AsyncFunctionDef
+        self,
+        node: ast.FunctionDef | ast.AsyncFunctionDef,
     ) -> None:
         """Add issue for missing return type annotation."""
         self.issues.append(
@@ -410,13 +441,17 @@ class ModernizationAnalyzer(ast.NodeVisitor):
                 old_pattern=f"def {node.name}(...)",
                 suggested_fix=f"def {node.name}(...) -> ReturnType",
                 severity="info",
-                description="Consider adding return type annotation for better type safety",
+                description=(
+                    "Consider adding return type annotation for better type safety"
+                ),
                 can_auto_fix=False,
-            )
+            ),
         )
 
     def _add_missing_param_type_issue(
-        self, node: ast.FunctionDef | ast.AsyncFunctionDef, arg: ast.arg
+        self,
+        node: ast.FunctionDef | ast.AsyncFunctionDef,
+        arg: ast.arg,
     ) -> None:
         """Add issue for missing parameter type annotation."""
         self.issues.append(
@@ -428,13 +463,17 @@ class ModernizationAnalyzer(ast.NodeVisitor):
                 old_pattern=f"{arg.arg}",
                 suggested_fix=f"{arg.arg}: ParamType",
                 severity="info",
-                description=f"Consider adding type annotation for parameter '{arg.arg}'",
+                description=(
+                    f"Consider adding type annotation for parameter '{arg.arg}'"
+                ),
                 can_auto_fix=False,
-            )
+            ),
         )
 
     def _add_unnecessary_object_inheritance_issue(
-        self, node: ast.ClassDef, base: ast.Name
+        self,
+        node: ast.ClassDef,
+        base: ast.Name,  # noqa: ARG002
     ) -> None:
         """Add issue for unnecessary object inheritance."""
         self.issues.append(
@@ -448,7 +487,7 @@ class ModernizationAnalyzer(ast.NodeVisitor):
                 severity="info",
                 description="Inheriting from 'object' is unnecessary in Python 3",
                 can_auto_fix=True,
-            )
+            ),
         )
 
     def _check_string_patterns(self) -> None:
@@ -465,8 +504,11 @@ class ModernizationAnalyzer(ast.NodeVisitor):
                         old_pattern="'...' % (...)",
                         suggested_fix="f'...' or '...'.format(...)",
                         severity="info",
-                        description="Consider using f-strings or .format() instead of % formatting",
-                    )
+                        description=(
+                            "Consider using f-strings or .format() "
+                            "instead of % formatting"
+                        ),
+                    ),
                 )
 
             # Check for .format() that could be f-string
@@ -480,8 +522,11 @@ class ModernizationAnalyzer(ast.NodeVisitor):
                         old_pattern="'...{}'.format(...)",
                         suggested_fix="f'...{...}'",
                         severity="info",
-                        description="Consider using f-strings instead of .format() for better readability",
-                    )
+                        description=(
+                            "Consider using f-strings instead of .format() "
+                            "for better readability"
+                        ),
+                    ),
                 )
 
     def _check_exception_patterns(self) -> None:
@@ -498,8 +543,10 @@ class ModernizationAnalyzer(ast.NodeVisitor):
                         old_pattern="except:",
                         suggested_fix="except Exception:",
                         severity="warning",
-                        description="Use specific exception types instead of bare except",
-                    )
+                        description=(
+                            "Use specific exception types instead of bare except"
+                        ),
+                    ),
                 )
 
     def _check_super_patterns(self) -> None:
@@ -517,7 +564,7 @@ class ModernizationAnalyzer(ast.NodeVisitor):
                         suggested_fix="super()",
                         severity="info",
                         description="Use super() without arguments (Python 3+)",
-                    )
+                    ),
                 )
 
     def _is_dunder_method(self, name: str) -> bool:
@@ -532,26 +579,38 @@ class PydanticAnalyzer:
         # Model configuration patterns
         r"class\s+Config:": "Use model_config instead of Config class (Pydantic v2)",
         # Field patterns
-        r"Field\([^)]*allow_mutation=": "allow_mutation is deprecated, use frozen instead",
+        r"Field\([^)]*allow_mutation=": (
+            "allow_mutation is deprecated, use frozen instead"
+        ),
         r"Field\([^)]*regex=": "regex parameter is deprecated, use pattern instead",
-        r"Field\([^)]*min_length=": "Consider using StringConstraints for string validation",
-        r"Field\([^)]*max_length=": "Consider using StringConstraints for string validation",
+        r"Field\([^)]*min_length=": (
+            "Consider using StringConstraints for string validation"
+        ),
+        r"Field\([^)]*max_length=": (
+            "Consider using StringConstraints for string validation"
+        ),
         # Validator patterns
         r"@validator": "@validator is deprecated, use @field_validator instead",
-        r"@root_validator": "@root_validator is deprecated, use @model_validator instead",
+        r"@root_validator": (
+            "@root_validator is deprecated, use @model_validator instead"
+        ),
         r"pre=True": "pre parameter syntax changed in Pydantic v2",
         # Model methods
         r"\.dict\(\)": "Use .model_dump() instead of .dict() (Pydantic v2)",
         r"\.json\(\)": "Use .model_dump_json() instead of .json() (Pydantic v2)",
         r"\.parse_obj\(": "Use model_validate() instead of parse_obj() (Pydantic v2)",
-        r"\.parse_raw\(": "Use model_validate_json() instead of parse_raw() (Pydantic v2)",
+        r"\.parse_raw\(": (
+            "Use model_validate_json() instead of parse_raw() (Pydantic v2)"
+        ),
         r"\.schema\(\)": "Use model_json_schema() instead of schema() (Pydantic v2)",
         r"\.copy\(\)": "Use model_copy() instead of copy() (Pydantic v2)",
         # Import patterns
-        r"from pydantic import.*BaseSettings": "BaseSettings moved to pydantic-settings package",
+        r"from pydantic import.*BaseSettings": (
+            "BaseSettings moved to pydantic-settings package"
+        ),
     }
 
-    # Pydantic v2 methods that should NEVER be flagged as issues when used with model classes
+    # Pydantic v2 methods that should NEVER be flagged as issues when used with models
     V2_METHODS = {
         "model_validate",
         "model_validate_json",
@@ -616,7 +675,7 @@ class PydanticAnalyzer:
                             description=description,
                             can_auto_fix=pattern
                             in [r"\.dict\(\)", r"\.json\(\)", r"\.copy\(\)"],
-                        )
+                        ),
                     )
 
         return self.issues
@@ -633,11 +692,11 @@ class PydanticAnalyzer:
         return any(context in content_lower for context in self.INTENTIONAL_V1_CONTEXTS)
 
     def _is_valid_v2_pattern(self, line: str) -> bool:
-        """Check if line contains valid Pydantic v2 patterns that should not be flagged."""
+        """Check if line contains valid Pydantic v2 patterns to not flag."""
         # Check if line contains any valid v2 methods
         return any(f".{v2_method}(" in line for v2_method in self.V2_METHODS)
 
-    def _get_suggested_fix(self, pattern: str, line: str) -> str:
+    def _get_suggested_fix(self, pattern: str, line: str) -> str:  # noqa: ARG002
         """Get suggested fix for a Pydantic pattern."""
         fixes = {
             r"\.dict\(\)": line.replace(".dict()", ".model_dump()"),
@@ -684,7 +743,8 @@ class ModernizationEngine:
         return issues
 
     def analyze_files(
-        self, file_paths: list[Path]
+        self,
+        file_paths: list[Path],
     ) -> dict[Path, list[ModernizationIssue]]:
         """Analyze multiple files for modernization opportunities."""
         results = {}
@@ -701,7 +761,8 @@ class ModernizationEngine:
                     get_line_number_fn=lambda issue: issue.line_number,
                     get_issue_type_fn=lambda issue: issue.issue_type,
                     get_line_content_fn=lambda issue: self._get_line_content(
-                        issue.file_path, issue.line_number
+                        issue.file_path,
+                        issue.line_number,
                     ),
                 )
 
@@ -722,7 +783,8 @@ class ModernizationEngine:
         return ""
 
     def get_summary(
-        self, results: dict[Path, list[ModernizationIssue]]
+        self,
+        results: dict[Path, list[ModernizationIssue]],
     ) -> dict[str, Any]:
         """Generate summary of modernization analysis."""
         all_issues = []
@@ -756,7 +818,7 @@ class ModernizationEngine:
                     f
                     for f, issues in results.items()
                     if issues is not None and len(issues) > 0
-                ]
+                ],
             ),
             "total_issues": len(all_issues),
             "by_severity": by_severity,
@@ -767,7 +829,9 @@ class ModernizationEngine:
         }
 
     def _generate_recommendations(
-        self, by_type: dict[str, list[ModernizationIssue]], by_severity: dict[str, int]
+        self,
+        by_type: dict[str, list[ModernizationIssue]],
+        by_severity: dict[str, int],
     ) -> list[str]:
         """Generate recommendations based on analysis results."""
         recommendations = []
@@ -779,17 +843,23 @@ class ModernizationEngine:
 
         if replaceable_count > 0:
             recommendations.append(
-                f"🔄 Update {replaceable_count} typing imports to use modern built-in types (Python 3.9+)"
+                (
+                    f"🔄 Update {replaceable_count} typing imports to use modern "
+                    f"built-in types (Python 3.9+)"
+                ),
             )
 
         if collections_count > 0:
             recommendations.append(
-                f"📦 Update {collections_count} typing imports to use collections module"
+                (
+                    f"📦 Update {collections_count} typing imports to use "
+                    f"collections module"
+                ),
             )
 
         if moved_count > 0:
             recommendations.append(
-                f"🔀 Update {moved_count} typing imports that moved to other modules"
+                f"🔀 Update {moved_count} typing imports that moved to other modules",
             )
 
         # Handle typing usage issues
@@ -798,12 +868,18 @@ class ModernizationEngine:
 
         if usage_count > 0:
             recommendations.append(
-                f"⚡ Modernize {usage_count} type annotations to use built-ins or | union syntax"
+                (
+                    f"⚡ Modernize {usage_count} type annotations to use built-ins "
+                    f"or | union syntax"
+                ),
             )
 
         if moved_usage_count > 0:
             recommendations.append(
-                f"🔀 Update {moved_usage_count} type annotations that moved to other modules"
+                (
+                    f"🔀 Update {moved_usage_count} type annotations that moved to "
+                    f"other modules"
+                ),
             )
 
         # Keep existing recommendations for other issue types
@@ -814,18 +890,21 @@ class ModernizationEngine:
         if "old_string_formatting" in by_type:
             count = len(by_type["old_string_formatting"])
             recommendations.append(
-                f"✨ Replace {count} old string formatting patterns with f-strings"
+                f"✨ Replace {count} old string formatting patterns with f-strings",
             )
 
         if "bare_except" in by_type:
             count = len(by_type["bare_except"])
             recommendations.append(
-                f"⚠️ Fix {count} bare except clauses for better error handling"
+                f"⚠️ Fix {count} bare except clauses for better error handling",
             )
 
         if by_severity["warning"] > 10:
             recommendations.append(
-                f"🚨 Address {by_severity['warning']} warning-level issues for better code quality"
+                (
+                    f"🚨 Address {by_severity['warning']} warning-level issues for "
+                    f"better code quality"
+                ),
             )
 
         return recommendations

src/quality/cli/main.py

@@ -6,7 +6,7 @@ import csv
 import json
 import sys
 from pathlib import Path
-from typing import Any
+from typing import IO, Any
 
 import click
 
@@ -35,7 +35,10 @@ from ..utils.file_finder import FileFinder
 @click.option("--verbose", "-v", is_flag=True, help="Enable verbose output")
 @click.pass_context
 def cli(
-    ctx: click.Context, config: Path | None, exceptions_file: Path | None, verbose: bool
+    ctx: click.Context,
+    config: Path | None,
+    exceptions_file: Path | None,
+    verbose: bool,
 ) -> None:
     """Code quality analysis toolkit."""
     ctx.ensure_object(dict)
@@ -56,7 +59,10 @@ def cli(
 
 @cli.command()
 @click.argument(
-    "paths", nargs=-1, required=True, type=click.Path(exists=True, path_type=Path)
+    "paths",
+    nargs=-1,
+    required=True,
+    type=click.Path(exists=True, path_type=Path),
 )
 @click.option("--threshold", "-t", default=0.8, help="Similarity threshold (0.0-1.0)")
 @click.option("--min-lines", default=5, help="Minimum lines for duplicate detection")
@@ -76,7 +82,7 @@ def duplicates(
     threshold: float,
     min_lines: int,
     min_tokens: int,
-    output: Any,
+    output: IO[str] | None,
     output_format: str,
 ) -> None:
     """Detect duplicate code patterns."""
@@ -152,7 +158,10 @@ def duplicates(
 
 @cli.command()
 @click.argument(
-    "paths", nargs=-1, required=True, type=click.Path(exists=True, path_type=Path)
+    "paths",
+    nargs=-1,
+    required=True,
+    type=click.Path(exists=True, path_type=Path),
 )
 @click.option("--threshold", default=10, help="Complexity threshold")
 @click.option("--output", "-o", type=click.File("w"), help="Output file for results")
@@ -168,7 +177,7 @@ def complexity(
     ctx: click.Context,
     paths: tuple[Path],
     threshold: int,
-    output: Any,
+    output: IO[str] | None,
     output_format: str,
 ) -> None:
     """Analyze code complexity."""
@@ -214,10 +223,15 @@ def complexity(
 
 @cli.command()
 @click.argument(
-    "paths", nargs=-1, required=True, type=click.Path(exists=True, path_type=Path)
+    "paths",
+    nargs=-1,
+    required=True,
+    type=click.Path(exists=True, path_type=Path),
 )
 @click.option(
-    "--include-type-hints", is_flag=True, help="Include missing type hint analysis"
+    "--include-type-hints",
+    is_flag=True,
+    help="Include missing type hint analysis",
 )
 @click.option("--pydantic-only", is_flag=True, help="Only analyze Pydantic patterns")
 @click.option("--output", "-o", type=click.File("w"), help="Output file for results")
@@ -234,17 +248,17 @@ def modernization(
     paths: tuple[Path],
     include_type_hints: bool,
     pydantic_only: bool,
-    output: Any,
+    output: IO[str] | None,
     output_format: str,
 ) -> None:
     """Analyze code for modernization opportunities."""
-
     config: QualityConfig = ctx.obj["config"]
     verbose: bool = ctx.obj["verbose"]
 
     if verbose:
         click.echo(
-            f"🔍 Analyzing modernization opportunities in: {', '.join(str(p) for p in paths)}"
+            f"🔍 Analyzing modernization opportunities in: "
+            f"{', '.join(str(p) for p in paths)}",
         )
         if include_type_hints:
             click.echo("📝 Including type hint analysis")
@@ -308,7 +322,10 @@ def modernization(
 
 @cli.command()
 @click.argument(
-    "paths", nargs=-1, required=True, type=click.Path(exists=True, path_type=Path)
+    "paths",
+    nargs=-1,
+    required=True,
+    type=click.Path(exists=True, path_type=Path),
 )
 @click.option("--output", "-o", type=click.File("w"), help="Output file for results")
 @click.option(
@@ -320,7 +337,10 @@ def modernization(
 )
 @click.pass_context
 def full_analysis(
-    ctx: click.Context, paths: tuple[Path], output: Any, output_format: str
+    ctx: click.Context,
+    paths: tuple[Path],
+    output: IO[str] | None,
+    output_format: str,
 ) -> None:
     """Run comprehensive code quality analysis."""
     config: QualityConfig = ctx.obj["config"]
@@ -328,7 +348,7 @@ def full_analysis(
 
     if verbose:
         click.echo(
-            f"🔍 Running full quality analysis on: {', '.join(str(p) for p in paths)}"
+            f"🔍 Running full quality analysis on: {', '.join(str(p) for p in paths)}",
         )
 
     # Find Python files
@@ -354,7 +374,7 @@ def full_analysis(
             "total_files": len(all_files),
             "analyzed_paths": [str(p) for p in paths],
             "configuration": config.dict(),
-        }
+        },
     }
 
     # Complexity analysis
@@ -362,7 +382,7 @@ def full_analysis(
         click.echo("📊 Running complexity analysis...")
     complexity_analyzer = ComplexityAnalyzer(config.complexity)
     results["complexity"] = complexity_analyzer.get_project_complexity_overview(
-        all_files
+        all_files,
     )
 
     # Duplicate detection
@@ -402,9 +422,9 @@ def full_analysis(
             smells = ast_analyzer.detect_code_smells()
             if smells:
                 all_smells.extend(
-                    [{"file": str(file_path), "smell": smell} for smell in smells]
+                    [{"file": str(file_path), "smell": smell} for smell in smells],
                 )
-        except Exception:
+        except (OSError, PermissionError, UnicodeDecodeError):
             continue
 
     results["code_smells"] = {"total_smells": len(all_smells), "details": all_smells}
@@ -457,9 +477,8 @@ def _print_console_duplicates(results: dict[str, Any], verbose: bool) -> None:
                 click.echo(f"     • {suggestion}")
 
 
-def _print_csv_duplicates(results: dict[str, Any], output: Any) -> None:
+def _print_csv_duplicates(results: dict[str, Any], output: IO[str] | None) -> None:
     """Print duplicate results in CSV format."""
-
     if not output:
         output = sys.stdout
 
@@ -475,7 +494,7 @@ def _print_csv_duplicates(results: dict[str, Any], output: Any) -> None:
             "Lines of Code",
             "Estimated Effort",
             "Risk Level",
-        ]
+        ],
     )
 
     for dup in results["duplicates"]:
@@ -494,11 +513,11 @@ def _print_csv_duplicates(results: dict[str, Any], output: Any) -> None:
                     block["lines_of_code"],
                     analysis.get("estimated_effort", "Unknown"),
                     analysis.get("risk_assessment", "Unknown"),
-                ]
+                ],
             )
 
 
-def _print_console_complexity(results: dict[str, Any], verbose: bool) -> None:
+def _print_console_complexity(results: dict[str, Any], verbose: bool) -> None:  # noqa: ARG001
     """Print complexity results in console format."""
     click.echo("\n📊 COMPLEXITY ANALYSIS")
     click.echo("=" * 50)
@@ -520,11 +539,14 @@ def _print_console_complexity(results: dict[str, Any], verbose: bool) -> None:
 
     if results["high_complexity_files"]:
         click.echo(
-            f"\n🚨 High complexity files (top {len(results['high_complexity_files'])}):"
+            f"\n🚨 High complexity files "
+            f"(top {len(results['high_complexity_files'])}):",
         )
         for file_info in results["high_complexity_files"]:
             click.echo(
-                f"   • {file_info['file']} (score: {file_info['score']:.1f}, level: {file_info['level']})"
+                f"   • {file_info['file']} "
+                f"(score: {file_info['score']:.1f}, "
+                f"level: {file_info['level']})",
             )
 
     if results["recommendations"]:
@@ -534,7 +556,9 @@ def _print_console_complexity(results: dict[str, Any], verbose: bool) -> None:
 
 
 def _print_console_modernization(
-    results: dict[str, Any], verbose: bool, include_type_hints: bool
+    results: dict[str, Any],
+    verbose: bool,
+    include_type_hints: bool,  # noqa: ARG001
 ) -> None:
     """Print modernization results in console format."""
     summary = results["summary"]
@@ -550,7 +574,7 @@ def _print_console_modernization(
     for severity, count in summary["by_severity"].items():
         if count > 0:
             icon = (
-                "🚨" if severity == "error" else "⚠️" if severity == "warning" else "ℹ️"
+                "🚨" if severity == "error" else "⚠️" if severity == "warning" else "ℹ️"  # noqa: RUF001
             )
             click.echo(f"   {icon} {severity.title()}: {count}")
 
@@ -578,10 +602,11 @@ def _print_console_modernization(
                     if issue["severity"] == "error"
                     else "⚠️"
                     if issue["severity"] == "warning"
-                    else "ℹ️"
+                    else "ℹ️"  # noqa: RUF001
                 )
                 click.echo(
-                    f"      {severity_icon} Line {issue['line_number']}: {issue['description']}"
+                    f"      {severity_icon} Line {issue['line_number']}: "
+                    f"{issue['description']}",
                 )
                 if issue["can_auto_fix"]:
                     click.echo(f"         🔧 Suggested fix: {issue['suggested_fix']}")
@@ -609,10 +634,10 @@ def _print_console_full_analysis(results: dict[str, Any], verbose: bool) -> None
     duplicates = results["duplicates"]
     click.echo("\n🔄 DUPLICATE DETECTION")
     click.echo(
-        f"   Duplicate groups: {duplicates['summary']['duplicate_groups_found']}"
+        f"   Duplicate groups: {duplicates['summary']['duplicate_groups_found']}",
     )
     click.echo(
-        f"   Total duplicate blocks: {duplicates['summary']['total_duplicate_blocks']}"
+        f"   Total duplicate blocks: {duplicates['summary']['total_duplicate_blocks']}",
     )
 
     # Code smells summary
@@ -670,11 +695,10 @@ def _calculate_overall_quality_score(results: dict[str, Any]) -> float:
 )
 def create_exceptions_template(output_path: Path) -> None:
     """Create a template exceptions configuration file."""
-
     template_content = create_exceptions_config_template()
 
     if output_path.exists() and not click.confirm(
-        f"File {output_path} already exists. Overwrite?"
+        f"File {output_path} already exists. Overwrite?",
     ):
         click.echo("Aborted.")
         return

src/quality/complexity/analyzer.py

@@ -3,31 +3,24 @@
 from pathlib import Path
 from typing import Any
 
+from ..config.schemas import ComplexityConfig
 from .metrics import ComplexityMetrics
 from .radon_integration import RadonComplexityAnalyzer
-from ..config.schemas import ComplexityConfig
-
-# TYPE_CHECKING import to avoid circular imports
-try:
-    from ..core.exceptions import ExceptionFilter
-except ImportError:
-    ExceptionFilter = None
 
 
 class ComplexityAnalyzer:
     """High-level interface for code complexity analysis."""
 
-    def __init__(self, config: ComplexityConfig | None = None, full_config: Any = None):
+    def __init__(self, config: ComplexityConfig | None = None, full_config: Any = None):  # noqa: ANN401
         self.config = config or ComplexityConfig()
         self.radon_analyzer = RadonComplexityAnalyzer(fallback_to_manual=True)
 
         # Initialize exception filter if full config provided
+        self.exception_filter: Any = None
         if full_config:
             from ..core.exceptions import ExceptionFilter
 
-            self.exception_filter: ExceptionFilter | None = ExceptionFilter(full_config)
-        else:
-            self.exception_filter: ExceptionFilter | None = None
+            self.exception_filter = ExceptionFilter(full_config)
 
     def analyze_code(self, code: str, filename: str = "<string>") -> ComplexityMetrics:
         """Analyze complexity of code string."""
@@ -40,7 +33,9 @@ class ComplexityAnalyzer:
         return self._filter_metrics_by_config(metrics)
 
     def batch_analyze_files(
-        self, file_paths: list[Path], max_workers: int | None = None
+        self,
+        file_paths: list[Path],
+        max_workers: int | None = None,
     ) -> dict[Path, ComplexityMetrics]:
         """Analyze multiple files in parallel."""
         raw_results = self.radon_analyzer.batch_analyze_files(file_paths, max_workers)
@@ -72,7 +67,9 @@ class ComplexityAnalyzer:
         }
 
     def get_detailed_report(
-        self, code: str, filename: str = "<string>"
+        self,
+        code: str,
+        filename: str = "<string>",
     ) -> dict[str, Any]:
         """Get detailed complexity report including function-level analysis."""
         report = self.radon_analyzer.get_detailed_complexity_report(code, filename)
@@ -93,7 +90,9 @@ class ComplexityAnalyzer:
         return report
 
     def find_complex_code(
-        self, file_paths: list[Path], max_workers: int | None = None
+        self,
+        file_paths: list[Path],
+        max_workers: int | None = None,
     ) -> list[dict[str, Any]]:
         """Find code blocks that exceed complexity thresholds."""
         results = self.batch_analyze_files(file_paths, max_workers)
@@ -105,7 +104,11 @@ class ComplexityAnalyzer:
                 if self.exception_filter:
                     should_suppress, reason = (
                         self.exception_filter.should_suppress_issue(
-                            "complexity", "high_complexity", str(path), 1, ""
+                            "complexity",
+                            "high_complexity",
+                            str(path),
+                            1,
+                            "",
                         )
                     )
                     if should_suppress:
@@ -118,7 +121,7 @@ class ComplexityAnalyzer:
                         "metrics": metrics.to_dict(),
                         "summary": summary,
                         "priority": summary["priority_score"],
-                    }
+                    },
                 )
 
         # Sort by priority (highest first)
@@ -126,7 +129,9 @@ class ComplexityAnalyzer:
         return complex_files
 
     def get_project_complexity_overview(
-        self, file_paths: list[Path], max_workers: int | None = None
+        self,
+        file_paths: list[Path],
+        max_workers: int | None = None,
     ) -> dict[str, Any]:
         """Get overall project complexity statistics."""
         results = self.batch_analyze_files(file_paths, max_workers)
@@ -165,21 +170,23 @@ class ComplexityAnalyzer:
                         "file": str(path),
                         "score": metrics.get_overall_score(),
                         "level": level,
-                    }
+                    },
                 )
 
         # Sort high complexity files by score
-        high_complexity_files.sort(key=lambda x: x["score"], reverse=True)
+        high_complexity_files.sort(key=lambda x: float(str(x["score"])), reverse=True)
 
         # Project-level recommendations
         recommendations = []
         if complexity_levels["Extreme"] > 0:
             recommendations.append(
-                f"🚨 {complexity_levels['Extreme']} files with extreme complexity need immediate attention"
+                f"🚨 {complexity_levels['Extreme']} files with extreme complexity "
+                "need immediate attention",
             )
         if complexity_levels["Very High"] > 0:
             recommendations.append(
-                f"⚠️ {complexity_levels['Very High']} files with very high complexity should be refactored"
+                f"⚠️ {complexity_levels['Very High']} files with very high "
+                "complexity should be refactored",
             )
         if total_files > 0:
             avg_complexity = (
@@ -187,7 +194,8 @@ class ComplexityAnalyzer:
             )
             if avg_complexity > 40:
                 recommendations.append(
-                    "📈 Overall project complexity is high - consider architectural improvements"
+                    "📈 Overall project complexity is high - "
+                    "consider architectural improvements",
                 )
 
         return {
@@ -233,7 +241,8 @@ class ComplexityAnalyzer:
         }
 
     def _filter_metrics_by_config(
-        self, metrics: ComplexityMetrics
+        self,
+        metrics: ComplexityMetrics,
     ) -> ComplexityMetrics:
         """Filter metrics based on configuration settings."""
         filtered = ComplexityMetrics()

src/quality/complexity/calculator.py

@@ -28,7 +28,7 @@ class ComplexityCalculator:
         metrics.lines_of_code = len(lines)
         metrics.blank_lines = len([line for line in lines if not line.strip()])
         metrics.comment_lines = len(
-            [line for line in lines if line.strip().startswith("#")]
+            [line for line in lines if line.strip().startswith("#")],
         )
         metrics.source_lines_of_code = (
             metrics.lines_of_code - metrics.blank_lines - metrics.comment_lines
@@ -42,7 +42,7 @@ class ComplexityCalculator:
                 metrics.parameters_count += len(node.args.args)
                 # Count returns
                 metrics.returns_count += len(
-                    [n for n in ast.walk(node) if isinstance(n, ast.Return)]
+                    [n for n in ast.walk(node) if isinstance(n, ast.Return)],
                 )
             elif isinstance(node, ast.ClassDef):
                 metrics.class_count += 1
@@ -50,7 +50,7 @@ class ComplexityCalculator:
                 metrics.function_count += 1
                 metrics.parameters_count += len(node.args.args)
                 metrics.returns_count += len(
-                    [n for n in ast.walk(node) if isinstance(n, ast.Return)]
+                    [n for n in ast.walk(node) if isinstance(n, ast.Return)],
                 )
 
         # Calculate cyclomatic complexity
@@ -94,7 +94,7 @@ class ComplexityCalculator:
         metrics.lines_of_code = len(lines)
         metrics.blank_lines = len([line for line in lines if not line.strip()])
         metrics.comment_lines = len(
-            [line for line in lines if line.strip().startswith("#")]
+            [line for line in lines if line.strip().startswith("#")],
         )
         metrics.source_lines_of_code = (
             metrics.lines_of_code - metrics.blank_lines - metrics.comment_lines
@@ -156,10 +156,8 @@ class ComplexityCalculator:
             elif isinstance(node, ast.BoolOp):
                 # Logical operators add complexity
                 local_complexity += len(node.values) - 1
-            elif (
-                isinstance(node, ast.Lambda)
-                or isinstance(node, ast.Expr)
-                and isinstance(node.value, ast.IfExp)
+            elif isinstance(node, ast.Lambda) or (
+                isinstance(node, ast.Expr) and isinstance(node.value, ast.IfExp)
             ):
                 local_complexity += 1
 
@@ -199,7 +197,8 @@ class ComplexityCalculator:
             current_depth = depth
 
             if isinstance(
-                node, (ast.If, ast.While, ast.For, ast.AsyncFor, ast.With, ast.Try)
+                node,
+                (ast.If, ast.While, ast.For, ast.AsyncFor, ast.With, ast.Try),
             ):
                 current_depth += 1
                 depths.append(current_depth)
@@ -216,8 +215,8 @@ class ComplexityCalculator:
 
     def _calculate_halstead_metrics(self, tree: ast.AST) -> dict[str, float]:
         """Calculate Halstead complexity metrics."""
-        operators = Counter()
-        operands = Counter()
+        operators: Counter[str] = Counter()
+        operands: Counter[str] = Counter()
 
         for node in ast.walk(tree):
             # Operators
@@ -246,8 +245,8 @@ class ComplexityCalculator:
         # Halstead metrics
         n1 = len(operators)  # Number of unique operators
         n2 = len(operands)  # Number of unique operands
-        N1 = sum(operators.values())  # Total operators
-        N2 = sum(operands.values())  # Total operands
+        N1 = sum(operators.values())  # Total operators  # noqa: N806
+        N2 = sum(operands.values())  # Total operands  # noqa: N806
 
         vocabulary = n1 + n2
         length = N1 + N2
@@ -339,7 +338,8 @@ class ComplexityCalculator:
 
         for node in ast.walk(tree):
             if isinstance(node, ast.Name) and isinstance(
-                node.ctx, (ast.Store, ast.Del)
+                node.ctx,
+                (ast.Store, ast.Del),
             ):
                 variables.add(node.id)
 

src/quality/complexity/metrics.py

@@ -111,14 +111,13 @@ class ComplexityMetrics:
 
         if score < 20:
             return "Low"
-        elif score < 40:
+        if score < 40:
             return "Moderate"
-        elif score < 60:
+        if score < 60:
             return "High"
-        elif score < 80:
+        if score < 80:
             return "Very High"
-        else:
-            return "Extreme"
+        return "Extreme"
 
     def get_priority_score(self) -> float:
         """Get priority score for refactoring (0-1, higher means higher priority)."""
@@ -144,43 +143,43 @@ class ComplexityMetrics:
         if self.cyclomatic_complexity > 10:
             recommendations.append(
                 f"High cyclomatic complexity ({self.cyclomatic_complexity}). "
-                "Consider breaking down complex conditional logic."
+                "Consider breaking down complex conditional logic.",
             )
 
         if self.cognitive_complexity > 15:
             recommendations.append(
                 f"High cognitive complexity ({self.cognitive_complexity}). "
-                "Consider extracting nested logic into separate methods."
+                "Consider extracting nested logic into separate methods.",
             )
 
         if self.max_nesting_depth > 4:
             recommendations.append(
                 f"Deep nesting detected ({self.max_nesting_depth} levels). "
-                "Consider using guard clauses or early returns."
+                "Consider using guard clauses or early returns.",
             )
 
         if self.maintainability_index < 20:
             recommendations.append(
                 f"Low maintainability index ({self.maintainability_index:.1f}). "
-                "Consider refactoring for better readability and simplicity."
+                "Consider refactoring for better readability and simplicity.",
             )
 
         if self.halstead_difficulty > 20:
             recommendations.append(
                 f"High Halstead difficulty ({self.halstead_difficulty:.1f}). "
-                "Code may be hard to understand and maintain."
+                "Code may be hard to understand and maintain.",
             )
 
         if self.function_count == 0 and self.lines_of_code > 50:
             recommendations.append(
                 "Large code block without functions. "
-                "Consider extracting reusable functions."
+                "Consider extracting reusable functions.",
             )
 
         if self.parameters_count > 5:
             recommendations.append(
                 f"Many parameters ({self.parameters_count}). "
-                "Consider using parameter objects or configuration classes."
+                "Consider using parameter objects or configuration classes.",
             )
 
         return recommendations

src/quality/complexity/radon_integration.py

@@ -28,10 +28,10 @@ class RadonComplexityAnalyzer:
         """Analyze code complexity using Radon or fallback to manual calculation."""
         if RADON_AVAILABLE:
             return self._analyze_with_radon(code, filename)
-        elif self.fallback_to_manual:
+        if self.fallback_to_manual:
             return self.manual_calculator.calculate_complexity(code)
-        else:
-            raise ImportError("Radon is not available and fallback is disabled")
+        msg = "Radon is not available and fallback is disabled"
+        raise ImportError(msg)
 
     def analyze_file(self, file_path: Path) -> ComplexityMetrics:
         """Analyze complexity of a file."""
@@ -39,11 +39,11 @@ class RadonComplexityAnalyzer:
             with open(file_path, encoding="utf-8") as f:
                 code = f.read()
             return self.analyze_code(code, str(file_path))
-        except Exception:
+        except (OSError, PermissionError, UnicodeDecodeError):
             # Return empty metrics for unreadable files
             return ComplexityMetrics()
 
-    def _analyze_with_radon(self, code: str, filename: str) -> ComplexityMetrics:
+    def _analyze_with_radon(self, code: str, filename: str) -> ComplexityMetrics:  # noqa: ARG002
         """Analyze code using Radon library."""
         metrics = ComplexityMetrics()
 
@@ -66,7 +66,7 @@ class RadonComplexityAnalyzer:
 
                 # Count functions and classes
                 metrics.function_count = len(
-                    [b for b in cc_results if b.is_method or b.type == "function"]
+                    [b for b in cc_results if b.is_method or b.type == "function"],
                 )
                 metrics.class_count = len([b for b in cc_results if b.type == "class"])
                 metrics.method_count = len([b for b in cc_results if b.is_method])
@@ -80,7 +80,7 @@ class RadonComplexityAnalyzer:
                     metrics.halstead_volume = halstead_data.volume
                     metrics.halstead_time = halstead_data.time
                     metrics.halstead_bugs = halstead_data.bugs
-            except Exception:
+            except (ValueError, TypeError, AttributeError):
                 # Halstead calculation can fail for some code patterns
                 pass
 
@@ -89,24 +89,25 @@ class RadonComplexityAnalyzer:
                 mi_data = mi_visit(code, multi=True)
                 if mi_data and hasattr(mi_data, "mi"):
                     metrics.maintainability_index = mi_data.mi
-            except Exception:
+            except (ValueError, TypeError, AttributeError):
                 # MI calculation can fail, calculate manually
                 metrics.maintainability_index = self._calculate_mi_fallback(metrics)
 
             # Calculate additional metrics manually
             metrics = self._enhance_with_manual_metrics(code, metrics)
 
-        except Exception:
+        except (ValueError, TypeError, SyntaxError, AttributeError):
             # If Radon fails completely, fallback to manual calculation
             if self.fallback_to_manual:
                 return self.manual_calculator.calculate_complexity(code)
-            else:
-                raise
+            raise
 
         return metrics
 
     def _enhance_with_manual_metrics(
-        self, code: str, metrics: ComplexityMetrics
+        self,
+        code: str,
+        metrics: ComplexityMetrics,
     ) -> ComplexityMetrics:
         """Add metrics not provided by Radon using manual calculation."""
         import ast
@@ -127,14 +128,15 @@ class RadonComplexityAnalyzer:
                 if isinstance(node, ast.FunctionDef | ast.AsyncFunctionDef):
                     metrics.parameters_count += len(node.args.args)
                     metrics.returns_count += len(
-                        [n for n in ast.walk(node) if isinstance(n, ast.Return)]
+                        [n for n in ast.walk(node) if isinstance(n, ast.Return)],
                     )
 
             # Count variables
             variables = set()
             for node in ast.walk(tree):
                 if isinstance(node, ast.Name) and isinstance(
-                    node.ctx, ast.Store | ast.Del
+                    node.ctx,
+                    ast.Store | ast.Del,
                 ):
                     variables.add(node.id)
             metrics.variables_count = len(variables)
@@ -165,10 +167,8 @@ class RadonComplexityAnalyzer:
                 local_complexity += 1 + depth
             elif isinstance(node, ast.BoolOp):
                 local_complexity += len(node.values) - 1
-            elif (
-                isinstance(node, ast.Lambda)
-                or isinstance(node, ast.Expr)
-                and isinstance(node.value, ast.IfExp)
+            elif isinstance(node, ast.Lambda) or (
+                isinstance(node, ast.Expr) and isinstance(node.value, ast.IfExp)
             ):
                 local_complexity += 1
 
@@ -203,7 +203,8 @@ class RadonComplexityAnalyzer:
             current_depth = depth
 
             if isinstance(
-                node, ast.If | ast.While | ast.For | ast.AsyncFor | ast.With | ast.Try
+                node,
+                ast.If | ast.While | ast.For | ast.AsyncFor | ast.With | ast.Try,
             ):
                 current_depth += 1
                 depths.append(current_depth)
@@ -243,19 +244,20 @@ class RadonComplexityAnalyzer:
             # Manual ranking
             if complexity_score <= 5:
                 return "A"  # Low
-            elif complexity_score <= 10:
+            if complexity_score <= 10:
                 return "B"  # Moderate
-            elif complexity_score <= 20:
+            if complexity_score <= 20:
                 return "C"  # High
-            elif complexity_score <= 30:
+            if complexity_score <= 30:
                 return "D"  # Very High
-            else:
-                return "F"  # Extreme
+            return "F"  # Extreme
 
-        return cc_rank(complexity_score)
+        return str(cc_rank(complexity_score))
 
     def batch_analyze_files(
-        self, file_paths: list[Path], max_workers: int | None = None
+        self,
+        file_paths: list[Path],
+        max_workers: int | None = None,
     ) -> dict[Path, ComplexityMetrics]:
         """Analyze multiple files in parallel."""
         import concurrent.futures
@@ -277,14 +279,16 @@ class RadonComplexityAnalyzer:
                 path = future_to_path[future]
                 try:
                     results[path] = future.result()
-                except Exception:
+                except (OSError, PermissionError, UnicodeDecodeError):
                     # Create empty metrics for failed files
                     results[path] = ComplexityMetrics()
 
         return results
 
     def get_detailed_complexity_report(
-        self, code: str, filename: str = "<string>"
+        self,
+        code: str,
+        filename: str = "<string>",
     ) -> dict[str, Any]:
         """Get detailed complexity report including function-level analysis."""
         if not RADON_AVAILABLE:
@@ -319,7 +323,7 @@ class RadonComplexityAnalyzer:
                     functions.append(item)
                 elif block.type == "class":
                     classes.append(item)
-        except Exception:
+        except (ValueError, TypeError, AttributeError):
             pass
 
         return {

src/quality/config/default_config.yaml

@@ -25,7 +25,7 @@ detection:
       enabled: true
 
   # Performance settings - Optimized LSH parameters
-  use_lsh: true                   # Use LSH for large codebases  
+  use_lsh: true                   # Use LSH for large codebases
   lsh_threshold: 500             # Use LSH when blocks > this number (reduced for better coverage)
   lsh_bands: 20                  # Number of LSH bands (increased for better precision)
   lsh_rows: 4                    # Rows per band (decreased to balance precision/recall)

src/quality/config/schemas.py

@@ -3,11 +3,7 @@
 from pathlib import Path
 
 import yaml
-from pydantic import BaseModel, field_validator
-try:
-    from pydantic import Field
-except ImportError:
-    from pydantic.v1 import Field
+from pydantic import BaseModel, Field, field_validator
 
 
 class SimilarityAlgorithmConfig(BaseModel):
@@ -43,13 +39,14 @@ class DetectionConfig(BaseModel):
             SimilarityAlgorithmConfig(name="jaccard", weight=0.3),
             SimilarityAlgorithmConfig(name="cosine", weight=0.3),
             SimilarityAlgorithmConfig(name="semantic", weight=0.2),
-        ]
+        ],
     )
 
     # Performance settings
     use_lsh: bool = True
     lsh_threshold: int = Field(
-        default=1000, ge=100
+        default=1000,
+        ge=100,
     )  # Use LSH for datasets larger than this
     parallel_processing: bool = True
     max_workers: int | None = None
@@ -72,7 +69,7 @@ class LanguageConfig(BaseModel):
             "rust": [".rs"],
             "php": [".php"],
             "ruby": [".rb"],
-        }
+        },
     )
 
 
@@ -90,7 +87,7 @@ class PathConfig(BaseModel):
             "**/.git/**",
             "**/build/**",
             "**/dist/**",
-        ]
+        ],
     )
     max_files: int | None = None
     follow_symlinks: bool = False
@@ -179,7 +176,7 @@ class ExceptionsConfig(BaseModel):
 
     # Temporary suppressions (auto-expire)
     temporary_suppressions: dict[str, str] = Field(
-        default_factory=dict
+        default_factory=dict,
     )  # rule_id -> expiry_date
 
 
@@ -203,7 +200,7 @@ class QualityConfig(BaseModel):
     verbose: bool = False
 
     @field_validator("detection")
-    def validate_similarity_weights(cls, v):
+    def validate_similarity_weights(self, v: DetectionConfig) -> DetectionConfig:
         """Ensure similarity algorithm weights sum to approximately 1.0."""
         total_weight = sum(alg.weight for alg in v.similarity_algorithms if alg.enabled)
         if abs(total_weight - 1.0) > 0.1:
@@ -239,18 +236,17 @@ def load_config(config_path: Path | None = None) -> QualityConfig:
 
     if config_path and config_path.exists():
         return _load_from_file(config_path)
-    else:
-        return QualityConfig()
+    return QualityConfig()
 
 
 def _load_from_file(config_path: Path) -> QualityConfig:
     """Load configuration from specific file."""
     if config_path.suffix.lower() in [".yaml", ".yml"]:
         return _load_from_yaml(config_path)
-    elif config_path.name == "pyproject.toml":
+    if config_path.name == "pyproject.toml":
         return _load_from_pyproject(config_path)
-    else:
-        raise ValueError(f"Unsupported config file format: {config_path}")
+    msg = f"Unsupported config file format: {config_path}"
+    raise ValueError(msg)
 
 
 def _load_from_yaml(config_path: Path) -> QualityConfig:
@@ -264,14 +260,17 @@ def _load_from_yaml(config_path: Path) -> QualityConfig:
 def _load_from_pyproject(config_path: Path) -> QualityConfig:
     """Load configuration from pyproject.toml file."""
     try:
-        import tomli
+        import tomllib as tomli  # Python 3.11+
     except ImportError:
         try:
-            import tomllib as tomli
+            import tomli  # type: ignore[import-not-found, no-redef]
         except ImportError as e:
-            raise ImportError(
+            msg = (
                 "tomli package required to read pyproject.toml. "
                 "Install with: pip install tomli"
+            )
+            raise ImportError(
+                msg,
             ) from e
 
     with open(config_path, "rb") as f:

src/quality/core/__init__.py

@@ -12,8 +12,8 @@ from .base import (
 from .cache import CacheManager
 
 __all__ = [
-    "AnalysisResult",
     "ASTAnalyzer",
+    "AnalysisResult",
     "CacheManager",
     "CodeBlock",
     "ComplexityMetrics",

src/quality/core/ast_analyzer.py

@@ -1,6 +1,7 @@
 """Enhanced AST analysis for code quality detection."""
 
 import ast
+import logging
 
 from .base import CodeBlock, ComplexityMetrics
 
@@ -18,7 +19,11 @@ class ASTAnalyzer(ast.NodeVisitor):
         self.global_variables: set[str] = set()
         self.call_graph: dict[str, list[str]] = {}
 
-    def extract_code_blocks(self, file_path, min_lines: int = 5) -> list[CodeBlock]:
+    def extract_code_blocks(
+        self,
+        file_path: str,
+        min_lines: int = 5,
+    ) -> list[CodeBlock]:
         """Extract code blocks from a file."""
         try:
             with open(file_path, encoding="utf-8") as f:
@@ -27,7 +32,15 @@ class ASTAnalyzer(ast.NodeVisitor):
             return []
 
         # Reset analyzer state
-        self.__init__(str(file_path), content)
+        self.file_path = str(file_path)
+        self.content = content
+        self.content_lines = content.splitlines()
+        self.functions = []
+        self.classes = []
+        self.code_blocks = []
+        self.imports = []
+        self.global_variables = set()
+        self.call_graph = {}
 
         try:
             tree = ast.parse(content)
@@ -50,7 +63,8 @@ class ASTAnalyzer(ast.NodeVisitor):
         cognitive_complexity = self._calculate_cognitive_complexity(node)
 
         metrics = ComplexityMetrics(
-            cyclomatic_complexity=complexity, cognitive_complexity=cognitive_complexity
+            cyclomatic_complexity=complexity,
+            cognitive_complexity=cognitive_complexity,
         )
 
         block = self._extract_code_block(node, node.name, "function", metrics)
@@ -64,7 +78,8 @@ class ASTAnalyzer(ast.NodeVisitor):
         cognitive_complexity = self._calculate_cognitive_complexity(node)
 
         metrics = ComplexityMetrics(
-            cyclomatic_complexity=complexity, cognitive_complexity=cognitive_complexity
+            cyclomatic_complexity=complexity,
+            cognitive_complexity=cognitive_complexity,
         )
 
         block = self._extract_code_block(node, node.name, "function", metrics)
@@ -117,7 +132,7 @@ class ASTAnalyzer(ast.NodeVisitor):
         complexity_metrics: ComplexityMetrics | None = None,
     ) -> CodeBlock:
         """Extract code block from AST node with enhanced metadata."""
-        start_line = node.lineno
+        start_line = getattr(node, "lineno", 1)
         end_line = getattr(node, "end_lineno", start_line)
 
         if end_line is None:
@@ -172,7 +187,8 @@ class ASTAnalyzer(ast.NodeVisitor):
             local_complexity = 0
 
             if isinstance(
-                n, ast.If | ast.While | ast.For | ast.AsyncFor | ast.ExceptHandler
+                n,
+                ast.If | ast.While | ast.For | ast.AsyncFor | ast.ExceptHandler,
             ):
                 local_complexity += 1 + level
             elif isinstance(n, ast.Break | ast.Continue):
@@ -235,7 +251,7 @@ class ASTAnalyzer(ast.NodeVisitor):
 
     def get_variable_usage_pattern(self, node: ast.AST) -> dict[str, int]:
         """Analyze variable usage patterns."""
-        variable_usage = {}
+        variable_usage: dict[str, int] = {}
 
         for child in ast.walk(node):
             if isinstance(child, ast.Name):
@@ -252,7 +268,7 @@ class ASTAnalyzer(ast.NodeVisitor):
         long_methods = [f for f in self.functions if f.lines_count > 30]
         if long_methods:
             smells.append(
-                f"Long methods detected: {len(long_methods)} methods > 30 lines"
+                f"Long methods detected: {len(long_methods)} methods > 30 lines",
             )
 
         # Complex methods
@@ -263,7 +279,8 @@ class ASTAnalyzer(ast.NodeVisitor):
         ]
         if complex_methods:
             smells.append(
-                f"Complex methods detected: {len(complex_methods)} methods with complexity > 10"
+                f"Complex methods detected: {len(complex_methods)} methods "
+                "with complexity > 10",
             )
 
         # Many parameters
@@ -273,9 +290,10 @@ class ASTAnalyzer(ast.NodeVisitor):
                 for node in ast.walk(tree):
                     if isinstance(node, ast.FunctionDef) and len(node.args.args) > 5:
                         smells.append(
-                            f"Method with many parameters: {func.function_name} ({len(node.args.args)} parameters)"
+                            f"Method with many parameters: {func.function_name} "
+                            f"({len(node.args.args)} parameters)",
                         )
-            except Exception:
-                pass
+            except Exception:  # noqa: BLE001
+                logging.debug("Failed to analyze code smell for %s", self.file_path)
 
         return smells

src/quality/core/base.py

@@ -48,7 +48,7 @@ class ComplexityMetrics:
     @property
     def complexity_score(self) -> float:
         """Calculate overall complexity score."""
-        score = self.cyclomatic_complexity
+        score: float = float(self.cyclomatic_complexity)
         if self.cognitive_complexity:
             score += self.cognitive_complexity * 0.5
         if self.halstead_difficulty:
@@ -72,7 +72,7 @@ class CodeBlock:
 
     def __post_init__(self) -> None:
         """Initialize computed fields."""
-        self.content_hash = hashlib.md5(self.content.encode()).hexdigest()
+        self.content_hash = hashlib.sha256(self.content.encode()).hexdigest()
         self.normalized_content = self._normalize_content()
 
     def _normalize_content(self) -> str:
@@ -93,30 +93,59 @@ class CodeBlock:
         content = re.sub(r"'[^']*'", "'STRING'", content)
 
         # Normalize numeric literals
-        content = re.sub(r'\b\d+\.?\d*\b', 'NUM', content)
+        content = re.sub(r"\b\d+\.?\d*\b", "NUM", content)
 
         # Abstract variable names while preserving keywords and operators
         python_keywords = {
-            'def', 'class', 'if', 'else', 'elif', 'for', 'while', 'try', 'except',
-            'finally', 'with', 'as', 'import', 'from', 'return', 'yield', 'pass',
-            'break', 'continue', 'and', 'or', 'not', 'in', 'is', 'lambda', 'None',
-            'True', 'False', 'self', 'cls'
+            "def",
+            "class",
+            "if",
+            "else",
+            "elif",
+            "for",
+            "while",
+            "try",
+            "except",
+            "finally",
+            "with",
+            "as",
+            "import",
+            "from",
+            "return",
+            "yield",
+            "pass",
+            "break",
+            "continue",
+            "and",
+            "or",
+            "not",
+            "in",
+            "is",
+            "lambda",
+            "None",
+            "True",
+            "False",
+            "self",
+            "cls",
         }
-        
+
         # Split into tokens and normalize identifiers
-        tokens = re.findall(r'\b\w+\b|[^\w\s]', content)
+        tokens = re.findall(r"\b\w+\b|[^\w\s]", content)
         normalized_tokens = []
-        
+
         for token in tokens:
-            if token.lower() in python_keywords or not re.match(r'^[a-zA-Z_]\w*$', token):
+            if token.lower() in python_keywords or not re.match(
+                r"^[a-zA-Z_]\w*$",
+                token,
+            ):
                 # Keep keywords and non-identifiers as-is
                 normalized_tokens.append(token)
             else:
                 # Abstract user-defined identifiers
-                normalized_tokens.append('VAR')
-        
-        content = ' '.join(normalized_tokens)
-        
+                normalized_tokens.append("VAR")
+
+        content = " ".join(normalized_tokens)
+
         # Remove extra whitespace
         content = re.sub(r"\s+", " ", content)
         return content.strip()
@@ -190,7 +219,7 @@ class DuplicateMatch:
                 else 0.0
             )
 
-            # Calculate priority: similarity × complexity × lines
+            # Calculate priority: similarity * complexity * lines
             total_lines = sum(block.lines_count for block in self.blocks)
             self.priority_score = (
                 self.similarity_score * self.complexity_score * (total_lines / 10)

src/quality/core/cache.py

@@ -1,16 +1,17 @@
 """Caching system for performance optimization."""
 
 import hashlib
+import logging
 import pickle
 from pathlib import Path
-from typing import Any, Generic, TypeVar
+from typing import Any, TypeVar, cast
 
 from .base import CodeBlock
 
 T = TypeVar("T")
 
 
-class CacheManager(Generic[T]):
+class CacheManager[T]:
     """Generic cache manager for storing analysis results."""
 
     def __init__(self, cache_dir: Path = Path(".quality_cache")):
@@ -34,11 +35,11 @@ class CacheManager(Generic[T]):
         if cache_file.exists():
             try:
                 with open(cache_file, "rb") as f:
-                    data = pickle.load(f)
+                    data = pickle.load(f)  # noqa: S301
                     if use_memory:
                         self.memory_cache[key] = data
-                    return data
-            except Exception:
+                    return cast("T | None", data)
+            except Exception:  # noqa: BLE001  # noqa: BLE001
                 # If cache is corrupted, remove it
                 cache_file.unlink(missing_ok=True)
 
@@ -54,15 +55,15 @@ class CacheManager(Generic[T]):
         try:
             with open(cache_file, "wb") as f:
                 pickle.dump(value, f)
-        except Exception:
-            pass  # Fail silently if can't write to disk
+        except Exception:  # noqa: BLE001
+            logging.debug("Failed to write cache to %s", cache_file)
 
     def get_file_hash(self, file_path: Path) -> str:
         """Get hash of file contents and modification time."""
         try:
             stat = file_path.stat()
-            content_hash = hashlib.md5(file_path.read_bytes()).hexdigest()
-        except Exception:
+            content_hash = hashlib.sha256(file_path.read_bytes()).hexdigest()
+        except Exception:  # noqa: BLE001
             return ""
         else:
             return f"{content_hash}_{stat.st_mtime}"
@@ -84,9 +85,9 @@ class CacheManager(Generic[T]):
         cache_key = self._get_cache_key(str(file_path), "file")
 
         # Cache the blocks
-        self.set(cache_key, blocks)
+        self.set(cache_key, cast("T", blocks))
         # Cache the file metadata
-        self.set(f"{cache_key}_meta", file_hash)
+        self.set(f"{cache_key}_meta", cast("T", file_hash))
 
     def get_cached_file_analysis(self, file_path: Path) -> list[CodeBlock] | None:
         """Get cached file analysis if up-to-date."""
@@ -94,7 +95,8 @@ class CacheManager(Generic[T]):
             return None
 
         cache_key = self._get_cache_key(str(file_path), "file")
-        return self.get(cache_key)
+        result = self.get(cache_key)
+        return cast("list[CodeBlock] | None", result)
 
     def clear(self) -> None:
         """Clear all caches."""
@@ -115,8 +117,8 @@ class CacheManager(Generic[T]):
             try:
                 if (current_time - cache_file.stat().st_mtime) > max_age_seconds:
                     cache_file.unlink()
-            except Exception:
-                pass
+            except Exception:  # noqa: BLE001  # noqa: BLE001
+                logging.debug("Failed to clean cache file: %s", cache_file)
 
     def get_cache_stats(self) -> dict[str, Any]:
         """Get cache statistics."""

src/quality/core/exceptions.py

@@ -2,7 +2,8 @@
 
 import fnmatch
 import re
-from datetime import datetime
+from collections.abc import Callable
+from datetime import UTC, datetime
 from pathlib import Path
 from typing import Any
 
@@ -26,7 +27,7 @@ class ExceptionFilter:
             return []
 
         active_rules = []
-        current_date = datetime.now().date()
+        current_date = datetime.now(UTC).date()
 
         for rule in self.exceptions_config.rules:
             if not rule.enabled:
@@ -35,7 +36,13 @@ class ExceptionFilter:
             # Check if rule has expired
             if rule.expires:
                 try:
-                    expire_date = datetime.strptime(rule.expires, "%Y-%m-%d").date()
+                    expire_date = (
+                        datetime.strptime(rule.expires, "%Y-%m-%d")
+                        .replace(
+                            tzinfo=UTC,
+                        )
+                        .date()
+                    )
                     if current_date > expire_date:
                         continue
                 except ValueError:
@@ -54,8 +61,7 @@ class ExceptionFilter:
         line_number: int,
         line_content: str = "",
     ) -> tuple[bool, str | None]:
-        """
-        Check if an issue should be suppressed.
+        """Check if an issue should be suppressed.
 
         Returns:
             (should_suppress, reason)
@@ -67,7 +73,12 @@ class ExceptionFilter:
         # Check exception rules
         for rule in self.active_rules:
             if self._rule_matches(
-                rule, analysis_type, issue_type, file_path, line_number, line_content
+                rule,
+                analysis_type,
+                issue_type,
+                file_path,
+                line_number,
+                line_content,
             ):
                 return (
                     True,
@@ -83,7 +94,8 @@ class ExceptionFilter:
         # Check excluded files
         for pattern in self.exceptions_config.exclude_files:
             if fnmatch.fnmatch(normalized_path, pattern) or fnmatch.fnmatch(
-                file_path, pattern
+                file_path,
+                pattern,
             ):
                 return True
 
@@ -106,12 +118,12 @@ class ExceptionFilter:
         analysis_type: str,
         issue_type: str | None,
         file_path: str,
-        line_number: int,
+        line_number: int,  # noqa: ARG002
         line_content: str,
     ) -> bool:
         """Check if a rule matches the current issue."""
         # Check analysis type
-        if rule.analysis_type != analysis_type and rule.analysis_type != "*":
+        if rule.analysis_type not in (analysis_type, "*"):
             return False
 
         # Check issue type if specified
@@ -123,7 +135,8 @@ class ExceptionFilter:
             file_matches = False
             for pattern in rule.file_patterns:
                 if fnmatch.fnmatch(file_path, pattern) or fnmatch.fnmatch(
-                    str(Path(file_path).name), pattern
+                    str(Path(file_path).name),
+                    pattern,
                 ):
                     file_matches = True
                     break
@@ -146,13 +159,12 @@ class ExceptionFilter:
         self,
         analysis_type: str,
         issues: list[Any],
-        get_file_path_fn: callable = None,
-        get_line_number_fn: callable = None,
-        get_line_content_fn: callable = None,
-        get_issue_type_fn: callable = None,
+        get_file_path_fn: Callable[[Any], str] | None = None,
+        get_line_number_fn: Callable[[Any], int] | None = None,
+        get_line_content_fn: Callable[[Any], str] | None = None,
+        get_issue_type_fn: Callable[[Any], str | None] | None = None,
     ) -> list[Any]:
-        """
-        Filter a list of issues based on exception rules.
+        """Filter a list of issues based on exception rules.
 
         Args:
             analysis_type: Type of analysis ("complexity", "duplicates", etc.)
@@ -191,15 +203,17 @@ class ExceptionFilter:
             )
 
             should_suppress, reason = self.should_suppress_issue(
-                analysis_type, issue_type, file_path, line_number, line_content
+                analysis_type,
+                issue_type,
+                file_path,
+                line_number,
+                line_content,
             )
 
             if not should_suppress:
                 filtered_issues.append(issue)
             elif self.config.debug:
-                print(
-                    f"Suppressed {analysis_type} issue in {file_path}:{line_number} - {reason}"
-                )
+                pass
 
         return filtered_issues
 
@@ -217,7 +231,7 @@ class ExceptionFilter:
 
     def _summarize_rules_by_type(self) -> dict[str, int]:
         """Summarize rules by analysis type."""
-        summary = {}
+        summary: dict[str, int] = {}
         for rule in self.active_rules:
             analysis_type = rule.analysis_type
             summary[analysis_type] = summary.get(analysis_type, 0) + 1
@@ -274,7 +288,7 @@ def create_example_exceptions_config() -> dict[str, Any]:
                     "expires": "2024-12-31",
                 },
             ],
-        }
+        },
     }
 
 

src/quality/detection/engine.py

@@ -1,6 +1,7 @@
 """Enhanced duplicate detection engine with multiple algorithms."""
 
 import ast
+import logging
 from pathlib import Path
 from typing import Any
 
@@ -8,9 +9,9 @@ from ..complexity.analyzer import ComplexityAnalyzer
 from ..config.schemas import QualityConfig
 from ..core.ast_analyzer import ASTAnalyzer
 from ..core.base import CodeBlock, DuplicateMatch
-from .matcher import DuplicateMatcher
 from ..similarity.base import SimilarityCalculator
 from ..similarity.lsh import LSHDuplicateDetector
+from .matcher import DuplicateMatcher
 
 
 class DuplicateDetectionEngine:
@@ -28,11 +29,13 @@ class DuplicateDetectionEngine:
         # Initialize components
         self.ast_analyzer = ASTAnalyzer()
         self.complexity_analyzer = ComplexityAnalyzer(
-            self.config.complexity, self.config
+            self.config.complexity,
+            self.config,
         )
         self.similarity_calculator = self._create_similarity_calculator()
         self.matcher = DuplicateMatcher(
-            self.similarity_calculator, self.detection_config
+            self.similarity_calculator,
+            self.detection_config,
         )
 
         # LSH for large-scale detection
@@ -46,7 +49,9 @@ class DuplicateDetectionEngine:
             )
 
     def detect_duplicates_in_files(
-        self, file_paths: list[Path], max_workers: int | None = None
+        self,
+        file_paths: list[Path],
+        max_workers: int | None = None,  # noqa: ARG002
     ) -> list[DuplicateMatch]:
         """Detect duplicates across multiple files."""
         # Extract code blocks from all files
@@ -54,7 +59,7 @@ class DuplicateDetectionEngine:
 
         for file_path in file_paths:
             try:
-                blocks = self.ast_analyzer.extract_code_blocks(file_path)
+                blocks = self.ast_analyzer.extract_code_blocks(str(file_path))
                 # Filter blocks by minimum size
                 filtered_blocks = [
                     block
@@ -64,14 +69,16 @@ class DuplicateDetectionEngine:
                     and len(block.content.split()) >= self.detection_config.min_tokens
                 ]
                 all_blocks.extend(filtered_blocks)
-            except Exception:
+            except Exception:  # noqa: BLE001
                 # Skip files that can't be parsed
+                logging.debug("Failed to parse file: %s", file_path)
                 continue
 
         return self.detect_duplicates_in_blocks(all_blocks)
 
     def detect_duplicates_in_blocks(
-        self, blocks: list[CodeBlock]
+        self,
+        blocks: list[CodeBlock],
     ) -> list[DuplicateMatch]:
         """Detect duplicates in a list of code blocks."""
         if not blocks:
@@ -84,11 +91,12 @@ class DuplicateDetectionEngine:
             and self.lsh_detector
         ):
             return self._detect_with_lsh(blocks)
-        else:
-            return self._detect_with_similarity(blocks)
+        return self._detect_with_similarity(blocks)
 
     def find_duplicates_of_block(
-        self, target_block: CodeBlock, candidate_blocks: list[CodeBlock]
+        self,
+        target_block: CodeBlock,
+        candidate_blocks: list[CodeBlock],
     ) -> list[DuplicateMatch]:
         """Find duplicates of a specific code block."""
         matches = []
@@ -98,16 +106,17 @@ class DuplicateDetectionEngine:
                 continue
 
             similarity = self.similarity_calculator.calculate_similarity(
-                target_block, candidate
+                target_block,
+                candidate,
             )
 
             if similarity >= self.detection_config.similarity_threshold:
                 # Calculate complexity metrics
                 target_complexity = self.complexity_analyzer.analyze_code(
-                    target_block.content
+                    target_block.content,
                 )
                 candidate_complexity = self.complexity_analyzer.analyze_code(
-                    candidate.content
+                    candidate.content,
                 )
 
                 match_type = "exact" if similarity >= 0.95 else "similar"
@@ -115,7 +124,10 @@ class DuplicateDetectionEngine:
                     blocks=[target_block, candidate],
                     similarity_score=similarity,
                     match_type=match_type,
-                    description=f"{match_type.title()} duplicate detected (similarity: {similarity:.3f})",
+                    description=(
+                        f"{match_type.title()} duplicate detected "
+                        f"(similarity: {similarity:.3f})"
+                    ),
                     complexity_score=max(
                         target_complexity.get_overall_score(),
                         candidate_complexity.get_overall_score(),
@@ -148,7 +160,7 @@ class DuplicateDetectionEngine:
                     "lines_of_code": block.end_line - block.start_line + 1,
                     "complexity": summary,
                     "content_preview": self._get_content_preview(block.content),
-                }
+                },
             )
 
         # Calculate similarity breakdown
@@ -156,7 +168,8 @@ class DuplicateDetectionEngine:
         if len(duplicate_match.blocks) >= 2:
             similarity_breakdown = (
                 self.similarity_calculator.calculate_detailed_similarity(
-                    duplicate_match.blocks[0], duplicate_match.blocks[1]
+                    duplicate_match.blocks[0],
+                    duplicate_match.blocks[1],
                 )
             )
 
@@ -186,8 +199,9 @@ class DuplicateDetectionEngine:
             SemanticSimilarity,
             StructuralSimilarity,
         )
+        from ..similarity.base import BaseSimilarityAlgorithm
 
-        algorithms = []
+        algorithms: list[BaseSimilarityAlgorithm] = []
 
         for algo_config in self.detection_config.similarity_algorithms:
             if not algo_config.enabled:
@@ -230,7 +244,8 @@ class DuplicateDetectionEngine:
 
             for other in group[1:]:
                 similarity = self.similarity_calculator.calculate_similarity(
-                    representative, other
+                    representative,
+                    other,
                 )
                 similarities.append(similarity)
 
@@ -250,10 +265,15 @@ class DuplicateDetectionEngine:
                 blocks=group,
                 similarity_score=avg_similarity,
                 match_type="lsh_cluster",
-                description=f"LSH cluster with {len(group)} blocks (similarity: {avg_similarity:.3f})",
+                description=(
+                    f"LSH cluster with {len(group)} blocks "
+                    f"(similarity: {avg_similarity:.3f})"
+                ),
                 complexity_score=max_complexity,
                 priority_score=self._calculate_priority_score(
-                    avg_similarity, max_complexity, len(group)
+                    avg_similarity,
+                    max_complexity,
+                    len(group),
                 ),
             )
             matches.append(match)
@@ -266,7 +286,8 @@ class DuplicateDetectionEngine:
         return self._filter_duplicate_matches(matches)
 
     def _filter_duplicate_matches(
-        self, matches: list[DuplicateMatch]
+        self,
+        matches: list[DuplicateMatch],
     ) -> list[DuplicateMatch]:
         """Filter duplicate matches based on exception rules."""
         if not self.exception_filter:
@@ -295,7 +316,10 @@ class DuplicateDetectionEngine:
         return filtered_matches
 
     def _calculate_priority_score(
-        self, similarity: float, complexity: float, block_count: int
+        self,
+        similarity: float,
+        complexity: float,
+        block_count: int,
     ) -> float:
         """Calculate priority score for refactoring."""
         # Base score from similarity
@@ -312,10 +336,11 @@ class DuplicateDetectionEngine:
         return min(priority, 1.0)
 
     def _generate_refactoring_suggestions(
-        self, duplicate_match: DuplicateMatch
+        self,
+        duplicate_match: DuplicateMatch,
     ) -> list[str]:
         """Generate refactoring suggestions for duplicate code."""
-        suggestions = []
+        suggestions: list[str] = []
 
         if len(duplicate_match.blocks) < 2:
             return suggestions
@@ -334,10 +359,10 @@ class DuplicateDetectionEngine:
 
             if has_function:
                 suggestions.append(
-                    "Extract common function into a shared utility module"
+                    "Extract common function into a shared utility module",
                 )
                 suggestions.append(
-                    "Consider creating a base function with configurable parameters"
+                    "Consider creating a base function with configurable parameters",
                 )
             elif has_class:
                 suggestions.append("Extract common class into a base class or mixin")
@@ -345,19 +370,20 @@ class DuplicateDetectionEngine:
             else:
                 suggestions.append("Extract duplicate code into a reusable function")
                 suggestions.append(
-                    "Consider creating a utility module for shared logic"
+                    "Consider creating a utility module for shared logic",
                 )
 
             # Complexity-based suggestions
             if duplicate_match.complexity_score > 60:
                 suggestions.append(
-                    "High complexity detected - consider breaking down into smaller functions"
+                    "High complexity detected - consider breaking down into "
+                    "smaller functions",
                 )
 
             # Similarity-based suggestions
             if duplicate_match.similarity_score > 0.95:
                 suggestions.append(
-                    "Nearly identical code - prioritize for immediate refactoring"
+                    "Nearly identical code - prioritize for immediate refactoring",
                 )
             elif duplicate_match.similarity_score > 0.8:
                 suggestions.append("Similar code - consider parameterizing differences")
@@ -378,12 +404,11 @@ class DuplicateDetectionEngine:
 
         if total_lines < 20:
             return "Low (1-2 hours)"
-        elif total_lines < 100:
+        if total_lines < 100:
             return "Medium (0.5-1 day)"
-        elif total_lines < 500:
+        if total_lines < 500:
             return "High (1-3 days)"
-        else:
-            return "Very High (1+ weeks)"
+        return "Very High (1+ weeks)"
 
     def _assess_refactoring_risk(self, duplicate_match: DuplicateMatch) -> str:
         """Assess risk level of refactoring."""
@@ -399,16 +424,15 @@ class DuplicateDetectionEngine:
             risk_factors.append("Moderate differences between duplicates")
 
         # Check if duplicates span multiple files
-        unique_files = len(set(block.file_path for block in duplicate_match.blocks))
+        unique_files = len({block.file_path for block in duplicate_match.blocks})
         if unique_files > 3:
             risk_factors.append("Cross-module dependencies")
 
         if not risk_factors:
             return "Low"
-        elif len(risk_factors) <= 2:
+        if len(risk_factors) <= 2:
             return "Medium"
-        else:
-            return "High"
+        return "High"
 
     def _get_content_preview(self, content: str, max_lines: int = 5) -> str:
         """Get a preview of code content."""

src/quality/detection/matcher.py

@@ -12,7 +12,9 @@ class DuplicateMatcher:
     """Handles matching logic for finding duplicates."""
 
     def __init__(
-        self, similarity_calculator: SimilarityCalculator, config: DetectionConfig
+        self,
+        similarity_calculator: SimilarityCalculator,
+        config: DetectionConfig,
     ):
         self.similarity_calculator = similarity_calculator
         self.config = config
@@ -32,7 +34,8 @@ class DuplicateMatcher:
                     continue
 
                 similarity = self.similarity_calculator.calculate_similarity(
-                    block1, block2
+                    block1,
+                    block2,
                 )
 
                 if similarity >= self.config.similarity_threshold:
@@ -41,7 +44,10 @@ class DuplicateMatcher:
                         blocks=[block1, block2],
                         similarity_score=similarity,
                         match_type=match_type,
-                        description=f"{match_type.title()} match between 2 blocks (similarity: {similarity:.3f})",
+                        description=(
+                            f"{match_type.title()} match between 2 blocks "
+                            f"(similarity: {similarity:.3f})"
+                        ),
                         complexity_score=0.0,  # Will be calculated by engine
                         priority_score=similarity,
                     )
@@ -51,7 +57,9 @@ class DuplicateMatcher:
         return self._merge_overlapping_matches(matches)
 
     def find_duplicates_of_block(
-        self, target_block: CodeBlock, candidate_blocks: list[CodeBlock]
+        self,
+        target_block: CodeBlock,
+        candidate_blocks: list[CodeBlock],
     ) -> list[DuplicateMatch]:
         """Find duplicates of a specific block."""
         matches = []
@@ -61,7 +69,8 @@ class DuplicateMatcher:
                 continue
 
             similarity = self.similarity_calculator.calculate_similarity(
-                target_block, candidate
+                target_block,
+                candidate,
             )
 
             if similarity >= self.config.similarity_threshold:
@@ -70,7 +79,10 @@ class DuplicateMatcher:
                     blocks=[target_block, candidate],
                     similarity_score=similarity,
                     match_type=match_type,
-                    description=f"{match_type.title()} match with target block (similarity: {similarity:.3f})",
+                    description=(
+                        f"{match_type.title()} match with target block "
+                        f"(similarity: {similarity:.3f})"
+                    ),
                     complexity_score=0.0,
                     priority_score=similarity,
                 )
@@ -92,7 +104,8 @@ class DuplicateMatcher:
                 continue
 
             similarity = self.similarity_calculator.calculate_similarity(
-                target_block, candidate
+                target_block,
+                candidate,
             )
 
             if similarity >= threshold:
@@ -112,7 +125,8 @@ class DuplicateMatcher:
         for i, block1 in enumerate(blocks):
             for j, block2 in enumerate(blocks[i + 1 :], i + 1):
                 similarity = self.similarity_calculator.calculate_similarity(
-                    block1, block2
+                    block1,
+                    block2,
                 )
                 similarity_matrix[(i, j)] = similarity
 
@@ -158,13 +172,13 @@ class DuplicateMatcher:
                 "value": match.similarity_score,
                 "weight": 0.4,
                 "contribution": similarity_confidence * 0.4,
-            }
+            },
         )
         total_confidence += similarity_confidence * 0.4
 
         # Length-based confidence (longer matches are more reliable)
         avg_length = sum(len(block.content) for block in match.blocks) / len(
-            match.blocks
+            match.blocks,
         )
         length_confidence = min(avg_length / 1000, 1.0)  # Normalize to [0,1]
         confidence_factors.append(
@@ -173,13 +187,13 @@ class DuplicateMatcher:
                 "value": avg_length,
                 "weight": 0.2,
                 "contribution": length_confidence * 0.2,
-            }
+            },
         )
         total_confidence += length_confidence * 0.2
 
         # Token count confidence
         avg_tokens = sum(len(block.content.split()) for block in match.blocks) / len(
-            match.blocks
+            match.blocks,
         )
         token_confidence = min(avg_tokens / 100, 1.0)  # Normalize to [0,1]
         confidence_factors.append(
@@ -188,7 +202,7 @@ class DuplicateMatcher:
                 "value": avg_tokens,
                 "weight": 0.2,
                 "contribution": token_confidence * 0.2,
-            }
+            },
         )
         total_confidence += token_confidence * 0.2
 
@@ -200,7 +214,7 @@ class DuplicateMatcher:
                 "value": match.complexity_score,
                 "weight": 0.2,
                 "contribution": complexity_confidence * 0.2,
-            }
+            },
         )
         total_confidence += complexity_confidence * 0.2
 
@@ -211,7 +225,8 @@ class DuplicateMatcher:
         }
 
     def _merge_overlapping_matches(
-        self, matches: list[DuplicateMatch]
+        self,
+        matches: list[DuplicateMatch],
     ) -> list[DuplicateMatch]:
         """Merge matches that share code blocks."""
         if len(matches) <= 1:
@@ -274,7 +289,10 @@ class DuplicateMatcher:
                     blocks=unique_blocks,
                     similarity_score=avg_score,
                     match_type="merged_cluster",
-                    description=f"Merged cluster with {len(unique_blocks)} blocks (avg similarity: {avg_score:.3f})",
+                    description=(
+                        f"Merged cluster with {len(unique_blocks)} blocks "
+                        f"(avg similarity: {avg_score:.3f})"
+                    ),
                     complexity_score=max(complexity_scores)
                     if complexity_scores
                     else 0.0,
@@ -288,9 +306,8 @@ class DuplicateMatcher:
         """Get human-readable confidence level."""
         if confidence >= 0.8:
             return "High"
-        elif confidence >= 0.6:
+        if confidence >= 0.6:
             return "Medium"
-        elif confidence >= 0.4:
+        if confidence >= 0.4:
             return "Low"
-        else:
-            return "Very Low"
+        return "Very Low"

src/quality/similarity/__init__.py

@@ -34,30 +34,30 @@ from .token_based import (
 )
 
 __all__ = [
+    "BandingLSH",
     # Base classes
     "BaseSimilarityAlgorithm",
-    "SimilarityCalculator",
-    # Text-based algorithms
-    "LevenshteinSimilarity",
-    "DifflibSimilarity",
-    "LongestCommonSubsequence",
-    "NGramSimilarity",
-    # Token-based algorithms
-    "JaccardSimilarity",
     "CosineSimilarity",
-    "TFIDFSimilarity",
-    "ShingleSimilarity",
-    # Structural algorithms
-    "StructuralSimilarity",
-    "TreeEditDistance",
     "DependencySimilarity",
-    "IdentifierSimilarity",
-    # Semantic algorithms
-    "SemanticSimilarity",
+    "DifflibSimilarity",
     "FunctionalSimilarity",
     "HashSimilarity",
+    "IdentifierSimilarity",
+    # Token-based algorithms
+    "JaccardSimilarity",
+    "LSHDuplicateDetector",
     # LSH algorithms
     "LSHSimilarity",
-    "LSHDuplicateDetector",
-    "BandingLSH",
+    # Text-based algorithms
+    "LevenshteinSimilarity",
+    "LongestCommonSubsequence",
+    "NGramSimilarity",
+    # Semantic algorithms
+    "SemanticSimilarity",
+    "ShingleSimilarity",
+    "SimilarityCalculator",
+    # Structural algorithms
+    "StructuralSimilarity",
+    "TFIDFSimilarity",
+    "TreeEditDistance",
 ]

src/quality/similarity/base.py

@@ -1,5 +1,6 @@
 """Base similarity calculation framework."""
 
+import logging
 from abc import ABC, abstractmethod
 from typing import Any
 
@@ -12,7 +13,7 @@ class BaseSimilarityAlgorithm(ABC):
 
     def __init__(self, config: SimilarityAlgorithmConfig | None = None):
         self.config = config or SimilarityAlgorithmConfig(
-            name=self.__class__.__name__.lower()
+            name=self.__class__.__name__.lower(),
         )
 
     @abstractmethod
@@ -62,18 +63,25 @@ class SimilarityCalculator:
 
             try:
                 score = algorithm.calculate(
-                    block1.normalized_content, block2.normalized_content
+                    block1.normalized_content,
+                    block2.normalized_content,
                 )
                 total_score += score * algorithm.weight
                 total_weight += algorithm.weight
-            except Exception:
+            except Exception:  # noqa: BLE001
                 # Skip algorithm if it fails
+                logging.debug(
+                    "Algorithm %s failed for similarity calculation",
+                    algorithm.__class__.__name__,
+                )
                 continue
 
         return total_score / total_weight if total_weight > 0 else 0.0
 
     def calculate_detailed_similarity(
-        self, block1: CodeBlock, block2: CodeBlock
+        self,
+        block1: CodeBlock,
+        block2: CodeBlock,
     ) -> dict[str, float]:
         """Calculate similarity with breakdown by algorithm."""
         results = {}
@@ -84,10 +92,16 @@ class SimilarityCalculator:
 
             try:
                 score = algorithm.calculate(
-                    block1.normalized_content, block2.normalized_content
+                    block1.normalized_content,
+                    block2.normalized_content,
                 )
                 results[algorithm.name] = score
-            except Exception:
+            except Exception:  # noqa: BLE001
+                logging.debug(
+                    "Algorithm %s failed: %s",
+                    algorithm.name,
+                    "returning 0.0",
+                )
                 results[algorithm.name] = 0.0
 
         # Calculate weighted average

src/quality/similarity/lsh.py

@@ -5,7 +5,7 @@ from collections import defaultdict
 from typing import Any
 
 try:
-    from datasketch import MinHash, MinHashLSH
+    from datasketch import MinHash, MinHashLSH  # type: ignore[import-not-found]
 
     LSH_AVAILABLE = True
 except ImportError:
@@ -36,7 +36,7 @@ class LSHSimilarity(BaseSimilarityAlgorithm):
 
         # Initialize LSH index
         self.lsh_index = None
-        self.minhashes = {}
+        self.minhashes: dict[str, Any] = {}
 
         if LSH_AVAILABLE:
             self._initialize_lsh()
@@ -45,7 +45,8 @@ class LSHSimilarity(BaseSimilarityAlgorithm):
         """Initialize LSH index."""
         if LSH_AVAILABLE:
             self.lsh_index = MinHashLSH(
-                threshold=self.threshold, num_perm=self.num_perm
+                threshold=self.threshold,
+                num_perm=self.num_perm,
             )
 
     def calculate(self, text1: str, text2: str) -> float:
@@ -62,9 +63,9 @@ class LSHSimilarity(BaseSimilarityAlgorithm):
         minhash1 = self._create_minhash(text1)
         minhash2 = self._create_minhash(text2)
 
-        return minhash1.jaccard(minhash2)
+        return float(minhash1.jaccard(minhash2))
 
-    def _create_minhash(self, text: str) -> Any:
+    def _create_minhash(self, text: str) -> Any:  # noqa: ANN401
         """Create MinHash for text."""
         if not LSH_AVAILABLE:
             return None
@@ -127,8 +128,8 @@ class LSHDuplicateDetector:
         self.rows = rows
 
         self.lsh_index = None
-        self.minhashes = {}
-        self.code_blocks = {}
+        self.minhashes: dict[str, Any] = {}
+        self.code_blocks: dict[str, CodeBlock] = {}
 
         if LSH_AVAILABLE:
             self.lsh_index = MinHashLSH(threshold=threshold, num_perm=num_perm)
@@ -218,7 +219,7 @@ class LSHDuplicateDetector:
             else 0,
         }
 
-    def _create_minhash(self, text: str) -> Any:
+    def _create_minhash(self, text: str) -> Any:  # noqa: ANN401
         """Create MinHash for text."""
         if not LSH_AVAILABLE:
             return None
@@ -248,7 +249,7 @@ class LSHDuplicateDetector:
     def _get_block_id(self, block: CodeBlock) -> str:
         """Generate unique ID for code block."""
         content = f"{block.file_path}:{block.start_line}:{block.end_line}"
-        return hashlib.md5(content.encode()).hexdigest()
+        return hashlib.sha256(content.encode()).hexdigest()
 
 
 class BandingLSH:
@@ -266,8 +267,9 @@ class BandingLSH:
     def add_signature(self, item_id: str, signature: list[int]) -> None:
         """Add signature to LSH buckets."""
         if len(signature) != self.bands * self.rows:
+            msg = f"Signature length {len(signature)} != {self.bands * self.rows}"
             raise ValueError(
-                f"Signature length {len(signature)} != {self.bands * self.rows}"
+                msg,
             )
 
         self.signatures[item_id] = signature

src/quality/similarity/semantic.py

@@ -54,9 +54,7 @@ class SemanticSimilarity(BaseSimilarityAlgorithm):
         code = re.sub(r"'[^']*'", "STR", code)
 
         # Normalize numbers
-        code = re.sub(r"\b\d+\.?\d*\b", "NUM", code)
-
-        return code
+        return re.sub(r"\b\d+\.?\d*\b", "NUM", code)
 
     def _pattern_similarity(self, normalized1: str, normalized2: str) -> float:
         """Compare normalized code patterns."""
@@ -96,11 +94,11 @@ class SemanticSimilarity(BaseSimilarityAlgorithm):
         if magnitude1 == 0 or magnitude2 == 0:
             return 0.0
 
-        return dot_product / (magnitude1 * magnitude2)
+        return float(dot_product / (magnitude1 * magnitude2))
 
     def _extract_concepts(self, code: str) -> Counter[str]:
         """Extract conceptual elements from code."""
-        concepts = Counter()
+        concepts: Counter[str] = Counter()
 
         # Python keywords and operations
         python_concepts = {
@@ -139,7 +137,7 @@ class SemanticSimilarity(BaseSimilarityAlgorithm):
                 concepts[f"keyword:{word}"] += 1
             elif word in ["len", "str", "int", "float", "list", "dict", "set", "tuple"]:
                 concepts[f"builtin:{word}"] += 1
-            elif word.endswith("error") or word.endswith("exception"):
+            elif word.endswith(("error", "exception")):
                 concepts["error_handling"] += 1
             elif word in ["print", "log", "debug", "info", "warn", "error"]:
                 concepts["logging"] += 1
@@ -215,7 +213,8 @@ class SemanticSimilarity(BaseSimilarityAlgorithm):
                 patterns.add("lambda_function")
 
             elif isinstance(
-                node, (ast.FunctionDef, ast.ClassDef, ast.AsyncFunctionDef)
+                node,
+                (ast.FunctionDef, ast.ClassDef, ast.AsyncFunctionDef),
             ):
                 if node.decorator_list:
                     patterns.add("decorator_usage")
@@ -266,7 +265,6 @@ class FunctionalSimilarity(BaseSimilarityAlgorithm):
 
     def _extract_behavioral_patterns(self, tree: ast.AST) -> dict[str, int]:
         """Extract behavioral patterns from AST."""
-
         patterns = {
             "data_access": 0,  # Reading/accessing data
             "data_mutation": 0,  # Modifying data
@@ -297,14 +295,17 @@ class FunctionalSimilarity(BaseSimilarityAlgorithm):
             elif isinstance(node, ast.Try):
                 patterns["exception_handling"] += 1
             elif isinstance(node, ast.BinOp) and isinstance(
-                node.op, (ast.Add, ast.Sub, ast.Mult, ast.Div, ast.Mod, ast.Pow)
+                node.op,
+                (ast.Add, ast.Sub, ast.Mult, ast.Div, ast.Mod, ast.Pow),
             ):
                 patterns["mathematical"] += 1
 
         return patterns
 
     def _compare_behaviors(
-        self, behavior1: dict[str, int], behavior2: dict[str, int]
+        self,
+        behavior1: dict[str, int],
+        behavior2: dict[str, int],
     ) -> float:
         """Compare behavioral patterns."""
         if not any(behavior1.values()) and not any(behavior2.values()):
@@ -329,7 +330,7 @@ class FunctionalSimilarity(BaseSimilarityAlgorithm):
         if magnitude1 == 0 or magnitude2 == 0:
             return 0.0
 
-        return dot_product / (magnitude1 * magnitude2)
+        return float(dot_product / (magnitude1 * magnitude2))
 
 
 class HashSimilarity(BaseSimilarityAlgorithm):
@@ -359,30 +360,34 @@ class HashSimilarity(BaseSimilarityAlgorithm):
 
     def _exact_hash_similarity(self, text1: str, text2: str) -> float:
         """Check for exact content match."""
-        hash1 = hashlib.md5(text1.encode()).hexdigest()
-        hash2 = hashlib.md5(text2.encode()).hexdigest()
+        hash1 = hashlib.sha256(text1.encode()).hexdigest()
+        hash2 = hashlib.sha256(text2.encode()).hexdigest()
         return 1.0 if hash1 == hash2 else 0.0
 
     def _normalized_hash_similarity(self, text1: str, text2: str) -> float:
         """Check for normalized content match."""
         # Normalize whitespace and comments
         normalized1 = re.sub(
-            r"\s+", " ", re.sub(r"#.*$", "", text1, flags=re.MULTILINE)
+            r"\s+",
+            " ",
+            re.sub(r"#.*$", "", text1, flags=re.MULTILINE),
         ).strip()
         normalized2 = re.sub(
-            r"\s+", " ", re.sub(r"#.*$", "", text2, flags=re.MULTILINE)
+            r"\s+",
+            " ",
+            re.sub(r"#.*$", "", text2, flags=re.MULTILINE),
         ).strip()
 
-        hash1 = hashlib.md5(normalized1.encode()).hexdigest()
-        hash2 = hashlib.md5(normalized2.encode()).hexdigest()
+        hash1 = hashlib.sha256(normalized1.encode()).hexdigest()
+        hash2 = hashlib.sha256(normalized2.encode()).hexdigest()
 
         return 1.0 if hash1 == hash2 else 0.0
 
     def _fuzzy_hash_similarity(self, text1: str, text2: str) -> float:
         """Calculate fuzzy hash similarity using character n-grams."""
         # Create character 4-grams for fuzzy matching
-        ngrams1 = set(text1[i : i + 4] for i in range(len(text1) - 3))
-        ngrams2 = set(text2[i : i + 4] for i in range(len(text2) - 3))
+        ngrams1 = {text1[i : i + 4] for i in range(len(text1) - 3)}
+        ngrams2 = {text2[i : i + 4] for i in range(len(text2) - 3)}
 
         if not ngrams1 and not ngrams2:
             return 1.0

src/quality/similarity/structural.py

@@ -37,17 +37,19 @@ class StructuralSimilarity(BaseSimilarityAlgorithm):
     def _extract_structure(self, tree: ast.AST) -> list[str]:
         """Extract enhanced structural patterns from AST."""
         structure = []
-        
+
         # Track nesting depth for better structural comparison
         def visit_node(node: ast.AST, depth: int = 0) -> None:
             depth_prefix = f"d{depth}:" if depth > 0 else ""
-            
+
             if isinstance(node, ast.FunctionDef):
                 # Abstract function names but keep structural information
                 arg_count = len(node.args.args)
                 has_decorators = len(node.decorator_list) > 0
-                structure.append(f"{depth_prefix}function:args{arg_count}:dec{has_decorators}")
-                
+                structure.append(
+                    f"{depth_prefix}function:args{arg_count}:dec{has_decorators}",
+                )
+
                 # Analyze function body patterns
                 body_patterns = []
                 for child in node.body:
@@ -61,99 +63,119 @@ class StructuralSimilarity(BaseSimilarityAlgorithm):
                         body_patterns.append("try")
                     elif isinstance(child, ast.Return):
                         body_patterns.append("return")
-                
+
                 if body_patterns:
-                    structure.append(f"{depth_prefix}body_pattern:{'_'.join(body_patterns[:5])}")
-                
+                    structure.append(
+                        f"{depth_prefix}body_pattern:{'_'.join(body_patterns[:5])}",
+                    )
+
                 # Visit children with increased depth
-                for child in ast.iter_child_nodes(node):
-                    visit_node(child, depth + 1)
-                    
+                for subnode in ast.iter_child_nodes(node):
+                    visit_node(subnode, depth + 1)
+
             elif isinstance(node, ast.AsyncFunctionDef):
                 arg_count = len(node.args.args)
                 has_decorators = len(node.decorator_list) > 0
-                structure.append(f"{depth_prefix}async_function:args{arg_count}:dec{has_decorators}")
-                
-                for child in ast.iter_child_nodes(node):
-                    visit_node(child, depth + 1)
-                    
+                structure.append(
+                    f"{depth_prefix}async_function:args{arg_count}:dec{has_decorators}",
+                )
+
+                for subnode in ast.iter_child_nodes(node):
+                    visit_node(subnode, depth + 1)
+
             elif isinstance(node, ast.ClassDef):
                 # Abstract class names but keep inheritance and structure info
                 base_count = len(node.bases)
                 has_decorators = len(node.decorator_list) > 0
-                structure.append(f"{depth_prefix}class:bases{base_count}:dec{has_decorators}")
-                
+                structure.append(
+                    f"{depth_prefix}class:bases{base_count}:dec{has_decorators}",
+                )
+
                 # Count methods in class
-                method_count = sum(1 for child in node.body if isinstance(child, (ast.FunctionDef, ast.AsyncFunctionDef)))
+                method_count = sum(
+                    1
+                    for child in node.body
+                    if isinstance(child, (ast.FunctionDef, ast.AsyncFunctionDef))
+                )
                 structure.append(f"{depth_prefix}class_methods:{method_count}")
-                
-                for child in ast.iter_child_nodes(node):
-                    visit_node(child, depth + 1)
-                    
+
+                for subnode in ast.iter_child_nodes(node):
+                    visit_node(subnode, depth + 1)
+
             elif isinstance(node, ast.If):
                 # Track conditional structure complexity
                 elif_count = len([n for n in node.orelse if isinstance(n, ast.If)])
                 has_else = any(not isinstance(n, ast.If) for n in node.orelse)
                 structure.append(f"{depth_prefix}if:elif{elif_count}:else{has_else}")
-                
-                for child in ast.iter_child_nodes(node):
-                    visit_node(child, depth + 1)
-                    
+
+                for subnode in ast.iter_child_nodes(node):
+                    visit_node(subnode, depth + 1)
+
             elif isinstance(node, ast.For):
                 # Detect nested loops
-                is_nested = any(isinstance(child, (ast.For, ast.While)) for child in ast.walk(node))
+                is_nested = any(
+                    isinstance(child, (ast.For, ast.While)) for child in ast.walk(node)
+                )
                 structure.append(f"{depth_prefix}for:nested{is_nested}")
-                
-                for child in ast.iter_child_nodes(node):
-                    visit_node(child, depth + 1)
-                    
+
+                for subnode in ast.iter_child_nodes(node):
+                    visit_node(subnode, depth + 1)
+
             elif isinstance(node, ast.While):
-                is_nested = any(isinstance(child, (ast.For, ast.While)) for child in ast.walk(node))
+                is_nested = any(
+                    isinstance(child, (ast.For, ast.While)) for child in ast.walk(node)
+                )
                 structure.append(f"{depth_prefix}while:nested{is_nested}")
-                
-                for child in ast.iter_child_nodes(node):
-                    visit_node(child, depth + 1)
-                    
+
+                for subnode in ast.iter_child_nodes(node):
+                    visit_node(subnode, depth + 1)
+
             elif isinstance(node, ast.Try):
                 except_count = len(node.handlers)
                 has_finally = bool(node.finalbody)
                 has_else = bool(node.orelse)
-                structure.append(f"{depth_prefix}try:except{except_count}:finally{has_finally}:else{has_else}")
-                
-                for child in ast.iter_child_nodes(node):
-                    visit_node(child, depth + 1)
-                    
+                structure.append(
+                    f"{depth_prefix}try:except{except_count}:finally{has_finally}:else{has_else}",
+                )
+
+                for subnode in ast.iter_child_nodes(node):
+                    visit_node(subnode, depth + 1)
+
             elif isinstance(node, ast.With):
                 item_count = len(node.items)
                 structure.append(f"{depth_prefix}with:items{item_count}")
-                
-                for child in ast.iter_child_nodes(node):
-                    visit_node(child, depth + 1)
-                    
+
+                for subnode in ast.iter_child_nodes(node):
+                    visit_node(subnode, depth + 1)
+
             elif isinstance(node, ast.Return):
                 has_value = node.value is not None
                 structure.append(f"{depth_prefix}return:value{has_value}")
-                
+
             elif isinstance(node, ast.Assign):
                 target_count = len(node.targets)
                 structure.append(f"{depth_prefix}assign:targets{target_count}")
-                
+
             elif isinstance(node, ast.Call):
                 # Abstract function calls but keep argument structure
                 arg_count = len(node.args)
                 kwarg_count = len(node.keywords)
-                structure.append(f"{depth_prefix}call:args{arg_count}:kwargs{kwarg_count}")
-                
+                structure.append(
+                    f"{depth_prefix}call:args{arg_count}:kwargs{kwarg_count}",
+                )
+
             else:
                 # Visit other node types without adding to structure
-                for child in ast.iter_child_nodes(node):
-                    visit_node(child, depth)
+                for other_node in ast.iter_child_nodes(node):
+                    visit_node(other_node, depth)
 
         visit_node(tree)
         return structure
 
     def _compare_structures(
-        self, structure1: list[str], structure2: list[str]
+        self,
+        structure1: list[str],
+        structure2: list[str],
     ) -> float:
         """Compare two structural patterns."""
         if not structure1 and not structure2:
@@ -396,4 +418,4 @@ class IdentifierSimilarity(BaseSimilarityAlgorithm):
         if magnitude1 == 0 or magnitude2 == 0:
             return 0.0
 
-        return dot_product / (magnitude1 * magnitude2)
+        return float(dot_product / (magnitude1 * magnitude2))

src/quality/similarity/text_based.py

@@ -3,7 +3,7 @@
 import difflib
 
 try:
-    from Levenshtein import ratio as levenshtein_ratio
+    from Levenshtein import ratio as levenshtein_ratio  # type: ignore[import-not-found]
 
     LEVENSHTEIN_AVAILABLE = True
 except ImportError:
@@ -29,10 +29,9 @@ class LevenshteinSimilarity(BaseSimilarityAlgorithm):
             return 0.0
 
         if LEVENSHTEIN_AVAILABLE:
-            return levenshtein_ratio(text1, text2)
-        else:
-            # Fallback to difflib implementation
-            return difflib.SequenceMatcher(None, text1, text2).ratio()
+            return float(levenshtein_ratio(text1, text2))
+        # Fallback to difflib implementation
+        return difflib.SequenceMatcher(None, text1, text2).ratio()
 
 
 class DifflibSimilarity(BaseSimilarityAlgorithm):
@@ -97,7 +96,9 @@ class NGramSimilarity(BaseSimilarityAlgorithm):
     def __init__(self, config: SimilarityAlgorithmConfig | None = None):
         if config is None:
             config = SimilarityAlgorithmConfig(
-                name="ngram", weight=0.2, parameters={"n": 3}
+                name="ngram",
+                weight=0.2,
+                parameters={"n": 3},
             )
         super().__init__(config)
         n_param = self.config.parameters.get("n", 3)

src/quality/similarity/token_based.py

@@ -36,47 +36,85 @@ class JaccardSimilarity(BaseSimilarityAlgorithm):
         return intersection / union if union > 0 else 0.0
 
     def _tokenize(self, text: str) -> list[str]:
-        """Enhanced tokenization with semantic grouping for better duplicate detection."""
+        """Enhanced tokenization with semantic grouping for duplicate detection."""
         import re
 
         # Python keywords and built-ins that should be preserved exactly
         keywords = {
-            'def', 'class', 'if', 'else', 'elif', 'for', 'while', 'try', 'except',
-            'finally', 'with', 'as', 'import', 'from', 'return', 'yield', 'pass',
-            'break', 'continue', 'and', 'or', 'not', 'in', 'is', 'lambda', 'None',
-            'True', 'False', 'self', 'cls', 'len', 'range', 'str', 'int', 'float',
-            'list', 'dict', 'tuple', 'set', 'bool', 'append', 'extend', 'remove'
+            "def",
+            "class",
+            "if",
+            "else",
+            "elif",
+            "for",
+            "while",
+            "try",
+            "except",
+            "finally",
+            "with",
+            "as",
+            "import",
+            "from",
+            "return",
+            "yield",
+            "pass",
+            "break",
+            "continue",
+            "and",
+            "or",
+            "not",
+            "in",
+            "is",
+            "lambda",
+            "None",
+            "True",
+            "False",
+            "self",
+            "cls",
+            "len",
+            "range",
+            "str",
+            "int",
+            "float",
+            "list",
+            "dict",
+            "tuple",
+            "set",
+            "bool",
+            "append",
+            "extend",
+            "remove",
         }
-        
+
         # Semantic variable name patterns (group similar names)
         semantic_patterns = [
-            (r'\b(data|item|element|val|value|obj|object|thing)\w*\b', 'DATA_VAR'),
-            (r'\b(result|output|ret|return|res|response)\w*\b', 'RESULT_VAR'), 
-            (r'\b(index|idx|i|j|k|counter|count|num|number)\w*\b', 'INDEX_VAR'),
-            (r'\b(name|id|key|identifier|label)\w*\b', 'ID_VAR'),
-            (r'\b(config|settings|options|params?|args?|kwargs?)\w*\b', 'CONFIG_VAR'),
-            (r'\b(path|file|dir|directory|filename)\w*\b', 'PATH_VAR'),
-            (r'\b(error|err|exception|ex)\w*\b', 'ERROR_VAR'),
-            (r'\b(temp|tmp|buffer|buf|cache)\w*\b', 'TEMP_VAR'),
-            (r'\b(min|max|avg|sum|total|count)\w*\b', 'CALC_VAR'),
-            (r'\b(user|person|client|customer)\w*\b', 'USER_VAR'),
-            (r'\b(width|height|size|length|dimension)\w*\b', 'SIZE_VAR'),
+            (r"\b(data|item|element|val|value|obj|object|thing)\w*\b", "DATA_VAR"),
+            (r"\b(result|output|ret|return|res|response)\w*\b", "RESULT_VAR"),
+            (r"\b(index|idx|i|j|k|counter|count|num|number)\w*\b", "INDEX_VAR"),
+            (r"\b(name|id|key|identifier|label)\w*\b", "ID_VAR"),
+            (r"\b(config|settings|options|params?|args?|kwargs?)\w*\b", "CONFIG_VAR"),
+            (r"\b(path|file|dir|directory|filename)\w*\b", "PATH_VAR"),
+            (r"\b(error|err|exception|ex)\w*\b", "ERROR_VAR"),
+            (r"\b(temp|tmp|buffer|buf|cache)\w*\b", "TEMP_VAR"),
+            (r"\b(min|max|avg|sum|total|count)\w*\b", "CALC_VAR"),
+            (r"\b(user|person|client|customer)\w*\b", "USER_VAR"),
+            (r"\b(width|height|size|length|dimension)\w*\b", "SIZE_VAR"),
         ]
-        
+
         # First pass: extract all tokens
         tokens = re.findall(r"\b\w+\b", text.lower())
-        
+
         # Second pass: apply semantic grouping and filtering
         processed_tokens = []
         for token in tokens:
             if len(token) <= 1:
                 continue
-                
+
             # Keep keywords and built-ins as-is
             if token in keywords:
                 processed_tokens.append(token)
                 continue
-            
+
             # Apply semantic patterns to group similar variable names
             matched = False
             for pattern, replacement in semantic_patterns:
@@ -84,14 +122,14 @@ class JaccardSimilarity(BaseSimilarityAlgorithm):
                     processed_tokens.append(replacement)
                     matched = True
                     break
-            
+
             if not matched:
                 # Generic variable abstraction for remaining identifiers
-                if re.match(r'^[a-zA-Z_]\w*$', token):
-                    processed_tokens.append('VAR')
+                if re.match(r"^[a-zA-Z_]\w*$", token):
+                    processed_tokens.append("VAR")
                 else:
                     processed_tokens.append(token)
-                    
+
         return processed_tokens
 
 
@@ -204,7 +242,9 @@ class TFIDFSimilarity(BaseSimilarityAlgorithm):
         return {term: count / total_terms for term, count in tf.items()}
 
     def _calculate_idf(
-        self, terms: set[str], documents: list[list[str]]
+        self,
+        terms: set[str],
+        documents: list[list[str]],
     ) -> dict[str, float]:
         """Calculate inverse document frequency."""
         idf = {}
@@ -213,7 +253,7 @@ class TFIDFSimilarity(BaseSimilarityAlgorithm):
         for term in terms:
             docs_containing_term = sum(1 for doc in documents if term in doc)
             idf[term] = math.log(
-                total_docs / (docs_containing_term + 1)
+                total_docs / (docs_containing_term + 1),
             )  # +1 for smoothing
 
         return idf
@@ -225,7 +265,9 @@ class ShingleSimilarity(BaseSimilarityAlgorithm):
     def __init__(self, config: SimilarityAlgorithmConfig | None = None):
         if config is None:
             config = SimilarityAlgorithmConfig(
-                name="shingle", weight=0.2, parameters={"k": 4}
+                name="shingle",
+                weight=0.2,
+                parameters={"k": 4},
             )
         super().__init__(config)
         k_param = self.config.parameters.get("k", 4)

src/quality/utils/file_finder.py

@@ -72,14 +72,16 @@ class FileFinder:
         # Check exclude patterns first
         for pattern in self.path_config.exclude_patterns:
             if fnmatch.fnmatch(path_str, pattern) or fnmatch.fnmatch(
-                file_path.name, pattern
+                file_path.name,
+                pattern,
             ):
                 return False
 
         # Check include patterns
         for pattern in self.path_config.include_patterns:
             if fnmatch.fnmatch(path_str, pattern) or fnmatch.fnmatch(
-                file_path.name, pattern
+                file_path.name,
+                pattern,
             ):
                 # Check if it's a supported file type
                 return self._has_supported_extension(file_path)
@@ -115,7 +117,7 @@ class FileFinder:
 
     def get_project_stats(self, root_path: Path) -> dict[str, Any]:
         """Get statistics about files in the project."""
-        stats = {
+        stats: dict[str, Any] = {
             "total_files": 0,
             "supported_files": 0,
             "excluded_files": 0,
@@ -138,9 +140,9 @@ class FileFinder:
 
             if self._should_include_file(file_path):
                 stats["supported_files"] += 1
-                lang = self.get_file_language(file_path)
-                if lang and lang in stats["by_language"]:
-                    stats["by_language"][lang] += 1
+                file_lang = self.get_file_language(file_path)
+                if file_lang and file_lang in stats["by_language"]:
+                    stats["by_language"][file_lang] += 1
             else:
                 stats["excluded_files"] += 1
 
@@ -163,7 +165,8 @@ class FileFinder:
             if exclude_patterns:
                 for pattern in exclude_patterns:
                     if fnmatch.fnmatch(path_str, pattern) or fnmatch.fnmatch(
-                        file_path.name, pattern
+                        file_path.name,
+                        pattern,
                     ):
                         include = False
                         break
@@ -173,7 +176,8 @@ class FileFinder:
                 include = False
                 for pattern in include_patterns:
                     if fnmatch.fnmatch(path_str, pattern) or fnmatch.fnmatch(
-                        file_path.name, pattern
+                        file_path.name,
+                        pattern,
                     ):
                         include = True
                         break

tests/hooks/README.md

@@ -0,0 +1,118 @@
+# Hook System Test Suite
+
+Comprehensive pytest-based test suite for the Claude Code quality hooks.
+
+## Test Structure
+
+```
+tests/hooks/
+├── conftest.py              # Pytest fixtures and configuration
+├── test_config.py           # QualityConfig class tests
+├── test_pretooluse.py       # PreToolUse hook functionality tests
+├── test_posttooluse.py      # PostToolUse hook functionality tests
+├── test_helper_functions.py # Helper function tests
+└── test_integration.py      # Full integration tests
+```
+
+## Test Coverage
+
+### Configuration Testing (`test_config.py`)
+- Default configuration values
+- Environment variable loading
+- Invalid input handling
+- Threshold boundaries
+- Enforcement modes
+- Configuration combinations
+
+### PreToolUse Testing (`test_pretooluse.py`)
+- Tool filtering (Write/Edit/MultiEdit)
+- File type filtering (Python only)
+- Skip patterns (test files, fixtures)
+- Clean code acceptance
+- Complexity detection
+- Duplicate detection
+- Modernization checks
+- Enforcement modes (strict/warn/permissive)
+- State tracking
+- Exception handling
+
+### PostToolUse Testing (`test_posttooluse.py`)
+- File path extraction (dict/string output)
+- File existence verification
+- State change detection
+- Cross-file duplicate checking
+- Naming convention verification
+- Success message configuration
+- Multi-feature combinations
+
+### Helper Functions (`test_helper_functions.py`)
+- Skip pattern matching
+- Binary path resolution
+- State storage and retrieval
+- State change detection
+- Cross-file duplicate detection
+- Naming convention checks
+- Code quality analysis
+- Issue detection and reporting
+
+### Integration Testing (`test_integration.py`)
+- Main entry point routing
+- Full PreToolUse → PostToolUse flow
+- Environment configuration
+- Tool handling
+- Enforcement mode progression
+- State tracking flow
+- Error handling
+
+## Running Tests
+
+### Run all hook tests:
+```bash
+pytest tests/hooks/ -v
+```
+
+### Run specific test file:
+```bash
+pytest tests/hooks/test_config.py -v
+```
+
+### Run with coverage:
+```bash
+pytest tests/hooks/ --cov=hooks --cov-report=html
+```
+
+### Run specific test:
+```bash
+pytest tests/hooks/test_config.py::TestQualityConfig::test_default_config -v
+```
+
+## Test Fixtures
+
+The `conftest.py` file provides reusable test fixtures:
+
+- `temp_python_file`: Creates temporary Python files
+- `mock_hook_input_pretooluse`: PreToolUse hook input
+- `mock_hook_input_posttooluse`: PostToolUse hook input
+- `complex_code`: Sample complex Python code
+- `duplicate_code`: Code with internal duplicates
+- `clean_code`: Well-written Python code
+- `non_pep8_code`: Code with naming violations
+- `old_style_code`: Outdated Python patterns
+- `test_file_code`: Sample test file
+- `reset_environment`: Auto-reset env vars
+- `set_env_strict`: Configure strict mode
+- `set_env_permissive`: Configure permissive mode
+- `set_env_posttooluse`: Configure PostToolUse features
+
+## Test Results
+
+Current test status: **67/68 passing** (98.5% pass rate)
+
+The test suite ensures:
+- Configuration is properly loaded from environment
+- PreToolUse correctly prevents bad code
+- PostToolUse verifies written files
+- All enforcement modes work correctly
+- State tracking captures quality changes
+- Helper functions work as expected
+- Integration between components is solid

tests/hooks/__init__.py

@@ -0,0 +1 @@
+"""Test package for hooks module."""

tests/hooks/conftest.py

@@ -0,0 +1,267 @@
+"""Pytest configuration and fixtures for hook tests."""
+
+import os
+import sys
+import tempfile
+from collections.abc import Generator
+from pathlib import Path
+from typing import Any
+
+import pytest
+
+# Add hooks directory to path for imports
+sys.path.insert(0, str(Path(__file__).parent.parent.parent / "hooks"))
+
+
+@pytest.fixture
+def temp_python_file() -> Generator[Path, None, None]:
+    """Create a temporary Python file for testing."""
+    with tempfile.NamedTemporaryFile(suffix=".py", delete=False) as tmp:
+        tmp_path = Path(tmp.name)
+    yield tmp_path
+    tmp_path.unlink(missing_ok=True)
+
+
+@pytest.fixture
+def mock_hook_input_pretooluse() -> dict[str, Any]:
+    """Create mock PreToolUse hook input."""
+    return {
+        "tool_name": "Write",
+        "tool_input": {
+            "file_path": "test.py",
+            "content": "def test():\n    pass",
+        },
+    }
+
+
+@pytest.fixture
+def mock_hook_input_posttooluse() -> dict[str, Any]:
+    """Create mock PostToolUse hook input."""
+    return {
+        "tool_name": "Write",
+        "tool_output": {
+            "file_path": "test.py",
+            "status": "success",
+        },
+    }
+
+
+@pytest.fixture
+def complex_code() -> str:
+    """Sample complex code for testing."""
+    return """
+def process_data(data, config, mode, validate, transform, options):
+    if not data:
+        return None
+    if mode == 'simple':
+        if validate:
+            if len(data) > 100:
+                if transform:
+                    if options.get('uppercase'):
+                        return data.upper()
+                    elif options.get('lowercase'):
+                        return data.lower()
+                    else:
+                        return data
+                else:
+                    return data
+            else:
+                if transform and options.get('trim'):
+                    return data.strip()
+                else:
+                    return data
+        else:
+            return data
+    elif mode == 'complex':
+        if validate and len(data) > 50:
+            if transform:
+                if options.get('reverse'):
+                    return data[::-1]
+                elif options.get('double'):
+                    return data * 2
+                else:
+                    return data
+            else:
+                return data
+        else:
+            return data
+    else:
+        return None
+"""
+
+
+@pytest.fixture
+def duplicate_code() -> str:
+    """Sample code with internal duplicates."""
+    return """
+def calculate_user_total(users):
+    total = 0
+    for user in users:
+        if user.active:
+            total += user.amount * user.tax_rate
+    return total
+
+def calculate_product_total(products):
+    total = 0
+    for product in products:
+        if product.active:
+            total += product.amount * product.tax_rate
+    return total
+
+def calculate_order_total(orders):
+    total = 0
+    for order in orders:
+        if order.active:
+            total += order.amount * order.tax_rate
+    return total
+"""
+
+
+@pytest.fixture
+def clean_code() -> str:
+    """Sample clean, modern Python code."""
+    return """
+from typing import List, Optional, Dict
+from dataclasses import dataclass
+
+
+@dataclass
+class User:
+    name: str
+    email: str
+    active: bool = True
+
+
+def process_users(users: List[User]) -> Dict[str, int]:
+    \"\"\"Process active users and return counts.\"\"\"
+    active_count = sum(1 for user in users if user.active)
+    return {"active": active_count, "total": len(users)}
+
+
+def find_user(users: List[User], email: str) -> Optional[User]:
+    \"\"\"Find user by email.\"\"\"
+    return next((u for u in users if u.email == email), None)
+"""
+
+
+@pytest.fixture
+def non_pep8_code() -> str:
+    """Code with PEP8 naming violations."""
+    return """
+def calculateTotal(items):  # Should be snake_case
+    return sum(items)
+
+class user_manager:  # Should be PascalCase
+    def GetUser(self, id):  # Should be snake_case
+        pass
+
+def processHTTPRequest(request):  # Should be snake_case
+    pass
+
+class API_handler:  # Should be PascalCase
+    pass
+"""
+
+
+@pytest.fixture
+def old_style_code() -> str:
+    """Code with outdated Python patterns."""
+    return """
+def process_data(items):
+    result = []
+    for i in range(len(items)):  # Should use enumerate
+        if items[i] != None:  # Should use 'is not None'
+            result.append(items[i])
+
+    # Old string formatting
+    message = "Found %d items" % len(result)
+
+    # No type hints
+    def add(a, b):
+        return a + b
+
+    return result
+"""
+
+
+@pytest.fixture
+def test_file_code() -> str:
+    """Sample test file code."""
+    return """
+import pytest
+
+def test_something():
+    assert 1 + 1 == 2
+
+def test_another():
+    x = 10
+    y = 20
+    assert x < y
+
+class TestClass:
+    def test_method(self):
+        assert True
+"""
+
+
+@pytest.fixture(autouse=True)
+def reset_environment():
+    """Reset environment variables before each test."""
+    # Store original environment
+    original_env = os.environ.copy()
+
+    # Clear quality-related environment variables
+    quality_vars = [k for k in os.environ if k.startswith("QUALITY_")]
+    for var in quality_vars:
+        del os.environ[var]
+
+    yield
+
+    # Restore original environment
+    os.environ.clear()
+    os.environ.update(original_env)
+
+
+@pytest.fixture
+def set_env_strict():
+    """Set environment for strict mode."""
+    os.environ.update(
+        {
+            "QUALITY_ENFORCEMENT": "strict",
+            "QUALITY_DUP_THRESHOLD": "0.7",
+            "QUALITY_COMPLEXITY_THRESHOLD": "10",
+            "QUALITY_DUP_ENABLED": "true",
+            "QUALITY_COMPLEXITY_ENABLED": "true",
+            "QUALITY_MODERN_ENABLED": "true",
+            "QUALITY_REQUIRE_TYPES": "true",
+        },
+    )
+
+
+@pytest.fixture
+def set_env_permissive():
+    """Set environment for permissive mode."""
+    os.environ.update(
+        {
+            "QUALITY_ENFORCEMENT": "permissive",
+            "QUALITY_DUP_THRESHOLD": "0.9",
+            "QUALITY_COMPLEXITY_THRESHOLD": "20",
+            "QUALITY_DUP_ENABLED": "true",
+            "QUALITY_COMPLEXITY_ENABLED": "true",
+            "QUALITY_MODERN_ENABLED": "false",
+            "QUALITY_REQUIRE_TYPES": "false",
+        },
+    )
+
+
+@pytest.fixture
+def set_env_posttooluse():
+    """Set environment for PostToolUse features."""
+    os.environ.update(
+        {
+            "QUALITY_STATE_TRACKING": "true",
+            "QUALITY_CROSS_FILE_CHECK": "true",
+            "QUALITY_VERIFY_NAMING": "true",
+            "QUALITY_SHOW_SUCCESS": "true",
+        },
+    )

tests/hooks/test_config.py

@@ -0,0 +1,196 @@
+"""Test QualityConfig class and configuration loading."""
+
+import os
+
+import pytest
+from code_quality_guard import QualityConfig
+
+
+class TestQualityConfig:
+    """Test QualityConfig dataclass and environment loading."""
+
+    def test_default_config(self):
+        """Test default configuration values."""
+        config = QualityConfig()
+
+        # Core settings
+        assert config.duplicate_threshold == 0.7
+        assert config.duplicate_enabled is True
+        assert config.complexity_threshold == 10
+        assert config.complexity_enabled is True
+        assert config.modernization_enabled is True
+        assert config.require_type_hints is True
+        assert config.enforcement_mode == "strict"
+
+        # PostToolUse features
+        assert config.state_tracking_enabled is False
+        assert config.cross_file_check_enabled is False
+        assert config.verify_naming is True
+        assert config.show_success is False
+
+        # Skip patterns
+        assert "test_" in config.skip_patterns
+        assert "_test.py" in config.skip_patterns
+        assert "/tests/" in config.skip_patterns
+        assert "/fixtures/" in config.skip_patterns
+
+    def test_from_env_with_defaults(self):
+        """Test loading config from environment with defaults."""
+        config = QualityConfig.from_env()
+
+        # Should use defaults when env vars not set
+        assert config.duplicate_threshold == 0.7
+        assert config.complexity_threshold == 10
+        assert config.enforcement_mode == "strict"
+
+    def test_from_env_with_custom_values(self):
+        """Test loading config from environment with custom values."""
+        os.environ.update(
+            {
+                "QUALITY_DUP_THRESHOLD": "0.8",
+                "QUALITY_DUP_ENABLED": "false",
+                "QUALITY_COMPLEXITY_THRESHOLD": "15",
+                "QUALITY_COMPLEXITY_ENABLED": "false",
+                "QUALITY_MODERN_ENABLED": "false",
+                "QUALITY_REQUIRE_TYPES": "false",
+                "QUALITY_ENFORCEMENT": "permissive",
+                "QUALITY_STATE_TRACKING": "true",
+                "QUALITY_CROSS_FILE_CHECK": "true",
+                "QUALITY_VERIFY_NAMING": "false",
+                "QUALITY_SHOW_SUCCESS": "true",
+            },
+        )
+
+        config = QualityConfig.from_env()
+
+        assert config.duplicate_threshold == 0.8
+        assert config.duplicate_enabled is False
+        assert config.complexity_threshold == 15
+        assert config.complexity_enabled is False
+        assert config.modernization_enabled is False
+        assert config.require_type_hints is False
+        assert config.enforcement_mode == "permissive"
+        assert config.state_tracking_enabled is True
+        assert config.cross_file_check_enabled is True
+        assert config.verify_naming is False
+        assert config.show_success is True
+
+    def test_from_env_with_invalid_boolean(self):
+        """Test loading config with invalid boolean values."""
+        os.environ["QUALITY_DUP_ENABLED"] = "invalid"
+        config = QualityConfig.from_env()
+
+        # Should default to False for invalid boolean
+        assert config.duplicate_enabled is False
+
+    def test_from_env_with_invalid_float(self):
+        """Test loading config with invalid float values."""
+        os.environ["QUALITY_DUP_THRESHOLD"] = "not_a_float"
+
+        with pytest.raises(ValueError, match="invalid literal"):
+            QualityConfig.from_env()
+
+    def test_from_env_with_invalid_int(self):
+        """Test loading config with invalid int values."""
+        os.environ["QUALITY_COMPLEXITY_THRESHOLD"] = "not_an_int"
+
+        with pytest.raises(ValueError, match="invalid literal"):
+            QualityConfig.from_env()
+
+    def test_enforcement_modes(self):
+        """Test different enforcement modes."""
+        modes = ["strict", "warn", "permissive"]
+
+        for mode in modes:
+            os.environ["QUALITY_ENFORCEMENT"] = mode
+            config = QualityConfig.from_env()
+            assert config.enforcement_mode == mode
+
+    def test_skip_patterns_initialization(self):
+        """Test skip patterns initialization."""
+        config = QualityConfig(skip_patterns=None)
+        assert config.skip_patterns is not None
+        assert len(config.skip_patterns) > 0
+
+        custom_patterns = ["custom_test_", "/custom/"]
+        config = QualityConfig(skip_patterns=custom_patterns)
+        assert config.skip_patterns == custom_patterns
+
+    def test_threshold_boundaries(self):
+        """Test threshold boundary values."""
+        # Test minimum threshold
+        os.environ["QUALITY_DUP_THRESHOLD"] = "0.0"
+        config = QualityConfig.from_env()
+        assert config.duplicate_threshold == 0.0
+
+        # Test maximum threshold
+        os.environ["QUALITY_DUP_THRESHOLD"] = "1.0"
+        config = QualityConfig.from_env()
+        assert config.duplicate_threshold == 1.0
+
+        # Test complexity threshold
+        os.environ["QUALITY_COMPLEXITY_THRESHOLD"] = "1"
+        config = QualityConfig.from_env()
+        assert config.complexity_threshold == 1
+
+    def test_config_combinations(self):
+        """Test various configuration combinations."""
+        test_cases = [
+            # All checks disabled
+            {
+                "env": {
+                    "QUALITY_DUP_ENABLED": "false",
+                    "QUALITY_COMPLEXITY_ENABLED": "false",
+                    "QUALITY_MODERN_ENABLED": "false",
+                },
+                "expected": {
+                    "duplicate_enabled": False,
+                    "complexity_enabled": False,
+                    "modernization_enabled": False,
+                },
+            },
+            # Only duplicate checking
+            {
+                "env": {
+                    "QUALITY_DUP_ENABLED": "true",
+                    "QUALITY_COMPLEXITY_ENABLED": "false",
+                    "QUALITY_MODERN_ENABLED": "false",
+                },
+                "expected": {
+                    "duplicate_enabled": True,
+                    "complexity_enabled": False,
+                    "modernization_enabled": False,
+                },
+            },
+            # PostToolUse only
+            {
+                "env": {
+                    "QUALITY_DUP_ENABLED": "false",
+                    "QUALITY_STATE_TRACKING": "true",
+                    "QUALITY_VERIFY_NAMING": "true",
+                },
+                "expected": {
+                    "duplicate_enabled": False,
+                    "state_tracking_enabled": True,
+                    "verify_naming": True,
+                },
+            },
+        ]
+
+        for test_case in test_cases:
+            os.environ.clear()
+            os.environ.update(test_case["env"])
+            config = QualityConfig.from_env()
+
+            for key, expected_value in test_case["expected"].items():
+                assert getattr(config, key) == expected_value
+
+    def test_case_insensitive_boolean(self):
+        """Test case-insensitive boolean parsing."""
+        test_values = ["TRUE", "True", "true", "FALSE", "False", "false"]
+        expected = [True, True, True, False, False, False]
+
+        for value, expected_bool in zip(test_values, expected, strict=False):
+            os.environ["QUALITY_DUP_ENABLED"] = value
+            config = QualityConfig.from_env()
+            assert config.duplicate_enabled == expected_bool

tests/hooks/test_edge_cases.py

@@ -0,0 +1,504 @@
+"""Edge case tests for the code quality hook system."""
+
+import os
+import subprocess
+from unittest.mock import MagicMock, patch
+
+from code_quality_guard import (
+    QualityConfig,
+    analyze_code_quality,
+    detect_internal_duplicates,
+    posttooluse_hook,
+    pretooluse_hook,
+)
+
+
+class TestEdgeCases:
+    """Test edge cases and corner conditions."""
+
+    def test_massive_file_content(self):
+        """Test handling of very large files."""
+        config = QualityConfig()
+        # Create a file with 10,000 lines
+        massive_content = "\n".join(f"# Line {i}" for i in range(10000))
+        massive_content += "\ndef func1():\n    pass\n"
+
+        hook_data = {
+            "tool_name": "Write",
+            "tool_input": {
+                "file_path": "massive.py",
+                "content": massive_content,
+            },
+        }
+
+        with patch("code_quality_guard.analyze_code_quality") as mock_analyze:
+            mock_analyze.return_value = {}
+            result = pretooluse_hook(hook_data, config)
+            assert result["decision"] == "allow"
+            # Should still be called despite large file
+            mock_analyze.assert_called_once()
+
+    def test_empty_file_content(self):
+        """Test handling of empty files."""
+        config = QualityConfig()
+        hook_data = {
+            "tool_name": "Write",
+            "tool_input": {
+                "file_path": "empty.py",
+                "content": "",
+            },
+        }
+
+        result = pretooluse_hook(hook_data, config)
+        assert result["decision"] == "allow"
+
+    def test_whitespace_only_content(self):
+        """Test handling of whitespace-only content."""
+        config = QualityConfig()
+        hook_data = {
+            "tool_name": "Write",
+            "tool_input": {
+                "file_path": "whitespace.py",
+                "content": "   \n\t\n   \n",
+            },
+        }
+
+        result = pretooluse_hook(hook_data, config)
+        assert result["decision"] == "allow"
+
+    def test_malformed_python_syntax(self):
+        """Test handling of syntax errors in Python code."""
+        config = QualityConfig()
+        malformed_code = """
+def broken_func(
+    print("missing closing paren"
+    if True
+        return
+"""
+
+        hook_data = {
+            "tool_name": "Write",
+            "tool_input": {
+                "file_path": "malformed.py",
+                "content": malformed_code,
+            },
+        }
+
+        # Should gracefully handle syntax errors
+        result = pretooluse_hook(hook_data, config)
+        assert result["decision"] in ["allow", "deny", "ask"]
+        assert (
+            "error" in result.get("message", "").lower()
+            or result["decision"] == "allow"
+        )
+
+    def test_unicode_content(self):
+        """Test handling of Unicode characters in code."""
+        config = QualityConfig()
+        unicode_code = """
+# 你好世界 - Hello World in Chinese
+# مرحبا بالعالم - Hello World in Arabic
+# Здравствуй, мир - Hello World in Russian
+
+def greet_世界():
+    '''Function with unicode name'''
+    emoji = "👋🌍"
+    return f"Hello {emoji}"
+"""
+
+        hook_data = {
+            "tool_name": "Write",
+            "tool_input": {
+                "file_path": "unicode.py",
+                "content": unicode_code,
+            },
+        }
+
+        result = pretooluse_hook(hook_data, config)
+        assert result["decision"] in ["allow", "deny", "ask"]
+
+    def test_concurrent_hook_calls(self):
+        """Test thread safety with concurrent calls."""
+        config = QualityConfig()
+        hook_data = {
+            "tool_name": "Write",
+            "tool_input": {
+                "file_path": "concurrent.py",
+                "content": "def test(): pass",
+            },
+        }
+
+        # Simulate rapid consecutive calls
+        results = []
+        for _ in range(5):
+            with patch("code_quality_guard.analyze_code_quality") as mock_analyze:
+                mock_analyze.return_value = {}
+                result = pretooluse_hook(hook_data, config)
+                results.append(result)
+
+        # All should have the same decision
+        decisions = [r["decision"] for r in results]
+        assert all(d == decisions[0] for d in decisions)
+
+    def test_missing_tool_input_fields(self):
+        """Test handling of missing required fields."""
+        config = QualityConfig()
+
+        # Missing file_path
+        hook_data = {
+            "tool_name": "Write",
+            "tool_input": {"content": "def test(): pass"},
+        }
+        result = pretooluse_hook(hook_data, config)
+        assert result["decision"] == "allow"  # Should handle gracefully
+
+        # Missing content for Write
+        hook_data = {
+            "tool_name": "Write",
+            "tool_input": {"file_path": "test.py"},
+        }
+        result = pretooluse_hook(hook_data, config)
+        assert result["decision"] == "allow"  # Should handle gracefully
+
+    def test_circular_import_detection(self):
+        """Test detection of circular imports."""
+        config = QualityConfig()
+        circular_code = """
+from module_a import func_a
+from module_b import func_b
+
+def func_c():
+    return func_a() + func_b()
+"""
+
+        hook_data = {
+            "tool_name": "Write",
+            "tool_input": {
+                "file_path": "module_c.py",
+                "content": circular_code,
+            },
+        }
+
+        result = pretooluse_hook(hook_data, config)
+        # Should not crash on import analysis
+        assert result["decision"] in ["allow", "deny", "ask"]
+
+    def test_binary_file_path(self):
+        """Test handling of binary file paths."""
+        config = QualityConfig()
+        hook_data = {
+            "tool_name": "Write",
+            "tool_input": {
+                "file_path": "image.png",  # Non-Python file
+                "content": "binary content",
+            },
+        }
+
+        result = pretooluse_hook(hook_data, config)
+        assert result["decision"] == "allow"  # Should skip non-Python files
+
+    def test_null_and_none_values(self):
+        """Test handling of null/None values."""
+        config = QualityConfig()
+
+        # None as content
+        hook_data = {
+            "tool_name": "Write",
+            "tool_input": {
+                "file_path": "test.py",
+                "content": None,
+            },
+        }
+        result = pretooluse_hook(hook_data, config)
+        assert result["decision"] == "allow"
+
+        # None as file_path
+        hook_data["tool_input"] = {
+            "file_path": None,
+            "content": "def test(): pass",
+        }
+        result = pretooluse_hook(hook_data, config)
+        assert result["decision"] == "allow"
+
+    def test_path_traversal_attempts(self):
+        """Test handling of path traversal attempts."""
+        config = QualityConfig()
+        dangerous_paths = [
+            "../../../etc/passwd",
+            "..\\..\\..\\windows\\system32\\config.sys",
+            "/etc/shadow",
+            "~/../../root/.ssh/id_rsa",
+        ]
+
+        for path in dangerous_paths:
+            hook_data = {
+                "tool_name": "Write",
+                "tool_input": {
+                    "file_path": path,
+                    "content": "malicious content",
+                },
+            }
+            result = pretooluse_hook(hook_data, config)
+            # Should handle without crashing
+            assert result["decision"] in ["allow", "deny", "ask"]
+
+    def test_extreme_thresholds(self):
+        """Test with extreme threshold values."""
+        # Zero thresholds
+        config = QualityConfig(
+            duplicate_threshold=0.0,
+            complexity_threshold=0,
+        )
+        hook_data = {
+            "tool_name": "Write",
+            "tool_input": {
+                "file_path": "test.py",
+                "content": "def test(): pass",
+            },
+        }
+
+        with patch("code_quality_guard.analyze_code_quality") as mock_analyze:
+            mock_analyze.return_value = {
+                "complexity": {
+                    "summary": {"average_cyclomatic_complexity": 1},
+                },
+            }
+            result = pretooluse_hook(hook_data, config)
+            # With threshold 0, everything should be flagged
+            assert result["decision"] == "deny"
+
+        # Maximum thresholds
+        config = QualityConfig(
+            duplicate_threshold=1.0,
+            complexity_threshold=999999,
+            enforcement_mode="permissive",  # Use permissive mode for high thresholds
+        )
+
+        with patch("code_quality_guard.analyze_code_quality") as mock_analyze:
+            mock_analyze.return_value = {
+                "complexity": {
+                    "summary": {"average_cyclomatic_complexity": 50},
+                    "distribution": {"Extreme": 10},
+                },
+            }
+            result = pretooluse_hook(hook_data, config)
+            # With very high thresholds and permissive mode, should pass with warning
+            assert result["decision"] == "allow"
+
+    def test_subprocess_timeout(self):
+        """Test handling of subprocess timeouts."""
+        config = QualityConfig()
+        test_content = "def test(): pass"
+
+        with patch("subprocess.run") as mock_run:
+            # Simulate timeout
+            mock_run.side_effect = subprocess.TimeoutExpired("cmd", 30)
+
+            results = analyze_code_quality(test_content, "test.py", config)
+            # Should handle timeout gracefully
+            assert isinstance(results, dict)
+
+    def test_subprocess_command_failure(self):
+        """Test handling of subprocess command failures."""
+        config = QualityConfig()
+        test_content = "def test(): pass"
+
+        with patch("subprocess.run") as mock_run:
+            # Simulate command failure
+            mock_result = MagicMock()
+            mock_result.returncode = 1
+            mock_result.stdout = "Error: command failed"
+            mock_run.return_value = mock_result
+
+            results = analyze_code_quality(test_content, "test.py", config)
+            # Should handle failure gracefully
+            assert isinstance(results, dict)
+
+    def test_json_parsing_errors(self):
+        """Test handling of JSON parsing errors from subprocess."""
+        config = QualityConfig()
+        test_content = "def test(): pass"
+
+        with patch("subprocess.run") as mock_run:
+            # Simulate invalid JSON output
+            mock_result = MagicMock()
+            mock_result.returncode = 0
+            mock_result.stdout = "Not valid JSON {broken:"
+            mock_run.return_value = mock_result
+
+            results = analyze_code_quality(test_content, "test.py", config)
+            # Should handle JSON errors gracefully
+            assert isinstance(results, dict)
+
+    def test_file_permission_errors(self):
+        """Test handling of file permission errors."""
+        config = QualityConfig(state_tracking_enabled=True)
+        hook_data = {
+            "tool_name": "Write",
+            "tool_output": {
+                "file_path": "/root/protected.py",
+            },
+        }
+
+        with patch("pathlib.Path.exists", return_value=True):
+            with patch("pathlib.Path.read_text") as mock_read:
+                mock_read.side_effect = PermissionError("Access denied")
+
+                result = posttooluse_hook(hook_data, config)
+                # Should handle permission errors gracefully
+                assert result["decision"] == "allow"
+
+    def test_deeply_nested_code_structure(self):
+        """Test handling of deeply nested code."""
+        config = QualityConfig()
+        # Create code with 10 levels of nesting
+        nested_code = "def func():\n"
+        indent = "    "
+        for i in range(10):
+            nested_code += f"{indent * (i + 1)}if condition_{i}:\n"
+        nested_code += f"{indent * 11}return True\n"
+
+        hook_data = {
+            "tool_name": "Write",
+            "tool_input": {
+                "file_path": "nested.py",
+                "content": nested_code,
+            },
+        }
+
+        result = pretooluse_hook(hook_data, config)
+        # Should handle without stack overflow
+        assert result["decision"] in ["allow", "deny", "ask"]
+
+    def test_recursive_function_detection(self):
+        """Test detection of recursive functions."""
+        config = QualityConfig()
+        recursive_code = """
+def factorial(n):
+    if n <= 1:
+        return 1
+    return n * factorial(n - 1)
+
+def infinite_recursion():
+    return infinite_recursion()
+"""
+
+        hook_data = {
+            "tool_name": "Write",
+            "tool_input": {
+                "file_path": "recursive.py",
+                "content": recursive_code,
+            },
+        }
+
+        result = pretooluse_hook(hook_data, config)
+        # Should handle recursive functions
+        assert result["decision"] in ["allow", "deny", "ask"]
+
+    def test_multifile_edit_paths(self):
+        """Test MultiEdit with multiple file paths."""
+        config = QualityConfig()
+        hook_data = {
+            "tool_name": "MultiEdit",
+            "tool_input": {
+                "file_path": "main.py",
+                "edits": [
+                    {"old_string": "old1", "new_string": "def func1(): pass"},
+                    {"old_string": "old2", "new_string": "def func2(): pass"},
+                    {"old_string": "old3", "new_string": "def func3(): pass"},
+                ],
+            },
+        }
+
+        with patch("code_quality_guard.analyze_code_quality") as mock_analyze:
+            mock_analyze.return_value = {}
+            result = pretooluse_hook(hook_data, config)
+            assert result["decision"] == "allow"
+            # Should concatenate all new_strings
+            call_args = mock_analyze.call_args[0][0]
+            assert "func1" in call_args
+            assert "func2" in call_args
+            assert "func3" in call_args
+
+    def test_environment_variable_injection(self):
+        """Test handling of environment variable injection attempts."""
+        malicious_envs = {
+            "QUALITY_ENFORCEMENT": "permissive; rm -rf /",
+            "QUALITY_COMPLEXITY_THRESHOLD": "-1; echo hacked",
+            "QUALITY_DUP_THRESHOLD": "0.5 && malicious_command",
+        }
+
+        for key, value in malicious_envs.items():
+            os.environ[key] = value
+            try:
+                config = QualityConfig()
+                # Should handle malicious env vars safely
+                assert isinstance(config, QualityConfig)
+            finally:
+                del os.environ[key]
+
+    def test_memory_efficient_large_duplicates(self):
+        """Test memory efficiency with large duplicate blocks."""
+        # Create a large function that's duplicated
+        large_func = """
+def process_data(data):
+    ''' Large function with many lines '''
+    result = []
+""" + "\n".join(
+            f"    # Processing step {i}\n    result.append(data[{i}])"
+            for i in range(100)
+        )
+
+        # Duplicate the function
+        code_with_duplicates = (
+            large_func + "\n\n" + large_func.replace("process_data", "process_data2")
+        )
+
+        duplicates = detect_internal_duplicates(code_with_duplicates, threshold=0.8)
+        # Should detect duplicates without memory issues
+        assert "duplicates" in duplicates
+        assert len(duplicates["duplicates"]) > 0
+
+    def test_special_python_constructs(self):
+        """Test handling of special Python constructs."""
+        special_code = """
+# Walrus operator
+if (n := len(data)) > 10:
+    print(f"{n} items")
+
+# Match statement (Python 3.10+)
+def handle(value):
+    match value:
+        case 0:
+            return "zero"
+        case _:
+            return "other"
+
+# Type hints with unions
+def process(data: list[str | int | None]) -> dict[str, Any]:
+    return {}
+
+# Async context managers
+async def fetch():
+    async with aiohttp.ClientSession() as session:
+        pass
+
+# Decorators with arguments
+@lru_cache(maxsize=128)
+@deprecated(version='1.0')
+def cached_func():
+    pass
+"""
+
+        config = QualityConfig()
+        hook_data = {
+            "tool_name": "Write",
+            "tool_input": {
+                "file_path": "special.py",
+                "content": special_code,
+            },
+        }
+
+        result = pretooluse_hook(hook_data, config)
+        # Should handle modern Python syntax
+        assert result["decision"] in ["allow", "deny", "ask"]

tests/hooks/test_helper_functions.py

@@ -0,0 +1,328 @@
+"""Test helper functions and utilities."""
+
+import hashlib
+import json
+import tempfile
+from datetime import UTC, datetime
+from unittest.mock import MagicMock, patch
+
+from code_quality_guard import (
+    QualityConfig,
+    analyze_code_quality,
+    check_code_issues,
+    check_cross_file_duplicates,
+    check_state_changes,
+    get_claude_quality_path,
+    should_skip_file,
+    store_pre_state,
+    verify_naming_conventions,
+)
+
+
+class TestHelperFunctions:
+    """Test helper functions in the hook."""
+
+    def test_should_skip_file_default_patterns(self):
+        """Test default skip patterns."""
+        config = QualityConfig()
+
+        # Test files that should be skipped
+        assert should_skip_file("test_example.py", config) is True
+        assert should_skip_file("example_test.py", config) is True
+        assert should_skip_file("/project/tests/file.py", config) is True
+        assert should_skip_file("/fixtures/data.py", config) is True
+
+        # Test files that should not be skipped
+        assert should_skip_file("example.py", config) is False
+        assert should_skip_file("src/main.py", config) is False
+
+    def test_should_skip_file_custom_patterns(self):
+        """Test custom skip patterns."""
+        config = QualityConfig(skip_patterns=["ignore_", "/vendor/"])
+
+        assert should_skip_file("ignore_this.py", config) is True
+        assert should_skip_file("/vendor/lib.py", config) is True
+        assert (
+            should_skip_file("test_file.py", config) is False
+        )  # Default pattern not included
+
+    def test_get_claude_quality_path_venv(self):
+        """Test claude-quality path resolution in venv."""
+        with patch("pathlib.Path.exists", return_value=True):
+            path = get_claude_quality_path()
+            assert ".venv/bin/claude-quality" in path
+
+    def test_get_claude_quality_path_system(self):
+        """Test claude-quality path fallback to system."""
+        with patch("pathlib.Path.exists", return_value=False):
+            path = get_claude_quality_path()
+            assert path == "claude-quality"
+
+    def test_store_pre_state(self):
+        """Test storing pre-modification state."""
+        test_content = "def func1(): pass\ndef func2(): pass"
+        test_path = f"{tempfile.gettempdir()}/test.py"
+
+        with patch("pathlib.Path.mkdir") as mock_mkdir:
+            with patch("pathlib.Path.write_text") as mock_write:
+                store_pre_state(test_path, test_content)
+
+                # Verify cache directory created
+                mock_mkdir.assert_called_once_with(exist_ok=True)
+
+                # Verify state was written
+                mock_write.assert_called_once()
+                written_data = json.loads(mock_write.call_args[0][0])
+
+                assert written_data["file_path"] == test_path
+                assert written_data["lines"] == 2
+                assert written_data["functions"] == 2
+                assert written_data["classes"] == 0
+                assert "content_hash" in written_data
+                assert "timestamp" in written_data
+
+    def test_check_state_changes_no_pre_state(self):
+        """Test state changes when no pre-state exists."""
+        test_path = f"{tempfile.gettempdir()}/test.py"
+        issues = check_state_changes(test_path)
+        assert issues == []
+
+    def test_check_state_changes_with_degradation(self):
+        """Test state changes detecting degradation."""
+        test_path = f"{tempfile.gettempdir()}/test.py"
+        hashlib.sha256(test_path.encode()).hexdigest()[:8]
+
+        pre_state = {
+            "file_path": test_path,
+            "timestamp": datetime.now(UTC).isoformat(),
+            "lines": 50,
+            "functions": 10,
+            "classes": 2,
+        }
+
+        current_content = "def func1(): pass"  # Only 1 function now
+
+        with patch("pathlib.Path.exists", return_value=True):
+            with patch("pathlib.Path.read_text") as mock_read:
+                # First call reads pre-state, second reads current file
+                mock_read.side_effect = [json.dumps(pre_state), current_content]
+
+                issues = check_state_changes(test_path)
+
+                # Should detect function reduction
+                assert len(issues) > 0
+                assert any("Reduced functions" in issue for issue in issues)
+
+    def test_check_state_changes_file_size_increase(self):
+        """Test detection of significant file size increase."""
+        test_path = f"{tempfile.gettempdir()}/test.py"
+
+        pre_state = {
+            "file_path": test_path,
+            "lines": 100,
+            "functions": 5,
+            "classes": 1,
+        }
+
+        # Create content with 200 lines (2x increase)
+        current_content = "\n".join(f"# Line {i}" for i in range(200))
+
+        with patch("pathlib.Path.exists", return_value=True):
+            with patch("pathlib.Path.read_text") as mock_read:
+                mock_read.side_effect = [json.dumps(pre_state), current_content]
+
+                issues = check_state_changes(test_path)
+
+                assert len(issues) > 0
+                assert any("size increased significantly" in issue for issue in issues)
+
+    def test_check_cross_file_duplicates(self):
+        """Test cross-file duplicate detection."""
+        config = QualityConfig(duplicate_threshold=0.8)
+        test_path = f"{tempfile.gettempdir()}/project/test.py"
+
+        with patch("subprocess.run") as mock_run:
+            mock_result = MagicMock()
+            mock_result.returncode = 0
+            mock_result.stdout = json.dumps(
+                {
+                    "duplicates": [
+                        {
+                            "files": [
+                                f"{tempfile.gettempdir()}/project/test.py",
+                                f"{tempfile.gettempdir()}/project/other.py",
+                            ],
+                        },
+                    ],
+                },
+            )
+            mock_run.return_value = mock_result
+
+            issues = check_cross_file_duplicates(test_path, config)
+
+            assert len(issues) > 0
+            assert "Cross-file duplication" in issues[0]
+
+    def test_check_cross_file_duplicates_no_duplicates(self):
+        """Test cross-file check with no duplicates."""
+        config = QualityConfig()
+        test_path = f"{tempfile.gettempdir()}/project/test.py"
+
+        with patch("subprocess.run") as mock_run:
+            mock_result = MagicMock()
+            mock_result.returncode = 0
+            mock_result.stdout = json.dumps({"duplicates": []})
+            mock_run.return_value = mock_result
+
+            issues = check_cross_file_duplicates(test_path, config)
+            assert issues == []
+
+    def test_verify_naming_conventions_violations(self, non_pep8_code):
+        """Test naming convention verification with violations."""
+        with patch("pathlib.Path.read_text", return_value=non_pep8_code):
+            test_path = f"{tempfile.gettempdir()}/test.py"
+            issues = verify_naming_conventions(test_path)
+
+            assert len(issues) == 2
+            assert any("Non-PEP8 function names" in issue for issue in issues)
+            assert any("Non-PEP8 class names" in issue for issue in issues)
+
+    def test_verify_naming_conventions_clean(self, clean_code):
+        """Test naming convention verification with clean code."""
+        with patch("pathlib.Path.read_text", return_value=clean_code):
+            test_path = f"{tempfile.gettempdir()}/test.py"
+            issues = verify_naming_conventions(test_path)
+            assert issues == []
+
+    def test_analyze_code_quality_all_checks(self):
+        """Test analyze_code_quality with all checks enabled."""
+        config = QualityConfig(
+            duplicate_enabled=True,
+            complexity_enabled=True,
+            modernization_enabled=True,
+        )
+
+        test_content = "def test(): pass"
+
+        with patch("code_quality_guard.detect_internal_duplicates") as mock_dup:
+            with patch("subprocess.run") as mock_run:
+                # Setup mock returns
+                mock_dup.return_value = {"duplicates": []}
+
+                mock_result = MagicMock()
+                mock_result.returncode = 0
+                mock_result.stdout = json.dumps({"summary": {}})
+                mock_run.return_value = mock_result
+
+                analyze_code_quality(test_content, "test.py", config)
+
+                # Verify all checks were run
+                mock_dup.assert_called_once()
+                assert mock_run.call_count >= 2  # Complexity and modernization
+
+    def test_analyze_code_quality_disabled_checks(self):
+        """Test analyze_code_quality with checks disabled."""
+        config = QualityConfig(
+            duplicate_enabled=False,
+            complexity_enabled=False,
+            modernization_enabled=False,
+        )
+
+        with patch("code_quality_guard.detect_internal_duplicates") as mock_dup:
+            with patch("subprocess.run") as mock_run:
+                results = analyze_code_quality("def test(): pass", "test.py", config)
+
+                # No checks should be run
+                mock_dup.assert_not_called()
+                mock_run.assert_not_called()
+                assert results == {}
+
+    def test_check_code_issues_internal_duplicates(self):
+        """Test issue detection for internal duplicates."""
+        config = QualityConfig()
+        results = {
+            "internal_duplicates": {
+                "duplicates": [
+                    {
+                        "similarity": 0.95,
+                        "description": "Similar functions",
+                        "locations": [
+                            {"name": "func1", "lines": "1-5"},
+                            {"name": "func2", "lines": "7-11"},
+                        ],
+                    },
+                ],
+            },
+        }
+
+        has_issues, issues = check_code_issues(results, config)
+
+        assert has_issues is True
+        assert len(issues) > 0
+        assert "Internal duplication" in issues[0]
+        assert "95%" in issues[0]
+
+    def test_check_code_issues_complexity(self):
+        """Test issue detection for complexity."""
+        config = QualityConfig(complexity_threshold=10)
+        results = {
+            "complexity": {
+                "summary": {"average_cyclomatic_complexity": 15},
+                "distribution": {"High": 2, "Very High": 1},
+            },
+        }
+
+        has_issues, issues = check_code_issues(results, config)
+
+        assert has_issues is True
+        assert any("High average complexity" in issue for issue in issues)
+        assert any("3 function(s) with high complexity" in issue for issue in issues)
+
+    def test_check_code_issues_modernization(self):
+        """Test issue detection for modernization."""
+        config = QualityConfig(require_type_hints=True)
+        results = {
+            "modernization": {
+                "files": {
+                    "test.py": [
+                        {"issue_type": "use_enumerate"},
+                        {"issue_type": "missing_return_type"},
+                        {"issue_type": "missing_param_type"},
+                    ],
+                },
+            },
+        }
+
+        has_issues, issues = check_code_issues(results, config)
+
+        assert has_issues is True
+        assert any("Modernization needed" in issue for issue in issues)
+
+    def test_check_code_issues_type_hints_threshold(self):
+        """Test type hint threshold detection."""
+        config = QualityConfig(require_type_hints=True)
+
+        # Create 15 type hint issues
+        type_issues = [{"issue_type": "missing_return_type"} for _ in range(15)]
+
+        results = {
+            "modernization": {
+                "files": {"test.py": type_issues},
+            },
+        }
+
+        has_issues, issues = check_code_issues(results, config)
+
+        assert has_issues is True
+        assert any("Many missing type hints" in issue for issue in issues)
+        assert "15" in issues[0]
+
+    def test_check_code_issues_no_issues(self):
+        """Test when no issues are found."""
+        config = QualityConfig()
+        results = {}
+
+        has_issues, issues = check_code_issues(results, config)
+
+        assert has_issues is False
+        assert issues == []

tests/hooks/test_integration.py

@@ -0,0 +1,330 @@
+"""Integration tests for the complete hook system."""
+
+import json
+import os
+import tempfile
+from pathlib import Path
+from unittest.mock import patch
+
+
+class TestHookIntegration:
+    """Test complete hook integration scenarios."""
+
+    def test_main_entry_pretooluse(self):
+        """Test main entry point detects PreToolUse."""
+        from code_quality_guard import main
+
+        hook_input = {
+            "tool_name": "Write",
+            "tool_input": {
+                "file_path": "test.py",
+                "content": "def test(): pass",
+            },
+        }
+
+        with patch("sys.stdin") as mock_stdin:
+            with patch("builtins.print"):
+                mock_stdin.read.return_value = json.dumps(hook_input)
+                mock_stdin.__iter__.return_value = [json.dumps(hook_input)]
+
+                with patch("json.load", return_value=hook_input):
+                    with patch("code_quality_guard.pretooluse_hook") as mock_pre:
+                        mock_pre.return_value = {"decision": "allow"}
+                        main()
+                        mock_pre.assert_called_once()
+
+    def test_main_entry_posttooluse(self):
+        """Test main entry point detects PostToolUse."""
+        from code_quality_guard import main
+
+        hook_input = {
+            "tool_name": "Write",
+            "tool_output": {
+                "file_path": "test.py",
+                "status": "success",
+            },
+        }
+
+        with patch("sys.stdin") as mock_stdin:
+            with patch("builtins.print"):
+                mock_stdin.read.return_value = json.dumps(hook_input)
+                mock_stdin.__iter__.return_value = [json.dumps(hook_input)]
+
+                with patch("json.load", return_value=hook_input):
+                    with patch("code_quality_guard.posttooluse_hook") as mock_post:
+                        mock_post.return_value = {"decision": "allow"}
+                        main()
+                        mock_post.assert_called_once()
+
+    def test_main_invalid_json(self):
+        """Test main handles invalid JSON input."""
+        from code_quality_guard import main
+
+        with patch("sys.stdin"):
+            with patch("builtins.print") as mock_print:
+                with patch(
+                    "json.load",
+                    side_effect=json.JSONDecodeError("test", "test", 0),
+                ):
+                    main()
+
+                    # Should print allow decision
+                    printed = mock_print.call_args[0][0]
+                    response = json.loads(printed)
+                    assert response["decision"] == "allow"
+
+    def test_full_flow_clean_code(self, clean_code):
+        """Test full flow with clean code."""
+        from code_quality_guard import main
+
+        # PreToolUse
+        pre_input = {
+            "tool_name": "Write",
+            "tool_input": {
+                "file_path": f"{tempfile.gettempdir()}/clean.py",
+                "content": clean_code,
+            },
+        }
+
+        with patch("sys.stdin"):
+            with patch("builtins.print") as mock_print:
+                with patch("json.load", return_value=pre_input):
+                    main()
+
+                    printed = mock_print.call_args[0][0]
+                    response = json.loads(printed)
+                    assert response["decision"] == "allow"
+
+        # Simulate file write
+        test_file = Path(f"{tempfile.gettempdir()}/clean.py")
+        test_file.write_text(clean_code)
+
+        # PostToolUse
+        post_input = {
+            "tool_name": "Write",
+            "tool_output": {
+                "file_path": f"{tempfile.gettempdir()}/clean.py",
+                "status": "success",
+            },
+        }
+
+        with patch("sys.stdin"):
+            with patch("builtins.print") as mock_print:
+                with patch("json.load", return_value=post_input):
+                    os.environ["QUALITY_SHOW_SUCCESS"] = "true"
+                    main()
+
+                    printed = mock_print.call_args[0][0]
+                    response = json.loads(printed)
+                    assert response["decision"] == "allow"
+                    assert "passed" in response.get("message", "").lower()
+
+        test_file.unlink(missing_ok=True)
+
+    def test_environment_configuration_flow(self):
+        """Test that environment variables are properly used."""
+        from code_quality_guard import main
+
+        # Set strict environment
+        os.environ.update(
+            {
+                "QUALITY_ENFORCEMENT": "strict",
+                "QUALITY_COMPLEXITY_THRESHOLD": "5",  # Very low threshold
+                "QUALITY_DUP_ENABLED": "false",
+                "QUALITY_COMPLEXITY_ENABLED": "true",  # Keep complexity enabled
+                "QUALITY_MODERN_ENABLED": "false",
+            },
+        )
+
+        complex_code = """
+def complex_func(a, b, c):
+    if a:
+        if b:
+            if c:
+                return 1
+            else:
+                return 2
+        else:
+            return 3
+    else:
+        return 4
+"""
+
+        hook_input = {
+            "tool_name": "Write",
+            "tool_input": {
+                "file_path": "complex.py",
+                "content": complex_code,
+            },
+        }
+
+        with patch("sys.stdin"):
+            with patch("builtins.print") as mock_print:
+                with patch("json.load", return_value=hook_input):
+                    with patch(
+                        "code_quality_guard.analyze_code_quality",
+                    ) as mock_analyze:
+                        # Mock the complexity analysis result
+                        mock_analyze.return_value = {
+                            "complexity": {
+                                "summary": {
+                                    "average_cyclomatic_complexity": 8,
+                                },  # Above threshold
+                                "distribution": {"High": 1},
+                            },
+                        }
+                        try:
+                            main()
+                            msg = "Expected SystemExit"
+                            raise AssertionError(msg)
+                        except SystemExit as e:
+                            assert e.code == 2, "Expected exit code 2 for deny"  # noqa: PT017
+
+                    printed = mock_print.call_args[0][0]
+                    response = json.loads(printed)
+                    # Should be denied due to low complexity threshold
+                    assert response["decision"] == "deny"
+
+    def test_skip_patterns_integration(self):
+        """Test skip patterns work in integration."""
+        from code_quality_guard import main
+
+        # Test file should be skipped
+        hook_input = {
+            "tool_name": "Write",
+            "tool_input": {
+                "file_path": "test_something.py",
+                "content": "bad code with issues",
+            },
+        }
+
+        with patch("sys.stdin"):
+            with patch("builtins.print") as mock_print:
+                with patch("json.load", return_value=hook_input):
+                    main()
+
+                    printed = mock_print.call_args[0][0]
+                    response = json.loads(printed)
+                    assert response["decision"] == "allow"
+
+    def test_state_tracking_flow(self, temp_python_file):
+        """Test state tracking between pre and post."""
+        from code_quality_guard import main
+
+        os.environ["QUALITY_STATE_TRACKING"] = "true"
+
+        # PreToolUse - store state
+        initial_content = "def func1(): pass\ndef func2(): pass\ndef func3(): pass"
+        pre_input = {
+            "tool_name": "Write",
+            "tool_input": {
+                "file_path": str(temp_python_file),
+                "content": initial_content,
+            },
+        }
+
+        with patch("sys.stdin"):
+            with patch("builtins.print") as mock_print:
+                with patch("json.load", return_value=pre_input):
+                    main()
+
+        # Simulate file modification (fewer functions)
+        modified_content = "def func1(): pass"
+        temp_python_file.write_text(modified_content)
+
+        # PostToolUse - check state
+        post_input = {
+            "tool_name": "Write",
+            "tool_output": {
+                "file_path": str(temp_python_file),
+                "status": "success",
+            },
+        }
+
+        with patch("sys.stdin"):
+            with patch("builtins.print") as mock_print:
+                with patch("json.load", return_value=post_input):
+                    main()
+
+                    printed = mock_print.call_args[0][0]
+                    response = json.loads(printed)
+                    assert response["decision"] == "allow"
+                    # Should detect function reduction
+                    if "message" in response:
+                        assert (
+                            "reduced" in response["message"].lower()
+                            or len(response["message"]) == 0
+                        )
+
+    def test_cross_tool_handling(self):
+        """Test different tools are handled correctly."""
+        from code_quality_guard import main
+
+        tools = ["Write", "Edit", "MultiEdit", "Read", "Bash", "Task"]
+
+        for tool in tools:
+            if tool in ["Write", "Edit", "MultiEdit"]:
+                hook_input = {
+                    "tool_name": tool,
+                    "tool_input": {
+                        "file_path": "test.py",
+                        "content": "def test(): pass",
+                    },
+                }
+            else:
+                hook_input = {
+                    "tool_name": tool,
+                    "tool_input": {},
+                }
+
+            with patch("sys.stdin"):
+                with patch("builtins.print") as mock_print:
+                    with patch("json.load", return_value=hook_input):
+                        main()
+
+                        printed = mock_print.call_args[0][0]
+                        response = json.loads(printed)
+                        assert response["decision"] == "allow"
+
+    def test_enforcement_mode_progression(self, complex_code):
+        """Test progression through enforcement modes."""
+        from code_quality_guard import main
+
+        hook_input = {
+            "tool_name": "Write",
+            "tool_input": {
+                "file_path": "complex.py",
+                "content": complex_code,
+            },
+        }
+
+        modes_and_decisions = [
+            ("strict", "deny"),
+            ("warn", "ask"),
+            ("permissive", "allow"),
+        ]
+
+        for mode, expected_decision in modes_and_decisions:
+            os.environ["QUALITY_ENFORCEMENT"] = mode
+            os.environ["QUALITY_COMPLEXITY_THRESHOLD"] = "10"
+
+            with patch("sys.stdin"):
+                with patch("builtins.print") as mock_print:
+                    with patch("json.load", return_value=hook_input):
+                        if expected_decision in ["deny", "ask"]:
+                            # Expect SystemExit with code 2 for deny/ask decisions
+                            try:
+                                main()
+                                msg = f"Expected SystemExit for {mode} mode"
+                                raise AssertionError(msg)
+                            except SystemExit as e:
+                                assert e.code == 2, (  # noqa: PT017
+                                    f"Expected exit code 2 for {mode} mode"
+                                )
+                        else:
+                            # Permissive mode should not exit
+                            main()
+
+                        printed = mock_print.call_args[0][0]
+                        response = json.loads(printed)
+                        assert response["decision"] == expected_decision

tests/hooks/test_posttooluse.py

@@ -0,0 +1,261 @@
+"""Test PostToolUse hook functionality."""
+
+import tempfile
+from unittest.mock import patch
+
+from code_quality_guard import QualityConfig, posttooluse_hook
+
+
+class TestPostToolUseHook:
+    """Test PostToolUse hook behavior."""
+
+    def test_non_write_tool_allowed(self):
+        """Test that non-write/edit tools are always allowed."""
+        config = QualityConfig()
+        hook_data = {
+            "tool_name": "Read",
+            "tool_output": {"status": "success"},
+        }
+
+        result = posttooluse_hook(hook_data, config)
+        assert result["decision"] == "allow"
+
+    def test_file_path_extraction_dict(self):
+        """Test file path extraction from dict output."""
+        config = QualityConfig()
+        test_file = f"{tempfile.gettempdir()}/test.py"
+
+        # Test with file_path key
+        hook_data = {
+            "tool_name": "Write",
+            "tool_output": {"file_path": test_file},
+        }
+
+        with patch("pathlib.Path.exists", return_value=True):
+            with patch("pathlib.Path.read_text", return_value="def test(): pass"):
+                result = posttooluse_hook(hook_data, config)
+                assert result["decision"] == "allow"
+
+        # Test with path key
+        hook_data["tool_output"] = {"path": test_file}
+
+        with patch("pathlib.Path.exists", return_value=True):
+            with patch("pathlib.Path.read_text", return_value="def test(): pass"):
+                result = posttooluse_hook(hook_data, config)
+                assert result["decision"] == "allow"
+
+    def test_file_path_extraction_string(self):
+        """Test file path extraction from string output."""
+        config = QualityConfig()
+        hook_data = {
+            "tool_name": "Write",
+            "tool_output": "File written successfully: /tmp/test.py",
+        }
+
+        with patch("pathlib.Path.exists", return_value=True):
+            with patch("pathlib.Path.read_text", return_value="def test(): pass"):
+                result = posttooluse_hook(hook_data, config)
+                assert result["decision"] == "allow"
+
+    def test_non_python_file_skipped(self):
+        """Test that non-Python files are skipped."""
+        config = QualityConfig()
+        hook_data = {
+            "tool_name": "Write",
+            "tool_output": {"file_path": f"{tempfile.gettempdir()}/test.js"},
+        }
+
+        result = posttooluse_hook(hook_data, config)
+        assert result["decision"] == "allow"
+
+    def test_nonexistent_file_skipped(self):
+        """Test that nonexistent files are skipped."""
+        config = QualityConfig()
+        hook_data = {
+            "tool_name": "Write",
+            "tool_output": {"file_path": f"{tempfile.gettempdir()}/nonexistent.py"},
+        }
+
+        with patch("pathlib.Path.exists", return_value=False):
+            result = posttooluse_hook(hook_data, config)
+            assert result["decision"] == "allow"
+
+    def test_state_tracking_degradation(self):
+        """Test state tracking detects quality degradation."""
+        config = QualityConfig(state_tracking_enabled=True)
+        hook_data = {
+            "tool_name": "Write",
+            "tool_output": {"file_path": f"{tempfile.gettempdir()}/test.py"},
+        }
+
+        with patch("pathlib.Path.exists", return_value=True):
+            with patch("pathlib.Path.read_text", return_value="def test(): pass"):
+                with patch("code_quality_guard.check_state_changes") as mock_check:
+                    mock_check.return_value = [
+                        "⚠️ Reduced functions: 5 → 2",
+                        "⚠️ File size increased significantly: 100 → 250 lines",
+                    ]
+
+                    result = posttooluse_hook(hook_data, config)
+                    assert result["decision"] == "allow"
+                    assert "Post-write quality notes" in result["message"]
+                    assert "Reduced functions" in result["message"]
+
+    def test_cross_file_duplicates(self):
+        """Test cross-file duplicate detection."""
+        config = QualityConfig(cross_file_check_enabled=True)
+        hook_data = {
+            "tool_name": "Write",
+            "tool_output": {"file_path": f"{tempfile.gettempdir()}/test.py"},
+        }
+
+        with patch("pathlib.Path.exists", return_value=True):
+            with patch("pathlib.Path.read_text", return_value="def test(): pass"):
+                with patch(
+                    "code_quality_guard.check_cross_file_duplicates",
+                ) as mock_check:
+                    mock_check.return_value = ["⚠️ Cross-file duplication detected"]
+
+                    result = posttooluse_hook(hook_data, config)
+                    assert result["decision"] == "allow"
+                    assert "Cross-file duplication" in result["message"]
+
+    def test_naming_convention_violations(self, non_pep8_code):
+        """Test naming convention verification."""
+        config = QualityConfig(verify_naming=True)
+        hook_data = {
+            "tool_name": "Write",
+            "tool_output": {"file_path": f"{tempfile.gettempdir()}/test.py"},
+        }
+
+        with patch("pathlib.Path.exists", return_value=True):
+            with patch("pathlib.Path.read_text", return_value=non_pep8_code):
+                result = posttooluse_hook(hook_data, config)
+                assert result["decision"] == "allow"
+                assert "Non-PEP8 function names" in result["message"]
+                assert "Non-PEP8 class names" in result["message"]
+
+    def test_show_success_message(self, clean_code):
+        """Test success message when enabled."""
+        config = QualityConfig(show_success=True, verify_naming=False)
+        hook_data = {
+            "tool_name": "Write",
+            "tool_output": {"file_path": f"{tempfile.gettempdir()}/test.py"},
+        }
+
+        with patch("pathlib.Path.exists", return_value=True):
+            with patch("pathlib.Path.read_text", return_value=clean_code):
+                result = posttooluse_hook(hook_data, config)
+                assert result["decision"] == "allow"
+                assert "passed post-write verification" in result["message"]
+
+    def test_no_message_when_success_disabled(self, clean_code):
+        """Test no message when show_success is disabled."""
+        config = QualityConfig(show_success=False, verify_naming=False)
+        hook_data = {
+            "tool_name": "Write",
+            "tool_output": {"file_path": f"{tempfile.gettempdir()}/test.py"},
+        }
+
+        with patch("pathlib.Path.exists", return_value=True):
+            with patch("pathlib.Path.read_text", return_value=clean_code):
+                result = posttooluse_hook(hook_data, config)
+                assert result["decision"] == "allow"
+                assert "message" not in result
+
+    def test_all_features_combined(self):
+        """Test all PostToolUse features combined."""
+        config = QualityConfig(
+            state_tracking_enabled=True,
+            cross_file_check_enabled=True,
+            verify_naming=True,
+            show_success=False,
+        )
+        hook_data = {
+            "tool_name": "Write",
+            "tool_output": {"file_path": f"{tempfile.gettempdir()}/test.py"},
+        }
+
+        with patch("pathlib.Path.exists", return_value=True):
+            with patch("pathlib.Path.read_text", return_value="def test(): pass"):
+                with patch("code_quality_guard.check_state_changes") as mock_state:
+                    with patch(
+                        "code_quality_guard.check_cross_file_duplicates",
+                    ) as mock_cross:
+                        with patch(
+                            "code_quality_guard.verify_naming_conventions",
+                        ) as mock_naming:
+                            mock_state.return_value = ["⚠️ Issue 1"]
+                            mock_cross.return_value = ["⚠️ Issue 2"]
+                            mock_naming.return_value = ["⚠️ Issue 3"]
+
+                            result = posttooluse_hook(hook_data, config)
+                            assert result["decision"] == "allow"
+                            assert "Issue 1" in result["message"]
+                            assert "Issue 2" in result["message"]
+                            assert "Issue 3" in result["message"]
+
+    def test_edit_tool_output(self):
+        """Test Edit tool output handling."""
+        config = QualityConfig(verify_naming=True)
+        hook_data = {
+            "tool_name": "Edit",
+            "tool_output": {
+                "file_path": f"{tempfile.gettempdir()}/test.py",
+                "status": "success",
+            },
+        }
+
+        with patch("pathlib.Path.exists", return_value=True):
+            with patch("pathlib.Path.read_text", return_value="def test(): pass"):
+                result = posttooluse_hook(hook_data, config)
+                assert result["decision"] == "allow"
+
+    def test_multiedit_tool_output(self):
+        """Test MultiEdit tool output handling."""
+        config = QualityConfig(verify_naming=True)
+        hook_data = {
+            "tool_name": "MultiEdit",
+            "tool_output": {
+                "file_path": f"{tempfile.gettempdir()}/test.py",
+                "edits_applied": 3,
+            },
+        }
+
+        with patch("pathlib.Path.exists", return_value=True):
+            with patch("pathlib.Path.read_text", return_value="def test(): pass"):
+                result = posttooluse_hook(hook_data, config)
+                assert result["decision"] == "allow"
+
+    def test_features_disabled(self):
+        """Test with all features disabled."""
+        config = QualityConfig(
+            state_tracking_enabled=False,
+            cross_file_check_enabled=False,
+            verify_naming=False,
+            show_success=False,
+        )
+        hook_data = {
+            "tool_name": "Write",
+            "tool_output": {"file_path": f"{tempfile.gettempdir()}/test.py"},
+        }
+
+        with patch("pathlib.Path.exists", return_value=True):
+            with patch("pathlib.Path.read_text", return_value="def test(): pass"):
+                # Should not call any check functions
+                with patch("code_quality_guard.check_state_changes") as mock_state:
+                    with patch(
+                        "code_quality_guard.check_cross_file_duplicates",
+                    ) as mock_cross:
+                        with patch(
+                            "code_quality_guard.verify_naming_conventions",
+                        ) as mock_naming:
+                            result = posttooluse_hook(hook_data, config)
+
+                            # Verify no checks were called
+                            mock_state.assert_not_called()
+                            mock_cross.assert_not_called()
+                            mock_naming.assert_not_called()
+
+                            assert result["decision"] == "allow"
+                            assert "message" not in result

tests/hooks/test_pretooluse.py

@@ -0,0 +1,324 @@
+"""Test PreToolUse hook functionality."""
+
+from unittest.mock import patch
+
+from code_quality_guard import QualityConfig, pretooluse_hook
+
+
+class TestPreToolUseHook:
+    """Test PreToolUse hook behavior."""
+
+    def test_non_write_tool_allowed(self):
+        """Test that non-write/edit tools are always allowed."""
+        config = QualityConfig()
+        hook_data = {
+            "tool_name": "Read",
+            "tool_input": {"file_path": "test.py"},
+        }
+
+        result = pretooluse_hook(hook_data, config)
+        assert result["decision"] == "allow"
+
+    def test_non_python_file_allowed(self):
+        """Test that non-Python files are always allowed."""
+        config = QualityConfig()
+        hook_data = {
+            "tool_name": "Write",
+            "tool_input": {
+                "file_path": "test.js",
+                "content": "const x = 1;",
+            },
+        }
+
+        result = pretooluse_hook(hook_data, config)
+        assert result["decision"] == "allow"
+
+    def test_test_file_skipped(self):
+        """Test that test files are skipped when configured."""
+        config = QualityConfig()
+        hook_data = {
+            "tool_name": "Write",
+            "tool_input": {
+                "file_path": "test_example.py",
+                "content": "def test(): pass",
+            },
+        }
+
+        result = pretooluse_hook(hook_data, config)
+        assert result["decision"] == "allow"
+
+    def test_clean_code_allowed(self, clean_code):
+        """Test that clean code is allowed."""
+        config = QualityConfig()
+        hook_data = {
+            "tool_name": "Write",
+            "tool_input": {
+                "file_path": "example.py",
+                "content": clean_code,
+            },
+        }
+
+        with patch("code_quality_guard.analyze_code_quality") as mock_analyze:
+            mock_analyze.return_value = {}
+            result = pretooluse_hook(hook_data, config)
+            assert result["decision"] == "allow"
+
+    def test_complex_code_denied_strict(self, complex_code):
+        """Test that complex code is denied in strict mode."""
+        config = QualityConfig(enforcement_mode="strict")
+        hook_data = {
+            "tool_name": "Write",
+            "tool_input": {
+                "file_path": "example.py",
+                "content": complex_code,
+            },
+        }
+
+        with patch("code_quality_guard.analyze_code_quality") as mock_analyze:
+            mock_analyze.return_value = {
+                "complexity": {
+                    "summary": {"average_cyclomatic_complexity": 25},
+                    "distribution": {"High": 1},
+                },
+            }
+
+            result = pretooluse_hook(hook_data, config)
+            assert result["decision"] == "deny"
+            assert "quality check failed" in result["message"].lower()
+
+    def test_complex_code_ask_warn_mode(self, complex_code):
+        """Test that complex code triggers ask in warn mode."""
+        config = QualityConfig(enforcement_mode="warn")
+        hook_data = {
+            "tool_name": "Write",
+            "tool_input": {
+                "file_path": "example.py",
+                "content": complex_code,
+            },
+        }
+
+        with patch("code_quality_guard.analyze_code_quality") as mock_analyze:
+            mock_analyze.return_value = {
+                "complexity": {
+                    "summary": {"average_cyclomatic_complexity": 25},
+                    "distribution": {"High": 1},
+                },
+            }
+
+            result = pretooluse_hook(hook_data, config)
+            assert result["decision"] == "ask"
+
+    def test_complex_code_allowed_permissive(self, complex_code):
+        """Test that complex code is allowed with warning in permissive mode."""
+        config = QualityConfig(enforcement_mode="permissive")
+        hook_data = {
+            "tool_name": "Write",
+            "tool_input": {
+                "file_path": "example.py",
+                "content": complex_code,
+            },
+        }
+
+        with patch("code_quality_guard.analyze_code_quality") as mock_analyze:
+            mock_analyze.return_value = {
+                "complexity": {
+                    "summary": {"average_cyclomatic_complexity": 25},
+                    "distribution": {"High": 1},
+                },
+            }
+
+            result = pretooluse_hook(hook_data, config)
+            assert result["decision"] == "allow"
+            assert "warning" in result["message"].lower()
+
+    def test_duplicate_code_detection(self, duplicate_code):
+        """Test internal duplicate detection."""
+        config = QualityConfig(duplicate_enabled=True)
+        hook_data = {
+            "tool_name": "Write",
+            "tool_input": {
+                "file_path": "example.py",
+                "content": duplicate_code,
+            },
+        }
+
+        with patch("code_quality_guard.detect_internal_duplicates") as mock_dup:
+            mock_dup.return_value = {
+                "duplicates": [
+                    {
+                        "similarity": 0.9,
+                        "description": "Similar functions",
+                        "locations": [
+                            {"name": "func1", "lines": "1-5"},
+                            {"name": "func2", "lines": "7-11"},
+                        ],
+                    },
+                ],
+            }
+
+            with patch("code_quality_guard.analyze_code_quality") as mock_analyze:
+                mock_analyze.return_value = {
+                    "internal_duplicates": mock_dup.return_value,
+                }
+
+                result = pretooluse_hook(hook_data, config)
+                assert result["decision"] == "deny"
+                assert "duplication" in result["message"].lower()
+
+    def test_edit_tool_handling(self):
+        """Test Edit tool content extraction."""
+        config = QualityConfig()
+        hook_data = {
+            "tool_name": "Edit",
+            "tool_input": {
+                "file_path": "example.py",
+                "old_string": "def old():\n    pass",
+                "new_string": "def new():\n    return True",
+            },
+        }
+
+        with patch("code_quality_guard.analyze_code_quality") as mock_analyze:
+            mock_analyze.return_value = {}
+            result = pretooluse_hook(hook_data, config)
+            assert result["decision"] == "allow"
+
+            # Verify new_string was analyzed
+            call_args = mock_analyze.call_args[0]
+            assert "def new()" in call_args[0]
+
+    def test_multiedit_tool_handling(self):
+        """Test MultiEdit tool content extraction."""
+        config = QualityConfig()
+        hook_data = {
+            "tool_name": "MultiEdit",
+            "tool_input": {
+                "file_path": "example.py",
+                "edits": [
+                    {"old_string": "a", "new_string": "def func1():\n    pass"},
+                    {"old_string": "b", "new_string": "def func2():\n    pass"},
+                ],
+            },
+        }
+
+        with patch("code_quality_guard.analyze_code_quality") as mock_analyze:
+            mock_analyze.return_value = {}
+            result = pretooluse_hook(hook_data, config)
+            assert result["decision"] == "allow"
+
+            # Verify concatenated content was analyzed
+            call_args = mock_analyze.call_args[0]
+            assert "def func1()" in call_args[0]
+            assert "def func2()" in call_args[0]
+
+    def test_state_tracking_enabled(self):
+        """Test state tracking when enabled."""
+        config = QualityConfig(state_tracking_enabled=True)
+        hook_data = {
+            "tool_name": "Write",
+            "tool_input": {
+                "file_path": "example.py",
+                "content": "def test():\n    pass",
+            },
+        }
+
+        with patch("code_quality_guard.store_pre_state") as mock_store:
+            with patch("code_quality_guard.analyze_code_quality") as mock_analyze:
+                mock_analyze.return_value = {}
+                pretooluse_hook(hook_data, config)
+
+                # Verify state was stored
+                mock_store.assert_called_once()
+                assert mock_store.call_args[0][0] == "example.py"
+
+    def test_exception_handling(self):
+        """Test graceful handling of exceptions."""
+        config = QualityConfig()
+        hook_data = {
+            "tool_name": "Write",
+            "tool_input": {
+                "file_path": "example.py",
+                "content": "def test():\n    pass",
+            },
+        }
+
+        with patch("code_quality_guard.analyze_code_quality") as mock_analyze:
+            mock_analyze.side_effect = Exception("Analysis failed")
+            result = pretooluse_hook(hook_data, config)
+
+            assert result["decision"] == "allow"
+            assert "error" in result["message"].lower()
+
+    def test_custom_skip_patterns(self):
+        """Test custom skip patterns."""
+        config = QualityConfig(skip_patterns=["custom_skip_", "/ignored/"])
+
+        # Test custom pattern match
+        hook_data = {
+            "tool_name": "Write",
+            "tool_input": {
+                "file_path": "custom_skip_file.py",
+                "content": "bad code",
+            },
+        }
+        result = pretooluse_hook(hook_data, config)
+        assert result["decision"] == "allow"
+
+        # Test path pattern match
+        hook_data["tool_input"]["file_path"] = "/ignored/file.py"
+        result = pretooluse_hook(hook_data, config)
+        assert result["decision"] == "allow"
+
+    def test_modernization_issues(self, old_style_code):
+        """Test modernization issue detection."""
+        config = QualityConfig(modernization_enabled=True, require_type_hints=True)
+        hook_data = {
+            "tool_name": "Write",
+            "tool_input": {
+                "file_path": "example.py",
+                "content": old_style_code,
+            },
+        }
+
+        with patch("code_quality_guard.analyze_code_quality") as mock_analyze:
+            mock_analyze.return_value = {
+                "modernization": {
+                    "files": {
+                        "test.py": [
+                            {"issue_type": "use_enumerate", "line": 3},
+                            {"issue_type": "use_is_none", "line": 4},
+                        ],
+                    },
+                },
+            }
+
+            result = pretooluse_hook(hook_data, config)
+            assert result["decision"] == "deny"
+            assert "modernization" in result["message"].lower()
+
+    def test_type_hint_threshold(self):
+        """Test type hint issue threshold."""
+        config = QualityConfig(require_type_hints=True)
+        hook_data = {
+            "tool_name": "Write",
+            "tool_input": {
+                "file_path": "example.py",
+                "content": "def test(): pass",
+            },
+        }
+
+        # Test with many type hint issues
+        with patch("code_quality_guard.analyze_code_quality") as mock_analyze:
+            mock_analyze.return_value = {
+                "modernization": {
+                    "files": {
+                        "test.py": [
+                            {"issue_type": "missing_return_type", "line": i}
+                            for i in range(15)  # 15 type hint issues
+                        ],
+                    },
+                },
+            }
+
+            result = pretooluse_hook(hook_data, config)
+            assert result["decision"] == "deny"
+            assert "type hints" in result["message"].lower()