@girardelli/architect-core 8.1.0

package/src/core/analyzers/temporal-scorer.ts

@@ -0,0 +1,227 @@
+/**
+ * Temporal Score Dimension — Adds time-series awareness to architecture scoring
+ *
+ * Combines current static score with historical velocity to produce:
+ * - Trend per module (improving / stable / degrading)
+ * - Temporal risk score (static score penalized by negative velocity)
+ * - Projected score in N weeks
+ *
+ * @author Camilo Girardelli — Girardelli Tecnologia
+ * @license MIT
+ */
+
+import type {
+  ModuleHistory,
+  VelocityVector,
+  GitHistoryReport,
+} from '../../infrastructure/git-history.js';
+
+// ═══════════════════════════════════════════════════════════════
+// TYPES
+// ═══════════════════════════════════════════════════════════════
+
+export type Trend = 'improving' | 'stable' | 'degrading';
+
+export interface TemporalScore {
+  /** Module or file path */
+  module: string;
+  /** Current static score (from ArchitectureScorer) */
+  staticScore: number;
+  /** Temporal-adjusted score (penalizes degrading trends) */
+  temporalScore: number;
+  /** Direction of change */
+  trend: Trend;
+  /** Projected score in projectionWeeks */
+  projectedScore: number;
+  /** Confidence in the projection (0-1) */
+  projectionConfidence: number;
+  /** Weeks used for projection */
+  projectionWeeks: number;
+  /** Risk level derived from temporal analysis */
+  riskLevel: 'low' | 'medium' | 'high' | 'critical';
+  /** Velocity data */
+  velocity: VelocityVector;
+}
+
+export interface TemporalReport {
+  projectPath: string;
+  analyzedAt: string;
+  overallTrend: Trend;
+  overallTemporalScore: number;
+  modules: TemporalScore[];
+  degradingModules: TemporalScore[];
+  improvingModules: TemporalScore[];
+}
+
+export interface TemporalScorerConfig {
+  /** Weeks ahead to project (default: 12) */
+  projectionWeeks?: number;
+  /** Weight of churn trend in temporal penalty (0-1, default: 0.6) */
+  churnWeight?: number;
+  /** Weight of commit acceleration in temporal penalty (0-1, default: 0.4) */
+  commitWeight?: number;
+  /** Threshold for trend classification: accelerating if > threshold % */
+  acceleratingThreshold?: number;
+  /** Threshold for trend classification: decelerating if < -threshold % */
+  deceleratingThreshold?: number;
+}
+
+const DEFAULT_CONFIG: Required<TemporalScorerConfig> = {
+  projectionWeeks: 12,
+  churnWeight: 0.6,
+  commitWeight: 0.4,
+  acceleratingThreshold: 15,
+  deceleratingThreshold: -15,
+};
+
+// ═══════════════════════════════════════════════════════════════
+// TEMPORAL SCORER
+// ═══════════════════════════════════════════════════════════════
+
+export class TemporalScorer {
+  private config: Required<TemporalScorerConfig>;
+
+  constructor(config?: TemporalScorerConfig) {
+    this.config = { ...DEFAULT_CONFIG, ...config };
+  }
+
+  /**
+   * Score modules temporally using git history + static scores.
+   *
+   * @param gitReport - Output from GitHistoryAnalyzer
+   * @param staticScores - Map of modulePath → static score (0-100)
+   */
+  score(
+    gitReport: GitHistoryReport,
+    staticScores: Map<string, number>,
+  ): TemporalReport {
+    const modules: TemporalScore[] = [];
+
+    for (const moduleHistory of gitReport.modules) {
+      const staticScore = staticScores.get(moduleHistory.modulePath)
+        ?? this.inferStaticScore(moduleHistory);
+
+      const ts = this.scoreModule(moduleHistory, staticScore);
+      modules.push(ts);
+    }
+
+    // Sort by risk (worst first)
+    modules.sort((a, b) => a.temporalScore - b.temporalScore);
+
+    const degrading = modules.filter(m => m.trend === 'degrading');
+    const improving = modules.filter(m => m.trend === 'improving');
+
+    const overallTrend = this.classifyOverallTrend(modules);
+    const overallScore = modules.length > 0
+      ? Math.round(modules.reduce((s, m) => s + m.temporalScore, 0) / modules.length)
+      : 0;
+
+    return {
+      projectPath: gitReport.projectPath,
+      analyzedAt: new Date().toISOString(),
+      overallTrend: overallTrend,
+      overallTemporalScore: overallScore,
+      modules,
+      degradingModules: degrading,
+      improvingModules: improving,
+    };
+  }
+
+  private scoreModule(module: ModuleHistory, staticScore: number): TemporalScore {
+    const velocity = module.velocityVector;
+
+    // Calculate temporal penalty based on velocity
+    const churnPenalty = velocity.churnTrend > 0
+      ? velocity.churnTrend * this.config.churnWeight * 0.3  // 30% impact per 100% churn increase
+      : velocity.churnTrend * this.config.churnWeight * 0.1; // 10% bonus per 100% churn decrease
+
+    const commitPenalty = velocity.commitAcceleration > 20
+      ? (velocity.commitAcceleration - 20) * this.config.commitWeight * 0.2  // penalty for excessive churn
+      : 0;
+
+    const totalPenalty = Math.max(-20, Math.min(30, churnPenalty + commitPenalty));
+    const temporalScore = Math.max(0, Math.min(100, Math.round(staticScore - totalPenalty)));
+
+    // Trend classification
+    const trend = this.classifyTrend(velocity);
+
+    // Linear projection
+    const weeklyDelta = totalPenalty / Math.max(this.config.projectionWeeks, 1);
+    const projectedScore = Math.max(0, Math.min(100,
+      Math.round(temporalScore - (weeklyDelta * this.config.projectionWeeks))
+    ));
+
+    // Confidence decreases with projection distance and instability
+    const instability = Math.abs(velocity.churnTrend) + Math.abs(velocity.commitAcceleration);
+    const projectionConfidence = Math.max(0.1, Math.min(1,
+      1 - (instability / 200) - (this.config.projectionWeeks / 52)
+    ));
+
+    const riskLevel = this.classifyRisk(temporalScore, trend, module.busFactor);
+
+    return {
+      module: module.modulePath,
+      staticScore,
+      temporalScore,
+      trend,
+      projectedScore,
+      projectionConfidence: Math.round(projectionConfidence * 100) / 100,
+      projectionWeeks: this.config.projectionWeeks,
+      riskLevel,
+      velocity,
+    };
+  }
+
+  private classifyTrend(velocity: VelocityVector): Trend {
+    // Degrading: churn increasing significantly or commit acceleration very high
+    if (velocity.churnTrend > 30 || velocity.commitAcceleration > 50) {
+      return 'degrading';
+    }
+    // Improving: churn decreasing and stable or decelerating
+    if (velocity.churnTrend < -10 && velocity.direction !== 'accelerating') {
+      return 'improving';
+    }
+    return 'stable';
+  }
+
+  private classifyRisk(
+    temporalScore: number,
+    trend: Trend,
+    busFactor: number,
+  ): TemporalScore['riskLevel'] {
+    if (temporalScore < 30 || (temporalScore < 50 && trend === 'degrading')) {
+      return 'critical';
+    }
+    if (temporalScore < 50 || (trend === 'degrading' && busFactor <= 1)) {
+      return 'high';
+    }
+    if (temporalScore < 70 || trend === 'degrading') {
+      return 'medium';
+    }
+    return 'low';
+  }
+
+  private classifyOverallTrend(modules: TemporalScore[]): Trend {
+    if (modules.length === 0) return 'stable';
+
+    const degrading = modules.filter(m => m.trend === 'degrading').length;
+    const improving = modules.filter(m => m.trend === 'improving').length;
+
+    const degradingRatio = degrading / modules.length;
+    const improvingRatio = improving / modules.length;
+
+    if (degradingRatio > 0.3) return 'degrading';
+    if (improvingRatio > 0.3) return 'improving';
+    return 'stable';
+  }
+
+  /** Infer a static score when none is provided (based on churn metrics) */
+  private inferStaticScore(module: ModuleHistory): number {
+    const avgChurn = module.aggregateChurn / Math.max(module.aggregateCommits, 1);
+    if (avgChurn < 20) return 85;
+    if (avgChurn < 50) return 75;
+    if (avgChurn < 100) return 65;
+    if (avgChurn < 200) return 50;
+    return 35;
+  }
+}

package/src/core/anti-patterns.ts

@@ -0,0 +1,324 @@
+import { readFileSync } from 'fs';
+import { AntiPattern, ArchitectConfig } from './types/core.js';
+import { FileNode } from './types/infrastructure.js';
+import type { CustomAntiPatternDetector, PluginContext } from './types/plugin.js';
+import { logger } from '../infrastructure/logger.js';
+
+export class AntiPatternDetector {
+  private config: ArchitectConfig;
+  private dependencyGraph: Map<string, Set<string>>;
+
+  /** Paths that indicate third-party or build artifacts — never report anti-patterns here */
+  private static readonly EXCLUDED_PATH_SEGMENTS = [
+    'node_modules', '/dist/', '/build/', '/coverage/',
+    '/.next/', '/venv/', '/__pycache__/', '/target/',
+  ];
+
+  private customDetectors: CustomAntiPatternDetector[] = [];
+  private pluginContext?: PluginContext;
+
+  constructor(config: ArchitectConfig) {
+    this.config = config;
+    this.dependencyGraph = new Map();
+  }
+
+  public setCustomDetectors(detectors: CustomAntiPatternDetector[]) {
+    this.customDetectors = detectors;
+  }
+
+  /**
+   * Check if a file path belongs to the project's own source code.
+   * Returns false for node_modules, dist, build artifacts, etc.
+   */
+  private isProjectFile(filePath: string): boolean {
+    const normalized = filePath.replace(/\\/g, '/');
+    return !AntiPatternDetector.EXCLUDED_PATH_SEGMENTS.some(seg =>
+      normalized.includes(seg)
+    );
+  }
+
+  async detect(
+    fileTree: FileNode,
+    dependencies: Map<string, Set<string>>
+  ): Promise<AntiPattern[]> {
+    this.dependencyGraph = dependencies;
+    const patterns: AntiPattern[] = [];
+
+    patterns.push(...this.detectGodClasses(fileTree));
+    patterns.push(...this.detectCircularDependencies());
+    patterns.push(...this.detectLeakyAbstractions(fileTree));
+    patterns.push(...this.detectFeatureEnvy(fileTree, dependencies));
+    patterns.push(...this.detectShotgunSurgery(dependencies));
+
+    // Execute Enterprise Custom Plugin Detectors
+    const context: PluginContext = this.pluginContext || {
+      config: this.config,
+      projectPath: process.cwd() // Fallback if not injected explicitly
+    };
+
+    for (const detector of this.customDetectors) {
+      try {
+        const customPatterns = await detector(fileTree, dependencies, context);
+        if (Array.isArray(customPatterns)) {
+          patterns.push(...customPatterns);
+        }
+      } catch (err) {
+        logger.warn(`[Architect Plugin] A custom rule engine failed during detection: ${(err as Error).message}`);
+      }
+    }
+
+    return patterns.sort((a, b) => {
+      const severityOrder: Record<string, number> = {
+        CRITICAL: 0,
+        HIGH: 1,
+        MEDIUM: 2,
+        LOW: 3,
+      };
+      return severityOrder[a.severity] - severityOrder[b.severity];
+    });
+  }
+
+  private detectGodClasses(node: FileNode): AntiPattern[] {
+    const patterns: AntiPattern[] = [];
+    const threshold =
+      this.config.antiPatterns?.godClass?.linesThreshold || 800; // Increased to 800 for OSS realities
+    const methodThreshold =
+      this.config.antiPatterns?.godClass?.methodsThreshold || 20; // Increased to 20
+
+    this.walkFileTree(node, (file) => {
+      if (file.type === 'file' && (file.lines || 0) > threshold && this.isProjectFile(file.path)) {
+        const methods = this.countMethods(file.path);
+        if (methods > methodThreshold) {
+          patterns.push({
+            name: 'God Class',
+            severity: 'CRITICAL',
+            location: file.path,
+            description: `Class with ${file.lines} lines and ${methods} methods violates single responsibility principle`,
+            suggestion:
+              'Consider splitting into smaller, focused classes with specific responsibilities',
+            metrics: {
+              lines: file.lines || 0,
+              methods,
+            },
+          });
+        }
+      }
+    });
+
+    return patterns;
+  }
+
+  private detectCircularDependencies(): AntiPattern[] {
+    const patterns: AntiPattern[] = [];
+    const visited = new Set<string>();
+    const recursionStack = new Set<string>();
+
+    for (const file of this.dependencyGraph.keys()) {
+      // Only check cycles starting from project files
+      if (!this.isProjectFile(file)) continue;
+
+      if (!visited.has(file)) {
+        const cycle = this.findCycle(file, visited, recursionStack);
+        if (cycle && cycle.every(f => this.isProjectFile(f))) {
+          patterns.push({
+            name: 'Circular Dependency',
+            severity: 'HIGH',
+            location: cycle.join(' -> '),
+            description: `Circular dependency detected: ${cycle.join(' -> ')}`,
+            suggestion:
+              'Refactor code to break the circular dependency using dependency injection or intermediate abstractions',
+            affectedFiles: cycle,
+          });
+        }
+      }
+    }
+
+    return patterns;
+  }
+
+  private findCycle(
+    node: string,
+    visited: Set<string>,
+    recursionStack: Set<string>
+  ): string[] | null {
+    visited.add(node);
+    recursionStack.add(node);
+
+    const neighbors = this.dependencyGraph.get(node) || new Set();
+    for (const neighbor of neighbors) {
+      if (!visited.has(neighbor)) {
+        const cycle = this.findCycle(neighbor, visited, recursionStack);
+        if (cycle) {
+          cycle.unshift(node);
+          return cycle;
+        }
+      } else if (recursionStack.has(neighbor)) {
+        return [node, neighbor];
+      }
+    }
+
+    recursionStack.delete(node);
+    return null;
+  }
+
+  private detectLeakyAbstractions(node: FileNode): AntiPattern[] {
+    const patterns: AntiPattern[] = [];
+
+    this.walkFileTree(node, (file) => {
+      if (file.type === 'file' && this.isProjectFile(file.path)) {
+        const internalExports = this.countInternalExports(file.path);
+        if (internalExports > 5) {
+          patterns.push({
+            name: 'Leaky Abstraction',
+            severity: 'MEDIUM',
+            location: file.path,
+            description: `Exports ${internalExports} internal types that should be private`,
+            suggestion:
+              'Use private/internal access modifiers and facade patterns to hide implementation details',
+            metrics: {
+              exportedInternalTypes: internalExports,
+            },
+          });
+        }
+      }
+    });
+
+    return patterns;
+  }
+
+  private detectFeatureEnvy(
+    node: FileNode,
+    dependencies: Map<string, Set<string>>
+  ): AntiPattern[] {
+    const patterns: AntiPattern[] = [];
+
+    this.walkFileTree(node, (file) => {
+      if (file.type === 'file' && this.isProjectFile(file.path)) {
+        const externalMethodCalls = (dependencies.get(file.path) || new Set())
+          .size;
+        const internalMethods = this.countMethods(file.path);
+        const name = file.name.toLowerCase();
+
+        // Skip infrastructure files where external deps are by design
+        const isInfraFile =
+          name.endsWith('.module.ts') ||
+          name.endsWith('.dto.ts') ||
+          name.endsWith('.entity.ts') ||
+          name.endsWith('.guard.ts') ||
+          name.endsWith('.pipe.ts') ||
+          name.endsWith('.interceptor.ts') ||
+          name.endsWith('.filter.ts') ||
+          name.endsWith('.decorator.ts') ||
+          name.endsWith('.spec.ts') ||
+          name.endsWith('.test.ts') ||
+          name.endsWith('-engine.ts') ||
+          name.endsWith('-enricher.ts') ||
+          name.endsWith('-detector.ts') ||
+          file.path.includes('/scripts/');
+
+        if (!isInfraFile && internalMethods > 0 && externalMethodCalls > internalMethods * 3) {
+          patterns.push({
+            name: 'Feature Envy',
+            severity: 'MEDIUM',
+            location: file.path,
+            description: `Uses more external methods (${externalMethodCalls}) than internal methods (${internalMethods})`,
+            suggestion:
+              'Move functionality closer to where it is used or extract to shared utility',
+            metrics: {
+              externalMethodCalls,
+              internalMethods,
+            },
+          });
+        }
+      }
+    });
+
+    return patterns;
+  }
+
+  private detectShotgunSurgery(
+    dependencies: Map<string, Set<string>>
+  ): AntiPattern[] {
+    const patterns: AntiPattern[] = [];
+    const threshold =
+      this.config.antiPatterns?.shotgunSurgery?.changePropagationThreshold ||
+      Math.max(15, Math.ceil(this.dependencyGraph.size * 0.02));
+
+    for (const [file, dependents] of dependencies) {
+      // Only report for project files
+      if (!this.isProjectFile(file)) continue;
+
+      const fileName = file.split('/').pop() || '';
+      const isBaseFile = ['index.ts', 'index.js', 'types.ts', 'logger.ts', 'config.ts', 'architect.ts', 'constants.ts', 'interfaces.ts', 'globals.ts'].includes(fileName) ||
+                         fileName.endsWith('.interface.ts') || fileName.endsWith('.constants.ts') || fileName.endsWith('.type.ts') || fileName.endsWith('.model.ts') || fileName.endsWith('.enum.ts');
+      const isExcludedDir = file.includes('tests/') || file.includes('scripts/') || file.includes('adapters/') || file.includes('agent-generator/');
+      if (isBaseFile || isExcludedDir) continue;
+
+      if (dependents.size >= threshold) {
+        patterns.push({
+          name: 'Shotgun Surgery',
+          severity: 'HIGH',
+          location: file,
+          description: `Changes to this file likely require modifications in ${dependents.size} other files`,
+          suggestion:
+            'Refactor to reduce coupling and consolidate related functionality into modules',
+          affectedFiles: Array.from(dependents).filter(f => this.isProjectFile(f)),
+          metrics: {
+            dependentFileCount: dependents.size,
+          },
+        });
+      }
+    }
+
+    return patterns;
+  }
+
+  private countMethods(filePath: string): number {
+    try {
+      const content = readFileSync(filePath, 'utf-8');
+      const methodRegex = /(?:async\s+)?(?:function|public|private|protected|static)\s+\w+\s*\(/g;
+      const arrowMethodRegex = /(?:readonly\s+)?\w+\s*=\s*(?:async\s+)?\(/g;
+      const matches = content.match(methodRegex);
+      const arrowMatches = content.match(arrowMethodRegex);
+      return (matches ? matches.length : 0) + (arrowMatches ? arrowMatches.length : 0);
+    } catch {
+      return 0;
+    }
+  }
+
+  private countInternalExports(filePath: string): number {
+    try {
+      const content = readFileSync(filePath, 'utf-8');
+      const internalTypes = [
+        '_',
+        'Internal',
+        'Private',
+        'Impl',
+        'Detail',
+      ];
+      let count = 0;
+
+      for (const type of internalTypes) {
+        const regex = new RegExp(`export\\s+\\w*${type}\\w*`, 'g');
+        const matches = content.match(regex);
+        count += matches ? matches.length : 0;
+      }
+
+      return count;
+    } catch {
+      return 0;
+    }
+  }
+
+  private walkFileTree(
+    node: FileNode,
+    callback: (node: FileNode) => void
+  ): void {
+    callback(node);
+    if (node.children) {
+      for (const child of node.children) {
+        this.walkFileTree(child, callback);
+      }
+    }
+  }
+}

package/src/core/ast/ast-parser.interface.ts

@@ -0,0 +1,21 @@
+/**
+ * Interface for Abstract Syntax Tree-based code parsers.
+ * Replaces regex-based static analysis to improve deterministic import resolution
+ * without compiling the project.
+ */
+export interface ASTParser {
+  /**
+   * Initializes the parser engine and loads required language parsers.
+   * Can throw an error if the native bindings fail.
+   */
+  initialize(): Promise<void>;
+
+  /**
+   * Parses the file content and extracts the imported/required module paths.
+   *
+   * @param content Raw file string content
+   * @param filePath Absolute path to the file
+   * @returns List of internal dependencies (import paths)
+   */
+  parseImports(content: string, filePath: string): string[];
+}

package/src/core/ast/path-resolver.ts

@@ -0,0 +1,61 @@
+import fs from 'fs';
+import path from 'path';
+
+export class PathResolver {
+  private projectRoot: string;
+  private tsconfigPaths: Record<string, string[]> = {};
+  private initialized = false;
+
+  constructor(projectRoot: string) {
+    this.projectRoot = projectRoot;
+  }
+
+  initialize(): void {
+    if (this.initialized) return;
+    try {
+      this.loadTsConfig();
+      // Em futuruos iteratives, carregar pyproject.toml e go.mod aliases
+      this.initialized = true;
+    } catch {
+      // Falhas na leitura de config não devem quebrar o parser
+    }
+  }
+
+  private loadTsConfig(): void {
+    const tsconfigPath = path.join(this.projectRoot, 'tsconfig.json');
+    if (fs.existsSync(tsconfigPath)) {
+      const content = fs.readFileSync(tsconfigPath, 'utf8');
+      
+      // Limpeza brutal de comentários JS/TS do JSON
+      const cleanContent = content.replace(new RegExp('//.*$', 'gm'), '').replace(new RegExp('/\\\\*[\\\\s\\\\S]*?\\\\*/', 'g'), '');
+      const parsed = JSON.parse(cleanContent);
+      
+      if (parsed?.compilerOptions?.paths) {
+        this.tsconfigPaths = parsed.compilerOptions.paths;
+      }
+    }
+  }
+
+  /**
+   * Resolve `importPath` baseando-se no dicionário de Aliases.
+   * Ex: "@/" mapeia para "src/"
+   */
+  resolveAlias(importPath: string): string {
+    this.initialize();
+
+    for (const alias in this.tsconfigPaths) {
+      // Ex: alias = "@/components/*", targets = ["src/components/*"]
+      const cleanAlias = alias.replace('/*', '');
+      
+      if (importPath.startsWith(cleanAlias)) {
+        const targets = this.tsconfigPaths[alias];
+        if (targets && targets.length > 0) {
+          const cleanTarget = targets[0].replace('/*', '');
+          return importPath.replace(cleanAlias, cleanTarget);
+        }
+      }
+    }
+
+    return importPath;
+  }
+}