@musashishao/agent-kit 1.2.2 → 1.3.0

package/.agent/skills/graph-mapper/scripts/generate_graph.py

@@ -0,0 +1,503 @@
+#!/usr/bin/env python3
+"""
+Graph Mapper - Lightweight Dependency Graph Generator
+
+Analyzes source code to build a dependency graph without external databases.
+Supports TypeScript/JavaScript and Python projects.
+
+Usage:
+    python generate_graph.py --src ./src --output .agent/graph.json --lang auto
+"""
+
+import os
+import re
+import json
+import argparse
+from pathlib import Path
+from typing import Dict, List, Set, Optional
+from dataclasses import dataclass, field, asdict
+from datetime import datetime
+
+
+@dataclass
+class Node:
+    """Represents a file node in the dependency graph."""
+    id: str
+    type: str  # component, hook, util, service, page, etc.
+    path: str
+    imports: List[str] = field(default_factory=list)
+    exports: List[str] = field(default_factory=list)
+
+
+@dataclass
+class Edge:
+    """Represents a dependency edge."""
+    source: str  # from
+    target: str  # to
+    type: str = "imports"  # imports, extends, implements
+
+
+@dataclass
+class Graph:
+    """The complete dependency graph."""
+    nodes: List[Node] = field(default_factory=list)
+    edges: List[Edge] = field(default_factory=list)
+    metadata: Dict = field(default_factory=dict)
+
+
+class TypeScriptAnalyzer:
+    """Analyzes TypeScript/JavaScript files for imports and exports."""
+    
+    EXTENSIONS = {'.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs'}
+    
+    # Regex patterns for import detection
+    IMPORT_PATTERNS = [
+        # import X from 'module'
+        r"import\s+(?:[\w\s{},*]+)\s+from\s+['\"]([^'\"]+)['\"]",
+        # import 'module'
+        r"import\s+['\"]([^'\"]+)['\"]",
+        # require('module')
+        r"require\s*\(\s*['\"]([^'\"]+)['\"]\s*\)",
+        # dynamic import('module')
+        r"import\s*\(\s*['\"]([^'\"]+)['\"]\s*\)",
+    ]
+    
+    EXPORT_PATTERNS = [
+        # export default
+        r"export\s+default\s+(?:class|function|const|let|var)?\s*(\w+)?",
+        # export { name }
+        r"export\s*\{([^}]+)\}",
+        # export const/let/var/function/class
+        r"export\s+(?:const|let|var|function|class|interface|type|enum)\s+(\w+)",
+    ]
+    
+    def __init__(self, base_path: Path, exclude_patterns: List[str]):
+        self.base_path = base_path
+        self.exclude_patterns = exclude_patterns
+    
+    def should_exclude(self, path: Path) -> bool:
+        """Check if path should be excluded."""
+        path_str = str(path)
+        for pattern in self.exclude_patterns:
+            if pattern in path_str:
+                return True
+        return False
+    
+    def analyze_file(self, file_path: Path) -> Optional[Node]:
+        """Analyze a single file for imports and exports."""
+        if self.should_exclude(file_path):
+            return None
+            
+        try:
+            content = file_path.read_text(encoding='utf-8')
+        except (UnicodeDecodeError, PermissionError):
+            return None
+        
+        relative_path = str(file_path.relative_to(self.base_path))
+        
+        # Determine node type based on path/filename
+        node_type = self._detect_type(relative_path)
+        
+        # Extract imports
+        imports = []
+        for pattern in self.IMPORT_PATTERNS:
+            matches = re.findall(pattern, content)
+            imports.extend(matches)
+        
+        # Resolve relative imports to absolute paths
+        imports = [self._resolve_import(imp, file_path) for imp in imports]
+        imports = [imp for imp in imports if imp]  # Filter None
+        
+        # Extract exports
+        exports = []
+        for pattern in self.EXPORT_PATTERNS:
+            matches = re.findall(pattern, content)
+            for match in matches:
+                if match:
+                    # Handle multiple exports in braces
+                    if ',' in match:
+                        exports.extend([e.strip() for e in match.split(',')])
+                    else:
+                        exports.append(match.strip())
+        
+        return Node(
+            id=relative_path,
+            type=node_type,
+            path=relative_path,
+            imports=list(set(imports)),
+            exports=list(set(exports))
+        )
+    
+    def _detect_type(self, path: str) -> str:
+        """Detect the type of file based on path and name."""
+        path_lower = path.lower()
+        
+        if '/components/' in path_lower or path_lower.startswith('components/'):
+            return 'component'
+        elif '/hooks/' in path_lower or path_lower.startswith('hooks/'):
+            return 'hook'
+        elif '/utils/' in path_lower or '/lib/' in path_lower:
+            return 'utility'
+        elif '/services/' in path_lower or '/api/' in path_lower:
+            return 'service'
+        elif '/pages/' in path_lower or '/app/' in path_lower:
+            return 'page'
+        elif '/types/' in path_lower:
+            return 'type'
+        elif '/store/' in path_lower or '/redux/' in path_lower:
+            return 'store'
+        elif '.test.' in path_lower or '.spec.' in path_lower:
+            return 'test'
+        else:
+            return 'module'
+    
+    def _resolve_import(self, import_path: str, from_file: Path) -> Optional[str]:
+        """Resolve relative import to project-relative path."""
+        # Skip external packages
+        if not import_path.startswith('.'):
+            return None
+        
+        # Resolve relative path
+        from_dir = from_file.parent
+        resolved = (from_dir / import_path).resolve()
+        
+        # Try common extensions if no extension
+        if not resolved.suffix:
+            for ext in self.EXTENSIONS:
+                test_path = resolved.with_suffix(ext)
+                if test_path.exists():
+                    resolved = test_path
+                    break
+            # Try index file
+            index_path = resolved / 'index.ts'
+            if index_path.exists():
+                resolved = index_path
+        
+        try:
+            return str(resolved.relative_to(self.base_path))
+        except ValueError:
+            return None
+    
+    def analyze_directory(self, directory: Path) -> List[Node]:
+        """Analyze all files in a directory."""
+        nodes = []
+        
+        for file_path in directory.rglob('*'):
+            if file_path.is_file() and file_path.suffix in self.EXTENSIONS:
+                node = self.analyze_file(file_path)
+                if node:
+                    nodes.append(node)
+        
+        return nodes
+
+
+class PythonAnalyzer:
+    """Analyzes Python files for imports and exports."""
+    
+    EXTENSIONS = {'.py'}
+    
+    IMPORT_PATTERNS = [
+        # from module import name
+        r"from\s+([\w.]+)\s+import",
+        # import module
+        r"^import\s+([\w.]+)",
+    ]
+    
+    def __init__(self, base_path: Path, exclude_patterns: List[str]):
+        self.base_path = base_path
+        self.exclude_patterns = exclude_patterns
+    
+    def should_exclude(self, path: Path) -> bool:
+        """Check if path should be excluded."""
+        path_str = str(path)
+        for pattern in self.exclude_patterns:
+            if pattern in path_str:
+                return True
+        return False
+    
+    def analyze_file(self, file_path: Path) -> Optional[Node]:
+        """Analyze a single Python file."""
+        if self.should_exclude(file_path):
+            return None
+            
+        try:
+            content = file_path.read_text(encoding='utf-8')
+        except (UnicodeDecodeError, PermissionError):
+            return None
+        
+        relative_path = str(file_path.relative_to(self.base_path))
+        node_type = self._detect_type(relative_path)
+        
+        # Extract imports
+        imports = []
+        for pattern in self.IMPORT_PATTERNS:
+            matches = re.findall(pattern, content, re.MULTILINE)
+            imports.extend(matches)
+        
+        # Resolve to file paths
+        imports = [self._resolve_import(imp) for imp in imports]
+        imports = [imp for imp in imports if imp]
+        
+        # Extract exports (public functions/classes)
+        exports = []
+        # Classes
+        exports.extend(re.findall(r"^class\s+(\w+)", content, re.MULTILINE))
+        # Functions (not private)
+        exports.extend(re.findall(r"^def\s+([a-zA-Z]\w*)", content, re.MULTILINE))
+        
+        return Node(
+            id=relative_path,
+            type=node_type,
+            path=relative_path,
+            imports=list(set(imports)),
+            exports=list(set(exports))
+        )
+    
+    def _detect_type(self, path: str) -> str:
+        """Detect the type of Python file."""
+        path_lower = path.lower()
+        
+        if '/models/' in path_lower:
+            return 'model'
+        elif '/views/' in path_lower or '/routes/' in path_lower:
+            return 'view'
+        elif '/services/' in path_lower:
+            return 'service'
+        elif '/utils/' in path_lower or '/helpers/' in path_lower:
+            return 'utility'
+        elif '/tests/' in path_lower or 'test_' in path_lower:
+            return 'test'
+        elif '/api/' in path_lower:
+            return 'api'
+        else:
+            return 'module'
+    
+    def _resolve_import(self, import_path: str) -> Optional[str]:
+        """Resolve Python import to file path."""
+        # Convert dot notation to path
+        path_parts = import_path.split('.')
+        
+        # Try to find the file
+        possible_path = self.base_path / '/'.join(path_parts)
+        
+        # Check for .py file
+        py_file = possible_path.with_suffix('.py')
+        if py_file.exists():
+            try:
+                return str(py_file.relative_to(self.base_path))
+            except ValueError:
+                return None
+        
+        # Check for package (__init__.py)
+        init_file = possible_path / '__init__.py'
+        if init_file.exists():
+            try:
+                return str(init_file.relative_to(self.base_path))
+            except ValueError:
+                return None
+        
+        return None
+    
+    def analyze_directory(self, directory: Path) -> List[Node]:
+        """Analyze all Python files in a directory."""
+        nodes = []
+        
+        for file_path in directory.rglob('*.py'):
+            if file_path.is_file():
+                node = self.analyze_file(file_path)
+                if node:
+                    nodes.append(node)
+        
+        return nodes
+
+
+def build_edges(nodes: List[Node]) -> List[Edge]:
+    """Build edges from node imports."""
+    edges = []
+    node_ids = {node.id for node in nodes}
+    
+    for node in nodes:
+        for imp in node.imports:
+            # Only create edge if target exists in our nodes
+            if imp in node_ids:
+                edges.append(Edge(
+                    source=node.id,
+                    target=imp,
+                    type="imports"
+                ))
+    
+    return edges
+
+
+def calculate_impact(graph: Graph, file_id: str, depth: int = 3) -> Dict:
+    """Calculate impact zone for a file."""
+    # Build reverse lookup (who imports this file)
+    dependents: Dict[str, Set[str]] = {}
+    for edge in graph.edges:
+        if edge.target not in dependents:
+            dependents[edge.target] = set()
+        dependents[edge.target].add(edge.source)
+    
+    # BFS to find all dependents up to depth
+    visited = set()
+    current_level = {file_id}
+    impact_files = []
+    
+    for _ in range(depth):
+        next_level = set()
+        for file in current_level:
+            if file in visited:
+                continue
+            visited.add(file)
+            if file in dependents:
+                for dep in dependents[file]:
+                    if dep not in visited:
+                        next_level.add(dep)
+                        impact_files.append(dep)
+        current_level = next_level
+        if not current_level:
+            break
+    
+    return {
+        "file": file_id,
+        "direct_dependents": list(dependents.get(file_id, [])),
+        "transitive_dependents": impact_files,
+        "impact_score": len(set(impact_files))
+    }
+
+
+def generate_markdown(graph: Graph, output_path: Path):
+    """Generate markdown representation of the graph."""
+    # Build reverse lookup
+    dependents: Dict[str, List[str]] = {}
+    for edge in graph.edges:
+        if edge.target not in dependents:
+            dependents[edge.target] = []
+        dependents[edge.target].append(edge.source)
+    
+    lines = [
+        "# Dependency Graph",
+        "",
+        f"> Generated: {datetime.now().isoformat()}",
+        f"> Total Files: {len(graph.nodes)}",
+        f"> Total Dependencies: {len(graph.edges)}",
+        "",
+        "---",
+        ""
+    ]
+    
+    # Group nodes by type
+    nodes_by_type: Dict[str, List[Node]] = {}
+    for node in graph.nodes:
+        if node.type not in nodes_by_type:
+            nodes_by_type[node.type] = []
+        nodes_by_type[node.type].append(node)
+    
+    for node_type, nodes in sorted(nodes_by_type.items()):
+        lines.append(f"## {node_type.title()}s ({len(nodes)})")
+        lines.append("")
+        
+        for node in sorted(nodes, key=lambda n: n.id):
+            lines.append(f"### `{node.id}`")
+            lines.append("")
+            
+            if node.imports:
+                lines.append("**Imports:**")
+                for imp in sorted(node.imports):
+                    lines.append(f"- `{imp}`")
+                lines.append("")
+            
+            deps = dependents.get(node.id, [])
+            if deps:
+                lines.append("**Imported by:**")
+                for dep in sorted(deps):
+                    lines.append(f"- `{dep}`")
+                lines.append("")
+            
+            impact_score = len(deps)
+            lines.append(f"**Impact Score:** {impact_score}")
+            lines.append("")
+            lines.append("---")
+            lines.append("")
+    
+    output_path.write_text('\n'.join(lines), encoding='utf-8')
+
+
+def main():
+    parser = argparse.ArgumentParser(description='Generate dependency graph')
+    parser.add_argument('--src', default='./src', help='Source directory')
+    parser.add_argument('--output', default='.agent/graph.json', help='Output file')
+    parser.add_argument('--format', choices=['json', 'markdown', 'both'], default='both')
+    parser.add_argument('--lang', choices=['typescript', 'python', 'auto'], default='auto')
+    parser.add_argument('--depth', type=int, default=3, help='Max depth for impact analysis')
+    parser.add_argument('--exclude', default='node_modules,__pycache__,.git,dist,build',
+                       help='Comma-separated patterns to exclude')
+    
+    args = parser.parse_args()
+    
+    src_path = Path(args.src).resolve()
+    output_path = Path(args.output)
+    exclude_patterns = args.exclude.split(',')
+    
+    if not src_path.exists():
+        print(f"Error: Source directory '{src_path}' does not exist")
+        return 1
+    
+    # Detect language if auto
+    lang = args.lang
+    if lang == 'auto':
+        ts_files = list(src_path.rglob('*.ts')) + list(src_path.rglob('*.tsx'))
+        py_files = list(src_path.rglob('*.py'))
+        lang = 'typescript' if len(ts_files) >= len(py_files) else 'python'
+        print(f"Auto-detected language: {lang}")
+    
+    # Analyze based on language
+    if lang == 'typescript':
+        analyzer = TypeScriptAnalyzer(src_path, exclude_patterns)
+    else:
+        analyzer = PythonAnalyzer(src_path, exclude_patterns)
+    
+    print(f"Analyzing {src_path}...")
+    nodes = analyzer.analyze_directory(src_path)
+    print(f"Found {len(nodes)} files")
+    
+    # Build graph
+    edges = build_edges(nodes)
+    print(f"Found {len(edges)} dependencies")
+    
+    graph = Graph(
+        nodes=nodes,
+        edges=edges,
+        metadata={
+            "generated_at": datetime.now().isoformat(),
+            "source_path": str(src_path),
+            "language": lang,
+            "total_files": len(nodes),
+            "total_edges": len(edges)
+        }
+    )
+    
+    # Ensure output directory exists
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    
+    # Generate outputs
+    if args.format in ['json', 'both']:
+        json_data = {
+            "metadata": graph.metadata,
+            "nodes": [asdict(n) for n in graph.nodes],
+            "edges": [asdict(e) for e in graph.edges]
+        }
+        output_path.write_text(json.dumps(json_data, indent=2), encoding='utf-8')
+        print(f"Generated: {output_path}")
+    
+    if args.format in ['markdown', 'both']:
+        md_path = output_path.with_suffix('.md')
+        generate_markdown(graph, md_path)
+        print(f"Generated: {md_path}")
+    
+    print("Done!")
+    return 0
+
+
+if __name__ == '__main__':
+    exit(main())