@aiready/context-analyzer 0.21.6 → 0.21.8

package/dist/index.d.ts

@@ -1,36 +1,68 @@
-import { ToolProvider, Severity, ScanOptions, CostConfig, ToolScoringOutput } from '@aiready/core';
+import { ToolProvider, Severity, ScanOptions, FileContent, CostConfig, ToolScoringOutput } from '@aiready/core';
 
 /**
  * Context Analyzer Tool Provider
  */
 declare const ContextAnalyzerProvider: ToolProvider;
 
+/**
+ * Options for the Context Analyzer tool.
+ * Controls thresholds for import depth, context budget, and cohesion.
+ */
 interface ContextAnalyzerOptions extends ScanOptions {
+    /** Maximum acceptable import depth (default: 5) */
     maxDepth?: number;
+    /** Maximum acceptable token budget for a single context (default: 25000) */
     maxContextBudget?: number;
+    /** Minimum acceptable cohesion score between 0 and 1 (default: 0.6) */
     minCohesion?: number;
+    /** Maximum acceptable fragmentation score between 0 and 1 (default: 0.5) */
     maxFragmentation?: number;
+    /** Analysis focus area: fragmentation, cohesion, depth, or all (default: 'all') */
     focus?: 'fragmentation' | 'cohesion' | 'depth' | 'all';
+    /** Whether to include node_modules in the analysis (default: false) */
     includeNodeModules?: boolean;
 }
+/**
+ * The result of a context analysis for a single file or module.
+ * Includes metrics for tokens, dependencies, cohesion, and AI impact.
+ */
 interface ContextAnalysisResult {
+    /** The file path being analyzed */
     file: string;
+    /** Total number of tokens in this file */
     tokenCost: number;
+    /** Total lines of code in the file */
     linesOfCode: number;
+    /** Maximum depth of the import tree for this file */
     importDepth: number;
+    /** Total number of transitive dependencies */
     dependencyCount: number;
+    /** List of all files in the dependency tree */
     dependencyList: string[];
+    /** Detected circular dependency chains */
     circularDeps: string[][];
+    /** Cohesion score from 0 to 1 (1 is perfect cohesion) */
     cohesionScore: number;
+    /** Detected domain categories for the module */
     domains: string[];
+    /** Number of exported symbols */
     exportCount: number;
+    /** Total tokens required to understand this file and all its dependencies */
     contextBudget: number;
+    /** Fragmentation score from 0 to 1 (0 is well-grouped) */
     fragmentationScore: number;
+    /** List of files that should be loaded together for full context */
     relatedFiles: string[];
+    /** The semantic classification of the file (e.g. 'barrel-export', 'service-file') */
     fileClassification: FileClassification;
+    /** Overall severity of identified issues */
     severity: Severity | 'critical' | 'major' | 'minor' | 'info';
+    /** List of specific structural problems found */
     issues: string[];
+    /** Actionable suggestions for improving context readiness */
     recommendations: string[];
+    /** Estimated tokens that could be saved by following recommendations */
     potentialSavings: number;
 }
 /**
@@ -129,19 +161,28 @@ interface TypeDependency {
 }
 
 /**
- * Calculate cohesion score (how related are exports in a file)
- * Legacy wrapper for backward compatibility with exact test expectations
+ * Calculate cohesion score (how related are exports in a file).
+ * Legacy wrapper for backward compatibility with exact test expectations.
+ *
+ * @param exports - List of exported symbols
+ * @param filePath - Path to the file being analyzed
+ * @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
  */
+/**
+ * Performs deep context analysis of a project.
+ * Scans files, builds a dependency graph, calculates context budgets,
+ * and identifies structural issues like high fragmentation or depth.
+ *
+ * @param options - Analysis parameters including root directory and focus areas
+ * @returns Comprehensive analysis results with metrics and identified issues
+ */
 declare function analyzeContext(options: ContextAnalyzerOptions): Promise<ContextAnalysisResult[]>;
 
-interface FileContent {
-    file: string;
-    content: string;
-}
 /**
  * Auto-detect domain keywords from workspace folder structure
  */
@@ -172,6 +213,15 @@ 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
+ */
 declare function calculateEnhancedCohesion(exports: ExportInfo[], filePath?: string, options?: {
     coUsageMatrix?: Map<string, Map<string, number>>;
     weights?: {
@@ -227,76 +277,6 @@ declare const Classification: {
  * @returns The determined file classification
  */
 declare function classifyFile(node: DependencyNode, cohesionScore?: number, domains?: string[]): FileClassification;
-/**
- * Detect if a file is a barrel export (index.ts)
- *
- * @param node The dependency node to check
- * @returns True if the file appears to be a barrel export
- */
-declare function isBarrelExport(node: DependencyNode): boolean;
-/**
- * Detect if a file is primarily type definitions
- *
- * @param node The dependency node to check
- * @returns True if the file appears to be primarily types
- */
-declare function isTypeDefinition(node: DependencyNode): boolean;
-/**
- * Detect if a file is a utility module
- *
- * @param node The dependency node to check
- * @returns True if the file appears to be a utility module
- */
-declare function isUtilityModule(node: DependencyNode): boolean;
-/**
- * Detect if a file is a Lambda/API handler
- *
- * @param node The dependency node to check
- * @returns True if the file appears to be a Lambda handler
- */
-declare function isLambdaHandler(node: DependencyNode): boolean;
-/**
- * Detect if a file is a service file
- *
- * @param node The dependency node to check
- * @returns True if the file appears to be a service file
- */
-declare function isServiceFile(node: DependencyNode): boolean;
-/**
- * Detect if a file is an email template/layout
- *
- * @param node The dependency node to check
- * @returns True if the file appears to be an email template
- */
-declare function isEmailTemplate(node: DependencyNode): boolean;
-/**
- * Detect if a file is a parser/transformer
- *
- * @param node The dependency node to check
- * @returns True if the file appears to be a parser
- */
-declare function isParserFile(node: DependencyNode): boolean;
-/**
- * Detect if a file is a session/state management file
- *
- * @param node The dependency node to check
- * @returns True if the file appears to be a session/state file
- */
-declare function isSessionFile(node: DependencyNode): boolean;
-/**
- * Detect if a file is a configuration or schema file
- *
- * @param node The dependency node to check
- * @returns True if the file appears to be a config file
- */
-declare function isConfigFile(node: DependencyNode): boolean;
-/**
- * Detect if a file is a Next.js App Router page
- *
- * @param node The dependency node to check
- * @returns True if the file appears to be a Next.js page
- */
-declare function isNextJsPage(node: DependencyNode): boolean;
 /**
  * Adjust cohesion score based on file classification
  *
@@ -317,6 +297,10 @@ declare function adjustFragmentationForClassification(baseFragmentation: number,
 
 /**
  * Group files by domain to detect module clusters
+ * @param graph - The dependency graph to analyze
+ * @param options - Optional configuration options
+ * @param options.useLogScale - Whether to use logarithmic scaling for calculations
+ * @returns Array of module clusters
  */
 declare function detectModuleClusters(graph: DependencyGraph, options?: {
     useLogScale?: boolean;
@@ -355,6 +339,9 @@ declare function mapScoreToRating(score: number): string;
 /**
  * Generate smart defaults for context analysis based on repository size
  * Automatically tunes thresholds to target ~10 most serious issues
+ * @param directory - The root directory to analyze
+ * @param userOptions - Partial user-provided options to merge with defaults
+ * @returns Complete ContextAnalyzerOptions with smart defaults
  */
 declare function getSmartDefaults(directory: string, userOptions: Partial<ContextAnalyzerOptions>): Promise<ContextAnalyzerOptions>;
 
@@ -365,14 +352,21 @@ declare function generateSummary(results: ContextAnalysisResult[], options?: any
 
 /**
  * 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
  */
 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
  */
 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
  */
 declare function findSemanticClusters(coUsageMatrix: Map<string, Map<string, number>>, minCoUsage?: number): Map<string, string[]>;
 /**
@@ -408,4 +402,4 @@ declare function generateHTMLReport(summary: ReturnType<typeof generateSummary>,
  */
 declare function runInteractiveSetup(directory: string, current: any): Promise<any>;
 
-export { Classification, type CoUsageData, type ContextAnalysisResult, type ContextAnalyzerOptions, ContextAnalyzerProvider, type ContextSummary, type DependencyGraph, type DependencyNode, type DomainAssignment, type DomainSignals, type ExportInfo, type FileClassification, type ModuleCluster, type TypeDependency, adjustCohesionForClassification, adjustFragmentationForClassification, analyzeContext, buildCoUsageMatrix, buildDependencyGraph, buildTypeGraph, calculateCohesion, calculateContextBudget, calculateContextScore, calculateDirectoryDistance, calculateDomainConfidence, calculateEnhancedCohesion, calculateFragmentation, calculateImportDepth, calculatePathEntropy, calculateStructuralCohesionFromCoUsage, classifyFile, detectCircularDependencies, detectModuleClusters, displayConsoleReport, extractDomainKeywordsFromPaths, extractExports, findConsolidationCandidates, findSemanticClusters, generateHTMLReport, generateSummary, getClassificationRecommendations, getCoUsageData, getGeneralRecommendations, getSmartDefaults, getTransitiveDependencies, inferDomain, inferDomainFromSemantics, isBarrelExport, isConfigFile, isEmailTemplate, isLambdaHandler, isNextJsPage, isParserFile, isServiceFile, isSessionFile, isTypeDefinition, isUtilityModule, mapScoreToRating, runInteractiveSetup };
+export { Classification, type CoUsageData, type ContextAnalysisResult, type ContextAnalyzerOptions, ContextAnalyzerProvider, type ContextSummary, type DependencyGraph, type DependencyNode, type DomainAssignment, type DomainSignals, type ExportInfo, type FileClassification, type ModuleCluster, type TypeDependency, adjustCohesionForClassification, adjustFragmentationForClassification, analyzeContext, buildCoUsageMatrix, buildDependencyGraph, buildTypeGraph, calculateCohesion, calculateContextBudget, calculateContextScore, calculateDirectoryDistance, calculateDomainConfidence, calculateEnhancedCohesion, calculateFragmentation, calculateImportDepth, calculatePathEntropy, calculateStructuralCohesionFromCoUsage, classifyFile, detectCircularDependencies, detectModuleClusters, displayConsoleReport, extractDomainKeywordsFromPaths, extractExports, findConsolidationCandidates, findSemanticClusters, generateHTMLReport, generateSummary, getClassificationRecommendations, getCoUsageData, getGeneralRecommendations, getSmartDefaults, getTransitiveDependencies, inferDomain, inferDomainFromSemantics, mapScoreToRating, runInteractiveSetup };