@aiready/core 0.9.26 → 0.9.28

package/dist/client.js

@@ -20,17 +20,22 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/client.ts
 var client_exports = {};
 __export(client_exports, {
+  CONTEXT_TIER_THRESHOLDS: () => CONTEXT_TIER_THRESHOLDS,
   DEFAULT_TOOL_WEIGHTS: () => DEFAULT_TOOL_WEIGHTS,
   LANGUAGE_EXTENSIONS: () => LANGUAGE_EXTENSIONS,
   Language: () => Language,
   ParseError: () => ParseError,
+  SIZE_ADJUSTED_THRESHOLDS: () => SIZE_ADJUSTED_THRESHOLDS,
   TOOL_NAME_MAP: () => TOOL_NAME_MAP,
   calculateOverallScore: () => calculateOverallScore,
   formatScore: () => formatScore,
   formatToolScore: () => formatToolScore,
   generateHTML: () => generateHTML,
+  getProjectSizeTier: () => getProjectSizeTier,
   getRating: () => getRating,
   getRatingDisplay: () => getRatingDisplay,
+  getRatingWithContext: () => getRatingWithContext,
+  getRecommendedThreshold: () => getRecommendedThreshold,
   getToolWeight: () => getToolWeight,
   normalizeToolName: () => normalizeToolName,
   parseWeightString: () => parseWeightString
@@ -73,16 +78,57 @@ var DEFAULT_TOOL_WEIGHTS = {
   "pattern-detect": 40,
   "context-analyzer": 35,
   "consistency": 25,
-  "doc-drift": 20,
-  "deps": 15
+  "hallucination-risk": 20,
+  "agent-grounding": 18,
+  "testability": 18,
+  "doc-drift": 15,
+  "deps": 12
 };
 var TOOL_NAME_MAP = {
   "patterns": "pattern-detect",
   "context": "context-analyzer",
   "consistency": "consistency",
+  "hallucination": "hallucination-risk",
+  "hallucination-risk": "hallucination-risk",
+  "grounding": "agent-grounding",
+  "agent-grounding": "agent-grounding",
+  "testability": "testability",
+  "tests": "testability",
   "doc-drift": "doc-drift",
+  "docs": "doc-drift",
   "deps": "deps"
 };
+var CONTEXT_TIER_THRESHOLDS = {
+  compact: { idealTokens: 3e3, criticalTokens: 1e4, idealDepth: 4 },
+  standard: { idealTokens: 5e3, criticalTokens: 15e3, idealDepth: 5 },
+  extended: { idealTokens: 15e3, criticalTokens: 5e4, idealDepth: 7 },
+  frontier: { idealTokens: 5e4, criticalTokens: 15e4, idealDepth: 10 }
+};
+var SIZE_ADJUSTED_THRESHOLDS = {
+  "xs": 80,
+  // < 50 files
+  "small": 75,
+  // 50-200 files
+  "medium": 70,
+  // 200-500 files
+  "large": 65,
+  // 500-2000 files
+  "enterprise": 58
+  // 2000+ files
+};
+function getProjectSizeTier(fileCount) {
+  if (fileCount < 50) return "xs";
+  if (fileCount < 200) return "small";
+  if (fileCount < 500) return "medium";
+  if (fileCount < 2e3) return "large";
+  return "enterprise";
+}
+function getRecommendedThreshold(fileCount, modelTier = "standard") {
+  const sizeTier = getProjectSizeTier(fileCount);
+  const base = SIZE_ADJUSTED_THRESHOLDS[sizeTier];
+  const modelBonus = modelTier === "frontier" ? -3 : modelTier === "extended" ? -2 : 0;
+  return base + modelBonus;
+}
 function normalizeToolName(shortName) {
   return TOOL_NAME_MAP[shortName] || shortName;
 }
@@ -165,6 +211,11 @@ function getRating(score) {
   if (score >= 40) return "Needs Work";
   return "Critical";
 }
+function getRatingWithContext(score, fileCount, modelTier = "standard") {
+  const threshold = getRecommendedThreshold(fileCount, modelTier);
+  const normalized = score - threshold + 70;
+  return getRating(normalized);
+}
 function getRatingDisplay(rating) {
   switch (rating) {
     case "Excellent":
@@ -379,17 +430,22 @@ function generateHTML(graph) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  CONTEXT_TIER_THRESHOLDS,
   DEFAULT_TOOL_WEIGHTS,
   LANGUAGE_EXTENSIONS,
   Language,
   ParseError,
+  SIZE_ADJUSTED_THRESHOLDS,
   TOOL_NAME_MAP,
   calculateOverallScore,
   formatScore,
   formatToolScore,
   generateHTML,
+  getProjectSizeTier,
   getRating,
   getRatingDisplay,
+  getRatingWithContext,
+  getRecommendedThreshold,
   getToolWeight,
   normalizeToolName,
   parseWeightString

package/dist/client.mjs

@@ -1,31 +1,41 @@
 import {
+  CONTEXT_TIER_THRESHOLDS,
   DEFAULT_TOOL_WEIGHTS,
   LANGUAGE_EXTENSIONS,
   Language,
   ParseError,
+  SIZE_ADJUSTED_THRESHOLDS,
   TOOL_NAME_MAP,
   calculateOverallScore,
   formatScore,
   formatToolScore,
   generateHTML,
+  getProjectSizeTier,
   getRating,
   getRatingDisplay,
+  getRatingWithContext,
+  getRecommendedThreshold,
   getToolWeight,
   normalizeToolName,
   parseWeightString
-} from "./chunk-HKSARRCD.mjs";
+} from "./chunk-JJ5JL5FX.mjs";
 export {
+  CONTEXT_TIER_THRESHOLDS,
   DEFAULT_TOOL_WEIGHTS,
   LANGUAGE_EXTENSIONS,
   Language,
   ParseError,
+  SIZE_ADJUSTED_THRESHOLDS,
   TOOL_NAME_MAP,
   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 };