@aiready/context-analyzer 0.9.22 → 0.9.25

package/dist/cli.js

@@ -890,6 +890,155 @@ function calculateDomainCohesion(exports2) {
   const maxEntropy = Math.log2(total);
   return maxEntropy > 0 ? 1 - entropy / maxEntropy : 1;
 }
+function classifyFile(node, cohesionScore, domains) {
+  const { exports: exports2, imports, linesOfCode, file } = node;
+  if (isBarrelExport(node)) {
+    return "barrel-export";
+  }
+  if (isTypeDefinitionFile(node)) {
+    return "type-definition";
+  }
+  if (isConfigOrSchemaFile(node)) {
+    return "cohesive-module";
+  }
+  const uniqueDomains = domains.filter((d) => d !== "unknown");
+  const hasSingleDomain = uniqueDomains.length <= 1;
+  const hasReasonableCohesion = cohesionScore >= 0.5;
+  if (hasSingleDomain) {
+    return "cohesive-module";
+  }
+  if (isUtilityFile(node)) {
+    return "cohesive-module";
+  }
+  const hasMultipleDomains = uniqueDomains.length > 1;
+  const hasLowCohesion = cohesionScore < 0.4;
+  if (hasMultipleDomains && hasLowCohesion) {
+    return "mixed-concerns";
+  }
+  if (cohesionScore >= 0.5) {
+    return "cohesive-module";
+  }
+  return "unknown";
+}
+function isBarrelExport(node) {
+  const { file, exports: exports2, imports, linesOfCode } = node;
+  const fileName = file.split("/").pop()?.toLowerCase();
+  const isIndexFile = fileName === "index.ts" || fileName === "index.js" || fileName === "index.tsx" || fileName === "index.jsx";
+  const hasReExports = exports2.length > 0 && imports.length > 0;
+  const highExportToLinesRatio = exports2.length > 3 && linesOfCode < exports2.length * 5;
+  const sparseCode = linesOfCode > 0 && linesOfCode < 50 && exports2.length >= 2;
+  if (isIndexFile && hasReExports) {
+    return true;
+  }
+  if (highExportToLinesRatio && imports.length >= exports2.length * 0.5) {
+    return true;
+  }
+  if (sparseCode && imports.length > 0) {
+    return true;
+  }
+  return false;
+}
+function isTypeDefinitionFile(node) {
+  const { file, exports: exports2 } = node;
+  const fileName = file.split("/").pop()?.toLowerCase();
+  const isTypesFile = fileName?.includes("types") || fileName?.includes(".d.ts") || fileName === "types.ts" || fileName === "interfaces.ts";
+  const typeExports = exports2.filter((e) => e.type === "type" || e.type === "interface");
+  const runtimeExports = exports2.filter((e) => e.type === "function" || e.type === "class" || e.type === "const");
+  const mostlyTypes = exports2.length > 0 && typeExports.length > runtimeExports.length && typeExports.length / exports2.length > 0.7;
+  return isTypesFile || mostlyTypes;
+}
+function isConfigOrSchemaFile(node) {
+  const { file, exports: exports2 } = node;
+  const fileName = file.split("/").pop()?.toLowerCase();
+  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`)
+  );
+  const isConfigPath = file.toLowerCase().includes("/config/") || file.toLowerCase().includes("/schemas/") || file.toLowerCase().includes("/settings/");
+  const hasSchemaExports = exports2.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;
+}
+function isUtilityFile(node) {
+  const { file, exports: exports2 } = node;
+  const fileName = file.split("/").pop()?.toLowerCase();
+  const utilityPatterns = [
+    "util",
+    "utility",
+    "utilities",
+    "helper",
+    "helpers",
+    "common",
+    "shared",
+    "lib",
+    "toolbox",
+    "toolkit",
+    ".util.",
+    "-util.",
+    "_util."
+  ];
+  const isUtilityName = utilityPatterns.some(
+    (pattern) => fileName?.includes(pattern)
+  );
+  const isUtilityPath = file.toLowerCase().includes("/utils/") || file.toLowerCase().includes("/helpers/") || file.toLowerCase().includes("/lib/") || file.toLowerCase().includes("/common/");
+  const hasManySmallExports = exports2.length >= 3 && exports2.every(
+    (e) => e.type === "function" || e.type === "const"
+  );
+  return isUtilityName || isUtilityPath || hasManySmallExports;
+}
+function adjustFragmentationForClassification(baseFragmentation, classification) {
+  switch (classification) {
+    case "barrel-export":
+      return 0;
+    case "type-definition":
+      return 0;
+    case "cohesive-module":
+      return baseFragmentation * 0.3;
+    case "mixed-concerns":
+      return baseFragmentation;
+    default:
+      return baseFragmentation * 0.7;
+  }
+}
+function getClassificationRecommendations(classification, file, issues) {
+  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;
+  }
+}
 
 // src/index.ts
 async function analyzeContext(options) {
@@ -952,6 +1101,8 @@ async function analyzeContext(options) {
         contextBudget: metric.contextBudget,
         fragmentationScore: 0,
         relatedFiles: [],
+        fileClassification: "unknown",
+        // Python files not yet classified
         severity,
         issues,
         recommendations,
@@ -999,6 +1150,33 @@ async function analyzeContext(options) {
     const domains = [
       ...new Set(node.exports.map((e) => e.inferredDomain || "unknown"))
     ];
+    const fileClassification = classifyFile(node, cohesionScore, domains);
+    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,
+      fragmentationScore: adjustedFragmentationScore,
+      maxDepth,
+      maxContextBudget,
+      minCohesion,
+      maxFragmentation,
+      circularDeps
+    });
     results.push({
       file,
       tokenCost: node.tokenCost,
@@ -1011,12 +1189,13 @@ async function analyzeContext(options) {
       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
     });
   }
   const allResults = [...results, ...pythonResults];

package/dist/cli.mjs

@@ -2,7 +2,7 @@
 import {
   analyzeContext,
   generateSummary
-} from "./chunk-VTALAPQZ.mjs";
+} from "./chunk-HOUDVRG2.mjs";
 import "./chunk-Y6FXYEAI.mjs";
 
 // src/cli.ts

package/dist/index.d.mts

@@ -22,11 +22,17 @@ interface ContextAnalysisResult {
     contextBudget: number;
     fragmentationScore: number;
     relatedFiles: string[];
+    fileClassification: FileClassification;
     severity: 'critical' | 'major' | 'minor' | 'info';
     issues: string[];
     recommendations: string[];
     potentialSavings: number;
 }
+/**
+ * Classification of file type for analysis context
+ * Helps distinguish real issues from false positives
+ */
+type FileClassification = 'barrel-export' | 'type-definition' | 'cohesive-module' | 'mixed-concerns' | 'unknown';
 interface ModuleCluster {
     domain: string;
     files: string[];
@@ -116,6 +122,28 @@ interface TypeDependency {
     usedBy: string[];
 }
 
+/**
+ * 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
+ */
+declare function classifyFile(node: DependencyNode, cohesionScore: number, domains: string[]): FileClassification;
+/**
+ * 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)
+ */
+declare function adjustFragmentationForClassification(baseFragmentation: number, classification: FileClassification): number;
+
 /**
  * Calculate AI Readiness Score for context efficiency (0-100)
  *
@@ -184,4 +212,4 @@ declare function analyzeContext(options: ContextAnalyzerOptions): Promise<Contex
  */
 declare function generateSummary(results: ContextAnalysisResult[]): ContextSummary;
 
-export { type CoUsageData, type ContextAnalysisResult, type ContextAnalyzerOptions, type ContextSummary, type DomainAssignment, type DomainSignals, type ModuleCluster, type TypeDependency, analyzeContext, buildCoUsageMatrix, buildTypeGraph, calculateContextScore, calculateDomainConfidence, findConsolidationCandidates, findSemanticClusters, generateSummary, getCoUsageData, getSmartDefaults, inferDomainFromSemantics };
+export { type CoUsageData, type ContextAnalysisResult, type ContextAnalyzerOptions, type ContextSummary, type DomainAssignment, type DomainSignals, type FileClassification, type ModuleCluster, type TypeDependency, adjustFragmentationForClassification, analyzeContext, buildCoUsageMatrix, buildTypeGraph, calculateContextScore, calculateDomainConfidence, classifyFile, findConsolidationCandidates, findSemanticClusters, generateSummary, getCoUsageData, getSmartDefaults, inferDomainFromSemantics };

package/dist/index.d.ts

@@ -22,11 +22,17 @@ interface ContextAnalysisResult {
     contextBudget: number;
     fragmentationScore: number;
     relatedFiles: string[];
+    fileClassification: FileClassification;
     severity: 'critical' | 'major' | 'minor' | 'info';
     issues: string[];
     recommendations: string[];
     potentialSavings: number;
 }
+/**
+ * Classification of file type for analysis context
+ * Helps distinguish real issues from false positives
+ */
+type FileClassification = 'barrel-export' | 'type-definition' | 'cohesive-module' | 'mixed-concerns' | 'unknown';
 interface ModuleCluster {
     domain: string;
     files: string[];
@@ -116,6 +122,28 @@ interface TypeDependency {
     usedBy: string[];
 }
 
+/**
+ * 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
+ */
+declare function classifyFile(node: DependencyNode, cohesionScore: number, domains: string[]): FileClassification;
+/**
+ * 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)
+ */
+declare function adjustFragmentationForClassification(baseFragmentation: number, classification: FileClassification): number;
+
 /**
  * Calculate AI Readiness Score for context efficiency (0-100)
  *
@@ -184,4 +212,4 @@ declare function analyzeContext(options: ContextAnalyzerOptions): Promise<Contex
  */
 declare function generateSummary(results: ContextAnalysisResult[]): ContextSummary;
 
-export { type CoUsageData, type ContextAnalysisResult, type ContextAnalyzerOptions, type ContextSummary, type DomainAssignment, type DomainSignals, type ModuleCluster, type TypeDependency, analyzeContext, buildCoUsageMatrix, buildTypeGraph, calculateContextScore, calculateDomainConfidence, findConsolidationCandidates, findSemanticClusters, generateSummary, getCoUsageData, getSmartDefaults, inferDomainFromSemantics };
+export { type CoUsageData, type ContextAnalysisResult, type ContextAnalyzerOptions, type ContextSummary, type DomainAssignment, type DomainSignals, type FileClassification, type ModuleCluster, type TypeDependency, adjustFragmentationForClassification, analyzeContext, buildCoUsageMatrix, buildTypeGraph, calculateContextScore, calculateDomainConfidence, classifyFile, findConsolidationCandidates, findSemanticClusters, generateSummary, getCoUsageData, getSmartDefaults, inferDomainFromSemantics };

package/dist/index.js

@@ -229,11 +229,13 @@ var init_python_context = __esm({
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  adjustFragmentationForClassification: () => adjustFragmentationForClassification,
   analyzeContext: () => analyzeContext,
   buildCoUsageMatrix: () => buildCoUsageMatrix,
   buildTypeGraph: () => buildTypeGraph,
   calculateContextScore: () => calculateContextScore,
   calculateDomainConfidence: () => calculateDomainConfidence,
+  classifyFile: () => classifyFile,
   findConsolidationCandidates: () => findConsolidationCandidates,
   findSemanticClusters: () => findSemanticClusters,
   generateSummary: () => generateSummary,
@@ -963,6 +965,155 @@ function calculateDomainCohesion(exports2) {
   const maxEntropy = Math.log2(total);
   return maxEntropy > 0 ? 1 - entropy / maxEntropy : 1;
 }
+function classifyFile(node, cohesionScore, domains) {
+  const { exports: exports2, imports, linesOfCode, file } = node;
+  if (isBarrelExport(node)) {
+    return "barrel-export";
+  }
+  if (isTypeDefinitionFile(node)) {
+    return "type-definition";
+  }
+  if (isConfigOrSchemaFile(node)) {
+    return "cohesive-module";
+  }
+  const uniqueDomains = domains.filter((d) => d !== "unknown");
+  const hasSingleDomain = uniqueDomains.length <= 1;
+  const hasReasonableCohesion = cohesionScore >= 0.5;
+  if (hasSingleDomain) {
+    return "cohesive-module";
+  }
+  if (isUtilityFile(node)) {
+    return "cohesive-module";
+  }
+  const hasMultipleDomains = uniqueDomains.length > 1;
+  const hasLowCohesion = cohesionScore < 0.4;
+  if (hasMultipleDomains && hasLowCohesion) {
+    return "mixed-concerns";
+  }
+  if (cohesionScore >= 0.5) {
+    return "cohesive-module";
+  }
+  return "unknown";
+}
+function isBarrelExport(node) {
+  const { file, exports: exports2, imports, linesOfCode } = node;
+  const fileName = file.split("/").pop()?.toLowerCase();
+  const isIndexFile = fileName === "index.ts" || fileName === "index.js" || fileName === "index.tsx" || fileName === "index.jsx";
+  const hasReExports = exports2.length > 0 && imports.length > 0;
+  const highExportToLinesRatio = exports2.length > 3 && linesOfCode < exports2.length * 5;
+  const sparseCode = linesOfCode > 0 && linesOfCode < 50 && exports2.length >= 2;
+  if (isIndexFile && hasReExports) {
+    return true;
+  }
+  if (highExportToLinesRatio && imports.length >= exports2.length * 0.5) {
+    return true;
+  }
+  if (sparseCode && imports.length > 0) {
+    return true;
+  }
+  return false;
+}
+function isTypeDefinitionFile(node) {
+  const { file, exports: exports2 } = node;
+  const fileName = file.split("/").pop()?.toLowerCase();
+  const isTypesFile = fileName?.includes("types") || fileName?.includes(".d.ts") || fileName === "types.ts" || fileName === "interfaces.ts";
+  const typeExports = exports2.filter((e) => e.type === "type" || e.type === "interface");
+  const runtimeExports = exports2.filter((e) => e.type === "function" || e.type === "class" || e.type === "const");
+  const mostlyTypes = exports2.length > 0 && typeExports.length > runtimeExports.length && typeExports.length / exports2.length > 0.7;
+  return isTypesFile || mostlyTypes;
+}
+function isConfigOrSchemaFile(node) {
+  const { file, exports: exports2 } = node;
+  const fileName = file.split("/").pop()?.toLowerCase();
+  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`)
+  );
+  const isConfigPath = file.toLowerCase().includes("/config/") || file.toLowerCase().includes("/schemas/") || file.toLowerCase().includes("/settings/");
+  const hasSchemaExports = exports2.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;
+}
+function isUtilityFile(node) {
+  const { file, exports: exports2 } = node;
+  const fileName = file.split("/").pop()?.toLowerCase();
+  const utilityPatterns = [
+    "util",
+    "utility",
+    "utilities",
+    "helper",
+    "helpers",
+    "common",
+    "shared",
+    "lib",
+    "toolbox",
+    "toolkit",
+    ".util.",
+    "-util.",
+    "_util."
+  ];
+  const isUtilityName = utilityPatterns.some(
+    (pattern) => fileName?.includes(pattern)
+  );
+  const isUtilityPath = file.toLowerCase().includes("/utils/") || file.toLowerCase().includes("/helpers/") || file.toLowerCase().includes("/lib/") || file.toLowerCase().includes("/common/");
+  const hasManySmallExports = exports2.length >= 3 && exports2.every(
+    (e) => e.type === "function" || e.type === "const"
+  );
+  return isUtilityName || isUtilityPath || hasManySmallExports;
+}
+function adjustFragmentationForClassification(baseFragmentation, classification) {
+  switch (classification) {
+    case "barrel-export":
+      return 0;
+    case "type-definition":
+      return 0;
+    case "cohesive-module":
+      return baseFragmentation * 0.3;
+    case "mixed-concerns":
+      return baseFragmentation;
+    default:
+      return baseFragmentation * 0.7;
+  }
+}
+function getClassificationRecommendations(classification, file, issues) {
+  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;
+  }
+}
 
 // src/scoring.ts
 function calculateContextScore(summary) {
@@ -1176,6 +1327,8 @@ async function analyzeContext(options) {
         contextBudget: metric.contextBudget,
         fragmentationScore: 0,
         relatedFiles: [],
+        fileClassification: "unknown",
+        // Python files not yet classified
         severity,
         issues,
         recommendations,
@@ -1223,6 +1376,33 @@ async function analyzeContext(options) {
     const domains = [
       ...new Set(node.exports.map((e) => e.inferredDomain || "unknown"))
     ];
+    const fileClassification = classifyFile(node, cohesionScore, domains);
+    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,
+      fragmentationScore: adjustedFragmentationScore,
+      maxDepth,
+      maxContextBudget,
+      minCohesion,
+      maxFragmentation,
+      circularDeps
+    });
     results.push({
       file,
       tokenCost: node.tokenCost,
@@ -1235,12 +1415,13 @@ async function analyzeContext(options) {
       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
     });
   }
   const allResults = [...results, ...pythonResults];
@@ -1470,11 +1651,13 @@ function downgradeSeverity(s) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  adjustFragmentationForClassification,
   analyzeContext,
   buildCoUsageMatrix,
   buildTypeGraph,
   calculateContextScore,
   calculateDomainConfidence,
+  classifyFile,
   findConsolidationCandidates,
   findSemanticClusters,
   generateSummary,

package/dist/index.mjs

@@ -1,23 +1,27 @@
 import {
+  adjustFragmentationForClassification,
   analyzeContext,
   buildCoUsageMatrix,
   buildTypeGraph,
   calculateContextScore,
   calculateDomainConfidence,
+  classifyFile,
   findConsolidationCandidates,
   findSemanticClusters,
   generateSummary,
   getCoUsageData,
   getSmartDefaults,
   inferDomainFromSemantics
-} from "./chunk-VTALAPQZ.mjs";
+} from "./chunk-HOUDVRG2.mjs";
 import "./chunk-Y6FXYEAI.mjs";
 export {
+  adjustFragmentationForClassification,
   analyzeContext,
   buildCoUsageMatrix,
   buildTypeGraph,
   calculateContextScore,
   calculateDomainConfidence,
+  classifyFile,
   findConsolidationCandidates,
   findSemanticClusters,
   generateSummary,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiready/context-analyzer",
-  "version": "0.9.22",
+  "version": "0.9.25",
   "description": "AI context window cost analysis - detect fragmented code, deep import chains, and expensive context budgets",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",