@aiready/context-analyzer 0.21.5 → 0.21.7

package/src/cluster-detector.ts

@@ -3,6 +3,10 @@ import { calculateFragmentation, calculateEnhancedCohesion } from './metrics';
 
 /**
  * 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
  */
 export function detectModuleClusters(
   graph: DependencyGraph,
@@ -20,6 +24,29 @@ export function detectModuleClusters(
 
   const clusters: ModuleCluster[] = [];
 
+  const generateSuggestedStructure = (
+    files: string[],
+    tokens: number,
+    fragmentation: number
+  ) => {
+    const targetFiles = Math.max(1, Math.ceil(tokens / 10000));
+    const plan: string[] = [];
+
+    if (fragmentation > 0.5) {
+      plan.push(
+        `Consolidate ${files.length} files scattered across multiple directories into ${targetFiles} core module(s)`
+      );
+    }
+
+    if (tokens > 20000) {
+      plan.push(
+        `Domain logic is very large (${Math.round(tokens / 1000)}k tokens). Ensure clear sub-domain boundaries.`
+      );
+    }
+
+    return { targetFiles, consolidationPlan: plan };
+  };
+
   for (const [domain, files] of domainMap.entries()) {
     if (files.length < 2 || domain === 'unknown') continue;
 
@@ -35,7 +62,7 @@ export function detectModuleClusters(
         (f) => new Set(graph.nodes.get(f)?.imports || [])
       );
       let intersection = new Set(allImportSets[0]);
-      let union = new Set(allImportSets[0]);
+      const union = new Set(allImportSets[0]);
 
       for (let i = 1; i < allImportSets.length; i++) {
         const nextSet = allImportSets[i];

package/src/defaults.ts

@@ -4,6 +4,9 @@ import type { ContextAnalyzerOptions } from './types';
 /**
  * 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
  */
 export async function getSmartDefaults(
   directory: string,

package/src/graph-builder.ts

@@ -1,4 +1,10 @@
-import { estimateTokens, parseFileExports } from '@aiready/core';
+import { estimateTokens, parseFileExports, FileContent } from '@aiready/core';
+import { singularize } from './utils/string-utils';
+import {
+  calculateImportDepthFromEdges,
+  detectGraphCycles,
+  getTransitiveDependenciesFromEdges,
+} from './utils/dependency-graph-utils';
 import type { DependencyGraph, DependencyNode } from './types';
 import {
   buildCoUsageMatrix,
@@ -8,11 +14,6 @@ import {
 import { extractExportsWithAST } from './ast-utils';
 import { join, dirname, normalize } from 'path';
 
-interface FileContent {
-  file: string;
-  content: string;
-}
-
 /**
  * Resolve an import source to its absolute path considering the importing file's location
  */
@@ -94,25 +95,6 @@ export function extractDomainKeywordsFromPaths(files: FileContent[]): string[] {
   return Array.from(folderNames);
 }
 
-/**
- * Simple singularization for common English plurals
- */
-function singularize(word: string): string {
-  const irregulars: Record<string, string> = {
-    people: 'person',
-    children: 'child',
-    men: 'man',
-    women: 'woman',
-  };
-
-  if (irregulars[word]) return irregulars[word];
-  if (word.endsWith('ies')) return word.slice(0, -3) + 'y';
-  if (word.endsWith('ses')) return word.slice(0, -2);
-  if (word.endsWith('s') && word.length > 3) return word.slice(0, -1);
-
-  return word;
-}
-
 /**
  * Build a dependency graph from file contents
  */
@@ -196,23 +178,7 @@ export function calculateImportDepth(
   visited = new Set<string>(),
   depth = 0
 ): number {
-  if (visited.has(file)) return depth;
-
-  const dependencies = graph.edges.get(file);
-  if (!dependencies || dependencies.size === 0) return depth;
-
-  visited.add(file);
-  let maxDepth = depth;
-
-  for (const dep of dependencies) {
-    maxDepth = Math.max(
-      maxDepth,
-      calculateImportDepth(dep, graph, visited, depth + 1)
-    );
-  }
-
-  visited.delete(file);
-  return maxDepth;
+  return calculateImportDepthFromEdges(file, graph.edges, visited, depth);
 }
 
 /**
@@ -223,19 +189,7 @@ export function getTransitiveDependencies(
   graph: DependencyGraph,
   visited = new Set<string>()
 ): string[] {
-  if (visited.has(file)) return [];
-
-  visited.add(file);
-  const dependencies = graph.edges.get(file);
-  if (!dependencies || dependencies.size === 0) return [];
-
-  const allDeps: string[] = [];
-  for (const dep of dependencies) {
-    allDeps.push(dep);
-    allDeps.push(...getTransitiveDependencies(dep, graph, visited));
-  }
-
-  return [...new Set(allDeps)];
+  return getTransitiveDependenciesFromEdges(file, graph.edges, visited);
 }
 
 /**
@@ -265,40 +219,5 @@ export function calculateContextBudget(
  * Detect circular dependencies
  */
 export function detectCircularDependencies(graph: DependencyGraph): string[][] {
-  const cycles: string[][] = [];
-  const visited = new Set<string>();
-  const recursionStack = new Set<string>();
-
-  function dfs(file: string, path: string[]): void {
-    if (recursionStack.has(file)) {
-      const cycleStart = path.indexOf(file);
-      if (cycleStart !== -1) {
-        cycles.push([...path.slice(cycleStart), file]);
-      }
-      return;
-    }
-
-    if (visited.has(file)) return;
-
-    visited.add(file);
-    recursionStack.add(file);
-    path.push(file);
-
-    const dependencies = graph.edges.get(file);
-    if (dependencies) {
-      for (const dep of dependencies) {
-        dfs(dep, [...path]);
-      }
-    }
-
-    recursionStack.delete(file);
-  }
-
-  for (const file of graph.nodes.keys()) {
-    if (!visited.has(file)) {
-      dfs(file, []);
-    }
-  }
-
-  return cycles;
+  return detectGraphCycles(graph.edges);
 }

package/src/heuristics.ts

@@ -0,0 +1,216 @@
+import { DependencyNode } from './types';
+
+/**
+ * Detect if a file is a barrel export (index.ts)
+ */
+export function isBarrelExport(node: DependencyNode): boolean {
+  const { file, exports } = node;
+  const fileName = file.split('/').pop()?.toLowerCase();
+
+  const isIndexFile = fileName === 'index.ts' || fileName === 'index.js';
+  const isSmallAndManyExports =
+    node.tokenCost < 1000 && (exports || []).length > 5;
+
+  const isReexportPattern =
+    (exports || []).length >= 5 &&
+    (exports || []).every((e) =>
+      ['const', 'function', 'type', 'interface'].includes(e.type)
+    );
+
+  return !!isIndexFile || !!isSmallAndManyExports || !!isReexportPattern;
+}
+
+/**
+ * Detect if a file is primarily type definitions
+ */
+export function isTypeDefinition(node: DependencyNode): boolean {
+  const { file } = node;
+  if (file.endsWith('.d.ts')) return true;
+
+  const nodeExports = node.exports || [];
+  const hasExports = nodeExports.length > 0;
+  const areAllTypes =
+    hasExports &&
+    nodeExports.every((e) => e.type === 'type' || e.type === 'interface');
+
+  const isTypePath = /\/(types|interfaces|models)\//i.test(file);
+  return !!areAllTypes || (isTypePath && hasExports);
+}
+
+/**
+ * Detect if a file is a utility module
+ */
+export function isUtilityModule(node: DependencyNode): boolean {
+  const { file } = node;
+  const isUtilPath = /\/(utils|helpers|util|helper)\//i.test(file);
+  const fileName = file.split('/').pop()?.toLowerCase() || '';
+  const isUtilName = /(utils\.|helpers\.|util\.|helper\.)/i.test(fileName);
+  return isUtilPath || isUtilName;
+}
+
+/**
+ * Detect if a file is a Lambda/API handler
+ */
+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 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')
+  );
+  return isHandlerName || isHandlerPath || hasHandlerExport;
+}
+
+/**
+ * Detect if a file is a service file
+ */
+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 isServicePath = file.toLowerCase().includes('/services/');
+  const hasServiceNamedExport = (exports || []).some((e) =>
+    e.name.toLowerCase().includes('service')
+  );
+  const hasClassExport = (exports || []).some((e) => e.type === 'class');
+  return (
+    isServiceName || isServicePath || (hasServiceNamedExport && hasClassExport)
+  );
+}
+
+/**
+ * Detect if a file is an email template/layout
+ */
+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 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'))
+  );
+  return isEmailPath || isEmailName || hasTemplateFunction;
+}
+
+/**
+ * Detect if a file is a parser/transformer
+ */
+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 isParserPath = /\/(parsers|transformers)\//i.test(file);
+  const hasParseFunction = (exports || []).some(
+    (e) =>
+      e.type === 'function' &&
+      (e.name.toLowerCase().startsWith('parse') ||
+        e.name.toLowerCase().startsWith('transform'))
+  );
+  return isParserName || isParserPath || hasParseFunction;
+}
+
+/**
+ * Detect if a file is a session/state management file
+ */
+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 isSessionPath = /\/(sessions|state)\//i.test(file);
+  const hasSessionExport = (exports || []).some((e) =>
+    ['session', 'state', 'store'].some((p) => e.name.toLowerCase().includes(p))
+  );
+  return isSessionName || isSessionPath || hasSessionExport;
+}
+
+/**
+ * Detect if a file is a Next.js App Router page
+ */
+export function isNextJsPage(node: DependencyNode): boolean {
+  const { file, exports } = node;
+  const lowerPath = file.toLowerCase();
+  const fileName = file.split('/').pop()?.toLowerCase() || '';
+
+  const isInAppDir =
+    lowerPath.includes('/app/') || lowerPath.startsWith('app/');
+  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())
+  );
+
+  return hasDefaultExport || hasNextJsExport;
+}
+
+/**
+ * Detect if a file is a configuration or schema file
+ */
+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 isConfigPath = /\/(config|settings|schemas)\//i.test(lowerPath);
+  const hasSchemaExport = (exports || []).some((e) =>
+    ['schema', 'config', 'setting'].some((p) =>
+      e.name.toLowerCase().includes(p)
+    )
+  );
+
+  return isConfigName || isConfigPath || hasSchemaExport;
+}

package/src/index.ts

@@ -5,9 +5,15 @@ import { ContextAnalyzerProvider } from './provider';
 ToolRegistry.register(ContextAnalyzerProvider);
 
 export * from './analyzer';
+export * from './graph-builder';
+export * from './metrics';
+export * from './classifier';
+export * from './cluster-detector';
+export * from './remediation';
 export * from './scoring';
 export * from './defaults';
 export * from './summary';
 export * from './types';
 export * from './semantic-analysis';
 export { ContextAnalyzerProvider };
+export * from './utils/output-formatter';

package/src/issue-analyzer.ts

@@ -0,0 +1,158 @@
+import { Severity } from '@aiready/core';
+
+/**
+ * Internal issue analysis logic
+ */
+/**
+ * Analyzes architectural issues related to AI context windows.
+ * Detects problems like high import depth, large context budgets,
+ * circular dependencies, and low cohesion.
+ *
+ * @param params - Combined metrics and graph data for a module
+ * @returns List of identified issues with severity and suggestions
+ */
+export function analyzeIssues(params: {
+  file: string;
+  importDepth: number;
+  contextBudget: number;
+  cohesionScore: number;
+  fragmentationScore: number;
+  maxDepth: number;
+  maxContextBudget: number;
+  minCohesion: number;
+  maxFragmentation: number;
+  circularDeps: string[][];
+}): {
+  severity: Severity;
+  issues: string[];
+  recommendations: string[];
+  potentialSavings: number;
+} {
+  const {
+    file,
+    importDepth,
+    contextBudget,
+    cohesionScore,
+    fragmentationScore,
+    maxDepth,
+    maxContextBudget,
+    minCohesion,
+    maxFragmentation,
+    circularDeps,
+  } = params;
+
+  const issues: string[] = [];
+  const recommendations: string[] = [];
+  let severity: Severity = Severity.Info;
+  let potentialSavings = 0;
+
+  // Check circular dependencies (CRITICAL)
+  if (circularDeps.length > 0) {
+    severity = Severity.Critical;
+    issues.push(`Part of ${circularDeps.length} circular dependency chain(s)`);
+    recommendations.push(
+      'Break circular dependencies by extracting interfaces or using dependency injection'
+    );
+    potentialSavings += contextBudget * 0.2;
+  }
+
+  // Check import depth
+  if (importDepth > maxDepth * 1.5) {
+    severity = Severity.Critical;
+    issues.push(`Import depth ${importDepth} exceeds limit by 50%`);
+    recommendations.push('Flatten dependency tree or use facade pattern');
+    potentialSavings += contextBudget * 0.3;
+  } else if (importDepth > maxDepth) {
+    if (severity !== Severity.Critical) severity = Severity.Major;
+    issues.push(
+      `Import depth ${importDepth} exceeds recommended maximum ${maxDepth}`
+    );
+    recommendations.push('Consider reducing dependency depth');
+    potentialSavings += contextBudget * 0.15;
+  }
+
+  // Check context budget
+  if (contextBudget > maxContextBudget * 1.5) {
+    severity = Severity.Critical;
+    issues.push(
+      `Context budget ${contextBudget.toLocaleString()} tokens is 50% over limit`
+    );
+    recommendations.push(
+      'Split into smaller modules or reduce dependency tree'
+    );
+    potentialSavings += contextBudget * 0.4;
+  } else if (contextBudget > maxContextBudget) {
+    if (severity !== Severity.Critical) severity = Severity.Major;
+    issues.push(
+      `Context budget ${contextBudget.toLocaleString()} exceeds ${maxContextBudget.toLocaleString()}`
+    );
+    recommendations.push('Reduce file size or dependencies');
+    potentialSavings += contextBudget * 0.2;
+  }
+
+  // Check cohesion
+  if (cohesionScore < minCohesion * 0.5) {
+    if (severity !== Severity.Critical) severity = Severity.Major;
+    issues.push(
+      `Very low cohesion (${(cohesionScore * 100).toFixed(0)}%) - mixed concerns`
+    );
+    recommendations.push(
+      'Split file by domain - separate unrelated functionality'
+    );
+    potentialSavings += contextBudget * 0.25;
+  } else if (cohesionScore < minCohesion) {
+    if (severity === Severity.Info) severity = Severity.Minor;
+    issues.push(`Low cohesion (${(cohesionScore * 100).toFixed(0)}%)`);
+    recommendations.push('Consider grouping related exports together');
+    potentialSavings += contextBudget * 0.1;
+  }
+
+  // Check fragmentation
+  if (fragmentationScore > maxFragmentation) {
+    if (severity === Severity.Info || severity === Severity.Minor)
+      severity = Severity.Minor;
+    issues.push(
+      `High fragmentation (${(fragmentationScore * 100).toFixed(0)}%) - scattered implementation`
+    );
+    recommendations.push('Consolidate with related files in same domain');
+    potentialSavings += contextBudget * 0.3;
+  }
+
+  if (issues.length === 0) {
+    issues.push('No significant issues detected');
+    recommendations.push('File is well-structured for AI context usage');
+  }
+
+  // Detect build artifacts
+  if (isBuildArtifact(file)) {
+    issues.push('Detected build artifact (bundled/output file)');
+    recommendations.push('Exclude build outputs from analysis');
+    severity = Severity.Info;
+    potentialSavings = 0;
+  }
+
+  return {
+    severity,
+    issues,
+    recommendations,
+    potentialSavings: Math.floor(potentialSavings),
+  };
+}
+
+/**
+ * Determines if a file path belongs to a build artifact or dependency folder.
+ * Helps exclude generated files from analysis to prevent false positives.
+ *
+ * @param filePath - The path to check
+ * @returns True if the file is a build artifact, false otherwise
+ */
+export function isBuildArtifact(filePath: string): boolean {
+  const lower = filePath.toLowerCase();
+  return (
+    lower.includes('/node_modules/') ||
+    lower.includes('/dist/') ||
+    lower.includes('/build/') ||
+    lower.includes('/out/') ||
+    lower.includes('/.next/')
+  );
+}

package/src/metrics.ts

@@ -5,6 +5,15 @@ 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
+ */
 export function calculateEnhancedCohesion(
   exports: ExportInfo[],
   filePath?: string,

package/src/scoring.ts

@@ -4,6 +4,7 @@ import {
   DEFAULT_COST_CONFIG,
   type CostConfig,
   ToolName,
+  getRatingSlug,
 } from '@aiready/core';
 import type { ToolScoringOutput } from '@aiready/core';
 import type { ContextSummary } from './types';
@@ -190,9 +191,6 @@ export function calculateContextScore(
 }
 
 export function mapScoreToRating(score: number): string {
-  if (score >= 90) return 'excellent';
-  if (score >= 75) return 'good';
-  if (score >= 60) return 'fair';
-  if (score >= 40) return 'needs work';
-  return 'critical';
+  // Use core implementation to resolve duplication
+  return getRatingSlug(score).replace('-', ' ');
 }

package/src/semantic-analysis.ts

@@ -5,9 +5,12 @@ import type {
   DomainSignals,
   ExportInfo,
 } from './types';
+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
  */
 export function buildCoUsageMatrix(
   graph: DependencyGraph
@@ -38,6 +41,8 @@ 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
  */
 export function buildTypeGraph(
   graph: DependencyGraph
@@ -60,6 +65,9 @@ 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
  */
 export function findSemanticClusters(
   coUsageMatrix: Map<string, Map<string, number>>,
@@ -312,20 +320,6 @@ export function inferDomain(
   return 'unknown';
 }
 
-function singularize(word: string): string {
-  const irregulars: Record<string, string> = {
-    people: 'person',
-    children: 'child',
-    men: 'man',
-    women: 'woman',
-  };
-  if (irregulars[word]) return irregulars[word];
-  if (word.endsWith('ies')) return word.slice(0, -3) + 'y';
-  if (word.endsWith('ses')) return word.slice(0, -2);
-  if (word.endsWith('s') && word.length > 3) return word.slice(0, -1);
-  return word;
-}
-
 export function getCoUsageData(
   file: string,
   coUsageMatrix: Map<string, Map<string, number>>