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

coding_assistant/documentation/decomposition/context_preserver.py

@@ -0,0 +1,477 @@
+"""Preserve architectural context during decomposition.
+
+This module ensures that even when a repository is partitioned into smaller pieces,
+the documentation maintains coherence by preserving architectural context, shared
+interfaces, design patterns, and relationships between partitions.
+"""
+
+from typing import Dict, List, Set, Tuple, Optional
+from dataclasses import dataclass, field
+from pathlib import Path
+import networkx as nx
+from collections import defaultdict, Counter
+
+from coding_assistant.documentation.decomposition.partitioner import Partition
+from coding_assistant.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+@dataclass
+class ModuleContext:
+    """
+    Context information for a module partition.
+
+    Preserves architectural understanding across partition boundaries.
+    """
+    partition_name: str
+    related_partitions: List[str] = field(default_factory=list)  # Connected partitions
+    shared_interfaces: List[str] = field(default_factory=list)   # Shared APIs/interfaces
+    common_patterns: List[str] = field(default_factory=list)     # Design patterns used
+    architectural_role: str = ""                                  # e.g., "data layer", "API layer"
+    key_files: List[str] = field(default_factory=list)           # Most important files
+    exports: List[str] = field(default_factory=list)             # Public interfaces
+    imports_from: Dict[str, List[str]] = field(default_factory=dict)  # What it imports
+    metadata: Dict = field(default_factory=dict)
+
+    def __repr__(self):
+        return f"ModuleContext({self.partition_name}, role={self.architectural_role})"
+
+
+class ContextPreserver:
+    """
+    Preserve architectural context across partitions.
+
+    Ensures documentation remains coherent despite decomposition by:
+    - Identifying related partitions and their relationships
+    - Extracting shared interfaces and APIs
+    - Detecting design patterns within partitions
+    - Inferring architectural roles (data layer, API layer, UI, etc.)
+    - Preserving cross-partition dependencies
+    """
+
+    def __init__(self):
+        """Initialize the context preserver."""
+        pass
+
+    def extract_context(self,
+                        partition: Partition,
+                        all_partitions: List[Partition],
+                        dependency_graph: nx.DiGraph,
+                        parsed_files: Optional[Dict[str, Dict]] = None) -> ModuleContext:
+        """
+        Extract architectural context for a partition.
+
+        Args:
+            partition: The partition to analyze
+            all_partitions: All partitions in the repository
+            dependency_graph: Full dependency graph
+            parsed_files: Optional dictionary of parsed file information
+
+        Returns:
+            ModuleContext with extracted architectural information
+        """
+        logger.debug(f"Extracting context for partition: {partition.name}")
+
+        # Identify related partitions
+        related = self._find_related_partitions(partition, all_partitions, dependency_graph)
+
+        # Extract shared interfaces
+        interfaces = self._extract_shared_interfaces(
+            partition, related, dependency_graph, parsed_files
+        )
+
+        # Detect design patterns
+        patterns = self._detect_patterns(partition, parsed_files)
+
+        # Infer architectural role
+        role = self._infer_architectural_role(partition, all_partitions, dependency_graph)
+
+        # Find key files (most central within partition)
+        key_files = self._identify_key_files(partition, dependency_graph)
+
+        # Extract exports (public interfaces)
+        exports = self._extract_exports(partition, parsed_files)
+
+        # Extract import relationships
+        imports_from = self._extract_import_relationships(
+            partition, all_partitions, dependency_graph
+        )
+
+        context = ModuleContext(
+            partition_name=partition.name,
+            related_partitions=[p.name for p in related],
+            shared_interfaces=interfaces,
+            common_patterns=patterns,
+            architectural_role=role,
+            key_files=key_files,
+            exports=exports,
+            imports_from=imports_from,
+            metadata={
+                'file_count': len(partition.files),
+                'loc': partition.size_loc,
+                'cohesion': partition.cohesion_score,
+                'level': partition.level
+            }
+        )
+
+        logger.debug(f"Context extracted: role={role}, patterns={len(patterns)}, related={len(related)}")
+
+        return context
+
+    def _find_related_partitions(self,
+                                   partition: Partition,
+                                   all_partitions: List[Partition],
+                                   graph: nx.DiGraph) -> List[Partition]:
+        """
+        Find partitions that are closely related to this one.
+
+        Criteria:
+        - Direct dependencies (imports/exports)
+        - High coupling score
+        - Shared file patterns
+        """
+        related = []
+        partition_files = set(partition.files)
+
+        for other in all_partitions:
+            if other.name == partition.name:
+                continue
+
+            # Check if there's a dependency relationship
+            if partition.name in other.dependencies or other.name in partition.dependencies:
+                related.append(other)
+                continue
+
+            # Compute coupling
+            coupling = self._compute_coupling(partition_files, set(other.files), graph)
+
+            # Consider related if coupling > threshold
+            if coupling > 0.05:  # 5% coupling threshold
+                related.append(other)
+
+        return related
+
+    def _compute_coupling(self,
+                           files1: Set[str],
+                           files2: Set[str],
+                           graph: nx.DiGraph) -> float:
+        """Compute coupling between two file sets."""
+        if not files1 or not files2:
+            return 0.0
+
+        edges_between = 0
+
+        for file1 in files1:
+            for file2 in files2:
+                if graph.has_edge(file1, file2) or graph.has_edge(file2, file1):
+                    edges_between += 1
+
+        possible_edges = len(files1) * len(files2) * 2
+
+        return edges_between / possible_edges if possible_edges > 0 else 0.0
+
+    def _extract_shared_interfaces(self,
+                                     partition: Partition,
+                                     related: List[Partition],
+                                     graph: nx.DiGraph,
+                                     parsed_files: Optional[Dict[str, Dict]]) -> List[str]:
+        """
+        Extract APIs/interfaces shared between partitions.
+
+        Looks for:
+        - Public functions/classes used by other partitions
+        - Exported symbols
+        - Common interfaces
+        """
+        if not parsed_files:
+            return []
+
+        interfaces = []
+        partition_files = set(partition.files)
+        related_files = set()
+
+        for related_partition in related:
+            related_files.update(related_partition.files)
+
+        # Find functions/classes in this partition used by related partitions
+        for file_path in partition.files:
+            if file_path not in parsed_files:
+                continue
+
+            parsed = parsed_files[file_path]
+            functions = parsed.get('functions', [])
+            classes = parsed.get('classes', [])
+
+            # Check if any function/class is likely public (not starting with _)
+            for func in functions:
+                func_name = func.get('name', '')
+                if not func_name.startswith('_'):
+                    # This is potentially a public interface
+                    interfaces.append(f"{Path(file_path).stem}.{func_name}")
+
+            for cls in classes:
+                cls_name = cls.get('name', '')
+                if not cls_name.startswith('_'):
+                    interfaces.append(f"{Path(file_path).stem}.{cls_name}")
+
+        # Limit to most likely interfaces (deduplicate and limit)
+        return list(set(interfaces))[:20]
+
+    def _detect_patterns(self,
+                          partition: Partition,
+                          parsed_files: Optional[Dict[str, Dict]]) -> List[str]:
+        """
+        Detect common design patterns in partition.
+
+        Heuristics for detecting:
+        - Factory pattern (Factory in class names)
+        - Singleton pattern (getInstance methods)
+        - Builder pattern (Builder in class names)
+        - Strategy pattern (Strategy in class names)
+        - Observer pattern (Observer, Listener in names)
+        - MVC pattern (Model, View, Controller in names)
+        """
+        if not parsed_files:
+            return []
+
+        patterns = set()
+
+        # Collect all class and function names
+        all_names = []
+
+        for file_path in partition.files:
+            if file_path not in parsed_files:
+                continue
+
+            parsed = parsed_files[file_path]
+
+            for func in parsed.get('functions', []):
+                all_names.append(func.get('name', '').lower())
+
+            for cls in parsed.get('classes', []):
+                all_names.append(cls.get('name', '').lower())
+
+        # Pattern detection heuristics
+        pattern_keywords = {
+            'Factory Pattern': ['factory', 'create', 'builder'],
+            'Singleton Pattern': ['singleton', 'getinstance', 'instance'],
+            'Builder Pattern': ['builder', 'build'],
+            'Strategy Pattern': ['strategy', 'algorithm'],
+            'Observer Pattern': ['observer', 'listener', 'subscriber', 'event'],
+            'Repository Pattern': ['repository', 'repo', 'store'],
+            'Service Pattern': ['service', 'handler', 'processor'],
+            'MVC Pattern': ['model', 'view', 'controller'],
+            'Dependency Injection': ['inject', 'provider', 'container'],
+        }
+
+        for pattern_name, keywords in pattern_keywords.items():
+            for keyword in keywords:
+                if any(keyword in name for name in all_names):
+                    patterns.add(pattern_name)
+                    break
+
+        return sorted(list(patterns))
+
+    def _infer_architectural_role(self,
+                                    partition: Partition,
+                                    all_partitions: List[Partition],
+                                    graph: nx.DiGraph) -> str:
+        """
+        Infer the architectural role of this partition.
+
+        Roles:
+        - Data Layer: Database, models, entities
+        - Business Logic: Services, processors, handlers
+        - API Layer: Controllers, routes, endpoints
+        - UI Layer: Views, components, templates
+        - Infrastructure: Config, utilities, helpers
+        - Integration: External APIs, adapters
+        """
+        # Analyze partition name and file names
+        name_lower = partition.name.lower()
+        file_names = [Path(f).stem.lower() for f in partition.files]
+
+        # Role keywords
+        role_keywords = {
+            'Data Layer': ['model', 'entity', 'database', 'db', 'repository', 'dao', 'schema'],
+            'Business Logic': ['service', 'processor', 'handler', 'manager', 'business', 'logic'],
+            'API Layer': ['api', 'controller', 'route', 'endpoint', 'rest', 'graphql'],
+            'UI Layer': ['view', 'component', 'template', 'ui', 'frontend', 'page'],
+            'Infrastructure': ['config', 'util', 'helper', 'common', 'core', 'base'],
+            'Integration': ['client', 'adapter', 'integration', 'external', 'connector'],
+            'Testing': ['test', 'spec', 'mock', 'fixture'],
+            'CLI': ['cli', 'command', 'console'],
+            'Documentation': ['doc', 'documentation'],
+        }
+
+        # Score each role
+        role_scores = defaultdict(int)
+
+        for role, keywords in role_keywords.items():
+            for keyword in keywords:
+                # Check partition name
+                if keyword in name_lower:
+                    role_scores[role] += 3
+
+                # Check file names
+                for file_name in file_names:
+                    if keyword in file_name:
+                        role_scores[role] += 1
+
+        if not role_scores:
+            return "General Purpose"
+
+        # Return role with highest score
+        best_role = max(role_scores.items(), key=lambda x: x[1])
+
+        return best_role[0]
+
+    def _identify_key_files(self,
+                             partition: Partition,
+                             graph: nx.DiGraph,
+                             top_n: int = 5) -> List[str]:
+        """
+        Identify the most important files within a partition.
+
+        Uses centrality within the partition subgraph.
+        """
+        if len(partition.files) <= top_n:
+            return partition.files
+
+        try:
+            subgraph = graph.subgraph(partition.files)
+            centrality = nx.betweenness_centrality(subgraph)
+
+            sorted_files = sorted(
+                centrality.items(),
+                key=lambda x: x[1],
+                reverse=True
+            )
+
+            return [f for f, _ in sorted_files[:top_n]]
+
+        except:
+            # Fallback: return first N files
+            return partition.files[:top_n]
+
+    def _extract_exports(self,
+                          partition: Partition,
+                          parsed_files: Optional[Dict[str, Dict]]) -> List[str]:
+        """
+        Extract public interfaces (exports) from partition.
+
+        Returns list of exported symbols (functions, classes).
+        """
+        if not parsed_files:
+            return []
+
+        exports = []
+
+        for file_path in partition.files:
+            if file_path not in parsed_files:
+                continue
+
+            parsed = parsed_files[file_path]
+            file_name = Path(file_path).stem
+
+            # Extract public functions
+            for func in parsed.get('functions', []):
+                func_name = func.get('name', '')
+                if not func_name.startswith('_'):  # Public function
+                    exports.append(f"{file_name}.{func_name}")
+
+            # Extract public classes
+            for cls in parsed.get('classes', []):
+                cls_name = cls.get('name', '')
+                if not cls_name.startswith('_'):  # Public class
+                    exports.append(f"{file_name}.{cls_name}")
+
+        return exports[:30]  # Limit to top 30 exports
+
+    def _extract_import_relationships(self,
+                                        partition: Partition,
+                                        all_partitions: List[Partition],
+                                        graph: nx.DiGraph) -> Dict[str, List[str]]:
+        """
+        Extract what this partition imports from other partitions.
+
+        Returns:
+            Dictionary mapping partition names to lists of imported files
+        """
+        # Build file -> partition mapping
+        file_to_partition = {}
+        for p in all_partitions:
+            for f in p.files:
+                file_to_partition[f] = p.name
+
+        imports_from = defaultdict(list)
+
+        for file in partition.files:
+            if not graph.has_node(file):
+                continue
+
+            # Check all outgoing edges (imports)
+            for _, target in graph.out_edges(file):
+                if target in file_to_partition:
+                    target_partition = file_to_partition[target]
+                    if target_partition != partition.name:
+                        imports_from[target_partition].append(target)
+
+        # Deduplicate and convert to regular dict
+        return {
+            partition_name: list(set(files))
+            for partition_name, files in imports_from.items()
+        }
+
+    def generate_context_summary(self, context: ModuleContext) -> str:
+        """
+        Generate a human-readable summary of module context.
+
+        Args:
+            context: ModuleContext to summarize
+
+        Returns:
+            Formatted summary string
+        """
+        lines = [
+            f"Module Context: {context.partition_name}",
+            "=" * 60,
+            f"Architectural Role: {context.architectural_role}",
+            f"Files: {context.metadata.get('file_count', 0)}",
+            f"Lines of Code: {context.metadata.get('loc', 0)}",
+            f"Cohesion: {context.metadata.get('cohesion', 0):.2f}",
+            "",
+            "Related Partitions:",
+        ]
+
+        for related in context.related_partitions[:5]:
+            lines.append(f"  - {related}")
+
+        if context.common_patterns:
+            lines.extend([
+                "",
+                "Design Patterns:",
+            ])
+            for pattern in context.common_patterns:
+                lines.append(f"  - {pattern}")
+
+        if context.key_files:
+            lines.extend([
+                "",
+                "Key Files:",
+            ])
+            for file_path in context.key_files:
+                lines.append(f"  - {Path(file_path).name}")
+
+        if context.exports:
+            lines.extend([
+                "",
+                f"Public Interfaces ({len(context.exports)}):",
+            ])
+            for export in context.exports[:10]:
+                lines.append(f"  - {export}")
+
+        lines.append("=" * 60)
+
+        return "\n".join(lines)