@girardelli/architect 5.0.0 → 8.1.0

package/src/analyzers/temporal-scorer.ts

@@ -1,227 +0,0 @@
-/**
- * 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 './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/anti-patterns.ts

@@ -1,287 +0,0 @@
-import { readFileSync } from 'fs';
-import { AntiPattern, FileNode, ArchitectConfig } from './types.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/',
-  ];
-
-  constructor(config: ArchitectConfig) {
-    this.config = config;
-    this.dependencyGraph = new Map();
-  }
-
-  /**
-   * 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)
-    );
-  }
-
-  detect(
-    fileTree: FileNode,
-    dependencies: Map<string, Set<string>>
-  ): 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));
-
-    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 || 500;
-    const methodThreshold =
-      this.config.antiPatterns?.godClass?.methodsThreshold || 10;
-
-    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');
-
-        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 || 8;
-
-    for (const [file, dependents] of dependencies) {
-      // Only report for project files
-      if (!this.isProjectFile(file)) 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);
-      }
-    }
-  }
-}