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

coding_assistant/documentation/decomposition/module_detector.py

@@ -0,0 +1,302 @@
+"""Module detection for identifying logical code groupings.
+
+This module provides enhanced module detection capabilities beyond basic
+community detection, incorporating file structure, naming conventions,
+and architectural patterns.
+"""
+
+from typing import Dict, List, Set, Optional
+from pathlib import Path
+import networkx as nx
+from collections import defaultdict
+
+from coding_assistant.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+class ModuleDetector:
+    """
+    Enhanced module detection using multiple strategies.
+
+    Combines:
+    - Directory structure analysis
+    - Community detection (from Phase 1)
+    - Naming convention patterns
+    - File relationship analysis
+    """
+
+    def __init__(self, dependency_graph: nx.DiGraph):
+        """
+        Initialize module detector.
+
+        Args:
+            dependency_graph: File dependency graph
+        """
+        self.graph = dependency_graph
+
+    def detect_modules(self,
+                        strategy: str = 'hybrid',
+                        min_module_size: int = 2) -> Dict[str, List[str]]:
+        """
+        Detect logical modules using specified strategy.
+
+        Args:
+            strategy: Detection strategy ('directory', 'community', 'hybrid')
+            min_module_size: Minimum files per module
+
+        Returns:
+            Dictionary mapping module names to file lists
+        """
+        logger.info(f"Detecting modules using '{strategy}' strategy")
+
+        if strategy == 'directory':
+            modules = self._detect_by_directory()
+        elif strategy == 'community':
+            modules = self._detect_by_community()
+        elif strategy == 'hybrid':
+            modules = self._detect_hybrid()
+        else:
+            raise ValueError(f"Unknown strategy: {strategy}")
+
+        # Filter out small modules
+        filtered = {
+            name: files for name, files in modules.items()
+            if len(files) >= min_module_size
+        }
+
+        logger.info(f"Detected {len(filtered)} modules (filtered from {len(modules)})")
+
+        return filtered
+
+    def _detect_by_directory(self) -> Dict[str, List[str]]:
+        """
+        Detect modules based on directory structure.
+
+        Groups files by their parent directory.
+        """
+        modules = defaultdict(list)
+
+        for node in self.graph.nodes():
+            path = Path(node)
+
+            # Get parent directory as module name
+            if len(path.parts) > 1:
+                module_name = '.'.join(path.parts[:-1])
+            else:
+                module_name = 'root'
+
+            modules[module_name].append(node)
+
+        return dict(modules)
+
+    def _detect_by_community(self) -> Dict[str, List[str]]:
+        """
+        Detect modules using community detection (Louvain algorithm).
+
+        Delegates to ModuleAnalyzer from Phase 1.
+        """
+        from coding_assistant.documentation.graph.module_analyzer import ModuleAnalyzer
+
+        analyzer = ModuleAnalyzer(self.graph)
+        modules = analyzer.detect_modules()
+
+        return modules
+
+    def _detect_hybrid(self) -> Dict[str, List[str]]:
+        """
+        Hybrid approach combining directory structure and community detection.
+
+        Algorithm:
+        1. Start with directory-based grouping
+        2. Apply community detection within each directory group
+        3. Merge highly coupled cross-directory modules
+        """
+        # Step 1: Directory-based grouping
+        dir_modules = self._detect_by_directory()
+
+        # Step 2: Refine each directory module with community detection
+        refined_modules = {}
+
+        for dir_module_name, files in dir_modules.items():
+            if len(files) < 3:
+                # Too small for community detection
+                refined_modules[dir_module_name] = files
+                continue
+
+            # Create subgraph
+            try:
+                subgraph = self.graph.subgraph(files)
+
+                # Apply community detection
+                import community as community_louvain
+                undirected = subgraph.to_undirected()
+
+                partition = community_louvain.best_partition(undirected)
+
+                # Group by community
+                communities = defaultdict(list)
+                for node, community_id in partition.items():
+                    communities[community_id].append(node)
+
+                # Create refined module names
+                if len(communities) == 1:
+                    # Single community, keep original name
+                    refined_modules[dir_module_name] = files
+                else:
+                    # Multiple communities, create sub-modules
+                    for community_id, community_files in communities.items():
+                        module_name = f"{dir_module_name}.sub{community_id}"
+                        refined_modules[module_name] = community_files
+
+            except Exception as e:
+                logger.warning(f"Community detection failed for {dir_module_name}: {e}")
+                refined_modules[dir_module_name] = files
+
+        return refined_modules
+
+    def compute_module_quality(self, modules: Dict[str, List[str]]) -> Dict[str, float]:
+        """
+        Compute quality scores for detected modules.
+
+        Quality considers:
+        - Cohesion (internal connectivity)
+        - Size balance
+        - Clear boundaries
+
+        Args:
+            modules: Dictionary of module -> files
+
+        Returns:
+            Dictionary of module -> quality score (0-1)
+        """
+        quality_scores = {}
+
+        for module_name, files in modules.items():
+            cohesion = self._compute_cohesion(files)
+            size_score = self._compute_size_score(len(files), len(modules))
+            boundary_score = self._compute_boundary_score(files, modules)
+
+            # Weighted average
+            quality = (
+                0.5 * cohesion +
+                0.3 * size_score +
+                0.2 * boundary_score
+            )
+
+            quality_scores[module_name] = quality
+
+        return quality_scores
+
+    def _compute_cohesion(self, files: List[str]) -> float:
+        """Compute internal cohesion of a module."""
+        if len(files) < 2:
+            return 1.0
+
+        try:
+            subgraph = self.graph.subgraph(files)
+            edges = subgraph.number_of_edges()
+            possible = len(files) * (len(files) - 1)
+
+            return edges / possible if possible > 0 else 0.0
+
+        except:
+            return 0.0
+
+    def _compute_size_score(self, module_size: int, total_modules: int) -> float:
+        """
+        Compute size balance score.
+
+        Prefers modules that are not too large or too small.
+        """
+        ideal_size = max(3, len(list(self.graph.nodes())) // total_modules)
+
+        # Penalty for deviation from ideal
+        deviation = abs(module_size - ideal_size) / ideal_size
+        score = max(0, 1.0 - deviation)
+
+        return score
+
+    def _compute_boundary_score(self,
+                                  files: List[str],
+                                  all_modules: Dict[str, List[str]]) -> float:
+        """
+        Compute how well-defined the module boundaries are.
+
+        Lower external coupling = higher score.
+        """
+        external_edges = 0
+        internal_edges = 0
+
+        files_set = set(files)
+
+        for file in files:
+            if not self.graph.has_node(file):
+                continue
+
+            for _, target in self.graph.out_edges(file):
+                if target in files_set:
+                    internal_edges += 1
+                else:
+                    external_edges += 1
+
+        total_edges = internal_edges + external_edges
+
+        if total_edges == 0:
+            return 1.0
+
+        # Higher score for more internal edges
+        return internal_edges / total_edges
+
+    def suggest_module_improvements(self,
+                                      modules: Dict[str, List[str]]) -> List[str]:
+        """
+        Suggest improvements to module structure.
+
+        Args:
+            modules: Current module grouping
+
+        Returns:
+            List of improvement suggestions
+        """
+        suggestions = []
+
+        quality_scores = self.compute_module_quality(modules)
+
+        # Identify low-quality modules
+        low_quality = [
+            name for name, score in quality_scores.items()
+            if score < 0.5
+        ]
+
+        if low_quality:
+            suggestions.append(
+                f"Consider refactoring {len(low_quality)} low-quality modules: "
+                f"{', '.join(low_quality[:3])}"
+            )
+
+        # Check for very small modules
+        small_modules = [
+            name for name, files in modules.items()
+            if len(files) == 1
+        ]
+
+        if small_modules:
+            suggestions.append(
+                f"Merge {len(small_modules)} single-file modules with related modules"
+            )
+
+        # Check for very large modules
+        avg_size = sum(len(files) for files in modules.values()) / len(modules)
+        large_modules = [
+            name for name, files in modules.items()
+            if len(files) > avg_size * 3
+        ]
+
+        if large_modules:
+            suggestions.append(
+                f"Consider splitting {len(large_modules)} large modules: "
+                f"{', '.join(large_modules[:3])}"
+            )
+
+        return suggestions