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

crackerjack/decorators/utils.py

@@ -0,0 +1,58 @@
+"""Shared utilities for error handling decorators."""
+
+import asyncio
+import inspect
+import typing as t
+from functools import wraps
+
+F = t.TypeVar("F", bound=t.Callable[..., t.Any])
+
+
+def is_async_function(func: t.Callable[..., t.Any]) -> bool:
+    """Check if a function is async."""
+    return asyncio.iscoroutinefunction(func)
+
+
+def preserve_signature[F: t.Callable[..., t.Any]](
+    wrapper: F,
+) -> t.Callable[[t.Callable[..., t.Any]], F]:
+    """Preserve function signature in decorators."""
+
+    def decorator(func: t.Callable[..., t.Any]) -> F:
+        wrapped = wraps(func)(wrapper)
+        # Preserve signature metadata
+        wrapped.__wrapped__ = func  # type: ignore[attr-defined]
+        return t.cast(F, wrapped)
+
+    return decorator
+
+
+def get_function_context(func: t.Callable[..., t.Any]) -> dict[str, t.Any]:
+    """Extract context information from a function for error reporting."""
+    return {
+        "function_name": func.__name__,
+        "module": func.__module__,
+        "qualname": func.__qualname__,
+        "is_async": is_async_function(func),
+    }
+
+
+def format_exception_chain(exc: BaseException) -> list[str]:
+    """Format exception chain for logging."""
+    chain: list[str] = []
+    current: BaseException | None = exc
+
+    while current is not None:
+        chain.append(f"{type(current).__name__}: {current}")
+        current = current.__cause__ or current.__context__
+
+    return chain
+
+
+def get_callable_params(func: t.Callable[..., t.Any]) -> list[inspect.Parameter]:
+    """Get function parameters using inspect."""
+    try:
+        sig = inspect.signature(func)
+        return list(sig.parameters.values())
+    except (ValueError, TypeError):
+        return []

crackerjack/docs/README.md

@@ -0,0 +1,11 @@
+> Crackerjack Docs: [Main](<../../README.md>) | [Crackerjack Package](<../README.md>) | [Docs](<./README.md>)
+
+# Package Docs
+
+Internal/generated documentation assets related to the package.
+
+## Related
+
+- [Crackerjack Package](<../README.md>) - Parent package
+- [Documentation](<../documentation/README.md>) - Documentation helpers and build utilities
+- [Data](<../data/README.md>) - Static data and assets

crackerjack/docs/generated/api/CLI_REFERENCE.md

@@ -83,7 +83,7 @@ This document describes all command-line options and usage patterns.
 - `--dev` (bool):
 - `--dashboard` (bool):
 - `--max_iterations` (int):
-- `--enterprise_batch` (str | None):
+- `--advanced_batch` (str | None):
 - `--monitor_dashboard` (str | None):
 - `--coverage_status` (bool):
 - `--coverage_goal` (float | None):

crackerjack/documentation/README.md

@@ -0,0 +1,11 @@
+> Crackerjack Docs: [Main](<../../README.md>) | [Crackerjack Package](<../README.md>) | [Documentation](<./README.md>)
+
+# Documentation Helpers
+
+Documentation helpers and build-time utilities used by the package.
+
+## Related
+
+- [Crackerjack Package](<../README.md>) - Parent package
+- [Docs](<../docs/README.md>) - Generated documentation assets
+- [Agents](<../agents/README.md>) - AI agents including DocumentationAgent

crackerjack/documentation/ai_templates.py

@@ -523,7 +523,7 @@ class AITemplateEngine:
         command_pattern = SAFE_PATTERNS[
             "extract_bash_command_blocks"
         ]._get_compiled_pattern()
-        return command_pattern.sub(enhance_command_block, content)  # type: ignore[no-any-return]
+        return command_pattern.sub(enhance_command_block, content)
 
     def _optimize_for_step_by_step(self, content: str, context: TemplateContext) -> str:
         """Optimize content for step-by-step processing.

crackerjack/documentation/dual_output_generator.py

@@ -8,7 +8,8 @@ from datetime import datetime
 from pathlib import Path
 
 import yaml
-from rich.console import Console
+from acb import console as acb_console
+from acb.console import Console
 
 from crackerjack.agents.coordinator import AgentCoordinator
 from crackerjack.services.cache import CrackerjackCache
@@ -60,7 +61,7 @@ class DualOutputGenerator:
         cache: CrackerjackCache | None = None,
     ):
         self.project_path = project_path or Path.cwd()
-        self.console = console or Console()
+        self.console = console or acb_console
         self.cache = cache or CrackerjackCache()
 
         # Documentation paths
@@ -122,7 +123,7 @@ class DualOutputGenerator:
     async def _generate_ai_reference(self) -> str:
         """Generate AI-REFERENCE.md with command decision trees and lookup tables."""
 
-        self.console.print("🤖 Generating AI reference documentation...")
+        self.console.print("🤖 Generating AI reference documentation")
 
         # Get current command structure
         from crackerjack.cli.options import CLI_OPTIONS
@@ -193,7 +194,7 @@ Generated by crackerjack documentation system v{self._get_version()}
     async def _generate_agent_capabilities(self) -> dict[str, t.Any]:
         """Generate AGENT-CAPABILITIES.json with structured agent data."""
 
-        self.console.print("🎯 Generating agent capabilities data...")
+        self.console.print("🎯 Generating agent capabilities data")
 
         # Initialize agent coordinator to get current agents
         from crackerjack.agents.base import AgentContext
@@ -247,7 +248,7 @@ Generated by crackerjack documentation system v{self._get_version()}
     async def _generate_error_patterns(self) -> dict[str, t.Any]:
         """Generate ERROR-PATTERNS.yaml with automated error resolution patterns."""
 
-        self.console.print("🔍 Generating error patterns documentation...")
+        self.console.print("🔍 Generating error patterns documentation")
 
         # Analyze existing error patterns and common fixes
         patterns = {
@@ -279,7 +280,7 @@ Generated by crackerjack documentation system v{self._get_version()}
     async def _generate_readme_enhancements(self) -> str:
         """Generate enhanced README.md sections with improved human readability."""
 
-        self.console.print("📖 Generating README enhancements...")
+        self.console.print("📖 Generating README enhancements")
 
         # Read current README if it exists
         if self.readme_path.exists():
@@ -692,7 +693,8 @@ graph TD
             return True
 
         # Check if source files are newer than generated docs
-        source_paths = list[t.Any](Path("crackerjack").rglob("*.py"))
+        # Use project_path to find source files instead of hardcoded "crackerjack"
+        source_paths = list[t.Any](self.project_path.rglob("*.py"))
         if not source_paths:
             return True
 
@@ -703,7 +705,7 @@ graph TD
             if p.exists()
         )
 
-        return latest_source > oldest_doc  # type: ignore[no-any-return]
+        return latest_source > oldest_doc
 
     async def _write_documentation_files(self, result: DocumentationResult) -> None:
         """Write generated documentation to files."""
@@ -758,7 +760,7 @@ graph TD
     def _get_version(self) -> str:
         """Get crackerjack version."""
         try:
-            from crackerjack.cli.utils import get_package_version
+            from crackerjack.cli.version import get_package_version
 
             return get_package_version()
         except Exception:

crackerjack/documentation/reference_generator.py

@@ -485,44 +485,74 @@ class ReferenceGenerator:
         Returns:
             Enhanced commands with workflow info
         """
-        # Define common workflow patterns
-        workflow_patterns = {
+        workflow_patterns = self._get_workflow_patterns()
+
+        for command in commands.values():
+            self._assign_command_workflows(command, workflow_patterns)
+            self._add_ai_context_to_command(command)
+
+        return commands
+
+    def _get_workflow_patterns(self) -> dict[str, list[str]]:
+        """Get workflow patterns for command categorization.
+
+        Returns:
+            Dictionary mapping workflow names to pattern lists
+        """
+        return {
             "development": ["test", "format", "lint", "type-check"],
             "release": ["version", "build", "publish", "tag"],
             "maintenance": ["clean", "update", "optimize", "backup"],
             "monitoring": ["status", "health", "metrics", "logs"],
         }
 
-        for command in commands.values():
-            # Assign workflows based on command name patterns
-            for workflow, patterns in workflow_patterns.items():
-                if any(pattern in command.name for pattern in patterns):
-                    command.common_workflows.append(workflow)
-
-            # Add AI context based on command purpose
-            if "test" in command.name:
-                command.ai_context.update(
-                    {
-                        "purpose": "quality_assurance",
-                        "automation_level": "high",
-                        "ai_agent_compatible": True,
-                    }
-                )
-                command.success_patterns.append("All tests passed")
-                command.failure_patterns.append("Test failures detected")
-
-            elif "format" in command.name or "lint" in command.name:
-                command.ai_context.update(
-                    {
-                        "purpose": "code_quality",
-                        "automation_level": "high",
-                        "ai_agent_compatible": True,
-                    }
-                )
-                command.success_patterns.append("No formatting issues")
-                command.failure_patterns.append("Style violations found")
+    def _assign_command_workflows(
+        self, command: CommandInfo, workflow_patterns: dict[str, list[str]]
+    ) -> None:
+        """Assign workflows to a command based on name patterns.
 
-        return commands
+        Args:
+            command: Command to assign workflows to
+            workflow_patterns: Workflow patterns to match against
+        """
+        for workflow, patterns in workflow_patterns.items():
+            if any(pattern in command.name for pattern in patterns):
+                command.common_workflows.append(workflow)
+
+    def _add_ai_context_to_command(self, command: CommandInfo) -> None:
+        """Add AI context to a command based on its purpose.
+
+        Args:
+            command: Command to enhance with AI context
+        """
+        if "test" in command.name:
+            self._add_test_ai_context(command)
+        elif "format" in command.name or "lint" in command.name:
+            self._add_quality_ai_context(command)
+
+    def _add_test_ai_context(self, command: CommandInfo) -> None:
+        """Add AI context for test-related commands."""
+        command.ai_context.update(
+            {
+                "purpose": "quality_assurance",
+                "automation_level": "high",
+                "ai_agent_compatible": True,
+            }
+        )
+        command.success_patterns.append("All tests passed")
+        command.failure_patterns.append("Test failures detected")
+
+    def _add_quality_ai_context(self, command: CommandInfo) -> None:
+        """Add AI context for code quality commands."""
+        command.ai_context.update(
+            {
+                "purpose": "code_quality",
+                "automation_level": "high",
+                "ai_agent_compatible": True,
+            }
+        )
+        command.success_patterns.append("No formatting issues")
+        command.failure_patterns.append("Style violations found")
 
     def _categorize_commands(
         self, commands: dict[str, CommandInfo]
@@ -536,8 +566,18 @@ class ReferenceGenerator:
             Dictionary of category to command names
         """
         categories: dict[str, list[str]] = {}
+        category_patterns = self._get_category_patterns()
+
+        for command in commands.values():
+            category = self._determine_command_category(command, category_patterns)
+            command.category = category
+            self._add_command_to_category(categories, category, command.name)
+
+        return categories
 
-        category_patterns = {
+    def _get_category_patterns(self) -> dict[str, list[str]]:
+        """Get category patterns for command classification."""
+        return {
             "development": ["test", "format", "lint", "check", "run"],
             "server": ["server", "start", "stop", "restart", "monitor"],
             "release": ["version", "bump", "publish", "build", "tag"],
@@ -545,27 +585,22 @@ class ReferenceGenerator:
             "utilities": ["clean", "help", "info", "status"],
         }
 
-        for command in commands.values():
-            assigned = False
-
-            # Assign based on patterns
-            for category, patterns in category_patterns.items():
-                if any(pattern in command.name for pattern in patterns):
-                    command.category = category
-                    if category not in categories:
-                        categories[category] = []
-                    categories[category].append(command.name)
-                    assigned = True
-                    break
-
-            # Default category
-            if not assigned:
-                command.category = "general"
-                if "general" not in categories:
-                    categories["general"] = []
-                categories["general"].append(command.name)
-
-        return categories
+    def _determine_command_category(
+        self, command: CommandInfo, category_patterns: dict[str, list[str]]
+    ) -> str:
+        """Determine the category for a command based on patterns."""
+        for category, patterns in category_patterns.items():
+            if any(pattern in command.name for pattern in patterns):
+                return category
+        return "general"
+
+    def _add_command_to_category(
+        self, categories: dict[str, list[str]], category: str, command_name: str
+    ) -> None:
+        """Add command to the specified category."""
+        if category not in categories:
+            categories[category] = []
+        categories[category].append(command_name)
 
     def _generate_workflows(
         self, commands: dict[str, CommandInfo]
@@ -663,7 +698,9 @@ class ReferenceGenerator:
         """Render command categories for markdown."""
         category_lines = []
         for category, command_names in reference.categories.items():
-            category_section = self._render_markdown_category(category, reference.commands, command_names)
+            category_section = self._render_markdown_category(
+                category, reference.commands, command_names
+            )
             category_lines.extend(category_section)
         return category_lines
 
@@ -733,7 +770,9 @@ class ReferenceGenerator:
 
         # Add related commands section
         if command.related_commands:
-            related_lines = self._render_command_related_markdown(command.related_commands)
+            related_lines = self._render_command_related_markdown(
+                command.related_commands
+            )
             lines.extend(related_lines)
 
         return lines
@@ -813,9 +852,11 @@ class ReferenceGenerator:
     def _render_html(self, reference: CommandReference) -> str:
         """Render reference as HTML."""
         html_parts = [
-            self._render_html_header(reference.generated_at.strftime("%Y-%m-%d %H:%M:%S")),
+            self._render_html_header(
+                reference.generated_at.strftime("%Y-%m-%d %H:%M:%S")
+            ),
             self._render_html_commands(reference),
-            "</body></html>"
+            "</body></html>",
         ]
         return "".join(html_parts)
 
@@ -842,7 +883,9 @@ class ReferenceGenerator:
         """Render HTML commands by category."""
         html_parts = []
         for category, command_names in reference.categories.items():
-            category_html = self._render_html_category(category, reference.commands, command_names)
+            category_html = self._render_html_category(
+                category, reference.commands, command_names
+            )
             html_parts.append(category_html)
         return "".join(html_parts)
 
@@ -918,7 +961,9 @@ class ReferenceGenerator:
             "aliases": command.aliases,
         }
 
-    def _serialize_parameters(self, parameters: list[ParameterInfo]) -> list[dict[str, t.Any]]:
+    def _serialize_parameters(
+        self, parameters: list[ParameterInfo]
+    ) -> list[dict[str, t.Any]]:
         """Serialize parameters for JSON output."""
         return [self._serialize_parameter(param) for param in parameters]
 

crackerjack/dynamic_config.py

@@ -148,7 +148,7 @@ HOOKS_REGISTRY: dict[str, list[HookMetadata]] = {
             "id": "uv-lock",
             "name": None,
             "repo": "https://github.com/astral-sh/uv-pre-commit",
-            "rev": "0.8.15",
+            "rev": "0.9.0",
             "tier": 1,
             "time_estimate": 0.5,
             "stages": None,
@@ -174,7 +174,7 @@ HOOKS_REGISTRY: dict[str, list[HookMetadata]] = {
             "stages": None,
             "args": None,
             "files": None,
-            "exclude": r"uv\.lock|pyproject\.toml|tests/.*|docs/.*|.*\.md",
+            "exclude": r"uv\.lock|pyproject\.toml|tests/.*|docs/.*|\.claude/.*|.*\.md",
             "additional_dependencies": None,
             "types_or": None,
             "language": None,
@@ -192,7 +192,7 @@ HOOKS_REGISTRY: dict[str, list[HookMetadata]] = {
             "stages": ["pre-push", "manual"],
             "args": ["-c", "pyproject.toml", "-r", "-ll"],
             "files": "^crackerjack/.*\\.py$",
-            "exclude": None,
+            "exclude": r"^tests/",
             "additional_dependencies": None,
             "types_or": None,
             "language": None,
@@ -224,7 +224,7 @@ HOOKS_REGISTRY: dict[str, list[HookMetadata]] = {
             "id": "ruff-check",
             "name": None,
             "repo": "https://github.com/astral-sh/ruff-pre-commit",
-            "rev": "v0.12.12",
+            "rev": "v0.14.0",
             "tier": 2,
             "time_estimate": 1.5,
             "stages": None,
@@ -242,7 +242,7 @@ HOOKS_REGISTRY: dict[str, list[HookMetadata]] = {
             "id": "ruff-format",
             "name": None,
             "repo": "https://github.com/astral-sh/ruff-pre-commit",
-            "rev": "v0.12.12",
+            "rev": "v0.14.0",
             "tier": 2,
             "time_estimate": 1.0,
             "stages": None,
@@ -284,9 +284,9 @@ HOOKS_REGISTRY: dict[str, list[HookMetadata]] = {
             "tier": 3,
             "time_estimate": 0.1,
             "stages": ["pre-push", "manual"],
-            "args": ["crackerjack"],
+            "args": ["crackerjack", "--exclude", "tests"],
             "files": None,
-            "exclude": None,
+            "exclude": r"^tests/",
             "additional_dependencies": None,
             "types_or": None,
             "language": "system",
@@ -334,13 +334,13 @@ HOOKS_REGISTRY: dict[str, list[HookMetadata]] = {
             "id": "refurb",
             "name": None,
             "repo": "https://github.com/dosisod/refurb",
-            "rev": "v2.1.0",
+            "rev": "v2.2.0",
             "tier": 3,
             "time_estimate": 3.0,
             "stages": ["pre-push", "manual"],
-            "args": ["--ignore", "FURB184", "--ignore", "FURB120"],
+            "args": [],
             "files": "^crackerjack/.*\\.py$",
-            "exclude": r"^tests/.*\.py$",
+            "exclude": r"^tests/",
             "additional_dependencies": None,
             "types_or": None,
             "language": None,
@@ -358,7 +358,7 @@ HOOKS_REGISTRY: dict[str, list[HookMetadata]] = {
             "stages": ["pre-push", "manual"],
             "args": ["--config-file", "mypy.ini", "./crackerjack"],
             "files": None,
-            "exclude": None,
+            "exclude": r"^tests/",
             "additional_dependencies": None,
             "types_or": None,
             "language": "system",
@@ -366,24 +366,6 @@ HOOKS_REGISTRY: dict[str, list[HookMetadata]] = {
             "experimental": False,
             "pass_filenames": False,
         },
-        {
-            "id": "pyright",
-            "name": "pyright-type-checking",
-            "repo": "local",
-            "rev": "",
-            "tier": 3,
-            "time_estimate": 0.25,
-            "stages": ["pre-push", "manual"],
-            "args": [],
-            "files": "^crackerjack/.*\\.py$",
-            "exclude": r"^crackerjack/(mcp|plugins)/.*\.py$|crackerjack/code_cleaner\.py$",
-            "additional_dependencies": None,
-            "types_or": None,
-            "language": "system",
-            "entry": "uv run pyright",
-            "experimental": False,
-            "pass_filenames": None,
-        },
     ],
     "experimental": [],
 }
@@ -465,19 +447,15 @@ class DynamicConfigGenerator:
         )
 
     def _sanitize_package_directory(self, package_directory: str) -> str:
-        """Convert hyphens to underscores in package directory names."""
         return package_directory.replace("-", "_")
 
     def _detect_package_directory(self) -> str:
-        """Detect the package directory name for the current project."""
         from pathlib import Path
 
-        # Check if we're in the crackerjack project itself
         current_dir = Path.cwd()
         if (current_dir / "crackerjack").exists() and (
             current_dir / "pyproject.toml"
         ).exists():
-            # Check if this is actually the crackerjack project
             with suppress(Exception):
                 import tomllib
 
@@ -486,7 +464,6 @@ class DynamicConfigGenerator:
                 if data.get("project", {}).get("name") == "crackerjack":
                     return "crackerjack"
 
-        # Try to read package name from pyproject.toml
         pyproject_path = current_dir / "pyproject.toml"
         if pyproject_path.exists():
             with suppress(Exception):
@@ -497,15 +474,13 @@ class DynamicConfigGenerator:
 
                 if "project" in data and "name" in data["project"]:
                     package_name = str(data["project"]["name"])
-                    # Check if package directory exists
+
                     if (current_dir / package_name).exists():
                         return package_name
 
-        # Fallback to project directory name
         if (current_dir / current_dir.name).exists():
             return current_dir.name
 
-        # Default fallback to current directory name
         return current_dir.name
 
     def _should_include_hook(
@@ -534,45 +509,55 @@ class DynamicConfigGenerator:
         for category_hooks in HOOKS_REGISTRY.values():
             for hook in category_hooks:
                 if self._should_include_hook(hook, config, enabled_experimental):
-                    # Create a copy and update package-specific configurations
                     updated_hook = self._update_hook_for_package(hook.copy())
                     filtered_hooks.append(updated_hook)
 
         return filtered_hooks
 
     def _update_hook_for_package(self, hook: HookMetadata) -> HookMetadata:
-        """Update hook configuration to use the detected package directory."""
-        # Update skylos hook
-        if hook["id"] == "skylos" and hook["args"]:
-            hook["args"] = [self.package_directory]
+        """Update hook configuration for custom package directory."""
+        hook = self._update_hook_args(hook)
+        hook = self._update_hook_paths(hook)
+        hook = self._update_hook_excludes(hook)
+        return hook
 
-        # Update zuban hook
+    def _update_hook_args(self, hook: HookMetadata) -> HookMetadata:
+        """Update hook arguments for specific tools."""
+        if hook["id"] == "skylos" and hook["args"]:
+            hook["args"] = [self.package_directory, "--exclude", "tests"]
         elif hook["id"] == "zuban" and hook["args"]:
-            # Replace the hardcoded "./crackerjack" with the dynamic package directory
-            updated_args = []
-            for arg in hook["args"]:
-                if arg == "./crackerjack":
-                    updated_args.append(f"./{self.package_directory}")
-                else:
-                    updated_args.append(arg)
-            hook["args"] = updated_args
-
-        # Update other hooks that use hardcoded "crackerjack" patterns
-        elif hook["files"] and "crackerjack" in hook["files"]:
-            hook["files"] = hook["files"].replace("crackerjack", self.package_directory)
+            hook["args"] = [
+                f"./{self.package_directory}" if arg == "./crackerjack" else arg
+                for arg in hook["args"]
+            ]
+        return hook
 
-        elif hook["exclude"] and "crackerjack" in hook["exclude"]:
+    def _update_hook_paths(self, hook: HookMetadata) -> HookMetadata:
+        """Update file and exclude paths for package directory."""
+        if hook["files"] and "crackerjack" in hook["files"]:
+            hook["files"] = hook["files"].replace("crackerjack", self.package_directory)
+        if hook["exclude"] and "crackerjack" in hook["exclude"]:
             hook["exclude"] = hook["exclude"].replace(
                 "crackerjack", self.package_directory
             )
+        return hook
 
-        # Ensure hooks exclude src directories to avoid JavaScript conflicts
+    def _update_hook_excludes(self, hook: HookMetadata) -> HookMetadata:
+        """Update exclude patterns to skip src/ directory."""
         if hook["exclude"]:
             if "src/" not in hook["exclude"]:
                 hook["exclude"] = f"{hook['exclude']}|^src/"
         else:
-            hook["exclude"] = "^src/"
-
+            exclude_tests_and_src = {
+                "skylos",
+                "zuban",
+                "bandit",
+                "refurb",
+                "complexipy",
+            }
+            hook["exclude"] = (
+                r"^tests/|^src/" if hook["id"] in exclude_tests_and_src else "^src/"
+            )
         return hook
 
     def group_hooks_by_repo(
@@ -640,7 +625,13 @@ class DynamicConfigGenerator:
             }
             repos.append(repo_data)
 
-        return self.template.render(repos=repos)
+        content = self.template.render(repos=repos)
+        # Preserve a space after 'repos:' to satisfy downstream consumers/tests
+        if content.startswith("repos:\n"):
+            content = content.replace("repos:\n", "repos: \n", 1)
+        # Ensure 'hooks:' lines include a trailing space for readability
+        content = content.replace("\n    hooks:\n", "\n    hooks: \n")
+        return content
 
     def create_temp_config(
         self,
@@ -651,7 +642,7 @@ class DynamicConfigGenerator:
         temp_file = tempfile.NamedTemporaryFile(
             mode="w",
             suffix=".yaml",
-            prefix=f"crackerjack-{mode}-",
+            prefix=f"crackerjack - {mode} -",
             delete=False,
             encoding="utf-8",
         )