@girardelli/architect-core 8.1.0

package/src/core/locales/types.ts

@@ -0,0 +1,95 @@
+export interface TranslationDictionary {
+  // Common
+  common: {
+    generatedBy: string;
+    mandatory: string;
+    yes: string;
+    no: string;
+    action: string;
+  };
+  
+  // Scanners / Progress
+  progress: {
+    scan: string;
+    dependencies: string;
+    layers: string;
+    antipatterns: string;
+    scoring: string;
+    normalize: string;
+    summarize: string;
+    
+    // Verbs
+    scanningSystem: string;
+    mappingGraph: string;
+    classifyingArch: string;
+    detectingAntiPatterns: string;
+    computingMetrics: string;
+    normalizingPaths: string;
+    generatingSummary: string;
+  };
+
+  // Agents
+  agents: {
+    backend: {
+      description: string;
+      title: string;
+      specialistIn: string;
+      stack: string;
+      principles: string;
+      projectStructure: string;
+      implementationRules: string;
+      rulesBody: string;
+      afterImplementation: string;
+      afterBody: string;
+    };
+    frontend: {
+      description: string;
+      title: string;
+      specialistIn: string;
+      stack: string;
+      prerequisites: string;
+      prerequisitesBody: string;
+      implementationRules: string;
+      rulesBody: string;
+    };
+    security: {
+      description: string;
+      title: string;
+      analysisFor: string;
+      checklist: string;
+      checklistBody: string;
+      whenToActivate: string;
+      whenBody: string;
+      expectedOutput: string;
+      outputBody: string;
+    };
+    qa: {
+      description: string;
+      title: string;
+      qualityFor: string;
+      nonNegotiable: string;
+      nonNegotiableBody: (min: number) => string;
+      pyramid: string;
+      process: string;
+      processBody: string;
+    };
+    techDebt: {
+      description: string;
+      title: string;
+      controlFor: string;
+      currentState: string;
+      roadmap: string;
+      targets: string;
+      rules: string;
+    };
+  };
+
+  // Domain & Enriched
+  enriched: {
+    modules: string;
+    endpoints: string;
+    domainContext: string;
+    untestedModules: string;
+    untestedModulesBody: (count: number) => string;
+  };
+}

package/src/core/plugin-loader.ts

@@ -0,0 +1,80 @@
+import path from 'path';
+import fs from 'fs';
+import { ArchitectPlugin, CustomAntiPatternDetector, PluginContext } from './types/plugin.js';
+import { ArchitectConfig } from './types/core.js';
+import { logger } from '../infrastructure/logger.js';
+
+export class PluginLoader {
+  private customDetectors: CustomAntiPatternDetector[] = [];
+  
+  constructor(
+    private projectPath: string,
+    private config: ArchitectConfig
+  ) {}
+
+  public get customAntiPatternDetectors(): CustomAntiPatternDetector[] {
+    return this.customDetectors;
+  }
+
+  public async loadPlugins(): Promise<void> {
+    if (!this.config.plugins || this.config.plugins.length === 0) {
+      return;
+    }
+
+    const context: PluginContext = {
+      projectPath: this.projectPath,
+      config: this.config
+    };
+
+    for (const pluginSpec of this.config.plugins) {
+      try {
+        await this.loadSinglePlugin(pluginSpec, context);
+      } catch (err) {
+        logger.warn(`[Architect Plugin] Failed to load plugin '${pluginSpec}': ${(err as Error).message}`);
+      }
+    }
+  }
+
+  private async loadSinglePlugin(pluginSpec: string, context: PluginContext): Promise<void> {
+    // 1. Resolve path (could be relative to project or node_modules)
+    let pluginPath = pluginSpec;
+    
+    // If it starts with ./ or ../ we assume it's relative to the target project
+    if (pluginSpec.startsWith('./') || pluginSpec.startsWith('../')) {
+      pluginPath = path.resolve(this.projectPath, pluginSpec);
+    }
+
+    // Verify file exists if we are resolving a local JS file to avoid unhelpful stack traces
+    if (!pluginSpec.startsWith('@') && !pluginSpec.match(/^[a-z0-9_-]+$/i)) {
+      if (!fs.existsSync(pluginPath)) {
+        throw new Error(`File not found at ${pluginPath}`);
+      }
+      
+      // Node 20+ ESM dynamic imports need absolute file:// URIs on Windows
+      if (process.platform === 'win32') {
+        pluginPath = `file://${pluginPath.replace(/\\/g, '/')}`;
+      }
+    }
+
+    // 2. Load the module using dynamic import
+    const pluginModule = await import(pluginPath);
+    
+    // 3. Extract default export mapping
+    const plugin: ArchitectPlugin = pluginModule.default || pluginModule;
+    
+    if (!plugin || typeof plugin !== 'object') {
+      throw new Error(`Plugin must export an 'ArchitectPlugin' object as default.`);
+    }
+
+    // 4. Register hooks
+    if (typeof plugin.detectAntiPatterns === 'function') {
+      // Wrap the detector so it automatically receives the PluginContext
+      const wrappedDetector: CustomAntiPatternDetector = async (fileTree, deps) => {
+        return plugin.detectAntiPatterns!(fileTree, deps, context);
+      };
+      
+      this.customDetectors.push(wrappedDetector);
+      logger.info(`[Architect Plugin] Registered Custom Rules from: ${plugin.name || pluginSpec}`);
+    }
+  }
+}

package/src/core/project-summarizer.ts

@@ -0,0 +1,42 @@
+import { AnalysisReport } from './types/core.js';
+import { ProjectSummary } from './types/summarizer.js';
+
+import { PackageReader } from './summarizer/package-reader.js';
+import { ReadmeReader } from './summarizer/readme-reader.js';
+import { KeywordExtractor } from './summarizer/keyword-extractor.js';
+import { PurposeInferrer } from './summarizer/purpose-inferrer.js';
+import { ModuleInferrer } from './summarizer/module-inferrer.js';
+
+/**
+ * ProjectSummarizer — infers what a project does from its metadata,
+ * structure, README, package.json, and file naming conventions.
+ *
+ * Refactored via Facade pattern in v5.0.0
+ */
+export class ProjectSummarizer {
+  private packageReader = new PackageReader();
+  private readmeReader = new ReadmeReader();
+  private keywordExtractor = new KeywordExtractor();
+  private purposeInferrer = new PurposeInferrer();
+  private moduleInferrer = new ModuleInferrer();
+
+  summarize(projectPath: string, report: AnalysisReport): ProjectSummary {
+    const packageInfo = this.packageReader.readPackageJson(projectPath);
+    const readmeContent = this.readmeReader.readReadme(projectPath);
+    const modules = this.moduleInferrer.inferModules(report, projectPath);
+    const entryPoints = this.purposeInferrer.findEntryPoints(report, projectPath);
+    const keywords = this.keywordExtractor.extractKeywords(packageInfo, readmeContent, modules, report);
+    const techStack = this.purposeInferrer.buildTechStack(report, packageInfo);
+    const description = this.purposeInferrer.buildDescription(packageInfo, readmeContent, report);
+    const purpose = this.purposeInferrer.inferPurpose(keywords, modules, report);
+
+    return {
+      description,
+      purpose,
+      modules,
+      techStack,
+      entryPoints,
+      keywords,
+    };
+  }
+}

package/src/core/refactor-engine.ts

@@ -0,0 +1,112 @@
+// import { readFileSync } from 'fs';
+// import { basename, dirname, join, relative } from 'path';
+import { AnalysisReport } from './types/core.js';
+import { RefactoringPlan, RefactorStep, RefactorRule} from './types/rules.js';
+
+// ── Tier 1 Rules ──
+import { HubSplitterRule } from './rules/hub-splitter.js';
+import { BarrelOptimizerRule } from './rules/barrel-optimizer.js';
+import { ImportOrganizerRule } from './rules/import-organizer.js';
+import { ModuleGrouperRule } from './rules/module-grouper.js';
+import { DeadCodeDetectorRule } from './rules/dead-code-detector.js';
+
+/**
+ * Refactoring Engine v2.0
+ * Orchestrates Tier 1 (rule-based) and Tier 2 (AST) refactoring rules.
+ */
+export class RefactorEngine {
+  private rules: RefactorRule[];
+
+  constructor() {
+    this.rules = [
+      // Tier 1: Rule Engine (pattern matching)
+      new HubSplitterRule(),
+      new BarrelOptimizerRule(),
+      new ImportOrganizerRule(),
+      new ModuleGrouperRule(),
+      new DeadCodeDetectorRule(),
+    ];
+  }
+
+  /**
+   * Analyze a project and generate a refactoring plan.
+   */
+  analyze(report: AnalysisReport, projectPath: string): RefactoringPlan {
+    const allSteps: RefactorStep[] = [];
+    let stepId = 1;
+
+    // Run each rule
+    for (const rule of this.rules) {
+      const steps = rule.analyze(report, projectPath);
+      for (const step of steps) {
+        step.id = stepId++;
+        allSteps.push(step);
+      }
+    }
+
+    // Sort by priority
+    const priorityOrder: Record<string, number> = {
+      CRITICAL: 0,
+      HIGH: 1,
+      MEDIUM: 2,
+      LOW: 3,
+    };
+    allSteps.sort((a, b) => priorityOrder[a.priority] - priorityOrder[b.priority]);
+
+    // Re-number after sorting
+    allSteps.forEach((s, i) => (s.id = i + 1));
+
+    // Calculate total operations
+    const totalOperations = allSteps.reduce(
+      (sum, s) => sum + s.operations.length,
+      0
+    );
+
+    // Estimate score after refactoring
+    const estimatedScoreAfter = this.estimateScoreAfter(report, allSteps);
+
+    return {
+      timestamp: new Date().toISOString(),
+      projectPath,
+      currentScore: report.score,
+      estimatedScoreAfter,
+      steps: allSteps,
+      totalOperations,
+      tier1Steps: allSteps.filter((s) => s.tier === 1).length,
+      tier2Steps: allSteps.filter((s) => s.tier === 2).length,
+    };
+  }
+
+  /**
+   * Estimates the architecture score after applying all refactoring steps.
+   */
+  private estimateScoreAfter(
+    report: AnalysisReport,
+    steps: RefactorStep[]
+  ): { overall: number; breakdown: Record<string, number> } {
+    const breakdown = { ...report.score.breakdown };
+
+    for (const step of steps) {
+      for (const impact of step.scoreImpact) {
+        if (impact.metric in breakdown) {
+          // Use estimated after value, capped at 95
+          const key = impact.metric as keyof typeof breakdown;
+          breakdown[key] = Math.min(95, Math.max(breakdown[key], impact.after));
+        }
+      }
+    }
+
+    // Recalculate overall with same weights
+    const overall = Math.round(
+      breakdown.modularity * 0.4 +
+        breakdown.coupling * 0.25 +
+        breakdown.cohesion * 0.2 +
+        breakdown.layering * 0.15
+    );
+
+    return {
+      overall: Math.min(100, overall),
+      breakdown,
+    };
+  }
+}

package/src/core/rules/barrel-optimizer.ts

@@ -0,0 +1,99 @@
+import { basename, dirname } from 'path';
+import { AnalysisReport } from '../types/core.js';
+import { RefactorRule, RefactorStep, FileOperation } from '../types/rules.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) },
+          ],
+          aiPrompt: `Analyze the barrel file \`${barrel}\` which re-exports ${outgoing.length} modules. This is creating a "Shotgun Surgery" risk.\nPlease optimize it by:\n1. Removing wildcard exports (e.g., \`export *\`) if any.\n2. Only re-exporting the public API interfaces/classes meant for consumers outside this module.\n3. Updating consumers (${incoming.map(i => basename(i.from)).join(', ')}) to import from the specific files directly instead of passing through this barrel file where appropriate.`,
+        });
+      }
+    }
+
+    return steps;
+  }
+}

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

@@ -0,0 +1,134 @@
+import { basename } from 'path';
+import { AnalysisReport } from '../types/core.js';
+import { RefactorRule, RefactorStep, FileOperation } from '../types/rules.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) },
+        ],
+        aiPrompt: `Analyze the following files: ${orphans.map(f => `\`${f}\``).join(', ')}.\nThese files currently have zero incoming dependencies across the architecture, meaning they might be dead code.\nPlease review them:\n1. If they are unused, explicitly delete them to shrink the blast radius.\n2. If they are entry points that the Architect missed, add them to the ignore list or document their usage.\n3. Make sure to remove any vestigial exports or imports pointing to them from the rest of the codebase.`,
+      });
+    }
+
+    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;
+  }
+}