@aiready/context-analyzer 0.21.10 → 0.21.11

package/src/heuristics.ts

@@ -1,10 +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;
@@ -12,22 +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;
@@ -37,7 +104,9 @@ 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);
@@ -48,6 +117,7 @@ export function isTypeDefinition(node: DependencyNode): boolean {
  *
  * @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;
@@ -62,24 +132,20 @@ export function isUtilityModule(node: DependencyNode): boolean {
  *
  * @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;
 }
@@ -89,17 +155,22 @@ export function isLambdaHandler(node: DependencyNode): boolean {
  *
  * @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)
   );
@@ -110,27 +181,21 @@ export function isServiceFile(node: DependencyNode): boolean {
  *
  * @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;
 }
@@ -140,27 +205,21 @@ export function isEmailTemplate(node: DependencyNode): boolean {
  *
  * @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;
 }
@@ -170,15 +229,20 @@ export function isParserFile(node: DependencyNode): boolean {
  *
  * @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;
 }
@@ -188,6 +252,7 @@ export function isSessionFile(node: DependencyNode): boolean {
  *
  * @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;
@@ -199,16 +264,12 @@ 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;
@@ -219,28 +280,36 @@ export function isNextJsPage(node: DependencyNode): boolean {
  *
  * @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,
+  };
+}

package/src/metrics.ts

@@ -32,7 +32,8 @@ export function calculateEnhancedCohesion(
   // 1. Domain-based cohesion using entropy
   const domains = exports.map((e) => e.inferredDomain || 'unknown');
   const domainCounts = new Map<string, number>();
-  for (const d of domains) domainCounts.set(d, (domainCounts.get(d) || 0) + 1);
+  for (const domain of domains)
+    domainCounts.set(domain, (domainCounts.get(domain) || 0) + 1);
 
   // IF ALL DOMAINS MATCH, RETURN 1.0 IMMEDIATELY (Legacy test compatibility)
   if (domainCounts.size === 1 && domains[0] !== 'unknown') {
@@ -40,11 +41,11 @@ export function calculateEnhancedCohesion(
   }
 
   const probs = Array.from(domainCounts.values()).map(
-    (c) => c / exports.length
+    (count) => count / exports.length
   );
   let domainEntropy = 0;
-  for (const p of probs) {
-    if (p > 0) domainEntropy -= p * Math.log2(p);
+  for (const prob of probs) {
+    if (prob > 0) domainEntropy -= prob * Math.log2(prob);
   }
 
   const maxEntropy = Math.log2(Math.max(2, domainCounts.size));
@@ -158,7 +159,7 @@ export function calculateFragmentation(
   if (files.length <= 1) return 0;
 
   const directories = new Set(
-    files.map((f) => f.split('/').slice(0, -1).join('/'))
+    files.map((file) => file.split('/').slice(0, -1).join('/'))
   );
   const uniqueDirs = directories.size;
 
@@ -189,15 +190,15 @@ export function calculatePathEntropy(files: string[]): number {
   if (!files || files.length === 0) return 0;
 
   const dirCounts = new Map<string, number>();
-  for (const f of files) {
-    const dir = f.split('/').slice(0, -1).join('/') || '.';
+  for (const file of files) {
+    const dir = file.split('/').slice(0, -1).join('/') || '.';
     dirCounts.set(dir, (dirCounts.get(dir) || 0) + 1);
   }
 
   const counts = Array.from(dirCounts.values());
   if (counts.length <= 1) return 0;
 
-  const total = counts.reduce((s, v) => s + v, 0);
+  const total = counts.reduce((sum, value) => sum + value, 0);
   let entropy = 0;
   for (const count of counts) {
     const prob = count / total;
@@ -217,11 +218,11 @@ export function calculatePathEntropy(files: string[]): number {
 export function calculateDirectoryDistance(files: string[]): number {
   if (!files || files.length <= 1) return 0;
 
-  const pathSegments = (p: string) => p.split('/').filter(Boolean);
-  const commonAncestorDepth = (a: string[], b: string[]) => {
-    const minLen = Math.min(a.length, b.length);
+  const pathSegments = (pathStr: string) => pathStr.split('/').filter(Boolean);
+  const commonAncestorDepth = (pathA: string[], pathB: string[]) => {
+    const minLen = Math.min(pathA.length, pathB.length);
     let i = 0;
-    while (i < minLen && a[i] === b[i]) i++;
+    while (i < minLen && pathA[i] === pathB[i]) i++;
     return i;
   };
 

package/src/orchestrator.ts

@@ -0,0 +1,136 @@
+import { scanFiles, readFileContent } from '@aiready/core';
+import type {
+  ContextAnalysisResult,
+  ContextAnalyzerOptions,
+  FileClassification,
+} from './types';
+import { calculateEnhancedCohesion } from './metrics';
+import { analyzeIssues } from './issue-analyzer';
+
+import {
+  buildDependencyGraph,
+  detectCircularDependencies,
+} from './graph-builder';
+import { detectModuleClusters } from './cluster-detector';
+import { mapNodeToResult } from './mapper';
+
+/**
+ * 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
+ */
+export function calculateCohesion(
+  exports: any[],
+  filePath?: string,
+  options?: any
+): number {
+  return calculateEnhancedCohesion(exports, filePath, options);
+}
+
+/**
+ * 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
+ */
+export async function analyzeContext(
+  options: ContextAnalyzerOptions
+): Promise<ContextAnalysisResult[]> {
+  const {
+    maxDepth = 5,
+    maxContextBudget = 25000,
+    minCohesion = 0.6,
+    maxFragmentation = 0.5,
+    includeNodeModules = false,
+    ...scanOptions
+  } = options;
+
+  const files = await scanFiles({
+    ...scanOptions,
+    exclude:
+      includeNodeModules && scanOptions.exclude
+        ? scanOptions.exclude.filter(
+            (pattern) => pattern !== '**/node_modules/**'
+          )
+        : scanOptions.exclude,
+  });
+
+  const pythonFiles = files.filter((f) => f.toLowerCase().endsWith('.py'));
+  const fileContents = await Promise.all(
+    files.map(async (file) => ({
+      file,
+      content: await readFileContent(file),
+    }))
+  );
+
+  const graph = buildDependencyGraph(
+    fileContents.filter((f) => !f.file.toLowerCase().endsWith('.py'))
+  );
+
+  let pythonResults: ContextAnalysisResult[] = [];
+  if (pythonFiles.length > 0) {
+    const { analyzePythonContext } = await import('./analyzers/python-context');
+    const pythonMetrics = await analyzePythonContext(
+      pythonFiles,
+      scanOptions.rootDir || options.rootDir || '.'
+    );
+
+    pythonResults = pythonMetrics.map((metric) => {
+      const { severity, issues, recommendations, potentialSavings } =
+        analyzeIssues({
+          file: metric.file,
+          importDepth: metric.importDepth,
+          contextBudget: metric.contextBudget,
+          cohesionScore: metric.cohesion,
+          fragmentationScore: 0,
+          maxDepth,
+          maxContextBudget,
+          minCohesion,
+          maxFragmentation,
+          circularDeps: [],
+        });
+
+      return {
+        file: metric.file,
+        tokenCost: 0,
+        linesOfCode: 0,
+        importDepth: metric.importDepth,
+        dependencyCount: 0,
+        dependencyList: [],
+        circularDeps: [],
+        cohesionScore: metric.cohesion,
+        domains: [],
+        exportCount: 0,
+        contextBudget: metric.contextBudget,
+        fragmentationScore: 0,
+        relatedFiles: [],
+        fileClassification: 'unknown' as FileClassification,
+        severity,
+        issues,
+        recommendations,
+        potentialSavings,
+      };
+    });
+  }
+
+  const clusters = detectModuleClusters(graph);
+  const allCircularDeps = detectCircularDependencies(graph);
+
+  const results: ContextAnalysisResult[] = Array.from(graph.nodes.values()).map(
+    (node) =>
+      mapNodeToResult(node, graph, clusters, allCircularDeps, {
+        maxDepth,
+        maxContextBudget,
+        minCohesion,
+        maxFragmentation,
+      })
+  );
+
+  return [...results, ...pythonResults];
+}