@aiready/context-analyzer 0.21.13 → 0.21.15

package/dist/cli.js

@@ -923,7 +923,19 @@ var CONFIG_NAME_PATTERNS = [
   "next.config",
   "sst.config"
 ];
+function isBoilerplateBarrel(node) {
+  const { exports: exports2, tokenCost } = node;
+  if (!exports2 || exports2.length === 0) return false;
+  const isPurelyReexports = exports2.every((exp) => !!exp.source);
+  if (!isPurelyReexports) return false;
+  if (tokenCost > 500) return false;
+  const sources = new Set(exports2.map((exp) => exp.source));
+  const isSingleSourcePassThrough = sources.size === 1;
+  const isMeaninglessAggregation = sources.size > 0 && sources.size < 3;
+  return isSingleSourcePassThrough || isMeaninglessAggregation;
+}
 function isBarrelExport(node) {
+  if (isBoilerplateBarrel(node)) return false;
   const { file, exports: exports2 } = node;
   const fileName = file.split("/").pop()?.toLowerCase();
   const isIndexFile = fileName === "index.ts" || fileName === "index.js";
@@ -1054,6 +1066,7 @@ function isHubAndSpokeFile(node) {
 // src/classifier.ts
 var Classification = {
   BARREL: "barrel-export",
+  BOILERPLATE: "boilerplate-barrel",
   TYPE_DEFINITION: "type-definition",
   NEXTJS_PAGE: "nextjs-page",
   LAMBDA_HANDLER: "lambda-handler",
@@ -1067,6 +1080,9 @@ var Classification = {
   UNKNOWN: "unknown"
 };
 function classifyFile(node, cohesionScore = 1, domains = []) {
+  if (isBoilerplateBarrel(node)) {
+    return Classification.BOILERPLATE;
+  }
   if (isBarrelExport(node)) {
     return Classification.BARREL;
   }
@@ -1115,6 +1131,9 @@ function classifyFile(node, cohesionScore = 1, domains = []) {
 }
 function adjustCohesionForClassification(baseCohesion, classification, node) {
   switch (classification) {
+    case Classification.BOILERPLATE:
+      return 0.2;
+    // Redundant indirection is low cohesion (architectural theater)
     case Classification.BARREL:
       return 1;
     case Classification.TYPE_DEFINITION:
@@ -1190,6 +1209,9 @@ function hasRelatedExportNames(exportNames) {
 }
 function adjustFragmentationForClassification(baseFragmentation, classification) {
   switch (classification) {
+    case Classification.BOILERPLATE:
+      return baseFragmentation * 1.5;
+    // Redundant barrels increase fragmentation
     case Classification.BARREL:
       return 0;
     case Classification.TYPE_DEFINITION:
@@ -1298,6 +1320,12 @@ function detectModuleClusters(graph, options) {
 // src/remediation.ts
 function getClassificationRecommendations(classification, file, issues) {
   switch (classification) {
+    case "boilerplate-barrel":
+      return [
+        "Redundant indirection detected (architectural theater)",
+        "Remove this pass-through barrel export to reduce cognitive load",
+        "Consider combining into meaningful domain exports if necessary"
+      ];
     case "barrel-export":
       return [
         "Barrel export file detected - multiple domains are expected here",

package/dist/cli.mjs

@@ -5,7 +5,7 @@ import {
   generateHTMLReport,
   generateSummary,
   runInteractiveSetup
-} from "./chunk-CAX2MOUZ.mjs";
+} from "./chunk-BEZPBI5C.mjs";
 import "./chunk-64U3PNO3.mjs";
 
 // src/cli.ts

package/dist/index.d.mts

@@ -69,7 +69,7 @@ interface ContextAnalysisResult {
  * Classification of file type for analysis context
  * Helps distinguish real issues from false positives
  */
-type FileClassification = 'barrel-export' | 'type-definition' | 'cohesive-module' | 'utility-module' | 'service-file' | 'lambda-handler' | 'email-template' | 'parser-file' | 'nextjs-page' | 'spoke-module' | 'mixed-concerns' | 'unknown';
+type FileClassification = 'barrel-export' | 'boilerplate-barrel' | 'type-definition' | 'cohesive-module' | 'utility-module' | 'service-file' | 'lambda-handler' | 'email-template' | 'parser-file' | 'nextjs-page' | 'spoke-module' | 'mixed-concerns' | 'unknown';
 interface ModuleCluster {
     domain: string;
     files: string[];
@@ -292,6 +292,7 @@ declare function calculateDirectoryDistance(files: string[]): number;
  */
 declare const Classification: {
     BARREL: "barrel-export";
+    BOILERPLATE: "boilerplate-barrel";
     TYPE_DEFINITION: "type-definition";
     NEXTJS_PAGE: "nextjs-page";
     LAMBDA_HANDLER: "lambda-handler";

package/dist/index.d.ts

@@ -69,7 +69,7 @@ interface ContextAnalysisResult {
  * Classification of file type for analysis context
  * Helps distinguish real issues from false positives
  */
-type FileClassification = 'barrel-export' | 'type-definition' | 'cohesive-module' | 'utility-module' | 'service-file' | 'lambda-handler' | 'email-template' | 'parser-file' | 'nextjs-page' | 'spoke-module' | 'mixed-concerns' | 'unknown';
+type FileClassification = 'barrel-export' | 'boilerplate-barrel' | 'type-definition' | 'cohesive-module' | 'utility-module' | 'service-file' | 'lambda-handler' | 'email-template' | 'parser-file' | 'nextjs-page' | 'spoke-module' | 'mixed-concerns' | 'unknown';
 interface ModuleCluster {
     domain: string;
     files: string[];
@@ -292,6 +292,7 @@ declare function calculateDirectoryDistance(files: string[]): number;
  */
 declare const Classification: {
     BARREL: "barrel-export";
+    BOILERPLATE: "boilerplate-barrel";
     TYPE_DEFINITION: "type-definition";
     NEXTJS_PAGE: "nextjs-page";
     LAMBDA_HANDLER: "lambda-handler";

package/dist/index.js

@@ -1057,7 +1057,19 @@ var CONFIG_NAME_PATTERNS = [
   "next.config",
   "sst.config"
 ];
+function isBoilerplateBarrel(node) {
+  const { exports: exports2, tokenCost } = node;
+  if (!exports2 || exports2.length === 0) return false;
+  const isPurelyReexports = exports2.every((exp) => !!exp.source);
+  if (!isPurelyReexports) return false;
+  if (tokenCost > 500) return false;
+  const sources = new Set(exports2.map((exp) => exp.source));
+  const isSingleSourcePassThrough = sources.size === 1;
+  const isMeaninglessAggregation = sources.size > 0 && sources.size < 3;
+  return isSingleSourcePassThrough || isMeaninglessAggregation;
+}
 function isBarrelExport(node) {
+  if (isBoilerplateBarrel(node)) return false;
   const { file, exports: exports2 } = node;
   const fileName = file.split("/").pop()?.toLowerCase();
   const isIndexFile = fileName === "index.ts" || fileName === "index.js";
@@ -1188,6 +1200,7 @@ function isHubAndSpokeFile(node) {
 // src/classifier.ts
 var Classification = {
   BARREL: "barrel-export",
+  BOILERPLATE: "boilerplate-barrel",
   TYPE_DEFINITION: "type-definition",
   NEXTJS_PAGE: "nextjs-page",
   LAMBDA_HANDLER: "lambda-handler",
@@ -1201,6 +1214,9 @@ var Classification = {
   UNKNOWN: "unknown"
 };
 function classifyFile(node, cohesionScore = 1, domains = []) {
+  if (isBoilerplateBarrel(node)) {
+    return Classification.BOILERPLATE;
+  }
   if (isBarrelExport(node)) {
     return Classification.BARREL;
   }
@@ -1249,6 +1265,9 @@ function classifyFile(node, cohesionScore = 1, domains = []) {
 }
 function adjustCohesionForClassification(baseCohesion, classification, node) {
   switch (classification) {
+    case Classification.BOILERPLATE:
+      return 0.2;
+    // Redundant indirection is low cohesion (architectural theater)
     case Classification.BARREL:
       return 1;
     case Classification.TYPE_DEFINITION:
@@ -1324,6 +1343,9 @@ function hasRelatedExportNames(exportNames) {
 }
 function adjustFragmentationForClassification(baseFragmentation, classification) {
   switch (classification) {
+    case Classification.BOILERPLATE:
+      return baseFragmentation * 1.5;
+    // Redundant barrels increase fragmentation
     case Classification.BARREL:
       return 0;
     case Classification.TYPE_DEFINITION:
@@ -1432,6 +1454,12 @@ function detectModuleClusters(graph, options) {
 // src/remediation.ts
 function getClassificationRecommendations(classification, file, issues) {
   switch (classification) {
+    case "boilerplate-barrel":
+      return [
+        "Redundant indirection detected (architectural theater)",
+        "Remove this pass-through barrel export to reduce cognitive load",
+        "Consider combining into meaningful domain exports if necessary"
+      ];
     case "barrel-export":
       return [
         "Barrel export file detected - multiple domains are expected here",

package/dist/index.mjs

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiready/context-analyzer",
-  "version": "0.21.13",
+  "version": "0.21.15",
   "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.10"
+    "@aiready/core": "0.23.12"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",

package/src/__tests__/boilerplate-barrel.test.ts

@@ -0,0 +1,103 @@
+import { describe, it, expect } from 'vitest';
+import {
+  classifyFile,
+  adjustFragmentationForClassification,
+  adjustCohesionForClassification,
+  getClassificationRecommendations,
+} from '../index';
+import type { DependencyNode } from '../types';
+
+describe('boilerplate-barrel classification', () => {
+  const createNode = (overrides: Partial<DependencyNode>): DependencyNode => ({
+    file: 'test.ts',
+    imports: [],
+    exports: [],
+    tokenCost: 100,
+    linesOfCode: 50,
+    ...overrides,
+  });
+
+  it('should classify single source pass-through as boilerplate-barrel', () => {
+    const node = createNode({
+      file: 'core/lib/types/domains/agent-types.ts',
+      tokenCost: 50,
+      exports: [{ name: '*', type: 'all', source: '../agent' } as any],
+    });
+
+    const classification = classifyFile(node, 1.0, ['agent']);
+    expect(classification).toBe('boilerplate-barrel');
+  });
+
+  it('should classify meaningless aggregation (2 sources) as boilerplate-barrel', () => {
+    const node = createNode({
+      file: 'src/types/mini-barrel.ts',
+      tokenCost: 80,
+      exports: [
+        { name: 'User', type: 'type', source: './user' } as any,
+        { name: 'Profile', type: 'type', source: './profile' } as any,
+      ],
+    });
+
+    const classification = classifyFile(node, 1.0, ['user', 'profile']);
+    expect(classification).toBe('boilerplate-barrel');
+  });
+
+  it('should classify meaningful aggregation (5+ sources) as regular barrel-export', () => {
+    const node = createNode({
+      file: 'src/index.ts',
+      tokenCost: 150,
+      exports: [
+        { name: 'A', type: 'const', source: './a' } as any,
+        { name: 'B', type: 'const', source: './b' } as any,
+        { name: 'C', type: 'const', source: './c' } as any,
+        { name: 'D', type: 'const', source: './d' } as any,
+        { name: 'E', type: 'const', source: './e' } as any,
+      ],
+    });
+
+    const classification = classifyFile(node, 1.0, ['a', 'b', 'c', 'd', 'e']);
+    expect(classification).toBe('barrel-export');
+  });
+
+  it('should NOT classify barrel with local logic as boilerplate', () => {
+    const node = createNode({
+      file: 'src/mixed-barrel.ts',
+      tokenCost: 600, // Above limit
+      exports: [
+        { name: 'A', type: 'const', source: './a' } as any,
+        { name: 'localFunc', type: 'function' } as any,
+      ],
+    });
+
+    // Should default to something else, or if it matches barrel patterns but has local logic
+    const classification = classifyFile(node, 0.5, ['a', 'local']);
+    expect(classification).not.toBe('boilerplate-barrel');
+  });
+
+  it('should penalize boilerplate-barrel in cohesion adjustment', () => {
+    const result = adjustCohesionForClassification(1.0, 'boilerplate-barrel');
+    expect(result).toBe(0.2); // Low score for architectural theater
+  });
+
+  it('should increase fragmentation for boilerplate-barrel', () => {
+    const result = adjustFragmentationForClassification(
+      0.4,
+      'boilerplate-barrel'
+    );
+    expect(result).toBeCloseTo(0.6, 2); // 0.4 * 1.5
+  });
+
+  it('should provide specific recommendations for boilerplate-barrel', () => {
+    const recommendations = getClassificationRecommendations(
+      'boilerplate-barrel',
+      'types/domains/agent-types.ts',
+      []
+    );
+    expect(recommendations).toContain(
+      'Redundant indirection detected (architectural theater)'
+    );
+    expect(recommendations).toContain(
+      'Remove this pass-through barrel export to reduce cognitive load'
+    );
+  });
+});

package/src/classifier.ts

@@ -1,6 +1,7 @@
 import type { DependencyNode, FileClassification } from './types';
 import {
   isBarrelExport,
+  isBoilerplateBarrel,
   isTypeDefinition,
   isNextJsPage,
   isLambdaHandler,
@@ -18,6 +19,7 @@ import {
  */
 export const Classification = {
   BARREL: 'barrel-export' as const,
+  BOILERPLATE: 'boilerplate-barrel' as const,
   TYPE_DEFINITION: 'type-definition' as const,
   NEXTJS_PAGE: 'nextjs-page' as const,
   LAMBDA_HANDLER: 'lambda-handler' as const,
@@ -44,7 +46,12 @@ export function classifyFile(
   cohesionScore: number = 1,
   domains: string[] = []
 ): FileClassification {
-  // 1. Detect barrel exports (primarily re-exports)
+  // 1. Detect boilerplate barrels (pure indirection/architectural theater)
+  if (isBoilerplateBarrel(node)) {
+    return Classification.BOILERPLATE;
+  }
+
+  // 2. Detect legitimate barrel exports (primarily re-exports that aggregate)
   if (isBarrelExport(node)) {
     return Classification.BARREL;
   }
@@ -134,6 +141,8 @@ export function adjustCohesionForClassification(
   node?: DependencyNode
 ): number {
   switch (classification) {
+    case Classification.BOILERPLATE:
+      return 0.2; // Redundant indirection is low cohesion (architectural theater)
     case Classification.BARREL:
       return 1;
     case Classification.TYPE_DEFINITION:
@@ -235,6 +244,8 @@ export function adjustFragmentationForClassification(
   classification: FileClassification
 ): number {
   switch (classification) {
+    case Classification.BOILERPLATE:
+      return baseFragmentation * 1.5; // Redundant barrels increase fragmentation
     case Classification.BARREL:
       return 0;
     case Classification.TYPE_DEFINITION:

package/src/heuristics.ts

@@ -64,14 +64,48 @@ const CONFIG_NAME_PATTERNS = [
   'sst.config',
 ];
 
+/**
+ * Detect if a file is a boilerplate barrel (architectural theater).
+ * A boilerplate barrel re-exports from other sources without adding value.
+ *
+ * @param node - The dependency node to analyze.
+ * @returns True if the file matches boilerplate barrel patterns.
+ */
+export function isBoilerplateBarrel(node: DependencyNode): boolean {
+  const { exports, tokenCost } = node;
+  if (!exports || exports.length === 0) return false;
+
+  // 1. Must be purely re-exports
+  const isPurelyReexports = exports.every((exp: any) => !!exp.source);
+  if (!isPurelyReexports) return false;
+
+  // 2. Must be low local token cost (no actual logic)
+  if (tokenCost > 500) return false;
+
+  // 3. Detect "Architectural Theater"
+  // If it re-exports everything from exactly ONE source, it's a pass-through
+  const sources = new Set(exports.map((exp: any) => exp.source));
+
+  // Pattern: export * from '../actual'
+  const isSingleSourcePassThrough = sources.size === 1;
+
+  // Pattern: multi-file 1-to-1 re-exports that don't aggregate much
+  // (e.g., 6 files each re-exporting from exactly one other file)
+  const isMeaninglessAggregation = sources.size > 0 && sources.size < 3;
+
+  return isSingleSourcePassThrough || isMeaninglessAggregation;
+}
+
 /**
  * Detect if a file is a barrel export (index.ts).
  *
  * @param node - The dependency node to analyze.
  * @returns True if the file matches barrel export patterns.
- * @lastUpdated 2026-03-18
+ * @lastUpdated 2026-03-20
  */
 export function isBarrelExport(node: DependencyNode): boolean {
+  if (isBoilerplateBarrel(node)) return false; // Already handled by more specific check
+
   const { file, exports } = node;
   const fileName = file.split('/').pop()?.toLowerCase();
 

package/src/remediation.ts

@@ -14,6 +14,12 @@ export function getClassificationRecommendations(
   issues: string[]
 ): string[] {
   switch (classification) {
+    case 'boilerplate-barrel':
+      return [
+        'Redundant indirection detected (architectural theater)',
+        'Remove this pass-through barrel export to reduce cognitive load',
+        'Consider combining into meaningful domain exports if necessary',
+      ];
     case 'barrel-export':
       return [
         'Barrel export file detected - multiple domains are expected here',

package/src/types.ts

@@ -80,6 +80,7 @@ export interface ContextAnalysisResult {
  */
 export type FileClassification =
   | 'barrel-export' // Re-exports from other modules (index.ts files)
+  | 'boilerplate-barrel' // Redundant barrel file with no added value (architectural theater)
   | 'type-definition' // Primarily type/interface definitions
   | 'cohesive-module' // Single domain, high cohesion (acceptable large files)
   | 'utility-module' // Utility/helper files with cohesive purpose despite multi-domain