@aiready/core 0.9.33 → 0.9.37

package/dist/client.d.mts

@@ -52,6 +52,29 @@ interface CostConfig {
     /** Days per month (default: 30) */
     daysPerMonth: number;
 }
+/**
+ * Token budget metrics (v0.13+)
+ * Technology-agnostic unit economics for AI impact.
+ */
+interface TokenBudget {
+    /** Total tokens required for full task context */
+    totalContextTokens: number;
+    /** Estimated tokens generated in response */
+    estimatedResponseTokens: number;
+    /** Tokens wasted on redundant/duplicated context */
+    wastedTokens: {
+        total: number;
+        bySource: {
+            duplication: number;
+            fragmentation: number;
+            chattiness: number;
+        };
+    };
+    /** Context efficiency ratio (0-1). 1.0 = perfect efficiency. */
+    efficiencyRatio: number;
+    /** Estimated tokens saved if recommendations are followed */
+    potentialRetrievableTokens: number;
+}
 /**
  * Productivity impact estimates
  */
@@ -109,19 +132,52 @@ interface ComprehensionDifficulty {
     /** Interpretation */
     rating: 'trivial' | 'easy' | 'moderate' | 'difficult' | 'expert';
 }
+/**
+/**
+ * Technical Value Chain
+ * Traces a technical issue through its impact on AI and developer outcomes.
+ */
+interface TechnicalValueChain {
+    issueType: string;
+    technicalMetric: string;
+    technicalValue: number;
+    aiImpact: {
+        description: string;
+        scoreImpact: number;
+    };
+    developerImpact: {
+        description: string;
+        productivityLoss: number;
+    };
+    businessOutcome: {
+        directCost: number;
+        opportunityCost: number;
+        riskLevel: 'low' | 'moderate' | 'high' | 'critical';
+    };
+}
 /**
  * Extended report with business metrics
  */
 interface BusinessReport extends Report {
     businessMetrics: {
-        /** Estimated monthly cost impact of AI context waste */
-        estimatedMonthlyCost: number;
+        /** Token-based unit economics (v0.13+) */
+        tokenBudget: TokenBudget;
+        /** @deprecated Use tokenBudget instead. Estimated monthly cost impact of AI context waste */
+        estimatedMonthlyCost: {
+            total: number;
+            range: [number, number];
+            confidence: number;
+        };
+        /** Opportunity cost of project delay due to technical debt */
+        opportunityCost: number;
         /** Estimated developer hours to address issues */
         estimatedDeveloperHours: number;
         /** Predicted AI suggestion acceptance rate */
         aiAcceptanceRate: number;
         /** Comprehension difficulty assessment */
         comprehensionDifficulty: ComprehensionDifficulty;
+        /** Traces for specific critical issues */
+        valueChains?: TechnicalValueChain[];
         /** Timestamp for trend tracking */
         period?: string;
     };
@@ -131,6 +187,8 @@ interface ScanOptions {
     include?: string[];
     exclude?: string[];
     maxDepth?: number;
+    onProgress?: (processed: number, total: number, message: string) => void;
+    includeTests?: boolean;
 }
 interface AIReadyConfig {
     scan?: {
@@ -250,6 +308,8 @@ interface GraphMetadata {
     majorIssues: number;
     minorIssues: number;
     infoIssues: number;
+    /** AI token budget unit economics (v0.13+) */
+    tokenBudget?: TokenBudget;
 }
 /**
  * Complete graph data structure for visualization
@@ -444,6 +504,8 @@ interface ToolScoringOutput {
     toolName: string;
     /** Normalized 0-100 score for this tool */
     score: number;
+    /** AI token budget unit economics (v0.13+) */
+    tokenBudget?: TokenBudget;
     /** Raw metrics used to calculate the score */
     rawMetrics: Record<string, any>;
     /** Factors that influenced the score */
@@ -613,4 +675,4 @@ declare function formatToolScore(output: ToolScoringOutput): string;
  */
 declare function generateHTML(graph: GraphData): string;
 
-export { type AIReadyConfig, type AcceptancePrediction, type AnalysisResult, type BusinessReport, CONTEXT_TIER_THRESHOLDS, 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 ModelContextTier, type NamingConvention, ParseError, type ParseResult, type ParseStatistics, type ProductivityImpact, type Report, SIZE_ADJUSTED_THRESHOLDS, type ScanOptions, type ScoringConfig, type ScoringResult, type SourceLocation, type SourceRange, TOOL_NAME_MAP, type ToolScoringOutput, calculateOverallScore, formatScore, formatToolScore, generateHTML, getProjectSizeTier, getRating, getRatingDisplay, getRatingWithContext, getRecommendedThreshold, getToolWeight, normalizeToolName, parseWeightString };
+export { type AIReadyConfig, type AcceptancePrediction, type AnalysisResult, type BusinessReport, CONTEXT_TIER_THRESHOLDS, 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 ModelContextTier, type NamingConvention, ParseError, type ParseResult, type ParseStatistics, type ProductivityImpact, type Report, SIZE_ADJUSTED_THRESHOLDS, type ScanOptions, type ScoringConfig, type ScoringResult, type SourceLocation, type SourceRange, TOOL_NAME_MAP, type TechnicalValueChain, type TokenBudget, type ToolScoringOutput, calculateOverallScore, formatScore, formatToolScore, generateHTML, getProjectSizeTier, getRating, getRatingDisplay, getRatingWithContext, getRecommendedThreshold, getToolWeight, normalizeToolName, parseWeightString };

package/dist/client.d.ts

@@ -52,6 +52,29 @@ interface CostConfig {
     /** Days per month (default: 30) */
     daysPerMonth: number;
 }
+/**
+ * Token budget metrics (v0.13+)
+ * Technology-agnostic unit economics for AI impact.
+ */
+interface TokenBudget {
+    /** Total tokens required for full task context */
+    totalContextTokens: number;
+    /** Estimated tokens generated in response */
+    estimatedResponseTokens: number;
+    /** Tokens wasted on redundant/duplicated context */
+    wastedTokens: {
+        total: number;
+        bySource: {
+            duplication: number;
+            fragmentation: number;
+            chattiness: number;
+        };
+    };
+    /** Context efficiency ratio (0-1). 1.0 = perfect efficiency. */
+    efficiencyRatio: number;
+    /** Estimated tokens saved if recommendations are followed */
+    potentialRetrievableTokens: number;
+}
 /**
  * Productivity impact estimates
  */
@@ -109,19 +132,52 @@ interface ComprehensionDifficulty {
     /** Interpretation */
     rating: 'trivial' | 'easy' | 'moderate' | 'difficult' | 'expert';
 }
+/**
+/**
+ * Technical Value Chain
+ * Traces a technical issue through its impact on AI and developer outcomes.
+ */
+interface TechnicalValueChain {
+    issueType: string;
+    technicalMetric: string;
+    technicalValue: number;
+    aiImpact: {
+        description: string;
+        scoreImpact: number;
+    };
+    developerImpact: {
+        description: string;
+        productivityLoss: number;
+    };
+    businessOutcome: {
+        directCost: number;
+        opportunityCost: number;
+        riskLevel: 'low' | 'moderate' | 'high' | 'critical';
+    };
+}
 /**
  * Extended report with business metrics
  */
 interface BusinessReport extends Report {
     businessMetrics: {
-        /** Estimated monthly cost impact of AI context waste */
-        estimatedMonthlyCost: number;
+        /** Token-based unit economics (v0.13+) */
+        tokenBudget: TokenBudget;
+        /** @deprecated Use tokenBudget instead. Estimated monthly cost impact of AI context waste */
+        estimatedMonthlyCost: {
+            total: number;
+            range: [number, number];
+            confidence: number;
+        };
+        /** Opportunity cost of project delay due to technical debt */
+        opportunityCost: number;
         /** Estimated developer hours to address issues */
         estimatedDeveloperHours: number;
         /** Predicted AI suggestion acceptance rate */
         aiAcceptanceRate: number;
         /** Comprehension difficulty assessment */
         comprehensionDifficulty: ComprehensionDifficulty;
+        /** Traces for specific critical issues */
+        valueChains?: TechnicalValueChain[];
         /** Timestamp for trend tracking */
         period?: string;
     };
@@ -131,6 +187,8 @@ interface ScanOptions {
     include?: string[];
     exclude?: string[];
     maxDepth?: number;
+    onProgress?: (processed: number, total: number, message: string) => void;
+    includeTests?: boolean;
 }
 interface AIReadyConfig {
     scan?: {
@@ -250,6 +308,8 @@ interface GraphMetadata {
     majorIssues: number;
     minorIssues: number;
     infoIssues: number;
+    /** AI token budget unit economics (v0.13+) */
+    tokenBudget?: TokenBudget;
 }
 /**
  * Complete graph data structure for visualization
@@ -444,6 +504,8 @@ interface ToolScoringOutput {
     toolName: string;
     /** Normalized 0-100 score for this tool */
     score: number;
+    /** AI token budget unit economics (v0.13+) */
+    tokenBudget?: TokenBudget;
     /** Raw metrics used to calculate the score */
     rawMetrics: Record<string, any>;
     /** Factors that influenced the score */
@@ -613,4 +675,4 @@ declare function formatToolScore(output: ToolScoringOutput): string;
  */
 declare function generateHTML(graph: GraphData): string;
 
-export { type AIReadyConfig, type AcceptancePrediction, type AnalysisResult, type BusinessReport, CONTEXT_TIER_THRESHOLDS, 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 ModelContextTier, type NamingConvention, ParseError, type ParseResult, type ParseStatistics, type ProductivityImpact, type Report, SIZE_ADJUSTED_THRESHOLDS, type ScanOptions, type ScoringConfig, type ScoringResult, type SourceLocation, type SourceRange, TOOL_NAME_MAP, type ToolScoringOutput, calculateOverallScore, formatScore, formatToolScore, generateHTML, getProjectSizeTier, getRating, getRatingDisplay, getRatingWithContext, getRecommendedThreshold, getToolWeight, normalizeToolName, parseWeightString };
+export { type AIReadyConfig, type AcceptancePrediction, type AnalysisResult, type BusinessReport, CONTEXT_TIER_THRESHOLDS, 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 ModelContextTier, type NamingConvention, ParseError, type ParseResult, type ParseStatistics, type ProductivityImpact, type Report, SIZE_ADJUSTED_THRESHOLDS, type ScanOptions, type ScoringConfig, type ScoringResult, type SourceLocation, type SourceRange, TOOL_NAME_MAP, type TechnicalValueChain, type TokenBudget, type ToolScoringOutput, calculateOverallScore, formatScore, formatToolScore, generateHTML, getProjectSizeTier, getRating, getRatingDisplay, getRatingWithContext, getRecommendedThreshold, getToolWeight, normalizeToolName, parseWeightString };

package/dist/index.d.mts

@@ -1,7 +1,8 @@
-import { ScanOptions, AIReadyConfig, CostConfig, ModelContextTier, ComprehensionDifficulty, ProductivityImpact, ToolScoringOutput, AcceptancePrediction, LanguageParser, Language, ParseResult, NamingConvention } from './client.mjs';
+import { ScanOptions, AIReadyConfig, CostConfig, ModelContextTier, ComprehensionDifficulty, ProductivityImpact, TokenBudget, TechnicalValueChain, ToolScoringOutput, AcceptancePrediction, LanguageParser, Language, ParseResult, NamingConvention } from './client.mjs';
 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.mjs';
 
 declare const DEFAULT_EXCLUDE: string[];
+declare const VAGUE_FILE_NAMES: Set<string>;
 /**
  * Scan files in a directory using glob patterns
  *
@@ -12,6 +13,14 @@ declare const DEFAULT_EXCLUDE: string[];
  * @returns Array of absolute file paths matching the patterns
  */
 declare function scanFiles(options: ScanOptions): Promise<string[]>;
+/**
+ * Scan for both files and directories, respecting ignore rules.
+ * Useful for tools that need to analyze directory structure.
+ */
+declare function scanEntries(options: ScanOptions): Promise<{
+    files: string[];
+    dirs: string[];
+}>;
 declare function readFileContent(filePath: string): Promise<string>;
 declare function getFileExtension(filePath: string): string;
 declare function isSourceFile(filePath: string): boolean;
@@ -139,7 +148,7 @@ interface ModelPricingPreset {
 }
 declare const MODEL_PRICING_PRESETS: Record<string, ModelPricingPreset>;
 /**
- * Get a model pricing preset by ID, with fallback to gpt-4o
+ * Get a model pricing preset by ID, with fallback to claude-4.6 (2026 default)
  */
 declare function getModelPreset(modelId: string): ModelPricingPreset;
 /**
@@ -228,11 +237,38 @@ interface DebtBreakdown {
  */
 declare const DEFAULT_COST_CONFIG: CostConfig;
 /**
- * Calculate estimated monthly cost of AI context waste
+ * @deprecated Since v0.13. Use calculateTokenBudget() + estimateCostFromBudget() instead.
+ * Dollar costs are volatile based on technology; token budgets are stable unit economics.
  *
- * Formula: (tokenWaste / 1000) × pricePer1K × queriesPerDev × devCount × days
+ * Calculate estimated monthly cost of AI context waste with confidence intervals.
  */
-declare function calculateMonthlyCost(tokenWaste: number, config?: Partial<CostConfig>): number;
+declare function calculateMonthlyCost(tokenWaste: number, config?: Partial<CostConfig>): {
+    total: number;
+    range: [number, number];
+    confidence: number;
+};
+/**
+ * Calculate token budget and unit economics for AI interactions.
+ * Technology-agnostic metric that remains valid across model generations.
+ */
+declare function calculateTokenBudget(params: {
+    totalContextTokens: number;
+    estimatedResponseTokens?: number;
+    wastedTokens: {
+        duplication: number;
+        fragmentation: number;
+        chattiness: number;
+    };
+}): TokenBudget;
+/**
+ * Estimate dollar cost from a token budget using model presets.
+ * Note: Use this for presentation only. Token budgets are the primary metric.
+ */
+declare function estimateCostFromBudget(budget: TokenBudget, model: ModelPricingPreset, config?: Partial<CostConfig>): {
+    total: number;
+    range: [number, number];
+    confidence: number;
+};
 /**
  * Calculate productivity impact from issues
  */
@@ -244,9 +280,10 @@ declare function calculateProductivityImpact(issues: {
  *
  * 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
+ * - Context efficiency is the strongest single predictor (empirical correlation: r=0.68)
  *
  * Confidence levels:
  * - 3 tools: 0.75 (triangulated estimate)
@@ -316,6 +353,14 @@ declare function calculateTechnicalDebtInterest(params: {
  * Get debt breakdown by category
  */
 declare function getDebtBreakdown(patternCost: number, contextCost: number, consistencyCost: number): DebtBreakdown[];
+/**
+ * Generate a Technical Value Chain for a specific issue
+ */
+declare function generateValueChain(params: {
+    issueType: string;
+    count: number;
+    severity: 'critical' | 'major' | 'minor';
+}): TechnicalValueChain;
 
 /**
  * Parser Factory - Manages language-specific parsers
@@ -826,4 +871,22 @@ declare function exportHistory(rootDir: string, format?: 'json' | 'csv'): string
  */
 declare function clearHistory(rootDir: string): void;
 
-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, type TestabilityIndex, ToolScoringOutput, TypeScriptParser, calculateAgentGrounding, calculateAiSignalClarity, calculateChangeAmplification, calculateCognitiveLoad, calculateComprehensionDifficulty, calculateConceptCohesion, calculateDependencyHealth, calculateDocDrift, calculateExtendedFutureProofScore, calculateFutureProofScore, calculateImportSimilarity, calculateKnowledgeConcentration, calculateMonthlyCost, calculatePatternEntropy, calculateProductivityImpact, calculateRemediationVelocity, calculateScoreTrend, calculateSemanticDistance, calculateTechnicalDebtInterest, calculateTestabilityIndex, clearHistory, estimateTokens, exportHistory, extractFunctions, extractImports, formatAcceptanceRate, formatCost, formatHours, getDebtBreakdown, getElapsedTime, getFileExtension, getHistorySummary, getModelPreset, getParser, getSupportedLanguages, handleCLIError, handleJSONOutput, isFileSupported, isSourceFile, loadConfig, loadMergedConfig, loadScoreHistory, mergeConfigWithDefaults, parseCode, parseFileExports, predictAcceptanceRate, readFileContent, resolveOutputPath, saveScoreEntry, scanFiles };
+/**
+ * Get git commit timestamps for each line in a file
+ */
+declare function getFileCommitTimestamps(file: string): Record<number, number>;
+/**
+ * Get the latest commit timestamp for a line range
+ */
+declare function getLineRangeLastModifiedCached(lineStamps: Record<number, number>, startLine: number, endLine: number): number;
+/**
+ * Get repository metadata (URL, branch, commit, author)
+ */
+declare function getRepoMetadata(directory: string): {
+    url?: string;
+    branch?: string;
+    commit?: 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 };

package/dist/index.d.ts

@@ -1,7 +1,8 @@
-import { ScanOptions, AIReadyConfig, CostConfig, ModelContextTier, ComprehensionDifficulty, ProductivityImpact, ToolScoringOutput, AcceptancePrediction, LanguageParser, Language, ParseResult, NamingConvention } from './client.js';
+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';
 
 declare const DEFAULT_EXCLUDE: string[];
+declare const VAGUE_FILE_NAMES: Set<string>;
 /**
  * Scan files in a directory using glob patterns
  *
@@ -12,6 +13,14 @@ declare const DEFAULT_EXCLUDE: string[];
  * @returns Array of absolute file paths matching the patterns
  */
 declare function scanFiles(options: ScanOptions): Promise<string[]>;
+/**
+ * Scan for both files and directories, respecting ignore rules.
+ * Useful for tools that need to analyze directory structure.
+ */
+declare function scanEntries(options: ScanOptions): Promise<{
+    files: string[];
+    dirs: string[];
+}>;
 declare function readFileContent(filePath: string): Promise<string>;
 declare function getFileExtension(filePath: string): string;
 declare function isSourceFile(filePath: string): boolean;
@@ -139,7 +148,7 @@ interface ModelPricingPreset {
 }
 declare const MODEL_PRICING_PRESETS: Record<string, ModelPricingPreset>;
 /**
- * Get a model pricing preset by ID, with fallback to gpt-4o
+ * Get a model pricing preset by ID, with fallback to claude-4.6 (2026 default)
  */
 declare function getModelPreset(modelId: string): ModelPricingPreset;
 /**
@@ -228,11 +237,38 @@ interface DebtBreakdown {
  */
 declare const DEFAULT_COST_CONFIG: CostConfig;
 /**
- * Calculate estimated monthly cost of AI context waste
+ * @deprecated Since v0.13. Use calculateTokenBudget() + estimateCostFromBudget() instead.
+ * Dollar costs are volatile based on technology; token budgets are stable unit economics.
  *
- * Formula: (tokenWaste / 1000) × pricePer1K × queriesPerDev × devCount × days
+ * Calculate estimated monthly cost of AI context waste with confidence intervals.
  */
-declare function calculateMonthlyCost(tokenWaste: number, config?: Partial<CostConfig>): number;
+declare function calculateMonthlyCost(tokenWaste: number, config?: Partial<CostConfig>): {
+    total: number;
+    range: [number, number];
+    confidence: number;
+};
+/**
+ * Calculate token budget and unit economics for AI interactions.
+ * Technology-agnostic metric that remains valid across model generations.
+ */
+declare function calculateTokenBudget(params: {
+    totalContextTokens: number;
+    estimatedResponseTokens?: number;
+    wastedTokens: {
+        duplication: number;
+        fragmentation: number;
+        chattiness: number;
+    };
+}): TokenBudget;
+/**
+ * Estimate dollar cost from a token budget using model presets.
+ * Note: Use this for presentation only. Token budgets are the primary metric.
+ */
+declare function estimateCostFromBudget(budget: TokenBudget, model: ModelPricingPreset, config?: Partial<CostConfig>): {
+    total: number;
+    range: [number, number];
+    confidence: number;
+};
 /**
  * Calculate productivity impact from issues
  */
@@ -244,9 +280,10 @@ declare function calculateProductivityImpact(issues: {
  *
  * 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
+ * - Context efficiency is the strongest single predictor (empirical correlation: r=0.68)
  *
  * Confidence levels:
  * - 3 tools: 0.75 (triangulated estimate)
@@ -316,6 +353,14 @@ declare function calculateTechnicalDebtInterest(params: {
  * Get debt breakdown by category
  */
 declare function getDebtBreakdown(patternCost: number, contextCost: number, consistencyCost: number): DebtBreakdown[];
+/**
+ * Generate a Technical Value Chain for a specific issue
+ */
+declare function generateValueChain(params: {
+    issueType: string;
+    count: number;
+    severity: 'critical' | 'major' | 'minor';
+}): TechnicalValueChain;
 
 /**
  * Parser Factory - Manages language-specific parsers
@@ -826,4 +871,22 @@ declare function exportHistory(rootDir: string, format?: 'json' | 'csv'): string
  */
 declare function clearHistory(rootDir: string): void;
 
-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, type TestabilityIndex, ToolScoringOutput, TypeScriptParser, calculateAgentGrounding, calculateAiSignalClarity, calculateChangeAmplification, calculateCognitiveLoad, calculateComprehensionDifficulty, calculateConceptCohesion, calculateDependencyHealth, calculateDocDrift, calculateExtendedFutureProofScore, calculateFutureProofScore, calculateImportSimilarity, calculateKnowledgeConcentration, calculateMonthlyCost, calculatePatternEntropy, calculateProductivityImpact, calculateRemediationVelocity, calculateScoreTrend, calculateSemanticDistance, calculateTechnicalDebtInterest, calculateTestabilityIndex, clearHistory, estimateTokens, exportHistory, extractFunctions, extractImports, formatAcceptanceRate, formatCost, formatHours, getDebtBreakdown, getElapsedTime, getFileExtension, getHistorySummary, getModelPreset, getParser, getSupportedLanguages, handleCLIError, handleJSONOutput, isFileSupported, isSourceFile, loadConfig, loadMergedConfig, loadScoreHistory, mergeConfigWithDefaults, parseCode, parseFileExports, predictAcceptanceRate, readFileContent, resolveOutputPath, saveScoreEntry, scanFiles };
+/**
+ * Get git commit timestamps for each line in a file
+ */
+declare function getFileCommitTimestamps(file: string): Record<number, number>;
+/**
+ * Get the latest commit timestamp for a line range
+ */
+declare function getLineRangeLastModifiedCached(lineStamps: Record<number, number>, startLine: number, endLine: number): number;
+/**
+ * Get repository metadata (URL, branch, commit, author)
+ */
+declare function getRepoMetadata(directory: string): {
+    url?: string;
+    branch?: string;
+    commit?: 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 };