@aiready/context-analyzer 0.9.20 → 0.9.23

package/src/__tests__/file-classification.test.ts

@@ -0,0 +1,216 @@
+import { describe, it, expect } from 'vitest';
+import {
+  classifyFile,
+  adjustFragmentationForClassification,
+  getClassificationRecommendations,
+} from '../analyzer';
+import type { DependencyNode, FileClassification } from '../types';
+
+describe('file classification', () => {
+  const createNode = (overrides: Partial<DependencyNode>): DependencyNode => ({
+    file: 'test.ts',
+    imports: [],
+    exports: [],
+    tokenCost: 100,
+    linesOfCode: 50,
+    ...overrides,
+  });
+
+  describe('classifyFile', () => {
+    it('should classify barrel export files correctly', () => {
+      const node = createNode({
+        file: 'src/index.ts',
+        imports: ['../module1', '../module2', '../module3'],
+        exports: [
+          { name: 'func1', type: 'function', inferredDomain: 'module1' },
+          { name: 'func2', type: 'function', inferredDomain: 'module2' },
+          { name: 'func3', type: 'function', inferredDomain: 'module3' },
+        ],
+        linesOfCode: 20, // Sparse code
+      });
+
+      const classification = classifyFile(node, 0.5, ['module1', 'module2', 'module3']);
+      expect(classification).toBe('barrel-export');
+    });
+
+    it('should classify type definition files correctly', () => {
+      const node = createNode({
+        file: 'src/types.ts',
+        exports: [
+          { name: 'User', type: 'interface', inferredDomain: 'user' },
+          { name: 'Order', type: 'interface', inferredDomain: 'order' },
+          { name: 'Product', type: 'type', inferredDomain: 'product' },
+          { name: 'Status', type: 'type', inferredDomain: 'unknown' },
+        ],
+        linesOfCode: 100,
+      });
+
+      const classification = classifyFile(node, 0.5, ['user', 'order', 'product']);
+      expect(classification).toBe('type-definition');
+    });
+
+    it('should classify cohesive module files correctly', () => {
+      const node = createNode({
+        file: 'src/calculator.ts',
+        exports: [
+          { name: 'calculate', type: 'function', inferredDomain: 'calc' },
+          { name: 'format', type: 'function', inferredDomain: 'calc' },
+          { name: 'validate', type: 'function', inferredDomain: 'calc' },
+        ],
+        imports: ['../utils'],
+        linesOfCode: 300,
+      });
+
+      const classification = classifyFile(node, 0.8, ['calc']);
+      expect(classification).toBe('cohesive-module');
+    });
+
+    it('should classify mixed concerns files correctly', () => {
+      const node = createNode({
+        file: 'src/audit.ts',
+        exports: [
+          { name: 'auditStatus', type: 'function', inferredDomain: 'audit' },
+          { name: 'createJob', type: 'function', inferredDomain: 'job' },
+          { name: 'LineItem', type: 'interface', inferredDomain: 'order' },
+          { name: 'SupportingDoc', type: 'type', inferredDomain: 'doc' },
+        ],
+        imports: ['../auth', '../job', '../order'],
+        linesOfCode: 384,
+      });
+
+      const classification = classifyFile(node, 0.3, ['audit', 'job', 'order', 'doc']);
+      expect(classification).toBe('mixed-concerns');
+    });
+
+    it('should classify files with low cohesion as mixed-concerns', () => {
+      const node = createNode({
+        file: 'src/utils.ts',
+        exports: [
+          { name: 'formatDate', type: 'function', inferredDomain: 'date' },
+          { name: 'parseJSON', type: 'function', inferredDomain: 'json' },
+          { name: 'validateEmail', type: 'function', inferredDomain: 'email' },
+        ],
+        imports: [],
+        linesOfCode: 150,
+      });
+
+      const classification = classifyFile(node, 0.4, ['date', 'json', 'email']);
+      expect(classification).toBe('mixed-concerns');
+    });
+
+    it('should return unknown for files that do not fit other categories', () => {
+      const node = createNode({
+        file: 'src/component.ts',
+        exports: [
+          { name: 'Component', type: 'function', inferredDomain: 'ui' },
+        ],
+        imports: ['react'],
+        linesOfCode: 100,
+      });
+
+      // Medium cohesion (0.6), single domain - not quite cohesive-module (needs 0.7)
+      const classification = classifyFile(node, 0.6, ['ui']);
+      expect(classification).toBe('unknown');
+    });
+  });
+
+  describe('adjustFragmentationForClassification', () => {
+    it('should return 0 fragmentation for barrel exports', () => {
+      const result = adjustFragmentationForClassification(0.8, 'barrel-export');
+      expect(result).toBe(0);
+    });
+
+    it('should return 0 fragmentation for type definitions', () => {
+      const result = adjustFragmentationForClassification(0.9, 'type-definition');
+      expect(result).toBe(0);
+    });
+
+    it('should reduce fragmentation by 70% for cohesive modules', () => {
+      const result = adjustFragmentationForClassification(0.6, 'cohesive-module');
+      expect(result).toBeCloseTo(0.18, 2); // 0.6 * 0.3
+    });
+
+    it('should keep full fragmentation for mixed concerns', () => {
+      const result = adjustFragmentationForClassification(0.7, 'mixed-concerns');
+      expect(result).toBe(0.7);
+    });
+
+    it('should reduce fragmentation by 30% for unknown classification', () => {
+      const result = adjustFragmentationForClassification(0.5, 'unknown');
+      expect(result).toBeCloseTo(0.35, 2); // 0.5 * 0.7
+    });
+  });
+
+  describe('getClassificationRecommendations', () => {
+    it('should provide barrel export recommendations', () => {
+      const recommendations = getClassificationRecommendations(
+        'barrel-export',
+        'src/index.ts',
+        ['High fragmentation']
+      );
+      expect(recommendations).toContain('Barrel export file detected - multiple domains are expected here');
+    });
+
+    it('should provide type definition recommendations', () => {
+      const recommendations = getClassificationRecommendations(
+        'type-definition',
+        'src/types.ts',
+        ['High fragmentation']
+      );
+      expect(recommendations).toContain('Type definition file - centralized types improve consistency');
+    });
+
+    it('should provide cohesive module recommendations', () => {
+      const recommendations = getClassificationRecommendations(
+        'cohesive-module',
+        'src/calculator.ts',
+        []
+      );
+      expect(recommendations).toContain('Module has good cohesion despite its size');
+    });
+
+    it('should provide mixed concerns recommendations', () => {
+      const recommendations = getClassificationRecommendations(
+        'mixed-concerns',
+        'src/audit.ts',
+        ['Multiple domains detected']
+      );
+      expect(recommendations).toContain('Consider splitting this file by domain');
+    });
+  });
+
+  describe('integration: barrel export detection edge cases', () => {
+    it('should detect barrel export even for non-index files with re-export patterns', () => {
+      const node = createNode({
+        file: 'src/exports.ts',
+        imports: ['../module1', '../module2', '../module3', '../module4', '../module5'],
+        exports: [
+          { name: 'a', type: 'function' },
+          { name: 'b', type: 'function' },
+          { name: 'c', type: 'function' },
+          { name: 'd', type: 'function' },
+          { name: 'e', type: 'function' },
+        ],
+        linesOfCode: 25, // Very sparse - mostly re-exports
+      });
+
+      const classification = classifyFile(node, 0.5, ['module1', 'module2']);
+      expect(classification).toBe('barrel-export');
+    });
+
+    it('should not misclassify large component files as barrel exports', () => {
+      const node = createNode({
+        file: 'src/components/Calculator.tsx', // NOT an index file
+        imports: ['react', '../hooks', '../utils'],
+        exports: [
+          { name: 'Calculator', type: 'function' },
+        ],
+        linesOfCode: 346, // Substantial code
+      });
+
+      // Single domain, high cohesion
+      const classification = classifyFile(node, 0.9, ['calculator']);
+      expect(classification).toBe('cohesive-module');
+    });
+  });
+});

package/src/analyzer.ts

@@ -5,6 +5,7 @@ import type {
   DependencyNode,
   ExportInfo,
   ModuleCluster,
+  FileClassification,
 } from './types';
 import { buildCoUsageMatrix, buildTypeGraph, inferDomainFromSemantics } from './semantic-analysis';
 
@@ -901,3 +902,189 @@ function calculateDomainCohesion(exports: ExportInfo[]): number {
   const maxEntropy = Math.log2(total);
   return maxEntropy > 0 ? 1 - entropy / maxEntropy : 1;
 }
+
+/**
+ * Classify a file based on its characteristics to help distinguish
+ * real issues from false positives.
+ * 
+ * Classification types:
+ * - barrel-export: Re-exports from other modules (index.ts files)
+ * - type-definition: Primarily type/interface definitions
+ * - cohesive-module: Single domain, high cohesion (acceptable large files)
+ * - mixed-concerns: Multiple domains, potential refactoring candidate
+ * - unknown: Unable to classify
+ */
+export function classifyFile(
+  node: DependencyNode,
+  cohesionScore: number,
+  domains: string[]
+): FileClassification {
+  const { exports, imports, linesOfCode } = node;
+  
+  // 1. Check for barrel export (index file that re-exports)
+  if (isBarrelExport(node)) {
+    return 'barrel-export';
+  }
+  
+  // 2. Check for type definition file
+  if (isTypeDefinitionFile(node)) {
+    return 'type-definition';
+  }
+  
+  // 3. Check for cohesive module (single domain + high cohesion)
+  const uniqueDomains = domains.filter(d => d !== 'unknown');
+  const hasSingleDomain = uniqueDomains.length <= 1;
+  const hasHighCohesion = cohesionScore >= 0.7;
+  
+  if (hasSingleDomain && hasHighCohesion) {
+    return 'cohesive-module';
+  }
+  
+  // 4. Check for mixed concerns (multiple domains + low cohesion)
+  const hasMultipleDomains = uniqueDomains.length > 1;
+  const hasLowCohesion = cohesionScore < 0.5;
+  
+  if (hasMultipleDomains || hasLowCohesion) {
+    return 'mixed-concerns';
+  }
+  
+  return 'unknown';
+}
+
+/**
+ * Detect if a file is a barrel export (re-exports from other modules)
+ * 
+ * Characteristics of barrel exports:
+ * - Named "index.ts" or "index.js"
+ * - Many re-export statements (export * from, export { x } from)
+ * - Little to no actual implementation code
+ * - High export count relative to lines of code
+ */
+function isBarrelExport(node: DependencyNode): boolean {
+  const { file, exports, imports, linesOfCode } = node;
+  
+  // Check filename pattern
+  const fileName = file.split('/').pop()?.toLowerCase();
+  const isIndexFile = fileName === 'index.ts' || fileName === 'index.js' || 
+                      fileName === 'index.tsx' || fileName === 'index.jsx';
+  
+  // Calculate re-export ratio
+  // Re-exports typically have form: export { x } from 'module' or export * from 'module'
+  // They have imports AND exports, with exports coming from those imports
+  const hasReExports = exports.length > 0 && imports.length > 0;
+  const highExportToLinesRatio = exports.length > 3 && linesOfCode < exports.length * 5;
+  
+  // Little actual code (mostly import/export statements)
+  const sparseCode = linesOfCode > 0 && linesOfCode < 50 && exports.length >= 2;
+  
+  // Index files with re-export patterns
+  if (isIndexFile && hasReExports) {
+    return true;
+  }
+  
+  // Non-index files that are clearly barrel exports
+  if (highExportToLinesRatio && imports.length >= exports.length * 0.5) {
+    return true;
+  }
+  
+  // Very sparse files with multiple re-exports
+  if (sparseCode && imports.length > 0) {
+    return true;
+  }
+  
+  return false;
+}
+
+/**
+ * Detect if a file is primarily a type definition file
+ * 
+ * Characteristics:
+ * - Mostly type/interface exports
+ * - Little to no runtime code
+ * - Often named *.d.ts or types.ts
+ */
+function isTypeDefinitionFile(node: DependencyNode): boolean {
+  const { file, exports } = node;
+  
+  // Check filename pattern
+  const fileName = file.split('/').pop()?.toLowerCase();
+  const isTypesFile = fileName?.includes('types') || fileName?.includes('.d.ts') ||
+                      fileName === 'types.ts' || fileName === 'interfaces.ts';
+  
+  // Count type exports vs other exports
+  const typeExports = exports.filter(e => e.type === 'type' || e.type === 'interface');
+  const runtimeExports = exports.filter(e => e.type === 'function' || e.type === 'class' || e.type === 'const');
+  
+  // High ratio of type exports
+  const mostlyTypes = exports.length > 0 && 
+                      typeExports.length > runtimeExports.length &&
+                      typeExports.length / exports.length > 0.7;
+  
+  return isTypesFile || mostlyTypes;
+}
+
+/**
+ * Adjust fragmentation score based on file classification
+ * 
+ * This reduces false positives by:
+ * - Ignoring fragmentation for barrel exports (they're meant to aggregate)
+ * - Ignoring fragmentation for type definitions (centralized types are good)
+ * - Reducing fragmentation for cohesive modules (large but focused is OK)
+ */
+export function adjustFragmentationForClassification(
+  baseFragmentation: number,
+  classification: FileClassification
+): number {
+  switch (classification) {
+    case 'barrel-export':
+      // Barrel exports are meant to have multiple domains - no fragmentation
+      return 0;
+    case 'type-definition':
+      // Centralized type definitions are good practice - no fragmentation
+      return 0;
+    case 'cohesive-module':
+      // Cohesive modules get a significant discount
+      return baseFragmentation * 0.3;
+    case 'mixed-concerns':
+      // Mixed concerns keep full fragmentation score
+      return baseFragmentation;
+    default:
+      // Unknown gets a small discount (benefit of doubt)
+      return baseFragmentation * 0.7;
+  }
+}
+
+/**
+ * Get classification-specific recommendations
+ */
+export function getClassificationRecommendations(
+  classification: FileClassification,
+  file: string,
+  issues: string[]
+): string[] {
+  switch (classification) {
+    case 'barrel-export':
+      return [
+        'Barrel export file detected - multiple domains are expected here',
+        'Consider if this barrel export improves or hinders discoverability',
+      ];
+    case 'type-definition':
+      return [
+        'Type definition file - centralized types improve consistency',
+        'Consider splitting if file becomes too large (>500 lines)',
+      ];
+    case 'cohesive-module':
+      return [
+        'Module has good cohesion despite its size',
+        'Consider documenting the module boundaries for AI assistants',
+      ];
+    case 'mixed-concerns':
+      return [
+        'Consider splitting this file by domain',
+        'Identify independent responsibilities and extract them',
+        'Review import dependencies to understand coupling',
+      ];
+    default:
+      return issues;
+  }
+}

package/src/index.ts

@@ -11,6 +11,9 @@ import {
   detectModuleClusters,
   calculatePathEntropy,
   calculateDirectoryDistance,
+  classifyFile,
+  adjustFragmentationForClassification,
+  getClassificationRecommendations,
 } from './analyzer';
 import { calculateContextScore } from './scoring';
 import type {
@@ -22,6 +25,7 @@ import type {
   DomainSignals,
   CoUsageData,
   TypeDependency,
+  FileClassification,
 } from './types';
 import {
   buildCoUsageMatrix,
@@ -42,6 +46,12 @@ export type {
   DomainSignals,
   CoUsageData,
   TypeDependency,
+  FileClassification,
+};
+
+export {
+  classifyFile,
+  adjustFragmentationForClassification,
 };
 
 export {
@@ -196,6 +206,7 @@ export async function analyzeContext(
         contextBudget: metric.contextBudget,
         fragmentationScore: 0,
         relatedFiles: [],
+        fileClassification: 'unknown' as const, // Python files not yet classified
         severity,
         issues,
         recommendations,
@@ -275,6 +286,41 @@ export async function analyzeContext(
       ...new Set(node.exports.map((e) => e.inferredDomain || 'unknown')),
     ];
 
+    // Classify the file to help distinguish real issues from false positives
+    const fileClassification = classifyFile(node, cohesionScore, domains);
+    
+    // Adjust fragmentation based on classification
+    const adjustedFragmentationScore = adjustFragmentationForClassification(
+      fragmentationScore,
+      fileClassification
+    );
+
+    // Get classification-specific recommendations
+    const classificationRecommendations = getClassificationRecommendations(
+      fileClassification,
+      file,
+      issues
+    );
+
+    // Re-analyze issues with adjusted fragmentation
+    const {
+      severity: adjustedSeverity,
+      issues: adjustedIssues,
+      recommendations: finalRecommendations,
+      potentialSavings: adjustedSavings,
+    } = analyzeIssues({
+      file,
+      importDepth,
+      contextBudget,
+      cohesionScore,
+      fragmentationScore: adjustedFragmentationScore,
+      maxDepth,
+      maxContextBudget,
+      minCohesion,
+      maxFragmentation,
+      circularDeps,
+    });
+
     results.push({
       file,
       tokenCost: node.tokenCost,
@@ -287,12 +333,13 @@ export async function analyzeContext(
       domains,
       exportCount: node.exports.length,
       contextBudget,
-      fragmentationScore,
+      fragmentationScore: adjustedFragmentationScore,
       relatedFiles,
-      severity,
-      issues,
-      recommendations,
-      potentialSavings,
+      fileClassification,
+      severity: adjustedSeverity,
+      issues: adjustedIssues,
+      recommendations: [...finalRecommendations, ...classificationRecommendations.slice(0, 1)],
+      potentialSavings: adjustedSavings,
     });
   }
 

package/src/types.ts

@@ -32,6 +32,9 @@ export interface ContextAnalysisResult {
   fragmentationScore: number; // 0-1, how scattered is this domain (0 = well-grouped)
   relatedFiles: string[]; // Files that should be loaded together
 
+  // File classification (NEW)
+  fileClassification: FileClassification; // Type of file for analysis context
+
   // Recommendations
   severity: 'critical' | 'major' | 'minor' | 'info';
   issues: string[]; // List of specific problems
@@ -39,6 +42,17 @@ export interface ContextAnalysisResult {
   potentialSavings: number; // Estimated token savings if fixed
 }
 
+/**
+ * Classification of file type for analysis context
+ * Helps distinguish real issues from false positives
+ */
+export type FileClassification = 
+  | 'barrel-export'    // Re-exports from other modules (index.ts files)
+  | 'type-definition'  // Primarily type/interface definitions
+  | 'cohesive-module'  // Single domain, high cohesion (acceptable large files)
+  | 'mixed-concerns'   // Multiple domains, potential refactoring candidate
+  | 'unknown';         // Unable to classify
+
 export interface ModuleCluster {
   domain: string; // e.g., "user-management", "auth"
   files: string[];