@aiready/context-analyzer 0.21.10 → 0.21.12

package/dist/index.mjs

@@ -32,7 +32,7 @@ import {
   inferDomain,
   inferDomainFromSemantics,
   runInteractiveSetup
-} from "./chunk-D25B5LZR.mjs";
+} from "./chunk-CAX2MOUZ.mjs";
 import "./chunk-64U3PNO3.mjs";
 
 // src/index.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiready/context-analyzer",
-  "version": "0.21.10",
+  "version": "0.21.12",
   "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.23.7"
+    "@aiready/core": "0.23.9"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",

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

@@ -89,14 +89,11 @@ describe('Cluster Detector', () => {
     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'
-    );
+    // fragmentation is reduced because files share imports (coupling discount)
+    // and are classified as cohesive modules (single domain 'auth')
+    // Final score: ~0.24 (raw 1.0 * 0.8 coupling discount * 0.3 cohesive multiplier)
+    expect(clusters[0].fragmentationScore).toBeLessThan(0.5);
+    expect(clusters[0].suggestedStructure.consolidationPlan.length).toBe(0); // No consolidation needed when fragmentation is low
   });
 
   it('should suggest boundary improvements for large domains', () => {

package/src/__tests__/fragmentation-coupling.test.ts

@@ -31,8 +31,11 @@ describe('fragmentation coupling discount', () => {
       files.map((f) => f.file),
       'billing'
     );
-    // With no import similarity the coupling discount should be 0 -> fragmentation unchanged
-    expect(cluster!.fragmentationScore).toBeCloseTo(base, 6);
+    // Adjusted fragmentation includes classification multiplier (0.3 for COHESIVE_MODULE)
+    const expected = base * 0.3;
+
+    // Allow small FP tolerance
+    expect(cluster!.fragmentationScore).toBeCloseTo(expected, 6);
   });
 
   it('applies up-to-20% discount when files share identical imports', () => {
@@ -60,7 +63,7 @@ describe('fragmentation coupling discount', () => {
       files.map((f) => f.file),
       'billing'
     );
-    const expected = base * 0.8; // full cohesion => 20% discount
+    const expected = base * 0.8 * 0.3; // full cohesion => 20% discount AND 0.3 classification multiplier
 
     // Allow small FP tolerance
     expect(cluster!.fragmentationScore).toBeCloseTo(expected, 6);

package/src/analyzer.ts

@@ -1,224 +1 @@
-import { scanFiles, readFileContent } from '@aiready/core';
-import type {
-  ExportInfo,
-  ContextAnalysisResult,
-  ContextAnalyzerOptions,
-  FileClassification,
-} from './types';
-import { calculateEnhancedCohesion } from './metrics';
-import { analyzeIssues } from './issue-analyzer';
-
-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).
- * 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: ExportInfo[],
-  filePath?: string,
-  options?: any
-): number {
-  return calculateEnhancedCohesion(exports, filePath, options);
-}
-
-/**
- * Analyze AI context window cost for a codebase
- */
-/**
- * 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, // Not provided by python context yet
-        importDepth: metric.importDepth,
-        dependencyCount: 0, // Not provided
-        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) => {
-      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,
-          maxContextBudget,
-          minCohesion,
-          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,
-      };
-    }
-  );
-
-  return [...results, ...pythonResults];
-}
+export * from './orchestrator';

package/src/classifier.ts

@@ -10,6 +10,7 @@ import {
   isSessionFile,
   isUtilityModule,
   isConfigFile,
+  isHubAndSpokeFile,
 } from './heuristics';
 
 /**
@@ -25,6 +26,7 @@ export const Classification = {
   PARSER: 'parser-file' as const,
   COHESIVE_MODULE: 'cohesive-module' as const,
   UTILITY_MODULE: 'utility-module' as const,
+  SPOKE_MODULE: 'spoke-module' as const,
   MIXED_CONCERNS: 'mixed-concerns' as const,
   UNKNOWN: 'unknown' as const,
 };
@@ -95,6 +97,11 @@ export function classifyFile(
     return Classification.COHESIVE_MODULE;
   }
 
+  // 11. Detect Spoke modules in monorepo
+  if (isHubAndSpokeFile(node)) {
+    return Classification.SPOKE_MODULE;
+  }
+
   // Cohesion and Domain heuristics
   if (domains.length <= 1 && domains[0] !== 'unknown') {
     return Classification.COHESIVE_MODULE;
@@ -152,6 +159,8 @@ export function adjustCohesionForClassification(
       return Math.max(0.72, Math.min(1, baseCohesion + 0.3));
     case Classification.PARSER:
       return Math.max(0.7, Math.min(1, baseCohesion + 0.3));
+    case Classification.SPOKE_MODULE:
+      return Math.max(baseCohesion, 0.6);
     case Classification.COHESIVE_MODULE:
       return Math.max(baseCohesion, 0.7);
     case Classification.MIXED_CONCERNS:
@@ -237,6 +246,8 @@ export function adjustFragmentationForClassification(
     case Classification.PARSER:
     case Classification.NEXTJS_PAGE:
       return baseFragmentation * 0.2;
+    case Classification.SPOKE_MODULE:
+      return baseFragmentation * 0.15; // Heavily discount intentional monorepo separation
     case Classification.COHESIVE_MODULE:
       return baseFragmentation * 0.3;
     case Classification.MIXED_CONCERNS:

package/src/cluster-detector.ts

@@ -1,5 +1,9 @@
 import type { DependencyGraph, ModuleCluster } from './types';
 import { calculateFragmentation, calculateEnhancedCohesion } from './metrics';
+import {
+  classifyFile,
+  adjustFragmentationForClassification,
+} from './classifier';
 
 /**
  * Group files by domain to detect module clusters
@@ -73,29 +77,42 @@ export function detectModuleClusters(
       sharedImportRatio = union.size > 0 ? intersection.size / union.size : 0;
     }
 
-    const fragmentation = calculateFragmentation(files, domain, {
+    const rawFragmentation = calculateFragmentation(files, domain, {
       ...options,
       sharedImportRatio,
     });
 
-    // Average cohesion for the cluster
+    // Average cohesion and adjusted fragmentation for the cluster
     let totalCohesion = 0;
+    let totalAdjustedFragmentation = 0;
+
     files.forEach((f) => {
       const node = graph.nodes.get(f);
-      if (node) totalCohesion += calculateEnhancedCohesion(node.exports);
+      if (node) {
+        const cohesion = calculateEnhancedCohesion(node.exports);
+        totalCohesion += cohesion;
+
+        const classification = classifyFile(node, cohesion);
+        totalAdjustedFragmentation += adjustFragmentationForClassification(
+          rawFragmentation,
+          classification
+        );
+      }
     });
+
     const avgCohesion = totalCohesion / files.length;
+    const fragmentationScore = totalAdjustedFragmentation / files.length;
 
     clusters.push({
       domain,
       files,
       totalTokens,
-      fragmentationScore: fragmentation,
+      fragmentationScore,
       avgCohesion,
       suggestedStructure: generateSuggestedStructure(
         files,
         totalTokens,
-        fragmentation
+        fragmentationScore
       ),
     });
   }