@aiready/core 0.9.39 → 0.18.0

package/README.md

@@ -33,3 +33,6 @@ This package provides common utilities, type definitions, and helper functions u
 ## License
 
 MIT
+// ping
+// ping
+// ping 2

package/dist/index.d.mts

@@ -1,5 +1,58 @@
-import { ScanOptions, AIReadyConfig, ModelContextTier, CostConfig, TokenBudget, ProductivityImpact, ToolScoringOutput, AcceptancePrediction, ComprehensionDifficulty, TechnicalValueChainSummary, TechnicalValueChain, 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';
+import { AnalysisResult, ScanOptions, AIReadyConfig, ModelContextTier, CostConfig, TokenBudget, ProductivityImpact, ToolScoringOutput, AcceptancePrediction, ComprehensionDifficulty, TechnicalValueChainSummary, TechnicalValueChain, LanguageParser, Language, ParseResult, NamingConvention } from './client.mjs';
+export { 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';
+
+/**
+ * Spoke-to-Hub Contract Definitions
+ * This file defines the expected JSON structure for tool outputs to ensure
+ * changes in spokes don't break the CLI, Platform, or Visualizer.
+ */
+
+/**
+ * The standard output every spoke MUST provide when analyzed.
+ * Some fields are optional depending on the tool's focus.
+ */
+interface SpokeOutput {
+    results: AnalysisResult[];
+    summary: any;
+    metadata?: {
+        toolName: string;
+        version: string;
+        timestamp: string;
+        [key: string]: any;
+    };
+}
+/**
+ * Validation utility to ensure a spoke's output matches the expected contract.
+ * Used in spoke tests to catch breakages early.
+ */
+declare function validateSpokeOutput(toolName: string, output: any): {
+    valid: boolean;
+    errors: string[];
+};
+/**
+ * The unified report format produced by the CLI and consumed by the Platform.
+ * This is the master contract for the entire system.
+ */
+interface UnifiedReport {
+    summary: {
+        totalFiles: number;
+        totalIssues: number;
+        criticalIssues: number;
+        majorIssues: number;
+    };
+    results: AnalysisResult[];
+    scoring?: {
+        overall: number;
+        rating: string;
+        timestamp: string;
+        breakdown: Array<{
+            toolName: string;
+            score: number;
+            [key: string]: any;
+        }>;
+    };
+    [toolKey: string]: any;
+}
 
 declare const DEFAULT_EXCLUDE: string[];
 declare const VAGUE_FILE_NAMES: Set<string>;
@@ -776,4 +829,4 @@ declare function getRepoMetadata(directory: string): {
     author?: string;
 };
 
-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 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, SEVERITY_TIME_ESTIMATES, ScanOptions, type ScoreHistoryEntry, type ScoreTrend, type SemanticDistance, type TechnicalDebtInterest, TechnicalValueChain, TechnicalValueChainSummary, type TestabilityIndex, TokenBudget, 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, estimateCostFromBudget, estimateTokens, exportHistory, extractFunctions, extractImports, formatAcceptanceRate, formatCost, formatHours, generateValueChain, getElapsedTime, getFileCommitTimestamps, getFileExtension, getHistorySummary, getLineRangeLastModifiedCached, getModelPreset, getParser, getRepoMetadata, getSafetyIcon, getScoreBar, getSeverityColor, getSupportedLanguages, handleCLIError, handleJSONOutput, isFileSupported, isSourceFile, loadConfig, loadMergedConfig, loadScoreHistory, mergeConfigWithDefaults, parseCode, parseFileExports, predictAcceptanceRate, readFileContent, resolveOutputPath, saveScoreEntry, scanEntries, scanFiles };
+export { AIReadyConfig, type ASTNode, AcceptancePrediction, type AgentGroundingScore, type AiSignalClarity, type AiSignalClaritySignal, AnalysisResult, type CLIOptions, type ChangeAmplificationScore, type CognitiveLoad, ComprehensionDifficulty, type ConceptCohesion, CostConfig, DEFAULT_COST_CONFIG, DEFAULT_EXCLUDE, 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, SEVERITY_TIME_ESTIMATES, ScanOptions, type ScoreHistoryEntry, type ScoreTrend, type SemanticDistance, type SpokeOutput, type TechnicalDebtInterest, TechnicalValueChain, TechnicalValueChainSummary, type TestabilityIndex, TokenBudget, ToolScoringOutput, TypeScriptParser, type UnifiedReport, 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, estimateCostFromBudget, estimateTokens, exportHistory, extractFunctions, extractImports, formatAcceptanceRate, formatCost, formatHours, generateValueChain, getElapsedTime, getFileCommitTimestamps, getFileExtension, getHistorySummary, getLineRangeLastModifiedCached, getModelPreset, getParser, getRepoMetadata, getSafetyIcon, getScoreBar, getSeverityColor, getSupportedLanguages, handleCLIError, handleJSONOutput, isFileSupported, isSourceFile, loadConfig, loadMergedConfig, loadScoreHistory, mergeConfigWithDefaults, parseCode, parseFileExports, predictAcceptanceRate, readFileContent, resolveOutputPath, saveScoreEntry, scanEntries, scanFiles, validateSpokeOutput };

package/dist/index.d.ts

@@ -1,5 +1,58 @@
-import { ScanOptions, AIReadyConfig, ModelContextTier, CostConfig, TokenBudget, ProductivityImpact, ToolScoringOutput, AcceptancePrediction, ComprehensionDifficulty, TechnicalValueChainSummary, TechnicalValueChain, LanguageParser, Language, ParseResult, NamingConvention } from './client.js';
-export { AnalysisResult, BusinessReport, CONTEXT_TIER_THRESHOLDS, CommonASTNode, DEFAULT_TOOL_WEIGHTS, ExportInfo, GraphData, GraphEdge, GraphIssueSeverity, GraphMetadata, GraphNode, ImportInfo, Issue, IssueType, LANGUAGE_EXTENSIONS, LanguageConfig, Location, Metrics, ParseError, ParseStatistics, Report, SIZE_ADJUSTED_THRESHOLDS, ScoringConfig, ScoringResult, SourceLocation, SourceRange, TOOL_NAME_MAP, calculateOverallScore, formatScore, formatToolScore, generateHTML, getProjectSizeTier, getRating, getRatingDisplay, getRatingWithContext, getRecommendedThreshold, getToolWeight, normalizeToolName, parseWeightString } from './client.js';
+import { AnalysisResult, ScanOptions, AIReadyConfig, ModelContextTier, CostConfig, TokenBudget, ProductivityImpact, ToolScoringOutput, AcceptancePrediction, ComprehensionDifficulty, TechnicalValueChainSummary, TechnicalValueChain, LanguageParser, Language, ParseResult, NamingConvention } from './client.js';
+export { BusinessReport, CONTEXT_TIER_THRESHOLDS, CommonASTNode, DEFAULT_TOOL_WEIGHTS, ExportInfo, GraphData, GraphEdge, GraphIssueSeverity, GraphMetadata, GraphNode, ImportInfo, Issue, IssueType, LANGUAGE_EXTENSIONS, LanguageConfig, Location, Metrics, ParseError, ParseStatistics, Report, SIZE_ADJUSTED_THRESHOLDS, ScoringConfig, ScoringResult, SourceLocation, SourceRange, TOOL_NAME_MAP, calculateOverallScore, formatScore, formatToolScore, generateHTML, getProjectSizeTier, getRating, getRatingDisplay, getRatingWithContext, getRecommendedThreshold, getToolWeight, normalizeToolName, parseWeightString } from './client.js';
+
+/**
+ * Spoke-to-Hub Contract Definitions
+ * This file defines the expected JSON structure for tool outputs to ensure
+ * changes in spokes don't break the CLI, Platform, or Visualizer.
+ */
+
+/**
+ * The standard output every spoke MUST provide when analyzed.
+ * Some fields are optional depending on the tool's focus.
+ */
+interface SpokeOutput {
+    results: AnalysisResult[];
+    summary: any;
+    metadata?: {
+        toolName: string;
+        version: string;
+        timestamp: string;
+        [key: string]: any;
+    };
+}
+/**
+ * Validation utility to ensure a spoke's output matches the expected contract.
+ * Used in spoke tests to catch breakages early.
+ */
+declare function validateSpokeOutput(toolName: string, output: any): {
+    valid: boolean;
+    errors: string[];
+};
+/**
+ * The unified report format produced by the CLI and consumed by the Platform.
+ * This is the master contract for the entire system.
+ */
+interface UnifiedReport {
+    summary: {
+        totalFiles: number;
+        totalIssues: number;
+        criticalIssues: number;
+        majorIssues: number;
+    };
+    results: AnalysisResult[];
+    scoring?: {
+        overall: number;
+        rating: string;
+        timestamp: string;
+        breakdown: Array<{
+            toolName: string;
+            score: number;
+            [key: string]: any;
+        }>;
+    };
+    [toolKey: string]: any;
+}
 
 declare const DEFAULT_EXCLUDE: string[];
 declare const VAGUE_FILE_NAMES: Set<string>;
@@ -776,4 +829,4 @@ declare function getRepoMetadata(directory: string): {
     author?: string;
 };
 
-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 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, SEVERITY_TIME_ESTIMATES, ScanOptions, type ScoreHistoryEntry, type ScoreTrend, type SemanticDistance, type TechnicalDebtInterest, TechnicalValueChain, TechnicalValueChainSummary, type TestabilityIndex, TokenBudget, 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, estimateCostFromBudget, estimateTokens, exportHistory, extractFunctions, extractImports, formatAcceptanceRate, formatCost, formatHours, generateValueChain, getElapsedTime, getFileCommitTimestamps, getFileExtension, getHistorySummary, getLineRangeLastModifiedCached, getModelPreset, getParser, getRepoMetadata, getSafetyIcon, getScoreBar, getSeverityColor, getSupportedLanguages, handleCLIError, handleJSONOutput, isFileSupported, isSourceFile, loadConfig, loadMergedConfig, loadScoreHistory, mergeConfigWithDefaults, parseCode, parseFileExports, predictAcceptanceRate, readFileContent, resolveOutputPath, saveScoreEntry, scanEntries, scanFiles };
+export { AIReadyConfig, type ASTNode, AcceptancePrediction, type AgentGroundingScore, type AiSignalClarity, type AiSignalClaritySignal, AnalysisResult, type CLIOptions, type ChangeAmplificationScore, type CognitiveLoad, ComprehensionDifficulty, type ConceptCohesion, CostConfig, DEFAULT_COST_CONFIG, DEFAULT_EXCLUDE, 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, SEVERITY_TIME_ESTIMATES, ScanOptions, type ScoreHistoryEntry, type ScoreTrend, type SemanticDistance, type SpokeOutput, type TechnicalDebtInterest, TechnicalValueChain, TechnicalValueChainSummary, type TestabilityIndex, TokenBudget, ToolScoringOutput, TypeScriptParser, type UnifiedReport, 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, estimateCostFromBudget, estimateTokens, exportHistory, extractFunctions, extractImports, formatAcceptanceRate, formatCost, formatHours, generateValueChain, getElapsedTime, getFileCommitTimestamps, getFileExtension, getHistorySummary, getLineRangeLastModifiedCached, getModelPreset, getParser, getRepoMetadata, getSafetyIcon, getScoreBar, getSeverityColor, getSupportedLanguages, handleCLIError, handleJSONOutput, isFileSupported, isSourceFile, loadConfig, loadMergedConfig, loadScoreHistory, mergeConfigWithDefaults, parseCode, parseFileExports, predictAcceptanceRate, readFileContent, resolveOutputPath, saveScoreEntry, scanEntries, scanFiles, validateSpokeOutput };

package/dist/index.js

@@ -115,7 +115,8 @@ __export(index_exports, {
   resolveOutputPath: () => resolveOutputPath,
   saveScoreEntry: () => saveScoreEntry,
   scanEntries: () => scanEntries,
-  scanFiles: () => scanFiles
+  scanFiles: () => scanFiles,
+  validateSpokeOutput: () => validateSpokeOutput
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -150,6 +151,54 @@ var ParseError = class extends Error {
   }
 };
 
+// src/types/contract.ts
+function validateSpokeOutput(toolName, output) {
+  const errors = [];
+  if (!output) {
+    return { valid: false, errors: ["Output is null or undefined"] };
+  }
+  if (!Array.isArray(output.results)) {
+    errors.push(`${toolName}: 'results' must be an array`);
+  } else {
+    output.results.forEach((res, idx) => {
+      const fileName = res.fileName || res.file || res.filePath;
+      if (!fileName)
+        errors.push(
+          `${toolName}: results[${idx}] missing 'fileName', 'file' or 'filePath'`
+        );
+      const issues = res.issues;
+      if (!Array.isArray(issues)) {
+        errors.push(`${toolName}: results[${idx}] 'issues' must be an array`);
+      } else if (issues.length > 0) {
+        issues.forEach((issue, iidx) => {
+          if (typeof issue === "string") return;
+          if (!issue.type && !res.file)
+            errors.push(
+              `${toolName}: results[${idx}].issues[${iidx}] missing 'type'`
+            );
+          if (!issue.severity && !res.severity)
+            errors.push(
+              `${toolName}: results[${idx}].issues[${iidx}] missing 'severity'`
+            );
+          const severity = issue.severity || res.severity;
+          if (severity && !["critical", "major", "minor", "info"].includes(severity)) {
+            errors.push(
+              `${toolName}: results[${idx}].issues[${iidx}] has invalid severity: ${severity}`
+            );
+          }
+        });
+      }
+    });
+  }
+  if (!output.summary) {
+    errors.push(`${toolName}: missing 'summary'`);
+  }
+  return {
+    valid: errors.length === 0,
+    errors
+  };
+}
+
 // src/utils/file-scanner.ts
 var import_glob = require("glob");
 var import_promises = require("fs/promises");
@@ -3021,5 +3070,6 @@ function getRepoMetadata(directory) {
   resolveOutputPath,
   saveScoreEntry,
   scanEntries,
-  scanFiles
+  scanFiles,
+  validateSpokeOutput
 });

package/dist/index.mjs

@@ -20,6 +20,54 @@ import {
   parseWeightString
 } from "./chunk-UQGI67WR.mjs";
 
+// src/types/contract.ts
+function validateSpokeOutput(toolName, output) {
+  const errors = [];
+  if (!output) {
+    return { valid: false, errors: ["Output is null or undefined"] };
+  }
+  if (!Array.isArray(output.results)) {
+    errors.push(`${toolName}: 'results' must be an array`);
+  } else {
+    output.results.forEach((res, idx) => {
+      const fileName = res.fileName || res.file || res.filePath;
+      if (!fileName)
+        errors.push(
+          `${toolName}: results[${idx}] missing 'fileName', 'file' or 'filePath'`
+        );
+      const issues = res.issues;
+      if (!Array.isArray(issues)) {
+        errors.push(`${toolName}: results[${idx}] 'issues' must be an array`);
+      } else if (issues.length > 0) {
+        issues.forEach((issue, iidx) => {
+          if (typeof issue === "string") return;
+          if (!issue.type && !res.file)
+            errors.push(
+              `${toolName}: results[${idx}].issues[${iidx}] missing 'type'`
+            );
+          if (!issue.severity && !res.severity)
+            errors.push(
+              `${toolName}: results[${idx}].issues[${iidx}] missing 'severity'`
+            );
+          const severity = issue.severity || res.severity;
+          if (severity && !["critical", "major", "minor", "info"].includes(severity)) {
+            errors.push(
+              `${toolName}: results[${idx}].issues[${iidx}] has invalid severity: ${severity}`
+            );
+          }
+        });
+      }
+    });
+  }
+  if (!output.summary) {
+    errors.push(`${toolName}: missing 'summary'`);
+  }
+  return {
+    valid: errors.length === 0,
+    errors
+  };
+}
+
 // src/utils/file-scanner.ts
 import { glob } from "glob";
 import { readFile } from "fs/promises";
@@ -2532,5 +2580,6 @@ export {
   resolveOutputPath,
   saveScoreEntry,
   scanEntries,
-  scanFiles
+  scanFiles,
+  validateSpokeOutput
 };

package/package.json

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