@aiready/core 0.21.21 → 0.22.0

package/dist/index.d.mts

@@ -769,6 +769,7 @@ declare function calculateAiSignalClarity(params: {
     deepCallbacks: number;
     ambiguousNames: number;
     undocumentedExports: number;
+    largeFiles?: number;
     totalSymbols: number;
     totalExports: number;
 }): AiSignalClarity;
@@ -987,4 +988,28 @@ declare function getRepoMetadata(directory: string): {
     author?: string;
 };
 
-export { AIReadyConfig, type ASTNode, AcceptancePrediction, type AgentGroundingScore, type AiSignalClarity, type AiSignalClaritySignal, type CLIOptions, CSharpParser, type ChangeAmplificationScore, type CognitiveLoad, ComprehensionDifficulty, type ConceptCohesion, CostConfig, DEFAULT_COST_CONFIG, DEFAULT_EXCLUDE, type DependencyHealthScore, type DocDriftRisk, ExportInfo, type ExportWithImports, type FileImport, type FileWithDomain, GoParser, JavaParser, type KnowledgeConcentrationRisk, Language, LanguageParser, type LoadFactor, MODEL_PRICING_PRESETS, ModelContextTier, type ModelPricingPreset, NamingConvention, ParseResult, ParserFactory, type PatternEntropy, ProductivityImpact, PythonParser, SEVERITY_TIME_ESTIMATES, ScanOptions, type ScoreHistoryEntry, type ScoreTrend, type SemanticDistance, SpokeOutput, type TechnicalDebtInterest, TechnicalValueChain, TechnicalValueChainSummary, type TestabilityIndex, TokenBudget, ToolName, type ToolProvider, ToolRegistry, ToolScoringOutput, TypeScriptParser, VAGUE_FILE_NAMES, calculateAgentGrounding, calculateAiSignalClarity, calculateBusinessROI, calculateChangeAmplification, calculateCognitiveLoad, calculateComprehensionDifficulty, calculateConceptCohesion, calculateDebtInterest, calculateDependencyHealth, calculateDocDrift, calculateExtendedFutureProofScore, calculateFutureProofScore, calculateImportSimilarity, calculateKnowledgeConcentration, calculateMonthlyCost, calculatePatternEntropy, calculateProductivityImpact, calculateSemanticDistance, calculateTechnicalValueChain, calculateTestabilityIndex, calculateTokenBudget, clearHistory, emitProgress, estimateCostFromBudget, estimateTokens, exportHistory, extractFunctions, extractImports, formatAcceptanceRate, formatCost, formatHours, generateValueChain, getElapsedTime, getFileCommitTimestamps, getFileExtension, getHistorySummary, getLineRangeLastModifiedCached, getModelPreset, getParser, getRepoMetadata, getSafetyIcon, getScoreBar, getSeverityColor, getSupportedLanguages, getWasmPath, handleCLIError, handleJSONOutput, initTreeSitter, initializeParsers, isFileSupported, isSourceFile, loadConfig, loadMergedConfig, loadScoreHistory, mergeConfigWithDefaults, parseCode, parseFileExports, predictAcceptanceRate, readFileContent, resolveOutputPath, saveScoreEntry, scanEntries, scanFiles, setupParser, validateSpokeOutput, validateWithSchema };
+/**
+ * Utilities for GitHub Actions integration
+ */
+/**
+ * Emit a GitHub Action annotation
+ * Format: ::(error|warning|notice) file={file},line={line},col={col},title={title}::{message}
+ */
+declare function emitAnnotation(params: {
+    level: 'error' | 'warning' | 'notice';
+    file: string;
+    line?: number;
+    col?: number;
+    title?: string;
+    message: string;
+}): void;
+/**
+ * Map AIReady severity to GitHub Action annotation level
+ */
+declare function severityToAnnotationLevel(severity: string): 'error' | 'warning' | 'notice';
+/**
+ * Emit multiple annotations from an array of issues
+ */
+declare function emitIssuesAsAnnotations(issues: any[]): void;
+
+export { AIReadyConfig, type ASTNode, AcceptancePrediction, type AgentGroundingScore, type AiSignalClarity, type AiSignalClaritySignal, type CLIOptions, CSharpParser, type ChangeAmplificationScore, type CognitiveLoad, ComprehensionDifficulty, type ConceptCohesion, CostConfig, DEFAULT_COST_CONFIG, DEFAULT_EXCLUDE, type DependencyHealthScore, type DocDriftRisk, ExportInfo, type ExportWithImports, type FileImport, type FileWithDomain, GoParser, JavaParser, type KnowledgeConcentrationRisk, Language, LanguageParser, type LoadFactor, MODEL_PRICING_PRESETS, ModelContextTier, type ModelPricingPreset, NamingConvention, ParseResult, ParserFactory, type PatternEntropy, ProductivityImpact, PythonParser, SEVERITY_TIME_ESTIMATES, ScanOptions, type ScoreHistoryEntry, type ScoreTrend, type SemanticDistance, SpokeOutput, type TechnicalDebtInterest, TechnicalValueChain, TechnicalValueChainSummary, type TestabilityIndex, TokenBudget, ToolName, type ToolProvider, ToolRegistry, ToolScoringOutput, TypeScriptParser, VAGUE_FILE_NAMES, calculateAgentGrounding, calculateAiSignalClarity, calculateBusinessROI, calculateChangeAmplification, calculateCognitiveLoad, calculateComprehensionDifficulty, calculateConceptCohesion, calculateDebtInterest, calculateDependencyHealth, calculateDocDrift, calculateExtendedFutureProofScore, calculateFutureProofScore, calculateImportSimilarity, calculateKnowledgeConcentration, calculateMonthlyCost, calculatePatternEntropy, calculateProductivityImpact, calculateSemanticDistance, calculateTechnicalValueChain, calculateTestabilityIndex, calculateTokenBudget, clearHistory, emitAnnotation, emitIssuesAsAnnotations, emitProgress, estimateCostFromBudget, estimateTokens, exportHistory, extractFunctions, extractImports, formatAcceptanceRate, formatCost, formatHours, generateValueChain, getElapsedTime, getFileCommitTimestamps, getFileExtension, getHistorySummary, getLineRangeLastModifiedCached, getModelPreset, getParser, getRepoMetadata, getSafetyIcon, getScoreBar, getSeverityColor, getSupportedLanguages, getWasmPath, handleCLIError, handleJSONOutput, initTreeSitter, initializeParsers, isFileSupported, isSourceFile, loadConfig, loadMergedConfig, loadScoreHistory, mergeConfigWithDefaults, parseCode, parseFileExports, predictAcceptanceRate, readFileContent, resolveOutputPath, saveScoreEntry, scanEntries, scanFiles, setupParser, severityToAnnotationLevel, validateSpokeOutput, validateWithSchema };

package/dist/index.d.ts

@@ -769,6 +769,7 @@ declare function calculateAiSignalClarity(params: {
     deepCallbacks: number;
     ambiguousNames: number;
     undocumentedExports: number;
+    largeFiles?: number;
     totalSymbols: number;
     totalExports: number;
 }): AiSignalClarity;
@@ -987,4 +988,28 @@ declare function getRepoMetadata(directory: string): {
     author?: string;
 };
 
-export { AIReadyConfig, type ASTNode, AcceptancePrediction, type AgentGroundingScore, type AiSignalClarity, type AiSignalClaritySignal, type CLIOptions, CSharpParser, type ChangeAmplificationScore, type CognitiveLoad, ComprehensionDifficulty, type ConceptCohesion, CostConfig, DEFAULT_COST_CONFIG, DEFAULT_EXCLUDE, type DependencyHealthScore, type DocDriftRisk, ExportInfo, type ExportWithImports, type FileImport, type FileWithDomain, GoParser, JavaParser, type KnowledgeConcentrationRisk, Language, LanguageParser, type LoadFactor, MODEL_PRICING_PRESETS, ModelContextTier, type ModelPricingPreset, NamingConvention, ParseResult, ParserFactory, type PatternEntropy, ProductivityImpact, PythonParser, SEVERITY_TIME_ESTIMATES, ScanOptions, type ScoreHistoryEntry, type ScoreTrend, type SemanticDistance, SpokeOutput, type TechnicalDebtInterest, TechnicalValueChain, TechnicalValueChainSummary, type TestabilityIndex, TokenBudget, ToolName, type ToolProvider, ToolRegistry, ToolScoringOutput, TypeScriptParser, VAGUE_FILE_NAMES, calculateAgentGrounding, calculateAiSignalClarity, calculateBusinessROI, calculateChangeAmplification, calculateCognitiveLoad, calculateComprehensionDifficulty, calculateConceptCohesion, calculateDebtInterest, calculateDependencyHealth, calculateDocDrift, calculateExtendedFutureProofScore, calculateFutureProofScore, calculateImportSimilarity, calculateKnowledgeConcentration, calculateMonthlyCost, calculatePatternEntropy, calculateProductivityImpact, calculateSemanticDistance, calculateTechnicalValueChain, calculateTestabilityIndex, calculateTokenBudget, clearHistory, emitProgress, estimateCostFromBudget, estimateTokens, exportHistory, extractFunctions, extractImports, formatAcceptanceRate, formatCost, formatHours, generateValueChain, getElapsedTime, getFileCommitTimestamps, getFileExtension, getHistorySummary, getLineRangeLastModifiedCached, getModelPreset, getParser, getRepoMetadata, getSafetyIcon, getScoreBar, getSeverityColor, getSupportedLanguages, getWasmPath, handleCLIError, handleJSONOutput, initTreeSitter, initializeParsers, isFileSupported, isSourceFile, loadConfig, loadMergedConfig, loadScoreHistory, mergeConfigWithDefaults, parseCode, parseFileExports, predictAcceptanceRate, readFileContent, resolveOutputPath, saveScoreEntry, scanEntries, scanFiles, setupParser, validateSpokeOutput, validateWithSchema };
+/**
+ * Utilities for GitHub Actions integration
+ */
+/**
+ * Emit a GitHub Action annotation
+ * Format: ::(error|warning|notice) file={file},line={line},col={col},title={title}::{message}
+ */
+declare function emitAnnotation(params: {
+    level: 'error' | 'warning' | 'notice';
+    file: string;
+    line?: number;
+    col?: number;
+    title?: string;
+    message: string;
+}): void;
+/**
+ * Map AIReady severity to GitHub Action annotation level
+ */
+declare function severityToAnnotationLevel(severity: string): 'error' | 'warning' | 'notice';
+/**
+ * Emit multiple annotations from an array of issues
+ */
+declare function emitIssuesAsAnnotations(issues: any[]): void;
+
+export { AIReadyConfig, type ASTNode, AcceptancePrediction, type AgentGroundingScore, type AiSignalClarity, type AiSignalClaritySignal, type CLIOptions, CSharpParser, type ChangeAmplificationScore, type CognitiveLoad, ComprehensionDifficulty, type ConceptCohesion, CostConfig, DEFAULT_COST_CONFIG, DEFAULT_EXCLUDE, type DependencyHealthScore, type DocDriftRisk, ExportInfo, type ExportWithImports, type FileImport, type FileWithDomain, GoParser, JavaParser, type KnowledgeConcentrationRisk, Language, LanguageParser, type LoadFactor, MODEL_PRICING_PRESETS, ModelContextTier, type ModelPricingPreset, NamingConvention, ParseResult, ParserFactory, type PatternEntropy, ProductivityImpact, PythonParser, SEVERITY_TIME_ESTIMATES, ScanOptions, type ScoreHistoryEntry, type ScoreTrend, type SemanticDistance, SpokeOutput, type TechnicalDebtInterest, TechnicalValueChain, TechnicalValueChainSummary, type TestabilityIndex, TokenBudget, ToolName, type ToolProvider, ToolRegistry, ToolScoringOutput, TypeScriptParser, VAGUE_FILE_NAMES, calculateAgentGrounding, calculateAiSignalClarity, calculateBusinessROI, calculateChangeAmplification, calculateCognitiveLoad, calculateComprehensionDifficulty, calculateConceptCohesion, calculateDebtInterest, calculateDependencyHealth, calculateDocDrift, calculateExtendedFutureProofScore, calculateFutureProofScore, calculateImportSimilarity, calculateKnowledgeConcentration, calculateMonthlyCost, calculatePatternEntropy, calculateProductivityImpact, calculateSemanticDistance, calculateTechnicalValueChain, calculateTestabilityIndex, calculateTokenBudget, clearHistory, emitAnnotation, emitIssuesAsAnnotations, emitProgress, estimateCostFromBudget, estimateTokens, exportHistory, extractFunctions, extractImports, formatAcceptanceRate, formatCost, formatHours, generateValueChain, getElapsedTime, getFileCommitTimestamps, getFileExtension, getHistorySummary, getLineRangeLastModifiedCached, getModelPreset, getParser, getRepoMetadata, getSafetyIcon, getScoreBar, getSeverityColor, getSupportedLanguages, getWasmPath, handleCLIError, handleJSONOutput, initTreeSitter, initializeParsers, isFileSupported, isSourceFile, loadConfig, loadMergedConfig, loadScoreHistory, mergeConfigWithDefaults, parseCode, parseFileExports, predictAcceptanceRate, readFileContent, resolveOutputPath, saveScoreEntry, scanEntries, scanFiles, setupParser, severityToAnnotationLevel, validateSpokeOutput, validateWithSchema };

package/dist/index.js

@@ -95,6 +95,8 @@ __export(index_exports, {
   calculateTestabilityIndex: () => calculateTestabilityIndex,
   calculateTokenBudget: () => calculateTokenBudget,
   clearHistory: () => clearHistory,
+  emitAnnotation: () => emitAnnotation,
+  emitIssuesAsAnnotations: () => emitIssuesAsAnnotations,
   emitProgress: () => emitProgress,
   estimateCostFromBudget: () => estimateCostFromBudget,
   estimateTokens: () => estimateTokens,
@@ -148,6 +150,7 @@ __export(index_exports, {
   scanEntries: () => scanEntries,
   scanFiles: () => scanFiles,
   setupParser: () => setupParser,
+  severityToAnnotationLevel: () => severityToAnnotationLevel,
   validateSpokeOutput: () => validateSpokeOutput,
   validateWithSchema: () => validateWithSchema
 });
@@ -4011,6 +4014,8 @@ function calculateAiSignalClarity(params) {
     deepCallbacks,
     ambiguousNames,
     undocumentedExports,
+    largeFiles = 0,
+    // Default to 0 to prevent NaN
     totalSymbols,
     totalExports
   } = params;
@@ -4027,28 +4032,35 @@ function calculateAiSignalClarity(params) {
   const overloadSignal = {
     name: "Symbol Overloading",
     count: overloadedSymbols,
-    riskContribution: Math.round(Math.min(1, overloadRatio) * 100 * 0.25),
+    riskContribution: Math.round(Math.min(1, overloadRatio) * 100 * 0.2),
     description: `${overloadedSymbols} overloaded symbols \u2014 AI picks wrong signature`
   };
+  const largeFileSignal = {
+    name: "Large Files",
+    count: largeFiles,
+    riskContribution: Math.round(Math.min(5, largeFiles) * 5),
+    // up to 25 points
+    description: `${largeFiles} large files \u2014 pushing AI context limits`
+  };
   const magicRatio = magicLiterals / Math.max(1, totalSymbols * 2);
   const magicSignal = {
     name: "Magic Literals",
     count: magicLiterals,
-    riskContribution: Math.round(Math.min(1, magicRatio) * 100 * 0.2),
+    riskContribution: Math.round(Math.min(1, magicRatio) * 100 * 0.15),
     description: `${magicLiterals} unnamed constants \u2014 AI invents wrong values`
   };
   const trapRatio = booleanTraps / Math.max(1, totalSymbols);
   const trapSignal = {
     name: "Boolean Traps",
     count: booleanTraps,
-    riskContribution: Math.round(Math.min(1, trapRatio) * 100 * 0.2),
+    riskContribution: Math.round(Math.min(1, trapRatio) * 100 * 0.15),
     description: `${booleanTraps} boolean trap parameters \u2014 AI inverts intent`
   };
   const sideEffectRatio = implicitSideEffects / Math.max(1, totalExports);
   const sideEffectSignal = {
     name: "Implicit Side Effects",
     count: implicitSideEffects,
-    riskContribution: Math.round(Math.min(1, sideEffectRatio) * 100 * 0.15),
+    riskContribution: Math.round(Math.min(1, sideEffectRatio) * 100 * 0.1),
     description: `${implicitSideEffects} functions with implicit side effects \u2014 AI misses contracts`
   };
   const callbackRatio = deepCallbacks / Math.max(1, totalSymbols * 0.1);
@@ -4062,18 +4074,19 @@ function calculateAiSignalClarity(params) {
   const ambiguousSignal = {
     name: "Ambiguous Names",
     count: ambiguousNames,
-    riskContribution: Math.round(Math.min(1, ambiguousRatio) * 100 * 0.1),
+    riskContribution: Math.round(Math.min(1, ambiguousRatio) * 100 * 0.05),
     description: `${ambiguousNames} non-descriptive identifiers \u2014 AI guesses wrong intent`
   };
   const undocRatio = undocumentedExports / Math.max(1, totalExports);
   const undocSignal = {
     name: "Undocumented Exports",
     count: undocumentedExports,
-    riskContribution: Math.round(Math.min(1, undocRatio) * 100 * 0.1),
+    riskContribution: Math.round(Math.min(1, undocRatio) * 100 * 0.05),
     description: `${undocumentedExports} public functions without docs \u2014 AI fabricates behavior`
   };
   const signals = [
     overloadSignal,
+    largeFileSignal,
     magicSignal,
     trapSignal,
     sideEffectSignal,
@@ -4096,6 +4109,10 @@ function calculateAiSignalClarity(params) {
   );
   const topRisk = topSignal.riskContribution > 0 ? topSignal.description : "No significant issues detected";
   const recommendations = [];
+  if (largeFileSignal.riskContribution > 5)
+    recommendations.push(
+      `Split ${largeFiles} large files (> 500 lines) into smaller, single-responsibility modules`
+    );
   if (overloadSignal.riskContribution > 5)
     recommendations.push(
       `Rename ${overloadedSymbols} overloaded symbols to unique, intent-revealing names`
@@ -4731,6 +4748,46 @@ function getRepoMetadata(directory) {
   }
   return metadata;
 }
+
+// src/utils/github-utils.ts
+function emitAnnotation(params) {
+  const { level, file, line, col, title, message } = params;
+  const parts = [];
+  if (file) parts.push(`file=${file}`);
+  if (line) parts.push(`line=${line}`);
+  if (col) parts.push(`col=${col}`);
+  if (title) parts.push(`title=${title}`);
+  const metadata = parts.length > 0 ? ` ${parts.join(",")}` : "";
+  console.log(`::${level}${metadata}::${message.replace(/\n/g, "%0A")}`);
+}
+function severityToAnnotationLevel(severity) {
+  switch (severity.toLowerCase()) {
+    case "critical":
+    case "high-risk":
+    case "blind-risk":
+      return "error";
+    case "major":
+    case "moderate-risk":
+      return "warning";
+    case "minor":
+    case "info":
+    case "safe":
+    default:
+      return "notice";
+  }
+}
+function emitIssuesAsAnnotations(issues) {
+  issues.forEach((issue) => {
+    emitAnnotation({
+      level: severityToAnnotationLevel(issue.severity || "info"),
+      file: issue.file || issue.fileName || "",
+      line: issue.line || issue.location?.start?.line,
+      col: issue.column || issue.location?.start?.column,
+      title: `${issue.tool || "AIReady"}: ${issue.type || "Issue"}`,
+      message: issue.message || issue.description || "No description provided"
+    });
+  });
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AnalysisResultSchema,
@@ -4798,6 +4855,8 @@ function getRepoMetadata(directory) {
   calculateTestabilityIndex,
   calculateTokenBudget,
   clearHistory,
+  emitAnnotation,
+  emitIssuesAsAnnotations,
   emitProgress,
   estimateCostFromBudget,
   estimateTokens,
@@ -4851,6 +4910,7 @@ function getRepoMetadata(directory) {
   scanEntries,
   scanFiles,
   setupParser,
+  severityToAnnotationLevel,
   validateSpokeOutput,
   validateWithSchema
 });

package/dist/index.mjs

@@ -3300,6 +3300,8 @@ function calculateAiSignalClarity(params) {
     deepCallbacks,
     ambiguousNames,
     undocumentedExports,
+    largeFiles = 0,
+    // Default to 0 to prevent NaN
     totalSymbols,
     totalExports
   } = params;
@@ -3316,28 +3318,35 @@ function calculateAiSignalClarity(params) {
   const overloadSignal = {
     name: "Symbol Overloading",
     count: overloadedSymbols,
-    riskContribution: Math.round(Math.min(1, overloadRatio) * 100 * 0.25),
+    riskContribution: Math.round(Math.min(1, overloadRatio) * 100 * 0.2),
     description: `${overloadedSymbols} overloaded symbols \u2014 AI picks wrong signature`
   };
+  const largeFileSignal = {
+    name: "Large Files",
+    count: largeFiles,
+    riskContribution: Math.round(Math.min(5, largeFiles) * 5),
+    // up to 25 points
+    description: `${largeFiles} large files \u2014 pushing AI context limits`
+  };
   const magicRatio = magicLiterals / Math.max(1, totalSymbols * 2);
   const magicSignal = {
     name: "Magic Literals",
     count: magicLiterals,
-    riskContribution: Math.round(Math.min(1, magicRatio) * 100 * 0.2),
+    riskContribution: Math.round(Math.min(1, magicRatio) * 100 * 0.15),
     description: `${magicLiterals} unnamed constants \u2014 AI invents wrong values`
   };
   const trapRatio = booleanTraps / Math.max(1, totalSymbols);
   const trapSignal = {
     name: "Boolean Traps",
     count: booleanTraps,
-    riskContribution: Math.round(Math.min(1, trapRatio) * 100 * 0.2),
+    riskContribution: Math.round(Math.min(1, trapRatio) * 100 * 0.15),
     description: `${booleanTraps} boolean trap parameters \u2014 AI inverts intent`
   };
   const sideEffectRatio = implicitSideEffects / Math.max(1, totalExports);
   const sideEffectSignal = {
     name: "Implicit Side Effects",
     count: implicitSideEffects,
-    riskContribution: Math.round(Math.min(1, sideEffectRatio) * 100 * 0.15),
+    riskContribution: Math.round(Math.min(1, sideEffectRatio) * 100 * 0.1),
     description: `${implicitSideEffects} functions with implicit side effects \u2014 AI misses contracts`
   };
   const callbackRatio = deepCallbacks / Math.max(1, totalSymbols * 0.1);
@@ -3351,18 +3360,19 @@ function calculateAiSignalClarity(params) {
   const ambiguousSignal = {
     name: "Ambiguous Names",
     count: ambiguousNames,
-    riskContribution: Math.round(Math.min(1, ambiguousRatio) * 100 * 0.1),
+    riskContribution: Math.round(Math.min(1, ambiguousRatio) * 100 * 0.05),
     description: `${ambiguousNames} non-descriptive identifiers \u2014 AI guesses wrong intent`
   };
   const undocRatio = undocumentedExports / Math.max(1, totalExports);
   const undocSignal = {
     name: "Undocumented Exports",
     count: undocumentedExports,
-    riskContribution: Math.round(Math.min(1, undocRatio) * 100 * 0.1),
+    riskContribution: Math.round(Math.min(1, undocRatio) * 100 * 0.05),
     description: `${undocumentedExports} public functions without docs \u2014 AI fabricates behavior`
   };
   const signals = [
     overloadSignal,
+    largeFileSignal,
     magicSignal,
     trapSignal,
     sideEffectSignal,
@@ -3385,6 +3395,10 @@ function calculateAiSignalClarity(params) {
   );
   const topRisk = topSignal.riskContribution > 0 ? topSignal.description : "No significant issues detected";
   const recommendations = [];
+  if (largeFileSignal.riskContribution > 5)
+    recommendations.push(
+      `Split ${largeFiles} large files (> 500 lines) into smaller, single-responsibility modules`
+    );
   if (overloadSignal.riskContribution > 5)
     recommendations.push(
       `Rename ${overloadedSymbols} overloaded symbols to unique, intent-revealing names`
@@ -4020,6 +4034,46 @@ function getRepoMetadata(directory) {
   }
   return metadata;
 }
+
+// src/utils/github-utils.ts
+function emitAnnotation(params) {
+  const { level, file, line, col, title, message } = params;
+  const parts = [];
+  if (file) parts.push(`file=${file}`);
+  if (line) parts.push(`line=${line}`);
+  if (col) parts.push(`col=${col}`);
+  if (title) parts.push(`title=${title}`);
+  const metadata = parts.length > 0 ? ` ${parts.join(",")}` : "";
+  console.log(`::${level}${metadata}::${message.replace(/\n/g, "%0A")}`);
+}
+function severityToAnnotationLevel(severity) {
+  switch (severity.toLowerCase()) {
+    case "critical":
+    case "high-risk":
+    case "blind-risk":
+      return "error";
+    case "major":
+    case "moderate-risk":
+      return "warning";
+    case "minor":
+    case "info":
+    case "safe":
+    default:
+      return "notice";
+  }
+}
+function emitIssuesAsAnnotations(issues) {
+  issues.forEach((issue) => {
+    emitAnnotation({
+      level: severityToAnnotationLevel(issue.severity || "info"),
+      file: issue.file || issue.fileName || "",
+      line: issue.line || issue.location?.start?.line,
+      col: issue.column || issue.location?.start?.column,
+      title: `${issue.tool || "AIReady"}: ${issue.type || "Issue"}`,
+      message: issue.message || issue.description || "No description provided"
+    });
+  });
+}
 export {
   AnalysisResultSchema,
   AnalysisStatus,
@@ -4086,6 +4140,8 @@ export {
   calculateTestabilityIndex,
   calculateTokenBudget,
   clearHistory,
+  emitAnnotation,
+  emitIssuesAsAnnotations,
   emitProgress,
   estimateCostFromBudget,
   estimateTokens,
@@ -4139,6 +4195,7 @@ export {
   scanEntries,
   scanFiles,
   setupParser,
+  severityToAnnotationLevel,
   validateSpokeOutput,
   validateWithSchema
 };

package/package.json

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