@aiready/context-analyzer 0.21.9 → 0.21.10

package/src/graph-builder.ts

@@ -52,7 +52,10 @@ function resolveImport(
 }
 
 /**
- * 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.
  */
 export function extractDomainKeywordsFromPaths(files: FileContent[]): string[] {
   const folderNames = new Set<string>();
@@ -96,7 +99,11 @@ export 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.
  */
 export function buildDependencyGraph(
   files: FileContent[],
@@ -170,7 +177,13 @@ export function buildDependencyGraph(
 }
 
 /**
- * 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.
  */
 export function calculateImportDepth(
   file: string,
@@ -182,7 +195,12 @@ export function calculateImportDepth(
 }
 
 /**
- * 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.
  */
 export function getTransitiveDependencies(
   file: string,
@@ -193,7 +211,11 @@ export function getTransitiveDependencies(
 }
 
 /**
- * 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.
  */
 export function calculateContextBudget(
   file: string,
@@ -216,7 +238,10 @@ export function calculateContextBudget(
 }
 
 /**
- * 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).
  */
 export function detectCircularDependencies(graph: DependencyGraph): string[][] {
   return detectGraphCycles(graph.edges);

package/src/heuristics.ts

@@ -2,6 +2,9 @@ import { DependencyNode } from './types';
 
 /**
  * Detect if a file is a barrel export (index.ts)
+ *
+ * @param node - The dependency node to analyze.
+ * @returns True if the file matches barrel export patterns.
  */
 export function isBarrelExport(node: DependencyNode): boolean {
   const { file, exports } = node;
@@ -22,6 +25,9 @@ export function isBarrelExport(node: DependencyNode): boolean {
 
 /**
  * Detect if a file is primarily type definitions
+ *
+ * @param node - The dependency node to analyze.
+ * @returns True if the file contains primarily types or matches type paths.
  */
 export function isTypeDefinition(node: DependencyNode): boolean {
   const { file } = node;
@@ -38,7 +44,10 @@ export function isTypeDefinition(node: DependencyNode): boolean {
 }
 
 /**
- * Detect if a file is a utility module
+ * Detect if a file is a utility module.
+ *
+ * @param node - The dependency node to analyze.
+ * @returns True if the file path or name suggests a utility/helper role.
  */
 export function isUtilityModule(node: DependencyNode): boolean {
   const { file } = node;
@@ -49,7 +58,10 @@ export function isUtilityModule(node: DependencyNode): boolean {
 }
 
 /**
- * Detect if a file is a Lambda/API handler
+ * Detect if a file is a Lambda/API handler.
+ *
+ * @param node - The dependency node to analyze.
+ * @returns True if the file serves as a coordination point for requests/lambdas.
  */
 export function isLambdaHandler(node: DependencyNode): boolean {
   const { file, exports } = node;
@@ -73,7 +85,10 @@ export function isLambdaHandler(node: DependencyNode): boolean {
 }
 
 /**
- * Detect if a file is a service file
+ * Detect if a file is a service file.
+ *
+ * @param node - The dependency node to analyze.
+ * @returns True if the file orchestrates logic or matches service patterns.
  */
 export function isServiceFile(node: DependencyNode): boolean {
   const { file, exports } = node;
@@ -91,7 +106,10 @@ export function isServiceFile(node: DependencyNode): boolean {
 }
 
 /**
- * Detect if a file is an email template/layout
+ * Detect if a file is an email template/layout.
+ *
+ * @param node - The dependency node to analyze.
+ * @returns True if the file is used for rendering notifications or emails.
  */
 export function isEmailTemplate(node: DependencyNode): boolean {
   const { file, exports } = node;
@@ -118,7 +136,10 @@ export function isEmailTemplate(node: DependencyNode): boolean {
 }
 
 /**
- * Detect if a file is a parser/transformer
+ * Detect if a file is a parser/transformer.
+ *
+ * @param node - The dependency node to analyze.
+ * @returns True if the file handles data conversion or serialization.
  */
 export function isParserFile(node: DependencyNode): boolean {
   const { file, exports } = node;
@@ -145,7 +166,10 @@ export function isParserFile(node: DependencyNode): boolean {
 }
 
 /**
- * Detect if a file is a session/state management file
+ * Detect if a file is a session/state management file.
+ *
+ * @param node - The dependency node to analyze.
+ * @returns True if the file manages application state or sessions.
  */
 export function isSessionFile(node: DependencyNode): boolean {
   const { file, exports } = node;
@@ -160,7 +184,10 @@ export function isSessionFile(node: DependencyNode): boolean {
 }
 
 /**
- * Detect if a file is a Next.js App Router page
+ * Detect if a file is a Next.js App Router page.
+ *
+ * @param node - The dependency node to analyze.
+ * @returns True if the file is a Next.js page or metadata entry.
  */
 export function isNextJsPage(node: DependencyNode): boolean {
   const { file, exports } = node;
@@ -188,7 +215,10 @@ export function isNextJsPage(node: DependencyNode): boolean {
 }
 
 /**
- * Detect if a file is a configuration or schema file
+ * Detect if a file is a configuration or schema file.
+ *
+ * @param node - The dependency node to analyze.
+ * @returns True if the file matches configuration, setting, or schema patterns.
  */
 export function isConfigFile(node: DependencyNode): boolean {
   const { file, exports } = node;

package/src/metrics.ts

@@ -2,17 +2,15 @@ import { calculateImportSimilarity } from '@aiready/core';
 import type { ExportInfo } from './types';
 import { isTestFile } from './ast-utils';
 
-/**
- * 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.
  */
 export function calculateEnhancedCohesion(
   exports: ExportInfo[],
@@ -105,6 +103,10 @@ export function calculateEnhancedCohesion(
 
 /**
  * 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.
  */
 export function calculateStructuralCohesionFromCoUsage(
   file: string,
@@ -137,6 +139,11 @@ export function calculateStructuralCohesionFromCoUsage(
 
 /**
  * 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).
  */
 export function calculateFragmentation(
   files: string[],
@@ -173,7 +180,10 @@ export function calculateFragmentation(
 }
 
 /**
- * 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.
  */
 export function calculatePathEntropy(files: string[]): number {
   if (!files || files.length === 0) return 0;
@@ -199,7 +209,10 @@ export 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).
  */
 export function calculateDirectoryDistance(files: string[]): number {
   if (!files || files.length <= 1) return 0;

package/src/remediation.ts

@@ -2,6 +2,11 @@ import type { FileClassification } from './types';
 
 /**
  * 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.
  */
 export function getClassificationRecommendations(
   classification: FileClassification,
@@ -66,7 +71,11 @@ export function getClassificationRecommendations(
 }
 
 /**
- * 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.
  */
 export function getGeneralRecommendations(
   metrics: {

package/src/scoring.ts

@@ -10,7 +10,39 @@ import type { ToolScoringOutput } from '@aiready/core';
 import type { ContextSummary } from './types';
 
 /**
- * Calculate AI Readiness Score for context efficiency (0-100)
+ * Thresholds and weights for context efficiency scoring.
+ */
+const BUDGET_EXCELLENT_THRESHOLD = 8000;
+const BUDGET_PENALTY_RATE = 200;
+const DEPTH_EXCELLENT_THRESHOLD = 8;
+const DEPTH_PENALTY_WEIGHT = 5;
+const FRAGMENTATION_EXCELLENT_THRESHOLD = 0.5;
+const FRAGMENTATION_PENALTY_WEIGHT = 100;
+const MAX_CRITICAL_PENALTY = 20;
+const CRITICAL_ISSUE_WEIGHT = 3;
+const MAX_MAJOR_PENALTY = 15;
+const MAJOR_ISSUE_WEIGHT = 1;
+const EXTREME_FILE_THRESHOLD = 15000;
+const MAX_EXTREME_PENALTY = 20;
+const EXTREME_PENALTY_DIVISOR = 500;
+const FRAGMENTATION_BONUS_THRESHOLD = 0.2;
+const ORGANIZATION_BONUS = 5;
+const MAX_TOTAL_PENALTY = 30;
+
+const WEIGHT_BUDGET = 0.35;
+const WEIGHT_DEPTH = 0.25;
+const WEIGHT_FRAGMENTATION = 0.25;
+
+/**
+ * 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
  */
 export function calculateContextScore(
   summary: ContextSummary,
@@ -29,54 +61,90 @@ export function calculateContextScore(
 
   // More reasonable thresholds for modern codebases
   const budgetScore =
-    avgContextBudget < 8000
+    avgContextBudget < BUDGET_EXCELLENT_THRESHOLD
       ? 100
-      : Math.max(0, 100 - (avgContextBudget - 8000) / 200);
+      : Math.max(
+          0,
+          100 -
+            (avgContextBudget - BUDGET_EXCELLENT_THRESHOLD) /
+              BUDGET_PENALTY_RATE
+        );
 
   const depthScore =
-    avgImportDepth < 8 ? 100 : Math.max(0, 100 - (avgImportDepth - 8) * 5);
+    avgImportDepth < DEPTH_EXCELLENT_THRESHOLD
+      ? 100
+      : Math.max(
+          0,
+          100 -
+            (avgImportDepth - DEPTH_EXCELLENT_THRESHOLD) * DEPTH_PENALTY_WEIGHT
+        );
 
   const fragmentationScore =
-    avgFragmentation < 0.5
+    avgFragmentation < FRAGMENTATION_EXCELLENT_THRESHOLD
       ? 100
-      : Math.max(0, 100 - (avgFragmentation - 0.5) * 100);
+      : Math.max(
+          0,
+          100 -
+            (avgFragmentation - FRAGMENTATION_EXCELLENT_THRESHOLD) *
+              FRAGMENTATION_PENALTY_WEIGHT
+        );
 
   // Cap penalties to prevent score going to 0
-  const criticalPenalty = Math.min(20, criticalIssues * 3); // Max 20 points
-  const majorPenalty = Math.min(15, majorIssues * 1); // Max 15 points
+  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 > 15000
-      ? Math.min(20, (maxContextBudget - 15000) / 500)
+    maxContextBudget > EXTREME_FILE_THRESHOLD
+      ? Math.min(
+          MAX_EXTREME_PENALTY,
+          (maxContextBudget - EXTREME_FILE_THRESHOLD) / EXTREME_PENALTY_DIVISOR
+        )
       : 0;
 
   // Add bonus for well-organized codebases
   let bonus = 0;
-  if (criticalIssues === 0 && majorIssues === 0 && avgFragmentation < 0.2) {
-    bonus = 5; // Well-organized codebase bonus
+  if (
+    criticalIssues === 0 &&
+    majorIssues === 0 &&
+    avgFragmentation < FRAGMENTATION_BONUS_THRESHOLD
+  ) {
+    bonus = ORGANIZATION_BONUS;
   }
 
   const rawScore =
-    budgetScore * 0.35 + depthScore * 0.25 + fragmentationScore * 0.25 + bonus;
+    budgetScore * WEIGHT_BUDGET +
+    depthScore * WEIGHT_DEPTH +
+    fragmentationScore * WEIGHT_FRAGMENTATION +
+    bonus;
   const finalScore =
-    rawScore - Math.min(30, criticalPenalty + majorPenalty) - maxBudgetPenalty;
+    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 < 8000 ? '(excellent)' : avgContextBudget < 12000 ? '(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 < 12000 ? '(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)'}`,
     },
   ];
@@ -190,6 +258,12 @@ export function calculateContextScore(
   };
 }
 
+/**
+ * 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").
+ */
 export function mapScoreToRating(score: number): string {
   // Use core implementation to resolve duplication
   return getRatingSlug(score).replace('-', ' ');

package/src/semantic-analysis.ts

@@ -8,9 +8,10 @@ import type {
 import { singularize } from './utils/string-utils';
 
 /**
- * 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.
  */
 export function buildCoUsageMatrix(
   graph: DependencyGraph
@@ -40,9 +41,10 @@ export function buildCoUsageMatrix(
 }
 
 /**
- * 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.
  */
 export function buildTypeGraph(
   graph: DependencyGraph
@@ -64,10 +66,11 @@ export function buildTypeGraph(
 }
 
 /**
- * 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.
  */
 export function findSemanticClusters(
   coUsageMatrix: Map<string, Map<string, number>>,
@@ -96,7 +99,15 @@ export function findSemanticClusters(
 }
 
 /**
- * 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.
  */
 export function inferDomainFromSemantics(
   file: string,
@@ -173,6 +184,12 @@ export function inferDomainFromSemantics(
   return assignments;
 }
 
+/**
+ * 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).
+ */
 export function calculateDomainConfidence(signals: DomainSignals): number {
   const weights = {
     coUsage: 0.35,
@@ -192,6 +209,12 @@ export 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.
  */
 export function extractExports(
   content: string,
@@ -238,6 +261,12 @@ export function extractExports(
 
 /**
  * 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).
  */
 export function inferDomain(
   name: string,
@@ -320,6 +349,13 @@ export function inferDomain(
   return 'unknown';
 }
 
+/**
+ * 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.
+ */
 export function getCoUsageData(
   file: string,
   coUsageMatrix: Map<string, Map<string, number>>
@@ -331,13 +367,23 @@ export function getCoUsageData(
   };
 }
 
+/**
+ * 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.
+ */
 export function findConsolidationCandidates(
   graph: DependencyGraph,
   coUsageMatrix: Map<string, Map<string, number>>,
   typeGraph: Map<string, Set<string>>,
   minCoUsage: number = 5,
   minSharedTypes: number = 2
-) {
+): any[] {
   const candidates: any[] = [];
   for (const [fileA, coUsages] of coUsageMatrix) {
     const nodeA = graph.nodes.get(fileA);

package/src/summary.ts

@@ -8,6 +8,10 @@ import { calculatePathEntropy } from './metrics';
 
 /**
  * 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.
  */
 export function generateSummary(
   results: ContextAnalysisResult[],