@girardelli/architect 1.2.1 → 2.1.0

package/src/rules/hub-splitter.ts

@@ -0,0 +1,123 @@
+import { basename, dirname, join } from 'path';
+import { AnalysisReport, RefactorRule, RefactorStep, FileOperation } from '../types.js';
+
+/**
+ * Hub Splitter Rule (Tier 1)
+ * Detects files with many connections and generates split plans.
+ * A "hub" is a file that many other files depend on, creating tight coupling.
+ */
+export class HubSplitterRule implements RefactorRule {
+  name = 'hub-splitter';
+  tier = 1 as const;
+
+  analyze(report: AnalysisReport, projectPath: string): RefactorStep[] {
+    const steps: RefactorStep[] = [];
+
+    // Count connections per node
+    const connectionCount: Record<string, { incoming: string[]; outgoing: string[] }> = {};
+
+    for (const edge of report.dependencyGraph.edges) {
+      if (!connectionCount[edge.from]) connectionCount[edge.from] = { incoming: [], outgoing: [] };
+      if (!connectionCount[edge.to]) connectionCount[edge.to] = { incoming: [], outgoing: [] };
+      connectionCount[edge.from].outgoing.push(edge.to);
+      connectionCount[edge.to].incoming.push(edge.from);
+    }
+
+    // Find hubs (5+ incoming connections, not barrel files)
+    const barrelFiles = new Set(['__init__.py', 'index.ts', 'index.js', 'index.tsx', 'mod.rs']);
+
+    for (const [file, connections] of Object.entries(connectionCount)) {
+      const fileName = basename(file);
+      if (barrelFiles.has(fileName)) continue;
+      if (connections.incoming.length < 5) continue;
+
+      const operations: FileOperation[] = [];
+
+      // Determine if this is a dot-notation module or a real file
+      const isDotNotation = !file.includes('/') && !file.includes('\\');
+      const moduleName = isDotNotation
+        ? file.split('.').pop() || file
+        : fileName.replace(/\.[^.]+$/, '');
+      const moduleDir = isDotNotation
+        ? file.split('.').slice(0, -1).join('/')
+        : dirname(file);
+      const ext = isDotNotation ? 'py' : (fileName.split('.').pop() || 'py');
+
+      // Analyze what dependents import to suggest groupings
+      const dependentGroups = this.groupDependents(connections.incoming);
+
+      // Suggest splitting into domain modules
+      if (dependentGroups.length >= 2) {
+        for (const group of dependentGroups) {
+          const newFileName = `${moduleName}_${group.name}.${ext}`;
+          const newPath = moduleDir ? `${moduleDir}/${newFileName}` : newFileName;
+
+          operations.push({
+            type: 'CREATE',
+            path: newPath,
+            description: `Create \`${newFileName}\` with functionality used by: ${group.dependents.join(', ')}`,
+            content: ext === 'py'
+              ? `"""${moduleName}_${group.name} — extracted from ${moduleName}."""\n# Used by: ${group.dependents.join(', ')}\n`
+              : `// ${moduleName}_${group.name} — extracted from ${moduleName}\n// Used by: ${group.dependents.join(', ')}\n`,
+          });
+        }
+
+        // Update imports in all dependents
+        for (const dependent of connections.incoming) {
+          operations.push({
+            type: 'MODIFY',
+            path: dependent,
+            description: `Update imports in \`${basename(dependent)}\` to use new split modules`,
+          });
+        }
+
+        // Mark original for refactoring
+        operations.push({
+          type: 'MODIFY',
+          path: isDotNotation ? `${moduleDir}/${moduleName}.${ext}` : file,
+          description: `Refactor \`${moduleName}.${ext}\` — extract grouped functionality to new modules`,
+        });
+      }
+
+      if (operations.length > 0) {
+        steps.push({
+          id: 0,
+          tier: 1,
+          rule: this.name,
+          priority: connections.incoming.length >= 8 ? 'CRITICAL' : 'HIGH',
+          title: `Split hub file: ${moduleName}.${ext}`,
+          description: `\`${file}\` has ${connections.incoming.length} incoming connections. ` +
+            `Split into ${dependentGroups.length} focused modules to reduce coupling.`,
+          rationale: `High fan-in (${connections.incoming.length} files depend on this) creates a bottleneck. ` +
+            `Changes to this file ripple to ${connections.incoming.length} other files. ` +
+            `Splitting by usage pattern reduces blast radius.`,
+          operations,
+          scoreImpact: [
+            { metric: 'coupling', before: report.score.breakdown.coupling, after: Math.min(95, report.score.breakdown.coupling + 15) },
+          ],
+        });
+      }
+    }
+
+    return steps;
+  }
+
+  private groupDependents(
+    dependents: string[]
+  ): Array<{ name: string; dependents: string[] }> {
+    // Group by top-level directory
+    const groups: Record<string, string[]> = {};
+
+    for (const dep of dependents) {
+      const parts = dep.includes('/') ? dep.split('/') : dep.split('.');
+      const groupName = parts.length >= 2 ? parts[parts.length - 2] : 'core';
+      if (!groups[groupName]) groups[groupName] = [];
+      groups[groupName].push(basename(dep));
+    }
+
+    return Object.entries(groups).map(([name, deps]) => ({
+      name,
+      dependents: deps,
+    }));
+  }
+}

package/src/rules/import-organizer.ts

@@ -0,0 +1,98 @@
+import { basename, dirname } from 'path';
+import { AnalysisReport, RefactorRule, RefactorStep, FileOperation } from '../types.js';
+
+/**
+ * Import Organizer Rule (Tier 1)
+ * Detects files that import from too many different modules (cross-boundary).
+ * Suggests dependency injection or facade patterns.
+ */
+export class ImportOrganizerRule implements RefactorRule {
+  name = 'import-organizer';
+  tier = 1 as const;
+
+  analyze(report: AnalysisReport, projectPath: string): RefactorStep[] {
+    const steps: RefactorStep[] = [];
+
+    // Find files that import from many different directories
+    const crossBoundary: Record<string, { targets: Set<string>; dirs: Set<string> }> = {};
+
+    for (const edge of report.dependencyGraph.edges) {
+      const fromDir = dirname(edge.from);
+      const toDir = dirname(edge.to);
+
+      if (!crossBoundary[edge.from]) {
+        crossBoundary[edge.from] = { targets: new Set(), dirs: new Set() };
+      }
+      crossBoundary[edge.from].targets.add(edge.to);
+
+      if (fromDir !== toDir) {
+        crossBoundary[edge.from].dirs.add(toDir);
+      }
+    }
+
+    // Files importing from 3+ different directories
+    const violators = Object.entries(crossBoundary)
+      .filter(([_, data]) => data.dirs.size >= 3)
+      .sort((a, b) => b[1].dirs.size - a[1].dirs.size);
+
+    for (const [file, data] of violators) {
+      const operations: FileOperation[] = [];
+      const fileName = basename(file);
+      const fileDir = dirname(file);
+
+      // Suggest creating a facade/service layer
+      const ext = fileName.split('.').pop() || 'py';
+      const nameBase = fileName.replace(/\.[^.]+$/, '');
+      const facadePath = `${fileDir}/${nameBase}_deps.${ext}`;
+
+      operations.push({
+        type: 'CREATE',
+        path: facadePath,
+        description: `Create dependency facade \`${basename(facadePath)}\` — centralizes ${data.dirs.size} cross-module imports`,
+        content: this.generateFacadeContent(ext, Array.from(data.targets), Array.from(data.dirs)),
+      });
+
+      operations.push({
+        type: 'MODIFY',
+        path: file,
+        description: `Refactor \`${fileName}\` to import from local facade instead of ${data.dirs.size} different modules`,
+      });
+
+      steps.push({
+        id: 0,
+        tier: 1,
+        rule: this.name,
+        priority: data.dirs.size >= 5 ? 'HIGH' : 'MEDIUM',
+        title: `Reduce cross-boundary imports: ${fileName}`,
+        description: `\`${file}\` imports from ${data.dirs.size} different modules: ` +
+          `${Array.from(data.dirs).map((d) => `\`${d}\``).join(', ')}. ` +
+          `Consider using a facade or dependency injection.`,
+        rationale: `Files with imports scattered across many modules have high afferent coupling. ` +
+          `A facade centralizes these dependencies, making the file easier to test (mock one facade) ` +
+          `and reducing the impact of changes in dependent modules.`,
+        operations,
+        scoreImpact: [
+          { metric: 'cohesion', before: report.score.breakdown.cohesion, after: Math.min(95, report.score.breakdown.cohesion + 5) },
+          { metric: 'coupling', before: report.score.breakdown.coupling, after: Math.min(95, report.score.breakdown.coupling + 5) },
+        ],
+      });
+    }
+
+    return steps;
+  }
+
+  private generateFacadeContent(ext: string, targets: string[], dirs: string[]): string {
+    if (ext === 'py') {
+      const imports = targets
+        .map((t) => `# from ${t.replace(/\//g, '.')} import ...`)
+        .join('\n');
+      return `"""Dependency facade — centralizes cross-module imports."""\n\n${imports}\n\n# Re-export what ${dirs.length} modules need\n`;
+    }
+
+    // JS/TS
+    const imports = targets
+      .map((t) => `// export { ... } from '${t}';`)
+      .join('\n');
+    return `/**\n * Dependency facade — centralizes cross-module imports.\n */\n\n${imports}\n`;
+  }
+}

package/src/rules/module-grouper.ts

@@ -0,0 +1,124 @@
+import { basename, dirname, join } from 'path';
+import { AnalysisReport, RefactorRule, RefactorStep, FileOperation } from '../types.js';
+
+/**
+ * Module Grouper Rule (Tier 1)
+ * Analyzes which files are frequently imported together and suggests
+ * grouping them into cohesive modules/packages.
+ */
+export class ModuleGrouperRule implements RefactorRule {
+  name = 'module-grouper';
+  tier = 1 as const;
+
+  analyze(report: AnalysisReport, projectPath: string): RefactorStep[] {
+    const steps: RefactorStep[] = [];
+
+    // Build co-import matrix: which files are imported together?
+    const coImportCount: Record<string, Record<string, number>> = {};
+
+    // For each source file, see what it imports
+    const importsBySource: Record<string, string[]> = {};
+    for (const edge of report.dependencyGraph.edges) {
+      if (!importsBySource[edge.from]) importsBySource[edge.from] = [];
+      importsBySource[edge.from].push(edge.to);
+    }
+
+    // Count co-imports
+    for (const [source, targets] of Object.entries(importsBySource)) {
+      for (let i = 0; i < targets.length; i++) {
+        for (let j = i + 1; j < targets.length; j++) {
+          const a = targets[i];
+          const b = targets[j];
+          if (!coImportCount[a]) coImportCount[a] = {};
+          if (!coImportCount[b]) coImportCount[b] = {};
+          coImportCount[a][b] = (coImportCount[a][b] || 0) + 1;
+          coImportCount[b][a] = (coImportCount[b][a] || 0) + 1;
+        }
+      }
+    }
+
+    // Find clusters: files that are always imported together
+    const clusters: Array<{ files: string[]; coImportScore: number }> = [];
+    const visited = new Set<string>();
+
+    for (const [fileA, partners] of Object.entries(coImportCount)) {
+      if (visited.has(fileA)) continue;
+
+      const strongPartners = Object.entries(partners)
+        .filter(([_, count]) => count >= 2)
+        .sort((a, b) => b[1] - a[1]);
+
+      if (strongPartners.length >= 2) {
+        const cluster = [fileA, ...strongPartners.map(([f]) => f)];
+        const inSameDir = cluster.every(
+          (f) => dirname(f) === dirname(cluster[0])
+        );
+
+        // Only suggest if NOT already in the same directory
+        if (!inSameDir) {
+          const score = strongPartners.reduce((sum, [_, c]) => sum + c, 0);
+          clusters.push({ files: cluster, coImportScore: score });
+          cluster.forEach((f) => visited.add(f));
+        }
+      }
+    }
+
+    // Generate steps for each cluster
+    for (const cluster of clusters.slice(0, 3)) {
+      const operations: FileOperation[] = [];
+      const clusterName = this.suggestModuleName(cluster.files);
+      const targetDir = `${dirname(cluster.files[0])}/${clusterName}`;
+
+      // Create new module directory
+      operations.push({
+        type: 'CREATE',
+        path: `${targetDir}/__init__.py`,
+        description: `Create new module \`${clusterName}/\` to group ${cluster.files.length} co-dependent files`,
+        content: `"""Module ${clusterName} — grouped by co-import pattern."""\n`,
+      });
+
+      // Move files
+      for (const file of cluster.files) {
+        const newPath = join(targetDir, basename(file));
+        operations.push({
+          type: 'MOVE',
+          path: file,
+          newPath,
+          description: `Move \`${basename(file)}\` → \`${clusterName}/${basename(file)}\``,
+        });
+      }
+
+      steps.push({
+        id: 0,
+        tier: 1,
+        rule: this.name,
+        priority: 'MEDIUM',
+        title: `Group co-dependent files into \`${clusterName}/\``,
+        description: `Files ${cluster.files.map((f) => `\`${basename(f)}\``).join(', ')} ` +
+          `are frequently imported together (co-import score: ${cluster.coImportScore}). ` +
+          `Grouping them improves cohesion.`,
+        rationale: `Files that are frequently imported together belong in the same module. ` +
+          `This improves discoverability and reduces the cognitive load of understanding ` +
+          `which files work together.`,
+        operations,
+        scoreImpact: [
+          { metric: 'cohesion', before: report.score.breakdown.cohesion, after: Math.min(95, report.score.breakdown.cohesion + 10) },
+          { metric: 'modularity', before: report.score.breakdown.modularity, after: Math.min(95, report.score.breakdown.modularity + 5) },
+        ],
+      });
+    }
+
+    return steps;
+  }
+
+  private suggestModuleName(files: string[]): string {
+    // Try to infer a common theme from filenames
+    const names = files.map((f) => basename(f).replace(/\.[^.]+$/, '').toLowerCase());
+    const commonParts = names[0].split(/[_-]/).filter((part) =>
+      names.every((n) => n.includes(part))
+    );
+
+    if (commonParts.length > 0) return commonParts[0];
+    return 'shared';
+  }
+}

package/src/scorer.ts

@@ -1,4 +1,5 @@
 import { ArchitectureScore, DependencyEdge, AntiPattern, ScoreComponent } from './types.js';
+import { basename } from 'path';
 
 export class ArchitectureScorer {
   private modularity: number = 0;
@@ -6,6 +7,15 @@ export class ArchitectureScorer {
   private cohesion: number = 0;
   private layering: number = 0;
 
+  /**
+   * Barrel/index files that naturally have many connections and should be
+   * excluded from coupling max-edge penalty calculations.
+   */
+  private static readonly BARREL_FILES = new Set([
+    '__init__.py', 'index.ts', 'index.js', 'index.tsx', 'index.jsx',
+    'mod.rs', '__init__.pyi',
+  ]);
+
   score(
     edges: DependencyEdge[],
     antiPatterns: AntiPattern[],
@@ -91,26 +101,42 @@ export class ArchitectureScorer {
   }
 
   private calculateCoupling(edges: DependencyEdge[], totalFiles: number): void {
-    if (totalFiles === 0) {
+    if (totalFiles === 0 || totalFiles === 1) {
       this.coupling = 50;
       return;
     }
 
-    const nodeWithMaxEdges = this.findNodeWithMaxEdges(edges);
+    // Exclude barrel/index files from max-edge calculation —
+    // they naturally have many connections by design.
+    const nonBarrelEdges = edges.filter((e) => {
+      const fromFile = basename(e.from);
+      const toFile = basename(e.to);
+      return !ArchitectureScorer.BARREL_FILES.has(fromFile) &&
+             !ArchitectureScorer.BARREL_FILES.has(toFile);
+    });
+
+    const nodeWithMaxEdges = this.findNodeWithMaxEdges(nonBarrelEdges);
     const maxEdgeCount = nodeWithMaxEdges ? nodeWithMaxEdges.count : 0;
 
-    const couplingRatio = maxEdgeCount / (totalFiles - 1);
+    // Use non-barrel file count for ratio calculation
+    const effectiveFiles = Math.max(totalFiles - 1, 1);
+    const couplingRatio = maxEdgeCount / effectiveFiles;
 
-    if (couplingRatio < 0.2) {
+    // More granular thresholds
+    if (couplingRatio < 0.15) {
       this.coupling = 95;
-    } else if (couplingRatio < 0.4) {
+    } else if (couplingRatio < 0.25) {
       this.coupling = 85;
-    } else if (couplingRatio < 0.6) {
-      this.coupling = 70;
-    } else if (couplingRatio < 0.8) {
+    } else if (couplingRatio < 0.35) {
+      this.coupling = 75;
+    } else if (couplingRatio < 0.5) {
+      this.coupling = 65;
+    } else if (couplingRatio < 0.7) {
       this.coupling = 50;
+    } else if (couplingRatio < 0.85) {
+      this.coupling = 35;
     } else {
-      this.coupling = 30;
+      this.coupling = 20;
     }
   }
 
@@ -149,23 +175,42 @@ export class ArchitectureScorer {
 
     const cohesionRatio = internalEdges / edges.length;
 
-    if (cohesionRatio > 0.7) {
+    // More granular thresholds
+    if (cohesionRatio > 0.8) {
       this.cohesion = 95;
-    } else if (cohesionRatio > 0.5) {
-      this.cohesion = 80;
+    } else if (cohesionRatio > 0.6) {
+      this.cohesion = 85;
+    } else if (cohesionRatio > 0.45) {
+      this.cohesion = 75;
     } else if (cohesionRatio > 0.3) {
       this.cohesion = 65;
-    } else if (cohesionRatio > 0.1) {
-      this.cohesion = 45;
+    } else if (cohesionRatio > 0.15) {
+      this.cohesion = 50;
     } else {
       this.cohesion = 30;
     }
   }
 
+  /**
+   * Determines if a dependency is "internal" (cohesive).
+   * Two files are considered cohesive if they share the same top-level
+   * package/directory (e.g., deepguard/cli.py → deepguard/analyzer.py).
+   * This is crucial for Python flat packages where all files live in
+   * one directory but ARE cohesive.
+   */
   private isInternalDependency(from: string, to: string): boolean {
-    const fromModule = from.split('/').slice(0, -1).join('/');
-    const toModule = to.split('/').slice(0, -1).join('/');
-    return fromModule === toModule;
+    const fromParts = from.split('/');
+    const toParts = to.split('/');
+
+    // If both are in root (no directory), they're cohesive
+    if (fromParts.length <= 1 && toParts.length <= 1) return true;
+
+    // Compare top-level directory (package name)
+    // e.g., "deepguard/cli.py" and "deepguard/analyzer.py" → same package
+    const fromTopLevel = fromParts.length > 1 ? fromParts[0] : '';
+    const toTopLevel = toParts.length > 1 ? toParts[0] : '';
+
+    return fromTopLevel === toTopLevel;
   }
 
   private calculateLayering(antiPatterns: AntiPattern[]): void {
@@ -191,3 +236,4 @@ export class ArchitectureScorer {
     }
   }
 }
+

package/src/types.ts

@@ -112,3 +112,55 @@ export interface ParsedImport {
   isDefault: boolean;
   isNamespace: boolean;
 }
+
+// ── v2.0 Refactoring Types ──
+
+export interface RefactoringPlan {
+  timestamp: string;
+  projectPath: string;
+  currentScore: ArchitectureScore;
+  estimatedScoreAfter: { overall: number; breakdown: Record<string, number> };
+  steps: RefactorStep[];
+  totalOperations: number;
+  tier1Steps: number;
+  tier2Steps: number;
+}
+
+export interface RefactorStep {
+  id: number;
+  tier: 1 | 2;
+  rule: string;
+  priority: 'CRITICAL' | 'HIGH' | 'MEDIUM' | 'LOW';
+  title: string;
+  description: string;
+  rationale: string;
+  operations: FileOperation[];
+  scoreImpact: { metric: string; before: number; after: number }[];
+  codePreview?: string;
+}
+
+export interface FileOperation {
+  type: 'CREATE' | 'MOVE' | 'MODIFY' | 'DELETE';
+  path: string;
+  newPath?: string;
+  content?: string;
+  diff?: string;
+  description: string;
+}
+
+export interface CodeSymbol {
+  name: string;
+  type: 'function' | 'class' | 'variable' | 'import' | 'export';
+  startLine: number;
+  endLine: number;
+  lines: number;
+  dependencies: string[];
+  usedBy: string[];
+}
+
+export interface RefactorRule {
+  name: string;
+  tier: 1 | 2;
+  analyze(report: AnalysisReport, projectPath: string): RefactorStep[];
+}
+