crackerjack 0.31.10__py3-none-any.whl → 0.31.13__py3-none-any.whl

crackerjack/agents/documentation_agent.py

@@ -1,9 +1,10 @@
-import re
 import subprocess
+import typing as t
 from contextlib import suppress
 from datetime import datetime
 from pathlib import Path
 
+from ..services.regex_patterns import SAFE_PATTERNS
 from .base import (
     FixResult,
     Issue,
@@ -14,8 +15,6 @@ from .base import (
 
 
 class DocumentationAgent(SubAgent):
-    """Agent specialized in maintaining documentation consistency and changelog updates."""
-
     def get_supported_types(self) -> set[IssueType]:
         return {IssueType.DOCUMENTATION}
 
@@ -28,7 +27,6 @@ class DocumentationAgent(SubAgent):
         self.log(f"Analyzing documentation issue: {issue.message}")
 
         try:
-            # Detect what type of documentation update is needed
             if "changelog" in issue.message.lower():
                 return await self._update_changelog(issue)
             if (
@@ -48,12 +46,10 @@ class DocumentationAgent(SubAgent):
             )
 
     async def _update_changelog(self, issue: Issue) -> FixResult:
-        """Update CHANGELOG.md with recent changes."""
         self.log("Updating changelog with recent changes")
 
         changelog_path = Path("CHANGELOG.md")
 
-        # Get recent commits since last version tag
         recent_changes = self._get_recent_changes()
 
         if not recent_changes:
@@ -63,10 +59,8 @@ class DocumentationAgent(SubAgent):
                 recommendations=["No recent changes to add to changelog"],
             )
 
-        # Generate changelog entry
         changelog_entry = self._generate_changelog_entry(recent_changes)
 
-        # Update or create changelog
         if changelog_path.exists():
             content = self.context.get_file_content(changelog_path)
             if content is None:
@@ -98,13 +92,10 @@ class DocumentationAgent(SubAgent):
         )
 
     async def _fix_documentation_consistency(self, issue: Issue) -> FixResult:
-        """Fix consistency issues across documentation files."""
         self.log("Checking documentation consistency")
 
-        # Find all markdown files
         md_files = list(Path().glob("*.md")) + list(Path("docs").glob("*.md"))
 
-        # Check agent count consistency
         agent_count_issues = self._check_agent_count_consistency(md_files)
 
         files_modified: list[str] = []
@@ -113,7 +104,6 @@ class DocumentationAgent(SubAgent):
         for file_path, current_count, expected_count in agent_count_issues:
             content = self.context.get_file_content(file_path)
             if content:
-                # Fix agent count references
                 updated_content = self._fix_agent_count_references(
                     content,
                     current_count,
@@ -143,10 +133,8 @@ class DocumentationAgent(SubAgent):
         )
 
     async def _update_api_documentation(self, issue: Issue) -> FixResult:
-        """Update API documentation when public interfaces change."""
         self.log("Updating API documentation")
 
-        # Check for API changes by analyzing recent modifications
         api_changes = self._detect_api_changes()
 
         if not api_changes:
@@ -158,7 +146,6 @@ class DocumentationAgent(SubAgent):
                 ],
             )
 
-        # Update README examples
         readme_path = Path("README.md")
         if readme_path.exists():
             content = self.context.get_file_content(readme_path)
@@ -188,11 +175,8 @@ class DocumentationAgent(SubAgent):
         )
 
     async def _general_documentation_update(self, issue: Issue) -> FixResult:
-        """Handle general documentation updates."""
         self.log("Performing general documentation update")
 
-        # Add review comments for manual review
-
         return FixResult(
             success=True,
             confidence=0.6,
@@ -204,7 +188,6 @@ class DocumentationAgent(SubAgent):
         )
 
     def _get_recent_changes(self) -> list[dict[str, str]]:
-        """Get recent git commits since last version tag."""
         try:
             commit_range = self._get_commit_range()
             if not commit_range:
@@ -217,7 +200,6 @@ class DocumentationAgent(SubAgent):
             return []
 
     def _get_commit_range(self) -> str:
-        """Determine the commit range for changelog generation."""
         result = subprocess.run(
             ["git", "describe", "--tags", "--abbrev=0"],
             capture_output=True,
@@ -229,11 +211,9 @@ class DocumentationAgent(SubAgent):
             last_tag = result.stdout.strip()
             return f"{last_tag}..HEAD"
 
-        # No tags found, get last 10 commits
         return "-10"
 
     def _get_commit_messages(self, commit_range: str) -> str:
-        """Get formatted commit messages for the given range."""
         result = subprocess.run(
             ["git", "log", commit_range, "--pretty=format:%s|%h|%an"],
             capture_output=True,
@@ -244,7 +224,6 @@ class DocumentationAgent(SubAgent):
         return result.stdout.strip() if result.returncode == 0 else ""
 
     def _parse_commit_messages(self, commit_output: str) -> list[dict[str, str]]:
-        """Parse git log output into structured change information."""
         changes: list[dict[str, str]] = []
 
         for line in commit_output.split("\n"):
@@ -252,16 +231,15 @@ class DocumentationAgent(SubAgent):
                 parts = line.split("|")
                 if len(parts) >= 2:
                     change_info: dict[str, str] = {
-                        "message": parts[0],
-                        "hash": parts[1],
-                        "author": parts[2] if len(parts) > 2 else "Unknown",
+                        "message": parts[0].strip(),
+                        "hash": parts[1].strip(),
+                        "author": parts[2].strip() if len(parts) > 2 else "Unknown",
                     }
                     changes.append(change_info)
 
         return changes
 
     def _generate_changelog_entry(self, changes: list[dict[str, str]]) -> str:
-        """Generate a formatted changelog entry."""
         date_str = datetime.now().strftime("%Y-%m-%d")
         entry_lines = [f"## [Unreleased] - {date_str}", ""]
 
@@ -274,7 +252,6 @@ class DocumentationAgent(SubAgent):
         self,
         changes: list[dict[str, str]],
     ) -> dict[str, list[str]]:
-        """Categorize changes by type."""
         categories: dict[str, list[str]] = {
             "features": [],
             "fixes": [],
@@ -290,7 +267,6 @@ class DocumentationAgent(SubAgent):
         return categories
 
     def _get_change_category(self, message: str) -> str:
-        """Determine the category for a change message."""
         if message.startswith(("feat:", "feature:")):
             return "features"
         if message.startswith("fix:"):
@@ -304,7 +280,6 @@ class DocumentationAgent(SubAgent):
         entry_lines: list[str],
         categories: dict[str, list[str]],
     ) -> None:
-        """Add categorized changes to the entry lines."""
         section_mappings = {
             "features": "### Added",
             "fixes": "### Fixed",
@@ -323,32 +298,27 @@ class DocumentationAgent(SubAgent):
         section_title: str,
         items: list[str],
     ) -> None:
-        """Add a section with items to the entry lines."""
         entry_lines.append(section_title)
         for item in items:
             entry_lines.append(f"- {item}")
         entry_lines.append("")
 
     def _insert_changelog_entry(self, content: str, entry: str) -> str:
-        """Insert new changelog entry at the top."""
         lines = content.split("\n")
 
-        # Find where to insert (after title and before first entry)
         insert_index = 0
         for i, line in enumerate(lines):
             if line.startswith(("# ", "## ")):
-                if i > 0:  # Skip the main title
+                if i > 0:
                     insert_index = i
                     break
 
-        # Insert the new entry
         new_lines = (
             lines[:insert_index] + entry.split("\n") + [""] + lines[insert_index:]
         )
         return "\n".join(new_lines)
 
     def _create_initial_changelog(self, entry: str) -> str:
-        """Create initial CHANGELOG.md with first entry."""
         return f"""# Changelog
 
 All notable changes to this project will be documented in this file.
@@ -363,8 +333,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
         self,
         md_files: list[Path],
     ) -> list[tuple[Path, int, int]]:
-        """Check for inconsistent agent count references across documentation."""
-        expected_count = 9  # Current total with DocumentationAgent
+        expected_count = 9
         issues: list[tuple[Path, int, int]] = []
         patterns = self._get_agent_count_patterns()
 
@@ -376,12 +345,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
         return issues
 
     def _get_agent_count_patterns(self) -> list[str]:
-        """Get regex patterns for detecting agent count references."""
         return [
-            r"(\d+)\s+agents",
-            r"(\d+)\s+specialized\s+agents",
-            r'total_agents["\']:\s*(\d+)',
-            r"(\d+)\s+sub-agents",
+            SAFE_PATTERNS["agent_count_pattern"].pattern,
+            SAFE_PATTERNS["specialized_agent_count_pattern"].pattern,
+            SAFE_PATTERNS["total_agents_config_pattern"].pattern,
+            SAFE_PATTERNS["sub_agent_count_pattern"].pattern,
         ]
 
     def _check_file_agent_count(
@@ -390,58 +358,122 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
         patterns: list[str],
         expected_count: int,
     ) -> tuple[Path, int, int] | None:
-        """Check a single file for agent count inconsistencies."""
         with suppress(Exception):
             content = self.context.get_file_content(file_path)
             if not content:
                 return None
 
-            for pattern in patterns:
-                matches = re.findall(pattern, content, re.IGNORECASE)
-                for match in matches:
-                    count = int(match)
-                    if (
-                        count != expected_count and count > 4
-                    ):  # Filter out unrelated numbers
-                        return (file_path, count, expected_count)
+            return self._analyze_file_content_for_agent_count(
+                file_path, content, patterns, expected_count
+            )
 
         return None
 
+    def _analyze_file_content_for_agent_count(
+        self,
+        file_path: Path,
+        content: str,
+        patterns: list[str],
+        expected_count: int,
+    ) -> tuple[Path, int, int] | None:
+        """Analyze file content for agent count inconsistencies."""
+        pattern_map = self._get_safe_pattern_map()
+
+        for pattern in patterns:
+            result = self._check_pattern_for_count_mismatch(
+                pattern, pattern_map, content, file_path, expected_count
+            )
+            if result:
+                return result
+
+        return None
+
+    def _get_safe_pattern_map(self) -> dict[str, str]:
+        """Get mapping of pattern strings to SAFE_PATTERNS keys."""
+        return {
+            SAFE_PATTERNS["agent_count_pattern"].pattern: "agent_count_pattern",
+            SAFE_PATTERNS[
+                "specialized_agent_count_pattern"
+            ].pattern: "specialized_agent_count_pattern",
+            SAFE_PATTERNS[
+                "total_agents_config_pattern"
+            ].pattern: "total_agents_config_pattern",
+            SAFE_PATTERNS["sub_agent_count_pattern"].pattern: "sub_agent_count_pattern",
+        }
+
+    def _check_pattern_for_count_mismatch(
+        self,
+        pattern: str,
+        pattern_map: dict[str, str],
+        content: str,
+        file_path: Path,
+        expected_count: int,
+    ) -> tuple[Path, int, int] | None:
+        """Check a specific pattern for count mismatches."""
+        if pattern not in pattern_map:
+            return None
+
+        safe_pattern = SAFE_PATTERNS[pattern_map[pattern]]
+        if not safe_pattern.test(content):
+            return None
+
+        return self._find_count_mismatch_in_matches(
+            safe_pattern, content, file_path, expected_count
+        )
+
+    def _find_count_mismatch_in_matches(
+        self,
+        safe_pattern: t.Any,
+        content: str,
+        file_path: Path,
+        expected_count: int,
+    ) -> tuple[Path, int, int] | None:
+        """Find count mismatches in pattern matches."""
+        matches = safe_pattern.findall(content)
+
+        for match in matches:
+            count = int(match)
+            if self._is_count_mismatch(count, expected_count):
+                return (file_path, count, expected_count)
+
+        return None
+
+    def _is_count_mismatch(self, count: int, expected_count: int) -> bool:
+        """Check if count represents a mismatch worth reporting."""
+        return count != expected_count and count > 4
+
     def _fix_agent_count_references(
         self,
         content: str,
         current_count: int,
         expected_count: int,
     ) -> str:
-        """Fix agent count references in documentation."""
-        # Replace various agent count patterns
-        patterns_replacements = [
-            (rf"\b{current_count}\s+agents\b", f"{expected_count} agents"),
-            (
-                rf"\b{current_count}\s+specialized\s+agents\b",
-                f"{expected_count} specialized agents",
-            ),
-            (
-                rf'total_agents["\']:\s*{current_count}',
-                f'total_agents": {expected_count}',
-            ),
-            (rf"\b{current_count}\s+sub-agents\b", f"{expected_count} sub-agents"),
-        ]
-
+        # Use SAFE_PATTERNS with dynamic replacement
         updated_content = content
-        for pattern, replacement in patterns_replacements:
-            updated_content = re.sub(
-                pattern,
-                replacement,
-                updated_content,
-                flags=re.IGNORECASE,
-            )
+
+        # Replace agent count references using safe patterns
+        agent_pattern = SAFE_PATTERNS["update_agent_count"]
+        specialized_pattern = SAFE_PATTERNS["update_specialized_agent_count"]
+        config_pattern = SAFE_PATTERNS["update_total_agents_config"]
+        sub_agent_pattern = SAFE_PATTERNS["update_sub_agent_count"]
+
+        # Apply patterns with dynamic replacement (NEW_COUNT -> expected_count)
+        updated_content = agent_pattern.apply(updated_content).replace(
+            "NEW_COUNT", str(expected_count)
+        )
+        updated_content = specialized_pattern.apply(updated_content).replace(
+            "NEW_COUNT", str(expected_count)
+        )
+        updated_content = config_pattern.apply(updated_content).replace(
+            "NEW_COUNT", str(expected_count)
+        )
+        updated_content = sub_agent_pattern.apply(updated_content).replace(
+            "NEW_COUNT", str(expected_count)
+        )
 
         return updated_content
 
     def _detect_api_changes(self) -> list[dict[str, str]]:
-        """Detect recent API changes that might affect documentation."""
-        # This is a simplified implementation - in practice would use AST analysis
         try:
             result = subprocess.run(
                 ["git", "diff", "--name-only", "HEAD~5..HEAD", "*.py"],
@@ -476,13 +508,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
         content: str,
         api_changes: list[dict[str, str]],
     ) -> str:
-        """Update README examples based on API changes."""
-        # This is a placeholder - real implementation would parse and update code examples
-        # For now, just add a comment noting API changes
         if api_changes and "TODO: Update examples" not in content:
-            # Add a note about updating examples
             lines = content.split("\n")
-            # Insert near the top after the title
+
             for i, line in enumerate(lines):
                 if line.startswith("# ") and i < len(lines) - 1:
                     lines.insert(