@aiready/context-analyzer 0.21.9 → 0.21.11

package/dist/index.d.ts

@@ -69,7 +69,7 @@ interface ContextAnalysisResult {
  * Classification of file type for analysis context
  * Helps distinguish real issues from false positives
  */
-type FileClassification = 'barrel-export' | 'type-definition' | 'cohesive-module' | 'utility-module' | 'service-file' | 'lambda-handler' | 'email-template' | 'parser-file' | 'nextjs-page' | 'mixed-concerns' | 'unknown';
+type FileClassification = 'barrel-export' | 'type-definition' | 'cohesive-module' | 'utility-module' | 'service-file' | 'lambda-handler' | 'email-template' | 'parser-file' | 'nextjs-page' | 'spoke-module' | 'mixed-concerns' | 'unknown';
 interface ModuleCluster {
     domain: string;
     files: string[];
@@ -169,10 +169,7 @@ interface TypeDependency {
  * @param options - Additional options for cohesion calculation
  * @returns Cohesion score between 0 and 1
  */
-declare function calculateCohesion(exports: ExportInfo[], filePath?: string, options?: any): number;
-/**
- * Analyze AI context window cost for a codebase
- */
+declare function calculateCohesion(exports: any[], filePath?: string, options?: any): number;
 /**
  * Performs deep context analysis of a project.
  * Scans files, builds a dependency graph, calculates context budgets,
@@ -184,43 +181,66 @@ declare function calculateCohesion(exports: ExportInfo[], filePath?: string, opt
 declare function analyzeContext(options: ContextAnalyzerOptions): Promise<ContextAnalysisResult[]>;
 
 /**
- * Auto-detect domain keywords from workspace folder structure
+ * Auto-detect domain keywords from workspace folder structure.
+ *
+ * @param files - Array of file contents to analyze for folder patterns.
+ * @returns Array of singularized domain keywords.
  */
 declare function extractDomainKeywordsFromPaths(files: FileContent[]): string[];
 /**
- * Build a dependency graph from file contents
+ * Build a dependency graph from file contents, resolving imports and extracting metadata.
+ *
+ * @param files - Array of file contents to process.
+ * @param options - Optional configuration for domain detection.
+ * @returns Complete dependency graph with nodes, edges, and semantic matrices.
  */
 declare function buildDependencyGraph(files: FileContent[], options?: {
     domainKeywords?: string[];
 }): DependencyGraph;
 /**
- * Calculate the maximum depth of import tree for a file
+ * Calculate the maximum depth of the import tree for a specific file.
+ *
+ * @param file - File path to start depth calculation from.
+ * @param graph - The dependency graph.
+ * @param visited - Optional set to track visited nodes during traversal.
+ * @param depth - Current recursion depth.
+ * @returns Maximum depth of the import chain.
  */
 declare function calculateImportDepth(file: string, graph: DependencyGraph, visited?: Set<string>, depth?: number): number;
 /**
- * Get all transitive dependencies for a file
+ * Retrieve all transitive dependencies for a specific file.
+ *
+ * @param file - File path to analyze.
+ * @param graph - The dependency graph.
+ * @param visited - Optional set to track visited nodes.
+ * @returns Array of all reachable file paths.
  */
 declare function getTransitiveDependencies(file: string, graph: DependencyGraph, visited?: Set<string>): string[];
 /**
- * Calculate total context budget (tokens needed to understand this file)
+ * Calculate total context budget (tokens needed to understand this file and its dependencies).
+ *
+ * @param file - File path to calculate budget for.
+ * @param graph - The dependency graph.
+ * @returns Total token count including recursive dependencies.
  */
 declare function calculateContextBudget(file: string, graph: DependencyGraph): number;
 /**
- * Detect circular dependencies
+ * Detect circular dependencies (cycles) within the dependency graph.
+ *
+ * @param graph - The dependency graph to scan.
+ * @returns Array of dependency cycles (each cycle is an array of file paths).
  */
 declare function detectCircularDependencies(graph: DependencyGraph): string[][];
 
-/**
- * Calculate cohesion score (how related are exports in a file)
- */
 /**
  * Calculates a cohesion score (0-1) for a module based on its exports,
  * shared imports, and internal structure. High cohesion indicates
  * a well-focused module that is easy for AI models to reason about.
  *
- * @param exports - Exported symbols and their metadata
- * @param imports - Imported symbols and their sources
- * @returns Cohesion score between 0 and 1
+ * @param exports - Exported symbols and their metadata.
+ * @param filePath - Optional file path for context.
+ * @param options - Optional configuration for weights and co-usage context.
+ * @returns Cohesion score between 0 and 1.
  */
 declare function calculateEnhancedCohesion(exports: ExportInfo[], filePath?: string, options?: {
     coUsageMatrix?: Map<string, Map<string, number>>;
@@ -232,10 +252,19 @@ declare function calculateEnhancedCohesion(exports: ExportInfo[], filePath?: str
 }): number;
 /**
  * Calculate structural cohesion for a file based on co-usage patterns.
+ *
+ * @param file - The file path to analyze.
+ * @param coUsageMatrix - Matrix of files frequently imported together.
+ * @returns Cohesion score between 0 and 1 based on co-usage distribution.
  */
 declare function calculateStructuralCohesionFromCoUsage(file: string, coUsageMatrix?: Map<string, Map<string, number>>): number;
 /**
  * Calculate fragmentation score (how scattered is a domain)
+ *
+ * @param files - List of files belonging to the domain.
+ * @param domain - The domain identifier.
+ * @param options - Optional calculation parameters (log scale, thresholds).
+ * @returns Fragmentation score from 0 (perfect) to 1 (highly scattered).
  */
 declare function calculateFragmentation(files: string[], domain: string, options?: {
     useLogScale?: boolean;
@@ -244,11 +273,17 @@ declare function calculateFragmentation(files: string[], domain: string, options
     dependencyCount?: number;
 }): number;
 /**
- * Calculate path entropy for a set of files
+ * Calculate path entropy for a set of files to measure directory distribution.
+ *
+ * @param files - Array of file paths.
+ * @returns Entropy score representing the spread across directories.
  */
 declare function calculatePathEntropy(files: string[]): number;
 /**
- * Calculate directory-distance metric based on common ancestor depth
+ * Calculate directory-distance metric based on common ancestor depth.
+ *
+ * @param files - Array of file paths to compare.
+ * @returns Normalized distance metric (0-1).
  */
 declare function calculateDirectoryDistance(files: string[]): number;
 
@@ -265,6 +300,7 @@ declare const Classification: {
     PARSER: "parser-file";
     COHESIVE_MODULE: "cohesive-module";
     UTILITY_MODULE: "utility-module";
+    SPOKE_MODULE: "spoke-module";
     MIXED_CONCERNS: "mixed-concerns";
     UNKNOWN: "unknown";
 };
@@ -308,10 +344,19 @@ declare function detectModuleClusters(graph: DependencyGraph, options?: {
 
 /**
  * Get classification-specific recommendations
+ *
+ * @param classification - The identified type of file (e.g., 'barrel-export', 'utility-module').
+ * @param file - File path or identifier.
+ * @param issues - Initial list of issues to supplement.
+ * @returns Array of tailored recommendations.
  */
 declare function getClassificationRecommendations(classification: FileClassification, file: string, issues: string[]): string[];
 /**
- * Generate general context recommendations
+ * Generate general context recommendations based on cross-tool metrics and thresholds.
+ *
+ * @param metrics - Object containing context budget, depth, circular dependencies, cohesion, and fragmentation.
+ * @param thresholds - Configurable limits for each metric.
+ * @returns Object with recommendations array, issues array, and overall severity level.
  */
 declare function getGeneralRecommendations(metrics: {
     contextBudget: number;
@@ -331,9 +376,23 @@ declare function getGeneralRecommendations(metrics: {
 };
 
 /**
- * Calculate AI Readiness Score for context efficiency (0-100)
+ * Calculate AI Readiness Score for context efficiency (0-100).
+ *
+ * Evaluates how efficiently an AI model can process the project's code context
+ * based on token budgets, import depth, and file fragmentation.
+ *
+ * @param summary - Consolidated context summary from the scan.
+ * @param costConfig - Optional configuration for business value calculations.
+ * @returns Standardized scoring output for the context analyzer tool.
+ * @lastUpdated 2026-03-18
  */
 declare function calculateContextScore(summary: ContextSummary, costConfig?: Partial<CostConfig>): ToolScoringOutput;
+/**
+ * Maps a numerical score to a human-readable rating slug.
+ *
+ * @param score - The 0-100 readiness score.
+ * @returns A formatted rating string (e.g., "excellent", "at risk").
+ */
 declare function mapScoreToRating(score: number): string;
 
 /**
@@ -347,46 +406,96 @@ declare function getSmartDefaults(directory: string, userOptions: Partial<Contex
 
 /**
  * Generate summary of context analysis results
+ *
+ * @param results - Array of individual file analysis results.
+ * @param options - Optional scan configuration for context extraction.
+ * @returns A consolidated summary of the entire context scan.
  */
 declare function generateSummary(results: ContextAnalysisResult[], options?: any): ContextSummary;
 
 /**
- * Build co-usage matrix: track which files are imported together
- * @param graph - The dependency graph to analyze
- * @returns Map of file to co-usage counts
+ * Build co-usage matrix: track which files are imported together frequently.
+ *
+ * @param graph - The dependency graph to analyze.
+ * @returns Map of file path to nested map of related files and their co-occurrence counts.
  */
 declare function buildCoUsageMatrix(graph: DependencyGraph): Map<string, Map<string, number>>;
 /**
- * Extract type dependencies from AST exports
- * @param graph - The dependency graph to analyze
- * @returns Map of type references to files that use them
+ * Extract type dependencies from AST exports to build a type-based relationship graph.
+ *
+ * @param graph - The dependency graph to analyze.
+ * @returns Map of type reference names to sets of files that consume or export them.
  */
 declare function buildTypeGraph(graph: DependencyGraph): Map<string, Set<string>>;
 /**
- * Find semantic clusters using co-usage patterns
- * @param coUsageMatrix - The co-usage matrix from buildCoUsageMatrix
- * @param minCoUsage - Minimum co-usage count to consider (default: 3)
- * @returns Map of cluster representative files to their cluster members
+ * Find semantic clusters using frequently occurring co-usage patterns.
+ *
+ * @param coUsageMatrix - The co-usage matrix from buildCoUsageMatrix.
+ * @param minCoUsage - Minimum co-usage count to consider a strong relationship (default: 3).
+ * @returns Map of cluster representative files to their associated cluster members.
  */
 declare function findSemanticClusters(coUsageMatrix: Map<string, Map<string, number>>, minCoUsage?: number): Map<string, string[]>;
 /**
- * Infer domain from semantic analysis (co-usage + types)
+ * Infer domain from semantic analysis (co-usage + types) to identify logical modules.
+ *
+ * @param file - The file path to infer domain for.
+ * @param exportName - The specific export identifier.
+ * @param graph - The full dependency graph.
+ * @param coUsageMatrix - Matrix of files frequently imported together.
+ * @param typeGraph - Map of type references to files.
+ * @param exportTypeRefs - Optional list of types referenced by the export.
+ * @returns Array of potential domain assignments with confidence scores.
  */
 declare function inferDomainFromSemantics(file: string, exportName: string, graph: DependencyGraph, coUsageMatrix: Map<string, Map<string, number>>, typeGraph: Map<string, Set<string>>, exportTypeRefs?: string[]): DomainAssignment[];
+/**
+ * Calculate confidence score for a domain assignment based on signals.
+ *
+ * @param signals - The set of semantic signals detected for a domain.
+ * @returns Numerical confidence score (0-1).
+ */
 declare function calculateDomainConfidence(signals: DomainSignals): number;
 /**
  * Regex-based export extraction (legacy/fallback)
+ *
+ * @param content - Source code content.
+ * @param filePath - Optional file path for domain context.
+ * @param domainOptions - Optional overrides for domain keywords.
+ * @param fileImports - Optional list of actual imports for semantic context.
+ * @returns Array of extracted export information.
  */
 declare function extractExports(content: string, filePath?: string, domainOptions?: {
     domainKeywords?: string[];
 }, fileImports?: string[]): ExportInfo[];
 /**
  * Infer domain from name, path, or imports
+ *
+ * @param name - The identifier name to analyze.
+ * @param filePath - Optional file path for structure context.
+ * @param domainOptions - Optional overrides for domain keywords.
+ * @param fileImports - Optional list of imports for domain context.
+ * @returns The inferred domain name (string).
  */
 declare function inferDomain(name: string, filePath?: string, domainOptions?: {
     domainKeywords?: string[];
 }, fileImports?: string[]): string;
+/**
+ * Retrieve co-usage data for a specific file.
+ *
+ * @param file - The file path to look up.
+ * @param coUsageMatrix - The global co-usage matrix.
+ * @returns Formatted co-usage data object.
+ */
 declare function getCoUsageData(file: string, coUsageMatrix: Map<string, Map<string, number>>): CoUsageData;
+/**
+ * Identify candidates for module consolidation based on high co-usage or shared types.
+ *
+ * @param graph - The dependency graph.
+ * @param coUsageMatrix - Matrix of frequently paired files.
+ * @param typeGraph - Map of shared type references.
+ * @param minCoUsage - Minimum co-usage count threshold.
+ * @param minSharedTypes - Minimum shared types threshold.
+ * @returns Array of consolidation candidates sorted by strength.
+ */
 declare function findConsolidationCandidates(graph: DependencyGraph, coUsageMatrix: Map<string, Map<string, number>>, typeGraph: Map<string, Set<string>>, minCoUsage?: number, minSharedTypes?: number): any[];
 
 /**