@aiready/core 0.9.26 → 0.9.28

package/dist/chunk-JJ5JL5FX.mjs

@@ -0,0 +1,408 @@
+// src/types/language.ts
+var Language = /* @__PURE__ */ ((Language2) => {
+  Language2["TypeScript"] = "typescript";
+  Language2["JavaScript"] = "javascript";
+  Language2["Python"] = "python";
+  Language2["Java"] = "java";
+  Language2["Go"] = "go";
+  Language2["Rust"] = "rust";
+  Language2["CSharp"] = "csharp";
+  return Language2;
+})(Language || {});
+var LANGUAGE_EXTENSIONS = {
+  ".ts": "typescript" /* TypeScript */,
+  ".tsx": "typescript" /* TypeScript */,
+  ".js": "javascript" /* JavaScript */,
+  ".jsx": "javascript" /* JavaScript */,
+  ".py": "python" /* Python */,
+  ".java": "java" /* Java */,
+  ".go": "go" /* Go */,
+  ".rs": "rust" /* Rust */,
+  ".cs": "csharp" /* CSharp */
+};
+var ParseError = class extends Error {
+  constructor(message, filePath, loc) {
+    super(message);
+    this.filePath = filePath;
+    this.loc = loc;
+    this.name = "ParseError";
+  }
+};
+
+// 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
+};
+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;
+}
+function getToolWeight(toolName, toolConfig, cliOverride) {
+  if (cliOverride !== void 0) {
+    return cliOverride;
+  }
+  if (toolConfig?.scoreWeight !== void 0) {
+    return toolConfig.scoreWeight;
+  }
+  return DEFAULT_TOOL_WEIGHTS[toolName] || 10;
+}
+function parseWeightString(weightStr) {
+  const weights = /* @__PURE__ */ new Map();
+  if (!weightStr) {
+    return weights;
+  }
+  const pairs = weightStr.split(",");
+  for (const pair of pairs) {
+    const [toolShortName, weightStr2] = pair.split(":");
+    if (toolShortName && weightStr2) {
+      const toolName = normalizeToolName(toolShortName.trim());
+      const weight = parseInt(weightStr2.trim(), 10);
+      if (!isNaN(weight) && weight > 0) {
+        weights.set(toolName, weight);
+      }
+    }
+  }
+  return weights;
+}
+function calculateOverallScore(toolOutputs, config, cliWeights) {
+  if (toolOutputs.size === 0) {
+    throw new Error("No tool outputs provided for scoring");
+  }
+  const weights = /* @__PURE__ */ new Map();
+  for (const [toolName] of toolOutputs.entries()) {
+    const cliWeight = cliWeights?.get(toolName);
+    const configWeight = config?.tools?.[toolName]?.scoreWeight;
+    const weight = cliWeight ?? configWeight ?? DEFAULT_TOOL_WEIGHTS[toolName] ?? 10;
+    weights.set(toolName, weight);
+  }
+  let weightedSum = 0;
+  let totalWeight = 0;
+  const breakdown = [];
+  const toolsUsed = [];
+  const calculationWeights = {};
+  for (const [toolName, output] of toolOutputs.entries()) {
+    const weight = weights.get(toolName) || 10;
+    const weightedScore = output.score * weight;
+    weightedSum += weightedScore;
+    totalWeight += weight;
+    toolsUsed.push(toolName);
+    calculationWeights[toolName] = weight;
+    breakdown.push(output);
+  }
+  const overall = Math.round(weightedSum / totalWeight);
+  const rating = getRating(overall);
+  const formulaParts = Array.from(toolOutputs.entries()).map(([name, output]) => {
+    const w = weights.get(name) || 10;
+    return `(${output.score} \xD7 ${w})`;
+  });
+  const formulaStr = `[${formulaParts.join(" + ")}] / ${totalWeight} = ${overall}`;
+  return {
+    overall,
+    rating,
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    toolsUsed,
+    breakdown,
+    calculation: {
+      formula: formulaStr,
+      weights: calculationWeights,
+      normalized: formulaStr
+    }
+  };
+}
+function getRating(score) {
+  if (score >= 90) return "Excellent";
+  if (score >= 75) return "Good";
+  if (score >= 60) return "Fair";
+  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":
+      return { emoji: "\u2705", color: "green" };
+    case "Good":
+      return { emoji: "\u{1F44D}", color: "blue" };
+    case "Fair":
+      return { emoji: "\u26A0\uFE0F", color: "yellow" };
+    case "Needs Work":
+      return { emoji: "\u{1F528}", color: "orange" };
+    case "Critical":
+      return { emoji: "\u274C", color: "red" };
+  }
+}
+function formatScore(result) {
+  const { emoji, color } = getRatingDisplay(result.rating);
+  return `${result.overall}/100 (${result.rating}) ${emoji}`;
+}
+function formatToolScore(output) {
+  let result = `  Score: ${output.score}/100
+
+`;
+  if (output.factors && output.factors.length > 0) {
+    result += `  Factors:
+`;
+    output.factors.forEach((factor) => {
+      const impactSign = factor.impact > 0 ? "+" : "";
+      result += `    \u2022 ${factor.name}: ${impactSign}${factor.impact} - ${factor.description}
+`;
+    });
+    result += "\n";
+  }
+  if (output.recommendations && output.recommendations.length > 0) {
+    result += `  Recommendations:
+`;
+    output.recommendations.forEach((rec, i) => {
+      const priorityIcon = rec.priority === "high" ? "\u{1F534}" : rec.priority === "medium" ? "\u{1F7E1}" : "\u{1F535}";
+      result += `    ${i + 1}. ${priorityIcon} ${rec.action}
+`;
+      result += `       Impact: +${rec.estimatedImpact} points
+
+`;
+    });
+  }
+  return result;
+}
+
+// src/utils/visualization.ts
+function generateHTML(graph) {
+  const payload = JSON.stringify(graph, null, 2);
+  return `<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>AIReady Visualization</title>
+    <style>
+      html,body { height: 100%; margin: 0; padding: 0; font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; background: #0f172a; color: #e2e8f0 }
+      #container { display:flex; height:100vh }
+      #panel { width: 320px; padding: 16px; background: #071130; box-shadow: -2px 0 8px rgba(0,0,0,0.3); overflow:auto }
+      #canvasWrap { flex:1; display:flex; align-items:center; justify-content:center }
+      canvas { background: #0b1220; border-radius:8px }
+      .stat { margin-bottom:12px }
+    </style>
+  </head>
+  <body>
+    <div id="container">
+      <div id="canvasWrap"><canvas id="canvas" width="1200" height="800"></canvas></div>
+      <div id="panel">
+        <h2>AIReady Visualization</h2>
+        <div class="stat"><strong>Files:</strong> <span id="stat-files"></span></div>
+        <div class="stat"><strong>Dependencies:</strong> <span id="stat-deps"></span></div>
+        <div class="stat"><strong>Legend</strong></div>
+        <div style="font-size:13px;line-height:1.3;color:#cbd5e1;margin-top:8px">
+          <div style="margin-bottom:8px"><span style="display:inline-block;width:12px;height:12px;background:#ff4d4f;margin-right:8px;border:1px solid rgba(255,255,255,0.06)"></span><strong>Critical</strong>: highest severity issues.</div>
+          <div style="margin-bottom:8px"><span style="display:inline-block;width:12px;height:12px;background:#ff9900;margin-right:8px;border:1px solid rgba(255,255,255,0.06)"></span><strong>Major</strong>: important issues.</div>
+          <div style="margin-bottom:8px"><span style="display:inline-block;width:12px;height:12px;background:#ffd666;margin-right:8px;border:1px solid rgba(255,255,255,0.06)"></span><strong>Minor</strong>: low priority issues.</div>
+          <div style="margin-bottom:8px"><span style="display:inline-block;width:12px;height:12px;background:#91d5ff;margin-right:8px;border:1px solid rgba(255,255,255,0.06)"></span><strong>Info</strong>: informational notes.</div>
+          <div style="margin-top:10px;color:#94a3b8"><strong>Node size</strong>: larger = higher token cost, more issues or dependency weight.</div>
+          <div style="margin-top:6px;color:#94a3b8"><strong>Proximity</strong>: nodes that are spatially close are more contextually related; relatedness is represented by distance and size rather than explicit edges.</div>
+          <div style="margin-top:6px;color:#94a3b8"><strong>Edge colors</strong>: <span style="color:#fb7e81">Similarity</span>, <span style="color:#84c1ff">Dependency</span>, <span style="color:#ffa500">Reference</span>, default <span style="color:#334155">Other</span>.</div>
+        </div>
+      </div>
+    </div>
+
+    <script>
+      const graphData = ${payload};
+      document.getElementById('stat-files').textContent = graphData.metadata.totalFiles;
+      document.getElementById('stat-deps').textContent = graphData.metadata.totalDependencies;
+
+      const canvas = document.getElementById('canvas');
+      const ctx = canvas.getContext('2d');
+
+      const nodes = graphData.nodes.map((n, i) => ({
+        ...n,
+        x: canvas.width / 2 + Math.cos(i / graphData.nodes.length * Math.PI * 2) * (Math.min(canvas.width, canvas.height) / 3),
+        y: canvas.height / 2 + Math.sin(i / graphData.nodes.length * Math.PI * 2) * (Math.min(canvas.width, canvas.height) / 3),
+      }));
+
+      function draw() {
+        ctx.clearRect(0, 0, canvas.width, canvas.height);
+
+        graphData.edges.forEach(edge => {
+          const s = nodes.find(n => n.id === edge.source);
+          const t = nodes.find(n => n.id === edge.target);
+          if (!s || !t) return;
+          if (edge.type === 'related') return;
+          if (edge.type === 'similarity') {
+            ctx.strokeStyle = '#fb7e81';
+            ctx.lineWidth = 1.2;
+          } else if (edge.type === 'dependency') {
+            ctx.strokeStyle = '#84c1ff';
+            ctx.lineWidth = 1.0;
+          } else if (edge.type === 'reference') {
+            ctx.strokeStyle = '#ffa500';
+            ctx.lineWidth = 0.9;
+          } else {
+            ctx.strokeStyle = '#334155';
+            ctx.lineWidth = 0.8;
+          }
+          ctx.beginPath();
+          ctx.moveTo(s.x, s.y);
+          ctx.lineTo(t.x, t.y);
+          ctx.stroke();
+        });
+
+        const groups = {};
+        nodes.forEach(n => {
+          const g = n.group || '__default';
+          if (!groups[g]) groups[g] = { minX: n.x, minY: n.y, maxX: n.x, maxY: n.y };
+          groups[g].minX = Math.min(groups[g].minX, n.x);
+          groups[g].minY = Math.min(groups[g].minY, n.y);
+          groups[g].maxX = Math.max(groups[g].maxX, n.x);
+          groups[g].maxY = Math.max(groups[g].maxY, n.y);
+        });
+
+        const groupRelations = {};
+        graphData.edges.forEach(edge => {
+          const sNode = nodes.find(n => n.id === edge.source);
+          const tNode = nodes.find(n => n.id === edge.target);
+          if (!sNode || !tNode) return;
+          const g1 = sNode.group || '__default';
+          const g2 = tNode.group || '__default';
+          if (g1 === g2) return;
+          const key = g1 < g2 ? g1 + '::' + g2 : g2 + '::' + g1;
+          groupRelations[key] = (groupRelations[key] || 0) + 1;
+        });
+
+        Object.keys(groupRelations).forEach(k => {
+          const count = groupRelations[k];
+          const [ga, gb] = k.split('::');
+          if (!groups[ga] || !groups[gb]) return;
+          const ax = (groups[ga].minX + groups[ga].maxX) / 2;
+          const ay = (groups[ga].minY + groups[ga].maxY) / 2;
+          const bx = (groups[gb].minX + groups[gb].maxX) / 2;
+          const by = (groups[gb].minY + groups[gb].maxY) / 2;
+          ctx.beginPath();
+          ctx.strokeStyle = 'rgba(148,163,184,0.25)';
+          ctx.lineWidth = Math.min(6, 0.6 + Math.sqrt(count));
+          ctx.moveTo(ax, ay);
+          ctx.lineTo(bx, by);
+          ctx.stroke();
+        });
+
+        Object.keys(groups).forEach(g => {
+          if (g === '__default') return;
+          const box = groups[g];
+          const pad = 16;
+          const x = box.minX - pad;
+          const y = box.minY - pad;
+          const w = (box.maxX - box.minX) + pad * 2;
+          const h = (box.maxY - box.minY) + pad * 2;
+          ctx.save();
+          ctx.fillStyle = 'rgba(30,64,175,0.04)';
+          ctx.strokeStyle = 'rgba(30,64,175,0.12)';
+          ctx.lineWidth = 1.2;
+          const r = 8;
+          ctx.beginPath();
+          ctx.moveTo(x + r, y);
+          ctx.arcTo(x + w, y, x + w, y + h, r);
+          ctx.arcTo(x + w, y + h, x, y + h, r);
+          ctx.arcTo(x, y + h, x, y, r);
+          ctx.arcTo(x, y, x + w, y, r);
+          ctx.closePath();
+          ctx.fill();
+          ctx.stroke();
+          ctx.restore();
+          ctx.fillStyle = '#94a3b8';
+          ctx.font = '11px sans-serif';
+          ctx.fillText(g, x + 8, y + 14);
+        });
+
+        nodes.forEach(n => {
+          const sizeVal = (n.size || n.value || 1);
+          const r = 6 + (sizeVal / 2);
+          ctx.beginPath();
+          ctx.fillStyle = n.color || '#60a5fa';
+          ctx.arc(n.x, n.y, r, 0, Math.PI * 2);
+          ctx.fill();
+
+          ctx.fillStyle = '#e2e8f0';
+          ctx.font = '11px sans-serif';
+          ctx.textAlign = 'center';
+          ctx.fillText(n.label || n.id.split('/').slice(-1)[0], n.x, n.y + r + 12);
+        });
+      }
+
+      draw();
+    </script>
+  </body>
+</html>`;
+}
+
+export {
+  Language,
+  LANGUAGE_EXTENSIONS,
+  ParseError,
+  DEFAULT_TOOL_WEIGHTS,
+  TOOL_NAME_MAP,
+  CONTEXT_TIER_THRESHOLDS,
+  SIZE_ADJUSTED_THRESHOLDS,
+  getProjectSizeTier,
+  getRecommendedThreshold,
+  normalizeToolName,
+  getToolWeight,
+  parseWeightString,
+  calculateOverallScore,
+  getRating,
+  getRatingWithContext,
+  getRatingDisplay,
+  formatScore,
+  formatToolScore,
+  generateHTML
+};

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 };