crackerjack 0.26.0__tar.gz → 0.27.1__tar.gz

{crackerjack-0.26.0/crackerjack → crackerjack-0.27.1}/.gitignore

@@ -18,3 +18,14 @@
 /coverage.json
 /test-results.xml
 /.coverage
+
+# AI agent output files
+/hooks-analysis.json
+/quality-metrics.json
+/project-structure.json
+/error-context.json
+/ai-agent-summary.json
+/bandit-report.json
+
+# Autotyping cache
+.autotyping-cache/

{crackerjack-0.26.0 → crackerjack-0.27.1}/.pre-commit-config-ai.yaml

@@ -1,105 +1,112 @@
+# AI-optimized pre-commit hooks for comprehensive analysis and structured output
+# Designed for AI agent workflows with enhanced reporting and metrics
+
 repos:
-  # File structure and format validators - check structure first
+  # Group 1: File Structure & Format Validation (parallel-safe, fast)
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v5.0.0
     hooks:
       - id: trailing-whitespace
         name: trailing-whitespace
-        verbose: true
+        stages: [pre-commit]
       - id: end-of-file-fixer
         name: end-of-file-fixer
-        verbose: true
+        stages: [pre-commit]
       - id: check-yaml
         name: check-yaml
-        verbose: true
+        stages: [pre-commit]
       - id: check-toml
         name: check-toml
-        verbose: true
+        stages: [pre-commit]
       - id: check-added-large-files
         name: check-added-large-files
-        verbose: true
+        stages: [pre-commit]
 
+  # Group 2: Project Configuration Management
   - repo: https://github.com/abravalheri/validate-pyproject
     rev: v0.24.1
     hooks:
       - id: validate-pyproject
-        verbose: true
+        stages: [pre-commit]
 
   - repo: https://github.com/tox-dev/pyproject-fmt
     rev: "v2.6.0"
     hooks:
       - id: pyproject-fmt
         args: ["-n"]
-        verbose: true
+        stages: [pre-commit]
 
-  # Package management - once structure is valid
   - repo: https://github.com/astral-sh/uv-pre-commit
-    rev: 0.7.15
+    rev: 0.7.21
     hooks:
       - id: uv-lock
         files: ^pyproject\.toml$
-        verbose: true
+        stages: [pre-commit]
 
-  # Security check - early to prevent credential leaks
+  # Group 3: Security (early detection, critical)
   - repo: https://github.com/Yelp/detect-secrets
     rev: v1.5.0
     hooks:
       - id: detect-secrets
         exclude: 'uv\.lock|pyproject\.toml|tests/.*|docs/.*|.*\.md'
-        verbose: true
+        stages: [pre-commit]
 
-  # Code quality tier 1 - quick fixes
+  # Group 4: Code Quality & Style (fast formatting)
   - repo: https://github.com/codespell-project/codespell
     rev: v2.4.1
     hooks:
       - id: codespell
-        verbose: true
         additional_dependencies:
           - tomli
+        stages: [pre-commit]
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.12.1
+    rev: v0.12.3
     hooks:
       - id: ruff-check
-        verbose: true
-        args: [--output-format=json]
+        args: ["--output-format=json", "--fix"]
+        stages: [pre-commit]
       - id: ruff-format
-        verbose: true
+        stages: [pre-commit]
 
   - repo: https://github.com/executablebooks/mdformat
-    rev: 0.7.18
+    rev: 0.7.22
     hooks:
       - id: mdformat
         additional_dependencies:
           - mdformat-ruff
+        stages: [pre-commit]
 
-  # Code quality tier 2 - analysis
+  # Group 5: Static Analysis (comprehensive, slower)
   - repo: https://github.com/jendrikseipp/vulture
     rev: 'v2.14'
     hooks:
       - id: vulture
-        verbose: true
+        args: ["--verbose"]
+        stages: [pre-commit]
 
   - repo: https://github.com/fredrikaverpil/creosote
     rev: v4.0.3
     hooks:
       - id: creosote
-        verbose: true
+        args: ["--verbose"]
+        stages: [pre-commit]
 
   - repo: https://github.com/rohaquinlop/complexipy-pre-commit
     rev: v3.0.0
     hooks:
       - id: complexipy
-        args: ["-d", "low", "-j"]
-        verbose: true
+        args: ["-d", "low", "--output", "complexipy.json"]
+        stages: [pre-commit]
 
   - repo: https://github.com/dosisod/refurb
     rev: v2.1.0
     hooks:
       - id: refurb
-        verbose: true
+        args: ["--quiet"]
+        stages: [pre-commit]
 
-  # Code quality tier 3 - thorough checks
+  # Group 6: Type Checking & Enhancement (most expensive)
   - repo: local
     hooks:
       - id: autotyping
@@ -109,25 +116,38 @@ repos:
           - --aggressive
           - --only-without-imports
           - --guess-common-names
+          - --cache-dir=.autotyping-cache
+          - --workers=4
+          - --max-line-length=88
+          - --exclude-name=test_*,conftest
           - crackerjack
         types_or: [ python, pyi ]
         language: python
-        files: \.py$
-        verbose: true
+        files: ^crackerjack/.*\.py$
+        stages: [pre-commit]
         additional_dependencies:
           - autotyping>=24.3.0
           - libcst>=1.1.0
 
   - repo: https://github.com/PyCQA/bandit
-    rev: '1.8.5'
+    rev: '1.8.6'
     hooks:
       - id: bandit
-        args: ["-c", "pyproject.toml", "--format", "json"]
-        verbose: true
+        args: ["-c", "pyproject.toml", "-f", "json", "-o", "bandit-report.json", "-r", "-ll"]
+        stages: [pre-commit]
 
   - repo: https://github.com/RobertCraigie/pyright-python
-    rev: v1.1.402
+    rev: v1.1.403
     hooks:
       - id: pyright
-        verbose: true
         args: ["--outputjson"]
+        stages: [pre-commit]
+
+  # Group 7: Documentation & Security Enhancement (AI-specific)
+  # pydocstyle temporarily disabled - conflicts with code cleaning functionality
+  # - repo: https://github.com/PyCQA/pydocstyle
+  #   rev: 6.3.0
+  #   hooks:
+  #     - id: pydocstyle
+  #       args: ["--config=pyproject.toml"]
+  #       stages: [pre-commit]

crackerjack-0.27.1/.pre-commit-config-fast.yaml

@@ -0,0 +1,69 @@
+# Fast pre-commit hooks for development workflow (target: <5s total)
+repos:
+  # Tier 1: Basic structure validation (1.5s)
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+        name: trailing-whitespace
+        stages: [pre-commit]
+      - id: end-of-file-fixer
+        name: end-of-file-fixer
+        stages: [pre-commit]
+      - id: check-yaml
+        name: check-yaml
+        stages: [pre-commit]
+      - id: check-toml
+        name: check-toml
+        stages: [pre-commit]
+      - id: check-added-large-files
+        name: check-added-large-files
+        stages: [pre-commit]
+
+  - repo: https://github.com/tox-dev/pyproject-fmt
+    rev: "v2.6.0"
+    hooks:
+      - id: pyproject-fmt
+        args: ["-n"]
+        stages: [pre-commit]
+
+  # Tier 2: Package management (0.5s)
+  - repo: https://github.com/astral-sh/uv-pre-commit
+    rev: 0.7.21
+    hooks:
+      - id: uv-lock
+        files: ^pyproject\.toml$
+        stages: [pre-commit]
+
+  # Tier 3: Security (early detection) (1s)
+  - repo: https://github.com/Yelp/detect-secrets
+    rev: v1.5.0
+    hooks:
+      - id: detect-secrets
+        exclude: 'uv\.lock|pyproject\.toml|tests/.*|docs/.*|.*\.md'
+        stages: [pre-commit]
+
+  # Tier 4: Quick formatting (1.5s)
+  - repo: https://github.com/codespell-project/codespell
+    rev: v2.4.1
+    hooks:
+      - id: codespell
+        additional_dependencies:
+          - tomli
+        stages: [pre-commit]
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.12.3
+    hooks:
+      - id: ruff-check
+        stages: [pre-commit]
+      - id: ruff-format
+        stages: [pre-commit]
+
+  - repo: https://github.com/executablebooks/mdformat
+    rev: 0.7.22
+    hooks:
+      - id: mdformat
+        additional_dependencies:
+          - mdformat-ruff
+        stages: [pre-commit]

{crackerjack-0.26.0 → crackerjack-0.27.1}/.pre-commit-config.yaml

@@ -55,29 +55,33 @@ repos:
         additional_dependencies:
           - mdformat-ruff
 
-  # Code quality tier 2 - analysis
+  # Code quality tier 2 - analysis (moved to pre-push for performance)
   - repo: https://github.com/jendrikseipp/vulture
     rev: 'v2.14'
     hooks:
       - id: vulture
+        stages: [pre-push, manual]
 
   - repo: https://github.com/fredrikaverpil/creosote
     rev: v4.0.3
     hooks:
       - id: creosote
+        stages: [pre-push, manual]
 
   - repo: https://github.com/rohaquinlop/complexipy-pre-commit
     rev: v3.0.0
     hooks:
       - id: complexipy
         args: ["-d", "low"]
+        stages: [pre-push, manual]
 
   - repo: https://github.com/dosisod/refurb
     rev: v2.1.0
     hooks:
       - id: refurb
+        stages: [pre-push, manual]
 
-  # Code quality tier 3 - thorough checks
+  # Code quality tier 3 - thorough checks (moved to pre-push for performance)
   - repo: local
     hooks:
       - id: autotyping
@@ -90,7 +94,8 @@ repos:
           - crackerjack
         types_or: [ python, pyi ]
         language: python
-        files: \.py$
+        files: ^crackerjack/.*\.py$
+        stages: [pre-push, manual]
         additional_dependencies:
           - autotyping>=24.3.0
           - libcst>=1.1.0
@@ -99,9 +104,11 @@ repos:
     rev: '1.8.6'
     hooks:
       - id: bandit
-        args: ["-c", "pyproject.toml"]
+        args: ["-c", "pyproject.toml", "-r", "-ll"]
+        stages: [pre-push, manual]
 
   - repo: https://github.com/RobertCraigie/pyright-python
     rev: v1.1.403
     hooks:
       - id: pyright
+        stages: [pre-push, manual]

{crackerjack-0.26.0 → crackerjack-0.27.1}/CLAUDE.md

@@ -44,6 +44,12 @@ python -m crackerjack -r
 
 # Enable verbose output
 python -m crackerjack -v
+
+# Run with fast pre-commit mode (default)
+python -m crackerjack
+
+# Run with comprehensive pre-commit checks
+python -m crackerjack --comprehensive
 ```
 
 ### Testing
@@ -80,6 +86,69 @@ python -m crackerjack -t --benchmark-regression --benchmark-regression-threshold
 python -m crackerjack --ai-agent -t
 ```
 
+### Running a Single Test
+
+```bash
+# Run a specific test file
+uv run pytest tests/test_crackerjack.py
+
+# Run a specific test function
+uv run pytest tests/test_crackerjack.py::test_code_cleaner_remove_docstrings
+
+# Run tests matching a pattern
+uv run pytest -k "test_code_cleaner"
+
+# Run with verbose output
+uv run pytest -v tests/test_crackerjack.py
+
+# Run with no parallel execution
+uv run pytest -n 0 tests/test_crackerjack.py
+```
+
+### Benchmark Testing Strategy
+
+Benchmarks should be run automatically at strategic intervals to catch performance regressions early:
+
+#### **Recommended Frequency:**
+
+**🚀 Critical Scenarios (Always Run Benchmarks):**
+
+```bash
+# Before major releases
+python -m crackerjack -t --benchmark-regression --benchmark-regression-threshold=5.0
+
+# After significant algorithmic changes (manual trigger)
+python -m crackerjack -t --benchmark --ai-agent
+```
+
+**📊 Regular Monitoring (Weekly):**
+
+```bash
+# Weekly automated benchmark monitoring
+python -m crackerjack -t --benchmark-regression --benchmark-regression-threshold=10.0
+```
+
+**🎲 Random Sampling (10% of commits):**
+
+```bash
+# Stochastic performance monitoring (implement in CI/CD)
+# Run on ~10% of commits to catch gradual performance drift
+python -m crackerjack -t --benchmark
+```
+
+#### **When to Run Benchmarks:**
+
+1. **Always:** Before releases, after performance-critical changes
+1. **Weekly:** Automated monitoring for performance drift detection
+1. **Randomly:** 10% of commits for stochastic performance sampling
+1. **On-demand:** When investigating performance issues
+
+#### **Benchmark Thresholds:**
+
+- **5% regression threshold:** For release candidates and critical changes
+- **10% regression threshold:** For regular monitoring and development
+- **Custom thresholds:** Adjust based on specific performance requirements
+
 ### Linting and Code Quality
 
 ```bash
@@ -238,6 +307,7 @@ Crackerjack follows a single-file architecture for simplicity and maintainabilit
 | `-v` | `--verbose` | Enable verbose output |
 | `-s` | `--skip-hooks` | Skip pre-commit hooks |
 | `-n` | `--no-config-updates` | Skip configuration updates |
+| | `--comprehensive` | Use comprehensive pre-commit hooks (slower but thorough) |
 
 ### Version Management
 
@@ -263,6 +333,7 @@ Crackerjack follows a single-file architecture for simplicity and maintainabilit
 1. **Code Style**: Follow the Crackerjack style guide (see RULES.md):
 
    - **Target Python 3.13+** - Use latest Python features
+   - **NO DOCSTRINGS** - The codebase standard is to have no docstrings (they are removed by the `-x` flag)
    - Use static typing throughout with modern syntax (import typing as `t`)
    - Use pathlib for file operations
    - Prefer Protocol over ABC
@@ -302,6 +373,13 @@ When generating code, AI assistants MUST follow these standards to ensure compli
 
 **IMPORTANT: Target Python 3.13+** - All code must be compatible with Python 3.13 or newer. Use the latest Python features and syntax.
 
+**CRITICAL: NO DOCSTRINGS** - Crackerjack's standard is to have NO docstrings in the package code. The `-x` (clean) flag removes all docstrings to reduce noise and keep the codebase clean. When generating code:
+
+- **DO NOT** add docstrings to functions, methods, classes, or modules
+- **DO NOT** add triple-quoted string documentation anywhere
+- Use inline comments sparingly only when absolutely necessary for complex logic
+- The codebase prioritizes clean, self-documenting code over documentation strings
+
 ### Refurb Standards (Modern Python Patterns up to 3.12)
 
 **Use modern syntax and built-ins:**
@@ -743,7 +821,163 @@ This enhancement ensures that the code cleaner (`-x` flag) can handle edge cases
 
 **Never skip crackerjack verification** - it's the project's standard quality gate.
 
+## Pre-commit Hook Maintenance
+
+### Monthly Maintenance Tasks
+
+1. **Update hook versions**: Run `pre-commit autoupdate` to get latest versions
+1. **Review security advisories**: Check for vulnerabilities in hook dependencies
+1. **Monitor performance**: Watch for hooks taking longer than expected
+1. **Check deprecation warnings**: Address any warnings from tools like autotyping
+
+### Performance Optimization
+
+- **Autotyping monitoring**: Currently 7.3s runtime (highest cost hook)
+- **Grouping strategy**: Consider grouping related hooks for better failure reporting
+- **CI/CD integration**: Move expensive operations to pre-push hooks for CI/CD
+
+### Security Maintenance
+
+- **Regular vulnerability scanning**: Use `pre-commit autoupdate` with caution on untrusted hooks
+- **Source verification**: Ensure all hooks come from trusted, actively maintained repositories
+- **Dependency monitoring**: Watch for security issues in hook dependencies via Snyk or similar tools
+
+### Quality Metrics to Monitor
+
+- Test coverage should remain ≥90%
+- Zero security vulnerabilities (Bandit)
+- Zero type errors (Pyright)
+- Zero dead code (Vulture)
+- Zero unused dependencies (Creosote)
+- Low complexity maintained (Complexipy)
+
+### Hook Performance Optimization (Enhanced July 2025)
+
+**🚀 Fast Development Mode (Default):**
+
+- Uses `.pre-commit-config-fast.yaml` for regular commits
+- Target execution time: \<5 seconds
+- Includes: structure validation, formatting, basic security checks
+- Command: `python -m crackerjack` (default behavior)
+
+**🔍 Comprehensive Analysis Mode:**
+
+- Uses `.pre-commit-config.yaml` for thorough analysis
+- Target execution time: \<30 seconds
+- Includes: all checks + type analysis, complexity, dead code detection
+- Command: `python -m crackerjack --comprehensive`
+
+**📦 Pre-push Hooks:**
+
+- Expensive operations automatically moved to pre-push stage
+- Runs comprehensive analysis before pushing changes
+- Prevents performance bottlenecks during development
+- Install: `pre-commit install --hook-type pre-push`
+
+### Hook Configuration Status (Last Audit: July 2025)
+
+✅ All hooks current and secure
+✅ Performance optimized with dual-mode configuration
+✅ Fast mode: \<5s execution time
+✅ Comprehensive mode: \<30s execution time
+✅ 90% test coverage achieved
+✅ 0 security vulnerabilities found
+
 ## Development Memories
 
 - Non-critical type errors are still errors that need to be fixed to pass crackerjack validation
 - test directory files need to pass pyright tests as well in order for crackerjack to successfully complete
+
+## AI Agent Integration
+
+When running with `--ai-agent` flag, Crackerjack produces structured output optimized for AI assistants:
+
+### Generated Files
+
+- **`test-results.xml`**: JUnit XML format test results with detailed test outcomes
+- **`coverage.json`**: JSON coverage report with line-by-line coverage data
+- **`benchmark.json`**: Benchmark results in JSON format (when benchmarks are run)
+- **`ai-agent-summary.json`**: Summary of the entire run with status and actions performed
+
+### Example AI-Optimized Commands
+
+```bash
+# Run tests with structured output for AI analysis
+python -m crackerjack --ai-agent -t
+
+# Run full workflow with AI output
+python -m crackerjack --ai-agent -a patch
+
+# Run benchmarks with AI output
+python -m crackerjack --ai-agent -t --benchmark
+```
+
+See README-AI-AGENT.md for detailed information about AI agent integration.
+
+## Test Execution Details
+
+### Test Configuration (pytest.ini_options)
+
+- **asyncio_mode**: "auto" - Automatic asyncio test detection and handling
+- **testpaths**: ["tests", "crackerjack"] - Directories to search for tests
+- **timeout**: 300 seconds default per test
+- **timeout_method**: "thread" - Uses thread-based timeout mechanism
+- **coverage**: Configured with --cov=crackerjack --cov-fail-under=42
+
+### Special Test Markers
+
+- **unit**: Unit tests
+- **benchmark**: Benchmark tests (disables parallel execution)
+- **integration**: Integration tests
+- **no_leaks**: Detect asyncio task leaks, thread leaks, and event loop blocking
+
+### Test Parallelization
+
+Tests run in parallel by default using pytest-xdist. The number of workers is automatically determined based on:
+
+- Project size (small/medium/large)
+- Available CPU cores
+- Benchmark mode (disables parallelization)
+- User-specified `--test-workers` option
+
+### Benchmark Testing
+
+When running benchmarks:
+
+- Parallel execution is automatically disabled
+- pytest-benchmark plugin is configured with optimized settings
+- Results can be compared against previous runs for regression detection
+- Benchmark results are saved in JSON format when using `--ai-agent`
+
+## Pre-commit Hook Configurations
+
+### Fast Mode (.pre-commit-config-fast.yaml)
+
+Optimized for development speed (\<5s):
+
+- Basic structure validation
+- UV lock file updates
+- Security checks (detect-secrets)
+- Quick formatting (codespell, ruff)
+- Markdown formatting (mdformat with ruff integration)
+
+### Comprehensive Mode (.pre-commit-config.yaml)
+
+Full analysis suite (\<30s):
+
+- All fast mode checks
+- Type checking (pyright)
+- Code modernization (refurb)
+- Security scanning (bandit)
+- Dead code detection (vulture)
+- Unused dependency detection (creosote)
+- Code complexity analysis (complexipy)
+- Automatic type annotation (autotyping)
+
+### Pre-push Hooks
+
+For expensive operations that should run before pushing:
+
+- Install with: `pre-commit install --hook-type pre-push`
+- Runs comprehensive analysis automatically
+- Prevents pushing code that doesn't meet quality standards

{crackerjack-0.26.0 → crackerjack-0.27.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crackerjack
-Version: 0.26.0
+Version: 0.27.1
 Summary: Crackerjack: code quality toolkit
 Project-URL: documentation, https://github.com/lesleslie/crackerjack
 Project-URL: homepage, https://github.com/lesleslie/crackerjack
@@ -23,6 +23,7 @@ Classifier: Topic :: Software Development :: Testing
 Classifier: Topic :: Utilities
 Classifier: Typing :: Typed
 Requires-Python: >=3.13
+Requires-Dist: aiofiles>=24.1
 Requires-Dist: autotyping>=24.9
 Requires-Dist: hatchling>=1.25
 Requires-Dist: keyring>=25.6

{crackerjack-0.26.0 → crackerjack-0.27.1}/RULES.md

@@ -23,9 +23,10 @@
 - **Clean Code Architecture**
 
   - Write modular functions that do one thing well
-  - Avoid unnecessary docstrings and line comments
+  - **NO DOCSTRINGS**: Never add docstrings to any code - the codebase standard is to have no docstrings (they are automatically removed by the `-x` flag)
+  - Avoid unnecessary line comments - use them sparingly only for complex logic
   - Use protocols (`t.Protocol`) instead of abstract base classes
-  - Choose clear, descriptive variable and function names
+  - Choose clear, descriptive variable and function names that make the code self-documenting
 
 - **Code Organization**
 

{crackerjack-0.26.0 → crackerjack-0.27.1/crackerjack}/.gitignore

@@ -18,3 +18,14 @@
 /coverage.json
 /test-results.xml
 /.coverage
+
+# AI agent output files
+/hooks-analysis.json
+/quality-metrics.json
+/project-structure.json
+/error-context.json
+/ai-agent-summary.json
+/bandit-report.json
+
+# Autotyping cache
+.autotyping-cache/