@aiready/context-analyzer 0.19.18 → 0.19.21

package/dist/index.mjs

@@ -1,4 +1,5 @@
 import {
+  Classification,
   ContextAnalyzerProvider,
   adjustCohesionForClassification,
   adjustFragmentationForClassification,
@@ -43,8 +44,9 @@ import {
   isTypeDefinition,
   isUtilityModule,
   mapScoreToRating
-} from "./chunk-PVVMK56C.mjs";
+} from "./chunk-CCBNKQYB.mjs";
 export {
+  Classification,
   ContextAnalyzerProvider,
   adjustCohesionForClassification,
   adjustFragmentationForClassification,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiready/context-analyzer",
-  "version": "0.19.18",
+  "version": "0.19.21",
   "description": "AI context window cost analysis - detect fragmented code, deep import chains, and expensive context budgets",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -49,7 +49,7 @@
     "commander": "^14.0.0",
     "chalk": "^5.3.0",
     "prompts": "^2.4.2",
-    "@aiready/core": "0.21.18"
+    "@aiready/core": "0.21.21"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",

package/src/__tests__/cluster-detector.test.ts

@@ -0,0 +1,138 @@
+import { describe, it, expect } from 'vitest';
+import { detectModuleClusters } from '../cluster-detector';
+import { DependencyGraph } from '../types';
+
+describe('Cluster Detector', () => {
+  it('should group files by domain into clusters', () => {
+    const graph: DependencyGraph = {
+      nodes: new Map([
+        [
+          'src/auth/login.ts',
+          {
+            file: 'src/auth/login.ts',
+            imports: [],
+            exports: [
+              { name: 'login', type: 'function', inferredDomain: 'auth' },
+            ],
+            tokenCost: 1000,
+            linesOfCode: 50,
+          },
+        ],
+        [
+          'src/auth/logout.ts',
+          {
+            file: 'src/auth/logout.ts',
+            imports: [],
+            exports: [
+              { name: 'logout', type: 'function', inferredDomain: 'auth' },
+            ],
+            tokenCost: 500,
+            linesOfCode: 20,
+          },
+        ],
+        [
+          'src/user/profile.ts',
+          {
+            file: 'src/user/profile.ts',
+            imports: [],
+            exports: [
+              { name: 'getProfile', type: 'function', inferredDomain: 'user' },
+            ],
+            tokenCost: 2000,
+            linesOfCode: 100,
+          },
+        ],
+      ]),
+      edges: new Map(),
+    };
+
+    const clusters = detectModuleClusters(graph);
+
+    // Should find 'auth' cluster (2 files), but skip 'user' (only 1 file)
+    expect(clusters.length).toBe(1);
+    expect(clusters[0].domain).toBe('auth');
+    expect(clusters[0].files).toHaveLength(2);
+    expect(clusters[0].totalTokens).toBe(1500);
+  });
+
+  it('should calculate fragmentation and suggest consolidation', () => {
+    const graph: DependencyGraph = {
+      nodes: new Map([
+        [
+          'src/auth/login.ts',
+          {
+            file: 'src/auth/login.ts',
+            imports: ['lib/common.ts'],
+            exports: [
+              { name: 'login', type: 'function', inferredDomain: 'auth' },
+            ],
+            tokenCost: 1000,
+            linesOfCode: 50,
+          },
+        ],
+        [
+          'src/utils/auth-helper.ts',
+          {
+            file: 'src/utils/auth-helper.ts',
+            imports: ['lib/common.ts'],
+            exports: [
+              { name: 'helper', type: 'function', inferredDomain: 'auth' },
+            ],
+            tokenCost: 500,
+            linesOfCode: 20,
+          },
+        ],
+      ]),
+      edges: new Map(),
+    };
+
+    const clusters = detectModuleClusters(graph);
+
+    expect(clusters[0].domain).toBe('auth');
+    // fragmentation should be high because they are in different directories
+    expect(clusters[0].fragmentationScore).toBeGreaterThan(0.5);
+    expect(
+      clusters[0].suggestedStructure.consolidationPlan.length
+    ).toBeGreaterThan(0);
+    expect(clusters[0].suggestedStructure.consolidationPlan[0]).toContain(
+      'Consolidate'
+    );
+  });
+
+  it('should suggest boundary improvements for large domains', () => {
+    const graph: DependencyGraph = {
+      nodes: new Map([
+        [
+          'src/big/part1.ts',
+          {
+            file: 'src/big/part1.ts',
+            imports: [],
+            exports: [{ name: 'p1', type: 'function', inferredDomain: 'big' }],
+            tokenCost: 15000,
+            linesOfCode: 500,
+          },
+        ],
+        [
+          'src/big/part2.ts',
+          {
+            file: 'src/big/part2.ts',
+            imports: [],
+            exports: [{ name: 'p2', type: 'function', inferredDomain: 'big' }],
+            tokenCost: 10000,
+            linesOfCode: 400,
+          },
+        ],
+      ]),
+      edges: new Map(),
+    };
+
+    const clusters = detectModuleClusters(graph);
+
+    expect(clusters[0].totalTokens).toBe(25000);
+    expect(
+      clusters[0].suggestedStructure.consolidationPlan.some((p) =>
+        p.includes('Ensure clear sub-domain boundaries')
+      )
+    ).toBe(true);
+  });
+});

package/src/__tests__/provider.test.ts

@@ -0,0 +1,78 @@
+import { describe, it, expect, vi } from 'vitest';
+import { ContextAnalyzerProvider } from '../provider';
+import * as analyzer from '../analyzer';
+import * as summary from '../summary';
+
+vi.mock('../analyzer', async () => {
+  const actual = await vi.importActual('../analyzer');
+  return {
+    ...actual,
+    analyzeContext: vi.fn(),
+  };
+});
+
+vi.mock('../summary', async () => {
+  const actual = await vi.importActual('../summary');
+  return {
+    ...actual,
+    generateSummary: vi.fn(),
+  };
+});
+
+describe('Context Analyzer Provider', () => {
+  it('should analyze and return SpokeOutput', async () => {
+    vi.mocked(analyzer.analyzeContext).mockResolvedValue([
+      {
+        file: 'file1.ts',
+        issues: ['issue'],
+        severity: 'major',
+        recommendations: ['fix'],
+        tokenCost: 100,
+        importDepth: 2,
+        contextBudget: 500,
+        cohesionScore: 0.8,
+        fragmentationScore: 0.1,
+        dependencyCount: 5,
+        dependencyList: [],
+        circularDeps: [],
+        domains: [],
+        exportCount: 1,
+        relatedFiles: [],
+        fileClassification: 'unknown',
+        potentialSavings: 0,
+        linesOfCode: 50,
+      } as any,
+    ]);
+    vi.mocked(summary.generateSummary).mockReturnValue({
+      totalFiles: 1,
+    } as any);
+
+    const output = await ContextAnalyzerProvider.analyze({ rootDir: '.' });
+
+    expect(output.summary.totalFiles).toBe(1);
+    expect(output.results[0].fileName).toBe('file1.ts');
+  });
+
+  it('should score an output', () => {
+    const mockOutput = {
+      summary: {
+        score: 80,
+        avgContextBudget: 1000,
+        maxContextBudget: 5000,
+        avgImportDepth: 3,
+        maxImportDepth: 5,
+        avgFragmentation: 0.2,
+        criticalIssues: 0,
+        majorIssues: 0,
+        totalFiles: 10,
+      } as any,
+      results: [],
+    };
+
+    const scoring = ContextAnalyzerProvider.score(mockOutput as any, {
+      rootDir: '.',
+    });
+    expect(scoring.score).toBeDefined();
+    expect(scoring.toolName).toBe('context-analyzer');
+  });
+});

package/src/__tests__/remediation.test.ts

@@ -0,0 +1,94 @@
+import { describe, it, expect } from 'vitest';
+import {
+  getClassificationRecommendations,
+  getGeneralRecommendations,
+} from '../remediation';
+
+describe('Remediation Logic', () => {
+  describe('getClassificationRecommendations', () => {
+    it('should return specific recommendations for barrel exports', () => {
+      const recs = getClassificationRecommendations(
+        'barrel-export',
+        'index.ts',
+        []
+      );
+      expect(recs[0]).toContain('Barrel export file detected');
+    });
+
+    it('should return specific recommendations for type definitions', () => {
+      const recs = getClassificationRecommendations(
+        'type-definition',
+        'types.ts',
+        []
+      );
+      expect(recs[0]).toContain('Type definition file');
+    });
+
+    it('should return general issues if classification is unknown', () => {
+      const issues = ['High complexity'];
+      const recs = getClassificationRecommendations(
+        'unknown',
+        'file.ts',
+        issues
+      );
+      expect(recs).toEqual(issues);
+    });
+  });
+
+  describe('getGeneralRecommendations', () => {
+    const thresholds = {
+      maxContextBudget: 10000,
+      maxDepth: 5,
+      minCohesion: 0.6,
+      maxFragmentation: 0.5,
+    };
+
+    it('should identify high context budget as major severity', () => {
+      const result = getGeneralRecommendations(
+        {
+          contextBudget: 15000,
+          importDepth: 3,
+          circularDeps: [],
+          cohesionScore: 0.8,
+          fragmentationScore: 0.2,
+        },
+        thresholds
+      );
+
+      expect(result.severity).toBe('major');
+      expect(result.issues[0]).toContain('High context budget');
+    });
+
+    it('should identify circular dependencies as critical severity', () => {
+      const result = getGeneralRecommendations(
+        {
+          contextBudget: 5000,
+          importDepth: 3,
+          circularDeps: [['a.ts', 'b.ts', 'a.ts']],
+          cohesionScore: 0.8,
+          fragmentationScore: 0.2,
+        },
+        thresholds
+      );
+
+      expect(result.severity).toBe('critical');
+      expect(result.recommendations[0]).toContain('circular imports');
+    });
+
+    it('should identify low cohesion as minor severity', () => {
+      const result = getGeneralRecommendations(
+        {
+          contextBudget: 5000,
+          importDepth: 3,
+          circularDeps: [],
+          cohesionScore: 0.4,
+          fragmentationScore: 0.2,
+        },
+        thresholds
+      );
+
+      expect(result.severity).toBe('minor');
+      expect(result.issues[0]).toContain('Low cohesion score');
+    });
+  });
+});

package/src/analyzer.ts

@@ -1,4 +1,9 @@
-import { estimateTokens, Severity } from '@aiready/core';
+import {
+  estimateTokens,
+  Severity,
+  scanFiles,
+  readFileContent,
+} from '@aiready/core';
 import type {
   DependencyGraph,
   DependencyNode,
@@ -6,15 +11,34 @@ import type {
   ModuleCluster,
   FileClassification,
   ContextAnalysisResult,
+  ContextAnalyzerOptions,
+  ContextSummary,
 } from './types';
 import { calculateEnhancedCohesion } from './metrics';
 import { isTestFile } from './ast-utils';
+import { calculateContextScore } from './scoring';
+import { getSmartDefaults } from './defaults';
+import { generateSummary } from './summary';
 
 export * from './graph-builder';
 export * from './metrics';
 export * from './classifier';
 export * from './cluster-detector';
 export * from './remediation';
+import {
+  buildDependencyGraph,
+  calculateImportDepth,
+  getTransitiveDependencies,
+  calculateContextBudget,
+  detectCircularDependencies,
+} from './graph-builder';
+import { detectModuleClusters } from './cluster-detector';
+import {
+  classifyFile,
+  adjustCohesionForClassification,
+  adjustFragmentationForClassification,
+} from './classifier';
+import { getClassificationRecommendations } from './remediation';
 
 /**
  * Calculate cohesion score (how related are exports in a file)
@@ -184,3 +208,222 @@ function isBuildArtifact(filePath: string): boolean {
     lower.includes('/.next/')
   );
 }
+
+/**
+ * Analyze AI context window cost for a codebase
+ */
+export async function analyzeContext(
+  options: ContextAnalyzerOptions
+): Promise<ContextAnalysisResult[]> {
+  const {
+    maxDepth = 5,
+    maxContextBudget = 10000,
+    minCohesion = 0.6,
+    maxFragmentation = 0.5,
+    focus = 'all',
+    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: metric.metrics.circularDependencies.map((cycle) =>
+            cycle.split(' → ')
+          ),
+        });
+
+      return {
+        file: metric.file,
+        tokenCost: Math.floor(
+          metric.contextBudget / (1 + metric.imports.length || 1)
+        ),
+        linesOfCode: metric.metrics.linesOfCode,
+        importDepth: metric.importDepth,
+        dependencyCount: metric.imports.length,
+        dependencyList: metric.imports.map(
+          (imp) => imp.resolvedPath || imp.source
+        ),
+        circularDeps: metric.metrics.circularDependencies.map((cycle) =>
+          cycle.split(' → ')
+        ),
+        cohesionScore: metric.cohesion,
+        domains: ['python'],
+        exportCount: metric.exports.length,
+        contextBudget: metric.contextBudget,
+        fragmentationScore: 0,
+        relatedFiles: [],
+        fileClassification: 'unknown' as const,
+        severity,
+        issues,
+        recommendations,
+        potentialSavings,
+      };
+    });
+  }
+
+  const circularDeps = detectCircularDependencies(graph);
+  const useLogScale = files.length >= 500;
+  const clusters = detectModuleClusters(graph, { useLogScale });
+  const fragmentationMap = new Map<string, number>();
+  for (const cluster of clusters) {
+    for (const file of cluster.files) {
+      fragmentationMap.set(file, cluster.fragmentationScore);
+    }
+  }
+
+  const results: ContextAnalysisResult[] = [];
+
+  for (const { file } of fileContents) {
+    const node = graph.nodes.get(file);
+    if (!node) continue;
+
+    const importDepth =
+      focus === 'depth' || focus === 'all'
+        ? calculateImportDepth(file, graph)
+        : 0;
+    const dependencyList =
+      focus === 'depth' || focus === 'all'
+        ? getTransitiveDependencies(file, graph)
+        : [];
+    const contextBudget =
+      focus === 'all' ? calculateContextBudget(file, graph) : node.tokenCost;
+    const cohesionScore =
+      focus === 'cohesion' || focus === 'all'
+        ? calculateCohesion(node.exports, file, {
+            coUsageMatrix: graph.coUsageMatrix,
+          })
+        : 1;
+
+    const fragmentationScore = fragmentationMap.get(file) || 0;
+    const relatedFiles: string[] = [];
+    for (const cluster of clusters) {
+      if (cluster.files.includes(file)) {
+        relatedFiles.push(...cluster.files.filter((f) => f !== file));
+        break;
+      }
+    }
+
+    const { issues } = analyzeIssues({
+      file,
+      importDepth,
+      contextBudget,
+      cohesionScore,
+      fragmentationScore,
+      maxDepth,
+      maxContextBudget,
+      minCohesion,
+      maxFragmentation,
+      circularDeps,
+    });
+
+    const domains = [
+      ...new Set(node.exports.map((e) => e.inferredDomain || 'unknown')),
+    ];
+    const fileClassification = classifyFile(node);
+    const adjustedCohesionScore = adjustCohesionForClassification(
+      cohesionScore,
+      fileClassification,
+      node
+    );
+    const adjustedFragmentationScore = adjustFragmentationForClassification(
+      fragmentationScore,
+      fileClassification
+    );
+    const classificationRecommendations = getClassificationRecommendations(
+      fileClassification,
+      file,
+      issues
+    );
+
+    const {
+      severity: adjustedSeverity,
+      issues: adjustedIssues,
+      recommendations: finalRecommendations,
+      potentialSavings: adjustedSavings,
+    } = analyzeIssues({
+      file,
+      importDepth,
+      contextBudget,
+      cohesionScore: adjustedCohesionScore,
+      fragmentationScore: adjustedFragmentationScore,
+      maxDepth,
+      maxContextBudget,
+      minCohesion,
+      maxFragmentation,
+      circularDeps,
+    });
+
+    results.push({
+      file,
+      tokenCost: node.tokenCost,
+      linesOfCode: node.linesOfCode,
+      importDepth,
+      dependencyCount: dependencyList.length,
+      dependencyList,
+      circularDeps: circularDeps.filter((cycle) => cycle.includes(file)),
+      cohesionScore: adjustedCohesionScore,
+      domains,
+      exportCount: node.exports.length,
+      contextBudget,
+      fragmentationScore: adjustedFragmentationScore,
+      relatedFiles,
+      fileClassification,
+      severity: adjustedSeverity,
+      issues: adjustedIssues,
+      recommendations: [
+        ...finalRecommendations,
+        ...classificationRecommendations.slice(0, 1),
+      ],
+      potentialSavings: adjustedSavings,
+    });
+  }
+
+  const allResults = [...results, ...pythonResults];
+  const finalSummary = generateSummary(allResults, options);
+  return allResults.sort((a, b) => {
+    const severityOrder = { critical: 0, major: 1, minor: 2, info: 3 };
+    const severityDiff = severityOrder[a.severity] - severityOrder[b.severity];
+    if (severityDiff !== 0) return severityDiff;
+    return b.contextBudget - a.contextBudget;
+  });
+}