@aiready/core 0.9.30 → 0.9.32

package/dist/index.d.mts

@@ -457,11 +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
+ * - AI Signal Clarity: How likely AI is to generate incorrect code
  * - Agent Grounding Score: How well an agent can navigate unaided
  * - Testability Index: How verifiable AI-generated changes are
  *
- * v0.12+: Added hallucination risk, agent grounding, and testability dimensions.
+ * v0.12+: Added AI signal clarity, agent grounding, and testability dimensions.
  */
 
 /**
@@ -557,7 +557,7 @@ declare function calculateFutureProofScore(params: {
  * Signals that increase the likelihood of AI generating incorrect code.
  * Technology-agnostic: these patterns confuse both current and future AI.
  */
-interface HallucinationRiskSignal {
+interface AiSignalClaritySignal {
     name: string;
     count: number;
     riskContribution: number;
@@ -565,7 +565,7 @@ interface HallucinationRiskSignal {
     examples?: string[];
 }
 /**
- * Hallucination Risk Score (0-100, higher = more risk)
+ * AI Signal Clarity Score (0-100, higher = more risk)
  *
  * Measures code patterns that empirically cause AI models to:
  * - Confidently generate incorrect function signatures
@@ -573,21 +573,21 @@ interface HallucinationRiskSignal {
  * - Miss implicit contracts / side effects
  * - Misunderstand overloaded symbols
  */
-interface HallucinationRisk {
+interface AiSignalClarity {
     /** Overall risk score (0-100). Higher = more likely AI will hallucinate. */
     score: number;
     rating: 'minimal' | 'low' | 'moderate' | 'high' | 'severe';
-    signals: HallucinationRiskSignal[];
+    signals: AiSignalClaritySignal[];
     /** Most impactful signal to fix first */
     topRisk: string;
     recommendations: string[];
 }
 /**
- * Calculate hallucination risk from code analysis results
+ * Calculate AI signal clarity from code analysis results
  *
  * Input data can come from any parser; all inputs are normalized 0-N counts.
  */
-declare function calculateHallucinationRisk(params: {
+declare function calculateAiSignalClarity(params: {
     /** Overloaded function names (same name, different signatures) */
     overloadedSymbols: number;
     /** Magic numbers and string literals without named constants */
@@ -606,7 +606,7 @@ declare function calculateHallucinationRisk(params: {
     totalSymbols: number;
     /** Total exports in codebase */
     totalExports: number;
-}): HallucinationRisk;
+}): AiSignalClarity;
 /**
  * Agent Grounding Score
  *
@@ -753,6 +753,26 @@ declare function calculateDependencyHealth(params: {
     deprecatedPackages: number;
     trainingCutoffSkew: number;
 }): DependencyHealthScore;
+interface ChangeAmplificationScore {
+    score: number;
+    rating: 'isolated' | 'contained' | 'amplified' | 'explosive';
+    avgAmplification: number;
+    maxAmplification: number;
+    hotspots: Array<{
+        file: string;
+        fanOut: number;
+        fanIn: number;
+        amplificationFactor: number;
+    }>;
+    recommendations: string[];
+}
+declare function calculateChangeAmplification(params: {
+    files: Array<{
+        file: string;
+        fanOut: number;
+        fanIn: number;
+    }>;
+}): ChangeAmplificationScore;
 /**
  * Calculate the complete extended future-proof score including all dimensions.
  * Replaces calculateFutureProofScore when all dimensions are available.
@@ -761,7 +781,7 @@ declare function calculateExtendedFutureProofScore(params: {
     cognitiveLoad: CognitiveLoad;
     patternEntropy: PatternEntropy;
     conceptCohesion: ConceptCohesion;
-    hallucinationRisk: HallucinationRisk;
+    aiSignalClarity: AiSignalClarity;
     agentGrounding: AgentGroundingScore;
     testability: TestabilityIndex;
     docDrift?: DocDriftRisk;
@@ -806,4 +826,4 @@ declare function exportHistory(rootDir: string, format?: 'json' | 'csv'): string
  */
 declare function clearHistory(rootDir: string): void;
 
-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 };
+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 };

package/dist/index.d.ts

@@ -457,11 +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
+ * - AI Signal Clarity: How likely AI is to generate incorrect code
  * - Agent Grounding Score: How well an agent can navigate unaided
  * - Testability Index: How verifiable AI-generated changes are
  *
- * v0.12+: Added hallucination risk, agent grounding, and testability dimensions.
+ * v0.12+: Added AI signal clarity, agent grounding, and testability dimensions.
  */
 
 /**
@@ -557,7 +557,7 @@ declare function calculateFutureProofScore(params: {
  * Signals that increase the likelihood of AI generating incorrect code.
  * Technology-agnostic: these patterns confuse both current and future AI.
  */
-interface HallucinationRiskSignal {
+interface AiSignalClaritySignal {
     name: string;
     count: number;
     riskContribution: number;
@@ -565,7 +565,7 @@ interface HallucinationRiskSignal {
     examples?: string[];
 }
 /**
- * Hallucination Risk Score (0-100, higher = more risk)
+ * AI Signal Clarity Score (0-100, higher = more risk)
  *
  * Measures code patterns that empirically cause AI models to:
  * - Confidently generate incorrect function signatures
@@ -573,21 +573,21 @@ interface HallucinationRiskSignal {
  * - Miss implicit contracts / side effects
  * - Misunderstand overloaded symbols
  */
-interface HallucinationRisk {
+interface AiSignalClarity {
     /** Overall risk score (0-100). Higher = more likely AI will hallucinate. */
     score: number;
     rating: 'minimal' | 'low' | 'moderate' | 'high' | 'severe';
-    signals: HallucinationRiskSignal[];
+    signals: AiSignalClaritySignal[];
     /** Most impactful signal to fix first */
     topRisk: string;
     recommendations: string[];
 }
 /**
- * Calculate hallucination risk from code analysis results
+ * Calculate AI signal clarity from code analysis results
  *
  * Input data can come from any parser; all inputs are normalized 0-N counts.
  */
-declare function calculateHallucinationRisk(params: {
+declare function calculateAiSignalClarity(params: {
     /** Overloaded function names (same name, different signatures) */
     overloadedSymbols: number;
     /** Magic numbers and string literals without named constants */
@@ -606,7 +606,7 @@ declare function calculateHallucinationRisk(params: {
     totalSymbols: number;
     /** Total exports in codebase */
     totalExports: number;
-}): HallucinationRisk;
+}): AiSignalClarity;
 /**
  * Agent Grounding Score
  *
@@ -753,6 +753,26 @@ declare function calculateDependencyHealth(params: {
     deprecatedPackages: number;
     trainingCutoffSkew: number;
 }): DependencyHealthScore;
+interface ChangeAmplificationScore {
+    score: number;
+    rating: 'isolated' | 'contained' | 'amplified' | 'explosive';
+    avgAmplification: number;
+    maxAmplification: number;
+    hotspots: Array<{
+        file: string;
+        fanOut: number;
+        fanIn: number;
+        amplificationFactor: number;
+    }>;
+    recommendations: string[];
+}
+declare function calculateChangeAmplification(params: {
+    files: Array<{
+        file: string;
+        fanOut: number;
+        fanIn: number;
+    }>;
+}): ChangeAmplificationScore;
 /**
  * Calculate the complete extended future-proof score including all dimensions.
  * Replaces calculateFutureProofScore when all dimensions are available.
@@ -761,7 +781,7 @@ declare function calculateExtendedFutureProofScore(params: {
     cognitiveLoad: CognitiveLoad;
     patternEntropy: PatternEntropy;
     conceptCohesion: ConceptCohesion;
-    hallucinationRisk: HallucinationRisk;
+    aiSignalClarity: AiSignalClarity;
     agentGrounding: AgentGroundingScore;
     testability: TestabilityIndex;
     docDrift?: DocDriftRisk;
@@ -806,4 +826,4 @@ declare function exportHistory(rootDir: string, format?: 'json' | 'csv'): string
  */
 declare function clearHistory(rootDir: string): void;
 
-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 };
+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 };

package/dist/index.js

@@ -44,6 +44,8 @@ __export(index_exports, {
   TOOL_NAME_MAP: () => TOOL_NAME_MAP,
   TypeScriptParser: () => TypeScriptParser,
   calculateAgentGrounding: () => calculateAgentGrounding,
+  calculateAiSignalClarity: () => calculateAiSignalClarity,
+  calculateChangeAmplification: () => calculateChangeAmplification,
   calculateCognitiveLoad: () => calculateCognitiveLoad,
   calculateComprehensionDifficulty: () => calculateComprehensionDifficulty,
   calculateConceptCohesion: () => calculateConceptCohesion,
@@ -51,7 +53,6 @@ __export(index_exports, {
   calculateDocDrift: () => calculateDocDrift,
   calculateExtendedFutureProofScore: () => calculateExtendedFutureProofScore,
   calculateFutureProofScore: () => calculateFutureProofScore,
-  calculateHallucinationRisk: () => calculateHallucinationRisk,
   calculateImportSimilarity: () => calculateImportSimilarity,
   calculateKnowledgeConcentration: () => calculateKnowledgeConcentration,
   calculateMonthlyCost: () => calculateMonthlyCost,
@@ -704,21 +705,21 @@ function generateHTML(graph) {
 
 // src/scoring.ts
 var DEFAULT_TOOL_WEIGHTS = {
-  "pattern-detect": 40,
-  "context-analyzer": 35,
-  "consistency": 25,
-  "hallucination-risk": 20,
-  "agent-grounding": 18,
-  "testability": 18,
-  "doc-drift": 15,
-  "deps": 12
+  "pattern-detect": 22,
+  "context-analyzer": 19,
+  "consistency": 14,
+  "ai-signal-clarity": 11,
+  "agent-grounding": 10,
+  "testability": 10,
+  "doc-drift": 8,
+  "deps": 6
 };
 var TOOL_NAME_MAP = {
   "patterns": "pattern-detect",
   "context": "context-analyzer",
   "consistency": "consistency",
-  "hallucination": "hallucination-risk",
-  "hallucination-risk": "hallucination-risk",
+  "AI signal clarity": "ai-signal-clarity",
+  "ai-signal-clarity": "ai-signal-clarity",
   "grounding": "agent-grounding",
   "agent-grounding": "agent-grounding",
   "testability": "testability",
@@ -768,7 +769,7 @@ function getToolWeight(toolName, toolConfig, cliOverride) {
   if (toolConfig?.scoreWeight !== void 0) {
     return toolConfig.scoreWeight;
   }
-  return DEFAULT_TOOL_WEIGHTS[toolName] || 10;
+  return DEFAULT_TOOL_WEIGHTS[toolName] || 5;
 }
 function parseWeightString(weightStr) {
   const weights = /* @__PURE__ */ new Map();
@@ -1049,11 +1050,11 @@ function predictAcceptanceRate(toolOutputs) {
       impact: Math.round(consistencyImpact * 100)
     });
   }
-  const hallucinationRisk = toolOutputs.get("hallucination-risk");
-  if (hallucinationRisk) {
-    const hrImpact = (50 - hallucinationRisk.score) * 2e-3;
+  const aiSignalClarity = toolOutputs.get("ai-signal-clarity");
+  if (aiSignalClarity) {
+    const hrImpact = (50 - aiSignalClarity.score) * 2e-3;
     factors.push({
-      name: "Hallucination Risk",
+      name: "AI Signal Clarity",
       impact: Math.round(hrImpact * 100)
     });
   }
@@ -2050,7 +2051,7 @@ function calculateFutureProofScore(params) {
     recommendations
   };
 }
-function calculateHallucinationRisk(params) {
+function calculateAiSignalClarity(params) {
   const {
     overloadedSymbols,
     magicLiterals,
@@ -2144,7 +2145,7 @@ function calculateHallucinationRisk(params) {
   else if (score < 75) rating = "high";
   else rating = "severe";
   const topSignal = signals.reduce((a, b) => a.riskContribution > b.riskContribution ? a : b);
-  const topRisk = topSignal.riskContribution > 0 ? topSignal.description : "No significant hallucination risks detected";
+  const topRisk = topSignal.riskContribution > 0 ? topSignal.description : "No significant AI signal claritys detected";
   const recommendations = [];
   if (overloadSignal.riskContribution > 5) {
     recommendations.push(`Rename ${overloadedSymbols} overloaded symbols to unique, intent-revealing names`);
@@ -2384,17 +2385,58 @@ function calculateDependencyHealth(params) {
     recommendations
   };
 }
+function calculateChangeAmplification(params) {
+  const { files } = params;
+  if (files.length === 0) {
+    return {
+      score: 100,
+      rating: "isolated",
+      avgAmplification: 1,
+      maxAmplification: 1,
+      hotspots: [],
+      recommendations: []
+    };
+  }
+  const hotspots = files.map((f) => {
+    const amplificationFactor = f.fanOut + f.fanIn * 0.5;
+    return { ...f, amplificationFactor };
+  }).sort((a, b) => b.amplificationFactor - a.amplificationFactor);
+  const maxAmplification = hotspots[0].amplificationFactor;
+  const avgAmplification = hotspots.reduce((sum, h) => sum + h.amplificationFactor, 0) / hotspots.length;
+  let score = 100 - avgAmplification * 5;
+  if (maxAmplification > 20) score -= maxAmplification - 20;
+  score = Math.max(0, Math.min(100, score));
+  let rating = "isolated";
+  if (score < 40) rating = "explosive";
+  else if (score < 70) rating = "amplified";
+  else if (score < 90) rating = "contained";
+  const recommendations = [];
+  if (score < 70 && hotspots.length > 0) {
+    recommendations.push(`Refactor top hotspot '${hotspots[0].file}' to reduce coupling (fan-out: ${hotspots[0].fanOut}, fan-in: ${hotspots[0].fanIn}).`);
+  }
+  if (maxAmplification > 30) {
+    recommendations.push(`Break down key bottlenecks with amplification factor > 30.`);
+  }
+  return {
+    score: Math.round(score),
+    rating,
+    avgAmplification,
+    maxAmplification,
+    hotspots: hotspots.slice(0, 10),
+    recommendations
+  };
+}
 function calculateExtendedFutureProofScore(params) {
   const loadScore = 100 - params.cognitiveLoad.score;
   const entropyScore = 100 - params.patternEntropy.entropy * 100;
   const cohesionScore = params.conceptCohesion.score * 100;
-  const hallucinationScore = 100 - params.hallucinationRisk.score;
+  const aiSignalClarityScore = 100 - params.aiSignalClarity.score;
   const groundingScore = params.agentGrounding.score;
   const testabilityScore = params.testability.score;
   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;
+  let overall = loadScore * 0.15 + entropyScore * 0.1 + cohesionScore * 0.1 + aiSignalClarityScore * 0.15 + groundingScore * 0.15 + testabilityScore * 0.15;
   if (params.docDrift) {
     overall += docDriftScore * 0.1;
     totalWeight += 0.1;
@@ -2421,9 +2463,9 @@ function calculateExtendedFutureProofScore(params) {
       description: params.conceptCohesion.rating
     },
     {
-      name: "Hallucination Risk",
-      impact: Math.round(hallucinationScore - 50),
-      description: `${params.hallucinationRisk.rating} risk (${params.hallucinationRisk.score}/100 raw)`
+      name: "AI Signal Clarity",
+      impact: Math.round(aiSignalClarityScore - 50),
+      description: `${params.aiSignalClarity.rating} risk (${params.aiSignalClarity.score}/100 raw)`
     },
     {
       name: "Agent Grounding",
@@ -2440,7 +2482,7 @@ function calculateExtendedFutureProofScore(params) {
     factors.push({
       name: "Documentation Drift",
       impact: Math.round(docDriftScore - 50),
-      description: `${params.docDrift.rating} risk of hallucination from drift`
+      description: `${params.docDrift.rating} risk of AI signal clarity from drift`
     });
   }
   if (params.dependencyHealth) {
@@ -2451,7 +2493,7 @@ function calculateExtendedFutureProofScore(params) {
     });
   }
   const recommendations = [];
-  for (const rec of params.hallucinationRisk.recommendations) {
+  for (const rec of params.aiSignalClarity.recommendations) {
     recommendations.push({ action: rec, estimatedImpact: 8, priority: "high" });
   }
   for (const rec of params.agentGrounding.recommendations) {
@@ -2482,7 +2524,7 @@ function calculateExtendedFutureProofScore(params) {
       cognitiveLoadScore: params.cognitiveLoad.score,
       entropyScore: params.patternEntropy.entropy,
       cohesionScore: params.conceptCohesion.score,
-      hallucinationRiskScore: params.hallucinationRisk.score,
+      aiSignalClarityScore: params.aiSignalClarity.score,
       agentGroundingScore: params.agentGrounding.score,
       testabilityScore: params.testability.score,
       docDriftScore: params.docDrift?.score,
@@ -2583,6 +2625,8 @@ function clearHistory(rootDir) {
   TOOL_NAME_MAP,
   TypeScriptParser,
   calculateAgentGrounding,
+  calculateAiSignalClarity,
+  calculateChangeAmplification,
   calculateCognitiveLoad,
   calculateComprehensionDifficulty,
   calculateConceptCohesion,
@@ -2590,7 +2634,6 @@ function clearHistory(rootDir) {
   calculateDocDrift,
   calculateExtendedFutureProofScore,
   calculateFutureProofScore,
-  calculateHallucinationRisk,
   calculateImportSimilarity,
   calculateKnowledgeConcentration,
   calculateMonthlyCost,

package/dist/index.mjs

@@ -18,7 +18,7 @@ import {
   getToolWeight,
   normalizeToolName,
   parseWeightString
-} from "./chunk-JJ5JL5FX.mjs";
+} from "./chunk-CWRCDSKZ.mjs";
 
 // src/utils/file-scanner.ts
 import { glob } from "glob";
@@ -575,11 +575,11 @@ function predictAcceptanceRate(toolOutputs) {
       impact: Math.round(consistencyImpact * 100)
     });
   }
-  const hallucinationRisk = toolOutputs.get("hallucination-risk");
-  if (hallucinationRisk) {
-    const hrImpact = (50 - hallucinationRisk.score) * 2e-3;
+  const aiSignalClarity = toolOutputs.get("ai-signal-clarity");
+  if (aiSignalClarity) {
+    const hrImpact = (50 - aiSignalClarity.score) * 2e-3;
     factors.push({
-      name: "Hallucination Risk",
+      name: "AI Signal Clarity",
       impact: Math.round(hrImpact * 100)
     });
   }
@@ -1576,7 +1576,7 @@ function calculateFutureProofScore(params) {
     recommendations
   };
 }
-function calculateHallucinationRisk(params) {
+function calculateAiSignalClarity(params) {
   const {
     overloadedSymbols,
     magicLiterals,
@@ -1670,7 +1670,7 @@ function calculateHallucinationRisk(params) {
   else if (score < 75) rating = "high";
   else rating = "severe";
   const topSignal = signals.reduce((a, b) => a.riskContribution > b.riskContribution ? a : b);
-  const topRisk = topSignal.riskContribution > 0 ? topSignal.description : "No significant hallucination risks detected";
+  const topRisk = topSignal.riskContribution > 0 ? topSignal.description : "No significant AI signal claritys detected";
   const recommendations = [];
   if (overloadSignal.riskContribution > 5) {
     recommendations.push(`Rename ${overloadedSymbols} overloaded symbols to unique, intent-revealing names`);
@@ -1910,17 +1910,58 @@ function calculateDependencyHealth(params) {
     recommendations
   };
 }
+function calculateChangeAmplification(params) {
+  const { files } = params;
+  if (files.length === 0) {
+    return {
+      score: 100,
+      rating: "isolated",
+      avgAmplification: 1,
+      maxAmplification: 1,
+      hotspots: [],
+      recommendations: []
+    };
+  }
+  const hotspots = files.map((f) => {
+    const amplificationFactor = f.fanOut + f.fanIn * 0.5;
+    return { ...f, amplificationFactor };
+  }).sort((a, b) => b.amplificationFactor - a.amplificationFactor);
+  const maxAmplification = hotspots[0].amplificationFactor;
+  const avgAmplification = hotspots.reduce((sum, h) => sum + h.amplificationFactor, 0) / hotspots.length;
+  let score = 100 - avgAmplification * 5;
+  if (maxAmplification > 20) score -= maxAmplification - 20;
+  score = Math.max(0, Math.min(100, score));
+  let rating = "isolated";
+  if (score < 40) rating = "explosive";
+  else if (score < 70) rating = "amplified";
+  else if (score < 90) rating = "contained";
+  const recommendations = [];
+  if (score < 70 && hotspots.length > 0) {
+    recommendations.push(`Refactor top hotspot '${hotspots[0].file}' to reduce coupling (fan-out: ${hotspots[0].fanOut}, fan-in: ${hotspots[0].fanIn}).`);
+  }
+  if (maxAmplification > 30) {
+    recommendations.push(`Break down key bottlenecks with amplification factor > 30.`);
+  }
+  return {
+    score: Math.round(score),
+    rating,
+    avgAmplification,
+    maxAmplification,
+    hotspots: hotspots.slice(0, 10),
+    recommendations
+  };
+}
 function calculateExtendedFutureProofScore(params) {
   const loadScore = 100 - params.cognitiveLoad.score;
   const entropyScore = 100 - params.patternEntropy.entropy * 100;
   const cohesionScore = params.conceptCohesion.score * 100;
-  const hallucinationScore = 100 - params.hallucinationRisk.score;
+  const aiSignalClarityScore = 100 - params.aiSignalClarity.score;
   const groundingScore = params.agentGrounding.score;
   const testabilityScore = params.testability.score;
   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;
+  let overall = loadScore * 0.15 + entropyScore * 0.1 + cohesionScore * 0.1 + aiSignalClarityScore * 0.15 + groundingScore * 0.15 + testabilityScore * 0.15;
   if (params.docDrift) {
     overall += docDriftScore * 0.1;
     totalWeight += 0.1;
@@ -1947,9 +1988,9 @@ function calculateExtendedFutureProofScore(params) {
       description: params.conceptCohesion.rating
     },
     {
-      name: "Hallucination Risk",
-      impact: Math.round(hallucinationScore - 50),
-      description: `${params.hallucinationRisk.rating} risk (${params.hallucinationRisk.score}/100 raw)`
+      name: "AI Signal Clarity",
+      impact: Math.round(aiSignalClarityScore - 50),
+      description: `${params.aiSignalClarity.rating} risk (${params.aiSignalClarity.score}/100 raw)`
     },
     {
       name: "Agent Grounding",
@@ -1966,7 +2007,7 @@ function calculateExtendedFutureProofScore(params) {
     factors.push({
       name: "Documentation Drift",
       impact: Math.round(docDriftScore - 50),
-      description: `${params.docDrift.rating} risk of hallucination from drift`
+      description: `${params.docDrift.rating} risk of AI signal clarity from drift`
     });
   }
   if (params.dependencyHealth) {
@@ -1977,7 +2018,7 @@ function calculateExtendedFutureProofScore(params) {
     });
   }
   const recommendations = [];
-  for (const rec of params.hallucinationRisk.recommendations) {
+  for (const rec of params.aiSignalClarity.recommendations) {
     recommendations.push({ action: rec, estimatedImpact: 8, priority: "high" });
   }
   for (const rec of params.agentGrounding.recommendations) {
@@ -2008,7 +2049,7 @@ function calculateExtendedFutureProofScore(params) {
       cognitiveLoadScore: params.cognitiveLoad.score,
       entropyScore: params.patternEntropy.entropy,
       cohesionScore: params.conceptCohesion.score,
-      hallucinationRiskScore: params.hallucinationRisk.score,
+      aiSignalClarityScore: params.aiSignalClarity.score,
       agentGroundingScore: params.agentGrounding.score,
       testabilityScore: params.testability.score,
       docDriftScore: params.docDrift?.score,
@@ -2108,6 +2149,8 @@ export {
   TOOL_NAME_MAP,
   TypeScriptParser,
   calculateAgentGrounding,
+  calculateAiSignalClarity,
+  calculateChangeAmplification,
   calculateCognitiveLoad,
   calculateComprehensionDifficulty,
   calculateConceptCohesion,
@@ -2115,7 +2158,6 @@ export {
   calculateDocDrift,
   calculateExtendedFutureProofScore,
   calculateFutureProofScore,
-  calculateHallucinationRisk,
   calculateImportSimilarity,
   calculateKnowledgeConcentration,
   calculateMonthlyCost,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiready/core",
-  "version": "0.9.30",
+  "version": "0.9.32",
   "description": "Shared utilities for AIReady analysis tools",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -51,7 +51,7 @@
     "typescript": "^5.9.3"
   },
   "scripts": {
-    "build": "tsup src/index.ts src/client.ts --format cjs,esm",
+    "build": "tsup src/index.ts src/client.ts --format cjs,esm --dts",
     "dev": "tsup src/index.ts src/client.ts --format cjs,esm --watch",
     "lint": "eslint src",
     "clean": "rm -rf dist",