@aiready/context-analyzer 0.21.5 → 0.21.6

package/src/cluster-detector.ts

@@ -35,7 +35,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/graph-builder.ts

@@ -1,4 +1,10 @@
 import { estimateTokens, parseFileExports } 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,
@@ -94,25 +100,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 +183,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 +194,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 +224,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/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,143 @@
+import { Severity } from '@aiready/core';
+
+/**
+ * Internal issue analysis logic
+ */
+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),
+  };
+}
+
+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/semantic-analysis.ts

@@ -5,6 +5,7 @@ import type {
   DomainSignals,
   ExportInfo,
 } from './types';
+import { singularize } from './utils/string-utils';
 
 /**
  * Build co-usage matrix: track which files are imported together
@@ -312,20 +313,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>>

package/src/summary.ts

@@ -3,7 +3,7 @@ import type {
   ContextSummary,
   ModuleCluster,
 } from './types';
-import { calculatePathEntropy, calculateDirectoryDistance } from './analyzer';
+import { calculatePathEntropy, calculateDirectoryDistance } from './metrics';
 import { GLOBAL_SCAN_OPTIONS } from '@aiready/core';
 
 /**
@@ -11,7 +11,7 @@ import { GLOBAL_SCAN_OPTIONS } from '@aiready/core';
  */
 export function generateSummary(
   results: ContextAnalysisResult[],
-  options?: any
+  options: any = {}
 ): ContextSummary {
   const config = options
     ? Object.fromEntries(
@@ -19,137 +19,92 @@ export function generateSummary(
           ([key]) => !GLOBAL_SCAN_OPTIONS.includes(key) || key === 'rootDir'
         )
       )
-    : undefined;
-
-  if (results.length === 0) {
-    return {
-      totalFiles: 0,
-      totalTokens: 0,
-      avgContextBudget: 0,
-      maxContextBudget: 0,
-      avgImportDepth: 0,
-      maxImportDepth: 0,
-      deepFiles: [],
-      avgFragmentation: 0,
-      fragmentedModules: [],
-      avgCohesion: 0,
-      lowCohesionFiles: [],
-      criticalIssues: 0,
-      majorIssues: 0,
-      minorIssues: 0,
-      totalPotentialSavings: 0,
-      topExpensiveFiles: [],
-      config,
-    };
-  }
+    : {};
 
   const totalFiles = results.length;
   const totalTokens = results.reduce((sum, r) => sum + r.tokenCost, 0);
-  const totalContextBudget = results.reduce(
-    (sum, r) => sum + r.contextBudget,
-    0
-  );
-  const avgContextBudget = totalContextBudget / totalFiles;
-  const maxContextBudget = Math.max(...results.map((r) => r.contextBudget));
-
-  const avgImportDepth =
-    results.reduce((sum, r) => sum + r.importDepth, 0) / totalFiles;
-  const maxImportDepth = Math.max(...results.map((r) => r.importDepth));
+  const avgContextBudget =
+    totalFiles > 0
+      ? results.reduce((sum, r) => sum + r.contextBudget, 0) / totalFiles
+      : 0;
 
+  // Find deep files
   const deepFiles = results
-    .filter((r) => r.importDepth >= 5)
-    .map((r) => ({ file: r.file, depth: r.importDepth }))
-    .sort((a, b) => b.depth - a.depth)
-    .slice(0, 10);
+    .filter((r) => r.importDepth > 5)
+    .map((r) => ({ file: r.file, depth: r.importDepth }));
 
-  const avgFragmentation =
-    results.reduce((sum, r) => sum + r.fragmentationScore, 0) / totalFiles;
+  const maxImportDepth = Math.max(0, ...results.map((r) => r.importDepth));
 
+  // Find fragmented modules (clusters)
   const moduleMap = new Map<string, ContextAnalysisResult[]>();
-  for (const result of results) {
-    for (const domain of result.domains) {
-      if (!moduleMap.has(domain)) moduleMap.set(domain, []);
-      moduleMap.get(domain)!.push(result);
+  results.forEach((r) => {
+    const parts = r.file.split('/');
+    // Try to identify domain/module (e.g., packages/core, src/utils)
+    let domain = 'root';
+    if (parts.length > 2) {
+      domain = parts.slice(0, 2).join('/');
     }
-  }
+    if (!moduleMap.has(domain)) moduleMap.set(domain, []);
+    moduleMap.get(domain)!.push(r);
+  });
 
   const fragmentedModules: ModuleCluster[] = [];
-  for (const [domain, files] of moduleMap.entries()) {
-    if (files.length < 2) continue;
-    const fragmentationScore =
-      files.reduce((sum, f) => sum + f.fragmentationScore, 0) / files.length;
-    if (fragmentationScore < 0.3) continue;
-
-    const totalTokens = files.reduce((sum, f) => sum + f.tokenCost, 0);
-    const avgCohesion =
-      files.reduce((sum, f) => sum + f.cohesionScore, 0) / files.length;
-    const targetFiles = Math.max(1, Math.ceil(files.length / 3));
-
+  moduleMap.forEach((files, domain) => {
+    const clusterTokens = files.reduce((sum, f) => sum + f.tokenCost, 0);
     const filePaths = files.map((f) => f.file);
-    const pathEntropy = calculatePathEntropy(filePaths);
-    const directoryDistance = calculateDirectoryDistance(filePaths);
-
-    function jaccard(a: string[], b: string[]) {
-      const s1 = new Set(a || []);
-      const s2 = new Set(b || []);
-      if (s1.size === 0 && s2.size === 0) return 0;
-      const inter = new Set([...s1].filter((x) => s2.has(x)));
-      const uni = new Set([...s1, ...s2]);
-      return uni.size === 0 ? 0 : inter.size / uni.size;
+    const avgEntropy = calculatePathEntropy(filePaths);
+
+    // A module is fragmented if it has many files with high directory distance
+    // and relatively low cohesion
+    const fragmentationScore = Math.min(1, avgEntropy * (files.length / 10));
+
+    if (fragmentationScore > 0.4) {
+      fragmentedModules.push({
+        domain,
+        files: filePaths,
+        fragmentationScore,
+        totalTokens: clusterTokens,
+        avgCohesion:
+          files.reduce((sum, f) => sum + f.cohesionScore, 0) / files.length,
+        suggestedStructure: {
+          targetFiles: Math.ceil(files.length / 2),
+          consolidationPlan: [
+            `Consolidate ${files.length} files in ${domain} into fewer modules`,
+          ],
+        },
+      });
     }
+  });
 
-    let importSimTotal = 0;
-    let importPairs = 0;
-    for (let i = 0; i < files.length; i++) {
-      for (let j = i + 1; j < files.length; j++) {
-        importSimTotal += jaccard(
-          files[i].dependencyList || [],
-          files[j].dependencyList || []
-        );
-        importPairs++;
-      }
-    }
+  fragmentedModules.sort((a, b) => b.fragmentationScore - a.fragmentationScore);
 
-    const importCohesion = importPairs > 0 ? importSimTotal / importPairs : 0;
-
-    fragmentedModules.push({
-      domain,
-      files: files.map((f) => f.file),
-      totalTokens,
-      fragmentationScore,
-      avgCohesion,
-      importCohesion,
-      pathEntropy,
-      directoryDistance,
-      suggestedStructure: {
-        targetFiles,
-        consolidationPlan: [
-          `Consolidate ${files.length} files across ${new Set(files.map((f) => f.file.split('/').slice(0, -1).join('/'))).size} directories`,
-          `Target ~${targetFiles} core modules to reduce context switching`,
-        ],
-      },
-    });
-  }
+  const avgFragmentation =
+    fragmentedModules.length > 0
+      ? fragmentedModules.reduce((sum, m) => sum + m.fragmentationScore, 0) /
+        fragmentedModules.length
+      : 0;
 
+  // Cohesion
   const avgCohesion =
-    results.reduce((sum, r) => sum + r.cohesionScore, 0) / totalFiles;
+    results.reduce((sum, r) => sum + r.cohesionScore, 0) / (totalFiles || 1);
+
   const lowCohesionFiles = results
     .filter((r) => r.cohesionScore < 0.4)
-    .map((r) => ({ file: r.file, score: r.cohesionScore }))
-    .sort((a, b) => a.score - b.score)
-    .slice(0, 10);
+    .map((r) => ({ file: r.file, score: r.cohesionScore }));
 
+  // Issues
   const criticalIssues = results.filter(
     (r) => r.severity === 'critical'
   ).length;
   const majorIssues = results.filter((r) => r.severity === 'major').length;
   const minorIssues = results.filter((r) => r.severity === 'minor').length;
+
   const totalPotentialSavings = results.reduce(
-    (sum, r) => sum + r.potentialSavings,
+    (sum, r) => sum + (r.potentialSavings || 0),
     0
   );
 
-  const topExpensiveFiles = results
+  const topExpensiveFiles = [...results]
     .sort((a, b) => b.contextBudget - a.contextBudget)
     .slice(0, 10)
     .map((r) => ({
@@ -162,8 +117,9 @@ export function generateSummary(
     totalFiles,
     totalTokens,
     avgContextBudget,
-    maxContextBudget,
-    avgImportDepth,
+    maxContextBudget: Math.max(0, ...results.map((r) => r.contextBudget)),
+    avgImportDepth:
+      results.reduce((sum, r) => sum + r.importDepth, 0) / (totalFiles || 1),
     maxImportDepth,
     deepFiles,
     avgFragmentation,

package/src/utils/dependency-graph-utils.ts

@@ -0,0 +1,126 @@
+/**
+ * Shared dependency graph utilities used by context analyzers.
+ */
+
+export function calculateImportDepthFromEdges(
+  file: string,
+  edges: Map<string, Set<string>>,
+  visited = new Set<string>(),
+  depth = 0
+): number {
+  if (visited.has(file)) return depth;
+
+  const dependencies = edges.get(file);
+  if (!dependencies || dependencies.size === 0) return depth;
+
+  const nextVisited = new Set(visited);
+  nextVisited.add(file);
+
+  let maxDepth = depth;
+  for (const dep of dependencies) {
+    maxDepth = Math.max(
+      maxDepth,
+      calculateImportDepthFromEdges(dep, edges, nextVisited, depth + 1)
+    );
+  }
+
+  return maxDepth;
+}
+
+export function getTransitiveDependenciesFromEdges(
+  file: string,
+  edges: Map<string, Set<string>>,
+  visited = new Set<string>()
+): string[] {
+  if (visited.has(file)) return [];
+
+  const nextVisited = new Set(visited);
+  nextVisited.add(file);
+
+  const dependencies = edges.get(file);
+  if (!dependencies || dependencies.size === 0) return [];
+
+  const allDeps: string[] = [];
+  for (const dep of dependencies) {
+    allDeps.push(dep);
+    allDeps.push(
+      ...getTransitiveDependenciesFromEdges(dep, edges, nextVisited)
+    );
+  }
+
+  return [...new Set(allDeps)];
+}
+
+export function detectGraphCycles(edges: Map<string, Set<string>>): 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);
+
+    const dependencies = edges.get(file);
+    if (dependencies) {
+      for (const dep of dependencies) {
+        dfs(dep, [...path, file]);
+      }
+    }
+
+    recursionStack.delete(file);
+  }
+
+  for (const file of edges.keys()) {
+    if (!visited.has(file)) {
+      dfs(file, []);
+    }
+  }
+
+  return cycles;
+}
+
+export function detectGraphCyclesFromFile(
+  file: string,
+  edges: Map<string, Set<string>>
+): string[][] {
+  const cycles: string[][] = [];
+  const visited = new Set<string>();
+  const recursionStack = new Set<string>();
+
+  function dfs(current: string, path: string[]): void {
+    if (recursionStack.has(current)) {
+      const cycleStart = path.indexOf(current);
+      if (cycleStart !== -1) {
+        cycles.push([...path.slice(cycleStart), current]);
+      }
+      return;
+    }
+
+    if (visited.has(current)) return;
+
+    visited.add(current);
+    recursionStack.add(current);
+
+    const dependencies = edges.get(current);
+    if (dependencies) {
+      for (const dep of dependencies) {
+        dfs(dep, [...path, current]);
+      }
+    }
+
+    recursionStack.delete(current);
+  }
+
+  dfs(file, []);
+  return cycles;
+}