@aiready/core 0.9.38 → 0.17.0

package/dist/index.d.ts

@@ -1,5 +1,58 @@
-import { ScanOptions, AIReadyConfig, CostConfig, ModelContextTier, ComprehensionDifficulty, ProductivityImpact, TokenBudget, TechnicalValueChain, ToolScoringOutput, AcceptancePrediction, LanguageParser, Language, ParseResult, NamingConvention } from './client.js';
-export { AnalysisResult, BusinessReport, CONTEXT_TIER_THRESHOLDS, CommonASTNode, DEFAULT_TOOL_WEIGHTS, ExportInfo, GraphData, GraphEdge, GraphIssueSeverity, GraphMetadata, GraphNode, ImportInfo, Issue, IssueType, LANGUAGE_EXTENSIONS, LanguageConfig, Location, Metrics, ParseError, ParseStatistics, Report, SIZE_ADJUSTED_THRESHOLDS, ScoringConfig, ScoringResult, SourceLocation, SourceRange, TOOL_NAME_MAP, calculateOverallScore, formatScore, formatToolScore, generateHTML, getProjectSizeTier, getRating, getRatingDisplay, getRatingWithContext, getRecommendedThreshold, getToolWeight, normalizeToolName, parseWeightString } from './client.js';
+import { AnalysisResult, ScanOptions, AIReadyConfig, ModelContextTier, CostConfig, TokenBudget, ProductivityImpact, ToolScoringOutput, AcceptancePrediction, ComprehensionDifficulty, TechnicalValueChainSummary, TechnicalValueChain, LanguageParser, Language, ParseResult, NamingConvention } from './client.js';
+export { BusinessReport, CONTEXT_TIER_THRESHOLDS, CommonASTNode, DEFAULT_TOOL_WEIGHTS, ExportInfo, GraphData, GraphEdge, GraphIssueSeverity, GraphMetadata, GraphNode, ImportInfo, Issue, IssueType, LANGUAGE_EXTENSIONS, LanguageConfig, Location, Metrics, ParseError, ParseStatistics, Report, SIZE_ADJUSTED_THRESHOLDS, ScoringConfig, ScoringResult, SourceLocation, SourceRange, TOOL_NAME_MAP, calculateOverallScore, formatScore, formatToolScore, generateHTML, getProjectSizeTier, getRating, getRatingDisplay, getRatingWithContext, getRecommendedThreshold, getToolWeight, normalizeToolName, parseWeightString } from './client.js';
+
+/**
+ * Spoke-to-Hub Contract Definitions
+ * This file defines the expected JSON structure for tool outputs to ensure
+ * changes in spokes don't break the CLI, Platform, or Visualizer.
+ */
+
+/**
+ * The standard output every spoke MUST provide when analyzed.
+ * Some fields are optional depending on the tool's focus.
+ */
+interface SpokeOutput {
+    results: AnalysisResult[];
+    summary: any;
+    metadata?: {
+        toolName: string;
+        version: string;
+        timestamp: string;
+        [key: string]: any;
+    };
+}
+/**
+ * Validation utility to ensure a spoke's output matches the expected contract.
+ * Used in spoke tests to catch breakages early.
+ */
+declare function validateSpokeOutput(toolName: string, output: any): {
+    valid: boolean;
+    errors: string[];
+};
+/**
+ * The unified report format produced by the CLI and consumed by the Platform.
+ * This is the master contract for the entire system.
+ */
+interface UnifiedReport {
+    summary: {
+        totalFiles: number;
+        totalIssues: number;
+        criticalIssues: number;
+        majorIssues: number;
+    };
+    results: AnalysisResult[];
+    scoring?: {
+        overall: number;
+        rating: string;
+        timestamp: string;
+        breakdown: Array<{
+            toolName: string;
+            score: number;
+            [key: string]: any;
+        }>;
+    };
+    [toolKey: string]: any;
+}
 
 declare const DEFAULT_EXCLUDE: string[];
 declare const VAGUE_FILE_NAMES: Set<string>;
@@ -120,23 +173,24 @@ declare function handleCLIError(error: unknown, commandName: string): never;
  * Calculate elapsed time and format for display
  */
 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.
- * NEW in v0.12: Multi-model pricing presets, model-aware CDI calibration,
- * and improved acceptance rate prediction with data-grounded baselines.
+ * Generate a visual score bar for console output
+ */
+declare function getScoreBar(val: number): string;
+/**
+ * Get status icon for safety ratings
+ */
+declare function getSafetyIcon(rating: string): string;
+/**
+ * Get chalk color function for a given severity
+ * @param severity severity level
+ * @param chalk chalk instance
  */
+declare function getSeverityColor(severity: string, chalk: any): any;
 
 /**
  * AI model pricing presets for cost estimation.
  * Prices are input token costs per 1K tokens (USD), as of Q1 2026.
- * Update these as model pricing evolves — the calculation logic is unchanged.
  */
 interface ModelPricingPreset {
     name: string;
@@ -151,96 +205,14 @@ declare const MODEL_PRICING_PRESETS: Record<string, ModelPricingPreset>;
  * Get a model pricing preset by ID, with fallback to claude-4.6 (2026 default)
  */
 declare function getModelPreset(modelId: string): ModelPricingPreset;
-/**
- * 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
- * Points to GPT-4o as the default model (most common in 2026).
- * Use MODEL_PRICING_PRESETS for model-specific accuracy.
  */
 declare const DEFAULT_COST_CONFIG: CostConfig;
 /**
- * @deprecated Since v0.13. Use calculateTokenBudget() + estimateCostFromBudget() instead.
- * Dollar costs are volatile based on technology; token budgets are stable unit economics.
- *
- * Calculate estimated monthly cost of AI context waste with confidence intervals.
+ * Calculate estimated monthly cost of AI context waste
+ * @deprecated Since v0.13
  */
 declare function calculateMonthlyCost(tokenWaste: number, config?: Partial<CostConfig>): {
     total: number;
@@ -248,8 +220,7 @@ declare function calculateMonthlyCost(tokenWaste: number, config?: Partial<CostC
     confidence: number;
 };
 /**
- * Calculate token budget and unit economics for AI interactions.
- * Technology-agnostic metric that remains valid across model generations.
+ * Calculate token budget and unit economics
  */
 declare function calculateTokenBudget(params: {
     totalContextTokens: number;
@@ -261,14 +232,23 @@ declare function calculateTokenBudget(params: {
     };
 }): TokenBudget;
 /**
- * Estimate dollar cost from a token budget using model presets.
- * Note: Use this for presentation only. Token budgets are the primary metric.
+ * Estimate dollar cost from a token budget
  */
 declare function estimateCostFromBudget(budget: TokenBudget, model: ModelPricingPreset, config?: Partial<CostConfig>): {
     total: number;
     range: [number, number];
     confidence: number;
 };
+
+/**
+ * Severity time estimates (hours to fix)
+ */
+declare const SEVERITY_TIME_ESTIMATES: {
+    critical: number;
+    major: number;
+    minor: number;
+    info: number;
+};
 /**
  * Calculate productivity impact from issues
  */
@@ -276,85 +256,113 @@ declare function calculateProductivityImpact(issues: {
     severity: string;
 }[], hourlyRate?: number): ProductivityImpact;
 /**
- * Predict AI suggestion acceptance rate based on code quality
- *
- * Calibration notes (v0.12):
- * - GitHub Copilot reports ~30% industry average acceptance rate (2023 blog)
- * - Research (Ziegler et al., 2022) indicates acceptance rate is a proxy for productivity
- * - Internal teams with high-consistency codebases report 40-55%
- * - Teams with semantic duplication report 20-25% (AI suggests wrong variant)
- * - Context efficiency is the strongest single predictor (empirical correlation: r=0.68)
- *
- * Confidence levels:
- * - 3 tools: 0.75 (triangulated estimate)
- * - 2 tools: 0.55 (partial estimate)
- * - 1 tool:  0.35 (weak estimate — don't over-rely)
+ * Predict AI suggestion acceptance rate
  */
 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.
- *
- * v0.12+: Now model-aware. Pass the `modelTier` of your AI toolchain
- * to recalibrate token budget thresholds correctly. With frontier models
- * (200k+ context), a 20k-token file is no longer "critical".
+ * Knowledge and Technical Debt Risk Metrics
  */
-declare function calculateComprehensionDifficulty(contextBudget: number, importDepth: number, fragmentation: number, consistencyScore: number, totalFiles: number, modelTier?: ModelContextTier): ComprehensionDifficulty;
+interface KnowledgeConcentrationRisk {
+    score: number;
+    rating: 'low' | 'moderate' | 'high' | 'critical';
+    analysis: {
+        uniqueConceptFiles: number;
+        totalFiles: number;
+        concentrationRatio: number;
+        singleAuthorFiles: number;
+        orphanFiles: number;
+    };
+    recommendations: string[];
+}
+declare function calculateKnowledgeConcentration(params: {
+    uniqueConceptFiles: number;
+    totalFiles: number;
+    singleAuthorFiles: number;
+    orphanFiles: number;
+}): KnowledgeConcentrationRisk;
+interface TechnicalDebtInterest {
+    monthlyRate: number;
+    annualRate: number;
+    principal: number;
+    projections: {
+        months6: number;
+        months12: number;
+        months24: number;
+    };
+    monthlyCost: number;
+}
+declare function calculateDebtInterest(principal: number, monthlyGrowthRate: number): TechnicalDebtInterest;
+
 /**
- * Format cost for display
+ * Calculate Technical Value Chain
  */
-declare function formatCost(cost: number): string;
+declare function calculateTechnicalValueChain(params: {
+    businessLogicDensity: number;
+    dataAccessComplexity: number;
+    apiSurfaceArea: number;
+}): TechnicalValueChainSummary;
 /**
- * Format hours for display
+ * Calculate Comprehension Difficulty Index (CDI)
  */
-declare function formatHours(hours: number): string;
+declare function calculateComprehensionDifficulty(contextBudget: number, importDepth: number, fragmentation: number, modelTier?: ModelContextTier | string): ComprehensionDifficulty;
+
 /**
- * Format acceptance rate for display
+ * Business Value Metrics Module
+ *
+ * Provides business-aligned metrics that quantify ROI and survive technology changes.
  */
-declare function formatAcceptanceRate(rate: number): string;
+
 /**
- * Calculate score trend from historical data
+ * Historical score entry for trend tracking
  */
-declare function calculateScoreTrend(history: ScoreHistoryEntry[]): ScoreTrend;
+interface ScoreHistoryEntry {
+    timestamp: string;
+    overallScore: number;
+    breakdown: Record<string, number>;
+    totalIssues: number;
+    totalTokens: number;
+}
 /**
- * Calculate remediation velocity
+ * Trend analysis comparing current vs historical scores
  */
-declare function calculateRemediationVelocity(history: ScoreHistoryEntry[], currentIssues: number): RemediationVelocity;
+interface ScoreTrend {
+    direction: 'improving' | 'stable' | 'degrading';
+    change30Days: number;
+    change90Days: number;
+    velocity: number;
+    projectedScore: number;
+}
 /**
- * Calculate knowledge concentration risk
- *
- * This measures how "centralized" knowledge is in the codebase,
- * similar to bus factor but for AI/ML training purposes.
+ * Calculate Aggregate Business ROI
  */
-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;
+declare function calculateBusinessROI(params: {
+    tokenWaste: number;
     issues: {
         severity: string;
     }[];
-    monthsOpen: number;
-}): TechnicalDebtInterest;
+    developerCount?: number;
+    modelId?: string;
+}): {
+    monthlySavings: number;
+    productivityGainHours: number;
+    annualValue: number;
+};
+/**
+ * Format cost for display
+ */
+declare function formatCost(cost: number): string;
 /**
- * Get debt breakdown by category
+ * Format hours for display
+ */
+declare function formatHours(hours: number): string;
+
+/**
+ * Format acceptance rate for display
  */
-declare function getDebtBreakdown(patternCost: number, contextCost: number, consistencyCost: number): DebtBreakdown[];
+declare function formatAcceptanceRate(rate: number): string;
 /**
- * Generate a Technical Value Chain for a specific issue
+ * Generate technical value chain for an issue (v0.12 legacy)
  */
 declare function generateValueChain(params: {
     issueType: string;
@@ -491,27 +499,8 @@ declare class PythonParser implements LanguageParser {
 }
 
 /**
- * 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
- * - AI Signal Clarity: How likely AI is to generate incorrect code
- * - Agent Grounding Score: How well an agent can navigate unaided
- * - Testability Index: How verifiable AI-generated changes are
- *
- * v0.12+: Added AI signal clarity, agent grounding, and testability dimensions.
- */
-
-/**
- * Factors that contribute to cognitive load for AI understanding
- * These are normalized 0-100 factors that can be combined
+ * Cognitive Load Metrics
+ * Measures how much mental effort is required for an AI to understand a file.
  */
 interface LoadFactor {
     name: string;
@@ -519,10 +508,6 @@ interface LoadFactor {
     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';
@@ -534,9 +519,6 @@ interface CognitiveLoad {
         conceptCount: number;
     };
 }
-/**
- * Calculate cognitive load from raw file metrics
- */
 declare function calculateCognitiveLoad(params: {
     linesOfCode: number;
     exportCount: number;
@@ -544,6 +526,11 @@ declare function calculateCognitiveLoad(params: {
     uniqueConcepts: number;
     cyclomaticComplexity?: number;
 }): CognitiveLoad;
+
+/**
+ * Semantic Distance Metrics
+ * Measures the conceptual distance between files or domains.
+ */
 interface SemanticDistance {
     between: [string, string];
     distance: number;
@@ -560,6 +547,11 @@ declare function calculateSemanticDistance(params: {
     file2Imports: string[];
     sharedDependencies: string[];
 }): SemanticDistance;
+
+/**
+ * Structural Metrics
+ * Measures pattern entropy and concept cohesion.
+ */
 interface PatternEntropy {
     domain: string;
     entropy: number;
@@ -592,15 +584,10 @@ declare function calculateConceptCohesion(params: {
         domains?: string[];
     }>;
 }): ConceptCohesion;
-declare function calculateFutureProofScore(params: {
-    cognitiveLoad: CognitiveLoad;
-    patternEntropy: PatternEntropy;
-    conceptCohesion: ConceptCohesion;
-    semanticDistances?: SemanticDistance[];
-}): ToolScoringOutput;
+
 /**
- * Signals that increase the likelihood of AI generating incorrect code.
- * Technology-agnostic: these patterns confuse both current and future AI.
+ * AI Signal Clarity Metrics
+ * Measures code patterns that increase the likelihood of AI generating incorrect code.
  */
 interface AiSignalClaritySignal {
     name: string;
@@ -609,162 +596,89 @@ interface AiSignalClaritySignal {
     description: string;
     examples?: string[];
 }
-/**
- * AI Signal Clarity Score (0-100, higher = more risk)
- *
- * Measures code patterns that empirically cause AI models to:
- * - Confidently generate incorrect function signatures
- * - Create plausible-but-wrong implementations
- * - Miss implicit contracts / side effects
- * - Misunderstand overloaded symbols
- */
 interface AiSignalClarity {
-    /** Overall risk score (0-100). Higher = more likely AI will hallucinate. */
     score: number;
     rating: 'minimal' | 'low' | 'moderate' | 'high' | 'severe';
     signals: AiSignalClaritySignal[];
-    /** Most impactful signal to fix first */
     topRisk: string;
     recommendations: string[];
 }
-/**
- * Calculate AI signal clarity from code analysis results
- *
- * Input data can come from any parser; all inputs are normalized 0-N counts.
- */
 declare function calculateAiSignalClarity(params: {
-    /** Overloaded function names (same name, different signatures) */
     overloadedSymbols: number;
-    /** Magic numbers and string literals without named constants */
     magicLiterals: number;
-    /** Boolean trap parameters (function(true, false, null)) */
     booleanTraps: number;
-    /** Implicit returns / void-implicit side effect functions */
     implicitSideEffects: number;
-    /** Callback nesting depth > 3 (callback hell indicator) */
     deepCallbacks: number;
-    /** Non-descriptive names: single letters, x1/x2 patterns, tmp/data/obj */
     ambiguousNames: number;
-    /** Exported symbols with no JSDoc/docstring */
     undocumentedExports: number;
-    /** Total symbols analyzed (for normalization) */
     totalSymbols: number;
-    /** Total exports in codebase */
     totalExports: number;
 }): AiSignalClarity;
+
 /**
- * Agent Grounding Score
- *
- * Measures how well an AI agent can navigate a codebase *independently*,
- * without human assistance or extensive prompting.
- *
- * High grounding = agent can find files, understand project structure,
- * locate relevant code, and correctly infer ownership without being told.
- *
- * This is technology-agnostic: any agentic system (current or future)
- * needs these structural guarantees to work effectively.
+ * Agent Grounding Metrics
+ * Measures how well an AI agent can navigate a codebase independently.
  */
 interface AgentGroundingScore {
-    /** 0-100 score; higher = better self-navigation */
     score: number;
     rating: 'excellent' | 'good' | 'moderate' | 'poor' | 'disorienting';
     dimensions: {
-        /** Can agent find where to put new code? (directory structure clarity) */
         structureClarityScore: number;
-        /** Can agent understand what a file does from its name alone? */
         selfDocumentationScore: number;
-        /** Are entry points (index, main, README) present and accurate? */
         entryPointScore: number;
-        /** Does the public API surface reflect the project's mental model? */
         apiClarityScore: number;
-        /** Is the domain language consistent? (Same concept = same word everywhere) */
         domainConsistencyScore: number;
     };
     recommendations: string[];
 }
-/**
- * Calculate how well an AI agent can ground itself in the codebase
- */
 declare function calculateAgentGrounding(params: {
-    /** Number of directories exceeding recommended depth (> 4 levels) */
     deepDirectories: number;
-    /** Total directories */
     totalDirectories: number;
-    /** Files whose name alone doesn't reveal purpose (e.g., utils.ts, helpers.ts, misc.ts) */
     vagueFileNames: number;
-    /** Total files */
     totalFiles: number;
-    /** Whether a root README exists */
     hasRootReadme: boolean;
-    /** Whether README has been updated in last 90 days (or unknown) */
     readmeIsFresh: boolean;
-    /** Number of barrel exports (index.ts/index.js files that re-export) */
     barrelExports: number;
-    /** Number of exported functions/classes/types with no type annotations */
     untypedExports: number;
-    /** Total exports */
     totalExports: number;
-    /** Number of domain terms used inconsistently (same concept, different names) */
     inconsistentDomainTerms: number;
-    /** Distinct domain vocabulary size (unique business terms detected) */
     domainVocabularySize: number;
 }): AgentGroundingScore;
+
 /**
- * Testability Index
- *
+ * Testability Index Metrics
  * Measures how verifiable AI-generated changes are.
- * AI assistants are only as useful as your ability to validate their output.
- *
- * Core insight: A codebase where generated code CAN'T be verified
- * is one where AI assistance actively introduces hidden risk.
- *
- * Technology-agnostic: test frameworks change; testability principles don't.
  */
 interface TestabilityIndex {
-    /** 0-100 score; higher = AI changes are more verifiable */
     score: number;
     rating: 'excellent' | 'good' | 'moderate' | 'poor' | 'unverifiable';
     dimensions: {
-        /** Ratio of test files to source files */
         testCoverageRatio: number;
-        /** Pure function prevalence (no side effects = easy to test) */
         purityScore: number;
-        /** Dependency injection / inversion of control score */
         dependencyInjectionScore: number;
-        /** Interface segregation (small, focused interfaces) */
         interfaceFocusScore: number;
-        /** Observable outputs (functions return values vs mutate state) */
         observabilityScore: number;
     };
-    /** Estimated AI suggestion safety — without tests, AI changes are high-risk */
     aiChangeSafetyRating: 'safe' | 'moderate-risk' | 'high-risk' | 'blind-risk';
     recommendations: string[];
 }
-/**
- * Calculate testability index from code structure analysis
- */
 declare function calculateTestabilityIndex(params: {
-    /** Number of test files (*.test.*, *.spec.*, __tests__/**) */
     testFiles: number;
-    /** Number of source files (excluding tests, configs) */
     sourceFiles: number;
-    /** Functions that take only data and return data (no I/O, no mutations) */
     pureFunctions: number;
-    /** Total functions analyzed */
     totalFunctions: number;
-    /** Classes/functions using constructor injection or factory patterns */
     injectionPatterns: number;
-    /** Total classes/services */
     totalClasses: number;
-    /** Interfaces/types with > 10 methods (low segregation) */
     bloatedInterfaces: number;
-    /** Total interfaces/types */
     totalInterfaces: number;
-    /** Functions that directly mutate external state (globals, DOM, DB without abstraction) */
     externalStateMutations: number;
-    /** Has a defined testing framework (package.json test script exists) */
     hasTestFramework: boolean;
 }): TestabilityIndex;
+
+/**
+ * Documentation Drift Metrics
+ * Measures the risk of documentation becoming out of sync with code.
+ */
 interface DocDriftRisk {
     score: number;
     rating: 'minimal' | 'low' | 'moderate' | 'high' | 'severe';
@@ -781,6 +695,11 @@ declare function calculateDocDrift(params: {
     outdatedComments: number;
     undocumentedComplexity: number;
 }): DocDriftRisk;
+
+/**
+ * Dependency Health Metrics
+ * Measures the health and recency of project dependencies.
+ */
 interface DependencyHealthScore {
     score: number;
     rating: 'excellent' | 'good' | 'moderate' | 'poor' | 'hazardous';
@@ -798,6 +717,11 @@ declare function calculateDependencyHealth(params: {
     deprecatedPackages: number;
     trainingCutoffSkew: number;
 }): DependencyHealthScore;
+
+/**
+ * Change Amplification Metrics
+ * Measures how a change in one file ripples through the system.
+ */
 interface ChangeAmplificationScore {
     score: number;
     rating: 'isolated' | 'contained' | 'amplified' | 'explosive';
@@ -818,9 +742,25 @@ declare function calculateChangeAmplification(params: {
         fanIn: number;
     }>;
 }): ChangeAmplificationScore;
+
+/**
+ * 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.
+ */
+
+/**
+ * Aggregate Future-Proof Score (Base)
+ */
+declare function calculateFutureProofScore(params: {
+    cognitiveLoad: CognitiveLoad;
+    patternEntropy: PatternEntropy;
+    conceptCohesion: ConceptCohesion;
+    semanticDistances?: SemanticDistance[];
+}): ToolScoringOutput;
 /**
- * Calculate the complete extended future-proof score including all dimensions.
- * Replaces calculateFutureProofScore when all dimensions are available.
+ * Complete Extended Future-Proof Score
  */
 declare function calculateExtendedFutureProofScore(params: {
     cognitiveLoad: CognitiveLoad;
@@ -889,4 +829,4 @@ declare function getRepoMetadata(directory: string): {
     author?: string;
 };
 
-export { AIReadyConfig, type ASTNode, AcceptancePrediction, type AgentGroundingScore, type AiSignalClarity, type AiSignalClaritySignal, type CLIOptions, type ChangeAmplificationScore, type CognitiveLoad, ComprehensionDifficulty, type ConceptCohesion, CostConfig, DEFAULT_COST_CONFIG, DEFAULT_EXCLUDE, type DebtBreakdown, type DependencyHealthScore, type DocDriftRisk, type ExportWithImports, type FileImport, type FileWithDomain, type KnowledgeConcentrationRisk, Language, LanguageParser, type LoadFactor, MODEL_PRICING_PRESETS, ModelContextTier, type ModelPricingPreset, NamingConvention, ParseResult, ParserFactory, type PatternEntropy, ProductivityImpact, PythonParser, type RemediationVelocity, ScanOptions, type ScoreHistoryEntry, type ScoreTrend, type SemanticDistance, type TechnicalDebtInterest, TechnicalValueChain, type TestabilityIndex, TokenBudget, ToolScoringOutput, TypeScriptParser, VAGUE_FILE_NAMES, calculateAgentGrounding, calculateAiSignalClarity, calculateChangeAmplification, calculateCognitiveLoad, calculateComprehensionDifficulty, calculateConceptCohesion, calculateDependencyHealth, calculateDocDrift, calculateExtendedFutureProofScore, calculateFutureProofScore, calculateImportSimilarity, calculateKnowledgeConcentration, calculateMonthlyCost, calculatePatternEntropy, calculateProductivityImpact, calculateRemediationVelocity, calculateScoreTrend, calculateSemanticDistance, calculateTechnicalDebtInterest, calculateTestabilityIndex, calculateTokenBudget, clearHistory, estimateCostFromBudget, estimateTokens, exportHistory, extractFunctions, extractImports, formatAcceptanceRate, formatCost, formatHours, generateValueChain, getDebtBreakdown, getElapsedTime, getFileCommitTimestamps, getFileExtension, getHistorySummary, getLineRangeLastModifiedCached, getModelPreset, getParser, getRepoMetadata, getSupportedLanguages, handleCLIError, handleJSONOutput, isFileSupported, isSourceFile, loadConfig, loadMergedConfig, loadScoreHistory, mergeConfigWithDefaults, parseCode, parseFileExports, predictAcceptanceRate, readFileContent, resolveOutputPath, saveScoreEntry, scanEntries, scanFiles };
+export { AIReadyConfig, type ASTNode, AcceptancePrediction, type AgentGroundingScore, type AiSignalClarity, type AiSignalClaritySignal, AnalysisResult, type CLIOptions, type ChangeAmplificationScore, type CognitiveLoad, ComprehensionDifficulty, type ConceptCohesion, CostConfig, DEFAULT_COST_CONFIG, DEFAULT_EXCLUDE, type DependencyHealthScore, type DocDriftRisk, type ExportWithImports, type FileImport, type FileWithDomain, type KnowledgeConcentrationRisk, Language, LanguageParser, type LoadFactor, MODEL_PRICING_PRESETS, ModelContextTier, type ModelPricingPreset, NamingConvention, ParseResult, ParserFactory, type PatternEntropy, ProductivityImpact, PythonParser, SEVERITY_TIME_ESTIMATES, ScanOptions, type ScoreHistoryEntry, type ScoreTrend, type SemanticDistance, type SpokeOutput, type TechnicalDebtInterest, TechnicalValueChain, TechnicalValueChainSummary, type TestabilityIndex, TokenBudget, ToolScoringOutput, TypeScriptParser, type UnifiedReport, VAGUE_FILE_NAMES, calculateAgentGrounding, calculateAiSignalClarity, calculateBusinessROI, calculateChangeAmplification, calculateCognitiveLoad, calculateComprehensionDifficulty, calculateConceptCohesion, calculateDebtInterest, calculateDependencyHealth, calculateDocDrift, calculateExtendedFutureProofScore, calculateFutureProofScore, calculateImportSimilarity, calculateKnowledgeConcentration, calculateMonthlyCost, calculatePatternEntropy, calculateProductivityImpact, calculateSemanticDistance, calculateTechnicalValueChain, calculateTestabilityIndex, calculateTokenBudget, clearHistory, estimateCostFromBudget, estimateTokens, exportHistory, extractFunctions, extractImports, formatAcceptanceRate, formatCost, formatHours, generateValueChain, getElapsedTime, getFileCommitTimestamps, getFileExtension, getHistorySummary, getLineRangeLastModifiedCached, getModelPreset, getParser, getRepoMetadata, getSafetyIcon, getScoreBar, getSeverityColor, getSupportedLanguages, handleCLIError, handleJSONOutput, isFileSupported, isSourceFile, loadConfig, loadMergedConfig, loadScoreHistory, mergeConfigWithDefaults, parseCode, parseFileExports, predictAcceptanceRate, readFileContent, resolveOutputPath, saveScoreEntry, scanEntries, scanFiles, validateSpokeOutput };