@aiready/core 0.9.27 → 0.9.30

package/dist/client.d.mts

@@ -10,7 +10,7 @@ interface Issue {
     location: Location;
     suggestion?: string;
 }
-type IssueType = 'duplicate-pattern' | 'context-fragmentation' | 'doc-drift' | 'naming-inconsistency' | 'naming-quality' | 'pattern-inconsistency' | 'architecture-inconsistency' | 'dead-code' | 'circular-dependency' | 'missing-types';
+type IssueType = 'duplicate-pattern' | 'context-fragmentation' | 'doc-drift' | 'dependency-health' | 'naming-inconsistency' | 'naming-quality' | 'pattern-inconsistency' | 'architecture-inconsistency' | 'dead-code' | 'circular-dependency' | 'missing-types' | 'hallucination-risk' | 'low-testability' | 'agent-navigation-failure' | 'ambiguous-api' | 'magic-literal' | 'boolean-trap';
 interface Location {
     file: string;
     line: number;
@@ -26,6 +26,18 @@ interface Metrics {
     estimatedMonthlyCost?: number;
     estimatedDeveloperHours?: number;
     comprehensionDifficultyIndex?: number;
+    /** Probability (0-100) that AI will hallucinate in this file/module */
+    hallucinationRiskScore?: number;
+    /** How well an agent can navigate to/from this file unaided (0-100) */
+    agentGroundingScore?: number;
+    /** Whether AI-generated changes to this file can be safely verified (0-100) */
+    testabilityScore?: number;
+    /** Level of documentation drift vs code reality (0-100, higher = more drift) */
+    docDriftScore?: number;
+    /** Health of dependencies in relation to AI training knowledge (0-100) */
+    dependencyHealthScore?: number;
+    /** Model context tier this analysis was calibrated for */
+    modelContextTier?: 'compact' | 'standard' | 'extended' | 'frontier';
 }
 /**
  * Cost estimation configuration
@@ -478,12 +490,63 @@ interface ScoringConfig {
 /**
  * Default weights for known tools.
  * New tools get weight of 10 if not specified.
+ *
+ * Weight philosophy:
+ * - pattern-detect (40): Semantic duplication directly wastes token budget and
+ *   confuses AI with contradictory in-context examples.
+ * - context-analyzer (35): Context limits are the primary hard constraint on
+ *   AI effectiveness regardless of model size.
+ * - consistency (25): Naming/pattern inconsistency degrades AI intent understanding
+ *   proportionally to codebase size.
+ * - hallucination-risk (20): Code patterns empirically causing AI to generate
+ *   confidently wrong outputs — critical for agentic use cases.
+ * - agent-grounding (18): How well an autonomous agent can navigate unaided —
+ *   increasingly important as agentic workflows grow.
+ * - testability (18): AI changes without verifiability create hidden risk.
+ * - doc-drift (15): Stale docs actively mislead AI; planned spoke.
+ * - deps (12): Dependency health affects AI suggestion accuracy; planned spoke.
  */
 declare const DEFAULT_TOOL_WEIGHTS: Record<string, number>;
 /**
  * Tool name normalization map (shorthand -> full name)
  */
 declare const TOOL_NAME_MAP: Record<string, string>;
+/**
+ * Model context tiers for context-aware threshold calibration.
+ *
+ * As AI models evolve from 32k → 128k → 1M+ context windows, absolute token
+ * thresholds become meaningless. Use these tiers to adjust context-analyzer
+ * thresholds relative to the model your team uses.
+ */
+type ModelContextTier = 'compact' | 'standard' | 'extended' | 'frontier';
+/**
+ * Context budget thresholds per tier.
+ * Scores are interpolated between these boundaries.
+ */
+declare const CONTEXT_TIER_THRESHOLDS: Record<ModelContextTier, {
+    /** Below this → full score for context budget */
+    idealTokens: number;
+    /** Above this → critical penalty for context budget */
+    criticalTokens: number;
+    /** Suggested max import depth before penalty */
+    idealDepth: number;
+}>;
+/**
+ * Project-size-adjusted minimum thresholds.
+ *
+ * Large codebases structurally accrue more issues. A score of 65 in an
+ * enterprise codebase is roughly equivalent to 75 in a small project.
+ * These are recommended minimum passing thresholds by project size.
+ */
+declare const SIZE_ADJUSTED_THRESHOLDS: Record<string, number>;
+/**
+ * Determine project size tier from file count
+ */
+declare function getProjectSizeTier(fileCount: number): keyof typeof SIZE_ADJUSTED_THRESHOLDS;
+/**
+ * Get the recommended minimum threshold for a project
+ */
+declare function getRecommendedThreshold(fileCount: number, modelTier?: ModelContextTier): number;
 /**
  * Normalize tool name from shorthand to full name
  */
@@ -515,6 +578,11 @@ declare function calculateOverallScore(toolOutputs: Map<string, ToolScoringOutpu
  * Convert numeric score to rating category
  */
 declare function getRating(score: number): ScoringResult['rating'];
+/**
+ * Convert score to rating with project-size awareness.
+ * Use this for display to give fairer assessment to large codebases.
+ */
+declare function getRatingWithContext(score: number, fileCount: number, modelTier?: ModelContextTier): ScoringResult['rating'];
 /**
  * Get rating emoji and color for display
  */
@@ -544,4 +612,4 @@ declare function formatToolScore(output: ToolScoringOutput): string;
  */
 declare function generateHTML(graph: GraphData): string;
 
-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 };
+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 };

package/dist/client.d.ts

@@ -10,7 +10,7 @@ interface Issue {
     location: Location;
     suggestion?: string;
 }
-type IssueType = 'duplicate-pattern' | 'context-fragmentation' | 'doc-drift' | 'naming-inconsistency' | 'naming-quality' | 'pattern-inconsistency' | 'architecture-inconsistency' | 'dead-code' | 'circular-dependency' | 'missing-types';
+type IssueType = 'duplicate-pattern' | 'context-fragmentation' | 'doc-drift' | 'dependency-health' | 'naming-inconsistency' | 'naming-quality' | 'pattern-inconsistency' | 'architecture-inconsistency' | 'dead-code' | 'circular-dependency' | 'missing-types' | 'hallucination-risk' | 'low-testability' | 'agent-navigation-failure' | 'ambiguous-api' | 'magic-literal' | 'boolean-trap';
 interface Location {
     file: string;
     line: number;
@@ -26,6 +26,18 @@ interface Metrics {
     estimatedMonthlyCost?: number;
     estimatedDeveloperHours?: number;
     comprehensionDifficultyIndex?: number;
+    /** Probability (0-100) that AI will hallucinate in this file/module */
+    hallucinationRiskScore?: number;
+    /** How well an agent can navigate to/from this file unaided (0-100) */
+    agentGroundingScore?: number;
+    /** Whether AI-generated changes to this file can be safely verified (0-100) */
+    testabilityScore?: number;
+    /** Level of documentation drift vs code reality (0-100, higher = more drift) */
+    docDriftScore?: number;
+    /** Health of dependencies in relation to AI training knowledge (0-100) */
+    dependencyHealthScore?: number;
+    /** Model context tier this analysis was calibrated for */
+    modelContextTier?: 'compact' | 'standard' | 'extended' | 'frontier';
 }
 /**
  * Cost estimation configuration
@@ -478,12 +490,63 @@ interface ScoringConfig {
 /**
  * Default weights for known tools.
  * New tools get weight of 10 if not specified.
+ *
+ * Weight philosophy:
+ * - pattern-detect (40): Semantic duplication directly wastes token budget and
+ *   confuses AI with contradictory in-context examples.
+ * - context-analyzer (35): Context limits are the primary hard constraint on
+ *   AI effectiveness regardless of model size.
+ * - consistency (25): Naming/pattern inconsistency degrades AI intent understanding
+ *   proportionally to codebase size.
+ * - hallucination-risk (20): Code patterns empirically causing AI to generate
+ *   confidently wrong outputs — critical for agentic use cases.
+ * - agent-grounding (18): How well an autonomous agent can navigate unaided —
+ *   increasingly important as agentic workflows grow.
+ * - testability (18): AI changes without verifiability create hidden risk.
+ * - doc-drift (15): Stale docs actively mislead AI; planned spoke.
+ * - deps (12): Dependency health affects AI suggestion accuracy; planned spoke.
  */
 declare const DEFAULT_TOOL_WEIGHTS: Record<string, number>;
 /**
  * Tool name normalization map (shorthand -> full name)
  */
 declare const TOOL_NAME_MAP: Record<string, string>;
+/**
+ * Model context tiers for context-aware threshold calibration.
+ *
+ * As AI models evolve from 32k → 128k → 1M+ context windows, absolute token
+ * thresholds become meaningless. Use these tiers to adjust context-analyzer
+ * thresholds relative to the model your team uses.
+ */
+type ModelContextTier = 'compact' | 'standard' | 'extended' | 'frontier';
+/**
+ * Context budget thresholds per tier.
+ * Scores are interpolated between these boundaries.
+ */
+declare const CONTEXT_TIER_THRESHOLDS: Record<ModelContextTier, {
+    /** Below this → full score for context budget */
+    idealTokens: number;
+    /** Above this → critical penalty for context budget */
+    criticalTokens: number;
+    /** Suggested max import depth before penalty */
+    idealDepth: number;
+}>;
+/**
+ * Project-size-adjusted minimum thresholds.
+ *
+ * Large codebases structurally accrue more issues. A score of 65 in an
+ * enterprise codebase is roughly equivalent to 75 in a small project.
+ * These are recommended minimum passing thresholds by project size.
+ */
+declare const SIZE_ADJUSTED_THRESHOLDS: Record<string, number>;
+/**
+ * Determine project size tier from file count
+ */
+declare function getProjectSizeTier(fileCount: number): keyof typeof SIZE_ADJUSTED_THRESHOLDS;
+/**
+ * Get the recommended minimum threshold for a project
+ */
+declare function getRecommendedThreshold(fileCount: number, modelTier?: ModelContextTier): number;
 /**
  * Normalize tool name from shorthand to full name
  */
@@ -515,6 +578,11 @@ declare function calculateOverallScore(toolOutputs: Map<string, ToolScoringOutpu
  * Convert numeric score to rating category
  */
 declare function getRating(score: number): ScoringResult['rating'];
+/**
+ * Convert score to rating with project-size awareness.
+ * Use this for display to give fairer assessment to large codebases.
+ */
+declare function getRatingWithContext(score: number, fileCount: number, modelTier?: ModelContextTier): ScoringResult['rating'];
 /**
  * Get rating emoji and color for display
  */
@@ -544,4 +612,4 @@ declare function formatToolScore(output: ToolScoringOutput): string;
  */
 declare function generateHTML(graph: GraphData): string;
 
-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 };
+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 };

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-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';
+import { ScanOptions, AIReadyConfig, CostConfig, ModelContextTier, ComprehensionDifficulty, ProductivityImpact, 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[];
 /**
@@ -120,8 +120,28 @@ declare function getElapsedTime(startTime: number): string;
  *
  * 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.
  */
 
+/**
+ * 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;
+    pricePer1KInputTokens: number;
+    pricePer1KOutputTokens: number;
+    contextTier: ModelContextTier;
+    /** Approximate daily queries per active dev for this model class */
+    typicalQueriesPerDevPerDay: number;
+}
+declare const MODEL_PRICING_PRESETS: Record<string, ModelPricingPreset>;
+/**
+ * Get a model pricing preset by ID, with fallback to gpt-4o
+ */
+declare function getModelPreset(modelId: string): ModelPricingPreset;
 /**
  * Historical score entry for trend tracking
  */
@@ -203,7 +223,8 @@ interface DebtBreakdown {
 }
 /**
  * Default cost configuration
- * Based on GPT-4 pricing and typical team usage
+ * 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;
 /**
@@ -221,10 +242,16 @@ declare function calculateProductivityImpact(issues: {
 /**
  * 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%
+ * Calibration notes (v0.12):
+ * - GitHub Copilot reports ~30% industry average acceptance rate (2023 blog)
+ * - 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
+ *
+ * Confidence levels:
+ * - 3 tools: 0.75 (triangulated estimate)
+ * - 2 tools: 0.55 (partial estimate)
+ * - 1 tool:  0.35 (weak estimate — don't over-rely)
  */
 declare function predictAcceptanceRate(toolOutputs: Map<string, ToolScoringOutput>): AcceptancePrediction;
 /**
@@ -232,8 +259,12 @@ declare function predictAcceptanceRate(toolOutputs: Map<string, ToolScoringOutpu
  *
  * 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".
  */
-declare function calculateComprehensionDifficulty(contextBudget: number, importDepth: number, fragmentation: number, consistencyScore: number, totalFiles: number): ComprehensionDifficulty;
+declare function calculateComprehensionDifficulty(contextBudget: number, importDepth: number, fragmentation: number, consistencyScore: number, totalFiles: number, modelTier?: ModelContextTier): ComprehensionDifficulty;
 /**
  * Format cost for display
  */
@@ -426,6 +457,11 @@ declare class PythonParser implements LanguageParser {
  * - 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
+ * - Hallucination Risk: 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 hallucination risk, agent grounding, and testability dimensions.
  */
 
 /**
@@ -517,6 +553,221 @@ declare function calculateFutureProofScore(params: {
     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.
+ */
+interface HallucinationRiskSignal {
+    name: string;
+    count: number;
+    riskContribution: number;
+    description: string;
+    examples?: string[];
+}
+/**
+ * Hallucination Risk 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 HallucinationRisk {
+    /** Overall risk score (0-100). Higher = more likely AI will hallucinate. */
+    score: number;
+    rating: 'minimal' | 'low' | 'moderate' | 'high' | 'severe';
+    signals: HallucinationRiskSignal[];
+    /** Most impactful signal to fix first */
+    topRisk: string;
+    recommendations: string[];
+}
+/**
+ * Calculate hallucination risk from code analysis results
+ *
+ * Input data can come from any parser; all inputs are normalized 0-N counts.
+ */
+declare function calculateHallucinationRisk(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;
+}): HallucinationRisk;
+/**
+ * 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.
+ */
+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
+ *
+ * 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;
+interface DocDriftRisk {
+    score: number;
+    rating: 'minimal' | 'low' | 'moderate' | 'high' | 'severe';
+    dimensions: {
+        uncommentedExports: number;
+        outdatedComments: number;
+        undocumentedComplexity: number;
+    };
+    recommendations: string[];
+}
+declare function calculateDocDrift(params: {
+    uncommentedExports: number;
+    totalExports: number;
+    outdatedComments: number;
+    undocumentedComplexity: number;
+}): DocDriftRisk;
+interface DependencyHealthScore {
+    score: number;
+    rating: 'excellent' | 'good' | 'moderate' | 'poor' | 'hazardous';
+    dimensions: {
+        outdatedPackages: number;
+        deprecatedPackages: number;
+        trainingCutoffSkew: number;
+    };
+    aiKnowledgeConfidence: 'high' | 'moderate' | 'low' | 'blind';
+    recommendations: string[];
+}
+declare function calculateDependencyHealth(params: {
+    totalPackages: number;
+    outdatedPackages: number;
+    deprecatedPackages: number;
+    trainingCutoffSkew: number;
+}): DependencyHealthScore;
+/**
+ * Calculate the complete extended future-proof score including all dimensions.
+ * Replaces calculateFutureProofScore when all dimensions are available.
+ */
+declare function calculateExtendedFutureProofScore(params: {
+    cognitiveLoad: CognitiveLoad;
+    patternEntropy: PatternEntropy;
+    conceptCohesion: ConceptCohesion;
+    hallucinationRisk: HallucinationRisk;
+    agentGrounding: AgentGroundingScore;
+    testability: TestabilityIndex;
+    docDrift?: DocDriftRisk;
+    dependencyHealth?: DependencyHealthScore;
+    semanticDistances?: SemanticDistance[];
+}): ToolScoringOutput;
 
 /**
  * Temporal Tracking Utilities
@@ -555,4 +806,4 @@ declare function exportHistory(rootDir: string, format?: 'json' | 'csv'): string
  */
 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 };
+export { AIReadyConfig, type ASTNode, AcceptancePrediction, type AgentGroundingScore, type CLIOptions, type CognitiveLoad, ComprehensionDifficulty, type ConceptCohesion, CostConfig, DEFAULT_COST_CONFIG, DEFAULT_EXCLUDE, type DebtBreakdown, type DependencyHealthScore, type DocDriftRisk, type ExportWithImports, type FileImport, type FileWithDomain, type HallucinationRisk, type HallucinationRiskSignal, 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, calculateCognitiveLoad, calculateComprehensionDifficulty, calculateConceptCohesion, calculateDependencyHealth, calculateDocDrift, calculateExtendedFutureProofScore, calculateFutureProofScore, calculateHallucinationRisk, 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 };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-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';
+import { ScanOptions, AIReadyConfig, CostConfig, ModelContextTier, ComprehensionDifficulty, ProductivityImpact, 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[];
 /**
@@ -120,8 +120,28 @@ declare function getElapsedTime(startTime: number): string;
  *
  * 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.
  */
 
+/**
+ * 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;
+    pricePer1KInputTokens: number;
+    pricePer1KOutputTokens: number;
+    contextTier: ModelContextTier;
+    /** Approximate daily queries per active dev for this model class */
+    typicalQueriesPerDevPerDay: number;
+}
+declare const MODEL_PRICING_PRESETS: Record<string, ModelPricingPreset>;
+/**
+ * Get a model pricing preset by ID, with fallback to gpt-4o
+ */
+declare function getModelPreset(modelId: string): ModelPricingPreset;
 /**
  * Historical score entry for trend tracking
  */
@@ -203,7 +223,8 @@ interface DebtBreakdown {
 }
 /**
  * Default cost configuration
- * Based on GPT-4 pricing and typical team usage
+ * 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;
 /**
@@ -221,10 +242,16 @@ declare function calculateProductivityImpact(issues: {
 /**
  * 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%
+ * Calibration notes (v0.12):
+ * - GitHub Copilot reports ~30% industry average acceptance rate (2023 blog)
+ * - 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
+ *
+ * Confidence levels:
+ * - 3 tools: 0.75 (triangulated estimate)
+ * - 2 tools: 0.55 (partial estimate)
+ * - 1 tool:  0.35 (weak estimate — don't over-rely)
  */
 declare function predictAcceptanceRate(toolOutputs: Map<string, ToolScoringOutput>): AcceptancePrediction;
 /**
@@ -232,8 +259,12 @@ declare function predictAcceptanceRate(toolOutputs: Map<string, ToolScoringOutpu
  *
  * 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".
  */
-declare function calculateComprehensionDifficulty(contextBudget: number, importDepth: number, fragmentation: number, consistencyScore: number, totalFiles: number): ComprehensionDifficulty;
+declare function calculateComprehensionDifficulty(contextBudget: number, importDepth: number, fragmentation: number, consistencyScore: number, totalFiles: number, modelTier?: ModelContextTier): ComprehensionDifficulty;
 /**
  * Format cost for display
  */
@@ -426,6 +457,11 @@ declare class PythonParser implements LanguageParser {
  * - 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
+ * - Hallucination Risk: 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 hallucination risk, agent grounding, and testability dimensions.
  */
 
 /**
@@ -517,6 +553,221 @@ declare function calculateFutureProofScore(params: {
     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.
+ */
+interface HallucinationRiskSignal {
+    name: string;
+    count: number;
+    riskContribution: number;
+    description: string;
+    examples?: string[];
+}
+/**
+ * Hallucination Risk 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 HallucinationRisk {
+    /** Overall risk score (0-100). Higher = more likely AI will hallucinate. */
+    score: number;
+    rating: 'minimal' | 'low' | 'moderate' | 'high' | 'severe';
+    signals: HallucinationRiskSignal[];
+    /** Most impactful signal to fix first */
+    topRisk: string;
+    recommendations: string[];
+}
+/**
+ * Calculate hallucination risk from code analysis results
+ *
+ * Input data can come from any parser; all inputs are normalized 0-N counts.
+ */
+declare function calculateHallucinationRisk(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;
+}): HallucinationRisk;
+/**
+ * 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.
+ */
+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
+ *
+ * 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;
+interface DocDriftRisk {
+    score: number;
+    rating: 'minimal' | 'low' | 'moderate' | 'high' | 'severe';
+    dimensions: {
+        uncommentedExports: number;
+        outdatedComments: number;
+        undocumentedComplexity: number;
+    };
+    recommendations: string[];
+}
+declare function calculateDocDrift(params: {
+    uncommentedExports: number;
+    totalExports: number;
+    outdatedComments: number;
+    undocumentedComplexity: number;
+}): DocDriftRisk;
+interface DependencyHealthScore {
+    score: number;
+    rating: 'excellent' | 'good' | 'moderate' | 'poor' | 'hazardous';
+    dimensions: {
+        outdatedPackages: number;
+        deprecatedPackages: number;
+        trainingCutoffSkew: number;
+    };
+    aiKnowledgeConfidence: 'high' | 'moderate' | 'low' | 'blind';
+    recommendations: string[];
+}
+declare function calculateDependencyHealth(params: {
+    totalPackages: number;
+    outdatedPackages: number;
+    deprecatedPackages: number;
+    trainingCutoffSkew: number;
+}): DependencyHealthScore;
+/**
+ * Calculate the complete extended future-proof score including all dimensions.
+ * Replaces calculateFutureProofScore when all dimensions are available.
+ */
+declare function calculateExtendedFutureProofScore(params: {
+    cognitiveLoad: CognitiveLoad;
+    patternEntropy: PatternEntropy;
+    conceptCohesion: ConceptCohesion;
+    hallucinationRisk: HallucinationRisk;
+    agentGrounding: AgentGroundingScore;
+    testability: TestabilityIndex;
+    docDrift?: DocDriftRisk;
+    dependencyHealth?: DependencyHealthScore;
+    semanticDistances?: SemanticDistance[];
+}): ToolScoringOutput;
 
 /**
  * Temporal Tracking Utilities
@@ -555,4 +806,4 @@ declare function exportHistory(rootDir: string, format?: 'json' | 'csv'): string
  */
 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 };
+export { AIReadyConfig, type ASTNode, AcceptancePrediction, type AgentGroundingScore, type CLIOptions, type CognitiveLoad, ComprehensionDifficulty, type ConceptCohesion, CostConfig, DEFAULT_COST_CONFIG, DEFAULT_EXCLUDE, type DebtBreakdown, type DependencyHealthScore, type DocDriftRisk, type ExportWithImports, type FileImport, type FileWithDomain, type HallucinationRisk, type HallucinationRiskSignal, 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, calculateCognitiveLoad, calculateComprehensionDifficulty, calculateConceptCohesion, calculateDependencyHealth, calculateDocDrift, calculateExtendedFutureProofScore, calculateFutureProofScore, calculateHallucinationRisk, 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 };

package/dist/index.js

@@ -47,6 +47,8 @@ __export(index_exports, {
   calculateCognitiveLoad: () => calculateCognitiveLoad,
   calculateComprehensionDifficulty: () => calculateComprehensionDifficulty,
   calculateConceptCohesion: () => calculateConceptCohesion,
+  calculateDependencyHealth: () => calculateDependencyHealth,
+  calculateDocDrift: () => calculateDocDrift,
   calculateExtendedFutureProofScore: () => calculateExtendedFutureProofScore,
   calculateFutureProofScore: () => calculateFutureProofScore,
   calculateHallucinationRisk: () => calculateHallucinationRisk,
@@ -2303,6 +2305,85 @@ function calculateTestabilityIndex(params) {
     recommendations
   };
 }
+function calculateDocDrift(params) {
+  const { uncommentedExports, totalExports, outdatedComments, undocumentedComplexity } = params;
+  const uncommentedRatio = totalExports > 0 ? uncommentedExports / totalExports : 0;
+  const outdatedScore = Math.min(100, outdatedComments * 15);
+  const uncommentedScore = Math.min(100, uncommentedRatio * 100);
+  const complexityScore = Math.min(100, undocumentedComplexity * 10);
+  const score = Math.round(
+    outdatedScore * 0.6 + uncommentedScore * 0.2 + complexityScore * 0.2
+  );
+  const finalScore = Math.min(100, Math.max(0, score));
+  let rating;
+  if (finalScore < 10) rating = "minimal";
+  else if (finalScore < 30) rating = "low";
+  else if (finalScore < 60) rating = "moderate";
+  else if (finalScore < 85) rating = "high";
+  else rating = "severe";
+  const recommendations = [];
+  if (outdatedComments > 0) {
+    recommendations.push(`Update or remove ${outdatedComments} outdated comments that contradict the code.`);
+  }
+  if (uncommentedRatio > 0.3) {
+    recommendations.push(`Add JSDoc to ${uncommentedExports} uncommented exports.`);
+  }
+  if (undocumentedComplexity > 0) {
+    recommendations.push(`Explain the business logic for ${undocumentedComplexity} highly complex functions.`);
+  }
+  return {
+    score: finalScore,
+    rating,
+    dimensions: {
+      uncommentedExports,
+      outdatedComments,
+      undocumentedComplexity
+    },
+    recommendations
+  };
+}
+function calculateDependencyHealth(params) {
+  const { totalPackages, outdatedPackages, deprecatedPackages, trainingCutoffSkew } = params;
+  const outdatedRatio = totalPackages > 0 ? outdatedPackages / totalPackages : 0;
+  const deprecatedRatio = totalPackages > 0 ? deprecatedPackages / totalPackages : 0;
+  const outdatedScore = Math.max(0, 100 - outdatedRatio * 200);
+  const deprecatedScore = Math.max(0, 100 - deprecatedRatio * 500);
+  const skewScore = Math.max(0, 100 - trainingCutoffSkew * 100);
+  const rawScore = outdatedScore * 0.3 + deprecatedScore * 0.4 + skewScore * 0.3;
+  const score = Math.round(Math.min(100, Math.max(0, rawScore)));
+  let rating;
+  if (score >= 85) rating = "excellent";
+  else if (score >= 70) rating = "good";
+  else if (score >= 50) rating = "moderate";
+  else if (score >= 30) rating = "poor";
+  else rating = "hazardous";
+  let aiKnowledgeConfidence;
+  if (trainingCutoffSkew < 0.2 && deprecatedPackages === 0) aiKnowledgeConfidence = "high";
+  else if (trainingCutoffSkew < 0.5 && deprecatedPackages <= 2) aiKnowledgeConfidence = "moderate";
+  else if (trainingCutoffSkew < 0.8) aiKnowledgeConfidence = "low";
+  else aiKnowledgeConfidence = "blind";
+  const recommendations = [];
+  if (deprecatedPackages > 0) {
+    recommendations.push(`Replace ${deprecatedPackages} deprecated packages, as AI will struggle to find modern solutions.`);
+  }
+  if (outdatedRatio > 0.2) {
+    recommendations.push(`Update ${outdatedPackages} outdated packages to keep APIs aligned with AI training data.`);
+  }
+  if (trainingCutoffSkew > 0.5) {
+    recommendations.push("High training cutoff skew detected. AI may hallucinate APIs that were introduced recently.");
+  }
+  return {
+    score,
+    rating,
+    dimensions: {
+      outdatedPackages,
+      deprecatedPackages,
+      trainingCutoffSkew
+    },
+    aiKnowledgeConfidence,
+    recommendations
+  };
+}
 function calculateExtendedFutureProofScore(params) {
   const loadScore = 100 - params.cognitiveLoad.score;
   const entropyScore = 100 - params.patternEntropy.entropy * 100;
@@ -2310,9 +2391,19 @@ function calculateExtendedFutureProofScore(params) {
   const hallucinationScore = 100 - params.hallucinationRisk.score;
   const groundingScore = params.agentGrounding.score;
   const testabilityScore = params.testability.score;
-  const overall = Math.round(
-    loadScore * 0.2 + entropyScore * 0.15 + cohesionScore * 0.15 + hallucinationScore * 0.2 + groundingScore * 0.15 + testabilityScore * 0.15
-  );
+  const docDriftScore = params.docDrift ? 100 - params.docDrift.score : 100;
+  const depsHealthScore = params.dependencyHealth ? params.dependencyHealth.score : 100;
+  let totalWeight = 0.8;
+  let overall = loadScore * 0.15 + entropyScore * 0.1 + cohesionScore * 0.1 + hallucinationScore * 0.15 + groundingScore * 0.15 + testabilityScore * 0.15;
+  if (params.docDrift) {
+    overall += docDriftScore * 0.1;
+    totalWeight += 0.1;
+  }
+  if (params.dependencyHealth) {
+    overall += depsHealthScore * 0.1;
+    totalWeight += 0.1;
+  }
+  overall = Math.round(overall / totalWeight);
   const factors = [
     {
       name: "Cognitive Load",
@@ -2345,6 +2436,20 @@ function calculateExtendedFutureProofScore(params) {
       description: `${params.testability.rating} \u2014 AI changes are ${params.testability.aiChangeSafetyRating}`
     }
   ];
+  if (params.docDrift) {
+    factors.push({
+      name: "Documentation Drift",
+      impact: Math.round(docDriftScore - 50),
+      description: `${params.docDrift.rating} risk of hallucination from drift`
+    });
+  }
+  if (params.dependencyHealth) {
+    factors.push({
+      name: "Dependency Health",
+      impact: Math.round(depsHealthScore - 50),
+      description: `${params.dependencyHealth.rating} health \u2014 AI knowledge is ${params.dependencyHealth.aiKnowledgeConfidence}`
+    });
+  }
   const recommendations = [];
   for (const rec of params.hallucinationRisk.recommendations) {
     recommendations.push({ action: rec, estimatedImpact: 8, priority: "high" });
@@ -2359,6 +2464,16 @@ function calculateExtendedFutureProofScore(params) {
   for (const rec of params.patternEntropy.recommendations) {
     recommendations.push({ action: rec, estimatedImpact: 5, priority: "low" });
   }
+  if (params.docDrift) {
+    for (const rec of params.docDrift.recommendations) {
+      recommendations.push({ action: rec, estimatedImpact: 8, priority: "high" });
+    }
+  }
+  if (params.dependencyHealth) {
+    for (const rec of params.dependencyHealth.recommendations) {
+      recommendations.push({ action: rec, estimatedImpact: 7, priority: "medium" });
+    }
+  }
   const semanticDistanceAvg = params.semanticDistances && params.semanticDistances.length > 0 ? params.semanticDistances.reduce((s, d) => s + d.distance, 0) / params.semanticDistances.length : 0;
   return {
     toolName: "future-proof",
@@ -2370,6 +2485,8 @@ function calculateExtendedFutureProofScore(params) {
       hallucinationRiskScore: params.hallucinationRisk.score,
       agentGroundingScore: params.agentGrounding.score,
       testabilityScore: params.testability.score,
+      docDriftScore: params.docDrift?.score,
+      dependencyHealthScore: params.dependencyHealth?.score,
       semanticDistanceAvg
     },
     factors,
@@ -2469,6 +2586,8 @@ function clearHistory(rootDir) {
   calculateCognitiveLoad,
   calculateComprehensionDifficulty,
   calculateConceptCohesion,
+  calculateDependencyHealth,
+  calculateDocDrift,
   calculateExtendedFutureProofScore,
   calculateFutureProofScore,
   calculateHallucinationRisk,

package/dist/index.mjs

@@ -1831,6 +1831,85 @@ function calculateTestabilityIndex(params) {
     recommendations
   };
 }
+function calculateDocDrift(params) {
+  const { uncommentedExports, totalExports, outdatedComments, undocumentedComplexity } = params;
+  const uncommentedRatio = totalExports > 0 ? uncommentedExports / totalExports : 0;
+  const outdatedScore = Math.min(100, outdatedComments * 15);
+  const uncommentedScore = Math.min(100, uncommentedRatio * 100);
+  const complexityScore = Math.min(100, undocumentedComplexity * 10);
+  const score = Math.round(
+    outdatedScore * 0.6 + uncommentedScore * 0.2 + complexityScore * 0.2
+  );
+  const finalScore = Math.min(100, Math.max(0, score));
+  let rating;
+  if (finalScore < 10) rating = "minimal";
+  else if (finalScore < 30) rating = "low";
+  else if (finalScore < 60) rating = "moderate";
+  else if (finalScore < 85) rating = "high";
+  else rating = "severe";
+  const recommendations = [];
+  if (outdatedComments > 0) {
+    recommendations.push(`Update or remove ${outdatedComments} outdated comments that contradict the code.`);
+  }
+  if (uncommentedRatio > 0.3) {
+    recommendations.push(`Add JSDoc to ${uncommentedExports} uncommented exports.`);
+  }
+  if (undocumentedComplexity > 0) {
+    recommendations.push(`Explain the business logic for ${undocumentedComplexity} highly complex functions.`);
+  }
+  return {
+    score: finalScore,
+    rating,
+    dimensions: {
+      uncommentedExports,
+      outdatedComments,
+      undocumentedComplexity
+    },
+    recommendations
+  };
+}
+function calculateDependencyHealth(params) {
+  const { totalPackages, outdatedPackages, deprecatedPackages, trainingCutoffSkew } = params;
+  const outdatedRatio = totalPackages > 0 ? outdatedPackages / totalPackages : 0;
+  const deprecatedRatio = totalPackages > 0 ? deprecatedPackages / totalPackages : 0;
+  const outdatedScore = Math.max(0, 100 - outdatedRatio * 200);
+  const deprecatedScore = Math.max(0, 100 - deprecatedRatio * 500);
+  const skewScore = Math.max(0, 100 - trainingCutoffSkew * 100);
+  const rawScore = outdatedScore * 0.3 + deprecatedScore * 0.4 + skewScore * 0.3;
+  const score = Math.round(Math.min(100, Math.max(0, rawScore)));
+  let rating;
+  if (score >= 85) rating = "excellent";
+  else if (score >= 70) rating = "good";
+  else if (score >= 50) rating = "moderate";
+  else if (score >= 30) rating = "poor";
+  else rating = "hazardous";
+  let aiKnowledgeConfidence;
+  if (trainingCutoffSkew < 0.2 && deprecatedPackages === 0) aiKnowledgeConfidence = "high";
+  else if (trainingCutoffSkew < 0.5 && deprecatedPackages <= 2) aiKnowledgeConfidence = "moderate";
+  else if (trainingCutoffSkew < 0.8) aiKnowledgeConfidence = "low";
+  else aiKnowledgeConfidence = "blind";
+  const recommendations = [];
+  if (deprecatedPackages > 0) {
+    recommendations.push(`Replace ${deprecatedPackages} deprecated packages, as AI will struggle to find modern solutions.`);
+  }
+  if (outdatedRatio > 0.2) {
+    recommendations.push(`Update ${outdatedPackages} outdated packages to keep APIs aligned with AI training data.`);
+  }
+  if (trainingCutoffSkew > 0.5) {
+    recommendations.push("High training cutoff skew detected. AI may hallucinate APIs that were introduced recently.");
+  }
+  return {
+    score,
+    rating,
+    dimensions: {
+      outdatedPackages,
+      deprecatedPackages,
+      trainingCutoffSkew
+    },
+    aiKnowledgeConfidence,
+    recommendations
+  };
+}
 function calculateExtendedFutureProofScore(params) {
   const loadScore = 100 - params.cognitiveLoad.score;
   const entropyScore = 100 - params.patternEntropy.entropy * 100;
@@ -1838,9 +1917,19 @@ function calculateExtendedFutureProofScore(params) {
   const hallucinationScore = 100 - params.hallucinationRisk.score;
   const groundingScore = params.agentGrounding.score;
   const testabilityScore = params.testability.score;
-  const overall = Math.round(
-    loadScore * 0.2 + entropyScore * 0.15 + cohesionScore * 0.15 + hallucinationScore * 0.2 + groundingScore * 0.15 + testabilityScore * 0.15
-  );
+  const docDriftScore = params.docDrift ? 100 - params.docDrift.score : 100;
+  const depsHealthScore = params.dependencyHealth ? params.dependencyHealth.score : 100;
+  let totalWeight = 0.8;
+  let overall = loadScore * 0.15 + entropyScore * 0.1 + cohesionScore * 0.1 + hallucinationScore * 0.15 + groundingScore * 0.15 + testabilityScore * 0.15;
+  if (params.docDrift) {
+    overall += docDriftScore * 0.1;
+    totalWeight += 0.1;
+  }
+  if (params.dependencyHealth) {
+    overall += depsHealthScore * 0.1;
+    totalWeight += 0.1;
+  }
+  overall = Math.round(overall / totalWeight);
   const factors = [
     {
       name: "Cognitive Load",
@@ -1873,6 +1962,20 @@ function calculateExtendedFutureProofScore(params) {
       description: `${params.testability.rating} \u2014 AI changes are ${params.testability.aiChangeSafetyRating}`
     }
   ];
+  if (params.docDrift) {
+    factors.push({
+      name: "Documentation Drift",
+      impact: Math.round(docDriftScore - 50),
+      description: `${params.docDrift.rating} risk of hallucination from drift`
+    });
+  }
+  if (params.dependencyHealth) {
+    factors.push({
+      name: "Dependency Health",
+      impact: Math.round(depsHealthScore - 50),
+      description: `${params.dependencyHealth.rating} health \u2014 AI knowledge is ${params.dependencyHealth.aiKnowledgeConfidence}`
+    });
+  }
   const recommendations = [];
   for (const rec of params.hallucinationRisk.recommendations) {
     recommendations.push({ action: rec, estimatedImpact: 8, priority: "high" });
@@ -1887,6 +1990,16 @@ function calculateExtendedFutureProofScore(params) {
   for (const rec of params.patternEntropy.recommendations) {
     recommendations.push({ action: rec, estimatedImpact: 5, priority: "low" });
   }
+  if (params.docDrift) {
+    for (const rec of params.docDrift.recommendations) {
+      recommendations.push({ action: rec, estimatedImpact: 8, priority: "high" });
+    }
+  }
+  if (params.dependencyHealth) {
+    for (const rec of params.dependencyHealth.recommendations) {
+      recommendations.push({ action: rec, estimatedImpact: 7, priority: "medium" });
+    }
+  }
   const semanticDistanceAvg = params.semanticDistances && params.semanticDistances.length > 0 ? params.semanticDistances.reduce((s, d) => s + d.distance, 0) / params.semanticDistances.length : 0;
   return {
     toolName: "future-proof",
@@ -1898,6 +2011,8 @@ function calculateExtendedFutureProofScore(params) {
       hallucinationRiskScore: params.hallucinationRisk.score,
       agentGroundingScore: params.agentGrounding.score,
       testabilityScore: params.testability.score,
+      docDriftScore: params.docDrift?.score,
+      dependencyHealthScore: params.dependencyHealth?.score,
       semanticDistanceAvg
     },
     factors,
@@ -1996,6 +2111,8 @@ export {
   calculateCognitiveLoad,
   calculateComprehensionDifficulty,
   calculateConceptCohesion,
+  calculateDependencyHealth,
+  calculateDocDrift,
   calculateExtendedFutureProofScore,
   calculateFutureProofScore,
   calculateHallucinationRisk,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiready/core",
-  "version": "0.9.27",
+  "version": "0.9.30",
   "description": "Shared utilities for AIReady analysis tools",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",