crackerjack 0.37.9__py3-none-any.whl → 0.45.2__py3-none-any.whl

crackerjack/py313.py

@@ -0,0 +1,191 @@
+import subprocess
+import typing
+from enum import Enum, auto
+from pathlib import Path
+from typing import Any, Self, TypedDict
+
+
+class CommandRunner[TReturn]:
+    def run_command(self, cmd: list[str], **kwargs: Any) -> TReturn:
+        raise NotImplementedError("Subclasses must implement run_command")
+
+
+class CommandResult(TypedDict):
+    success: bool
+    exit_code: int
+    stdout: str
+    stderr: str
+    command: list[str]
+    duration_ms: float
+
+
+def process_command_output(result: CommandResult) -> tuple[bool, str]:
+    match result:
+        case {"success": True, "stdout": stdout} if stdout.strip():
+            return (True, stdout)
+        case {"success": True}:
+            return (True, "Command completed successfully with no output")
+        case {"success": False, "exit_code": code, "stderr": stderr} if code == 127:
+            return (False, f"Command not found: {stderr}")
+        case {"success": False, "exit_code": code} if code > 0:
+            return (False, f"Command failed with exit code {code}: {result['stderr']}")
+        case _:
+            pass
+    return (False, "Unknown command result pattern")
+
+
+class HookStatus(Enum):
+    SUCCESS = auto()
+    FAILURE = auto()
+    SKIPPED = auto()
+    ERROR = auto()
+
+
+class HookResult(TypedDict):
+    status: HookStatus
+    hook_id: str
+    output: str
+    files: list[str]
+
+
+def analyze_hook_result(result: HookResult) -> str:
+    match result:
+        case {"status": HookStatus.SUCCESS, "hook_id": hook_id}:
+            return f"✅ Hook {hook_id} passed successfully"
+        case {"status": HookStatus.FAILURE, "hook_id": hook_id, "output": output} if (
+            "fixable" in output
+        ):
+            return f"🔧 Hook {hook_id} failed with fixable issues"
+        case {"status": HookStatus.FAILURE, "hook_id": hook_id}:
+            return f"❌ Hook {hook_id} failed"
+        case {"status": HookStatus.SKIPPED, "hook_id": hook_id}:
+            return f"⏩ Hook {hook_id} was skipped"
+        case {"status": HookStatus.ERROR, "hook_id": hook_id, "output": output}:
+            return f"💥 Hook {hook_id} encountered an error: {output}"
+        case _:
+            pass
+    return "Unknown hook result pattern"
+
+
+class ModernConfigManager:
+    def __init__(self, config_path: Path) -> None:
+        self.config_path = config_path
+        self.config: dict[str, Any] = {}
+
+    def load(self) -> Self:
+        return self
+
+    def update(self, key: str, value: Any) -> Self:
+        self.config[key] = value
+        return self
+
+    def save(self) -> Self:
+        return self
+
+
+def categorize_file(file_path: Path) -> str:
+    path_str = str(file_path)
+    name = file_path
+    match path_str:
+        case s if name.suffix == ".py" and "/ tests /" in s:
+            return "Python Test File"
+        case s if name.suffix == ".py" and "__init__.py" in name.name:
+            return "Python Module Init"
+        case s if name.suffix == ".py":
+            return "Python Source File"
+        case s if name.suffix in {".md", ".rst", ".txt"}:
+            return "Documentation File"
+        case s if name.stem.startswith(".") or name.name in {
+            ".gitignore",
+            ".pre-commit-config.yaml",
+        }:
+            return "Configuration File"
+        case _:
+            pass
+    return "Unknown File Type"
+
+
+def process_hook_results[T: HookResult, R](
+    results: list[T],
+    success_handler: typing.Callable[[T], R],
+    failure_handler: typing.Callable[[T], R],
+) -> list[R]:
+    processed_results: list[R] = []
+    for result in results:
+        if (
+            hasattr(result, "__getitem__")  # Check if it supports dict-style access
+            and typing.cast(dict[str, typing.Any], result).get("status")
+            == HookStatus.SUCCESS
+        ):
+            processed_results.append(success_handler(result))
+        else:
+            processed_results.append(failure_handler(result))
+    return processed_results
+
+
+class EnhancedCommandRunner:
+    def __init__(self, working_dir: Path | None = None) -> None:
+        self.working_dir = working_dir
+
+    def run(self, cmd: list[str], **kwargs: Any) -> CommandResult:
+        import time
+
+        start_time = time.time()
+        try:
+            process = subprocess.run(
+                cmd,
+                check=False,
+                capture_output=True,
+                text=True,
+                cwd=self.working_dir,
+                **kwargs,
+            )
+            duration_ms = (time.time() - start_time) * 1000
+            return CommandResult(
+                success=process.returncode == 0,
+                exit_code=process.returncode,
+                stdout=process.stdout,
+                stderr=process.stderr,
+                command=cmd,
+                duration_ms=duration_ms,
+            )
+        except subprocess.SubprocessError as e:
+            duration_ms = (time.time() - start_time) * 1000
+            return CommandResult(
+                success=False,
+                exit_code=-1,
+                stdout="",
+                stderr=str(e),
+                command=cmd,
+                duration_ms=duration_ms,
+            )
+
+    def handle_result(self, result: CommandResult) -> tuple[bool, str]:
+        return process_command_output(result)
+
+
+def clean_python_code(code: str) -> str:
+    lines = code.splitlines()
+    cleaned_lines: list[str] = []
+    for line in lines:
+        match line.strip():
+            case "":
+                if not cleaned_lines or cleaned_lines[-1].strip():
+                    cleaned_lines.append("")
+            case s if s.startswith(("import ", "from ")):
+                cleaned_lines.append(line)
+            case s if s.startswith("#"):
+                continue
+            case s if "#" in s and (
+                not any(
+                    skip in s for skip in ("# noqa", "# type: ", "# pragma", "# skip")
+                )
+            ):
+                code_part = line.split("#", 1)[0].rstrip()
+                if code_part:
+                    cleaned_lines.append(code_part)
+            case s if s.startswith(('"""', "'''")):
+                continue
+            case _:
+                cleaned_lines.append(line)
+    return "\n".join(cleaned_lines)

crackerjack/security/README.md

@@ -0,0 +1,11 @@
+> Crackerjack Docs: [Main](<../../README.md>) | [Crackerjack Package](<../README.md>) | [Security](<./README.md>)
+
+# Security
+
+Security checks, validators, and related utilities.
+
+## Related
+
+- [Crackerjack Package](<../README.md>) - Parent package
+- [Agents](<../agents/README.md>) - SecurityAgent for automated security fixes
+- [Services](<../services/README.md>) - Security service implementations

crackerjack/services/README.md

@@ -0,0 +1,374 @@
+> Crackerjack Docs: [Main](<../../README.md>) | [CLAUDE.md](../../docs/guides/CLAUDE.md) | [Services](<./README.md>)
+
+# Services
+
+Service abstractions and provider integrations for infrastructure, quality, monitoring, and AI capabilities.
+
+## Overview
+
+The services package contains 60+ specialized service modules organized into functional categories. Services handle infrastructure concerns (filesystem, git, config), quality enforcement, monitoring, security, and AI integration. Most services follow ACB patterns with dependency injection and lifecycle management.
+
+## Service Categories
+
+### Core Infrastructure
+
+**Filesystem & File Operations**
+
+- `filesystem.py`: Core filesystem operations with path validation
+- `enhanced_filesystem.py`: Advanced filesystem operations with atomic writes
+- `file_modifier.py`: Safe file modification with backup and rollback
+- `file_filter.py`: File filtering and pattern matching
+- `file_hasher.py`: Content hashing for change detection
+- `backup_service.py`: Automated backup creation and management
+
+**Version Control**
+
+- `git.py`: Git operations (commit, push, status, branch management)
+- `intelligent_commit.py`: AI-powered commit message generation
+- `changelog_automation.py`: Automatic changelog generation from commits
+
+**Configuration Management**
+
+- `unified_config.py`: Unified configuration loading and validation
+- `config_merge.py`: Intelligent configuration merging for initialization
+- `config_template.py`: Configuration template management and versioning
+- `config_integrity.py`: Configuration validation and integrity checking
+
+**Initialization**
+
+- `initialization.py`: Project initialization and setup workflows
+
+### Quality & Testing
+
+**Coverage & Testing**
+
+- `coverage_ratchet.py`: Coverage ratchet system (never decrease coverage)
+- `coverage_badge_service.py`: Coverage badge generation and updates
+- `incremental_executor.py`: Incremental test execution
+- `parallel_executor.py`: Parallel test execution with pytest-xdist
+
+**Quality Enforcement**
+
+- `tool_filter.py`: Quality tool filtering and selection
+- `tool_version_service.py`: Tool version management and compatibility
+- `quality/` subdirectory — Quality-specific services
+
+### Security
+
+**Input Validation & Security**
+
+- `input_validator.py`: Comprehensive input validation framework
+- `validation_rate_limiter.py`: Rate limiting for validation failures
+- `security.py`: Core security utilities and validation
+- `security_logger.py`: Security event logging with severity levels
+- `secure_path_utils.py`: Path traversal prevention and validation
+- `secure_subprocess.py`: Safe subprocess execution without shell injection
+
+**Status & Authentication**
+
+- `status_security_manager.py`: Security manager for status operations
+- `status_authentication.py`: Authentication for status endpoints
+- `bounded_status_operations.py`: Bounded operations for status queries
+- `thread_safe_status_collector.py`: Thread-safe status data collection
+- `secure_status_formatter.py`: Secure formatting for status output
+
+**Resource Management**
+
+- `websocket_resource_limiter.py`: WebSocket connection and resource limits
+
+### Monitoring & Metrics
+
+**Health & Metrics**
+
+- `health_metrics.py`: Health metrics collection and reporting
+- `metrics.py`: General metrics tracking and aggregation
+- `profiler.py`: Performance profiling and analysis
+- `dependency_monitor.py`: Dependency health monitoring
+- `monitoring/` subdirectory — Monitoring-specific services
+
+**Debugging & Logging**
+
+- `debug.py`: Debug utilities and helpers
+- `logging.py`: Structured logging configuration
+- `log_manager.py`: Log file management and rotation
+
+### Pattern Analysis & Intelligence
+
+**Pattern Detection & Analysis**
+
+- `regex_patterns.py`: Centralized regex pattern registry (advanced-grade)
+- `regex_utils.py`: Regex utilities and validation
+- `pattern_detector.py`: Code pattern detection and analysis
+- `pattern_cache.py`: Pattern caching for performance
+- `error_pattern_analyzer.py`: Error pattern analysis and categorization
+
+**AI & Intelligence**
+
+- `anomaly_detector.py`: Anomaly detection in code and metrics
+- `predictive_analytics.py`: Predictive analytics for quality trends
+- `ai/` subdirectory — AI-specific services
+- `vector_store.py`: Vector storage for semantic search
+
+**Analysis & Optimization**
+
+- `dependency_analyzer.py`: Dependency graph analysis
+- `version_analyzer.py`: Version compatibility analysis
+- `heatmap_generator.py`: Code complexity heatmap generation
+- `memory_optimizer.py`: Memory usage optimization
+- `enterprise_optimizer.py`: Enterprise-level optimization strategies
+
+### Documentation & Code Analysis
+
+**Documentation**
+
+- `documentation_generator.py`: Automated API documentation generation
+- `documentation_service.py`: Documentation management and updates
+
+**Code Intelligence**
+
+- `api_extractor.py`: API surface extraction and analysis
+- `smart_scheduling.py`: Intelligent task scheduling
+
+### Language Server Protocol (LSP)
+
+**LSP Integration**
+
+- `lsp_client.py`: Generic LSP client implementation
+- `zuban_lsp_service.py`: Zuban LSP service integration
+- `server_manager.py`: LSP server lifecycle management
+
+### Utilities
+
+**Cache & Performance**
+
+- `cache.py`: General-purpose caching
+- `terminal_utils.py`: Terminal and console utilities
+- `version_checker.py`: Version checking and updates
+
+## Architecture
+
+### ACB Compliance Status
+
+Based on Phase 2-4 refactoring audit:
+
+| Category | Compliance | Status | Notes |
+|----------|-----------|--------|-------|
+| Core Infrastructure | 95% | ✅ Excellent | Phase 3 refactored, consistent constructors |
+| Security Services | 95% | ✅ Excellent | Comprehensive validation and logging |
+| Quality Services | 90% | ✅ Good | Coverage ratchet, testing infrastructure |
+| Monitoring Services | 85% | ✅ Good | Health metrics, profiling |
+| LSP Services | 80% | ✅ Good | Server management, client integration |
+| AI Services | 75% | ⚠️ Mixed | Some legacy patterns remain |
+
+### Dependency Injection Pattern
+
+Most services follow ACB dependency injection:
+
+```python
+from acb.depends import depends, Inject
+from crackerjack.models.protocols import Console, CrackerjackCache
+
+
+@depends.inject
+class FileSystemService:
+    def __init__(
+        self,
+        console: Inject[Console] = None,
+        cache: Inject[CrackerjackCache] = None,
+    ) -> None:
+        self.console = console
+        self.cache = cache
+
+    async def init(self) -> None:
+        # Async initialization if needed
+        pass
+```
+
+## Usage Examples
+
+### Filesystem Operations
+
+```python
+from crackerjack.services.filesystem import FileSystemService
+
+fs = FileSystemService()
+await fs.init()
+
+# Safe file operations
+content = await fs.read_file(Path("config.yaml"))
+await fs.write_file(Path("output.txt"), "data")
+```
+
+### Git Operations
+
+```python
+from crackerjack.services.git import GitService
+
+git = GitService()
+await git.init()
+
+# Commit with intelligent message
+await git.commit_changes(
+    message="Auto-generated commit message", files=["file1.py", "file2.py"]
+)
+```
+
+### Coverage Ratchet
+
+```python
+from crackerjack.services.coverage_ratchet import CoverageRatchet
+
+ratchet = CoverageRatchet()
+current = 21.6
+baseline = 19.6
+
+if ratchet.validate_coverage(current, baseline):
+    print("Coverage improved!")
+```
+
+### Security Validation
+
+```python
+from crackerjack.services.input_validator import get_input_validator
+
+validator = get_input_validator()
+result = validator.validate_command_args("safe_command arg1 arg2")
+
+if result.valid:
+    # Safe to execute
+    execute(result.sanitized_value)
+```
+
+### Pattern Detection
+
+```python
+from crackerjack.services.regex_patterns import SAFE_PATTERNS
+
+# Use centralized, validated patterns
+text = SAFE_PATTERNS["fix_hyphenated_names"].apply(text)
+```
+
+## Service Subdirectories
+
+### AI Services (`ai/`)
+
+AI-specific services for code analysis and generation:
+
+- Claude integration
+- Code generation
+- Semantic analysis
+- See [ai/README.md](<./ai/README.md>)
+
+### Monitoring Services (`monitoring/`)
+
+Health and performance monitoring:
+
+- Real-time metrics
+- Performance tracking
+- Resource monitoring
+- See [monitoring/README.md](<./monitoring/README.md>)
+
+### Quality Services (`quality/`)
+
+Quality enforcement and tracking:
+
+- Quality metrics
+- Standards enforcement
+- Compliance tracking
+- See [quality/README.md](<./quality/README.md>)
+
+### Pattern Services (`patterns/`)
+
+Pattern detection and analysis:
+
+- Code pattern recognition
+- Anti-pattern detection
+- Pattern libraries
+- See [patterns/README.md](./patterns/README.md) (if exists)
+
+## Configuration
+
+Services use ACB Settings for configuration:
+
+```python
+from acb.depends import depends
+from crackerjack.config import CrackerjackSettings
+
+settings = depends.get(CrackerjackSettings)
+```
+
+Configuration files:
+
+- `settings/crackerjack.yaml` — Base configuration
+- `settings/local.yaml` — Local overrides (gitignored)
+
+## Security Considerations
+
+### Input Validation
+
+All user input should be validated through `input_validator.py`:
+
+```python
+from crackerjack.services.input_validator import validate_and_sanitize_string
+
+try:
+    safe_input = validate_and_sanitize_string(user_input)
+    # Use safe_input
+except ExecutionError as e:
+    # Handle validation failure
+    pass
+```
+
+### Path Validation
+
+Use `secure_path_utils.py` for all path operations:
+
+```python
+from crackerjack.services.secure_path_utils import SecurePathValidator
+
+validated_path = SecurePathValidator.validate_file_path(
+    user_path, base_directory=project_root
+)
+```
+
+### Subprocess Security
+
+Use `secure_subprocess.py` instead of direct subprocess calls:
+
+```python
+from crackerjack.services.secure_subprocess import SecureSubprocess
+
+result = await SecureSubprocess.run_command(
+    ["python", "-m", "pytest"], cwd=project_root
+)
+```
+
+## Best Practices
+
+1. **Use DI**: Always use dependency injection via `@depends.inject`
+1. **Import Protocols**: Import from `models/protocols.py`, not concrete classes
+1. **Validate Input**: Use input_validator for all external input
+1. **Secure Paths**: Use SecurePathValidator for path operations
+1. **Centralize Patterns**: Use regex_patterns.py instead of raw regex
+1. **Handle Errors**: Use structured error handling with specific exceptions
+1. **Log Security Events**: Use security_logger for security-relevant operations
+1. **Cache Appropriately**: Use cache service for expensive operations
+1. **Async When Needed**: Use async/await for I/O-bound operations
+1. **Test Thoroughly**: Add tests for all new services
+
+## Related
+
+- [Adapters](<../adapters/README.md>) — Quality tool adapters that use services
+- [Managers](<../managers/README.md>) — Managers that coordinate services
+- [Orchestration](<../orchestration/README.md>) — Orchestration using services
+- [Config](<../config/README.md>) — ACB Settings integration
+- [SECURITY.md](<../../docs/reference/SECURITY.md>) — Security documentation
+
+## Future Enhancements
+
+- [ ] Standardize async/sync patterns across all services
+- [ ] Add telemetry and observability
+- [ ] Implement service health checks
+- [ ] Add circuit breaker patterns for external services
+- [ ] Create service benchmarking framework
+- [ ] Develop service plugin system

crackerjack/services/__init__.py

@@ -1,22 +1,9 @@
-from .cache import CacheEntry, CacheStats, CrackerjackCache, FileCache, InMemoryCache
-from .config import ConfigurationService
-from .file_hasher import FileHasher, SmartFileWatcher
-from .filesystem import FileSystemService
-from .git import GitService
-from .initialization import InitializationService
-from .security import SecurityService
+"""Services for crackerjack.
 
-__all__ = [
-    "CacheEntry",
-    "CacheStats",
-    "ConfigurationService",
-    "CrackerjackCache",
-    "FileCache",
-    "FileHasher",
-    "FileSystemService",
-    "GitService",
-    "InMemoryCache",
-    "InitializationService",
-    "SecurityService",
-    "SmartFileWatcher",
-]
+This package contains service classes that provide business logic
+and operations that are used across multiple components.
+"""
+
+from crackerjack.services.file_modifier import SafeFileModifier
+
+__all__ = ["SafeFileModifier"]