@aiready/context-analyzer 0.21.5 → 0.21.7

package/src/summary.ts

@@ -3,15 +3,15 @@ import type {
   ContextSummary,
   ModuleCluster,
 } from './types';
-import { calculatePathEntropy, calculateDirectoryDistance } from './analyzer';
 import { GLOBAL_SCAN_OPTIONS } from '@aiready/core';
+import { calculatePathEntropy } from './metrics';
 
 /**
  * Generate summary of context analysis results
  */
 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/types.ts

@@ -1,45 +1,77 @@
 import type { ScanOptions, Severity } from '@aiready/core';
 
+/**
+ * Options for the Context Analyzer tool.
+ * Controls thresholds for import depth, context budget, and cohesion.
+ */
 export interface ContextAnalyzerOptions extends ScanOptions {
-  maxDepth?: number; // Maximum acceptable import depth, default 5
-  maxContextBudget?: number; // Maximum acceptable token budget, default 10000
-  minCohesion?: number; // Minimum acceptable cohesion score (0-1), default 0.6
-  maxFragmentation?: number; // Maximum acceptable fragmentation (0-1), default 0.5
-  focus?: 'fragmentation' | 'cohesion' | 'depth' | 'all'; // Analysis focus, default 'all'
-  includeNodeModules?: boolean; // Include node_modules in analysis, default false
+  /** Maximum acceptable import depth (default: 5) */
+  maxDepth?: number;
+  /** Maximum acceptable token budget for a single context (default: 25000) */
+  maxContextBudget?: number;
+  /** Minimum acceptable cohesion score between 0 and 1 (default: 0.6) */
+  minCohesion?: number;
+  /** Maximum acceptable fragmentation score between 0 and 1 (default: 0.5) */
+  maxFragmentation?: number;
+  /** Analysis focus area: fragmentation, cohesion, depth, or all (default: 'all') */
+  focus?: 'fragmentation' | 'cohesion' | 'depth' | 'all';
+  /** Whether to include node_modules in the analysis (default: false) */
+  includeNodeModules?: boolean;
 }
 
+/**
+ * The result of a context analysis for a single file or module.
+ * Includes metrics for tokens, dependencies, cohesion, and AI impact.
+ */
 export interface ContextAnalysisResult {
+  /** The file path being analyzed */
   file: string;
 
   // Basic metrics
-  tokenCost: number; // Total tokens in this file
+  /** Total number of tokens in this file */
+  tokenCost: number;
+  /** Total lines of code in the file */
   linesOfCode: number;
 
   // Dependency analysis
-  importDepth: number; // Max depth of import tree
-  dependencyCount: number; // Total transitive dependencies
-  dependencyList: string[]; // All files in dependency tree
-  circularDeps: string[][]; // Circular dependency chains if any
+  /** Maximum depth of the import tree for this file */
+  importDepth: number;
+  /** Total number of transitive dependencies */
+  dependencyCount: number;
+  /** List of all files in the dependency tree */
+  dependencyList: string[];
+  /** Detected circular dependency chains */
+  circularDeps: string[][];
 
   // Cohesion analysis
-  cohesionScore: number; // 0-1, how related are exports (1 = perfect cohesion)
-  domains: string[]; // Detected domain categories (e.g., ['user', 'auth'])
+  /** Cohesion score from 0 to 1 (1 is perfect cohesion) */
+  cohesionScore: number;
+  /** Detected domain categories for the module */
+  domains: string[];
+  /** Number of exported symbols */
   exportCount: number;
 
   // AI context impact
-  contextBudget: number; // Total tokens to understand this file (includes all deps)
-  fragmentationScore: number; // 0-1, how scattered is this domain (0 = well-grouped)
-  relatedFiles: string[]; // Files that should be loaded together
+  /** Total tokens required to understand this file and all its dependencies */
+  contextBudget: number;
+  /** Fragmentation score from 0 to 1 (0 is well-grouped) */
+  fragmentationScore: number;
+  /** List of files that should be loaded together for full context */
+  relatedFiles: string[];
 
   // File classification (NEW)
-  fileClassification: FileClassification; // Type of file for analysis context
+  /** The semantic classification of the file (e.g. 'barrel-export', 'service-file') */
+  fileClassification: FileClassification;
 
   // Recommendations
+  /** Overall severity of identified issues */
   severity: Severity | 'critical' | 'major' | 'minor' | 'info';
-  issues: string[]; // List of specific problems
-  recommendations: string[]; // Actionable suggestions
-  potentialSavings: number; // Estimated token savings if fixed
+  /** List of specific structural problems found */
+  issues: string[];
+  /** Actionable suggestions for improving context readiness */
+  recommendations: string[];
+  /** Estimated tokens that could be saved by following recommendations */
+  potentialSavings: number;
 }
 
 /**

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;
+}