claude-mpm 4.21.0__py3-none-any.whl → 5.0.2__py3-none-any.whl

claude_mpm/tools/code_tree_analyzer/python_analyzer.py

@@ -0,0 +1,284 @@
+#!/usr/bin/env python3
+"""
+Python Analyzer
+===============
+
+Analyzes Python source code using AST.
+
+WHY: Python's built-in AST module provides rich structural information
+that we can leverage for detailed analysis.
+"""
+
+import ast
+from pathlib import Path
+from typing import List, Optional
+
+from ...core.logging_config import get_logger
+from ..code_tree_events import CodeNodeEvent, CodeTreeEventEmitter
+from .models import CodeNode
+
+
+class PythonAnalyzer:
+    """Analyzes Python source code using AST."""
+
+    def __init__(self, emitter: Optional[CodeTreeEventEmitter] = None):
+        self.logger = get_logger(__name__)
+        self.emitter = emitter
+
+    def analyze_file(self, file_path: Path) -> List[CodeNode]:
+        """Analyze a Python file and extract code structure.
+
+        Args:
+            file_path: Path to Python file
+
+        Returns:
+            List of code nodes found in the file
+        """
+        nodes = []
+
+        try:
+            with Path(file_path).open(
+                encoding="utf-8",
+            ) as f:
+                source = f.read()
+
+            tree = ast.parse(source, filename=str(file_path))
+            nodes = self._extract_nodes(tree, file_path, source)
+
+        except SyntaxError as e:
+            self.logger.warning(f"Syntax error in {file_path}: {e}")
+            if self.emitter:
+                self.emitter.emit_error(str(file_path), f"Syntax error: {e}")
+        except Exception as e:
+            self.logger.error(f"Error analyzing {file_path}: {e}")
+            if self.emitter:
+                self.emitter.emit_error(str(file_path), str(e))
+
+        return nodes
+
+    def _extract_nodes(
+        self, tree: ast.AST, file_path: Path, source: str
+    ) -> List[CodeNode]:
+        """Extract code nodes from AST tree.
+
+        Args:
+            tree: AST tree
+            file_path: Source file path
+            source: Source code text
+
+        Returns:
+            List of extracted code nodes
+        """
+        nodes = []
+        source.splitlines()
+
+        class NodeVisitor(ast.NodeVisitor):
+            def __init__(self, parent_name: Optional[str] = None):
+                self.parent_name = parent_name
+                self.current_class = None
+
+            def visit_ClassDef(self, node):
+                # Extract class information
+                class_node = CodeNode(
+                    file_path=str(file_path),
+                    node_type="class",
+                    name=node.name,
+                    line_start=node.lineno,
+                    line_end=node.end_lineno or node.lineno,
+                    has_docstring=bool(ast.get_docstring(node)),
+                    decorators=[self._decorator_name(d) for d in node.decorator_list],
+                    parent=self.parent_name,
+                    complexity=self._calculate_complexity(node),
+                    signature=self._get_class_signature(node),
+                )
+
+                nodes.append(class_node)
+
+                # Emit event if emitter is available
+                if self.emitter:
+                    self.emitter.emit_node(
+                        CodeNodeEvent(
+                            file_path=str(file_path),
+                            node_type="class",
+                            name=node.name,
+                            line_start=node.lineno,
+                            line_end=node.end_lineno or node.lineno,
+                            complexity=class_node.complexity,
+                            has_docstring=class_node.has_docstring,
+                            decorators=class_node.decorators,
+                            parent=self.parent_name,
+                            children_count=len(node.body),
+                        )
+                    )
+
+                # Visit class members
+                old_class = self.current_class
+                self.current_class = node.name
+                for child in node.body:
+                    if isinstance(child, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                        self.visit_FunctionDef(child, is_method=True)
+                self.current_class = old_class
+
+            def visit_FunctionDef(self, node, is_method=False):
+                # Determine node type
+                node_type = "method" if is_method else "function"
+                parent = self.current_class if is_method else self.parent_name
+
+                # Extract function information
+                func_node = CodeNode(
+                    file_path=str(file_path),
+                    node_type=node_type,
+                    name=node.name,
+                    line_start=node.lineno,
+                    line_end=node.end_lineno or node.lineno,
+                    has_docstring=bool(ast.get_docstring(node)),
+                    decorators=[self._decorator_name(d) for d in node.decorator_list],
+                    parent=parent,
+                    complexity=self._calculate_complexity(node),
+                    signature=self._get_function_signature(node),
+                )
+
+                nodes.append(func_node)
+
+                # Emit event if emitter is available
+                if self.emitter:
+                    self.emitter.emit_node(
+                        CodeNodeEvent(
+                            file_path=str(file_path),
+                            node_type=node_type,
+                            name=node.name,
+                            line_start=node.lineno,
+                            line_end=node.end_lineno or node.lineno,
+                            complexity=func_node.complexity,
+                            has_docstring=func_node.has_docstring,
+                            decorators=func_node.decorators,
+                            parent=parent,
+                            children_count=0,
+                        )
+                    )
+
+            def visit_Assign(self, node):
+                # Handle module-level variable assignments
+                if self.current_class is None:  # Only module-level assignments
+                    for target in node.targets:
+                        if isinstance(target, ast.Name):
+                            var_node = CodeNode(
+                                file_path=str(file_path),
+                                node_type="variable",
+                                name=target.id,
+                                line_start=node.lineno,
+                                line_end=node.end_lineno or node.lineno,
+                                parent=self.parent_name,
+                                complexity=0,
+                                signature=f"{target.id} = ...",
+                            )
+                            nodes.append(var_node)
+
+                            # Emit event if emitter is available
+                            if self.emitter:
+                                self.emitter.emit_node(
+                                    CodeNodeEvent(
+                                        file_path=str(file_path),
+                                        node_type="variable",
+                                        name=target.id,
+                                        line_start=node.lineno,
+                                        line_end=node.end_lineno or node.lineno,
+                                        parent=self.parent_name,
+                                    )
+                                )
+
+            def visit_AsyncFunctionDef(self, node):
+                self.visit_FunctionDef(node)
+
+            def _decorator_name(self, decorator):
+                """Extract decorator name from AST node."""
+                if isinstance(decorator, ast.Name):
+                    return decorator.id
+                if isinstance(decorator, ast.Call):
+                    if isinstance(decorator.func, ast.Name):
+                        return decorator.func.id
+                    if isinstance(decorator.func, ast.Attribute):
+                        return decorator.func.attr
+                return "unknown"
+
+            def _calculate_complexity(self, node):
+                """Calculate cyclomatic complexity of a node."""
+                complexity = 1  # Base complexity
+
+                for child in ast.walk(node):
+                    if isinstance(
+                        child, (ast.If, ast.While, ast.For, ast.ExceptHandler)
+                    ):
+                        complexity += 1
+                    elif isinstance(child, ast.BoolOp):
+                        complexity += len(child.values) - 1
+
+                return complexity
+
+            def _get_function_signature(self, node):
+                """Extract function signature."""
+                args = []
+                for arg in node.args.args:
+                    args.append(arg.arg)
+                return f"{node.name}({', '.join(args)})"
+
+            def _get_class_signature(self, node):
+                """Extract class signature."""
+                bases = []
+                for base in node.bases:
+                    if isinstance(base, ast.Name):
+                        bases.append(base.id)
+                base_str = f"({', '.join(bases)})" if bases else ""
+                return f"class {node.name}{base_str}"
+
+        # Extract imports
+        for node in ast.walk(tree):
+            if isinstance(node, ast.Import):
+                for alias in node.names:
+                    import_node = CodeNode(
+                        file_path=str(file_path),
+                        node_type="import",
+                        name=alias.name,
+                        line_start=node.lineno,
+                        line_end=node.end_lineno or node.lineno,
+                        signature=f"import {alias.name}",
+                    )
+                    nodes.append(import_node)
+
+            elif isinstance(node, ast.ImportFrom):
+                module = node.module or ""
+                for alias in node.names:
+                    import_node = CodeNode(
+                        file_path=str(file_path),
+                        node_type="import",
+                        name=f"{module}.{alias.name}",
+                        line_start=node.lineno,
+                        line_end=node.end_lineno or node.lineno,
+                        signature=f"from {module} import {alias.name}",
+                    )
+                    nodes.append(import_node)
+
+        # Visit all nodes
+        visitor = NodeVisitor()
+        visitor.emitter = self.emitter
+        visitor.visit(tree)
+
+        return nodes
+
+    def _get_assignment_signature(self, node: ast.Assign, var_name: str) -> str:
+        """Get assignment signature string."""
+        try:
+            # Try to get a simple representation of the value
+            if isinstance(node.value, ast.Constant):
+                if isinstance(node.value.value, str):
+                    return f'{var_name} = "{node.value.value}"'
+                return f"{var_name} = {node.value.value}"
+            if isinstance(node.value, ast.Name):
+                return f"{var_name} = {node.value.id}"
+            if isinstance(node.value, ast.List):
+                return f"{var_name} = [...]"
+            if isinstance(node.value, ast.Dict):
+                return f"{var_name} = {{...}}"
+            return f"{var_name} = ..."
+        except Exception:
+            return f"{var_name} = ..."

claude_mpm/utils/agent_dependency_loader.py

@@ -16,6 +16,7 @@ import sys
 import time
 from typing import Any, Dict, List, Optional, Set, Tuple
 
+import yaml
 from packaging.requirements import InvalidRequirement, Requirement
 
 from ..core.logger import get_logger
@@ -89,10 +90,48 @@ class AgentDependencyLoader:
         self.deployed_agents = deployed_agents
         return deployed_agents
 
+    def _extract_yaml_frontmatter(self, content: str) -> Optional[Dict[str, Any]]:
+        """
+        Extract and parse YAML frontmatter from markdown.
+
+        Frontmatter must be at the start of the file, delimited by '---'.
+        Example:
+            ---
+            name: agent_name
+            dependencies:
+              python:
+                - package>=1.0.0
+            ---
+            # Agent content...
+
+        Args:
+            content: File content to parse
+
+        Returns:
+            Parsed YAML frontmatter as dict, or None if not found/invalid
+        """
+        if not content.strip().startswith("---"):
+            return None
+
+        # Split on --- delimiters
+        parts = content.split("---", 2)
+        if len(parts) < 3:
+            return None
+
+        try:
+            return yaml.safe_load(parts[1])
+        except yaml.YAMLError as e:
+            logger.warning(f"Failed to parse YAML frontmatter: {e}")
+            return None
+
     def load_agent_dependencies(self) -> Dict[str, Dict]:
         """
         Load dependency information for deployed agents from their source configs.
 
+        Searches for agent configuration in both markdown (.md) and JSON (.json) formats.
+        Markdown files with YAML frontmatter are searched first for better maintainability.
+        Falls back to JSON format for backward compatibility.
+
         Returns:
             Dictionary mapping agent IDs to their dependency requirements
         """
@@ -106,19 +145,47 @@ class AgentDependencyLoader:
         ]
 
         for agent_id in self.deployed_agents:
-            # Try to find the agent's JSON config
+            found = False
+
+            # Try to find the agent's config (markdown first, then JSON)
             for config_dir in config_paths:
-                config_file = config_dir / f"{agent_id}.json"
-                if config_file.exists():
+                if found:
+                    break
+
+                # Try markdown first (current format with YAML frontmatter)
+                md_file = config_dir / f"{agent_id}.md"
+                if md_file.exists():
                     try:
-                        with config_file.open() as f:
-                            config = json.load(f)
-                            if "dependencies" in config:
-                                agent_dependencies[agent_id] = config["dependencies"]
-                                logger.debug(f"Loaded dependencies for {agent_id}")
-                                break
+                        content = md_file.read_text(encoding="utf-8")
+                        frontmatter = self._extract_yaml_frontmatter(content)
+                        if frontmatter and "dependencies" in frontmatter:
+                            agent_dependencies[agent_id] = frontmatter["dependencies"]
+                            logger.debug(
+                                f"Loaded dependencies for {agent_id} from markdown"
+                            )
+                            found = True
+                            break
                     except Exception as e:
-                        logger.warning(f"Failed to load config for {agent_id}: {e}")
+                        logger.warning(f"Failed to load markdown for {agent_id}: {e}")
+
+                # Fall back to JSON for backward compatibility
+                if not found:
+                    json_file = config_dir / f"{agent_id}.json"
+                    if json_file.exists():
+                        try:
+                            with json_file.open() as f:
+                                config = json.load(f)
+                                if "dependencies" in config:
+                                    agent_dependencies[agent_id] = config[
+                                        "dependencies"
+                                    ]
+                                    logger.debug(
+                                        f"Loaded dependencies for {agent_id} from JSON"
+                                    )
+                                    found = True
+                                    break
+                        except Exception as e:
+                            logger.warning(f"Failed to load JSON for {agent_id}: {e}")
 
         self.agent_dependencies = agent_dependencies
         logger.debug(f"Loaded dependencies for {len(agent_dependencies)} agents")
@@ -678,7 +745,7 @@ class AgentDependencyLoader:
             logger.info(
                 f"Auto-installing {len(results['summary']['missing_python'])} missing dependencies..."
             )
-            success, error = self.install_missing_dependencies(
+            success, _error = self.install_missing_dependencies(
                 results["summary"]["missing_python"]
             )
             if success:
@@ -777,7 +844,7 @@ class AgentDependencyLoader:
             import sys
 
             if sys.version_info >= (3, 13):
-                compatible, incompatible = self.check_python_compatibility(
+                _compatible, incompatible = self.check_python_compatibility(
                     summary["missing_python"]
                 )
                 if incompatible:
@@ -949,7 +1016,7 @@ class AgentDependencyLoader:
         Returns:
             Cached results or None if not available/valid.
         """
-        has_changed, current_hash = self.has_agents_changed()
+        has_changed, _current_hash = self.has_agents_changed()
 
         if not has_changed:
             state = self.load_deployment_state()

claude_mpm/utils/dependency_cache.py

@@ -333,7 +333,9 @@ class SmartDependencyChecker:
         return True, "No valid cache, checking needed"
 
     def get_or_check_dependencies(
-        self, loader, force_check: bool = False  # AgentDependencyLoader instance
+        self,
+        loader,
+        force_check: bool = False,  # AgentDependencyLoader instance
     ) -> Tuple[Dict, bool]:
         """
         Get dependency results from cache or perform check.

claude_mpm/utils/gitignore.py

@@ -0,0 +1,241 @@
+"""GitIgnore management utilities.
+
+This module provides functionality to safely manage .gitignore entries,
+ensuring claude-mpm configuration directories are excluded from version control.
+
+Design Decisions:
+- In-memory set for duplicate detection (O(1) lookups)
+- Preserves existing file formatting and comments
+- Adds section headers for clarity
+- Handles edge cases (missing newlines, empty files, etc.)
+
+Trade-offs:
+- Simplicity: File append vs. full parse/rewrite (chosen append for safety)
+- Performance: Read entire file vs. streaming (file is small, simplicity wins)
+- Safety: Non-destructive append only, never modifies existing entries
+"""
+
+from pathlib import Path
+from typing import List, Set, Tuple
+
+from claude_mpm.core.logging_utils import get_logger
+
+logger = get_logger(__name__)
+
+
+class GitIgnoreManager:
+    """Manages .gitignore file updates safely and non-destructively.
+
+    Design Pattern: Builder pattern for fluent API
+    - Initialize with project directory
+    - Call ensure_entries() to add patterns
+    - Returns summary of changes made
+
+    Performance:
+    - Time Complexity: O(n) where n = existing .gitignore lines
+    - Space Complexity: O(n) for storing unique entries in set
+    - Expected Performance: <1ms for typical .gitignore files (<1000 lines)
+
+    Error Handling:
+    - FileNotFoundError: Creates new .gitignore if missing
+    - PermissionError: Propagated to caller for appropriate handling
+    - UnicodeDecodeError: Logged and treated as binary file (skip)
+    """
+
+    def __init__(self, project_dir: Path):
+        """Initialize with project directory.
+
+        Args:
+            project_dir: Path to project root (where .gitignore lives)
+        """
+        self.project_dir = Path(project_dir)
+        self.gitignore_path = self.project_dir / ".gitignore"
+
+    def ensure_entries(self, entries: List[str]) -> Tuple[List[str], List[str]]:
+        """Ensure specified entries exist in .gitignore.
+
+        Non-destructive operation that:
+        1. Reads existing entries (if file exists)
+        2. Identifies which entries are missing
+        3. Appends only missing entries with section header
+        4. Preserves all existing content and formatting
+
+        Args:
+            entries: List of gitignore patterns to add (e.g., [".claude-mpm/"])
+
+        Returns:
+            Tuple of (added_entries, existing_entries)
+            - added_entries: Patterns that were added to .gitignore
+            - existing_entries: Patterns that were already present
+
+        Example:
+            >>> manager = GitIgnoreManager(Path("."))
+            >>> added, existing = manager.ensure_entries([".claude-mpm/"])
+            >>> print(f"Added: {added}, Already present: {existing}")
+            Added: ['.claude-mpm/'], Already present: []
+        """
+        # Read existing entries
+        existing = self._read_existing_entries()
+
+        # Determine what needs to be added
+        to_add = [e for e in entries if e not in existing]
+        already_present = [e for e in entries if e in existing]
+
+        if to_add:
+            self._append_entries(to_add)
+            logger.info(f"Added {len(to_add)} entries to .gitignore: {to_add}")
+
+        if already_present:
+            logger.debug(f"Entries already in .gitignore: {already_present}")
+
+        return to_add, already_present
+
+    def _read_existing_entries(self) -> Set[str]:
+        """Read existing .gitignore entries.
+
+        Parses .gitignore file and extracts all non-comment, non-blank patterns.
+        Handles edge cases:
+        - File doesn't exist -> returns empty set
+        - File is binary -> logs warning, returns empty set
+        - File has no newline at end -> handled correctly
+
+        Returns:
+            Set of existing gitignore patterns (stripped, normalized)
+        """
+        if not self.gitignore_path.exists():
+            logger.debug(".gitignore does not exist, will create new file")
+            return set()
+
+        try:
+            with open(self.gitignore_path, encoding="utf-8") as f:
+                # Strip whitespace and comments, filter blanks
+                entries = {
+                    line.strip()
+                    for line in f
+                    if line.strip() and not line.strip().startswith("#")
+                }
+
+            logger.debug(f"Found {len(entries)} existing entries in .gitignore")
+            return entries
+
+        except UnicodeDecodeError:
+            logger.warning(
+                f".gitignore appears to be binary, cannot parse: {self.gitignore_path}"
+            )
+            return set()
+        except Exception as e:
+            logger.error(f"Error reading .gitignore: {e}")
+            raise
+
+    def _append_entries(self, entries: List[str]) -> None:
+        """Append entries to .gitignore with proper formatting.
+
+        Handles formatting edge cases:
+        - Ensures blank line before new section (if file exists and isn't empty)
+        - Adds section header comment for clarity
+        - Ensures each entry on its own line
+        - Handles missing trailing newline in existing file
+
+        Args:
+            entries: List of patterns to append
+
+        Raises:
+            PermissionError: If cannot write to .gitignore
+            OSError: If disk is full or other I/O error
+        """
+        mode = "a" if self.gitignore_path.exists() else "w"
+
+        try:
+            with open(self.gitignore_path, mode, encoding="utf-8") as f:
+                # Add blank line before entries if file exists and isn't empty
+                if mode == "a" and self.gitignore_path.stat().st_size > 0:
+                    # Check if last line has newline
+                    with open(self.gitignore_path, "rb") as check:
+                        check.seek(-1, 2)  # Seek to last byte
+                        last_byte = check.read(1)
+                        if last_byte != b"\n":
+                            f.write("\n")
+
+                    f.write("\n# Claude MPM configuration\n")
+                else:
+                    # New file or empty file - add header without extra blank line
+                    f.write("# Claude MPM configuration\n")
+
+                for entry in entries:
+                    f.write(f"{entry}\n")
+
+            logger.info(f"Updated .gitignore at {self.gitignore_path}")
+
+        except PermissionError:
+            logger.error(
+                f"Permission denied writing to .gitignore: {self.gitignore_path}"
+            )
+            raise
+        except OSError as e:
+            logger.error(f"I/O error writing to .gitignore: {e}")
+            raise
+
+
+def ensure_claude_mpm_gitignore(project_dir: str = ".") -> dict:
+    """Ensure claude-mpm directories are in .gitignore.
+
+    Convenience function that wraps GitIgnoreManager to add standard
+    claude-mpm configuration directories to .gitignore.
+
+    Standard Entries Added:
+    - .claude-mpm/: Main configuration directory
+    - .claude/agents/: Agent runtime files
+
+    Args:
+        project_dir: Project directory path (default: current directory)
+
+    Returns:
+        Dictionary with operation results:
+        - added: List of patterns that were added
+        - existing: List of patterns that were already present
+        - gitignore_path: Path to the .gitignore file
+
+    Example:
+        >>> result = ensure_claude_mpm_gitignore()
+        >>> if result["added"]:
+        ...     print(f"Added {len(result['added'])} entries to .gitignore")
+
+    Error Handling:
+        - PermissionError: Returns error dict with status="error"
+        - FileNotFoundError on parent dir: Returns error dict
+        - All other exceptions: Propagated to caller
+    """
+    try:
+        manager = GitIgnoreManager(Path(project_dir))
+
+        # Standard claude-mpm entries
+        entries_to_add = [
+            ".claude-mpm/",
+            ".claude/agents/",
+        ]
+
+        added, existing = manager.ensure_entries(entries_to_add)
+
+        return {
+            "status": "success",
+            "added": added,
+            "existing": existing,
+            "gitignore_path": str(manager.gitignore_path),
+        }
+
+    except PermissionError as e:
+        logger.error(f"Permission denied updating .gitignore: {e}")
+        return {
+            "status": "error",
+            "error": f"Permission denied: {e}",
+            "added": [],
+            "existing": [],
+        }
+    except FileNotFoundError as e:
+        logger.error(f"Project directory not found: {e}")
+        return {
+            "status": "error",
+            "error": f"Directory not found: {e}",
+            "added": [],
+            "existing": [],
+        }