crackerjack 0.37.8__py3-none-any.whl → 0.38.0__py3-none-any.whl

crackerjack/documentation/reference_generator.py

@@ -397,13 +397,29 @@ class ReferenceGenerator:
 
         arg_index = func_node.args.args.index(arg)
         if arg_index >= defaults_start:
-            default_index = arg_index - defaults_start
-            default_node = func_node.args.defaults[default_index]
-            if isinstance(default_node, ast.Constant):
-                return default_node.value, False
+            return self._extract_argument_default(arg_index, defaults_start, func_node)
 
         return None, True
 
+    def _extract_argument_default(
+        self, arg_index: int, defaults_start: int, func_node: ast.FunctionDef
+    ) -> tuple[t.Any, bool]:
+        """Extract default value for a specific argument.
+
+        Args:
+            arg_index: Index of the argument
+            defaults_start: Index where defaults start
+            func_node: Parent function node
+
+        Returns:
+            Tuple of (default_value, required)
+        """
+        default_index = arg_index - defaults_start
+        default_node = func_node.args.defaults[default_index]
+        if isinstance(default_node, ast.Constant):
+            return default_node.value, False
+        return None, True
+
     async def _enhance_with_examples(
         self, commands: dict[str, CommandInfo]
     ) -> dict[str, CommandInfo]:
@@ -416,35 +432,47 @@ class ReferenceGenerator:
             Enhanced commands with examples
         """
         for command in commands.values():
-            # Generate basic examples
-            basic_example = f"python -m crackerjack --{command.name}"
-
-            # Add parameter examples
-            param_examples = []
-            for param in command.parameters:
-                if not param.required and param.default_value is not None:
-                    if isinstance(param.default_value, bool):
-                        param_examples.append(f"--{param.name}")
-                    else:
-                        param_examples.append(f"--{param.name} {param.default_value}")
-
-            if param_examples:
-                enhanced_example = f"{basic_example} {' '.join(param_examples)}"
-                command.examples.append(
-                    {
-                        "description": f"Using {command.name} with parameters",
-                        "command": enhanced_example,
-                    }
-                )
+            self._add_basic_example(command)
+            self._add_parameter_examples(command)
+        return commands
 
+    def _add_basic_example(self, command: CommandInfo) -> None:
+        """Add a basic example for a command."""
+        basic_example = f"python -m crackerjack --{command.name}"
+        command.examples.append(
+            {
+                "description": f"Basic {command.name} usage",
+                "command": basic_example,
+            }
+        )
+
+    def _add_parameter_examples(self, command: CommandInfo) -> None:
+        """Add parameter examples for a command."""
+        # Generate basic examples
+        basic_example = f"python -m crackerjack --{command.name}"
+
+        # Add parameter examples
+        param_examples = []
+        for param in command.parameters:
+            if not param.required and param.default_value is not None:
+                param_example = self._format_parameter_example(param)
+                if param_example:
+                    param_examples.append(param_example)
+
+        if param_examples:
+            enhanced_example = f"{basic_example} {' '.join(param_examples)}"
             command.examples.append(
                 {
-                    "description": f"Basic {command.name} usage",
-                    "command": basic_example,
+                    "description": f"Using {command.name} with parameters",
+                    "command": enhanced_example,
                 }
             )
 
-        return commands
+    def _format_parameter_example(self, param: ParameterInfo) -> str | None:
+        """Format a parameter example."""
+        if isinstance(param.default_value, bool):
+            return f"--{param.name}"
+        return f"--{param.name} {param.default_value}"
 
     async def _enhance_with_workflows(
         self, commands: dict[str, CommandInfo]
@@ -457,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]
@@ -508,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)
 
-        category_patterns = {
+        return categories
+
+    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"],
@@ -517,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]
@@ -632,26 +695,28 @@ class ReferenceGenerator:
         ]
 
     def _render_markdown_categories(self, reference: CommandReference) -> list[str]:
-        """Render command categories for markdown.
-
-        Args:
-            reference: Command reference
-
-        Returns:
-            List of category section lines
-        """
+        """Render command categories for markdown."""
         category_lines = []
         for category, command_names in reference.categories.items():
-            category_lines.extend(
-                [
-                    f"## {category.title()}",
-                    "",
-                ]
+            category_section = self._render_markdown_category(
+                category, reference.commands, command_names
             )
+            category_lines.extend(category_section)
+        return category_lines
 
-            for command_name in command_names:
-                command = reference.commands[command_name]
-                category_lines.extend(self._render_command_markdown(command))
+    def _render_markdown_category(
+        self, category: str, commands: dict[str, CommandInfo], command_names: list[str]
+    ) -> list[str]:
+        """Render markdown for a single category."""
+        category_lines = [
+            f"## {category.title()}",
+            "",
+        ]
+
+        for command_name in command_names:
+            command = commands[command_name]
+            command_lines = self._render_command_markdown(command)
+            category_lines.extend(command_lines)
 
         return category_lines
 
@@ -685,14 +750,7 @@ class ReferenceGenerator:
         return workflow_lines
 
     def _render_command_markdown(self, command: CommandInfo) -> list[str]:
-        """Render single command as Markdown.
-
-        Args:
-            command: Command to render
-
-        Returns:
-            List of markdown lines
-        """
+        """Render single command as Markdown."""
         lines = [
             f"### `{command.name}`",
             "",
@@ -702,50 +760,49 @@ class ReferenceGenerator:
 
         # Add parameters section
         if command.parameters:
-            lines.extend(self._render_command_parameters_markdown(command.parameters))
+            param_lines = self._render_command_parameters_markdown(command.parameters)
+            lines.extend(param_lines)
 
         # Add examples section
         if command.examples:
-            lines.extend(self._render_command_examples_markdown(command.examples))
+            example_lines = self._render_command_examples_markdown(command.examples)
+            lines.extend(example_lines)
 
         # Add related commands section
         if command.related_commands:
-            lines.extend(
-                self._render_command_related_markdown(command.related_commands)
+            related_lines = self._render_command_related_markdown(
+                command.related_commands
             )
+            lines.extend(related_lines)
 
         return lines
 
     def _render_command_parameters_markdown(
         self, parameters: list[ParameterInfo]
     ) -> list[str]:
-        """Render command parameters for markdown.
-
-        Args:
-            parameters: List of parameters to render
-
-        Returns:
-            List of parameter section lines
-        """
+        """Render command parameters for markdown."""
         param_lines = [
             "**Parameters:**",
             "",
         ]
 
         for param in parameters:
-            required_str = " (required)" if param.required else ""
-            default_str = (
-                f" (default: {param.default_value})"
-                if param.default_value is not None
-                else ""
-            )
-            param_lines.append(
-                f"- `--{param.name}` ({param.type_hint}){required_str}{default_str}: {param.description}"
-            )
+            param_line = self._format_parameter_line(param)
+            param_lines.append(param_line)
 
         param_lines.append("")
         return param_lines
 
+    def _format_parameter_line(self, param: ParameterInfo) -> str:
+        """Format a single parameter line."""
+        required_str = " (required)" if param.required else ""
+        default_str = (
+            f" (default: {param.default_value})"
+            if param.default_value is not None
+            else ""
+        )
+        return f"- `--{param.name}` ({param.type_hint}){required_str}{default_str}: {param.description}"
+
     def _render_command_examples_markdown(
         self, examples: list[dict[str, str]]
     ) -> list[str]:
@@ -794,12 +851,14 @@ class ReferenceGenerator:
 
     def _render_html(self, reference: CommandReference) -> str:
         """Render reference as HTML."""
-        html = self._render_html_header(
-            reference.generated_at.strftime("%Y-%m-%d %H:%M:%S")
-        )
-        html += self._render_html_commands(reference)
-        html += "</body></html>"
-        return html
+        html_parts = [
+            self._render_html_header(
+                reference.generated_at.strftime("%Y-%m-%d %H:%M:%S")
+            ),
+            self._render_html_commands(reference),
+            "</body></html>",
+        ]
+        return "".join(html_parts)
 
     def _render_html_header(self, generated_at: str) -> str:
         """Render HTML header with styles and metadata."""
@@ -822,26 +881,40 @@ class ReferenceGenerator:
 
     def _render_html_commands(self, reference: CommandReference) -> str:
         """Render HTML commands by category."""
-        html = ""
+        html_parts = []
         for category, command_names in reference.categories.items():
-            html += f"<h2>{category.title()}</h2>"
-            html += self._render_html_category_commands(
-                reference.commands, command_names
+            category_html = self._render_html_category(
+                category, reference.commands, command_names
             )
+            html_parts.append(category_html)
+        return "".join(html_parts)
+
+    def _render_html_category(
+        self, category: str, commands: dict[str, CommandInfo], command_names: list[str]
+    ) -> str:
+        """Render HTML for a single category."""
+        html = f"<h2>{category.title()}</h2>"
+        html += self._render_html_category_commands(commands, command_names)
         return html
 
     def _render_html_category_commands(
         self, commands: dict[str, CommandInfo], command_names: list[str]
     ) -> str:
         """Render HTML for commands in a category."""
-        html = ""
+        html_parts = []
         for command_name in command_names:
             command = commands[command_name]
-            html += '<div class="command">'
-            html += f"<h3><code>{command.name}</code></h3>"
-            html += f"<p>{command.description}</p>"
-            html += self._render_html_command_parameters(command.parameters)
-            html += "</div>"
+            command_html = self._render_single_html_command(command)
+            html_parts.append(command_html)
+        return "".join(html_parts)
+
+    def _render_single_html_command(self, command: CommandInfo) -> str:
+        """Render HTML for a single command."""
+        html = '<div class="command">'
+        html += f"<h3><code>{command.name}</code></h3>"
+        html += f"<p>{command.description}</p>"
+        html += self._render_html_command_parameters(command.parameters)
+        html += "</div>"
         return html
 
     def _render_html_command_parameters(self, parameters: list[ParameterInfo]) -> str:
@@ -864,31 +937,46 @@ class ReferenceGenerator:
             "version": reference.version,
             "categories": reference.categories,
             "workflows": reference.workflows,
-            "commands": {},
+            "commands": self._serialize_commands(reference.commands),
         }
 
-        for name, command in reference.commands.items():
-            data["commands"][name] = {
-                "name": command.name,
-                "description": command.description,
-                "category": command.category,
-                "parameters": [
-                    {
-                        "name": param.name,
-                        "type": param.type_hint,
-                        "default": param.default_value,
-                        "description": param.description,
-                        "required": param.required,
-                    }
-                    for param in command.parameters
-                ],
-                "examples": command.examples,
-                "related_commands": command.related_commands,
-                "aliases": command.aliases,
-            }
-
         return json.dumps(data, indent=2, default=str)
 
+    def _serialize_commands(self, commands: dict[str, CommandInfo]) -> dict[str, t.Any]:
+        """Serialize commands for JSON output."""
+        serialized_commands = {}
+        for name, command in commands.items():
+            serialized_commands[name] = self._serialize_command(command)
+        return serialized_commands
+
+    def _serialize_command(self, command: CommandInfo) -> dict[str, t.Any]:
+        """Serialize a single command for JSON output."""
+        return {
+            "name": command.name,
+            "description": command.description,
+            "category": command.category,
+            "parameters": self._serialize_parameters(command.parameters),
+            "examples": command.examples,
+            "related_commands": command.related_commands,
+            "aliases": command.aliases,
+        }
+
+    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]
+
+    def _serialize_parameter(self, param: ParameterInfo) -> dict[str, t.Any]:
+        """Serialize a single parameter for JSON output."""
+        return {
+            "name": param.name,
+            "type": param.type_hint,
+            "default": param.default_value,
+            "description": param.description,
+            "required": param.required,
+        }
+
     def _render_yaml(self, reference: CommandReference) -> str:
         """Render reference as YAML."""
         import yaml

crackerjack/dynamic_config.py

@@ -1,5 +1,6 @@
 import tempfile
 import typing as t
+from contextlib import suppress
 from pathlib import Path
 
 import jinja2
@@ -191,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,
@@ -283,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",
@@ -337,9 +338,9 @@ HOOKS_REGISTRY: dict[str, list[HookMetadata]] = {
             "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,
@@ -357,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",
@@ -469,29 +470,26 @@ class DynamicConfigGenerator:
 
     def _detect_package_directory(self) -> str:
         """Detect the package directory name for the current project."""
-        import os
         from pathlib import Path
 
         # Check if we're in the crackerjack project itself
-        current_dir = Path(os.getcwd())
+        current_dir = Path.cwd()
         if (current_dir / "crackerjack").exists() and (
             current_dir / "pyproject.toml"
         ).exists():
             # Check if this is actually the crackerjack project
-            try:
+            with suppress(Exception):
                 import tomllib
 
                 with (current_dir / "pyproject.toml").open("rb") as f:
                     data = tomllib.load(f)
                 if data.get("project", {}).get("name") == "crackerjack":
                     return "crackerjack"
-            except Exception:
-                pass
 
         # Try to read package name from pyproject.toml
         pyproject_path = current_dir / "pyproject.toml"
         if pyproject_path.exists():
-            try:
+            with suppress(Exception):
                 import tomllib
 
                 with pyproject_path.open("rb") as f:
@@ -502,8 +500,6 @@ class DynamicConfigGenerator:
                     # Check if package directory exists
                     if (current_dir / package_name).exists():
                         return package_name
-            except Exception:
-                pass
 
         # Fallback to project directory name
         if (current_dir / current_dir.name).exists():
@@ -548,7 +544,7 @@ class DynamicConfigGenerator:
         """Update hook configuration to use the detected package directory."""
         # Update skylos hook
         if hook["id"] == "skylos" and hook["args"]:
-            hook["args"] = [self.package_directory]
+            hook["args"] = [self.package_directory, "--exclude", "tests"]
 
         # Update zuban hook
         elif hook["id"] == "zuban" and hook["args"]:
@@ -570,12 +566,24 @@ class DynamicConfigGenerator:
                 "crackerjack", self.package_directory
             )
 
-        # Ensure hooks exclude src directories to avoid JavaScript conflicts
+        # Ensure hooks exclude src directories to avoid JavaScript conflicts and tests
         if hook["exclude"]:
+            # Add src exclusion if not present
             if "src/" not in hook["exclude"]:
                 hook["exclude"] = f"{hook['exclude']}|^src/"
         else:
-            hook["exclude"] = "^src/"
+            # If no exclusion, add both tests and src
+            if hook["id"] in (
+                "skylos",
+                "zuban",
+                "bandit",
+                "refurb",
+                "complexipy",
+                "pyright",
+            ):
+                hook["exclude"] = r"^tests/|^src/"
+            else:
+                hook["exclude"] = "^src/"
 
         return hook