@aiready/context-analyzer 0.9.22 → 0.9.25

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

@@ -0,0 +1,251 @@
+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 multiple domains and very low cohesion as mixed-concerns', () => {
+      const node = createNode({
+        file: 'src/services/mixed-service.ts', // NOT a utility/config path
+        exports: [
+          { name: 'DateFormatter', type: 'class', inferredDomain: 'date' }, // Use class to avoid utility detection
+          { name: 'JSONParser', type: 'class', inferredDomain: 'json' },
+          { name: 'EmailValidator', type: 'class', inferredDomain: 'email' },
+        ],
+        imports: [],
+        linesOfCode: 150,
+      });
+
+      // Multiple domains + very low cohesion (< 0.4) = mixed concerns
+      // Note: NOT in /utils/ or /helpers/ path, uses classes (not just functions/consts)
+      const classification = classifyFile(node, 0.3, ['date', 'json', 'email']);
+      expect(classification).toBe('mixed-concerns');
+    });
+
+    it('should classify single domain files as cohesive-module regardless of cohesion', () => {
+      const node = createNode({
+        file: 'src/component.ts',
+        exports: [
+          { name: 'Component', type: 'function', inferredDomain: 'ui' },
+        ],
+        imports: ['react'],
+        linesOfCode: 100,
+      });
+
+      // Single domain = cohesive module (even with medium cohesion)
+      const classification = classifyFile(node, 0.6, ['ui']);
+      expect(classification).toBe('cohesive-module');
+    });
+
+    it('should classify utility files as cohesive-module by design', () => {
+      const node = createNode({
+        file: 'src/utils/helpers.ts',
+        exports: [
+          { name: 'formatDate', type: 'function', inferredDomain: 'date' },
+          { name: 'parseJSON', type: 'function', inferredDomain: 'json' },
+          { name: 'validateEmail', type: 'function', inferredDomain: 'email' },
+        ],
+        imports: [],
+        linesOfCode: 150,
+      });
+
+      // Utility files are classified as cohesive by design
+      const classification = classifyFile(node, 0.4, ['date', 'json', 'email']);
+      expect(classification).toBe('cohesive-module');
+    });
+
+    it('should classify config/schema files as cohesive-module', () => {
+      const node = createNode({
+        file: 'src/db-schema.ts',
+        exports: [
+          { name: 'userTable', type: 'const', inferredDomain: 'db' },
+          { name: 'userSchema', type: 'const', inferredDomain: 'schema' },
+        ],
+        imports: ['../db'],
+        linesOfCode: 81,
+      });
+
+      // Config/schema files are classified as cohesive
+      const classification = classifyFile(node, 0.4, ['db', 'schema']);
+      expect(classification).toBe('cohesive-module');
+    });
+  });
+
+  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,283 @@ 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, file } = 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 config/schema file (special case - acceptable multi-domain)
+  if (isConfigOrSchemaFile(node)) {
+    return 'cohesive-module'; // Treat as cohesive since it's intentional
+  }
+  
+  // 4. Check for cohesive module (single domain + reasonable cohesion)
+  const uniqueDomains = domains.filter(d => d !== 'unknown');
+  const hasSingleDomain = uniqueDomains.length <= 1;
+  const hasReasonableCohesion = cohesionScore >= 0.5; // Lowered threshold
+  
+  // Single domain files are almost always cohesive (even with lower cohesion score)
+  if (hasSingleDomain) {
+    return 'cohesive-module';
+  }
+  
+  // 5. Check for utility file pattern (multiple domains but utility purpose)
+  if (isUtilityFile(node)) {
+    return 'cohesive-module'; // Utilities often have mixed imports by design
+  }
+  
+  // 6. Check for mixed concerns (multiple domains + low cohesion)
+  const hasMultipleDomains = uniqueDomains.length > 1;
+  const hasLowCohesion = cohesionScore < 0.4; // Lowered threshold
+  
+  if (hasMultipleDomains && hasLowCohesion) {
+    return 'mixed-concerns';
+  }
+  
+  // 7. Default to cohesive-module for files with reasonable cohesion
+  // This reduces false positives for legitimate files
+  if (cohesionScore >= 0.5) {
+    return 'cohesive-module';
+  }
+  
+  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;
+}
+
+/**
+ * Detect if a file is a config/schema file
+ * 
+ * Characteristics:
+ * - Named with config, schema, or settings patterns
+ * - Often defines database schemas, configuration objects
+ * - Multiple domains are acceptable (centralized config)
+ */
+function isConfigOrSchemaFile(node: DependencyNode): boolean {
+  const { file, exports } = node;
+  
+  const fileName = file.split('/').pop()?.toLowerCase();
+  
+  // Check filename patterns for config/schema files
+  const configPatterns = [
+    'config', 'schema', 'settings', 'options', 'constants',
+    'env', 'environment', '.config.', '-config.', '_config.',
+  ];
+  
+  const isConfigName = configPatterns.some(pattern => 
+    fileName?.includes(pattern) || fileName?.startsWith(pattern) || fileName?.endsWith(`${pattern}.ts`)
+  );
+  
+  // Check if file is in a config/settings directory
+  const isConfigPath = file.toLowerCase().includes('/config/') || 
+                       file.toLowerCase().includes('/schemas/') ||
+                       file.toLowerCase().includes('/settings/');
+  
+  // Check for schema-like exports (often have table/model definitions)
+  const hasSchemaExports = exports.some(e => 
+    e.name.toLowerCase().includes('table') ||
+    e.name.toLowerCase().includes('schema') ||
+    e.name.toLowerCase().includes('config') ||
+    e.name.toLowerCase().includes('setting')
+  );
+  
+  return isConfigName || isConfigPath || hasSchemaExports;
+}
+
+/**
+ * Detect if a file is a utility/helper file
+ * 
+ * Characteristics:
+ * - Named with util, helper, or utility patterns
+ * - Often contains mixed helper functions by design
+ * - Multiple domains are acceptable (utility purpose)
+ */
+function isUtilityFile(node: DependencyNode): boolean {
+  const { file, exports } = node;
+  
+  const fileName = file.split('/').pop()?.toLowerCase();
+  
+  // Check filename patterns for utility files
+  const utilityPatterns = [
+    'util', 'utility', 'utilities', 'helper', 'helpers',
+    'common', 'shared', 'lib', 'toolbox', 'toolkit',
+    '.util.', '-util.', '_util.',
+  ];
+  
+  const isUtilityName = utilityPatterns.some(pattern => 
+    fileName?.includes(pattern)
+  );
+  
+  // Check if file is in a utils/helpers directory
+  const isUtilityPath = file.toLowerCase().includes('/utils/') || 
+                        file.toLowerCase().includes('/helpers/') ||
+                        file.toLowerCase().includes('/lib/') ||
+                        file.toLowerCase().includes('/common/');
+  
+  // Check if file has many small utility-like exports
+  const hasManySmallExports = exports.length >= 3 && exports.every(e => 
+    e.type === 'function' || e.type === 'const'
+  );
+  
+  return isUtilityName || isUtilityPath || hasManySmallExports;
+}
+
+/**
+ * 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[];