@aiready/core 0.19.2 → 0.19.5

package/dist/client.d.ts

@@ -1,44 +1,268 @@
-interface AnalysisResult {
-    fileName: string;
-    issues: Issue[];
-    metrics: Metrics;
-}
-interface Issue {
-    type: IssueType;
-    severity: 'critical' | 'major' | 'minor' | 'info';
-    message: string;
-    location: Location;
-    suggestion?: string;
-}
-type IssueType = 'duplicate-pattern' | 'context-fragmentation' | 'doc-drift' | 'dependency-health' | 'naming-inconsistency' | 'naming-quality' | 'pattern-inconsistency' | 'architecture-inconsistency' | 'dead-code' | 'circular-dependency' | 'missing-types' | 'ai-signal-clarity' | 'low-testability' | 'agent-navigation-failure' | 'ambiguous-api' | 'magic-literal' | 'boolean-trap' | 'change-amplification';
-interface Location {
-    file: string;
-    line: number;
-    column?: number;
-    endLine?: number;
-    endColumn?: number;
-}
-interface Metrics {
-    tokenCost?: number;
-    complexityScore?: number;
-    consistencyScore?: number;
-    docFreshnessScore?: number;
-    estimatedMonthlyCost?: number;
-    estimatedDeveloperHours?: number;
-    comprehensionDifficultyIndex?: number;
-    /** Probability (0-100) that AI will hallucinate in this file/module */
-    aiSignalClarityScore?: 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';
-}
+import { z } from 'zod';
+
+/**
+ * Severity levels for all AIReady issues.
+ */
+declare enum Severity {
+    Critical = "critical",
+    Major = "major",
+    Minor = "minor",
+    Info = "info"
+}
+declare const SeveritySchema: z.ZodEnum<typeof Severity>;
+/**
+ * Canonical Tool Names (IDs)
+ * Used everywhere as the single source of truth for tool identification.
+ */
+declare enum ToolName {
+    PatternDetect = "pattern-detect",
+    ContextAnalyzer = "context-analyzer",
+    NamingConsistency = "naming-consistency",
+    AiSignalClarity = "ai-signal-clarity",
+    AgentGrounding = "agent-grounding",
+    TestabilityIndex = "testability-index",
+    DocDrift = "doc-drift",
+    DependencyHealth = "dependency-health",
+    ChangeAmplification = "change-amplification",
+    CognitiveLoad = "cognitive-load",
+    PatternEntropy = "pattern-entropy",
+    ConceptCohesion = "concept-cohesion",
+    SemanticDistance = "semantic-distance"
+}
+declare const ToolNameSchema: z.ZodEnum<typeof ToolName>;
+/**
+ * Friendly labels for UI display
+ */
+declare const FRIENDLY_TOOL_NAMES: Record<ToolName, string>;
+/**
+ * Standardized issue types across all AIReady tools.
+ */
+declare enum IssueType {
+    DuplicatePattern = "duplicate-pattern",
+    PatternInconsistency = "pattern-inconsistency",
+    ContextFragmentation = "context-fragmentation",
+    DependencyHealth = "dependency-health",
+    CircularDependency = "circular-dependency",
+    DocDrift = "doc-drift",
+    NamingInconsistency = "naming-inconsistency",
+    NamingQuality = "naming-quality",
+    ArchitectureInconsistency = "architecture-inconsistency",
+    DeadCode = "dead-code",
+    MissingTypes = "missing-types",
+    MagicLiteral = "magic-literal",
+    BooleanTrap = "boolean-trap",
+    AiSignalClarity = "ai-signal-clarity",
+    LowTestability = "low-testability",
+    AgentNavigationFailure = "agent-navigation-failure",
+    AmbiguousApi = "ambiguous-api",
+    ChangeAmplification = "change-amplification"
+}
+declare const IssueTypeSchema: z.ZodEnum<typeof IssueType>;
+/**
+ * Analysis processing status.
+ */
+declare enum AnalysisStatus {
+    Processing = "processing",
+    Completed = "completed",
+    Failed = "failed"
+}
+declare const AnalysisStatusSchema: z.ZodEnum<typeof AnalysisStatus>;
+/**
+ * AI Model Context Tiers.
+ */
+declare enum ModelTier {
+    Compact = "compact",
+    Standard = "standard",
+    Extended = "extended",
+    Frontier = "frontier"
+}
+declare const ModelTierSchema: z.ZodEnum<typeof ModelTier>;
+/**
+ * Source code location schema.
+ */
+declare const LocationSchema: z.ZodObject<{
+    file: z.ZodString;
+    line: z.ZodNumber;
+    column: z.ZodOptional<z.ZodNumber>;
+    endLine: z.ZodOptional<z.ZodNumber>;
+    endColumn: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+type Location = z.infer<typeof LocationSchema>;
+/**
+ * Standard Issue schema.
+ */
+declare const IssueSchema: z.ZodObject<{
+    type: z.ZodEnum<typeof IssueType>;
+    severity: z.ZodEnum<typeof Severity>;
+    message: z.ZodString;
+    location: z.ZodObject<{
+        file: z.ZodString;
+        line: z.ZodNumber;
+        column: z.ZodOptional<z.ZodNumber>;
+        endLine: z.ZodOptional<z.ZodNumber>;
+        endColumn: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>;
+    suggestion: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type Issue = z.infer<typeof IssueSchema>;
+/**
+ * Standard Metrics schema.
+ */
+declare const MetricsSchema: z.ZodObject<{
+    tokenCost: z.ZodOptional<z.ZodNumber>;
+    complexityScore: z.ZodOptional<z.ZodNumber>;
+    consistencyScore: z.ZodOptional<z.ZodNumber>;
+    docFreshnessScore: z.ZodOptional<z.ZodNumber>;
+    aiSignalClarityScore: z.ZodOptional<z.ZodNumber>;
+    agentGroundingScore: z.ZodOptional<z.ZodNumber>;
+    testabilityScore: z.ZodOptional<z.ZodNumber>;
+    docDriftScore: z.ZodOptional<z.ZodNumber>;
+    dependencyHealthScore: z.ZodOptional<z.ZodNumber>;
+    modelContextTier: z.ZodOptional<z.ZodEnum<typeof ModelTier>>;
+    estimatedMonthlyCost: z.ZodOptional<z.ZodNumber>;
+    estimatedDeveloperHours: z.ZodOptional<z.ZodNumber>;
+    comprehensionDifficultyIndex: z.ZodOptional<z.ZodNumber>;
+    totalSymbols: z.ZodOptional<z.ZodNumber>;
+    totalExports: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+type Metrics = z.infer<typeof MetricsSchema>;
+/**
+ * Individual file/module analysis result.
+ */
+declare const AnalysisResultSchema: z.ZodObject<{
+    fileName: z.ZodString;
+    issues: z.ZodArray<z.ZodObject<{
+        type: z.ZodEnum<typeof IssueType>;
+        severity: z.ZodEnum<typeof Severity>;
+        message: z.ZodString;
+        location: z.ZodObject<{
+            file: z.ZodString;
+            line: z.ZodNumber;
+            column: z.ZodOptional<z.ZodNumber>;
+            endLine: z.ZodOptional<z.ZodNumber>;
+            endColumn: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>;
+        suggestion: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    metrics: z.ZodObject<{
+        tokenCost: z.ZodOptional<z.ZodNumber>;
+        complexityScore: z.ZodOptional<z.ZodNumber>;
+        consistencyScore: z.ZodOptional<z.ZodNumber>;
+        docFreshnessScore: z.ZodOptional<z.ZodNumber>;
+        aiSignalClarityScore: z.ZodOptional<z.ZodNumber>;
+        agentGroundingScore: z.ZodOptional<z.ZodNumber>;
+        testabilityScore: z.ZodOptional<z.ZodNumber>;
+        docDriftScore: z.ZodOptional<z.ZodNumber>;
+        dependencyHealthScore: z.ZodOptional<z.ZodNumber>;
+        modelContextTier: z.ZodOptional<z.ZodEnum<typeof ModelTier>>;
+        estimatedMonthlyCost: z.ZodOptional<z.ZodNumber>;
+        estimatedDeveloperHours: z.ZodOptional<z.ZodNumber>;
+        comprehensionDifficultyIndex: z.ZodOptional<z.ZodNumber>;
+        totalSymbols: z.ZodOptional<z.ZodNumber>;
+        totalExports: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+type AnalysisResult = z.infer<typeof AnalysisResultSchema>;
+/**
+ * Standard spoke tool output contract.
+ */
+declare const SpokeOutputSchema: z.ZodObject<{
+    results: z.ZodArray<z.ZodObject<{
+        fileName: z.ZodString;
+        issues: z.ZodArray<z.ZodObject<{
+            type: z.ZodEnum<typeof IssueType>;
+            severity: z.ZodEnum<typeof Severity>;
+            message: z.ZodString;
+            location: z.ZodObject<{
+                file: z.ZodString;
+                line: z.ZodNumber;
+                column: z.ZodOptional<z.ZodNumber>;
+                endLine: z.ZodOptional<z.ZodNumber>;
+                endColumn: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strip>;
+            suggestion: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        metrics: z.ZodObject<{
+            tokenCost: z.ZodOptional<z.ZodNumber>;
+            complexityScore: z.ZodOptional<z.ZodNumber>;
+            consistencyScore: z.ZodOptional<z.ZodNumber>;
+            docFreshnessScore: z.ZodOptional<z.ZodNumber>;
+            aiSignalClarityScore: z.ZodOptional<z.ZodNumber>;
+            agentGroundingScore: z.ZodOptional<z.ZodNumber>;
+            testabilityScore: z.ZodOptional<z.ZodNumber>;
+            docDriftScore: z.ZodOptional<z.ZodNumber>;
+            dependencyHealthScore: z.ZodOptional<z.ZodNumber>;
+            modelContextTier: z.ZodOptional<z.ZodEnum<typeof ModelTier>>;
+            estimatedMonthlyCost: z.ZodOptional<z.ZodNumber>;
+            estimatedDeveloperHours: z.ZodOptional<z.ZodNumber>;
+            comprehensionDifficultyIndex: z.ZodOptional<z.ZodNumber>;
+            totalSymbols: z.ZodOptional<z.ZodNumber>;
+            totalExports: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>;
+    }, z.core.$strip>>;
+    summary: z.ZodAny;
+    metadata: z.ZodOptional<z.ZodObject<{
+        toolName: z.ZodString;
+        version: z.ZodString;
+        timestamp: z.ZodString;
+    }, z.core.$catchall<z.ZodAny>>>;
+}, z.core.$strip>;
+type SpokeOutput = z.infer<typeof SpokeOutputSchema>;
+/**
+ * Master Unified Report contract (CLI -> Platform).
+ */
+declare const UnifiedReportSchema: z.ZodObject<{
+    summary: z.ZodObject<{
+        totalFiles: z.ZodNumber;
+        totalIssues: z.ZodNumber;
+        criticalIssues: z.ZodNumber;
+        majorIssues: z.ZodNumber;
+    }, z.core.$strip>;
+    results: z.ZodArray<z.ZodObject<{
+        fileName: z.ZodString;
+        issues: z.ZodArray<z.ZodObject<{
+            type: z.ZodEnum<typeof IssueType>;
+            severity: z.ZodEnum<typeof Severity>;
+            message: z.ZodString;
+            location: z.ZodObject<{
+                file: z.ZodString;
+                line: z.ZodNumber;
+                column: z.ZodOptional<z.ZodNumber>;
+                endLine: z.ZodOptional<z.ZodNumber>;
+                endColumn: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strip>;
+            suggestion: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        metrics: z.ZodObject<{
+            tokenCost: z.ZodOptional<z.ZodNumber>;
+            complexityScore: z.ZodOptional<z.ZodNumber>;
+            consistencyScore: z.ZodOptional<z.ZodNumber>;
+            docFreshnessScore: z.ZodOptional<z.ZodNumber>;
+            aiSignalClarityScore: z.ZodOptional<z.ZodNumber>;
+            agentGroundingScore: z.ZodOptional<z.ZodNumber>;
+            testabilityScore: z.ZodOptional<z.ZodNumber>;
+            docDriftScore: z.ZodOptional<z.ZodNumber>;
+            dependencyHealthScore: z.ZodOptional<z.ZodNumber>;
+            modelContextTier: z.ZodOptional<z.ZodEnum<typeof ModelTier>>;
+            estimatedMonthlyCost: z.ZodOptional<z.ZodNumber>;
+            estimatedDeveloperHours: z.ZodOptional<z.ZodNumber>;
+            comprehensionDifficultyIndex: z.ZodOptional<z.ZodNumber>;
+            totalSymbols: z.ZodOptional<z.ZodNumber>;
+            totalExports: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>;
+    }, z.core.$strip>>;
+    scoring: z.ZodOptional<z.ZodObject<{
+        overall: z.ZodNumber;
+        rating: z.ZodString;
+        timestamp: z.ZodString;
+        breakdown: z.ZodArray<z.ZodObject<{
+            toolName: z.ZodUnion<readonly [z.ZodEnum<typeof ToolName>, z.ZodString]>;
+            score: z.ZodNumber;
+        }, z.core.$catchall<z.ZodAny>>>;
+    }, z.core.$strip>>;
+}, z.core.$catchall<z.ZodAny>>;
+type UnifiedReport = z.infer<typeof UnifiedReportSchema>;
+
 /**
  * Cost estimation configuration
  */
@@ -87,15 +311,7 @@ interface ProductivityImpact {
     totalCost: number;
     /** Breakdown by severity */
     bySeverity: {
-        critical: {
-            hours: number;
-            cost: number;
-        };
-        major: {
-            hours: number;
-            cost: number;
-        };
-        minor: {
+        [K in Severity]: {
             hours: number;
             cost: number;
         };
@@ -279,7 +495,7 @@ interface Report {
 /**
  * Severity levels for issues
  */
-type GraphIssueSeverity = 'critical' | 'major' | 'minor' | 'info';
+type GraphIssueSeverity = Severity;
 /**
  * Base graph node
  */
@@ -333,7 +549,7 @@ interface GraphData {
     issues?: {
         id: string;
         type: string;
-        severity: GraphIssueSeverity;
+        severity: Severity;
         nodeIds: string[];
         message: string;
     }[];
@@ -561,53 +777,26 @@ interface ScoringConfig {
  * Default weights for known tools. Weights sum to 100 and read directly as
  * percentage contribution to the overall score.
  * New tools get weight of 5 if not specified.
- *
- * Weight philosophy:
- * - pattern-detect (22%): Semantic duplication directly wastes token budget and
- *   confuses AI with contradictory in-context examples.
- * - context-analyzer (19%): Context limits are the primary hard constraint on
- *   AI effectiveness regardless of model size.
- * - consistency (14%): Naming/pattern inconsistency degrades AI intent understanding
- *   proportionally to codebase size.
- * - ai-signal-clarity (11%): Code patterns empirically causing AI to generate
- *   confidently wrong outputs — critical for agentic use cases.
- * - agent-grounding (10%): How well an autonomous agent can navigate unaided —
- *   increasingly important as agentic workflows grow.
- * - testability (10%): AI changes without verifiability create hidden risk.
- * - doc-drift (8%): Stale docs actively mislead AI; planned spoke.
- * - deps (6%): Dependency health affects AI suggestion accuracy; planned spoke.
  */
 declare const DEFAULT_TOOL_WEIGHTS: Record<string, number>;
 /**
- * Tool name normalization map (shorthand -> full name)
+ * Tool name normalization map (shorthand -> canonical 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>;
 /**
@@ -619,30 +808,21 @@ declare function getProjectSizeTier(fileCount: number): keyof typeof SIZE_ADJUST
  */
 declare function getRecommendedThreshold(fileCount: number, modelTier?: ModelContextTier): number;
 /**
- * Normalize tool name from shorthand to full name
+ * Normalize tool name from shorthand to canonical name
  */
 declare function normalizeToolName(shortName: string): string;
 /**
- * Get tool weight with fallback priority:
- * 1. CLI override
- * 2. Tool config scoreWeight
- * 3. Default weight
- * 4. 10 (for unknown tools)
+ * Get tool weight
  */
 declare function getToolWeight(toolName: string, toolConfig?: {
     scoreWeight?: number;
 }, cliOverride?: number): number;
 /**
- * Parse weight string from CLI (e.g., "patterns:50,context:30")
+ * Parse weight string from CLI
  */
 declare function parseWeightString(weightStr?: string): Map<string, number>;
 /**
- * Calculate overall AI Readiness Score from multiple tool scores.
- *
- * Formula: Σ(tool_score × tool_weight) / Σ(active_tool_weights)
- *
- * This allows dynamic composition - score adjusts automatically
- * based on which tools actually ran.
+ * Calculate overall AI Readiness Score
  */
 declare function calculateOverallScore(toolOutputs: Map<string, ToolScoringOutput>, config?: any, cliWeights?: Map<string, number>): ScoringResult;
 /**
@@ -651,18 +831,17 @@ declare function calculateOverallScore(toolOutputs: Map<string, ToolScoringOutpu
 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
+ * Get rating display properties
  */
 declare function getRatingDisplay(rating: ScoringResult['rating']): {
     emoji: string;
     color: string;
 };
 /**
- * Format score for display with rating
+ * Format score for display
  */
 declare function formatScore(result: ScoringResult): string;
 /**
@@ -683,4 +862,4 @@ declare function formatToolScore(output: ToolScoringOutput): string;
  */
 declare function generateHTML(graph: GraphData): string;
 
-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 TechnicalValueChain, type TechnicalValueChainSummary, type TokenBudget, type ToolScoringOutput, calculateOverallScore, formatScore, formatToolScore, generateHTML, getProjectSizeTier, getRating, getRatingDisplay, getRatingWithContext, getRecommendedThreshold, getToolWeight, normalizeToolName, parseWeightString };
+export { type AIReadyConfig, type AcceptancePrediction, type AnalysisResult, AnalysisResultSchema, AnalysisStatus, AnalysisStatusSchema, type BusinessReport, CONTEXT_TIER_THRESHOLDS, type CommonASTNode, type ComprehensionDifficulty, type CostConfig, DEFAULT_TOOL_WEIGHTS, type ExportInfo, FRIENDLY_TOOL_NAMES, type GraphData, type GraphEdge, type GraphIssueSeverity, type GraphMetadata, type GraphNode, type ImportInfo, type Issue, IssueSchema, IssueType, IssueTypeSchema, LANGUAGE_EXTENSIONS, Language, type LanguageConfig, type LanguageParser, type Location, LocationSchema, type Metrics, MetricsSchema, type ModelContextTier, ModelTier, ModelTierSchema, type NamingConvention, ParseError, type ParseResult, type ParseStatistics, type ProductivityImpact, type Report, SIZE_ADJUSTED_THRESHOLDS, type ScanOptions, type ScoringConfig, type ScoringResult, Severity, SeveritySchema, type SourceLocation, type SourceRange, type SpokeOutput, SpokeOutputSchema, TOOL_NAME_MAP, type TechnicalValueChain, type TechnicalValueChainSummary, type TokenBudget, ToolName, ToolNameSchema, type ToolScoringOutput, type UnifiedReport, UnifiedReportSchema, calculateOverallScore, formatScore, formatToolScore, generateHTML, getProjectSizeTier, getRating, getRatingDisplay, getRatingWithContext, getRecommendedThreshold, getToolWeight, normalizeToolName, parseWeightString };