@aiready/core 0.9.23 → 0.9.26

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { ScanOptions, AIReadyConfig, LanguageParser, Language, ParseResult, NamingConvention } from './client.js';
-export { AnalysisResult, CommonASTNode, DEFAULT_TOOL_WEIGHTS, ExportInfo, GraphData, GraphEdge, GraphIssueSeverity, GraphMetadata, GraphNode, ImportInfo, Issue, IssueType, LANGUAGE_EXTENSIONS, LanguageConfig, Location, Metrics, ParseError, ParseStatistics, Report, ScoringConfig, ScoringResult, SourceLocation, SourceRange, TOOL_NAME_MAP, ToolScoringOutput, calculateOverallScore, formatScore, formatToolScore, generateHTML, getRating, getRatingDisplay, getToolWeight, normalizeToolName, parseWeightString } from './client.js';
+import { ScanOptions, AIReadyConfig, CostConfig, ComprehensionDifficulty, ProductivityImpact, ToolScoringOutput, AcceptancePrediction, LanguageParser, Language, ParseResult, NamingConvention } from './client.js';
+export { AnalysisResult, BusinessReport, CommonASTNode, DEFAULT_TOOL_WEIGHTS, ExportInfo, GraphData, GraphEdge, GraphIssueSeverity, GraphMetadata, GraphNode, ImportInfo, Issue, IssueType, LANGUAGE_EXTENSIONS, LanguageConfig, Location, Metrics, ParseError, ParseStatistics, Report, ScoringConfig, ScoringResult, SourceLocation, SourceRange, TOOL_NAME_MAP, calculateOverallScore, formatScore, formatToolScore, generateHTML, getRating, getRatingDisplay, getToolWeight, normalizeToolName, parseWeightString } from './client.js';
 
 declare const DEFAULT_EXCLUDE: string[];
 /**
@@ -112,6 +112,180 @@ declare function handleCLIError(error: unknown, commandName: string): never;
  */
 declare function getElapsedTime(startTime: number): string;
 
+/**
+ * Business Value Metrics Module
+ *
+ * Provides business-aligned metrics that quantify ROI and survive technology changes.
+ * These metrics connect technical measurements to developer productivity and cost impact.
+ *
+ * NEW in v0.11: Extended with temporal tracking, knowledge concentration, and
+ * technical debt interest calculations.
+ */
+
+/**
+ * Historical score entry for trend tracking
+ */
+interface ScoreHistoryEntry {
+    timestamp: string;
+    overallScore: number;
+    breakdown: Record<string, number>;
+    totalIssues: number;
+    totalTokens: number;
+}
+/**
+ * Trend analysis comparing current vs historical scores
+ */
+interface ScoreTrend {
+    direction: 'improving' | 'stable' | 'degrading';
+    change30Days: number;
+    change90Days: number;
+    velocity: number;
+    projectedScore: number;
+}
+/**
+ * Remediation velocity tracking
+ */
+interface RemediationVelocity {
+    issuesFixedThisWeek: number;
+    avgIssuesPerWeek: number;
+    trend: 'accelerating' | 'stable' | 'decelerating';
+    estimatedCompletionWeeks: number;
+}
+/**
+ * Knowledge concentration risk - measures "bus factor" for AI training
+ */
+interface KnowledgeConcentrationRisk {
+    /** Overall risk score 0-100: higher = more risk */
+    score: number;
+    rating: 'low' | 'moderate' | 'high' | 'critical';
+    /** Analysis details */
+    analysis: {
+        /** Files with unique concepts (only source) */
+        uniqueConceptFiles: number;
+        totalFiles: number;
+        concentrationRatio: number;
+        /** Key person dependencies (files only one person understands) */
+        singleAuthorFiles: number;
+        /** Orphan files (no dependencies) */
+        orphanFiles: number;
+    };
+    /** Recommendations for reducing risk */
+    recommendations: string[];
+}
+/**
+ * Technical debt interest rate - cost of inaction over time
+ */
+interface TechnicalDebtInterest {
+    /** Monthly interest rate (% of principal adding up) */
+    monthlyRate: number;
+    /** Annual effective rate */
+    annualRate: number;
+    /** Principal (current technical debt cost) */
+    principal: number;
+    /** Projected debt in 6/12/24 months */
+    projections: {
+        months6: number;
+        months12: number;
+        months24: number;
+    };
+    /** Monthly cost of delay */
+    monthlyCost: number;
+}
+/**
+ * Detailed debt breakdown by category
+ */
+interface DebtBreakdown {
+    category: string;
+    currentCost: number;
+    monthlyGrowthRate: number;
+    priority: 'high' | 'medium' | 'low';
+    fixCost: number;
+}
+/**
+ * Default cost configuration
+ * Based on GPT-4 pricing and typical team usage
+ */
+declare const DEFAULT_COST_CONFIG: CostConfig;
+/**
+ * Calculate estimated monthly cost of AI context waste
+ *
+ * Formula: (tokenWaste / 1000) × pricePer1K × queriesPerDev × devCount × days
+ */
+declare function calculateMonthlyCost(tokenWaste: number, config?: Partial<CostConfig>): number;
+/**
+ * Calculate productivity impact from issues
+ */
+declare function calculateProductivityImpact(issues: {
+    severity: string;
+}[], hourlyRate?: number): ProductivityImpact;
+/**
+ * Predict AI suggestion acceptance rate based on code quality
+ *
+ * Research shows:
+ * - High consistency correlates with 30%+ higher acceptance
+ * - Low context budget improves understanding by ~40%
+ * - Good naming patterns reduce clarification needs by 50%
+ */
+declare function predictAcceptanceRate(toolOutputs: Map<string, ToolScoringOutput>): AcceptancePrediction;
+/**
+ * Calculate Comprehension Difficulty Index
+ *
+ * A future-proof abstraction that normalizes multiple factors
+ * into a single difficulty score. Lower = easier for AI.
+ */
+declare function calculateComprehensionDifficulty(contextBudget: number, importDepth: number, fragmentation: number, consistencyScore: number, totalFiles: number): ComprehensionDifficulty;
+/**
+ * Format cost for display
+ */
+declare function formatCost(cost: number): string;
+/**
+ * Format hours for display
+ */
+declare function formatHours(hours: number): string;
+/**
+ * Format acceptance rate for display
+ */
+declare function formatAcceptanceRate(rate: number): string;
+/**
+ * Calculate score trend from historical data
+ */
+declare function calculateScoreTrend(history: ScoreHistoryEntry[]): ScoreTrend;
+/**
+ * Calculate remediation velocity
+ */
+declare function calculateRemediationVelocity(history: ScoreHistoryEntry[], currentIssues: number): RemediationVelocity;
+/**
+ * Calculate knowledge concentration risk
+ *
+ * This measures how "centralized" knowledge is in the codebase,
+ * similar to bus factor but for AI/ML training purposes.
+ */
+declare function calculateKnowledgeConcentration(files: {
+    path: string;
+    exports: number;
+    imports: number;
+}[], authorData?: Map<string, string[]>): KnowledgeConcentrationRisk;
+/**
+ * Calculate technical debt interest rate
+ *
+ * The key insight: technical debt compounds over time.
+ * Each month, issues grow by a certain rate due to:
+ * - New code inheriting patterns
+ * - Context budget growing
+ * - Duplication spreading
+ */
+declare function calculateTechnicalDebtInterest(params: {
+    currentMonthlyCost: number;
+    issues: {
+        severity: string;
+    }[];
+    monthsOpen: number;
+}): TechnicalDebtInterest;
+/**
+ * Get debt breakdown by category
+ */
+declare function getDebtBreakdown(patternCost: number, contextCost: number, consistencyCost: number): DebtBreakdown[];
+
 /**
  * Parser Factory - Manages language-specific parsers
  *
@@ -240,4 +414,145 @@ declare class PythonParser implements LanguageParser {
     private extractExportsRegex;
 }
 
-export { AIReadyConfig, type ASTNode, type CLIOptions, DEFAULT_EXCLUDE, type ExportWithImports, type FileImport, Language, LanguageParser, NamingConvention, ParseResult, ParserFactory, PythonParser, ScanOptions, TypeScriptParser, calculateImportSimilarity, estimateTokens, extractFunctions, extractImports, getElapsedTime, getFileExtension, getParser, getSupportedLanguages, handleCLIError, handleJSONOutput, isFileSupported, isSourceFile, loadConfig, loadMergedConfig, mergeConfigWithDefaults, parseCode, parseFileExports, readFileContent, resolveOutputPath, scanFiles };
+/**
+ * Future-Proof AI Metrics Abstraction Layer
+ *
+ * This module provides technology-agnostic metric primitives that will
+ * remain valid across changes in AI models, tokenization, and paradigms.
+ *
+ * The key insight: rather than measuring "tokens" or "import depth",
+ * we measure cognitive concepts that translate to any AI architecture:
+ * - Cognitive Load: How much mental effort for AI to understand
+ * - Semantic Distance: How far apart related concepts are
+ * - Concept Cohesion: How well grouped related ideas are
+ * - Pattern Entropy: How ordered vs chaotic the structure is
+ */
+
+/**
+ * Factors that contribute to cognitive load for AI understanding
+ * These are normalized 0-100 factors that can be combined
+ */
+interface LoadFactor {
+    name: string;
+    score: number;
+    weight: number;
+    description: string;
+}
+/**
+ * Cognitive Load Assessment
+ * Replaces "token cost" with a multi-dimensional load analysis
+ */
+interface CognitiveLoad {
+    score: number;
+    rating: 'trivial' | 'easy' | 'moderate' | 'difficult' | 'expert';
+    factors: LoadFactor[];
+    rawValues: {
+        size: number;
+        complexity: number;
+        dependencyCount: number;
+        conceptCount: number;
+    };
+}
+/**
+ * Calculate cognitive load from raw file metrics
+ */
+declare function calculateCognitiveLoad(params: {
+    linesOfCode: number;
+    exportCount: number;
+    importCount: number;
+    uniqueConcepts: number;
+    cyclomaticComplexity?: number;
+}): CognitiveLoad;
+interface SemanticDistance {
+    between: [string, string];
+    distance: number;
+    relationship: 'same-file' | 'same-domain' | 'cross-domain' | 'unrelated';
+    path: string[];
+    reason: string;
+}
+declare function calculateSemanticDistance(params: {
+    file1: string;
+    file2: string;
+    file1Domain: string;
+    file2Domain: string;
+    file1Imports: string[];
+    file2Imports: string[];
+    sharedDependencies: string[];
+}): SemanticDistance;
+interface PatternEntropy {
+    domain: string;
+    entropy: number;
+    rating: 'crystalline' | 'well-structured' | 'moderate' | 'fragmented' | 'chaotic';
+    distribution: {
+        locationCount: number;
+        dominantLocation: string;
+        giniCoefficient: number;
+    };
+    recommendations: string[];
+}
+interface FileWithDomain {
+    path: string;
+    domain: string;
+}
+declare function calculatePatternEntropy(files: FileWithDomain[]): PatternEntropy;
+interface ConceptCohesion {
+    score: number;
+    rating: 'excellent' | 'good' | 'moderate' | 'poor';
+    analysis: {
+        uniqueDomains: number;
+        domainConcentration: number;
+        exportPurposeClarity: number;
+    };
+}
+declare function calculateConceptCohesion(params: {
+    exports: Array<{
+        name: string;
+        inferredDomain?: string;
+        domains?: string[];
+    }>;
+}): ConceptCohesion;
+declare function calculateFutureProofScore(params: {
+    cognitiveLoad: CognitiveLoad;
+    patternEntropy: PatternEntropy;
+    conceptCohesion: ConceptCohesion;
+    semanticDistances?: SemanticDistance[];
+}): ToolScoringOutput;
+
+/**
+ * Temporal Tracking Utilities
+ *
+ * Manages score history storage and retrieval for trend analysis.
+ * Stores data in .aiready/history/ directory.
+ */
+/**
+ * Load score history from disk
+ */
+declare function loadScoreHistory(rootDir: string): any[];
+/**
+ * Save score entry to history
+ */
+declare function saveScoreEntry(rootDir: string, entry: {
+    overallScore: number;
+    breakdown: Record<string, number>;
+    totalIssues: number;
+    totalTokens: number;
+}): void;
+/**
+ * Get summary of recent history
+ */
+declare function getHistorySummary(rootDir: string): {
+    totalScans: number;
+    firstScan: string | null;
+    lastScan: string | null;
+    avgScore: number;
+};
+/**
+ * Export history for external analysis
+ */
+declare function exportHistory(rootDir: string, format?: 'json' | 'csv'): string;
+/**
+ * Clear history (for testing or reset)
+ */
+declare function clearHistory(rootDir: string): void;
+
+export { AIReadyConfig, type ASTNode, AcceptancePrediction, type CLIOptions, type CognitiveLoad, ComprehensionDifficulty, type ConceptCohesion, CostConfig, DEFAULT_COST_CONFIG, DEFAULT_EXCLUDE, type DebtBreakdown, type ExportWithImports, type FileImport, type FileWithDomain, type KnowledgeConcentrationRisk, Language, LanguageParser, type LoadFactor, NamingConvention, ParseResult, ParserFactory, type PatternEntropy, ProductivityImpact, PythonParser, type RemediationVelocity, ScanOptions, type ScoreHistoryEntry, type ScoreTrend, type SemanticDistance, type TechnicalDebtInterest, ToolScoringOutput, TypeScriptParser, calculateCognitiveLoad, calculateComprehensionDifficulty, calculateConceptCohesion, calculateFutureProofScore, calculateImportSimilarity, calculateKnowledgeConcentration, calculateMonthlyCost, calculatePatternEntropy, calculateProductivityImpact, calculateRemediationVelocity, calculateScoreTrend, calculateSemanticDistance, calculateTechnicalDebtInterest, clearHistory, estimateTokens, exportHistory, extractFunctions, extractImports, formatAcceptanceRate, formatCost, formatHours, getDebtBreakdown, getElapsedTime, getFileExtension, getHistorySummary, getParser, getSupportedLanguages, handleCLIError, handleJSONOutput, isFileSupported, isSourceFile, loadConfig, loadMergedConfig, loadScoreHistory, mergeConfigWithDefaults, parseCode, parseFileExports, predictAcceptanceRate, readFileContent, resolveOutputPath, saveScoreEntry, scanFiles };