@aiready/context-analyzer 0.21.8 → 0.21.10

package/dist/index.d.ts

@@ -184,43 +184,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 +255,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 +276,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;
 
@@ -308,10 +346,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 +378,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 +408,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[];
 
 /**

package/dist/index.js

@@ -1718,6 +1718,25 @@ function generateSummary(results, options = {}) {
 
 // src/scoring.ts
 var import_core8 = require("@aiready/core");
+var BUDGET_EXCELLENT_THRESHOLD = 8e3;
+var BUDGET_PENALTY_RATE = 200;
+var DEPTH_EXCELLENT_THRESHOLD = 8;
+var DEPTH_PENALTY_WEIGHT = 5;
+var FRAGMENTATION_EXCELLENT_THRESHOLD = 0.5;
+var FRAGMENTATION_PENALTY_WEIGHT = 100;
+var MAX_CRITICAL_PENALTY = 20;
+var CRITICAL_ISSUE_WEIGHT = 3;
+var MAX_MAJOR_PENALTY = 15;
+var MAJOR_ISSUE_WEIGHT = 1;
+var EXTREME_FILE_THRESHOLD = 15e3;
+var MAX_EXTREME_PENALTY = 20;
+var EXTREME_PENALTY_DIVISOR = 500;
+var FRAGMENTATION_BONUS_THRESHOLD = 0.2;
+var ORGANIZATION_BONUS = 5;
+var MAX_TOTAL_PENALTY = 30;
+var WEIGHT_BUDGET = 0.35;
+var WEIGHT_DEPTH = 0.25;
+var WEIGHT_FRAGMENTATION = 0.25;
 function calculateContextScore(summary, costConfig) {
   const {
     avgContextBudget,
@@ -1729,33 +1748,53 @@ function calculateContextScore(summary, costConfig) {
     majorIssues,
     totalFiles
   } = summary;
-  const budgetScore = avgContextBudget < 8e3 ? 100 : Math.max(0, 100 - (avgContextBudget - 8e3) / 200);
-  const depthScore = avgImportDepth < 8 ? 100 : Math.max(0, 100 - (avgImportDepth - 8) * 5);
-  const fragmentationScore = avgFragmentation < 0.5 ? 100 : Math.max(0, 100 - (avgFragmentation - 0.5) * 100);
-  const criticalPenalty = Math.min(20, criticalIssues * 3);
-  const majorPenalty = Math.min(15, majorIssues * 1);
-  const maxBudgetPenalty = maxContextBudget > 15e3 ? Math.min(20, (maxContextBudget - 15e3) / 500) : 0;
+  const budgetScore = avgContextBudget < BUDGET_EXCELLENT_THRESHOLD ? 100 : Math.max(
+    0,
+    100 - (avgContextBudget - BUDGET_EXCELLENT_THRESHOLD) / BUDGET_PENALTY_RATE
+  );
+  const depthScore = avgImportDepth < DEPTH_EXCELLENT_THRESHOLD ? 100 : Math.max(
+    0,
+    100 - (avgImportDepth - DEPTH_EXCELLENT_THRESHOLD) * DEPTH_PENALTY_WEIGHT
+  );
+  const fragmentationScore = avgFragmentation < FRAGMENTATION_EXCELLENT_THRESHOLD ? 100 : Math.max(
+    0,
+    100 - (avgFragmentation - FRAGMENTATION_EXCELLENT_THRESHOLD) * FRAGMENTATION_PENALTY_WEIGHT
+  );
+  const criticalPenalty = Math.min(
+    MAX_CRITICAL_PENALTY,
+    criticalIssues * CRITICAL_ISSUE_WEIGHT
+  );
+  const majorPenalty = Math.min(
+    MAX_MAJOR_PENALTY,
+    majorIssues * MAJOR_ISSUE_WEIGHT
+  );
+  const maxBudgetPenalty = maxContextBudget > EXTREME_FILE_THRESHOLD ? Math.min(
+    MAX_EXTREME_PENALTY,
+    (maxContextBudget - EXTREME_FILE_THRESHOLD) / EXTREME_PENALTY_DIVISOR
+  ) : 0;
   let bonus = 0;
-  if (criticalIssues === 0 && majorIssues === 0 && avgFragmentation < 0.2) {
-    bonus = 5;
+  if (criticalIssues === 0 && majorIssues === 0 && avgFragmentation < FRAGMENTATION_BONUS_THRESHOLD) {
+    bonus = ORGANIZATION_BONUS;
   }
-  const rawScore = budgetScore * 0.35 + depthScore * 0.25 + fragmentationScore * 0.25 + bonus;
-  const finalScore = rawScore - Math.min(30, criticalPenalty + majorPenalty) - maxBudgetPenalty;
+  const rawScore = budgetScore * WEIGHT_BUDGET + depthScore * WEIGHT_DEPTH + fragmentationScore * WEIGHT_FRAGMENTATION + bonus;
+  const finalScore = rawScore - Math.min(MAX_TOTAL_PENALTY, criticalPenalty + majorPenalty) - maxBudgetPenalty;
   const score = Math.max(0, Math.min(100, Math.round(finalScore)));
   const factors = [
     {
       name: "Context Budget",
-      impact: Math.round(budgetScore * 0.35 - 35),
-      description: `Avg ${Math.round(avgContextBudget)} tokens per file ${avgContextBudget < 8e3 ? "(excellent)" : avgContextBudget < 12e3 ? "(acceptable)" : "(high)"}`
+      impact: Math.round(budgetScore * WEIGHT_BUDGET - WEIGHT_BUDGET * 100),
+      description: `Avg ${Math.round(avgContextBudget)} tokens per file ${avgContextBudget < BUDGET_EXCELLENT_THRESHOLD ? "(excellent)" : avgContextBudget < 12e3 ? "(acceptable)" : "(high)"}`
     },
     {
       name: "Import Depth",
-      impact: Math.round(depthScore * 0.25 - 25),
-      description: `Avg ${avgImportDepth.toFixed(1)} levels ${avgImportDepth < 8 ? "(excellent)" : avgImportDepth < 12 ? "(acceptable)" : "(deep)"}`
+      impact: Math.round(depthScore * WEIGHT_DEPTH - WEIGHT_DEPTH * 100),
+      description: `Avg ${avgImportDepth.toFixed(1)} levels ${avgImportDepth < DEPTH_EXCELLENT_THRESHOLD ? "(excellent)" : avgImportDepth < 12 ? "(acceptable)" : "(deep)"}`
     },
     {
       name: "Fragmentation",
-      impact: Math.round(fragmentationScore * 0.25 - 25),
+      impact: Math.round(
+        fragmentationScore * WEIGHT_FRAGMENTATION - WEIGHT_FRAGMENTATION * 100
+      ),
       description: `${(avgFragmentation * 100).toFixed(0)}% fragmentation ${avgFragmentation < 0.3 ? "(well-organized)" : avgFragmentation < 0.5 ? "(moderate)" : "(high)"}`
     }
   ];

package/dist/index.mjs

@@ -53,6 +53,25 @@ import {
   ToolName,
   getRatingSlug
 } from "@aiready/core";
+var BUDGET_EXCELLENT_THRESHOLD = 8e3;
+var BUDGET_PENALTY_RATE = 200;
+var DEPTH_EXCELLENT_THRESHOLD = 8;
+var DEPTH_PENALTY_WEIGHT = 5;
+var FRAGMENTATION_EXCELLENT_THRESHOLD = 0.5;
+var FRAGMENTATION_PENALTY_WEIGHT = 100;
+var MAX_CRITICAL_PENALTY = 20;
+var CRITICAL_ISSUE_WEIGHT = 3;
+var MAX_MAJOR_PENALTY = 15;
+var MAJOR_ISSUE_WEIGHT = 1;
+var EXTREME_FILE_THRESHOLD = 15e3;
+var MAX_EXTREME_PENALTY = 20;
+var EXTREME_PENALTY_DIVISOR = 500;
+var FRAGMENTATION_BONUS_THRESHOLD = 0.2;
+var ORGANIZATION_BONUS = 5;
+var MAX_TOTAL_PENALTY = 30;
+var WEIGHT_BUDGET = 0.35;
+var WEIGHT_DEPTH = 0.25;
+var WEIGHT_FRAGMENTATION = 0.25;
 function calculateContextScore(summary, costConfig) {
   const {
     avgContextBudget,
@@ -64,33 +83,53 @@ function calculateContextScore(summary, costConfig) {
     majorIssues,
     totalFiles
   } = summary;
-  const budgetScore = avgContextBudget < 8e3 ? 100 : Math.max(0, 100 - (avgContextBudget - 8e3) / 200);
-  const depthScore = avgImportDepth < 8 ? 100 : Math.max(0, 100 - (avgImportDepth - 8) * 5);
-  const fragmentationScore = avgFragmentation < 0.5 ? 100 : Math.max(0, 100 - (avgFragmentation - 0.5) * 100);
-  const criticalPenalty = Math.min(20, criticalIssues * 3);
-  const majorPenalty = Math.min(15, majorIssues * 1);
-  const maxBudgetPenalty = maxContextBudget > 15e3 ? Math.min(20, (maxContextBudget - 15e3) / 500) : 0;
+  const budgetScore = avgContextBudget < BUDGET_EXCELLENT_THRESHOLD ? 100 : Math.max(
+    0,
+    100 - (avgContextBudget - BUDGET_EXCELLENT_THRESHOLD) / BUDGET_PENALTY_RATE
+  );
+  const depthScore = avgImportDepth < DEPTH_EXCELLENT_THRESHOLD ? 100 : Math.max(
+    0,
+    100 - (avgImportDepth - DEPTH_EXCELLENT_THRESHOLD) * DEPTH_PENALTY_WEIGHT
+  );
+  const fragmentationScore = avgFragmentation < FRAGMENTATION_EXCELLENT_THRESHOLD ? 100 : Math.max(
+    0,
+    100 - (avgFragmentation - FRAGMENTATION_EXCELLENT_THRESHOLD) * FRAGMENTATION_PENALTY_WEIGHT
+  );
+  const criticalPenalty = Math.min(
+    MAX_CRITICAL_PENALTY,
+    criticalIssues * CRITICAL_ISSUE_WEIGHT
+  );
+  const majorPenalty = Math.min(
+    MAX_MAJOR_PENALTY,
+    majorIssues * MAJOR_ISSUE_WEIGHT
+  );
+  const maxBudgetPenalty = maxContextBudget > EXTREME_FILE_THRESHOLD ? Math.min(
+    MAX_EXTREME_PENALTY,
+    (maxContextBudget - EXTREME_FILE_THRESHOLD) / EXTREME_PENALTY_DIVISOR
+  ) : 0;
   let bonus = 0;
-  if (criticalIssues === 0 && majorIssues === 0 && avgFragmentation < 0.2) {
-    bonus = 5;
+  if (criticalIssues === 0 && majorIssues === 0 && avgFragmentation < FRAGMENTATION_BONUS_THRESHOLD) {
+    bonus = ORGANIZATION_BONUS;
   }
-  const rawScore = budgetScore * 0.35 + depthScore * 0.25 + fragmentationScore * 0.25 + bonus;
-  const finalScore = rawScore - Math.min(30, criticalPenalty + majorPenalty) - maxBudgetPenalty;
+  const rawScore = budgetScore * WEIGHT_BUDGET + depthScore * WEIGHT_DEPTH + fragmentationScore * WEIGHT_FRAGMENTATION + bonus;
+  const finalScore = rawScore - Math.min(MAX_TOTAL_PENALTY, criticalPenalty + majorPenalty) - maxBudgetPenalty;
   const score = Math.max(0, Math.min(100, Math.round(finalScore)));
   const factors = [
     {
       name: "Context Budget",
-      impact: Math.round(budgetScore * 0.35 - 35),
-      description: `Avg ${Math.round(avgContextBudget)} tokens per file ${avgContextBudget < 8e3 ? "(excellent)" : avgContextBudget < 12e3 ? "(acceptable)" : "(high)"}`
+      impact: Math.round(budgetScore * WEIGHT_BUDGET - WEIGHT_BUDGET * 100),
+      description: `Avg ${Math.round(avgContextBudget)} tokens per file ${avgContextBudget < BUDGET_EXCELLENT_THRESHOLD ? "(excellent)" : avgContextBudget < 12e3 ? "(acceptable)" : "(high)"}`
     },
     {
       name: "Import Depth",
-      impact: Math.round(depthScore * 0.25 - 25),
-      description: `Avg ${avgImportDepth.toFixed(1)} levels ${avgImportDepth < 8 ? "(excellent)" : avgImportDepth < 12 ? "(acceptable)" : "(deep)"}`
+      impact: Math.round(depthScore * WEIGHT_DEPTH - WEIGHT_DEPTH * 100),
+      description: `Avg ${avgImportDepth.toFixed(1)} levels ${avgImportDepth < DEPTH_EXCELLENT_THRESHOLD ? "(excellent)" : avgImportDepth < 12 ? "(acceptable)" : "(deep)"}`
     },
     {
       name: "Fragmentation",
-      impact: Math.round(fragmentationScore * 0.25 - 25),
+      impact: Math.round(
+        fragmentationScore * WEIGHT_FRAGMENTATION - WEIGHT_FRAGMENTATION * 100
+      ),
       description: `${(avgFragmentation * 100).toFixed(0)}% fragmentation ${avgFragmentation < 0.3 ? "(well-organized)" : avgFragmentation < 0.5 ? "(moderate)" : "(high)"}`
     }
   ];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiready/context-analyzer",
-  "version": "0.21.8",
+  "version": "0.21.10",
   "description": "AI context window cost analysis - detect fragmented code, deep import chains, and expensive context budgets",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -49,7 +49,7 @@
     "commander": "^14.0.0",
     "chalk": "^5.3.0",
     "prompts": "^2.4.2",
-    "@aiready/core": "0.23.4"
+    "@aiready/core": "0.23.7"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",

package/src/ast-utils.ts

@@ -3,7 +3,14 @@ import type { ExportInfo } from './types';
 import { inferDomain, extractExports } from './semantic-analysis';
 
 /**
- * Extract exports using high-fidelity AST parsing across 5+ languages
+ * Extract exports using high-fidelity AST parsing across 5+ languages.
+ *
+ * @param content - File contents to parse.
+ * @param filePath - Path to the file for language detection and context.
+ * @param domainOptions - Optional configuration for domain detection.
+ * @param fileImports - Optional array of strings for resolving imports.
+ * @returns Array of high-fidelity export metadata.
+ * @lastUpdated 2026-03-18
  */
 export function extractExportsWithAST(
   content: string,
@@ -40,7 +47,10 @@ export function extractExportsWithAST(
 }
 
 /**
- * Check if a file is a test, mock, or fixture file
+ * Check if a file is a test, mock, or fixture file.
+ *
+ * @param filePath - The path to the file to check.
+ * @returns True if the file matches test/mock patterns.
  */
 export function isTestFile(filePath: string): boolean {
   const lower = filePath.toLowerCase();

package/src/cli-definition.ts

@@ -0,0 +1,61 @@
+import { Command } from 'commander';
+import { contextActionHandler } from './cli-action';
+
+/**
+ * Define the context analysis command structure.
+ * Separating this from the execution logic helps reduce context overhead.
+ *
+ * @param program - Commander program instance to attach the command to.
+ */
+export function defineContextCommand(program: Command): void {
+  program
+    .name('aiready-context')
+    .description('Analyze AI context window cost and code structure')
+    .version('0.1.0')
+    .addHelpText(
+      'after',
+      '\nCONFIGURATION:\n  Supports config files: aiready.json, aiready.config.json, .aiready.json, .aireadyrc.json, aiready.config.js, .aireadyrc.js\n  CLI options override config file settings'
+    )
+    .argument('<directory>', 'Directory to analyze')
+    .option('--max-depth <number>', 'Maximum acceptable import depth')
+    .option(
+      '--max-context <number>',
+      'Maximum acceptable context budget (tokens)'
+    )
+    .option(
+      '--min-cohesion <number>',
+      'Minimum acceptable cohesion score (0-1)'
+    )
+    .option(
+      '--max-fragmentation <number>',
+      'Maximum acceptable fragmentation (0-1)'
+    )
+    .option(
+      '--focus <type>',
+      'Analysis focus: fragmentation, cohesion, depth, all'
+    )
+    .option('--include-node-modules', 'Include node_modules in analysis')
+    .option(
+      '--include <patterns>',
+      'File patterns to include (comma-separated)'
+    )
+    .option(
+      '--exclude <patterns>',
+      'File patterns to exclude (comma-separated)'
+    )
+    .option(
+      '--max-results <number>',
+      'Maximum number of results to show in console output'
+    )
+    .option(
+      '-o, --output <format>',
+      'Output format: console, json, html',
+      'console'
+    )
+    .option('--output-file <path>', 'Output file path (for json/html)')
+    .option(
+      '--interactive',
+      'Run interactive setup to suggest excludes and focus areas'
+    )
+    .action(contextActionHandler);
+}

package/src/cli.ts

@@ -1,50 +1,8 @@
 #!/usr/bin/env node
 
 import { Command } from 'commander';
-import { contextActionHandler } from './cli-action';
+import { defineContextCommand } from './cli-definition';
 
 const program = new Command();
-
-program
-  .name('aiready-context')
-  .description('Analyze AI context window cost and code structure')
-  .version('0.1.0')
-  .addHelpText(
-    'after',
-    '\nCONFIGURATION:\n  Supports config files: aiready.json, aiready.config.json, .aiready.json, .aireadyrc.json, aiready.config.js, .aireadyrc.js\n  CLI options override config file settings'
-  )
-  .argument('<directory>', 'Directory to analyze')
-  .option('--max-depth <number>', 'Maximum acceptable import depth')
-  .option(
-    '--max-context <number>',
-    'Maximum acceptable context budget (tokens)'
-  )
-  .option('--min-cohesion <number>', 'Minimum acceptable cohesion score (0-1)')
-  .option(
-    '--max-fragmentation <number>',
-    'Maximum acceptable fragmentation (0-1)'
-  )
-  .option(
-    '--focus <type>',
-    'Analysis focus: fragmentation, cohesion, depth, all'
-  )
-  .option('--include-node-modules', 'Include node_modules in analysis')
-  .option('--include <patterns>', 'File patterns to include (comma-separated)')
-  .option('--exclude <patterns>', 'File patterns to exclude (comma-separated)')
-  .option(
-    '--max-results <number>',
-    'Maximum number of results to show in console output'
-  )
-  .option(
-    '-o, --output <format>',
-    'Output format: console, json, html',
-    'console'
-  )
-  .option('--output-file <path>', 'Output file path (for json/html)')
-  .option(
-    '--interactive',
-    'Run interactive setup to suggest excludes and focus areas'
-  )
-  .action(contextActionHandler);
-
+defineContextCommand(program);
 program.parse(process.argv);