@girardelli/architect 1.3.0 → 2.2.0

package/src/rules/dead-code-detector.ts

@@ -0,0 +1,132 @@
+import { basename } from 'path';
+import { AnalysisReport, RefactorRule, RefactorStep, FileOperation } from '../types.js';
+
+/**
+ * Dead Code Detector Rule (Tier 1)
+ * Finds files with no incoming edges (nobody imports them)
+ * and exports that are never used.
+ * 
+ * Handles both path-style (deepguard/report.py) and
+ * dot-notation (deepguard.report) references.
+ */
+export class DeadCodeDetectorRule implements RefactorRule {
+  name = 'dead-code-detector';
+  tier = 1 as const;
+
+  private static readonly ENTRY_POINTS = new Set([
+    'main.py', 'cli.py', 'app.py', 'manage.py', 'wsgi.py', 'asgi.py',
+    'main.ts', 'main.js', 'app.ts', 'app.js', 'server.ts', 'server.js',
+    'index.html', 'setup.py', 'setup.cfg', 'pyproject.toml',
+  ]);
+
+  analyze(report: AnalysisReport, projectPath: string): RefactorStep[] {
+    const steps: RefactorStep[] = [];
+    const edges = report.dependencyGraph.edges;
+
+    // Build a set of ALL referenced targets (both path and dot-notation)
+    const allTargets = new Set<string>();
+    const allSources = new Set<string>();
+    for (const edge of edges) {
+      allTargets.add(edge.to);
+      allSources.add(edge.from);
+    }
+
+    // Only consider actual files (with path separators) as candidates
+    const fileNodes = report.dependencyGraph.nodes.filter(
+      (n) => n.includes('/') || n.includes('\\')
+    );
+
+    // Build incoming edge count considering dot-notation matches
+    const incomingCount: Record<string, number> = {};
+
+    for (const file of fileNodes) {
+      incomingCount[file] = 0;
+
+      // Direct incoming edges
+      for (const edge of edges) {
+        if (edge.to === file) {
+          incomingCount[file]++;
+        }
+      }
+
+      // Check dot-notation references:
+      // deepguard/report.py might be referenced as deepguard.report or .report
+      const dotVariants = this.getDotVariants(file);
+      for (const variant of dotVariants) {
+        if (allTargets.has(variant)) {
+          incomingCount[file]++;
+        }
+      }
+    }
+
+    // Find orphan files
+    const orphans: string[] = [];
+
+    for (const [file, count] of Object.entries(incomingCount)) {
+      const fileName = basename(file);
+
+      // Skip entry points and config files
+      if (DeadCodeDetectorRule.ENTRY_POINTS.has(fileName)) continue;
+      if (fileName.startsWith('__')) continue;
+      if (fileName.startsWith('.')) continue;
+      if (fileName.endsWith('.test.ts') || fileName.endsWith('.spec.ts')) continue;
+      if (fileName.endsWith('_test.py') || fileName.endsWith('.test.py')) continue;
+
+      // Also skip if the file has outgoing edges (it's active code)
+      if (allSources.has(file)) continue;
+
+      if (count === 0) {
+        orphans.push(file);
+      }
+    }
+
+    if (orphans.length > 0) {
+      const operations: FileOperation[] = orphans.map((file) => ({
+        type: 'DELETE' as const,
+        path: file,
+        description: `\`${basename(file)}\` has no incoming dependencies — verify if still needed`,
+      }));
+
+      steps.push({
+        id: 0,
+        tier: 1,
+        rule: this.name,
+        priority: orphans.length >= 3 ? 'MEDIUM' : 'LOW',
+        title: `Review ${orphans.length} potentially unused file(s)`,
+        description: `Found ${orphans.length} file(s) with no incoming dependencies: ` +
+          `${orphans.map((f) => `\`${basename(f)}\``).join(', ')}. ` +
+          `These may be dead code or missing from the module's public API.`,
+        rationale: `Files with zero incoming edges are either entry points (already excluded), ` +
+          `or potentially dead code. Removing dead code reduces maintenance burden ` +
+          `and improves modularity scores.`,
+        operations,
+        scoreImpact: [
+          { metric: 'modularity', before: report.score.breakdown.modularity, after: Math.min(95, report.score.breakdown.modularity + 5) },
+        ],
+      });
+    }
+
+    return steps;
+  }
+
+  /**
+   * Generate dot-notation variants for a file path.
+   * "deepguard/report.py" → ["deepguard.report", ".report"]
+   */
+  private getDotVariants(filePath: string): string[] {
+    const variants: string[] = [];
+    const withoutExt = filePath.replace(/\.[^.]+$/, '');
+    const dotPath = withoutExt.replace(/[/\\]/g, '.');
+
+    variants.push(dotPath);
+
+    // Relative dot-notation: .report
+    const parts = filePath.split('/');
+    if (parts.length >= 2) {
+      const lastPart = parts[parts.length - 1].replace(/\.[^.]+$/, '');
+      variants.push(`.${lastPart}`);
+    }
+
+    return variants;
+  }
+}

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/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[];
+}
+