@aiready/context-analyzer 0.21.9 → 0.21.11

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

@@ -1,7 +1,75 @@
 import { DependencyNode } from './types';
 
 /**
- * Detect if a file is a barrel export (index.ts)
+ * Heuristic patterns for file classification.
+ */
+const BARREL_EXPORT_MIN_EXPORTS = 5;
+const BARREL_EXPORT_TOKEN_LIMIT = 1000;
+
+const HANDLER_NAME_PATTERNS = [
+  'handler',
+  '.handler.',
+  '-handler.',
+  'lambda',
+  '.lambda.',
+  '-lambda.',
+];
+
+const SERVICE_NAME_PATTERNS = [
+  'service',
+  '.service.',
+  '-service.',
+  '_service.',
+];
+
+const EMAIL_NAME_PATTERNS = [
+  '-email-',
+  '.email.',
+  '_email_',
+  '-template',
+  '.template.',
+  '_template',
+  '-mail.',
+  '.mail.',
+];
+
+const PARSER_NAME_PATTERNS = [
+  'parser',
+  '.parser.',
+  '-parser.',
+  '_parser.',
+  'transform',
+  'converter',
+  'mapper',
+  'serializer',
+];
+
+const SESSION_NAME_PATTERNS = ['session', 'state', 'context', 'store'];
+
+const NEXTJS_METADATA_EXPORTS = [
+  'metadata',
+  'generatemetadata',
+  'faqjsonld',
+  'jsonld',
+  'icon',
+];
+
+const CONFIG_NAME_PATTERNS = [
+  '.config.',
+  'tsconfig',
+  'jest.config',
+  'package.json',
+  'aiready.json',
+  'next.config',
+  'sst.config',
+];
+
+/**
+ * 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.
+ * @lastUpdated 2026-03-18
  */
 export function isBarrelExport(node: DependencyNode): boolean {
   const { file, exports } = node;
@@ -9,19 +77,24 @@ export function isBarrelExport(node: DependencyNode): boolean {
 
   const isIndexFile = fileName === 'index.ts' || fileName === 'index.js';
   const isSmallAndManyExports =
-    node.tokenCost < 1000 && (exports || []).length > 5;
+    node.tokenCost < BARREL_EXPORT_TOKEN_LIMIT &&
+    (exports || []).length > BARREL_EXPORT_MIN_EXPORTS;
 
   const isReexportPattern =
-    (exports || []).length >= 5 &&
-    (exports || []).every((e) =>
-      ['const', 'function', 'type', 'interface'].includes(e.type)
+    (exports || []).length >= BARREL_EXPORT_MIN_EXPORTS &&
+    (exports || []).every((exp: any) =>
+      ['const', 'function', 'type', 'interface'].includes(exp.type)
     );
 
   return !!isIndexFile || !!isSmallAndManyExports || !!isReexportPattern;
 }
 
 /**
- * Detect if a file is primarily type definitions
+ * 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.
+ * @lastUpdated 2026-03-18
  */
 export function isTypeDefinition(node: DependencyNode): boolean {
   const { file } = node;
@@ -31,14 +104,20 @@ export function isTypeDefinition(node: DependencyNode): boolean {
   const hasExports = nodeExports.length > 0;
   const areAllTypes =
     hasExports &&
-    nodeExports.every((e) => e.type === 'type' || e.type === 'interface');
+    nodeExports.every(
+      (exp: any) => exp.type === 'type' || exp.type === 'interface'
+    );
 
   const isTypePath = /\/(types|interfaces|models)\//i.test(file);
   return !!areAllTypes || (isTypePath && hasExports);
 }
 
 /**
- * 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.
+ * @lastUpdated 2026-03-18
  */
 export function isUtilityModule(node: DependencyNode): boolean {
   const { file } = node;
@@ -49,118 +128,131 @@ 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.
+ * @lastUpdated 2026-03-18
  */
 export function isLambdaHandler(node: DependencyNode): boolean {
   const { file, exports } = node;
   const fileName = file.split('/').pop()?.toLowerCase() || '';
-  const handlerPatterns = [
-    'handler',
-    '.handler.',
-    '-handler.',
-    'lambda',
-    '.lambda.',
-    '-lambda.',
-  ];
-  const isHandlerName = handlerPatterns.some((p) => fileName.includes(p));
+
+  const isHandlerName = HANDLER_NAME_PATTERNS.some((pattern: string) =>
+    fileName.includes(pattern)
+  );
   const isHandlerPath = /\/(handlers|lambdas|lambda|functions)\//i.test(file);
   const hasHandlerExport = (exports || []).some(
-    (e) =>
-      ['handler', 'main', 'lambdahandler'].includes(e.name.toLowerCase()) ||
-      e.name.toLowerCase().endsWith('handler')
+    (exp: any) =>
+      ['handler', 'main', 'lambdahandler'].includes(exp.name.toLowerCase()) ||
+      exp.name.toLowerCase().endsWith('handler')
   );
   return isHandlerName || isHandlerPath || hasHandlerExport;
 }
 
 /**
- * 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.
+ * @lastUpdated 2026-03-18
  */
 export function isServiceFile(node: DependencyNode): boolean {
   const { file, exports } = node;
   const fileName = file.split('/').pop()?.toLowerCase() || '';
-  const servicePatterns = ['service', '.service.', '-service.', '_service.'];
-  const isServiceName = servicePatterns.some((p) => fileName.includes(p));
+
+  const isServiceName = SERVICE_NAME_PATTERNS.some((pattern: string) =>
+    fileName.includes(pattern)
+  );
   const isServicePath = file.toLowerCase().includes('/services/');
-  const hasServiceNamedExport = (exports || []).some((e) =>
-    e.name.toLowerCase().includes('service')
+  const hasServiceNamedExport = (exports || []).some((exp: any) =>
+    exp.name.toLowerCase().includes('service')
+  );
+  const hasClassExport = (exports || []).some(
+    (exp: any) => exp.type === 'class'
   );
-  const hasClassExport = (exports || []).some((e) => e.type === 'class');
   return (
     isServiceName || isServicePath || (hasServiceNamedExport && hasClassExport)
   );
 }
 
 /**
- * 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.
+ * @lastUpdated 2026-03-18
  */
 export function isEmailTemplate(node: DependencyNode): boolean {
   const { file, exports } = node;
   const fileName = file.split('/').pop()?.toLowerCase() || '';
-  const emailPatterns = [
-    '-email-',
-    '.email.',
-    '_email_',
-    '-template',
-    '.template.',
-    '_template',
-    '-mail.',
-    '.mail.',
-  ];
-  const isEmailName = emailPatterns.some((p) => fileName.includes(p));
+
+  const isEmailName = EMAIL_NAME_PATTERNS.some((pattern: string) =>
+    fileName.includes(pattern)
+  );
   const isEmailPath = /\/(emails|mail|notifications)\//i.test(file);
   const hasTemplateFunction = (exports || []).some(
-    (e) =>
-      e.type === 'function' &&
-      (e.name.toLowerCase().startsWith('render') ||
-        e.name.toLowerCase().startsWith('generate'))
+    (exp: any) =>
+      exp.type === 'function' &&
+      (exp.name.toLowerCase().startsWith('render') ||
+        exp.name.toLowerCase().startsWith('generate'))
   );
   return isEmailPath || isEmailName || hasTemplateFunction;
 }
 
 /**
- * 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.
+ * @lastUpdated 2026-03-18
  */
 export function isParserFile(node: DependencyNode): boolean {
   const { file, exports } = node;
   const fileName = file.split('/').pop()?.toLowerCase() || '';
-  const parserPatterns = [
-    'parser',
-    '.parser.',
-    '-parser.',
-    '_parser.',
-    'transform',
-    'converter',
-    'mapper',
-    'serializer',
-  ];
-  const isParserName = parserPatterns.some((p) => fileName.includes(p));
+
+  const isParserName = PARSER_NAME_PATTERNS.some((pattern: string) =>
+    fileName.includes(pattern)
+  );
   const isParserPath = /\/(parsers|transformers)\//i.test(file);
   const hasParseFunction = (exports || []).some(
-    (e) =>
-      e.type === 'function' &&
-      (e.name.toLowerCase().startsWith('parse') ||
-        e.name.toLowerCase().startsWith('transform'))
+    (exp: any) =>
+      exp.type === 'function' &&
+      (exp.name.toLowerCase().startsWith('parse') ||
+        exp.name.toLowerCase().startsWith('transform'))
   );
   return isParserName || isParserPath || hasParseFunction;
 }
 
 /**
- * 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.
+ * @lastUpdated 2026-03-18
  */
 export function isSessionFile(node: DependencyNode): boolean {
   const { file, exports } = node;
   const fileName = file.split('/').pop()?.toLowerCase() || '';
-  const sessionPatterns = ['session', 'state', 'context', 'store'];
-  const isSessionName = sessionPatterns.some((p) => fileName.includes(p));
+
+  const isSessionName = SESSION_NAME_PATTERNS.some((pattern: string) =>
+    fileName.includes(pattern)
+  );
   const isSessionPath = /\/(sessions|state)\//i.test(file);
-  const hasSessionExport = (exports || []).some((e) =>
-    ['session', 'state', 'store'].some((p) => e.name.toLowerCase().includes(p))
+  const hasSessionExport = (exports || []).some((exp: any) =>
+    ['session', 'state', 'store'].some((pattern: string) =>
+      exp.name.toLowerCase().includes(pattern)
+    )
   );
   return isSessionName || isSessionPath || hasSessionExport;
 }
 
 /**
- * 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.
+ * @lastUpdated 2026-03-18
  */
 export function isNextJsPage(node: DependencyNode): boolean {
   const { file, exports } = node;
@@ -172,45 +264,52 @@ export function isNextJsPage(node: DependencyNode): boolean {
   if (!isInAppDir || (fileName !== 'page.tsx' && fileName !== 'page.ts'))
     return false;
 
-  const hasDefaultExport = (exports || []).some((e) => e.type === 'default');
-  const nextJsExports = [
-    'metadata',
-    'generatemetadata',
-    'faqjsonld',
-    'jsonld',
-    'icon',
-  ];
-  const hasNextJsExport = (exports || []).some((e) =>
-    nextJsExports.includes(e.name.toLowerCase())
+  const hasDefaultExport = (exports || []).some(
+    (exp: any) => exp.type === 'default'
+  );
+
+  const hasNextJsExport = (exports || []).some((exp: any) =>
+    NEXTJS_METADATA_EXPORTS.includes(exp.name.toLowerCase())
   );
 
   return hasDefaultExport || hasNextJsExport;
 }
 
 /**
- * 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.
+ * @lastUpdated 2026-03-18
  */
 export function isConfigFile(node: DependencyNode): boolean {
   const { file, exports } = node;
   const lowerPath = file.toLowerCase();
   const fileName = file.split('/').pop()?.toLowerCase() || '';
 
-  const configPatterns = [
-    '.config.',
-    'tsconfig',
-    'jest.config',
-    'package.json',
-    'aiready.json',
-    'next.config',
-    'sst.config',
-  ];
-  const isConfigName = configPatterns.some((p) => fileName.includes(p));
+  const isConfigName = CONFIG_NAME_PATTERNS.some((pattern: string) =>
+    fileName.includes(pattern)
+  );
   const isConfigPath = /\/(config|settings|schemas)\//i.test(lowerPath);
-  const hasSchemaExport = (exports || []).some((e) =>
-    ['schema', 'config', 'setting'].some((p) =>
-      e.name.toLowerCase().includes(p)
+  const hasSchemaExport = (exports || []).some((exp: any) =>
+    ['schema', 'config', 'setting'].some((pattern: string) =>
+      exp.name.toLowerCase().includes(pattern)
     )
   );
 
   return isConfigName || isConfigPath || hasSchemaExport;
 }
+
+/**
+ * Detect if a file is part of a hub-and-spoke monorepo architecture.
+ *
+ * Many files spread across multiple packages (spokes) is intentional in
+ * AIReady and shouldn't be penalized as heavily for fragmentation.
+ *
+ * @param node - The dependency node to analyze.
+ * @returns True if the file path suggests it belongs to a spoke package.
+ */
+export function isHubAndSpokeFile(node: DependencyNode): boolean {
+  const { file } = node;
+  return /\/packages\/[a-zA-Z0-9-]+\/src\//.test(file);
+}

package/src/mapper.ts

@@ -0,0 +1,118 @@
+import type {
+  ContextAnalysisResult,
+  DependencyGraph,
+  DependencyNode,
+  ModuleCluster,
+} from './types';
+import { calculateEnhancedCohesion } from './metrics';
+import { analyzeIssues } from './issue-analyzer';
+import {
+  calculateImportDepth,
+  getTransitiveDependencies,
+  calculateContextBudget,
+} from './graph-builder';
+import {
+  classifyFile,
+  adjustCohesionForClassification,
+  adjustFragmentationForClassification,
+} from './classifier';
+import { getClassificationRecommendations } from './remediation';
+
+export interface MappingOptions {
+  maxDepth: number;
+  maxContextBudget: number;
+  minCohesion: number;
+  maxFragmentation: number;
+}
+
+/**
+ * Maps a single dependency node to a comprehensive ContextAnalysisResult.
+ */
+export function mapNodeToResult(
+  node: DependencyNode,
+  graph: DependencyGraph,
+  clusters: ModuleCluster[],
+  allCircularDeps: string[][],
+  options: MappingOptions
+): ContextAnalysisResult {
+  const file = node.file;
+  const tokenCost = node.tokenCost;
+  const importDepth = calculateImportDepth(file, graph);
+  const transitiveDeps = getTransitiveDependencies(file, graph);
+  const contextBudget = calculateContextBudget(file, graph);
+  const circularDeps = allCircularDeps.filter((cycle) => cycle.includes(file));
+
+  // Find cluster for this file
+  const cluster = clusters.find((c) => c.files.includes(file));
+  const rawFragmentationScore = cluster ? cluster.fragmentationScore : 0;
+
+  // Cohesion
+  const rawCohesionScore = calculateEnhancedCohesion(
+    node.exports,
+    file,
+    options as any
+  );
+
+  // Initial classification
+  const fileClassification = classifyFile(node, rawCohesionScore);
+
+  // Adjust scores based on classification
+  const cohesionScore = adjustCohesionForClassification(
+    rawCohesionScore,
+    fileClassification
+  );
+  const fragmentationScore = adjustFragmentationForClassification(
+    rawFragmentationScore,
+    fileClassification
+  );
+
+  const { severity, issues, recommendations, potentialSavings } = analyzeIssues(
+    {
+      file,
+      importDepth,
+      contextBudget,
+      cohesionScore,
+      fragmentationScore,
+      maxDepth: options.maxDepth,
+      maxContextBudget: options.maxContextBudget,
+      minCohesion: options.minCohesion,
+      maxFragmentation: options.maxFragmentation,
+      circularDeps,
+    }
+  );
+
+  // Add classification-specific recommendations
+  const classRecs = getClassificationRecommendations(
+    fileClassification,
+    file,
+    issues
+  );
+  const allRecommendations = Array.from(
+    new Set([...recommendations, ...classRecs])
+  );
+
+  return {
+    file,
+    tokenCost,
+    linesOfCode: node.linesOfCode,
+    importDepth,
+    dependencyCount: transitiveDeps.length,
+    dependencyList: transitiveDeps,
+    circularDeps,
+    cohesionScore,
+    domains: Array.from(
+      new Set(
+        node.exports.flatMap((e) => e.domains?.map((d) => d.domain) || [])
+      )
+    ),
+    exportCount: node.exports.length,
+    contextBudget,
+    fragmentationScore,
+    relatedFiles: cluster ? cluster.files : [],
+    fileClassification,
+    severity,
+    issues,
+    recommendations: allRecommendations,
+    potentialSavings,
+  };
+}