@girardelli/architect 5.0.0 → 8.1.0

package/src/rules/barrel-optimizer.ts

@@ -1,97 +0,0 @@
-import { basename, dirname } from 'path';
-import { AnalysisReport, RefactorRule, RefactorStep, FileOperation } from '../types.js';
-
-/**
- * Barrel Optimizer Rule (Tier 1)
- * Analyzes barrel files (__init__.py, index.ts) and suggests optimization.
- * Barrel files that re-export everything create unnecessary coupling.
- */
-export class BarrelOptimizerRule implements RefactorRule {
-  name = 'barrel-optimizer';
-  tier = 1 as const;
-
-  private static readonly BARREL_FILES = new Set([
-    '__init__.py', 'index.ts', 'index.js', 'index.tsx', 'index.jsx',
-  ]);
-
-  analyze(report: AnalysisReport, projectPath: string): RefactorStep[] {
-    const steps: RefactorStep[] = [];
-
-    // Find barrel files in the dependency graph
-    const barrelNodes = report.dependencyGraph.nodes.filter((n) =>
-      BarrelOptimizerRule.BARREL_FILES.has(basename(n))
-    );
-
-    for (const barrel of barrelNodes) {
-      // Count how many things this barrel re-exports (outgoing edges)
-      const outgoing = report.dependencyGraph.edges.filter(
-        (e) => e.from === barrel
-      );
-      const incoming = report.dependencyGraph.edges.filter(
-        (e) => e.to === barrel
-      );
-
-      if (outgoing.length < 3) continue;
-
-      // Check for "pass-through" pattern: files import from barrel
-      // but barrel just re-exports from siblings
-      const siblingDir = dirname(barrel);
-      const siblingExports = outgoing.filter(
-        (e) => dirname(e.to) === siblingDir
-      );
-
-      const operations: FileOperation[] = [];
-
-      // Suggest direct imports instead of barrel
-      for (const consumer of incoming) {
-        const consumedModules = outgoing
-          .filter((e) => {
-            // Check if consumer actually needs this module
-            return report.dependencyGraph.edges.some(
-              (edge) => edge.from === consumer.from && edge.to === e.to
-            );
-          })
-          .map((e) => e.to);
-
-        if (consumedModules.length > 0) {
-          operations.push({
-            type: 'MODIFY',
-            path: consumer.from,
-            description: `Replace barrel import from \`${basename(barrel)}\` with direct imports: ${consumedModules.map((m) => basename(m)).join(', ')}`,
-          });
-        }
-      }
-
-      // Suggest simplifying the barrel
-      if (siblingExports.length > 5) {
-        operations.push({
-          type: 'MODIFY',
-          path: barrel,
-          description: `Simplify ${basename(barrel)}: only re-export public API (${siblingExports.length} re-exports detected, consider reducing)`,
-        });
-      }
-
-      if (operations.length > 0) {
-        steps.push({
-          id: 0,
-          tier: 1,
-          rule: this.name,
-          priority: outgoing.length >= 8 ? 'HIGH' : 'MEDIUM',
-          title: `Optimize barrel: ${barrel}`,
-          description: `\`${barrel}\` re-exports ${outgoing.length} modules. ` +
-            `This creates a "Shotgun Surgery" risk — any change propagates widely.`,
-          rationale: `Barrel files that re-export everything make it hard to tree-shake unused code ` +
-            `and create implicit dependencies. Direct imports make dependency relationships explicit ` +
-            `and reduce the blast radius of changes.`,
-          operations,
-          scoreImpact: [
-            { metric: 'coupling', before: report.score.breakdown.coupling, after: Math.min(95, report.score.breakdown.coupling + 10) },
-            { metric: 'layering', before: report.score.breakdown.layering, after: Math.min(95, report.score.breakdown.layering + 5) },
-          ],
-        });
-      }
-    }
-
-    return steps;
-  }
-}

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

@@ -1,132 +0,0 @@
-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

@@ -1,123 +0,0 @@
-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

@@ -1,98 +0,0 @@
-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

@@ -1,124 +0,0 @@
-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';
-  }
-}