@aiready/core 0.9.23 → 0.9.26

package/dist/client.d.mts

@@ -23,6 +23,96 @@ interface Metrics {
     complexityScore?: number;
     consistencyScore?: number;
     docFreshnessScore?: number;
+    estimatedMonthlyCost?: number;
+    estimatedDeveloperHours?: number;
+    comprehensionDifficultyIndex?: number;
+}
+/**
+ * Cost estimation configuration
+ */
+interface CostConfig {
+    /** Price per 1K tokens (default: $0.01 for GPT-4) */
+    pricePer1KTokens: number;
+    /** Average AI queries per developer per day */
+    queriesPerDevPerDay: number;
+    /** Number of developers on the team */
+    developerCount: number;
+    /** Days per month (default: 30) */
+    daysPerMonth: number;
+}
+/**
+ * Productivity impact estimates
+ */
+interface ProductivityImpact {
+    /** Estimated hours to fix all issues */
+    totalHours: number;
+    /** Average hourly rate for developers */
+    hourlyRate: number;
+    /** Estimated total fix cost */
+    totalCost: number;
+    /** Breakdown by severity */
+    bySeverity: {
+        critical: {
+            hours: number;
+            cost: number;
+        };
+        major: {
+            hours: number;
+            cost: number;
+        };
+        minor: {
+            hours: number;
+            cost: number;
+        };
+    };
+}
+/**
+ * AI acceptance rate prediction
+ * Based on research correlating code quality to AI suggestion acceptance
+ */
+interface AcceptancePrediction {
+    /** Predicted acceptance rate (0-1) */
+    rate: number;
+    /** Confidence level (0-1) */
+    confidence: number;
+    /** Factors affecting acceptance */
+    factors: {
+        name: string;
+        impact: number;
+    }[];
+}
+/**
+ * Comprehension difficulty score (future-proof abstraction)
+ * Normalized 0-100 scale: lower = easier for AI to understand
+ */
+interface ComprehensionDifficulty {
+    /** Overall difficulty score (0-100) */
+    score: number;
+    /** Factors contributing to difficulty */
+    factors: {
+        name: string;
+        contribution: number;
+        description: string;
+    }[];
+    /** Interpretation */
+    rating: 'trivial' | 'easy' | 'moderate' | 'difficult' | 'expert';
+}
+/**
+ * Extended report with business metrics
+ */
+interface BusinessReport extends Report {
+    businessMetrics: {
+        /** Estimated monthly cost impact of AI context waste */
+        estimatedMonthlyCost: number;
+        /** Estimated developer hours to address issues */
+        estimatedDeveloperHours: number;
+        /** Predicted AI suggestion acceptance rate */
+        aiAcceptanceRate: number;
+        /** Comprehension difficulty assessment */
+        comprehensionDifficulty: ComprehensionDifficulty;
+        /** Timestamp for trend tracking */
+        period?: string;
+    };
 }
 interface ScanOptions {
     rootDir: string;
@@ -454,4 +544,4 @@ declare function formatToolScore(output: ToolScoringOutput): string;
  */
 declare function generateHTML(graph: GraphData): string;
 
-export { type AIReadyConfig, type AnalysisResult, type CommonASTNode, DEFAULT_TOOL_WEIGHTS, type ExportInfo, type GraphData, type GraphEdge, type GraphIssueSeverity, type GraphMetadata, type GraphNode, type ImportInfo, type Issue, type IssueType, LANGUAGE_EXTENSIONS, Language, type LanguageConfig, type LanguageParser, type Location, type Metrics, type NamingConvention, ParseError, type ParseResult, type ParseStatistics, type Report, type ScanOptions, type ScoringConfig, type ScoringResult, type SourceLocation, type SourceRange, TOOL_NAME_MAP, type ToolScoringOutput, calculateOverallScore, formatScore, formatToolScore, generateHTML, getRating, getRatingDisplay, getToolWeight, normalizeToolName, parseWeightString };
+export { type AIReadyConfig, type AcceptancePrediction, type AnalysisResult, type BusinessReport, type CommonASTNode, type ComprehensionDifficulty, type CostConfig, DEFAULT_TOOL_WEIGHTS, type ExportInfo, type GraphData, type GraphEdge, type GraphIssueSeverity, type GraphMetadata, type GraphNode, type ImportInfo, type Issue, type IssueType, LANGUAGE_EXTENSIONS, Language, type LanguageConfig, type LanguageParser, type Location, type Metrics, type NamingConvention, ParseError, type ParseResult, type ParseStatistics, type ProductivityImpact, type Report, type ScanOptions, type ScoringConfig, type ScoringResult, type SourceLocation, type SourceRange, TOOL_NAME_MAP, type ToolScoringOutput, calculateOverallScore, formatScore, formatToolScore, generateHTML, getRating, getRatingDisplay, getToolWeight, normalizeToolName, parseWeightString };

package/dist/client.d.ts

@@ -23,6 +23,96 @@ interface Metrics {
     complexityScore?: number;
     consistencyScore?: number;
     docFreshnessScore?: number;
+    estimatedMonthlyCost?: number;
+    estimatedDeveloperHours?: number;
+    comprehensionDifficultyIndex?: number;
+}
+/**
+ * Cost estimation configuration
+ */
+interface CostConfig {
+    /** Price per 1K tokens (default: $0.01 for GPT-4) */
+    pricePer1KTokens: number;
+    /** Average AI queries per developer per day */
+    queriesPerDevPerDay: number;
+    /** Number of developers on the team */
+    developerCount: number;
+    /** Days per month (default: 30) */
+    daysPerMonth: number;
+}
+/**
+ * Productivity impact estimates
+ */
+interface ProductivityImpact {
+    /** Estimated hours to fix all issues */
+    totalHours: number;
+    /** Average hourly rate for developers */
+    hourlyRate: number;
+    /** Estimated total fix cost */
+    totalCost: number;
+    /** Breakdown by severity */
+    bySeverity: {
+        critical: {
+            hours: number;
+            cost: number;
+        };
+        major: {
+            hours: number;
+            cost: number;
+        };
+        minor: {
+            hours: number;
+            cost: number;
+        };
+    };
+}
+/**
+ * AI acceptance rate prediction
+ * Based on research correlating code quality to AI suggestion acceptance
+ */
+interface AcceptancePrediction {
+    /** Predicted acceptance rate (0-1) */
+    rate: number;
+    /** Confidence level (0-1) */
+    confidence: number;
+    /** Factors affecting acceptance */
+    factors: {
+        name: string;
+        impact: number;
+    }[];
+}
+/**
+ * Comprehension difficulty score (future-proof abstraction)
+ * Normalized 0-100 scale: lower = easier for AI to understand
+ */
+interface ComprehensionDifficulty {
+    /** Overall difficulty score (0-100) */
+    score: number;
+    /** Factors contributing to difficulty */
+    factors: {
+        name: string;
+        contribution: number;
+        description: string;
+    }[];
+    /** Interpretation */
+    rating: 'trivial' | 'easy' | 'moderate' | 'difficult' | 'expert';
+}
+/**
+ * Extended report with business metrics
+ */
+interface BusinessReport extends Report {
+    businessMetrics: {
+        /** Estimated monthly cost impact of AI context waste */
+        estimatedMonthlyCost: number;
+        /** Estimated developer hours to address issues */
+        estimatedDeveloperHours: number;
+        /** Predicted AI suggestion acceptance rate */
+        aiAcceptanceRate: number;
+        /** Comprehension difficulty assessment */
+        comprehensionDifficulty: ComprehensionDifficulty;
+        /** Timestamp for trend tracking */
+        period?: string;
+    };
 }
 interface ScanOptions {
     rootDir: string;
@@ -454,4 +544,4 @@ declare function formatToolScore(output: ToolScoringOutput): string;
  */
 declare function generateHTML(graph: GraphData): string;
 
-export { type AIReadyConfig, type AnalysisResult, type CommonASTNode, DEFAULT_TOOL_WEIGHTS, type ExportInfo, type GraphData, type GraphEdge, type GraphIssueSeverity, type GraphMetadata, type GraphNode, type ImportInfo, type Issue, type IssueType, LANGUAGE_EXTENSIONS, Language, type LanguageConfig, type LanguageParser, type Location, type Metrics, type NamingConvention, ParseError, type ParseResult, type ParseStatistics, type Report, type ScanOptions, type ScoringConfig, type ScoringResult, type SourceLocation, type SourceRange, TOOL_NAME_MAP, type ToolScoringOutput, calculateOverallScore, formatScore, formatToolScore, generateHTML, getRating, getRatingDisplay, getToolWeight, normalizeToolName, parseWeightString };
+export { type AIReadyConfig, type AcceptancePrediction, type AnalysisResult, type BusinessReport, type CommonASTNode, type ComprehensionDifficulty, type CostConfig, DEFAULT_TOOL_WEIGHTS, type ExportInfo, type GraphData, type GraphEdge, type GraphIssueSeverity, type GraphMetadata, type GraphNode, type ImportInfo, type Issue, type IssueType, LANGUAGE_EXTENSIONS, Language, type LanguageConfig, type LanguageParser, type Location, type Metrics, type NamingConvention, ParseError, type ParseResult, type ParseStatistics, type ProductivityImpact, type Report, type ScanOptions, type ScoringConfig, type ScoringResult, type SourceLocation, type SourceRange, TOOL_NAME_MAP, type ToolScoringOutput, calculateOverallScore, formatScore, formatToolScore, generateHTML, getRating, getRatingDisplay, getToolWeight, normalizeToolName, parseWeightString };

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { ScanOptions, AIReadyConfig, LanguageParser, Language, ParseResult, NamingConvention } from './client.mjs';
-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.mjs';
+import { ScanOptions, AIReadyConfig, CostConfig, ComprehensionDifficulty, ProductivityImpact, ToolScoringOutput, AcceptancePrediction, LanguageParser, Language, ParseResult, NamingConvention } from './client.mjs';
+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.mjs';
 
 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 };