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

crackerjack/data/README.md

@@ -0,0 +1,11 @@
+> Crackerjack Docs: [Main](<../../README.md>) | [Crackerjack Package](<../README.md>) | [Data](<./README.md>)
+
+# Data
+
+Static data and assets used by the package (keep small; large assets belong elsewhere).
+
+## Related
+
+- [Crackerjack Package](<../README.md>) - Parent package
+- [Documentation](<../documentation/README.md>) - Documentation helpers
+- [UI Templates](<../ui/templates/README.md>) - UI template files

crackerjack/data/__init__.py

@@ -0,0 +1,8 @@
+"""Data access layer utilities backed by ACB infrastructure."""
+
+from __future__ import annotations
+
+from crackerjack.data.models import QualityBaselineRecord
+from crackerjack.data.repository import QualityBaselineRepository
+
+__all__ = ["QualityBaselineRecord", "QualityBaselineRepository"]

crackerjack/data/models.py

@@ -0,0 +1,79 @@
+"""SQLModel data models for the Crackerjack data layer."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from sqlalchemy import JSON, Column, DateTime, String
+from sqlmodel import Field, SQLModel
+
+
+class QualityBaselineRecord(SQLModel, table=True):
+    """Persistent representation of quality metrics for a git revision."""
+
+    __tablename__ = "quality_baselines"
+
+    id: int | None = Field(default=None, primary_key=True)
+    git_hash: str = Field(sa_column=Column(String(64), unique=True, index=True))
+    recorded_at: datetime = Field(
+        default_factory=datetime.utcnow,
+        sa_column=Column(DateTime(timezone=True), index=True),
+    )
+    coverage_percent: float = Field(default=0.0)
+    test_count: int = Field(default=0)
+    test_pass_rate: float = Field(default=0.0)
+    hook_failures: int = Field(default=0)
+    complexity_violations: int = Field(default=0)
+    security_issues: int = Field(default=0)
+    type_errors: int = Field(default=0)
+    linting_issues: int = Field(default=0)
+    quality_score: int = Field(default=0)
+    extra_metadata: dict[str, Any] | None = Field(
+        default=None,
+        sa_column=Column(JSON, nullable=True),
+    )
+
+    def update_from_dict(self, data: dict[str, Any]) -> None:
+        """Update this record in-place from a dictionary of values."""
+        for key, value in data.items():
+            if not hasattr(self, key):
+                continue
+            setattr(self, key, value)
+
+
+class ProjectHealthRecord(SQLModel, table=True):
+    """Persistent representation of project health metrics."""
+
+    __tablename__ = "project_health"
+
+    id: int | None = Field(default=None, primary_key=True)
+    project_root: str = Field(sa_column=Column(String(255), unique=True, index=True))
+    lint_error_trend: list[int] = Field(default_factory=list, sa_column=Column(JSON))
+    test_coverage_trend: list[float] = Field(
+        default_factory=list,
+        sa_column=Column(JSON),
+    )
+    dependency_age: dict[str, int] = Field(
+        default_factory=dict,
+        sa_column=Column(JSON),
+    )
+    config_completeness: float = Field(default=0.0)
+    last_updated: datetime = Field(
+        default_factory=datetime.utcnow,
+        sa_column=Column(DateTime(timezone=True)),
+    )
+
+
+class DependencyMonitorCacheRecord(SQLModel, table=True):
+    """Cache entry for dependency monitor state."""
+
+    __tablename__ = "dependency_monitor_cache"
+
+    id: int | None = Field(default=None, primary_key=True)
+    project_root: str = Field(sa_column=Column(String(255), unique=True, index=True))
+    cache_data: dict[str, Any] = Field(default_factory=dict, sa_column=Column(JSON))
+    updated_at: datetime = Field(
+        default_factory=datetime.utcnow,
+        sa_column=Column(DateTime(timezone=True)),
+    )

crackerjack/data/repository.py

@@ -0,0 +1,210 @@
+"""Data repositories backed by ACB SQL adapter."""
+
+from __future__ import annotations
+
+import logging
+import typing as t
+from typing import Any
+
+from crackerjack.data.models import (
+    DependencyMonitorCacheRecord,
+    ProjectHealthRecord,
+    QualityBaselineRecord,
+)
+
+LOGGER = logging.getLogger(__name__)
+
+
+from acb.depends import depends
+
+try:
+    from acb.adapters.models._hybrid import ACBQuery  # type: ignore[attr-defined]
+    from acb.adapters.models._memory import (
+        MemoryDatabaseAdapter,  # type: ignore[attr-defined]
+    )
+    from acb.adapters.models._pydantic import (
+        PydanticModelAdapter,  # type: ignore[attr-defined]
+    )
+    from acb.adapters.models._query import registry  # type: ignore[attr-defined]
+
+    # Register in-memory adapters for default usage
+    registry.register_database_adapter("memory", MemoryDatabaseAdapter())
+    registry.register_model_adapter("pydantic", PydanticModelAdapter())
+
+    # ACB hybrid query is available - use in-memory adapter as default
+    # (SQL/NoSQL adapters can be configured when those databases are set up)
+    _query_instance = ACBQuery(
+        database_adapter_name="memory",
+        model_adapter_name="pydantic",
+    )
+    depends.set(ACBQuery, _query_instance)
+
+except ImportError:  # pragma: no cover - fallback when hybrid query missing
+    LOGGER.warning(
+        "ACB hybrid query adapter not available; using in-memory query fallback.",
+    )
+
+    class _InMemorySimpleOps:
+        def __init__(self, model: type[Any], store: list[Any]) -> None:
+            self._model = model
+            self._store = store
+
+        async def create_or_update(
+            self,
+            data: dict[str, Any],
+            key_field: str,
+        ) -> Any:
+            key_value = data.get(key_field)
+            for existing in self._store:
+                if getattr(existing, key_field, None) == key_value:
+                    if hasattr(existing, "update_from_dict"):
+                        existing.update_from_dict(data)
+                    else:
+                        for key, value in data.items():
+                            if hasattr(existing, key):
+                                setattr(existing, key, value)
+                    return existing
+            instance = self._model(**data)
+            self._store.append(instance)
+            return instance
+
+        async def find(self, **filters: Any) -> Any | None:
+            for existing in self._store:
+                if all(
+                    getattr(existing, key, None) == value
+                    for key, value in filters.items()
+                ):
+                    return existing
+            return None
+
+        async def delete(self, **filters: Any) -> bool:
+            to_remove = [
+                existing
+                for existing in self._store
+                if all(
+                    getattr(existing, key, None) == value
+                    for key, value in filters.items()
+                )
+            ]
+            for item in to_remove:
+                self._store.remove(item)
+            return bool(to_remove)
+
+        async def all(self) -> list[Any]:
+            return self._store.copy()
+
+    class _InMemoryAdvancedOps:
+        def __init__(self, simple_ops: _InMemorySimpleOps) -> None:
+            self._simple = simple_ops
+            self._order_field: str | None = None
+            self._limit: int | None = None
+
+        def order_by_desc(self, field: str) -> _InMemoryAdvancedOps:
+            self._order_field = field
+            return self
+
+        def limit(self, limit: int) -> _InMemoryAdvancedOps:
+            self._limit = limit
+            return self
+
+        async def all(self) -> list[Any]:
+            records = await self._simple.all()
+            if self._order_field:
+
+                def key_fn(item: Any) -> Any:
+                    return getattr(item, self._order_field or "", None)
+
+                records.sort(key=key_fn, reverse=True)
+            if self._limit is not None:
+                records = records[: self._limit]
+            return records
+
+    class _InMemoryModelInterface:
+        def __init__(self, model: type[Any], store: list[Any]) -> None:
+            self.simple = _InMemorySimpleOps(model, store)
+            self.advanced = _InMemoryAdvancedOps(self.simple)
+
+    class ACBQuery:  # type: ignore[no-redef]
+        def __init__(self) -> None:
+            self._stores: dict[type[Any], list[Any]] = {}
+
+        def for_model(self, model: type[Any]) -> _InMemoryModelInterface:
+            if model not in self._stores:
+                self._stores[model] = []
+            return _InMemoryModelInterface(model, self._stores[model])
+
+    depends.set(ACBQuery, ACBQuery())
+
+
+class QualityBaselineRepository:
+    def __init__(self) -> None:
+        self.query = depends.get_sync(ACBQuery)
+
+    async def upsert(self, data: dict[str, Any]) -> QualityBaselineRecord:
+        result = await self.query.for_model(
+            QualityBaselineRecord
+        ).simple.create_or_update(data, "git_hash")
+        return t.cast(QualityBaselineRecord, result)
+
+    async def get_by_git_hash(self, git_hash: str) -> QualityBaselineRecord | None:
+        result = await self.query.for_model(QualityBaselineRecord).simple.find(
+            git_hash=git_hash
+        )
+        return t.cast(QualityBaselineRecord | None, result)
+
+    async def list_recent(self, limit: int = 10) -> list[QualityBaselineRecord]:
+        result = (
+            await self.query.for_model(QualityBaselineRecord)
+            .advanced.order_by_desc("recorded_at")
+            .limit(limit)
+            .all()
+        )
+        return t.cast(list[QualityBaselineRecord], result)
+
+    async def delete_for_git_hash(self, git_hash: str) -> bool:
+        result = await self.query.for_model(QualityBaselineRecord).simple.delete(
+            git_hash=git_hash
+        )
+        return t.cast(bool, result)
+
+
+class HealthMetricsRepository:
+    def __init__(self) -> None:
+        self.query = depends.get_sync(ACBQuery)
+
+    async def upsert(
+        self,
+        project_root: str,
+        data: dict[str, Any],
+    ) -> ProjectHealthRecord:
+        result = await self.query.for_model(
+            ProjectHealthRecord
+        ).simple.create_or_update(data, "project_root")
+        return t.cast(ProjectHealthRecord, result)
+
+    async def get(self, project_root: str) -> ProjectHealthRecord | None:
+        result = await self.query.for_model(ProjectHealthRecord).simple.find(
+            project_root=project_root
+        )
+        return t.cast(ProjectHealthRecord | None, result)
+
+
+class DependencyMonitorRepository:
+    def __init__(self) -> None:
+        self.query = depends.get_sync(ACBQuery)
+
+    async def upsert(
+        self,
+        project_root: str,
+        cache_data: dict[str, Any],
+    ) -> DependencyMonitorCacheRecord:
+        result = await self.query.for_model(
+            DependencyMonitorCacheRecord
+        ).simple.create_or_update(cache_data, "project_root")
+        return t.cast(DependencyMonitorCacheRecord, result)
+
+    async def get(self, project_root: str) -> DependencyMonitorCacheRecord | None:
+        result = await self.query.for_model(DependencyMonitorCacheRecord).simple.find(
+            project_root=project_root
+        )
+        return t.cast(DependencyMonitorCacheRecord | None, result)

crackerjack/decorators/README.md

@@ -0,0 +1,180 @@
+> Crackerjack Docs: [Main](<../../README.md>) | [Crackerjack Package](<../README.md>) | [Decorators](<./README.md>)
+
+# Decorators
+
+Cross-cutting decorators and helper wrappers for error handling, retry logic, validation, and performance optimization. All decorators support both sync and async functions automatically.
+
+## Available Decorators
+
+### Error Handling
+
+**`handle_errors`** - Centralized error handling with transformation and fallback support
+
+```python
+from crackerjack.decorators import handle_errors
+from crackerjack.errors import FileError
+
+
+@handle_errors(
+    error_types=[FileNotFoundError, PermissionError],
+    transform_to=FileError,
+    fallback={},
+)
+def load_config(path: str) -> dict:
+    with open(path) as f:
+        return json.load(f)
+```
+
+**`log_errors`** - Log errors with context before re-raising
+
+```python
+import logging
+from crackerjack.decorators import log_errors
+
+logger = logging.getLogger(__name__)
+
+
+@log_errors(logger=logger, level="error", include_traceback=True)
+async def critical_operation() -> bool:
+    return await perform_operation()
+```
+
+**`graceful_degradation`** - Gracefully degrade on errors with optional warnings
+
+```python
+from crackerjack.decorators import graceful_degradation
+
+
+@graceful_degradation(fallback_value=[], warn=True)
+def get_optional_features() -> list[str]:
+    # Returns [] on error with warning
+    return fetch_features()
+```
+
+### Retry and Timeout
+
+**`retry`** - Retry decorator with exponential backoff
+
+```python
+from crackerjack.decorators import retry
+
+
+@retry(max_attempts=3, exceptions=[ConnectionError], backoff=0.5)
+async def fetch_data() -> dict:
+    return await api_client.get()
+```
+
+**`with_timeout`** - Timeout enforcement for long-running operations
+
+```python
+from crackerjack.decorators import with_timeout
+
+
+@with_timeout(seconds=30, error_message="Operation timed out")
+def heavy_computation() -> int:
+    return compute_result()
+```
+
+### Validation
+
+**`validate_args`** - Validate function arguments using callables and type checks
+
+```python
+from crackerjack.decorators import validate_args
+
+
+@validate_args(
+    validators={"path": lambda p: Path(p).exists(), "count": lambda n: n > 0},
+    type_check=True,
+)
+def process_files(path: str, count: int) -> bool:
+    return True
+```
+
+### Pattern Detection
+
+**`cache_errors`** - Detect and cache error patterns for AI-powered analysis
+
+```python
+from crackerjack.decorators import cache_errors
+from pathlib import Path
+
+
+@cache_errors(error_type="lint", auto_analyze=True)
+async def run_linter(files: list[Path]) -> bool:
+    # Errors automatically cached and analyzed
+    return await linter.run(files)
+```
+
+## Best Practices
+
+### Complexity Guidelines
+
+Keep decorator implementation complexity ≤15 per function using helper methods:
+
+```python
+def _create_async_wrapper(func, config):
+    """Helper to create async wrapper - reduces complexity."""
+
+    @wraps(func)
+    async def wrapper(*args, **kwargs):
+        return await func(*args, **kwargs)
+
+    return wrapper
+```
+
+### Sync and Async Support
+
+All decorators automatically detect function type using `is_async_function`:
+
+```python
+from crackerjack.decorators.helpers import is_async_function
+
+
+def decorator(func):
+    if is_async_function(func):
+        return _create_async_wrapper(func)
+    return _create_sync_wrapper(func)
+```
+
+### Error Context
+
+Use `get_function_context` for rich error reporting:
+
+```python
+from crackerjack.decorators.helpers import get_function_context
+
+context = get_function_context(func)
+# Returns: {
+#     "function_name": "my_function",
+#     "module": "mymodule",
+#     "qualname": "MyClass.my_function",
+#     "is_async": True
+# }
+```
+
+### Combining Decorators
+
+Stack decorators from innermost to outermost:
+
+```python
+@log_errors()
+@retry(max_attempts=3)
+@with_timeout(seconds=30)
+@handle_errors(fallback={})
+async def fetch_and_process() -> dict:
+    return await process()
+```
+
+## Implementation Modules
+
+- **`error_handling.py`** - Core error decorators (retry, handle_errors, timeout, etc.)
+- **`patterns.py`** - Pattern detection decorators (cache_errors)
+- **`utils.py`** - Shared utilities for decorator implementation
+
+## Related
+
+- [Exceptions](<../exceptions/README.md>) - Custom exception types
+- [Errors](../errors/README.md) - Error handling and error types
+- [MCP Cache](<../mcp/README.md>) - Error pattern caching for AI analysis
+- [Architecture: ACB Patterns](../../docs/guides/CLAUDE.md#critical-architectural-pattern-protocol-based-di) - Dependency injection patterns

crackerjack/decorators/__init__.py

@@ -0,0 +1,35 @@
+from .error_handling import (
+    graceful_degradation,
+    handle_errors,
+    log_errors,
+    retry,
+    validate_args,
+    with_timeout,
+)
+from .error_handling_decorators import (
+    handle_all_errors,
+    handle_file_errors,
+    handle_json_errors,
+    handle_network_errors,
+    handle_subprocess_errors,
+    handle_validation_errors,
+    retry_on_error,
+)
+from .patterns import cache_errors
+
+__all__ = [
+    "retry",
+    "handle_errors",
+    "with_timeout",
+    "log_errors",
+    "graceful_degradation",
+    "validate_args",
+    "handle_file_errors",
+    "handle_json_errors",
+    "handle_subprocess_errors",
+    "handle_validation_errors",
+    "handle_network_errors",
+    "handle_all_errors",
+    "retry_on_error",
+    "cache_errors",
+]