ai-coding-assistant 0.5.0__py3-none-any.whl

coding_assistant/documentation/graph/module_analyzer.py

@@ -0,0 +1,475 @@
+"""Analyze module relationships and coherence."""
+
+from typing import Dict, List, Set, Tuple, Optional
+import networkx as nx
+from collections import defaultdict
+import community as community_louvain
+
+from coding_assistant.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+class ModuleAnalyzer:
+    """
+    Analyze and identify logical modules in codebase.
+
+    Uses graph analysis techniques to:
+    - Detect logical module groupings (community detection)
+    - Compute cohesion and coupling metrics
+    - Identify core/central files
+    - Analyze architectural patterns
+    """
+
+    def __init__(self, dependency_graph: nx.DiGraph):
+        """
+        Initialize the module analyzer.
+
+        Args:
+            dependency_graph: Dependency graph from DependencyGraphBuilder
+        """
+        self.graph = dependency_graph
+
+    def detect_modules(self, resolution: float = 1.0) -> Dict[str, List[str]]:
+        """
+        Detect logical modules using community detection.
+
+        Uses the Louvain algorithm for community detection, which finds
+        densely connected groups of nodes (files that work closely together).
+
+        Args:
+            resolution: Resolution parameter for Louvain algorithm.
+                       Higher values -> more smaller communities
+                       Lower values -> fewer larger communities
+
+        Returns:
+            Dictionary mapping module names to lists of file paths
+        """
+        if self.graph.number_of_nodes() == 0:
+            logger.warning("Empty graph, cannot detect modules")
+            return {}
+
+        logger.info(f"Detecting modules using Louvain algorithm (resolution={resolution})")
+
+        # Convert to undirected graph for community detection
+        undirected = self.graph.to_undirected()
+
+        # Apply Louvain community detection
+        try:
+            partition = community_louvain.best_partition(
+                undirected,
+                resolution=resolution
+            )
+
+            # Group nodes by community
+            communities: Dict[int, List[str]] = defaultdict(list)
+            for node, community_id in partition.items():
+                communities[community_id].append(node)
+
+            # Convert to named modules
+            modules = {}
+            for i, (community_id, files) in enumerate(sorted(communities.items())):
+                # Try to name module based on common path prefix
+                module_name = self._infer_module_name(files) or f"module_{i}"
+                modules[module_name] = files
+
+            logger.info(f"Detected {len(modules)} modules")
+
+            # Log module sizes
+            for module_name, files in modules.items():
+                logger.info(f"  {module_name}: {len(files)} files")
+
+            return modules
+
+        except Exception as e:
+            logger.error(f"Failed to detect modules: {e}")
+            return {}
+
+    def _infer_module_name(self, files: List[str]) -> Optional[str]:
+        """
+        Infer a meaningful module name from a list of files.
+
+        Looks for common path prefix or directory name.
+
+        Args:
+            files: List of file paths in the module
+
+        Returns:
+            Inferred module name or None
+        """
+        if not files:
+            return None
+
+        # Find common path prefix
+        from pathlib import Path
+
+        paths = [Path(f).parts for f in files]
+
+        if len(paths) == 1:
+            # Single file, use its parent directory
+            return Path(files[0]).parent.name
+
+        # Find longest common prefix
+        common_prefix = []
+        for parts in zip(*paths):
+            if len(set(parts)) == 1:
+                common_prefix.append(parts[0])
+            else:
+                break
+
+        if common_prefix:
+            # Filter out common parts like 'src', 'coding_assistant'
+            filtered = [p for p in common_prefix if p not in ['src', 'home', 'projects']]
+            if filtered:
+                return '.'.join(filtered)
+
+        return None
+
+    def compute_cohesion(self, module_files: List[str]) -> float:
+        """
+        Compute cohesion score for a module.
+
+        Cohesion measures how closely related the files within a module are.
+        Higher cohesion = better module design.
+
+        Formula: (internal edges) / (possible internal edges)
+
+        Args:
+            module_files: List of file paths in the module
+
+        Returns:
+            Cohesion score between 0 and 1
+        """
+        if len(module_files) < 2:
+            return 1.0  # Single file is perfectly cohesive
+
+        # Create subgraph for this module
+        try:
+            subgraph = self.graph.subgraph(module_files)
+
+            # Count actual internal edges
+            internal_edges = subgraph.number_of_edges()
+
+            # Count possible edges (for directed graph: n * (n-1))
+            n = len(module_files)
+            possible_edges = n * (n - 1)
+
+            if possible_edges == 0:
+                return 1.0
+
+            cohesion = internal_edges / possible_edges
+
+            return min(cohesion, 1.0)  # Cap at 1.0
+
+        except Exception as e:
+            logger.warning(f"Failed to compute cohesion: {e}")
+            return 0.0
+
+    def compute_coupling(self, module1: List[str], module2: List[str]) -> float:
+        """
+        Compute coupling between two modules.
+
+        Coupling measures how dependent two modules are on each other.
+        Lower coupling = better module design (loose coupling).
+
+        Formula: (edges between modules) / (total possible edges between modules)
+
+        Args:
+            module1: Files in first module
+            module2: Files in second module
+
+        Returns:
+            Coupling score between 0 and 1
+        """
+        if not module1 or not module2:
+            return 0.0
+
+        # Count edges from module1 to module2 and vice versa
+        edges_between = 0
+
+        for file1 in module1:
+            for file2 in module2:
+                if self.graph.has_edge(file1, file2):
+                    edges_between += 1
+                if self.graph.has_edge(file2, file1):
+                    edges_between += 1
+
+        # Total possible edges
+        possible_edges = len(module1) * len(module2) * 2  # Both directions
+
+        if possible_edges == 0:
+            return 0.0
+
+        coupling = edges_between / possible_edges
+
+        return min(coupling, 1.0)
+
+    def identify_core_files(self, top_n: int = 10) -> List[Tuple[str, float]]:
+        """
+        Identify the most central/important files using betweenness centrality.
+
+        Core files are those that connect different parts of the codebase
+        and are crucial for information flow.
+
+        Args:
+            top_n: Number of core files to return
+
+        Returns:
+            List of (file_path, centrality_score) tuples, sorted by score
+        """
+        if self.graph.number_of_nodes() == 0:
+            return []
+
+        try:
+            # Compute betweenness centrality
+            centrality = nx.betweenness_centrality(self.graph)
+
+            # Sort by centrality
+            sorted_files = sorted(
+                centrality.items(),
+                key=lambda x: x[1],
+                reverse=True
+            )
+
+            core_files = sorted_files[:top_n]
+
+            logger.info(f"Identified {len(core_files)} core files")
+            for file_path, score in core_files[:5]:
+                logger.info(f"  {file_path}: {score:.4f}")
+
+            return core_files
+
+        except Exception as e:
+            logger.error(f"Failed to identify core files: {e}")
+            return []
+
+    def compute_module_metrics(self, modules: Dict[str, List[str]]) -> Dict[str, Dict]:
+        """
+        Compute comprehensive metrics for each module.
+
+        Args:
+            modules: Dictionary mapping module names to file lists
+
+        Returns:
+            Dictionary mapping module names to their metrics
+        """
+        module_metrics = {}
+
+        for module_name, files in modules.items():
+            metrics = {
+                'file_count': len(files),
+                'cohesion': self.compute_cohesion(files),
+                'avg_coupling': 0.0,
+                'total_lines': 0,
+            }
+
+            # Compute total lines of code
+            for file_path in files:
+                if self.graph.has_node(file_path):
+                    node_data = self.graph.nodes[file_path]
+                    metrics['total_lines'] += node_data.get('line_count', 0)
+
+            # Compute average coupling with other modules
+            couplings = []
+            for other_module, other_files in modules.items():
+                if other_module != module_name:
+                    coupling = self.compute_coupling(files, other_files)
+                    couplings.append(coupling)
+
+            if couplings:
+                metrics['avg_coupling'] = sum(couplings) / len(couplings)
+
+            module_metrics[module_name] = metrics
+
+        return module_metrics
+
+    def analyze_module_dependencies(self, modules: Dict[str, List[str]]) -> Dict[str, List[str]]:
+        """
+        Analyze dependencies between modules.
+
+        Args:
+            modules: Dictionary mapping module names to file lists
+
+        Returns:
+            Dictionary mapping module names to lists of modules they depend on
+        """
+        module_deps: Dict[str, Set[str]] = defaultdict(set)
+
+        # Create reverse mapping: file -> module
+        file_to_module = {}
+        for module_name, files in modules.items():
+            for file_path in files:
+                file_to_module[file_path] = module_name
+
+        # Analyze dependencies
+        for source_module, files in modules.items():
+            for file_path in files:
+                if self.graph.has_node(file_path):
+                    # Check all outgoing edges
+                    for _, target_file in self.graph.out_edges(file_path):
+                        target_module = file_to_module.get(target_file)
+                        if target_module and target_module != source_module:
+                            module_deps[source_module].add(target_module)
+
+        # Convert sets to sorted lists
+        return {
+            module: sorted(list(deps))
+            for module, deps in module_deps.items()
+        }
+
+    def detect_layered_architecture(self, modules: Dict[str, List[str]]) -> Dict[int, List[str]]:
+        """
+        Detect layered architecture by analyzing module dependencies.
+
+        Identifies layers where:
+        - Layer 0: Modules with no dependencies
+        - Layer 1: Modules depending only on Layer 0
+        - Layer N: Modules depending on Layers 0 to N-1
+
+        Args:
+            modules: Dictionary mapping module names to file lists
+
+        Returns:
+            Dictionary mapping layer number to list of module names
+        """
+        module_deps = self.analyze_module_dependencies(modules)
+
+        layers: Dict[int, List[str]] = defaultdict(list)
+        assigned = set()
+
+        current_layer = 0
+
+        while len(assigned) < len(modules):
+            current_layer_modules = []
+
+            for module_name in modules.keys():
+                if module_name in assigned:
+                    continue
+
+                deps = set(module_deps.get(module_name, []))
+
+                # Check if all dependencies are in previous layers
+                if not deps or deps.issubset(assigned):
+                    current_layer_modules.append(module_name)
+
+            if not current_layer_modules:
+                # Circular dependencies or disconnected components
+                # Assign remaining modules to current layer
+                for module_name in modules.keys():
+                    if module_name not in assigned:
+                        current_layer_modules.append(module_name)
+
+            layers[current_layer] = current_layer_modules
+            assigned.update(current_layer_modules)
+            current_layer += 1
+
+        logger.info(f"Detected {len(layers)} architectural layers")
+        for layer_num, layer_modules in layers.items():
+            logger.info(f"  Layer {layer_num}: {', '.join(layer_modules)}")
+
+        return dict(layers)
+
+    def identify_architectural_patterns(self, modules: Dict[str, List[str]]) -> List[str]:
+        """
+        Identify common architectural patterns in the codebase.
+
+        Detects patterns like:
+        - MVC (Model-View-Controller)
+        - Layered architecture
+        - Microservices/modular
+        - Monolithic
+
+        Args:
+            modules: Dictionary mapping module names to file lists
+
+        Returns:
+            List of detected pattern names
+        """
+        patterns = []
+
+        # Check for layered architecture
+        layers = self.detect_layered_architecture(modules)
+        if len(layers) >= 3:
+            patterns.append("Layered Architecture")
+
+        # Check for MVC pattern (common module names)
+        module_names_lower = [m.lower() for m in modules.keys()]
+
+        mvc_keywords = {'model', 'view', 'controller'}
+        if any(keyword in name for name in module_names_lower for keyword in mvc_keywords):
+            patterns.append("MVC Pattern")
+
+        # Check for modular architecture (many loosely coupled modules)
+        if len(modules) >= 5:
+            metrics = self.compute_module_metrics(modules)
+            avg_coupling = sum(m['avg_coupling'] for m in metrics.values()) / len(metrics)
+
+            if avg_coupling < 0.2:
+                patterns.append("Modular Architecture (Low Coupling)")
+
+        # Check for monolithic (few modules, high coupling)
+        if len(modules) <= 2:
+            patterns.append("Monolithic Architecture")
+
+        logger.info(f"Detected architectural patterns: {', '.join(patterns) if patterns else 'None'}")
+
+        return patterns
+
+    def generate_module_summary(self, modules: Dict[str, List[str]]) -> str:
+        """
+        Generate a human-readable summary of module analysis.
+
+        Args:
+            modules: Dictionary mapping module names to file lists
+
+        Returns:
+            Formatted summary string
+        """
+        metrics = self.compute_module_metrics(modules)
+        dependencies = self.analyze_module_dependencies(modules)
+        patterns = self.identify_architectural_patterns(modules)
+        core_files = self.identify_core_files(top_n=5)
+
+        summary_lines = [
+            "=" * 60,
+            "MODULE ANALYSIS SUMMARY",
+            "=" * 60,
+            "",
+            f"Total Modules: {len(modules)}",
+            f"Total Files: {sum(len(files) for files in modules.values())}",
+            "",
+            "Detected Patterns:",
+        ]
+
+        for pattern in patterns:
+            summary_lines.append(f"  - {pattern}")
+
+        summary_lines.extend([
+            "",
+            "Module Metrics:",
+        ])
+
+        for module_name, module_metrics in metrics.items():
+            summary_lines.append(
+                f"  {module_name}:"
+            )
+            summary_lines.append(
+                f"    Files: {module_metrics['file_count']}, "
+                f"LOC: {module_metrics['total_lines']}, "
+                f"Cohesion: {module_metrics['cohesion']:.2f}, "
+                f"Avg Coupling: {module_metrics['avg_coupling']:.2f}"
+            )
+
+        summary_lines.extend([
+            "",
+            "Core Files (Highest Centrality):",
+        ])
+
+        for file_path, centrality in core_files:
+            from pathlib import Path
+            filename = Path(file_path).name
+            summary_lines.append(f"  {filename}: {centrality:.4f}")
+
+        summary_lines.append("=" * 60)
+
+        return "\n".join(summary_lines)

coding_assistant/documentation/writers/__init__.py

@@ -0,0 +1,11 @@
+"""Documentation writers for various output formats.
+
+This module provides writers that convert generated documentation
+and diagrams into different output formats (markdown, HTML, etc.).
+"""
+
+from .markdown_writer import MarkdownWriter
+
+__all__ = [
+    'MarkdownWriter',
+]