@girardelli/architect 6.0.0 → 8.1.0

package/src/core/rules/import-organizer.ts

@@ -1,100 +0,0 @@
-import { basename, dirname } from 'path';
-import { AnalysisReport } from '../types/core.js';
-import { RefactorRule, RefactorStep, FileOperation } from '../types/rules.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);
-      }
-    }
-
-    // Outliers reais espalhados consumindo +5 diretórios. Testa bypass em unit-tests (.test.) naturais de altíssima injeção (mock).
-    const violators = Object.entries(crossBoundary)
-      .filter(([fileName, data]) => data.dirs.size >= 5 && !fileName.includes('.test.'))
-      .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) },
-        ],
-        aiPrompt: `Analyze the file \`${file}\` which currently imports from ${data.dirs.size} cross-boundary distinct directories/modules (${Array.from(data.dirs).join(', ')}).\nPlease refactor this to use the Dependency Injection (DI) or Facade pattern:\n1. Extract these imports into a dedicated file \`${facadePath}\`.\n2. Re-export or bundle them appropriately.\n3. Update \`${file}\` to import strictly from the new \`${facadePath}\` rather than directly reaching into multiple disjointed modules, lowering its afferent coupling.`,
-      });
-    }
-
-    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/core/rules/module-grouper.ts

@@ -1,133 +0,0 @@
-import { basename, dirname, join } from 'path';
-import { AnalysisReport } from '../types/core.js';
-import { RefactorRule, RefactorStep, FileOperation } from '../types/rules.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 >= 3)
-        .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) {
-          // Arquitetura Limpa: Impede arrastar Módulos Transversais (DTOs/Types) para se tornarem fechados em Pastas de Domínios
-          const hasTypes = cluster.some(f => {
-            const lowerF = f.toLowerCase();
-            return lowerF.includes('types') || lowerF.includes('interface') || lowerF.includes('/types/');
-          });
-          if (hasTypes) continue;
-
-          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) },
-        ],
-        aiPrompt: `Analyze the files: ${cluster.files.map(f => `\`${f}\``).join(', ')}.\nThese files are frequently imported together but are currently scattered across different directories.\nPlease refactor to improve cohesion:\n1. Create a new directory named \`${targetDir}\`.\n2. Move these files solidly into this new directory.\n3. Add an index/barrel file if appropriate.\n4. Securely scan the entire project to fix all broken imports resulting from this move.`,
-      });
-    }
-
-    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/core/scorer.ts

@@ -1,254 +0,0 @@
-import { ArchitectureScore, DependencyEdge, AntiPattern, ScoreComponent } from './types/core.js';
-import { basename } from 'path';
-
-export class ArchitectureScorer {
-  private modularity: number = 0;
-  private coupling: number = 0;
-  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', 'types.ts', 'types.js', 'logger.ts', 'logger.js'
-  ]);
-
-  score(
-    edges: DependencyEdge[],
-    antiPatterns: AntiPattern[],
-    totalFiles: number
-  ): ArchitectureScore {
-    this.calculateModularity(edges, totalFiles);
-    this.calculateCoupling(edges, totalFiles);
-    this.calculateCohesion(edges);
-    this.calculateLayering(antiPatterns, totalFiles);
-
-    const components = [
-      {
-        name: 'Modularity',
-        score: Math.round(this.modularity),
-        maxScore: 100,
-        weight: 0.4,
-        explanation:
-          'Measures appropriate module boundaries and single responsibility principle adherence',
-      },
-      {
-        name: 'Coupling',
-        score: Math.round(this.coupling),
-        maxScore: 100,
-        weight: 0.25,
-        explanation:
-          'Evaluates interdependencies between modules; lower coupling is better',
-      },
-      {
-        name: 'Cohesion',
-        score: Math.round(this.cohesion),
-        maxScore: 100,
-        weight: 0.2,
-        explanation:
-          'Assesses how closely related functionality is grouped together',
-      },
-      {
-        name: 'Layering',
-        score: Math.round(this.layering),
-        maxScore: 100,
-        weight: 0.15,
-        explanation: 'Checks adherence to architectural layer separation',
-      },
-    ];
-
-    const overall = Math.round(
-      components[0].score * components[0].weight +
-        components[1].score * components[1].weight +
-        components[2].score * components[2].weight +
-        components[3].score * components[3].weight
-    );
-
-    return {
-      overall: Math.min(100, Math.max(0, overall)),
-      components,
-      breakdown: {
-        modularity: Math.round(this.modularity),
-        coupling: Math.round(this.coupling),
-        cohesion: Math.round(this.cohesion),
-        layering: Math.round(this.layering),
-      },
-    };
-  }
-
-  private calculateModularity(edges: DependencyEdge[], totalFiles: number): void {
-    if (totalFiles === 0) {
-      this.modularity = 50;
-      return;
-    }
-
-    const avgEdgesPerFile = edges.length / totalFiles;
-
-    if (avgEdgesPerFile < 2) {
-      this.modularity = 100;
-    } else if (avgEdgesPerFile < 4) {
-      this.modularity = 85;
-    } else if (avgEdgesPerFile < 6) {
-      this.modularity = 70;
-    } else if (avgEdgesPerFile < 10) {
-      this.modularity = 50;
-    } else {
-      this.modularity = 30;
-    }
-  }
-
-  private calculateCoupling(edges: DependencyEdge[], totalFiles: number): void {
-    if (totalFiles === 0 || totalFiles === 1) {
-      this.coupling = 50;
-      return;
-    }
-
-    // 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;
-
-    // Use non-barrel file count for ratio calculation
-    const effectiveFiles = Math.max(totalFiles - 1, 1);
-    const couplingRatio = maxEdgeCount / effectiveFiles;
-
-    // More granular thresholds
-    if (couplingRatio < 0.15) {
-      this.coupling = 100;
-    } else if (couplingRatio < 0.25) {
-      this.coupling = 85;
-    } 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 = 20;
-    }
-  }
-
-  private findNodeWithMaxEdges(
-    edges: DependencyEdge[]
-  ): { node: string; count: number } | null {
-    const nodeEdgeCount: Record<string, number> = {};
-
-    for (const edge of edges) {
-      nodeEdgeCount[edge.from] = (nodeEdgeCount[edge.from] || 0) + 1;
-      nodeEdgeCount[edge.to] = (nodeEdgeCount[edge.to] || 0) + 1;
-    }
-
-    let maxNode: string | null = null;
-    let maxCount = 0;
-
-    for (const [node, count] of Object.entries(nodeEdgeCount)) {
-      if (count > maxCount) {
-        maxCount = count;
-        maxNode = node;
-      }
-    }
-
-    return maxNode ? { node: maxNode, count: maxCount } : null;
-  }
-
-  private calculateCohesion(edges: DependencyEdge[]): void {
-    if (edges.length === 0) {
-      this.cohesion = 50;
-      return;
-    }
-
-    const internalEdges = edges.filter((e) =>
-      this.isInternalDependency(e.from, e.to)
-    ).length;
-
-    const cohesionRatio = internalEdges / edges.length;
-
-    // More granular thresholds
-    if (cohesionRatio > 0.8) {
-      this.cohesion = 100;
-    } 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.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 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[], totalFiles?: number): void {
-    const layeringViolations = antiPatterns.filter(
-      (p) =>
-        p.name === 'Leaky Abstraction' ||
-        p.name === 'Shotgun Surgery' ||
-        p.name === 'Circular Dependency'
-    ).length;
-
-    if (layeringViolations === 0) {
-      this.layering = 100;
-      return;
-    }
-
-    // Use ratio-based scoring: violations per 100 files
-    // This makes scoring fair regardless of project size
-    const fileCount = Math.max(totalFiles || 50, 10);
-    const violationRatio = layeringViolations / fileCount;
-
-    if (violationRatio < 0.02) {
-      // < 2% — e.g. 1 violation in 50 files
-      this.layering = 95;
-    } else if (violationRatio < 0.05) {
-      // < 5% — e.g. 2-3 violations in 50 files
-      this.layering = 80;
-    } else if (violationRatio < 0.1) {
-      // < 10% — e.g. 5 violations in 50 files
-      this.layering = 65;
-    } else if (violationRatio < 0.2) {
-      // < 20% — significant issues
-      this.layering = 50;
-    } else if (violationRatio < 0.35) {
-      this.layering = 35;
-    } else {
-      // > 35% — severe layering problems
-      this.layering = 20;
-    }
-  }
-}
-

package/src/core/summarizer/keyword-extractor.ts

@@ -1,53 +0,0 @@
-import { existsSync, readFileSync } from 'fs';
-import { join, basename } from 'path';
-import { AnalysisReport } from '../types/core.js';
-import { ProjectSummary } from '../types/summarizer.js';
-import { FileNode, WorkspaceInfo } from '../types/infrastructure.js';
-
-export class KeywordExtractor {
-  public static readonly KEYWORD_BLACKLIST = new Set([
-    'node_modules', 'dist', 'build', '.git', '.next', 'coverage',
-    '__tests__', '__mocks__', 'src', 'lib', 'index', 'main',
-    'out', 'tmp', '.cache', 'vendor', '.vscode', '.idea',
-  ]);
-
-public extractKeywords(
-    packageInfo: Record<string, unknown>,
-    readme: string,
-    modules: ProjectSummary['modules'],
-    report: AnalysisReport,
-  ): string[] {
-    const keywords = new Set<string>();
-
-    // From package.json keywords
-    if (Array.isArray(packageInfo.keywords)) {
-      for (const kw of packageInfo.keywords) {
-        if (typeof kw === 'string') keywords.add(kw.toLowerCase());
-      }
-    }
-
-    // From module names (only clean names)
-    for (const mod of modules) {
-      const name = mod.name.toLowerCase();
-      if (!KeywordExtractor.KEYWORD_BLACKLIST.has(name)) {
-        keywords.add(name);
-      }
-    }
-
-    // From frameworks detected
-    for (const fw of report.projectInfo.frameworks) {
-      keywords.add(fw.toLowerCase());
-    }
-
-    // From languages
-    for (const lang of report.projectInfo.primaryLanguages) {
-      keywords.add(lang.toLowerCase());
-    }
-
-    // Filter out blacklisted and generic entries
-    return [...keywords]
-      .filter(kw => !KeywordExtractor.KEYWORD_BLACKLIST.has(kw) && kw.length > 1)
-      .slice(0, 20);
-  }
-
-}