crackerjack 0.33.0__py3-none-any.whl → 0.33.2__py3-none-any.whl

crackerjack/models/protocols.py

@@ -51,6 +51,10 @@ class OptionsProtocol(t.Protocol):
     global_lock_timeout: int = 600
     global_lock_cleanup: bool = True
     global_lock_dir: str | None = None
+    generate_docs: bool = False
+    docs_format: str = "markdown"
+    validate_docs: bool = False
+    update_docs_index: bool = False
 
 
 @t.runtime_checkable
@@ -77,6 +81,8 @@ class GitInterface(t.Protocol):
 
     def get_changed_files(self) -> list[str]: ...
 
+    def get_staged_files(self) -> list[str]: ...
+
     def commit(self, message: str) -> bool: ...
 
     def push(self) -> bool: ...
@@ -105,49 +111,17 @@ class HookManager(t.Protocol):
 
 @t.runtime_checkable
 class SecurityAwareHookManager(HookManager, t.Protocol):
-    """Security-aware hook manager that tracks security-critical failures."""
-
-    def get_security_critical_failures(self, results: list[t.Any]) -> list[t.Any]:
-        """Extract security-critical failures from hook results.
-
-        Args:
-            results: List of hook results from run_fast_hooks or run_comprehensive_hooks
-
-        Returns:
-            List of results that are security-critical and failed
-        """
-        ...
+    def get_security_critical_failures(self, results: list[t.Any]) -> list[t.Any]: ...
 
-    def has_security_critical_failures(self, results: list[t.Any]) -> bool:
-        """Check if any security-critical hooks failed.
-
-        Args:
-            results: List of hook results
-
-        Returns:
-            True if any CRITICAL security level hooks failed
-        """
-        ...
+    def has_security_critical_failures(self, results: list[t.Any]) -> bool: ...
 
     def get_security_audit_report(
         self, fast_results: list[t.Any], comprehensive_results: list[t.Any]
-    ) -> dict[str, t.Any]:
-        """Generate security audit report for publishing decisions.
-
-        Args:
-            fast_results: Results from fast hooks
-            comprehensive_results: Results from comprehensive hooks
-
-        Returns:
-            Dict containing security status, failed critical checks, and recommendations
-        """
-        ...
+    ) -> dict[str, t.Any]: ...
 
 
 @t.runtime_checkable
 class CoverageRatchetProtocol(t.Protocol):
-    """Protocol for coverage ratchet service."""
-
     def get_baseline_coverage(self) -> float: ...
 
     def update_baseline_coverage(self, new_coverage: float) -> bool: ...
@@ -165,8 +139,6 @@ class CoverageRatchetProtocol(t.Protocol):
 
 @t.runtime_checkable
 class ConfigurationServiceProtocol(t.Protocol):
-    """Protocol for configuration service."""
-
     def update_precommit_config(self, options: OptionsProtocol) -> bool: ...
 
     def update_pyproject_config(self, options: OptionsProtocol) -> bool: ...
@@ -176,8 +148,6 @@ class ConfigurationServiceProtocol(t.Protocol):
 
 @t.runtime_checkable
 class SecurityServiceProtocol(t.Protocol):
-    """Protocol for security service."""
-
     def validate_file_safety(self, path: str | Path) -> bool: ...
 
     def check_hardcoded_secrets(self, content: str) -> list[dict[str, t.Any]]: ...
@@ -193,8 +163,6 @@ class SecurityServiceProtocol(t.Protocol):
 
 @t.runtime_checkable
 class InitializationServiceProtocol(t.Protocol):
-    """Protocol for initialization service."""
-
     def initialize_project(self, project_path: str | Path) -> bool: ...
 
     def validate_project_structure(self) -> bool: ...
@@ -204,8 +172,6 @@ class InitializationServiceProtocol(t.Protocol):
 
 @t.runtime_checkable
 class UnifiedConfigurationServiceProtocol(t.Protocol):
-    """Protocol for unified configuration service."""
-
     def merge_configurations(self) -> dict[str, t.Any]: ...
 
     def validate_configuration(self, config: dict[str, t.Any]) -> bool: ...
@@ -239,8 +205,6 @@ class PublishManager(t.Protocol):
 
 @t.runtime_checkable
 class ConfigMergeServiceProtocol(t.Protocol):
-    """Protocol for smart configuration file merging."""
-
     def smart_merge_pyproject(
         self,
         source_content: dict[str, t.Any],
@@ -285,107 +249,143 @@ class ConfigMergeServiceProtocol(t.Protocol):
 
 @t.runtime_checkable
 class HookLockManagerProtocol(t.Protocol):
-    """Protocol for managing hook-specific locks to prevent concurrent execution."""
+    def requires_lock(self, hook_name: str) -> bool: ...
 
-    def requires_lock(self, hook_name: str) -> bool:
-        """Check if a hook requires sequential execution.
+    async def acquire_hook_lock(
+        self, hook_name: str
+    ) -> t.AsyncContextManager[None]: ...
 
-        Args:
-            hook_name: Name of the hook to check
+    def get_lock_stats(self) -> dict[str, t.Any]: ...
 
-        Returns:
-            True if the hook requires a lock for sequential execution
-        """
-        ...
+    def add_hook_to_lock_list(self, hook_name: str) -> None: ...
 
-    async def acquire_hook_lock(self, hook_name: str) -> t.AsyncContextManager[None]:
-        """Acquire a lock for the specified hook if it requires one.
+    def remove_hook_from_lock_list(self, hook_name: str) -> None: ...
 
-        Args:
-            hook_name: Name of the hook to lock
+    def is_hook_currently_locked(self, hook_name: str) -> bool: ...
 
-        Returns:
-            Async context manager for lock acquisition
-        """
-        ...
+    def enable_global_lock(self, enabled: bool = True) -> None: ...
 
-    def get_lock_stats(self) -> dict[str, t.Any]:
-        """Get statistics about lock usage for monitoring.
+    def is_global_lock_enabled(self) -> bool: ...
 
-        Returns:
-            Dict containing lock statistics per hook
-        """
-        ...
+    def get_global_lock_path(self, hook_name: str) -> Path: ...
 
-    def add_hook_to_lock_list(self, hook_name: str) -> None:
-        """Add a hook to the list requiring sequential execution.
+    def cleanup_stale_locks(self, max_age_hours: float = 2.0) -> int: ...
 
-        Args:
-            hook_name: Name of the hook to add
-        """
-        ...
+    def get_global_lock_stats(self) -> dict[str, t.Any]: ...
 
-    def remove_hook_from_lock_list(self, hook_name: str) -> None:
-        """Remove a hook from the list requiring sequential execution.
 
-        Args:
-            hook_name: Name of the hook to remove
-        """
-        ...
+@t.runtime_checkable
+class DocumentationServiceProtocol(t.Protocol):
+    """Service for automated documentation generation and maintenance."""
+
+    def extract_api_documentation(
+        self, source_paths: list[Path]
+    ) -> dict[str, t.Any]: ...
+
+    def generate_documentation(
+        self, template_name: str, context: dict[str, t.Any]
+    ) -> str: ...
+
+    def validate_documentation(self, doc_paths: list[Path]) -> list[dict[str, str]]: ...
+
+    def update_documentation_index(self) -> bool: ...
 
-    def is_hook_currently_locked(self, hook_name: str) -> bool:
-        """Check if a hook is currently locked.
+    def get_documentation_coverage(self) -> dict[str, t.Any]: ...
 
-        Args:
-            hook_name: Name of the hook to check
 
-        Returns:
-            True if the hook is currently locked
-        """
-        ...
+@t.runtime_checkable
+class APIExtractorProtocol(t.Protocol):
+    """Protocol for extracting API documentation from source code."""
+
+    def extract_from_python_files(self, files: list[Path]) -> dict[str, t.Any]: ...
 
-    def enable_global_lock(self, enabled: bool = True) -> None:
-        """Enable or disable global lock functionality.
+    def extract_protocol_definitions(self, protocol_file: Path) -> dict[str, t.Any]: ...
 
-        Args:
-            enabled: Whether to enable global locking
-        """
-        ...
+    def extract_service_interfaces(
+        self, service_files: list[Path]
+    ) -> dict[str, t.Any]: ...
 
-    def is_global_lock_enabled(self) -> bool:
-        """Check if global lock functionality is enabled.
+    def extract_cli_commands(self, cli_files: list[Path]) -> dict[str, t.Any]: ...
 
-        Returns:
-            True if global locking is enabled
-        """
-        ...
+    def extract_mcp_tools(self, mcp_files: list[Path]) -> dict[str, t.Any]: ...
 
-    def get_global_lock_path(self, hook_name: str) -> Path:
-        """Get the filesystem path for a hook's global lock file.
 
-        Args:
-            hook_name: Name of the hook
+@t.runtime_checkable
+class DocumentationGeneratorProtocol(t.Protocol):
+    """Protocol for generating documentation from extracted data."""
 
-        Returns:
-            Path to the lock file for the hook
-        """
-        ...
+    def generate_api_reference(self, api_data: dict[str, t.Any]) -> str: ...
+
+    def generate_user_guide(self, template_context: dict[str, t.Any]) -> str: ...
+
+    def generate_changelog_update(
+        self, version: str, changes: dict[str, t.Any]
+    ) -> str: ...
+
+    def render_template(
+        self, template_path: Path, context: dict[str, t.Any]
+    ) -> str: ...
+
+    def generate_cross_references(
+        self, api_data: dict[str, t.Any]
+    ) -> dict[str, list[str]]: ...
+
+
+@t.runtime_checkable
+class DocumentationValidatorProtocol(t.Protocol):
+    """Protocol for validating documentation quality and consistency."""
+
+    def validate_links(self, doc_content: str) -> list[dict[str, str]]: ...
+
+    def check_documentation_freshness(
+        self, api_data: dict[str, t.Any], doc_paths: list[Path]
+    ) -> dict[str, t.Any]: ...
+
+    def validate_cross_references(
+        self, docs: dict[str, str]
+    ) -> list[dict[str, str]]: ...
+
+    def calculate_coverage_metrics(
+        self, api_data: dict[str, t.Any], existing_docs: dict[str, str]
+    ) -> dict[str, float]: ...
+
+
+@t.runtime_checkable
+class LoggerProtocol(t.Protocol):
+    """Protocol for structured logging interface."""
+
+    def info(self, message: str, **kwargs: t.Any) -> None: ...
+
+    def warning(self, message: str, **kwargs: t.Any) -> None: ...
+
+    def error(self, message: str, **kwargs: t.Any) -> None: ...
+
+    def debug(self, message: str, **kwargs: t.Any) -> None: ...
+
+
+@t.runtime_checkable
+class ConfigManagerProtocol(t.Protocol):
+    """Protocol for configuration management."""
+
+    def get(self, key: str, default: t.Any = None) -> t.Any: ...
+
+    def set(self, key: str, value: t.Any) -> None: ...
+
+    def save(self) -> bool: ...
+
+    def load(self) -> bool: ...
+
+
+@t.runtime_checkable
+class FileSystemServiceProtocol(t.Protocol):
+    """Protocol for file system operations."""
 
-    def cleanup_stale_locks(self, max_age_hours: float = 2.0) -> int:
-        """Clean up stale lock files older than max_age_hours.
+    def read_file(self, path: str | Path) -> str: ...
 
-        Args:
-            max_age_hours: Maximum age in hours before a lock is considered stale
+    def write_file(self, path: str | Path, content: str) -> None: ...
 
-        Returns:
-            Number of stale locks cleaned up
-        """
-        ...
+    def exists(self, path: str | Path) -> bool: ...
 
-    def get_global_lock_stats(self) -> dict[str, t.Any]:
-        """Get comprehensive statistics about global lock usage.
+    def mkdir(self, path: str | Path, parents: bool = False) -> None: ...
 
-        Returns:
-            Dictionary containing global lock statistics and metrics
-        """
-        ...
+    def ensure_directory(self, path: str | Path) -> None: ...