tech-debt-score 0.1.5 → 0.1.6

package/src/cli/index.ts

@@ -1,81 +0,0 @@
-#!/usr/bin/env node
-/**
- * CLI Entry Point
- * Command-line interface for tech-debt-score
- * 
- * NO BUSINESS LOGIC HERE - just argument parsing and delegation
- */
-
-import { analyzeCommand } from './commands/analyze.js';
-
-async function main() {
-  const args = process.argv.slice(2);
-  
-  if (args.includes('--help') || args.includes('-h')) {
-    printHelp();
-    process.exit(0);
-  }
-
-  // Parse arguments
-  let rootPath = process.cwd();
-  let jsonOutputPath: string | undefined;
-
-  for (let i = 0; i < args.length; i++) {
-    const arg = args[i];
-    if (!arg) continue;
-
-    if (arg === '--json' || arg === '-j') {
-      const nextArg = args[i + 1];
-      if (nextArg && !nextArg.startsWith('-')) {
-        jsonOutputPath = nextArg;
-        i++; // Skip next arg
-      }
-    } else if (!arg.startsWith('-')) {
-      rootPath = arg;
-    }
-  }
-  
-  try {
-    await analyzeCommand(rootPath, jsonOutputPath);
-    process.exit(0);
-  } catch (error) {
-    console.error('❌ Analysis failed:', error instanceof Error ? error.message : error);
-    process.exit(1);
-  }
-}
-
-function printHelp() {
-  console.log(`
-┌─────────────────────────────────────────────┐
-│  tech-debt-score - Quantify Technical Debt  │
-│  Built by developers, for developers        │
-└─────────────────────────────────────────────┘
-
-Usage:
-  tech-debt-score [path]
-
-Arguments:
-  path              Path to analyze (default: current directory)
-
-Options:
-  -h, --help        Show this help message
-
-Examples:
-  tech-debt-score                    # Analyze current directory
-  tech-debt-score ./my-project       # Analyze specific directory
-  tech-debt-score /path/to/code      # Analyze absolute path
-
-Options:
-  -h, --help            Show this help message
-  -j, --json <file>     Output JSON report to specific file
-
-
-For more information, visit:
-https://github.com/panduken/tech-debt-score
-  `);
-}
-
-// Run if executed directly
-if (import.meta.url === `file://${process.argv[1]}`) {
-  main();
-}

package/src/domain/entities/Finding.ts

@@ -1,79 +0,0 @@
-/**
- * Domain Entity: Finding
- * Represents an identified issue or code smell in the codebase
- */
-
-import type { SourceLocation, Severity } from '../../shared/types.js';
-
-export interface Finding {
-  /**
-   * ID of the rule that generated this finding
-   */
-  ruleId: string;
-
-  /**
-   * Severity level of the issue
-   */
-  severity: Severity;
-
-  /**
-   * Human-readable message describing the issue
-   */
-  message: string;
-
-  /**
-   * File path where the issue was found
-   */
-  filePath: string;
-
-  /**
-   * Optional exact location in the source code
-   */
-  location?: SourceLocation;
-
-  /**
-   * Optional suggestion for fixing the issue
-   */
-  suggestion?: string;
-}
-
-export class FindingBuilder {
-  private finding: Partial<Finding> = {};
-
-  withRuleId(ruleId: string): this {
-    this.finding.ruleId = ruleId;
-    return this;
-  }
-
-  withSeverity(severity: Severity): this {
-    this.finding.severity = severity;
-    return this;
-  }
-
-  withMessage(message: string): this {
-    this.finding.message = message;
-    return this;
-  }
-
-  withFilePath(filePath: string): this {
-    this.finding.filePath = filePath;
-    return this;
-  }
-
-  withLocation(location: SourceLocation): this {
-    this.finding.location = location;
-    return this;
-  }
-
-  withSuggestion(suggestion: string): this {
-    this.finding.suggestion = suggestion;
-    return this;
-  }
-
-  build(): Finding {
-    if (!this.finding.ruleId || !this.finding.severity || !this.finding.message || !this.finding.filePath) {
-      throw new Error('Finding requires ruleId, severity, message, and filePath');
-    }
-    return this.finding as Finding;
-  }
-}

package/src/domain/entities/Metric.ts

@@ -1,70 +0,0 @@
-/**
- * Domain Entity: Metric
- * Represents a single measurement extracted from code analysis
- */
-
-import type { SourceLocation } from '../../shared/types.js';
-
-export interface Metric {
-  /**
-   * Unique identifier for the metric type
-   * e.g., 'cyclomatic-complexity', 'function-length', 'any-usage'
-   */
-  name: string;
-
-  /**
-   * The measured value
-   */
-  value: number;
-
-  /**
-   * File path where this metric was measured
-   */
-  filePath: string;
-
-  /**
-   * Optional location in the source code
-   */
-  location?: SourceLocation;
-
-  /**
-   * Optional context (e.g., function name, class name)
-   */
-  context?: string;
-}
-
-export class MetricBuilder {
-  private metric: Partial<Metric> = {};
-
-  withName(name: string): this {
-    this.metric.name = name;
-    return this;
-  }
-
-  withValue(value: number): this {
-    this.metric.value = value;
-    return this;
-  }
-
-  withFilePath(filePath: string): this {
-    this.metric.filePath = filePath;
-    return this;
-  }
-
-  withLocation(location: SourceLocation): this {
-    this.metric.location = location;
-    return this;
-  }
-
-  withContext(context: string): this {
-    this.metric.context = context;
-    return this;
-  }
-
-  build(): Metric {
-    if (!this.metric.name || this.metric.value === undefined || !this.metric.filePath) {
-      throw new Error('Metric requires name, value, and filePath');
-    }
-    return this.metric as Metric;
-  }
-}

package/src/domain/entities/Rule.ts

@@ -1,49 +0,0 @@
-/**
- * Domain Entity: Rule
- * Represents an evaluation rule that processes metrics and generates findings
- */
-
-import type { Metric } from './Metric.js';
-import type { Finding } from './Finding.js';
-
-export interface Rule {
-  /**
-   * Unique identifier for this rule
-   */
-  id: string;
-
-  /**
-   * Human-readable name
-   */
-  name: string;
-
-  /**
-   * Description of what this rule evaluates
-   */
-  description: string;
-
-  /**
-   * Evaluate metrics and produce findings
-   */
-  evaluate(metrics: Metric[]): Finding[];
-
-  /**
-   * Calculate a score (0-100) based on findings
-   * where 100 = no issues, 0 = maximum issues
-   */
-  calculateScore(findings: Finding[]): number;
-}
-
-/**
- * Abstract base class for rules
- */
-export abstract class BaseRule implements Rule {
-  constructor(
-    public readonly id: string,
-    public readonly name: string,
-    public readonly description: string
-  ) {}
-
-  abstract evaluate(metrics: Metric[]): Finding[];
-  abstract calculateScore(findings: Finding[]): number;
-}

package/src/domain/entities/Score.ts

@@ -1,94 +0,0 @@
-/**
- * Domain Entity: Score
- * Represents the technical debt score and category breakdowns
- */
-
-export interface CategoryScore {
-  /**
-   * Category name (e.g., 'Complexity', 'Size', 'Type Safety')
-   */
-  name: string;
-
-  /**
-   * Score for this category (0-100, where 100 = no debt)
-   */
-  score: number;
-
-  /**
-   * Weight of this category in the overall score (0-1)
-   */
-  weight: number;
-
-  /**
-   * Optional description of what this category measures
-   */
-  description?: string;
-}
-
-export interface Score {
-  /**
-   * Overall technical debt score (0-100, where 100 = no debt)
-   */
-  overall: number;
-
-  /**
-   * Breakdown by category
-   */
-  categories: CategoryScore[];
-
-  /**
-   * When this score was calculated
-   */
-  timestamp: Date;
-
-  /**
-   * Optional metadata about the analysis
-   */
-  metadata?: {
-    filesAnalyzed: number;
-    totalMetrics: number;
-    totalFindings: number;
-  };
-}
-
-export class ScoreCalculator {
-  /**
-   * Calculate overall score from category scores
-   * 
-   * Formula: Σ(category_score × category_weight)
-   */
-  static calculateOverall(categories: CategoryScore[]): number {
-    // Validate weights sum to 1.0 (or close to it)
-    const totalWeight = categories.reduce((sum, cat) => sum + cat.weight, 0);
-    if (Math.abs(totalWeight - 1.0) > 0.01) {
-      throw new Error(`Category weights must sum to 1.0, got ${totalWeight}`);
-    }
-
-    // Calculate weighted average
-    const weightedSum = categories.reduce(
-      (sum, cat) => sum + (cat.score * cat.weight),
-      0
-    );
-
-    // Round to 2 decimal places
-    return Math.round(weightedSum * 100) / 100;
-  }
-
-  /**
-   * Normalize a raw value to 0-100 scale
-   * 
-   * @param value - The raw value to normalize
-   * @param min - Minimum value (maps to 100)
-   * @param max - Maximum value (maps to 0)
-   * @param invert - If true, higher values = better score
-   */
-  static normalize(value: number, min: number, max: number, invert = false): number {
-    if (value <= min) return invert ? 0 : 100;
-    if (value >= max) return invert ? 100 : 0;
-
-    const normalized = ((value - min) / (max - min)) * 100;
-    const score = invert ? normalized : 100 - normalized;
-
-    return Math.round(score * 100) / 100;
-  }
-}

package/src/domain/index.ts

@@ -1,15 +0,0 @@
-/**
- * Domain Layer - Public API
- * Exports all domain entities and services
- */
-
-// Entities
-export * from './entities/Metric.js';
-export * from './entities/Finding.js';
-export * from './entities/Score.js';
-export * from './entities/Rule.js';
-
-// Rules
-export * from './rules/ComplexityRule.js';
-export * from './rules/SizeRule.js';
-export * from './rules/TypeSafetyRule.js';

package/src/domain/rules/CircularDependencyRule.ts

@@ -1,65 +0,0 @@
-/**
- * Domain Rule: Circular Dependency Rule
- * Detects circular dependencies between modules
- */
-
-import { BaseRule } from '../entities/Rule.js';
-import type { Metric } from '../entities/Metric.js';
-import type { Finding } from '../entities/Finding.js';
-import { FindingBuilder } from '../entities/Finding.js';
-
-export class CircularDependencyRule extends BaseRule {
-  constructor() {
-    super(
-      'circular-dependency',
-      'Circular Dependency Rule',
-      'Detects circular dependencies between modules that can cause maintenance issues'
-    );
-  }
-
-  evaluate(metrics: Metric[]): Finding[] {
-    const findings: Finding[] = [];
-
-    // Find circular dependency metrics
-    const circularDepMetrics = metrics.filter(m => m.name === 'circular-dependency');
-
-    for (const metric of circularDepMetrics) {
-      if (metric.value > 0) {
-        // Extract cycle information from context
-        const cycleLength = metric.value;
-        const severity = cycleLength >= 4 ? 'high' : cycleLength >= 3 ? 'medium' : 'low';
-        
-        findings.push(
-          new FindingBuilder()
-            .withRuleId(this.id)
-            .withSeverity(severity)
-            .withMessage(
-              `Circular dependency detected: ${metric.context || 'module cycle'} (${cycleLength} files in cycle)`
-            )
-            .withFilePath(metric.filePath)
-            .withSuggestion('Refactor to break the circular dependency by introducing interfaces or dependency injection')
-            .build()
-        );
-      }
-    }
-
-    return findings;
-  }
-
-  calculateScore(findings: Finding[]): number {
-    if (findings.length === 0) return 100;
-
-    // Circular dependencies are serious - heavy penalty
-    const penalty = findings.reduce((sum, finding) => {
-      switch (finding.severity) {
-        case 'high': return sum + 20; // Very bad
-        case 'medium': return sum + 12;
-        case 'low': return sum + 6;
-        default: return sum;
-      }
-    }, 0);
-
-    const score = Math.max(0, 100 - penalty);
-    return Math.round(score * 100) / 100;
-  }
-}

package/src/domain/rules/ComplexityRule.ts

@@ -1,88 +0,0 @@
-/**
- * Domain Rule: Complexity Rule
- * Evaluates cyclomatic complexity and nesting depth
- */
-
-import { BaseRule } from '../entities/Rule.js';
-import type { Metric } from '../entities/Metric.js';
-import type { Finding } from '../entities/Finding.js';
-import { FindingBuilder } from '../entities/Finding.js';
-
-export class ComplexityRule extends BaseRule {
-  // Thresholds (configurable in future versions)
-  private readonly COMPLEXITY_THRESHOLD = 10;
-  private readonly NESTING_THRESHOLD = 4;
-
-  constructor() {
-    super(
-      'complexity',
-      'Complexity Rule',
-      'Evaluates cyclomatic complexity and nesting depth to identify overly complex code'
-    );
-  }
-
-  evaluate(metrics: Metric[]): Finding[] {
-    const findings: Finding[] = [];
-
-    // Filter for complexity-related metrics
-    const complexityMetrics = metrics.filter(
-      m => m.name === 'cyclomatic-complexity' || m.name === 'nesting-depth'
-    );
-
-    for (const metric of complexityMetrics) {
-      if (metric.name === 'cyclomatic-complexity' && metric.value > this.COMPLEXITY_THRESHOLD) {
-        const builder = new FindingBuilder()
-          .withRuleId(this.id)
-          .withSeverity(metric.value > 20 ? 'high' : 'medium')
-          .withMessage(
-            `High cyclomatic complexity (${metric.value}) in ${metric.context || 'function'}`
-          )
-          .withFilePath(metric.filePath)
-          .withSuggestion('Consider breaking this function into smaller, more focused functions');
-        
-        if (metric.location) {
-          builder.withLocation(metric.location);
-        }
-        
-        findings.push(builder.build());
-      }
-
-      if (metric.name === 'nesting-depth' && metric.value > this.NESTING_THRESHOLD) {
-        const builder = new FindingBuilder()
-          .withRuleId(this.id)
-          .withSeverity(metric.value > 6 ? 'high' : 'medium')
-          .withMessage(
-            `Deep nesting (${metric.value} levels) in ${metric.context || 'function'}`
-          )
-          .withFilePath(metric.filePath)
-          .withSuggestion('Reduce nesting by using early returns or extracting functions');
-        
-        if (metric.location) {
-          builder.withLocation(metric.location);
-        }
-        
-        findings.push(builder.build());
-      }
-    }
-
-    return findings;
-  }
-
-  calculateScore(findings: Finding[]): number {
-    if (findings.length === 0) return 100;
-
-    // Penalty based on severity
-    const penalty = findings.reduce((sum, finding) => {
-      switch (finding.severity) {
-        case 'high': return sum + 10;
-        case 'medium': return sum + 5;
-        case 'low': return sum + 2;
-        default: return sum;
-      }
-    }, 0);
-
-    // Cap the penalty and invert to get score
-    const score = Math.max(0, 100 - penalty);
-    return Math.round(score * 100) / 100;
-  }
-}

package/src/domain/rules/DuplicationRule.ts

@@ -1,70 +0,0 @@
-/**
- * Domain Rule: Code Duplication Rule
- * Detects duplicate code blocks using token-based similarity
- */
-
-import { BaseRule } from '../entities/Rule.js';
-import type { Metric } from '../entities/Metric.js';
-import type { Finding } from '../entities/Finding.js';
-import { FindingBuilder } from '../entities/Finding.js';
-
-export class DuplicationRule extends BaseRule {
-  // Thresholds
-  private readonly MIN_DUPLICATE_TOKENS = 50; // Minimum tokens to consider as duplication
-  private readonly SIMILARITY_THRESHOLD = 0.95; // 95% similarity
-
-  constructor() {
-    super(
-      'duplication',
-      'Code Duplication Rule',
-      'Detects duplicate or highly similar code blocks across the codebase'
-    );
-  }
-
-  evaluate(metrics: Metric[]): Finding[] {
-    const findings: Finding[] = [];
-
-    // Group metrics by type
-    const duplicationMetrics = metrics.filter(m => m.name === 'code-duplication');
-
-    for (const metric of duplicationMetrics) {
-      if (metric.value > 0) {
-        const severity = metric.value > 5 ? 'high' : metric.value > 2 ? 'medium' : 'low';
-        
-        const builder = new FindingBuilder()
-          .withRuleId(this.id)
-          .withSeverity(severity)
-          .withMessage(
-            `Found ${metric.value} duplicate code block(s) in ${metric.context || 'file'}`
-          )
-          .withFilePath(metric.filePath)
-          .withSuggestion('Extract duplicate code into reusable functions or modules');
-        
-        if (metric.location) {
-          builder.withLocation(metric.location);
-        }
-        
-        findings.push(builder.build());
-      }
-    }
-
-    return findings;
-  }
-
-  calculateScore(findings: Finding[]): number {
-    if (findings.length === 0) return 100;
-
-    // Each duplication finding reduces score
-    const penalty = findings.reduce((sum, finding) => {
-      switch (finding.severity) {
-        case 'high': return sum + 15;
-        case 'medium': return sum + 8;
-        case 'low': return sum + 4;
-        default: return sum;
-      }
-    }, 0);
-
-    const score = Math.max(0, 100 - penalty);
-    return Math.round(score * 100) / 100;
-  }
-}