@aiready/core 0.23.2 → 0.23.4

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { ToolName, ScanOptions, SpokeOutput, ToolScoringOutput, AnalysisResult, AIReadyConfig, ModelContextTier, CostConfig, TokenBudget, ProductivityImpact, AcceptancePrediction, ComprehensionDifficulty, TechnicalValueChainSummary, TechnicalValueChain, LanguageParser, Language, ExportInfo, ParseResult, NamingConvention } from './client.js';
-export { AiSignalClarityConfig, AnalysisResultSchema, AnalysisStatus, AnalysisStatusSchema, BaseToolConfig, BusinessReport, COMMON_FINE_TUNING_OPTIONS, CONTEXT_TIER_THRESHOLDS, CommonASTNode, ContextAnalyzerConfig, DEFAULT_TOOL_WEIGHTS, FRIENDLY_TOOL_NAMES, GLOBAL_INFRA_OPTIONS, GLOBAL_SCAN_OPTIONS, GraphData, GraphEdge, GraphIssueSeverity, GraphMetadata, GraphNode, ImportInfo, Issue, IssueSchema, IssueType, IssueTypeSchema, LANGUAGE_EXTENSIONS, LanguageConfig, Location, LocationSchema, Metrics, MetricsSchema, ModelTier, ModelTierSchema, NamingConsistencyConfig, ParseError, ParseStatistics, PatternDetectConfig, ReadinessRating, RecommendationPriority, Report, SCORING_PROFILES, SIZE_ADJUSTED_THRESHOLDS, ScoringConfig, ScoringProfile, ScoringResult, Severity, SeveritySchema, SourceLocation, SourceRange, SpokeOutputSchema, SpokeSummary, SpokeSummarySchema, TOOL_NAME_MAP, ToolNameSchema, UnifiedReport, UnifiedReportSchema, calculateOverallScore, formatScore, formatToolScore, generateHTML, getProjectSizeTier, getRating, getRatingDisplay, getRatingWithContext, getRecommendedThreshold, getToolWeight, normalizeToolName, parseWeightString } from './client.js';
+import { T as ToolName, S as ScanOptions, a as SpokeOutput, b as ToolScoringOutput, c as Severity, A as AnalysisResult, E as ExportWithImports, d as ASTNode, F as FileImport, e as AIReadyConfig, M as ModelContextTier, C as CostConfig, f as TokenBudget, P as ProductivityImpact, g as AcceptancePrediction, h as ComprehensionDifficulty, i as TechnicalValueChainSummary, j as TechnicalValueChain, L as LanguageParser, k as Language, l as ExportInfo, m as ParseResult, N as NamingConvention, I as ImportInfo } from './client-D-cn9ydj.js';
+export { n as AnalysisResultSchema, o as AnalysisStatus, p as AnalysisStatusSchema, B as BusinessMetrics, q as COMMON_FINE_TUNING_OPTIONS, r as CONTEXT_TIER_THRESHOLDS, s as CommonASTNode, t as Config, D as DEFAULT_TOOL_WEIGHTS, u as FRIENDLY_TOOL_NAMES, v as FileContent, G as GLOBAL_INFRA_OPTIONS, w as GLOBAL_SCAN_OPTIONS, x as GraphData, y as GraphEdge, z as GraphIssueSeverity, H as GraphMetadata, J as GraphNode, K as Issue, O as IssueSchema, Q as IssueType, R as IssueTypeSchema, U as LANGUAGE_EXTENSIONS, V as LanguageConfig, W as Location, X as LocationSchema, Y as Metrics, Z as MetricsSchema, _ as ModelTier, $ as ModelTierSchema, a0 as ParseError, a1 as ParseStatistics, a2 as ReadinessRating, a3 as RecommendationPriority, a4 as SCORING_PROFILES, a5 as SIZE_ADJUSTED_THRESHOLDS, a6 as ScanResult, a7 as ScoringConfig, a8 as ScoringProfile, a9 as ScoringResult, aa as SeveritySchema, ab as SourceLocation, ac as SourceRange, ad as SpokeOutputSchema, ae as SpokeSummary, af as SpokeSummarySchema, ag as TOOL_NAME_MAP, ah as ToolNameSchema, ai as ToolOptions, aj as ToolOutput, ak as UnifiedReport, al as UnifiedReportSchema, am as calculateOverallScore, an as formatScore, ao as formatToolScore, ap as generateHTML, aq as getProjectSizeTier, ar as getRating, as as getRatingDisplay, at as getRatingSlug, au as getRatingWithContext, av as getRecommendedThreshold, aw as getToolWeight, ax as normalizeToolName, ay as parseWeightString } from './client-D-cn9ydj.js';
 import { z } from 'zod';
 import * as Parser from 'web-tree-sitter';
 import { TSESTree } from '@typescript-eslint/typescript-estree';
@@ -123,7 +123,17 @@ declare class ToolRegistry {
     static clear(): void;
 }
 
+/**
+ * Default file exclusion patterns for AIReady scans.
+ * These patterns are applied to exclude build artifacts, dependencies,
+ * test files, and other non-source files from analysis.
+ */
 declare const DEFAULT_EXCLUDE: string[];
+/**
+ * Set of vague/abiguous file names that indicate poor code organization.
+ * These names don't convey the file's purpose and make it harder for AI
+ * to understand the codebase structure.
+ */
 declare const VAGUE_FILE_NAMES: Set<string>;
 /**
  * Scan files in a directory using glob patterns
@@ -143,17 +153,53 @@ declare function scanEntries(options: ScanOptions): Promise<{
     files: string[];
     dirs: string[];
 }>;
+/**
+ * Read the contents of a file as a UTF-8 string.
+ * @param filePath - Absolute path to the file to read
+ * @returns The file contents as a string
+ */
+/**
+ * Read the contents of a file as a UTF-8 string.
+ * @param filePath - Absolute path to the file to read
+ * @returns The file contents as a string
+ */
 declare function readFileContent(filePath: string): Promise<string>;
+/**
+ * Extract the file extension from a file path.
+ * @param filePath - The file path to extract extension from
+ * @returns The file extension without the dot (e.g., 'ts', 'js', 'py')
+ */
+/**
+ * Extract the file extension from a file path.
+ * @param filePath - The file path to extract extension from
+ * @returns The file extension without the dot (e.g., 'ts', 'js', 'py')
+ */
 declare function getFileExtension(filePath: string): string;
+/**
+ * Check if a file is a source code file based on its extension.
+ * Supports TypeScript, JavaScript, Python, Java, Go, Rust, and C#.
+ * @param filePath - The file path to check
+ * @returns True if the file has a source code extension
+ */
+/**
+ * Check if a file is a source code file based on its extension.
+ * Supports TypeScript, JavaScript, Python, Java, Go, Rust, and C#.
+ * @param filePath - The file path to check
+ * @returns True if the file has a source code extension
+ */
 declare function isSourceFile(filePath: string): boolean;
 
 /**
  * Common CLI configuration interface
  */
 interface CLIOptions {
+    /** Root directory for analysis */
     rootDir: string;
+    /** Glob patterns to include */
     include?: string[];
+    /** Glob patterns to exclude */
     exclude?: string[];
+    /** Any other tool-specific options */
     [key: string]: any;
 }
 /**
@@ -167,49 +213,101 @@ interface CLIOptions {
 declare function resolveOutputPath(userPath: string | undefined, defaultFilename: string, workingDir?: string): string;
 /**
  * Load and merge configuration with CLI options
+ * @param directory Root directory to load config from
+ * @param defaults Default configuration values
+ * @param cliOptions Configuration overrides from CLI arguments
+ * @returns Merged configuration object
  */
 declare function loadMergedConfig<T extends Record<string, any>>(directory: string, defaults: T, cliOptions: Partial<T>): Promise<T & {
     rootDir: string;
 }>;
 /**
- * Handle JSON output for CLI commands
+ * Handle JSON output for CLI commands.
+ * Writes to file if outputFile is provided, otherwise logs to console.
+ * @param data Data to output
+ * @param outputFile Optional path to save JSON file
+ * @param successMessage Optional message to show on success
  */
 declare function handleJSONOutput(data: any, outputFile?: string, successMessage?: string): void;
 /**
- * Common error handler for CLI commands
+ * Common error handler for CLI commands.
+ * Logs error and exits process with code 1.
+ * @param error Error object or message
+ * @param commandName Name of the command that failed
  */
 declare function handleCLIError(error: unknown, commandName: string): never;
 /**
  * Calculate elapsed time and format for display
+ * @param startTime timestamp in milliseconds
+ * @returns Formatted seconds (e.g. "1.23")
  */
 declare function getElapsedTime(startTime: number): string;
 /**
  * Generate a visual score bar for console output
+ * @param val Score value (0-100)
+ * @returns String representation of the bar (e.g. "█████░░░░░")
  */
 declare function getScoreBar(val: number): string;
 /**
  * Get status icon for safety ratings
+ * @param rating Safety rating slug
+ * @returns Emoji icon representating the rating
  */
 declare function getSafetyIcon(rating: string): string;
 /**
  * Emit progress update with throttling to reduce log noise
+ * @param processed Number of items processed
+ * @param total Total items to process
+ * @param toolId Tool identifier
+ * @param message Progress message
+ * @param onProgress Global progress callback
+ * @param throttleCount Frequency of updates (every N items)
  */
 declare function emitProgress(processed: number, total: number, toolId: string, message: string, onProgress?: (processed: number, total: number, message: string) => void, throttleCount?: number): void;
 /**
  * Get chalk color function for a given severity
- * @param severity severity level
- * @param chalk chalk instance
+ * @param severity Severity level string
+ * @param chalkInstance Chalk instance to use
+ * @returns Chalk color function
+ */
+declare function getSeverityColor(severity: string, chalkInstance?: any): any;
+/**
+ * Get numeric severity value for comparison (4-1)
+ * @param s Severity level string
+ * @returns Numeric value (4: critical, 3: major, 2: minor, 1: info)
+ */
+declare function getSeverityValue(s: string | undefined): number;
+/**
+ * Get numeric severity level (alias for getSeverityValue)
+ * @param s Severity level string
+ * @returns Numeric value
  */
-declare function getSeverityColor(severity: string, chalk: any): any;
+declare function getSeverityLevel(s: string | undefined): number;
 /**
- * Find the latest aiready report in a directory by modification time
- * Searches for both new format (aiready-report-*) and legacy format (aiready-scan-*)
+ * Get colored severity badge for console output
+ * @param severity Severity level
+ * @param chalkInstance Chalk instance (optional)
+ * @returns Formatted badge string
+ */
+declare function getSeverityBadge(severity: Severity | string, chalkInstance?: any): string;
+/**
+ * Get Severity enum from string for internal logic
+ * @param s Severity level string
+ * @returns Normalized severity string
+ */
+declare function getSeverityEnum(s: string | undefined): any;
+/**
+ * Find the latest aiready report in a directory by modification time.
+ * Searches for both new format (aiready-report-*) and legacy format (aiready-scan-*).
  * @param dirPath - The directory path to search for .aiready directory
  * @returns The path to the latest report or null if not found
  */
 declare function findLatestReport(dirPath: string): string | null;
 /**
- * Find the latest scan report file in a directory
+ * Find the latest scan report file with a specific prefix.
+ * @param scanReportsDir Directory containing reports
+ * @param reportFilePrefix Filename prefix to match (e.g. "report-")
+ * @returns Path to the latest matching report or null
  */
 declare function findLatestScanReport(scanReportsDir: string, reportFilePrefix: string): string | null;
 
@@ -249,55 +347,52 @@ interface ProviderFactoryConfig<TReport> {
  */
 declare function createProvider<TReport>(config: ProviderFactoryConfig<TReport>): ToolProvider;
 
-interface ExportWithImports {
-    name: string;
-    type: 'function' | 'class' | 'const' | 'type' | 'interface' | 'default';
-    imports: string[];
-    dependencies: string[];
-    typeReferences: string[];
-    loc?: {
-        start: {
-            line: number;
-            column: number;
-        };
-        end: {
-            line: number;
-            column: number;
-        };
-    };
-}
-interface FileImport {
-    source: string;
-    specifiers: string[];
-    isTypeOnly: boolean;
-}
 /**
- * Parse TypeScript/JavaScript file and extract exports with their import dependencies
+ * Parse TypeScript/JavaScript file and extract exports with their import dependencies.
+ * Automatically handles different languages via the parser factory.
+ *
+ * @param code - The source code to parse
+ * @param filePath - Path to the file (used for language detection and AST metadata)
+ * @returns Object containing all identified exports and imports
  */
 declare function parseFileExports(code: string, filePath: string): {
     exports: ExportWithImports[];
     imports: FileImport[];
 };
 /**
- * Calculate import-based similarity between two exports (Jaccard index)
+ * Calculate import-based similarity between two exports using Jaccard index.
+ * Returns a score between 0 and 1 representing the overlap in imported symbols.
+ *
+ * @param export1 - First export to compare
+ * @param export2 - Second export to compare
+ * @returns Similarity score (0 = no overlap, 1 = identical imports)
  */
 declare function calculateImportSimilarity(export1: ExportWithImports, export2: ExportWithImports): number;
-interface ASTNode {
-    type: string;
-    loc?: {
-        start: {
-            line: number;
-            column: number;
-        };
-        end: {
-            line: number;
-            column: number;
-        };
-    };
-}
-declare function parseCode(code: string, language: string): ASTNode | null;
-declare function extractFunctions(ast: ASTNode): ASTNode[];
-declare function extractImports(ast: ASTNode): string[];
+/**
+ * Parse code into an AST node.
+ * @deprecated Use parseFileExports instead for full dependency analysis.
+ *
+ * @param code - Source code to parse
+ * @param language - Target language
+ * @returns Generic AST node or null if unsupported
+ */
+declare function parseCode(_code: string, _language: string): ASTNode | null;
+/**
+ * Extract functions from an AST.
+ * @deprecated Use parseFileExports instead for complete export metadata.
+ *
+ * @param ast - The AST to scan
+ * @returns Array of function nodes
+ */
+declare function extractFunctions(_ast: ASTNode): ASTNode[];
+/**
+ * Extract imports from an AST.
+ * @deprecated Use parseFileExports instead for structured import info.
+ *
+ * @param ast - The AST to scan
+ * @returns Array of imported module names
+ */
+declare function extractImports(_ast: ASTNode): string[];
 
 /**
  * Estimate token count for text (rough approximation)
@@ -305,7 +400,18 @@ declare function extractImports(ast: ASTNode): string[];
  */
 declare function estimateTokens(text: string): number;
 
+/**
+ * Search upwards for AIReady configuration files and load the first one found.
+ * @param rootDir Starting directory for the search
+ * @returns Parsed configuration object or null if not found
+ */
 declare function loadConfig(rootDir: string): Promise<AIReadyConfig | null>;
+/**
+ * Merge user-provided configuration with default settings.
+ * @param userConfig The configuration loaded from file
+ * @param defaults The default configuration object
+ * @returns Merged configuration with all defaults applied
+ */
 declare function mergeConfigWithDefaults(userConfig: AIReadyConfig | null, defaults: any): any;
 
 /**
@@ -433,27 +539,49 @@ declare function calculateComprehensionDifficulty(contextBudget: number, importD
  */
 
 /**
- * Historical score entry for trend tracking
+ * Historical score entry for trend tracking.
+ * Used to store and compare results across different points in time.
  */
 interface ScoreHistoryEntry {
+    /** ISO timestamp of the scan */
     timestamp: string;
+    /** Overall score (0-100) */
     overallScore: number;
+    /** Breakdown of scores by tool */
     breakdown: Record<string, number>;
+    /** Total number of issues detected */
     totalIssues: number;
+    /** Total tokens analyzed */
     totalTokens: number;
 }
 /**
- * Trend analysis comparing current vs historical scores
+ * Trend analysis comparing current vs historical scores.
+ * Helps teams understand if their AI-readiness is improving or degrading.
  */
 interface ScoreTrend {
+    /** Overall trend direction */
     direction: 'improving' | 'stable' | 'degrading';
+    /** Percentage change in score over last 30 days */
     change30Days: number;
+    /** Percentage change in score over last 90 days */
     change90Days: number;
+    /** Rate of change (points per week) */
     velocity: number;
+    /** Projected score in 30 days based on current velocity */
     projectedScore: number;
 }
 /**
- * Calculate Aggregate Business ROI
+ * Calculate Aggregate Business ROI from code analysis results.
+ *
+ * This high-level function combines token waste and productivity impact
+ * to produce a monthly and annual dollar value of the issues found.
+ *
+ * @param params - Parameters for ROI calculation
+ * @param params.tokenWaste - Estimated total tokens wasted on context inefficiencies
+ * @param params.issues - Array of issues with severity levels for productivity impact
+ * @param params.developerCount - Number of developers in the team (default: 5)
+ * @param params.modelId - AI model ID for pricing model selection (default: 'claude-4.6')
+ * @returns Business ROI metrics including savings and recommendations
  */
 declare function calculateBusinessROI(params: {
     tokenWaste: number;
@@ -463,25 +591,49 @@ declare function calculateBusinessROI(params: {
     developerCount?: number;
     modelId?: string;
 }): {
+    /** Estimated monthly savings if issues are resolved */
     monthlySavings: number;
+    /** Total developer hours gained per month */
     productivityGainHours: number;
+    /** Projected total annual business value gained */
     annualValue: number;
 };
 /**
- * Format cost for display
+ * Format currency value for display in console or reports.
+ *
+ * Handles small values with decimals and large values with 'k' suffix.
+ *
+ * @param cost Cost in USD
+ * @returns Formatted currency string (e.g. "$0.50", "$500", "$1.2k")
  */
 declare function formatCost(cost: number): string;
 /**
- * Format hours for display
+ * Format time duration in hours for display in console or reports.
+ *
+ * Automatically switches between minutes, hours, and weeks based on magnitude.
+ *
+ * @param hours Number of hours
+ * @returns Formatted duration string (e.g. "30min", "4.5h", "2.1 weeks")
  */
 declare function formatHours(hours: number): string;
 
 /**
- * Format acceptance rate for display
+ * Format AI acceptance rate as a human-readable percentage string.
+ * @param rate Rate value between 0 and 1
+ * @returns Formatted percentage (e.g. "85%")
  */
 declare function formatAcceptanceRate(rate: number): string;
 /**
- * Generate technical value chain for an issue (v0.12 legacy)
+ * Generate a technical value chain map for a specific issue category.
+ *
+ * maps technical metrics (like duplication count) to business outcomes
+ * by explaining the impact on AI models and developer workflow.
+ *
+ * @param params Issue information
+ * @param params.issueType Unique identifier for the issue type
+ * @param params.count Total occurrences of this issue
+ * @param params.severity Severity level of the issues
+ * @returns A structured technical value chain object
  */
 declare function generateValueChain(params: {
     issueType: string;
@@ -607,24 +759,43 @@ declare class TypeScriptParser implements LanguageParser {
 }
 
 /**
- * Python Parser implementation using tree-sitter
+ * Base Language Parser implementation to consolidate shared logic
  */
-declare class PythonParser implements LanguageParser {
-    readonly language = Language.Python;
-    readonly extensions: string[];
-    private parser;
-    private initialized;
+declare abstract class BaseLanguageParser implements LanguageParser {
+    abstract readonly language: Language;
+    abstract readonly extensions: string[];
+    protected parser: Parser.Parser | null;
+    protected initialized: boolean;
     /**
      * Initialize the tree-sitter parser
      */
     initialize(): Promise<void>;
-    getAST(code: string, filePath: string): Promise<Parser.Tree | null>;
-    analyzeMetadata(node: Parser.Node, code: string): Partial<ExportInfo>;
+    /**
+     * Get the parser name for tree-sitter setup
+     */
+    protected abstract getParserName(): string;
+    getAST(code: string, _filePath?: string): Promise<Parser.Tree | null>;
+    abstract analyzeMetadata(node: Parser.Node, code: string): Partial<ExportInfo>;
     parse(code: string, filePath: string): ParseResult;
-    private extractImportsAST;
-    private extractExportsAST;
+    protected abstract extractImportsAST(rootNode: Parser.Node): ImportInfo[];
+    protected abstract extractExportsAST(rootNode: Parser.Node, code: string): ExportInfo[];
+    protected abstract parseRegex(code: string, filePath: string): ParseResult;
+    abstract getNamingConventions(): NamingConvention;
+    canHandle(filePath: string): boolean;
+}
+
+/**
+ * Python Parser implementation using tree-sitter
+ */
+declare class PythonParser extends BaseLanguageParser {
+    readonly language = Language.Python;
+    readonly extensions: string[];
+    protected getParserName(): string;
+    analyzeMetadata(node: Parser.Node, code: string): Partial<ExportInfo>;
+    protected extractImportsAST(rootNode: Parser.Node): ImportInfo[];
+    protected extractExportsAST(rootNode: Parser.Node, code: string): ExportInfo[];
     private extractParameters;
-    private parseRegex;
+    protected parseRegex(code: string, filePath: string): ParseResult;
     getNamingConventions(): NamingConvention;
     canHandle(filePath: string): boolean;
     private extractImportsRegex;
@@ -634,21 +805,14 @@ declare class PythonParser implements LanguageParser {
 /**
  * Java Parser implementation using tree-sitter
  */
-declare class JavaParser implements LanguageParser {
+declare class JavaParser extends BaseLanguageParser {
     readonly language = Language.Java;
     readonly extensions: string[];
-    private parser;
-    private initialized;
-    /**
-     * Initialize the tree-sitter parser
-     */
-    initialize(): Promise<void>;
-    getAST(code: string, filePath: string): Promise<Parser.Tree | null>;
+    protected getParserName(): string;
     analyzeMetadata(node: Parser.Node, code: string): Partial<ExportInfo>;
-    parse(code: string, filePath: string): ParseResult;
-    private parseRegex;
-    private extractImportsAST;
-    private extractExportsAST;
+    protected parseRegex(code: string): ParseResult;
+    protected extractImportsAST(rootNode: Parser.Node): ImportInfo[];
+    protected extractExportsAST(rootNode: Parser.Node, code: string): ExportInfo[];
     private getModifiers;
     private extractSubExports;
     private extractParameters;
@@ -659,21 +823,14 @@ declare class JavaParser implements LanguageParser {
 /**
  * C# Parser implementation using tree-sitter
  */
-declare class CSharpParser implements LanguageParser {
+declare class CSharpParser extends BaseLanguageParser {
     readonly language = Language.CSharp;
     readonly extensions: string[];
-    private parser;
-    private initialized;
-    /**
-     * Initialize the tree-sitter parser
-     */
-    initialize(): Promise<void>;
-    getAST(code: string, filePath: string): Promise<Parser.Tree | null>;
+    protected getParserName(): string;
     analyzeMetadata(node: Parser.Node, code: string): Partial<ExportInfo>;
-    parse(code: string, filePath: string): ParseResult;
-    private parseRegex;
-    private extractImportsAST;
-    private extractExportsAST;
+    protected parseRegex(code: string): ParseResult;
+    protected extractImportsAST(rootNode: Parser.Node): ImportInfo[];
+    protected extractExportsAST(rootNode: Parser.Node, code: string): ExportInfo[];
     private getModifiers;
     private extractParameters;
     getNamingConventions(): NamingConvention;
@@ -683,21 +840,14 @@ declare class CSharpParser implements LanguageParser {
 /**
  * Go Parser implementation using tree-sitter
  */
-declare class GoParser implements LanguageParser {
+declare class GoParser extends BaseLanguageParser {
     readonly language = Language.Go;
     readonly extensions: string[];
-    private parser;
-    private initialized;
-    /**
-     * Initialize the tree-sitter parser
-     */
-    initialize(): Promise<void>;
-    getAST(code: string, filePath: string): Promise<Parser.Tree | null>;
+    protected getParserName(): string;
     analyzeMetadata(node: Parser.Node, code: string): Partial<ExportInfo>;
-    parse(code: string, filePath: string): ParseResult;
-    private parseRegex;
-    private extractImportsAST;
-    private extractExportsAST;
+    protected parseRegex(code: string): ParseResult;
+    protected extractImportsAST(rootNode: Parser.Node): ImportInfo[];
+    protected extractExportsAST(rootNode: Parser.Node, code: string): ExportInfo[];
     private extractParameters;
     getNamingConventions(): NamingConvention;
     canHandle(filePath: string): boolean;
@@ -757,31 +907,64 @@ declare function calculateSemanticDistance(params: {
  * Structural Metrics
  * Measures pattern entropy and concept cohesion.
  */
+/**
+ * Represents the entropy of patterns in a domain
+ */
 interface PatternEntropy {
+    /** Domain identifier */
     domain: string;
+    /** Entropy score (0-1) where higher mean more fragmented */
     entropy: number;
+    /** Human-readable structural rating */
     rating: 'crystalline' | 'well-structured' | 'moderate' | 'fragmented' | 'chaotic';
+    /** Distribution metrics */
     distribution: {
+        /** Number of distinct locations */
         locationCount: number;
+        /** Single most frequent location */
         dominantLocation: string;
+        /** Gini coefficient of concentration (0-1) */
         giniCoefficient: number;
     };
+    /** Recommendations for structural improvement */
     recommendations: string[];
 }
+/**
+ * A file path with its inferred domain
+ */
 interface FileWithDomain {
     path: string;
     domain: string;
 }
+/**
+ * Calculate pattern entropy (degree of fragmentation) for a set of files
+ * @param files Array of files with their domains
+ * @returns Entropy analysis result
+ */
 declare function calculatePatternEntropy(files: FileWithDomain[]): PatternEntropy;
+/**
+ * Measures how focused a set of concepts is within a domain
+ */
 interface ConceptCohesion {
+    /** Normalized score (0-1) where 1 is perfect cohesion */
     score: number;
+    /** Human-readable rating */
     rating: 'excellent' | 'good' | 'moderate' | 'poor';
+    /** Detailed cohesion metrics */
     analysis: {
+        /** Number of distinct domains involved */
         uniqueDomains: number;
+        /** Percentage of exports belonging to the dominant domain */
         domainConcentration: number;
+        /** Ratio of unique domains to total exports */
         exportPurposeClarity: number;
     };
 }
+/**
+ * Calculate concept cohesion for a set of exports
+ * @param params Object containing exports to analyze
+ * @returns Cohesion analysis result
+ */
 declare function calculateConceptCohesion(params: {
     exports: Array<{
         name: string;
@@ -794,20 +977,41 @@ declare function calculateConceptCohesion(params: {
  * AI Signal Clarity Metrics
  * Measures code patterns that increase the likelihood of AI generating incorrect code.
  */
+/**
+ * Represents a single risk signal affecting AI clarity
+ */
 interface AiSignalClaritySignal {
+    /** Name of the signal */
     name: string;
+    /** Occurrences of this signal */
     count: number;
+    /** Numerical contribution to the risk score */
     riskContribution: number;
+    /** Human-readable description of the risk */
     description: string;
+    /** Examples of problematic patterns */
     examples?: string[];
 }
+/**
+ * Complete AI Signal Clarity analysis result
+ */
 interface AiSignalClarity {
+    /** Normalized risk score (0-100) where higher means more confusion risk */
     score: number;
+    /** Human-readable risk rating */
     rating: 'minimal' | 'low' | 'moderate' | 'high' | 'severe';
+    /** Individual signals detected */
     signals: AiSignalClaritySignal[];
+    /** The single highest risk factor identified */
     topRisk: string;
+    /** Actionable recommendations to improve clarity */
     recommendations: string[];
 }
+/**
+ * Calculate AI Signal Clarity metrics based on various code patterns
+ * @param params Object containing counts of various problematic patterns
+ * @returns Clarity analysis result
+ */
 declare function calculateAiSignalClarity(params: {
     overloadedSymbols: number;
     magicLiterals: number;
@@ -965,10 +1169,22 @@ declare function calculateChangeAmplification(params: {
  *
  * This module provides technology-agnostic metric primitives that will
  * remain valid across changes in AI models, tokenization, and paradigms.
+ *
+ * It focuses on cognitive load, semantic cohesion, and structural entropy.
  */
 
 /**
- * Aggregate Future-Proof Score (Base)
+ * Calculate the Aggregate Future-Proof Score based on core structural metrics.
+ *
+ * Combines cognitive load, pattern entropy, and concept cohesion into a single
+ * normalized score that predicts how well AI systems can handle this code in the long term.
+ *
+ * @param params - Configuration for score calculation
+ * @param params.cognitiveLoad - Cognitive load metrics (file size, depth, fragmentation)
+ * @param params.patternEntropy - Structural randomness vs consistency
+ * @param params.conceptCohesion - Semantic alignment within logical blocks
+ * @param params.semanticDistances - Optional measurements of conceptual drift
+ * @returns ToolScoringOutput containing the final score and influencing factors
  */
 declare function calculateFutureProofScore(params: {
     cognitiveLoad: CognitiveLoad;
@@ -977,7 +1193,13 @@ declare function calculateFutureProofScore(params: {
     semanticDistances?: SemanticDistance[];
 }): ToolScoringOutput;
 /**
- * Complete Extended Future-Proof Score
+ * Calculate a Comprehensive Extended Future-Proof Score.
+ *
+ * Incorporates secondary signals like documentation drift, dependency health,
+ * and testability index to provide a holistic view of the repository's AI readiness.
+ *
+ * @param params - Comprehensive set of metric outputs
+ * @returns ToolScoringOutput with extended analysis results
  */
 declare function calculateExtendedFutureProofScore(params: FutureProofRecommendationParams & {
     semanticDistances?: SemanticDistance[];
@@ -1062,4 +1284,4 @@ declare function severityToAnnotationLevel(severity: string): 'error' | 'warning
  */
 declare function emitIssuesAsAnnotations(issues: any[]): void;
 
-export { AIReadyConfig, type ASTNode, AcceptancePrediction, type AgentGroundingScore, type AiSignalClarity, type AiSignalClaritySignal, AnalysisResult, 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, type ProviderFactoryConfig, 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, buildSimpleProviderScore, buildSpokeOutput, calculateAgentGrounding, calculateAiSignalClarity, calculateBusinessROI, calculateChangeAmplification, calculateCognitiveLoad, calculateComprehensionDifficulty, calculateConceptCohesion, calculateDebtInterest, calculateDependencyHealth, calculateDocDrift, calculateExtendedFutureProofScore, calculateFutureProofScore, calculateImportSimilarity, calculateKnowledgeConcentration, calculateMonthlyCost, calculatePatternEntropy, calculateProductivityImpact, calculateSemanticDistance, calculateTechnicalValueChain, calculateTestabilityIndex, calculateTokenBudget, clearHistory, createProvider, emitAnnotation, emitIssuesAsAnnotations, emitProgress, estimateCostFromBudget, estimateTokens, exportHistory, extractFunctions, extractImports, findLatestReport, findLatestScanReport, formatAcceptanceRate, formatCost, formatHours, generateValueChain, getElapsedTime, getFileCommitTimestamps, getFileExtension, getHistorySummary, getLineRangeLastModifiedCached, getModelPreset, getParser, getRepoMetadata, getSafetyIcon, getScoreBar, getSeverityColor, getSupportedLanguages, getWasmPath, groupIssuesByFile, handleCLIError, handleJSONOutput, initTreeSitter, initializeParsers, isFileSupported, isSourceFile, loadConfig, loadMergedConfig, loadScoreHistory, mergeConfigWithDefaults, parseCode, parseFileExports, predictAcceptanceRate, readFileContent, resolveOutputPath, saveScoreEntry, scanEntries, scanFiles, setupParser, severityToAnnotationLevel, validateSpokeOutput, validateWithSchema };
+export { AIReadyConfig, ASTNode, AcceptancePrediction, type AgentGroundingScore, type AiSignalClarity, type AiSignalClaritySignal, AnalysisResult, type CLIOptions, CSharpParser, type ChangeAmplificationScore, type CognitiveLoad, ComprehensionDifficulty, type ConceptCohesion, CostConfig, DEFAULT_COST_CONFIG, DEFAULT_EXCLUDE, type DependencyHealthScore, type DocDriftRisk, ExportInfo, ExportWithImports, FileImport, type FileWithDomain, GoParser, ImportInfo, JavaParser, type KnowledgeConcentrationRisk, Language, LanguageParser, type LoadFactor, MODEL_PRICING_PRESETS, ModelContextTier, type ModelPricingPreset, NamingConvention, ParseResult, ParserFactory, type PatternEntropy, ProductivityImpact, type ProviderFactoryConfig, PythonParser, SEVERITY_TIME_ESTIMATES, ScanOptions, type ScoreHistoryEntry, type ScoreTrend, type SemanticDistance, Severity, Severity as SeverityType, SpokeOutput, type TechnicalDebtInterest, TechnicalValueChain, TechnicalValueChainSummary, type TestabilityIndex, TokenBudget, ToolName, type ToolProvider, ToolRegistry, ToolScoringOutput, TypeScriptParser, VAGUE_FILE_NAMES, buildSimpleProviderScore, buildSpokeOutput, calculateAgentGrounding, calculateAiSignalClarity, calculateBusinessROI, calculateChangeAmplification, calculateCognitiveLoad, calculateComprehensionDifficulty, calculateConceptCohesion, calculateDebtInterest, calculateDependencyHealth, calculateDocDrift, calculateExtendedFutureProofScore, calculateFutureProofScore, calculateImportSimilarity, calculateKnowledgeConcentration, calculateMonthlyCost, calculatePatternEntropy, calculateProductivityImpact, calculateSemanticDistance, calculateTechnicalValueChain, calculateTestabilityIndex, calculateTokenBudget, clearHistory, createProvider, emitAnnotation, emitIssuesAsAnnotations, emitProgress, estimateCostFromBudget, estimateTokens, exportHistory, extractFunctions, extractImports, findLatestReport, findLatestScanReport, formatAcceptanceRate, formatCost, formatHours, generateValueChain, getElapsedTime, getFileCommitTimestamps, getFileExtension, getHistorySummary, getLineRangeLastModifiedCached, getModelPreset, getParser, getRepoMetadata, getSafetyIcon, getScoreBar, getSeverityBadge, getSeverityColor, getSeverityEnum, getSeverityLevel, getSeverityValue, getSupportedLanguages, getWasmPath, groupIssuesByFile, handleCLIError, handleJSONOutput, initTreeSitter, initializeParsers, isFileSupported, isSourceFile, loadConfig, loadMergedConfig, loadScoreHistory, mergeConfigWithDefaults, parseCode, parseFileExports, predictAcceptanceRate, readFileContent, resolveOutputPath, saveScoreEntry, scanEntries, scanFiles, setupParser, severityToAnnotationLevel, validateSpokeOutput, validateWithSchema };