@aiready/core 0.21.17 → 0.21.21

package/dist/client.d.mts

@@ -235,6 +235,11 @@ declare const UnifiedReportSchema: z.ZodObject<{
         totalIssues: z.ZodNumber;
         criticalIssues: z.ZodNumber;
         majorIssues: z.ZodNumber;
+        businessImpact: z.ZodOptional<z.ZodObject<{
+            estimatedMonthlyWaste: z.ZodOptional<z.ZodNumber>;
+            potentialSavings: z.ZodOptional<z.ZodNumber>;
+            productivityHours: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
     }, z.core.$strip>;
     results: z.ZodArray<z.ZodObject<{
         fileName: z.ZodString;
@@ -443,103 +448,142 @@ declare const GLOBAL_INFRA_OPTIONS: string[];
  */
 declare const COMMON_FINE_TUNING_OPTIONS: string[];
 declare const GLOBAL_SCAN_OPTIONS: string[];
+/**
+ * Base configuration for any AIReady tool
+ */
+interface BaseToolConfig {
+    /** Whether this tool is enabled for the scan */
+    enabled?: boolean;
+    /** Custom weight for overall score calculation (sum should be 100) */
+    scoreWeight?: number;
+    /** Catch-all for any other tool-specific options */
+    [key: string]: any;
+}
+/**
+ * Configuration for the pattern-detect tool (semantic duplicate detection)
+ */
+interface PatternDetectConfig extends BaseToolConfig {
+    /** Similarity threshold (0-1). Higher = more strict. */
+    minSimilarity?: number;
+    /** Minimum lines to consider a block */
+    minLines?: number;
+    /** Batch size for parallel processing */
+    batchSize?: number;
+    /** Use approximate matching engine for faster results on large repos */
+    approx?: boolean;
+    /** Minimum tokens shared between blocks for candidates */
+    minSharedTokens?: number;
+    /** Maximum number of candidates to compare per block */
+    maxCandidatesPerBlock?: number;
+}
+/**
+ * Configuration for the context-analyzer tool (fragmentation and budget)
+ */
+interface ContextAnalyzerConfig extends BaseToolConfig {
+    /** Maximum directory depth to traverse */
+    maxDepth?: number;
+    /** Maximum tokens allowed per context window */
+    maxContextBudget?: number;
+    /** Minimum cohesion score required (0-1) */
+    minCohesion?: number;
+    /** Maximum fragmentation ratio allowed (0-1) */
+    maxFragmentation?: number;
+    /** Primary focus area for the analyzer */
+    focus?: 'fragmentation' | 'cohesion' | 'depth' | 'all';
+    /** Whether to include dependencies from node_modules */
+    includeNodeModules?: boolean;
+    /** Project-specific domain keywords for better inference */
+    domainKeywords?: string[];
+}
+/**
+ * Configuration for the naming-consistency tool
+ */
+interface NamingConsistencyConfig extends BaseToolConfig {
+    /** Project-approved abbreviations */
+    acceptedAbbreviations?: string[];
+    /** Words that are allowed to be short (like 'id', 'db') */
+    shortWords?: string[];
+    /** Specific checks to disable */
+    disableChecks?: ('single-letter' | 'abbreviation' | 'convention-mix' | 'unclear' | 'poor-naming')[];
+}
+/**
+ * Configuration for the ai-signal-clarity tool
+ */
+interface AiSignalClarityConfig extends BaseToolConfig {
+    /** Detect unnamed constants */
+    checkMagicLiterals?: boolean;
+    /** Detect positional boolean arguments */
+    checkBooleanTraps?: boolean;
+    /** Detect generic names like 'temp', 'data' */
+    checkAmbiguousNames?: boolean;
+    /** Detect public exports missing JSDoc */
+    checkUndocumentedExports?: boolean;
+    /** Detect implicit state mutations */
+    checkImplicitSideEffects?: boolean;
+    /** Detect deeply nested callbacks */
+    checkDeepCallbacks?: boolean;
+}
+/**
+ * Consolidated AIReady configuration schema
+ */
 interface AIReadyConfig {
+    /** Global scan settings */
     scan?: {
+        /** Glob patterns to include */
         include?: string[];
+        /** Glob patterns to exclude */
         exclude?: string[];
+        /** List of tools to execute */
         tools?: string[];
     };
+    /** Tool-specific configurations */
     tools?: {
-        'pattern-detect'?: {
-            enabled?: boolean;
-            scoreWeight?: number;
-            minSimilarity?: number;
-            minLines?: number;
-            batchSize?: number;
-            approx?: boolean;
-            minSharedTokens?: number;
-            maxCandidatesPerBlock?: number;
-            streamResults?: boolean;
-            maxResults?: number;
-        };
-        'context-analyzer'?: {
-            enabled?: boolean;
-            scoreWeight?: number;
-            maxDepth?: number;
-            maxContextBudget?: number;
-            minCohesion?: number;
-            maxFragmentation?: number;
-            focus?: 'fragmentation' | 'cohesion' | 'depth' | 'all';
-            includeNodeModules?: boolean;
-            maxResults?: number;
-            domainKeywords?: string[];
-            domainPatterns?: string[];
-            pathDomainMap?: Record<string, string>;
-        };
-        [ToolName.NamingConsistency]?: {
-            enabled?: boolean;
-            scoreWeight?: number;
-            acceptedAbbreviations?: string[];
-            shortWords?: string[];
-            disableChecks?: ('single-letter' | 'abbreviation' | 'convention-mix' | 'unclear' | 'poor-naming')[];
-        };
-        [ToolName.AiSignalClarity]?: {
-            enabled?: boolean;
-            scoreWeight?: number;
-            checkMagicLiterals?: boolean;
-            checkBooleanTraps?: boolean;
-            checkAmbiguousNames?: boolean;
-            checkUndocumentedExports?: boolean;
-            checkImplicitSideEffects?: boolean;
-            checkDeepCallbacks?: boolean;
-            minSeverity?: string;
-        };
-        [ToolName.AgentGrounding]?: {
-            enabled?: boolean;
-            scoreWeight?: number;
+        'pattern-detect'?: PatternDetectConfig;
+        'context-analyzer'?: ContextAnalyzerConfig;
+        [ToolName.NamingConsistency]?: NamingConsistencyConfig;
+        [ToolName.AiSignalClarity]?: AiSignalClarityConfig;
+        [ToolName.AgentGrounding]?: BaseToolConfig & {
             maxRecommendedDepth?: number;
             readmeStaleDays?: number;
-            additionalVagueNames?: string[];
         };
-        [ToolName.TestabilityIndex]?: {
-            enabled?: boolean;
-            scoreWeight?: number;
+        [ToolName.TestabilityIndex]?: BaseToolConfig & {
             minCoverageRatio?: number;
             testPatterns?: string[];
         };
-        [ToolName.DocDrift]?: {
-            enabled?: boolean;
-            scoreWeight?: number;
+        [ToolName.DocDrift]?: BaseToolConfig & {
             maxCommits?: number;
             staleMonths?: number;
         };
-        [ToolName.DependencyHealth]?: {
-            enabled?: boolean;
-            scoreWeight?: number;
+        [ToolName.DependencyHealth]?: BaseToolConfig & {
             trainingCutoffYear?: number;
         };
-        [ToolName.ChangeAmplification]?: {
-            enabled?: boolean;
-            scoreWeight?: number;
-        };
-        [toolName: string]: {
-            enabled?: boolean;
-            scoreWeight?: number;
-            [key: string]: any;
-        } | undefined;
+        [ToolName.ChangeAmplification]?: BaseToolConfig;
+        /** Support for custom/third-party tools */
+        [toolName: string]: BaseToolConfig | undefined;
     };
+    /** Global scoring and threshold settings */
     scoring?: {
+        /** Minimum overall score required to pass CI/CD */
         threshold?: number;
+        /** Detailed breakdown in terminal output */
         showBreakdown?: boolean;
+        /** Comparison with a previous run */
         compareBaseline?: string;
+        /** Auto-persist result to this path */
         saveTo?: string;
     };
+    /** Console and file output preferences */
     output?: {
+        /** Output format (console, json, html) */
         format?: 'console' | 'json' | 'html';
+        /** Target file for the full report */
         file?: string;
     };
+    /** Graph Visualizer preferences */
     visualizer?: {
+        /** Custom directory grouping levels */
         groupingDirs?: string[];
+        /** Performance constraints for large graphs */
         graph?: {
             maxNodes?: number;
             maxEdges?: number;
@@ -817,10 +861,25 @@ interface ParseStatistics {
 }
 
 /**
- * AI Readiness Scoring System
- *
- * Provides dynamic, composable scoring across multiple analysis tools.
- * Each tool contributes a 0-100 score with configurable weights.
+ * Priority levels for actionable recommendations
+ */
+declare enum RecommendationPriority {
+    High = "high",
+    Medium = "medium",
+    Low = "low"
+}
+/**
+ * AI Readiness Rating categories
+ */
+declare enum ReadinessRating {
+    Excellent = "Excellent",
+    Good = "Good",
+    Fair = "Fair",
+    NeedsWork = "Needs Work",
+    Critical = "Critical"
+}
+/**
+ * Output structure for a single tool's scoring analysis
  */
 interface ToolScoringOutput {
     /** Unique tool identifier (e.g., "pattern-detect") */
@@ -833,43 +892,58 @@ interface ToolScoringOutput {
     rawMetrics: Record<string, any>;
     /** Factors that influenced the score */
     factors: Array<{
+        /** Human-readable name of the factor */
         name: string;
+        /** Points contribution (positive or negative) */
         impact: number;
+        /** Explanation of the factor's impact */
         description: string;
     }>;
     /** Actionable recommendations with estimated impact */
     recommendations: Array<{
+        /** The recommended action to take */
         action: string;
+        /** Potential points increase if implemented */
         estimatedImpact: number;
-        priority: 'high' | 'medium' | 'low';
+        /** Implementation priority */
+        priority: RecommendationPriority | 'high' | 'medium' | 'low';
     }>;
 }
+/**
+ * Consolidated scoring result across all tools
+ */
 interface ScoringResult {
     /** Overall AI Readiness Score (0-100) */
     overall: number;
-    /** Rating category */
-    rating: 'Excellent' | 'Good' | 'Fair' | 'Needs Work' | 'Critical';
+    /** Rating category representing the overall readiness */
+    rating: ReadinessRating | string;
     /** Timestamp of score calculation */
     timestamp: string;
     /** Tools that contributed to this score */
     toolsUsed: string[];
-    /** Breakdown by tool */
+    /** Breakdown by individual tool */
     breakdown: ToolScoringOutput[];
-    /** Calculation details */
+    /** Internal calculation details for transparency */
     calculation: {
+        /** Textual representation of the calculation formula */
         formula: string;
+        /** Weights applied to each tool */
         weights: Record<string, number>;
+        /** Simplified normalized formula output */
         normalized: string;
     };
 }
+/**
+ * Configuration options for the scoring system
+ */
 interface ScoringConfig {
-    /** Minimum passing score (exit code 1 if below) */
+    /** Minimum passing score (CLI will exit with non-zero if below) */
     threshold?: number;
-    /** Show detailed breakdown in output */
+    /** Whether to show the detailed tool-by-tool breakdown */
     showBreakdown?: boolean;
-    /** Path to baseline JSON for comparison */
+    /** Path to a baseline report JSON for trend comparison */
     compareBaseline?: string;
-    /** Auto-save score to this path */
+    /** Target file path to persist the calculated score */
     saveTo?: string;
 }
 /**
@@ -899,52 +973,92 @@ declare const CONTEXT_TIER_THRESHOLDS: Record<ModelContextTier, {
  */
 declare const SIZE_ADJUSTED_THRESHOLDS: Record<string, number>;
 /**
- * Determine project size tier from file count
+ * Determine project size tier based on the total number of files
+ *
+ * @param fileCount Total number of files in the project
+ * @returns A string identifier for the project size tier (xs, small, medium, large, enterprise)
  */
 declare function getProjectSizeTier(fileCount: number): keyof typeof SIZE_ADJUSTED_THRESHOLDS;
 /**
- * Get the recommended minimum threshold for a project
+ * Calculate the recommended minimum AI readiness threshold for a project
+ *
+ * @param fileCount Total number of files in the project
+ * @param modelTier The model context tier targeted (compact, standard, extended, frontier)
+ * @returns The recommended score threshold (0-100)
  */
 declare function getRecommendedThreshold(fileCount: number, modelTier?: ModelContextTier): number;
 /**
- * Normalize tool name from shorthand to canonical name
+ * Normalize a tool name from a shorthand or alias to its canonical ID
+ *
+ * @param shortName The tool shorthand or alias name
+ * @returns The canonical tool ID
  */
 declare function normalizeToolName(shortName: string): string;
 /**
- * Get tool weight
+ * Retrieve the weight for a specific tool, considering overrides
+ *
+ * @param toolName The canonical tool ID
+ * @param toolConfig Optional configuration for the tool containing a weight
+ * @param cliOverride Optional weight override from the CLI
+ * @returns The weight to be used for this tool in overall scoring
  */
 declare function getToolWeight(toolName: string, toolConfig?: {
     scoreWeight?: number;
 }, cliOverride?: number): number;
 /**
- * Parse weight string from CLI
+ * Parse a comma-separated weight string (e.g. "patterns:30,context:10")
+ *
+ * @param weightStr The raw weight string from the CLI or config
+ * @returns A Map of tool IDs to their parsed weights
  */
 declare function parseWeightString(weightStr?: string): Map<string, number>;
 /**
- * Calculate overall AI Readiness Score
+ * Calculate the overall consolidated AI Readiness Score
+ *
+ * @param toolOutputs Map of tool IDs to their individual scoring outputs
+ * @param config Optional global configuration
+ * @param cliWeights Optional weight overrides from the CLI
+ * @returns Consolidate ScoringResult including overall score and rating
  */
 declare function calculateOverallScore(toolOutputs: Map<string, ToolScoringOutput>, config?: any, cliWeights?: Map<string, number>): ScoringResult;
 /**
  * Convert numeric score to rating category
+ *
+ * @param score The numerical AI readiness score (0-100)
+ * @returns The corresponding ReadinessRating category
  */
-declare function getRating(score: number): ScoringResult['rating'];
+declare function getRating(score: number): ReadinessRating;
 /**
  * Convert score to rating with project-size awareness.
+ *
+ * @param score The numerical AI readiness score
+ * @param fileCount Total number of files in the project
+ * @param modelTier The model context tier being targeted
+ * @returns The size-adjusted ReadinessRating
  */
-declare function getRatingWithContext(score: number, fileCount: number, modelTier?: ModelContextTier): ScoringResult['rating'];
+declare function getRatingWithContext(score: number, fileCount: number, modelTier?: ModelContextTier): ReadinessRating;
 /**
- * Get rating display properties
+ * Get rating display properties (emoji and color)
+ *
+ * @param rating The readiness rating category
+ * @returns Object containing display emoji and color string
  */
-declare function getRatingDisplay(rating: ScoringResult['rating']): {
+declare function getRatingDisplay(rating: ReadinessRating | string): {
     emoji: string;
     color: string;
 };
 /**
- * Format score for display
+ * Format score for human-readable console display
+ *
+ * @param result The consolidated scoring result
+ * @returns Formatted string for display
  */
 declare function formatScore(result: ScoringResult): string;
 /**
- * Format individual tool score for display
+ * Format individual tool score for detailed console display
+ *
+ * @param output The scoring output for a single tool
+ * @returns Formatted string with factors and recommendations
  */
 declare function formatToolScore(output: ToolScoringOutput): string;
 
@@ -961,4 +1075,4 @@ declare function formatToolScore(output: ToolScoringOutput): string;
  */
 declare function generateHTML(graph: GraphData): string;
 
-export { type AIReadyConfig, type AcceptancePrediction, type AnalysisResult, AnalysisResultSchema, AnalysisStatus, AnalysisStatusSchema, type BusinessReport, COMMON_FINE_TUNING_OPTIONS, CONTEXT_TIER_THRESHOLDS, type CommonASTNode, type ComprehensionDifficulty, type CostConfig, DEFAULT_TOOL_WEIGHTS, type ExportInfo, FRIENDLY_TOOL_NAMES, GLOBAL_INFRA_OPTIONS, GLOBAL_SCAN_OPTIONS, 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, type SpokeSummary, SpokeSummarySchema, 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 };
+export { type AIReadyConfig, type AcceptancePrediction, type AiSignalClarityConfig, type AnalysisResult, AnalysisResultSchema, AnalysisStatus, AnalysisStatusSchema, type BaseToolConfig, type BusinessReport, COMMON_FINE_TUNING_OPTIONS, CONTEXT_TIER_THRESHOLDS, type CommonASTNode, type ComprehensionDifficulty, type ContextAnalyzerConfig, type CostConfig, DEFAULT_TOOL_WEIGHTS, type ExportInfo, FRIENDLY_TOOL_NAMES, GLOBAL_INFRA_OPTIONS, GLOBAL_SCAN_OPTIONS, 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 NamingConsistencyConfig, type NamingConvention, ParseError, type ParseResult, type ParseStatistics, type PatternDetectConfig, type ProductivityImpact, ReadinessRating, RecommendationPriority, type Report, SIZE_ADJUSTED_THRESHOLDS, type ScanOptions, type ScoringConfig, type ScoringResult, Severity, SeveritySchema, type SourceLocation, type SourceRange, type SpokeOutput, SpokeOutputSchema, type SpokeSummary, SpokeSummarySchema, 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 };