@aiready/context-analyzer 0.5.0 → 0.5.3

package/.turbo/turbo-build.log

@@ -1,6 +1,6 @@
 
 
-> @aiready/context-analyzer@0.5.0 build /Users/pengcao/projects/aiready/packages/context-analyzer
+> @aiready/context-analyzer@0.5.3 build /Users/pengcao/projects/aiready/packages/context-analyzer
 > tsup src/index.ts src/cli.ts --format cjs,esm --dts
 
 CLI Building entry: src/cli.ts, src/index.ts
@@ -9,15 +9,15 @@
 CLI Target: es2020
 CJS Build start
 ESM Build start
-CJS dist/cli.js   39.27 KB
-CJS dist/index.js 20.62 KB
-CJS ⚡️ Build success in 42ms
+CJS dist/cli.js   39.84 KB
+CJS dist/index.js 21.19 KB
+CJS ⚡️ Build success in 57ms
 ESM dist/cli.mjs            18.45 KB
+ESM dist/chunk-EX7HCWAO.mjs 20.05 KB
 ESM dist/index.mjs          164.00 B
-ESM dist/chunk-NJUW6VED.mjs 19.48 KB
-ESM ⚡️ Build success in 42ms
+ESM ⚡️ Build success in 57ms
 DTS Build start
-DTS ⚡️ Build success in 551ms
+DTS ⚡️ Build success in 529ms
 DTS dist/cli.d.ts    20.00 B
 DTS dist/index.d.ts  2.44 KB
 DTS dist/cli.d.mts   20.00 B

package/.turbo/turbo-test.log

@@ -1,33 +1,12 @@
 
 
-> @aiready/context-analyzer@0.5.0 test /Users/pengcao/projects/aiready/packages/context-analyzer
+> @aiready/context-analyzer@0.5.3 test /Users/pengcao/projects/aiready/packages/context-analyzer
 > vitest run
 
 
  RUN  v2.1.9 /Users/pengcao/projects/aiready/packages/context-analyzer
 
-[?25l · src/__tests__/analyzer.test.ts (13)
-   · buildDependencyGraph (1)
-     · should build a basic dependency graph
-   · calculateImportDepth (2)
-     · should calculate import depth correctly
-     · should handle circular dependencies gracefully
-   · getTransitiveDependencies (1)
-     · should get all transitive dependencies
-   · calculateContextBudget (1)
-     · should calculate total token cost including dependencies
-   · detectCircularDependencies (2)
-     · should detect circular dependencies
-     · should return empty for no circular dependencies
-   · calculateCohesion (3)
-     · should return 1 for single export
-     · should return high cohesion for related exports
-     · should return low cohesion for mixed exports
-   · calculateFragmentation (3)
-     · should return 0 for single file
-     · should return 0 for files in same directory
-     · should return high fragmentation for scattered files
-[?25l ✓ src/__tests__/analyzer.test.ts (13)
+ ✓ src/__tests__/analyzer.test.ts (14)
    ✓ buildDependencyGraph (1)
      ✓ should build a basic dependency graph
    ✓ calculateImportDepth (2)
@@ -40,18 +19,19 @@
    ✓ detectCircularDependencies (2)
      ✓ should detect circular dependencies
      ✓ should return empty for no circular dependencies
-   ✓ calculateCohesion (3)
+   ✓ calculateCohesion (4)
      ✓ should return 1 for single export
      ✓ should return high cohesion for related exports
      ✓ should return low cohesion for mixed exports
+     ✓ should return 1 for test files even with mixed domains
    ✓ calculateFragmentation (3)
      ✓ should return 0 for single file
      ✓ should return 0 for files in same directory
      ✓ should return high fragmentation for scattered files
 
  Test Files  1 passed (1)
-      Tests  13 passed (13)
-   Start at  07:46:59
-   Duration  394ms (transform 66ms, setup 0ms, collect 75ms, tests 41ms, environment 0ms, prepare 42ms)
+      Tests  14 passed (14)
+   Start at  08:26:52
+   Duration  317ms (transform 60ms, setup 0ms, collect 67ms, tests 4ms, environment 0ms, prepare 46ms)
 
-[?25h[?25h
+[?25h

package/README.md

@@ -4,10 +4,15 @@
 
 When AI tools try to help with your code, they need to load files into their context window. Fragmented code structures make this expensive and sometimes impossible. This tool analyzes your codebase to identify:
 
-- Deep import chains that require loading dozens of files
-- Fragmented modules scattered across many directories
-- Low-cohesion files mixing unrelated concerns
-- Files with excessive context budgets
+- 📦 **High Context Budget**: Files that cost too many AI tokens to understand (file + dependencies)
+- 🔗 **Deep Import Chains**: Cascading dependencies that force AI to load many files
+- 🎯 **Low Cohesion**: Files mixing unrelated concerns (God objects)
+- 🗂️ **High Fragmentation**: Domains scattered across many directories
+
+**Quick Start:**
+```bash
+npx @aiready/context-analyzer ./src
+```
 
 ## 🎯 Why This Tool?
 
@@ -50,6 +55,147 @@ Result: AI sees everything, gives complete answers ✅
 - Use **@aiready/context-analyzer** to optimize for AI tools (advisory)
 - Track improvements over time with SaaS tier
 
+## 🧠 Understanding the Metrics
+
+This tool measures four key dimensions that affect how much context AI tools need to load:
+
+### 📊 Context Budget (Tokens)
+
+**What it measures:** Total AI tokens needed to understand a file (file content + all dependencies)
+
+**Why it matters:** AI tools have limited context windows (e.g., 128K tokens). Large context budgets mean:
+- AI needs to load more files to understand your code
+- Risk of hitting context limits → incomplete/wrong answers
+- Slower AI responses (more processing time)
+
+**Example:**
+```typescript
+// High context budget (15,000 tokens)
+import { A, B, C } from './deeply/nested/utils'  // +5,000 tokens
+import { X, Y, Z } from './another/chain'       // +8,000 tokens
+// Your file: 2,000 tokens
+// Total: 15,000 tokens just to understand this one file!
+
+// Low context budget (2,500 tokens)  
+// No deep imports, self-contained logic
+// Total: 2,500 tokens
+```
+
+**🎯 Recommendation:** Files with high context budgets should be **split into smaller, more focused modules**.
+
+---
+
+### 🔗 Import Depth
+
+**What it measures:** How many layers deep your import chains go
+
+**Why it matters:** Deep import chains create cascading context loads:
+```
+app.ts → service.ts → helper.ts → util.ts → core.ts → base.ts
+```
+AI must load all 6 files just to understand app.ts!
+
+**Example:**
+```typescript
+// Deep chain (depth 8) = AI loads 8+ files
+import { validate } from '../../../utils/validators/user/schema'
+
+// Shallow (depth 2) = AI loads 2 files  
+import { validate } from './validators'
+```
+
+**🎯 Recommendation:** Flatten dependency trees or use **facade patterns** to reduce depth.
+
+---
+
+### 🎯 Cohesion Score (0-1)
+
+**What it measures:** How related the exports in a file are to each other
+
+**How it's calculated:** Uses Shannon entropy of inferred domains
+- 1.0 = Perfect cohesion (all exports are related)
+- 0.0 = Zero cohesion (completely unrelated exports)
+
+**Why it matters:** Low cohesion = "God object" pattern = AI confusion
+```typescript
+// Low cohesion (0.3) - mixing unrelated concerns
+export function validateUser() { }      // User domain
+export function formatDate() { }        // Date domain  
+export function sendEmail() { }         // Email domain
+export class DatabasePool { }          // Database domain
+// AI thinks: "What does this file actually do?"
+
+// High cohesion (0.9) - focused responsibility
+export function validateUser() { }
+export function createUser() { }
+export function updateUser() { }
+export interface User { }
+// AI thinks: "Clear! This is user management."
+```
+
+**🎯 Recommendation:** Files with low cohesion should be **split by domain** into separate, focused files.
+
+---
+
+### 🗂️ Fragmentation Score (0-1)
+
+**What it measures:** How scattered a domain/concept is across different directories
+
+**How it's calculated:** `(unique directories - 1) / (total files - 1)`
+- 0.0 = No fragmentation (all files in same directory)
+- 1.0 = Maximum fragmentation (each file in different directory)
+
+**Why it matters:** Scattered domains force AI to load many unrelated paths
+```typescript
+// High fragmentation (0.8) - User domain scattered
+src/api/user-routes.ts           // 800 tokens
+src/services/user-service.ts     // 1,200 tokens
+src/helpers/user-helpers.ts      // 600 tokens
+src/utils/user-utils.ts          // 500 tokens
+src/validators/user-validator.ts // 700 tokens
+src/models/user-model.ts         // 900 tokens
+// Total: 4,700 tokens spread across 6 directories!
+// AI must navigate entire codebase to understand "User"
+
+// Low fragmentation (0.0) - consolidated
+src/user/user.ts                 // 2,800 tokens  
+src/user/types.ts                // 600 tokens
+// Total: 3,400 tokens in one place (29% savings!)
+// AI finds everything in one logical location
+```
+
+**🎯 Recommendation:** Domains with high fragmentation should be **consolidated** into cohesive modules.
+
+---
+
+### ⚖️ The Tradeoff: Splitting vs. Consolidating
+
+**Important:** These metrics can pull in opposite directions!
+
+| Action | Context Budget ⬇️ | Fragmentation ⬇️ | Cohesion ⬆️ |
+|--------|------------------|------------------|-------------|
+| **Split large file** | ✅ Reduces | ⚠️ May increase | ✅ Can improve |
+| **Consolidate scattered files** | ⚠️ May increase | ✅ Reduces | ⚠️ May decrease |
+
+**Best Practice:** Optimize for your use case:
+- **Large files with mixed concerns** → Split by domain (improves cohesion + reduces budget)
+- **Scattered single-domain files** → Consolidate (reduces fragmentation)
+- **Large files with high cohesion** → May be OK if under context budget threshold
+- **Small scattered files** → Consolidate into domain modules
+
+**The tool helps you identify the right balance!**
+
+### 📋 Quick Reference Table
+
+| Metric | Good ✅ | Bad ❌ | Fix |
+|--------|---------|--------|-----|
+| **Context Budget** | < 10K tokens | > 25K tokens | Split large files |
+| **Import Depth** | ≤ 5 levels | ≥ 8 levels | Flatten dependencies |
+| **Cohesion** | > 0.6 (60%) | < 0.4 (40%) | Split by domain |
+| **Fragmentation** | < 0.5 (50%) | > 0.7 (70%) | Consolidate domain |
+
+**Rule of thumb:** The tool flags files that make AI's job harder (expensive to load, confusing to understand, scattered to find).
+
 ## 🚀 Installation
 
 ```bash
@@ -93,6 +239,13 @@ aiready-context ./src --output json --output-file custom-report.json
 
 > **💡 Tip:** By default, console output shows the top 10 results per category. Use `--max-results <number>` to see more, or use `--output json` to get complete details of all issues.
 
+### Understanding Threshold Tuning
+
+Each parameter controls **when the tool flags a file as problematic**. Think of them as sensitivity dials:
+
+- **Lower values** = More strict = More issues reported = More sensitive
+- **Higher values** = More lenient = Fewer issues reported = Less sensitive
+
 ### Getting More/Fewer Results
 
 **Want to catch MORE potential issues?** (More sensitive, shows smaller problems)
@@ -100,23 +253,39 @@ aiready-context ./src --output json --output-file custom-report.json
 ```bash
 # Lower thresholds to be more strict:
 aiready-context ./src --max-depth 3 --max-context 5000 --min-cohesion 0.7 --max-fragmentation 0.4
+#                                 ↓                  ↓                   ↑                      ↓
+#                         Catches depth≥4    Catches 5K+ tokens  Requires 70%+ cohesion  Catches 40%+ fragmentation
 ```
 
+**What this means:**
+- `--max-depth 3`: Flag files with import depth ≥4 (stricter than default 5-7)
+- `--max-context 5000`: Flag files needing 5K+ tokens (catches smaller files)
+- `--min-cohesion 0.7`: Require 70%+ cohesion (stricter about mixed concerns)
+- `--max-fragmentation 0.4`: Flag domains with 40%+ scatter (catches less severe fragmentation)
+
 **Want to see FEWER issues?** (Less noise, focus on critical problems only)
 
 ```bash
 # Raise thresholds to be more lenient:
 aiready-context ./src --max-depth 10 --max-context 30000 --min-cohesion 0.4 --max-fragmentation 0.8
+#                                  ↑                   ↑                   ↓                      ↑
+#                         Only depth≥11      Only 30K+ tokens      Allows 40%+ cohesion    Only 80%+ fragmentation
 ```
 
+**What this means:**
+- `--max-depth 10`: Only flag import depth ≥11 (very deep chains)
+- `--max-context 30000`: Only flag files needing 30K+ tokens (only huge files)
+- `--min-cohesion 0.4`: Accept 40%+ cohesion (more lenient about mixed concerns)
+- `--max-fragmentation 0.8`: Only flag 80%+ scatter (only severely fragmented)
+
 ### Threshold Parameters Explained
 
-| Parameter | Default (Auto) | Lower = More Strict | Higher = Less Strict |
-|-----------|---------------|-------------------|---------------------|
-| `--max-depth` | 4-10* | Catches shallower imports | Only very deep chains |
-| `--max-context` | 8k-40k* | Catches smaller files | Only huge files |
-| `--min-cohesion` | 0.35-0.5* | Stricter about mixed concerns | More lenient |
-| `--max-fragmentation` | 0.5-0.8* | Catches less scattered code | Only severely scattered |
+| Parameter | Default (Auto) | Lower = More Strict | Higher = Less Strict | Impact |
+|-----------|---------------|-------------------|---------------------|--------|
+| `--max-depth` | 4-10* | Catches shallower imports | Only very deep chains | More splits → flatter structure |
+| `--max-context` | 8k-40k* | Catches smaller files | Only huge files | More splits → smaller modules |
+| `--min-cohesion` | 0.35-0.5* | Stricter about mixed concerns | More lenient | More splits → focused files |
+| `--max-fragmentation` | 0.5-0.8* | Catches less scattered code | Only severely scattered | More consolidation → domain modules |
 
 \* Auto-adjusted based on your repository size (100 files vs 2000+ files)
 
@@ -125,16 +294,36 @@ aiready-context ./src --max-depth 10 --max-context 30000 --min-cohesion 0.4 --ma
 **Small codebase getting too many warnings?**
 ```bash
 aiready-context ./src --max-depth 6 --min-cohesion 0.5
+# Explanation: Allow slightly deeper imports and more mixed concerns
+# Use when: Your codebase is naturally small and warnings feel excessive
 ```
 
 **Large codebase showing too few issues?**
 ```bash
 aiready-context ./src --max-depth 5 --max-context 15000
+# Explanation: Be stricter about depth and context to catch more problems
+# Use when: You know there are issues but they're not being detected
 ```
 
 **Focus on critical issues only:**
 ```bash
 aiready-context ./src --max-depth 8 --max-context 25000 --min-cohesion 0.3
+# Explanation: Very lenient - only show the worst offenders
+# Use when: Fixing warnings in stages, start with critical issues first
+```
+
+**Preparing for AI refactoring sprint:**
+```bash
+aiready-context ./src --max-depth 4 --max-context 8000 --min-cohesion 0.6 --max-fragmentation 0.5
+# Explanation: Strict on all dimensions to get comprehensive issue list
+# Use when: Planning a major refactoring effort, need complete audit
+```
+
+**Microservices architecture (naturally fragmented):**
+```bash
+aiready-context ./src --max-fragmentation 0.9
+# Explanation: Very lenient on fragmentation (services are meant to be separate)
+# Use when: Analyzing microservices where fragmentation is intentional
 ```
 
 ## 📤 Output Options

package/dist/chunk-EX7HCWAO.mjs

@@ -0,0 +1,625 @@
+// src/index.ts
+import { scanFiles, readFileContent } from "@aiready/core";
+
+// src/analyzer.ts
+import { estimateTokens } from "@aiready/core";
+function buildDependencyGraph(files) {
+  const nodes = /* @__PURE__ */ new Map();
+  const edges = /* @__PURE__ */ new Map();
+  for (const { file, content } of files) {
+    const imports = extractImportsFromContent(content);
+    const exports = extractExports(content);
+    const tokenCost = estimateTokens(content);
+    const linesOfCode = content.split("\n").length;
+    nodes.set(file, {
+      file,
+      imports,
+      exports,
+      tokenCost,
+      linesOfCode
+    });
+    edges.set(file, new Set(imports));
+  }
+  return { nodes, edges };
+}
+function extractImportsFromContent(content) {
+  const imports = [];
+  const patterns = [
+    /import\s+.*?\s+from\s+['"](.+?)['"]/g,
+    // import ... from '...'
+    /import\s+['"](.+?)['"]/g,
+    // import '...'
+    /require\(['"](.+?)['"]\)/g
+    // require('...')
+  ];
+  for (const pattern of patterns) {
+    let match;
+    while ((match = pattern.exec(content)) !== null) {
+      const importPath = match[1];
+      if (importPath && !importPath.startsWith("@") && !importPath.startsWith("node:")) {
+        imports.push(importPath);
+      }
+    }
+  }
+  return [...new Set(imports)];
+}
+function calculateImportDepth(file, graph, visited = /* @__PURE__ */ new Set(), depth = 0) {
+  if (visited.has(file)) {
+    return depth;
+  }
+  const dependencies = graph.edges.get(file);
+  if (!dependencies || dependencies.size === 0) {
+    return depth;
+  }
+  visited.add(file);
+  let maxDepth = depth;
+  for (const dep of dependencies) {
+    const depDepth = calculateImportDepth(dep, graph, visited, depth + 1);
+    maxDepth = Math.max(maxDepth, depDepth);
+  }
+  visited.delete(file);
+  return maxDepth;
+}
+function getTransitiveDependencies(file, graph, visited = /* @__PURE__ */ new Set()) {
+  if (visited.has(file)) {
+    return [];
+  }
+  visited.add(file);
+  const dependencies = graph.edges.get(file);
+  if (!dependencies || dependencies.size === 0) {
+    return [];
+  }
+  const allDeps = [];
+  for (const dep of dependencies) {
+    allDeps.push(dep);
+    allDeps.push(...getTransitiveDependencies(dep, graph, visited));
+  }
+  return [...new Set(allDeps)];
+}
+function calculateContextBudget(file, graph) {
+  const node = graph.nodes.get(file);
+  if (!node) return 0;
+  let totalTokens = node.tokenCost;
+  const deps = getTransitiveDependencies(file, graph);
+  for (const dep of deps) {
+    const depNode = graph.nodes.get(dep);
+    if (depNode) {
+      totalTokens += depNode.tokenCost;
+    }
+  }
+  return totalTokens;
+}
+function detectCircularDependencies(graph) {
+  const cycles = [];
+  const visited = /* @__PURE__ */ new Set();
+  const recursionStack = /* @__PURE__ */ new Set();
+  function dfs(file, path) {
+    if (recursionStack.has(file)) {
+      const cycleStart = path.indexOf(file);
+      if (cycleStart !== -1) {
+        cycles.push([...path.slice(cycleStart), file]);
+      }
+      return;
+    }
+    if (visited.has(file)) {
+      return;
+    }
+    visited.add(file);
+    recursionStack.add(file);
+    path.push(file);
+    const dependencies = graph.edges.get(file);
+    if (dependencies) {
+      for (const dep of dependencies) {
+        dfs(dep, [...path]);
+      }
+    }
+    recursionStack.delete(file);
+  }
+  for (const file of graph.nodes.keys()) {
+    if (!visited.has(file)) {
+      dfs(file, []);
+    }
+  }
+  return cycles;
+}
+function calculateCohesion(exports, filePath) {
+  if (exports.length === 0) return 1;
+  if (exports.length === 1) return 1;
+  if (filePath && isTestFile(filePath)) {
+    return 1;
+  }
+  const domains = exports.map((e) => e.inferredDomain || "unknown");
+  const domainCounts = /* @__PURE__ */ new Map();
+  for (const domain of domains) {
+    domainCounts.set(domain, (domainCounts.get(domain) || 0) + 1);
+  }
+  const total = domains.length;
+  let entropy = 0;
+  for (const count of domainCounts.values()) {
+    const p = count / total;
+    if (p > 0) {
+      entropy -= p * Math.log2(p);
+    }
+  }
+  const maxEntropy = Math.log2(total);
+  return maxEntropy > 0 ? 1 - entropy / maxEntropy : 1;
+}
+function isTestFile(filePath) {
+  const lower = filePath.toLowerCase();
+  return lower.includes("test") || lower.includes("spec") || lower.includes("mock") || lower.includes("fixture") || lower.includes("__tests__") || lower.includes(".test.") || lower.includes(".spec.");
+}
+function calculateFragmentation(files, domain) {
+  if (files.length <= 1) return 0;
+  const directories = new Set(files.map((f) => f.split("/").slice(0, -1).join("/")));
+  return (directories.size - 1) / (files.length - 1);
+}
+function detectModuleClusters(graph) {
+  const domainMap = /* @__PURE__ */ new Map();
+  for (const [file, node] of graph.nodes.entries()) {
+    const domains = node.exports.map((e) => e.inferredDomain || "unknown");
+    const primaryDomain = domains[0] || "unknown";
+    if (!domainMap.has(primaryDomain)) {
+      domainMap.set(primaryDomain, []);
+    }
+    domainMap.get(primaryDomain).push(file);
+  }
+  const clusters = [];
+  for (const [domain, files] of domainMap.entries()) {
+    if (files.length < 2) continue;
+    const totalTokens = files.reduce((sum, file) => {
+      const node = graph.nodes.get(file);
+      return sum + (node?.tokenCost || 0);
+    }, 0);
+    const fragmentationScore = calculateFragmentation(files, domain);
+    const avgCohesion = files.reduce((sum, file) => {
+      const node = graph.nodes.get(file);
+      return sum + (node ? calculateCohesion(node.exports, file) : 0);
+    }, 0) / files.length;
+    const targetFiles = Math.max(1, Math.ceil(files.length / 3));
+    const consolidationPlan = generateConsolidationPlan(
+      domain,
+      files,
+      targetFiles
+    );
+    clusters.push({
+      domain,
+      files,
+      totalTokens,
+      fragmentationScore,
+      avgCohesion,
+      suggestedStructure: {
+        targetFiles,
+        consolidationPlan
+      }
+    });
+  }
+  return clusters.sort((a, b) => b.fragmentationScore - a.fragmentationScore);
+}
+function extractExports(content) {
+  const exports = [];
+  const patterns = [
+    /export\s+function\s+(\w+)/g,
+    /export\s+class\s+(\w+)/g,
+    /export\s+const\s+(\w+)/g,
+    /export\s+type\s+(\w+)/g,
+    /export\s+interface\s+(\w+)/g,
+    /export\s+default/g
+  ];
+  const types = [
+    "function",
+    "class",
+    "const",
+    "type",
+    "interface",
+    "default"
+  ];
+  patterns.forEach((pattern, index) => {
+    let match;
+    while ((match = pattern.exec(content)) !== null) {
+      const name = match[1] || "default";
+      const type = types[index];
+      const inferredDomain = inferDomain(name);
+      exports.push({ name, type, inferredDomain });
+    }
+  });
+  return exports;
+}
+function inferDomain(name) {
+  const lower = name.toLowerCase();
+  const domainKeywords = [
+    "authentication",
+    "authorization",
+    "payment",
+    "invoice",
+    "customer",
+    "product",
+    "order",
+    "cart",
+    "user",
+    "admin",
+    "repository",
+    "controller",
+    "service",
+    "config",
+    "model",
+    "view",
+    "auth",
+    "api",
+    "helper",
+    "util"
+  ];
+  for (const keyword of domainKeywords) {
+    const wordBoundaryPattern = new RegExp(`\\b${keyword}\\b`, "i");
+    if (wordBoundaryPattern.test(name)) {
+      return keyword;
+    }
+  }
+  for (const keyword of domainKeywords) {
+    if (lower.includes(keyword)) {
+      return keyword;
+    }
+  }
+  return "unknown";
+}
+function generateConsolidationPlan(domain, files, targetFiles) {
+  const plan = [];
+  if (files.length <= targetFiles) {
+    return [`No consolidation needed for ${domain}`];
+  }
+  plan.push(
+    `Consolidate ${files.length} ${domain} files into ${targetFiles} cohesive file(s):`
+  );
+  const dirGroups = /* @__PURE__ */ new Map();
+  for (const file of files) {
+    const dir = file.split("/").slice(0, -1).join("/");
+    if (!dirGroups.has(dir)) {
+      dirGroups.set(dir, []);
+    }
+    dirGroups.get(dir).push(file);
+  }
+  plan.push(`1. Create unified ${domain} module file`);
+  plan.push(
+    `2. Move related functionality from ${files.length} scattered files`
+  );
+  plan.push(`3. Update imports in dependent files`);
+  plan.push(
+    `4. Remove old files after consolidation (verify with tests first)`
+  );
+  return plan;
+}
+
+// src/index.ts
+async function getSmartDefaults(directory, userOptions) {
+  const files = await scanFiles({
+    rootDir: directory,
+    include: userOptions.include,
+    exclude: userOptions.exclude
+  });
+  const estimatedBlocks = files.length;
+  let maxDepth;
+  let maxContextBudget;
+  let minCohesion;
+  let maxFragmentation;
+  if (estimatedBlocks < 100) {
+    maxDepth = 4;
+    maxContextBudget = 8e3;
+    minCohesion = 0.5;
+    maxFragmentation = 0.5;
+  } else if (estimatedBlocks < 500) {
+    maxDepth = 5;
+    maxContextBudget = 15e3;
+    minCohesion = 0.45;
+    maxFragmentation = 0.6;
+  } else if (estimatedBlocks < 2e3) {
+    maxDepth = 7;
+    maxContextBudget = 25e3;
+    minCohesion = 0.4;
+    maxFragmentation = 0.7;
+  } else {
+    maxDepth = 10;
+    maxContextBudget = 4e4;
+    minCohesion = 0.35;
+    maxFragmentation = 0.8;
+  }
+  return {
+    maxDepth,
+    maxContextBudget,
+    minCohesion,
+    maxFragmentation,
+    focus: "all",
+    includeNodeModules: false,
+    rootDir: userOptions.rootDir || directory,
+    include: userOptions.include,
+    exclude: userOptions.exclude
+  };
+}
+async function analyzeContext(options) {
+  const {
+    maxDepth = 5,
+    maxContextBudget = 1e4,
+    minCohesion = 0.6,
+    maxFragmentation = 0.5,
+    focus = "all",
+    includeNodeModules = false,
+    ...scanOptions
+  } = options;
+  const files = await scanFiles({
+    ...scanOptions,
+    // Only add node_modules to exclude if includeNodeModules is false
+    // The DEFAULT_EXCLUDE already includes node_modules, so this is only needed
+    // if user overrides the default exclude list
+    exclude: includeNodeModules && scanOptions.exclude ? scanOptions.exclude.filter((pattern) => pattern !== "**/node_modules/**") : scanOptions.exclude
+  });
+  const fileContents = await Promise.all(
+    files.map(async (file) => ({
+      file,
+      content: await readFileContent(file)
+    }))
+  );
+  const graph = buildDependencyGraph(fileContents);
+  const circularDeps = detectCircularDependencies(graph);
+  const clusters = detectModuleClusters(graph);
+  const fragmentationMap = /* @__PURE__ */ new Map();
+  for (const cluster of clusters) {
+    for (const file of cluster.files) {
+      fragmentationMap.set(file, cluster.fragmentationScore);
+    }
+  }
+  const results = [];
+  for (const { file } of fileContents) {
+    const node = graph.nodes.get(file);
+    if (!node) continue;
+    const importDepth = focus === "depth" || focus === "all" ? calculateImportDepth(file, graph) : 0;
+    const dependencyList = focus === "depth" || focus === "all" ? getTransitiveDependencies(file, graph) : [];
+    const contextBudget = focus === "all" ? calculateContextBudget(file, graph) : node.tokenCost;
+    const cohesionScore = focus === "cohesion" || focus === "all" ? calculateCohesion(node.exports, file) : 1;
+    const fragmentationScore = fragmentationMap.get(file) || 0;
+    const relatedFiles = [];
+    for (const cluster of clusters) {
+      if (cluster.files.includes(file)) {
+        relatedFiles.push(...cluster.files.filter((f) => f !== file));
+        break;
+      }
+    }
+    const { severity, issues, recommendations, potentialSavings } = analyzeIssues({
+      file,
+      importDepth,
+      contextBudget,
+      cohesionScore,
+      fragmentationScore,
+      maxDepth,
+      maxContextBudget,
+      minCohesion,
+      maxFragmentation,
+      circularDeps
+    });
+    const domains = [
+      ...new Set(node.exports.map((e) => e.inferredDomain || "unknown"))
+    ];
+    results.push({
+      file,
+      tokenCost: node.tokenCost,
+      linesOfCode: node.linesOfCode,
+      importDepth,
+      dependencyCount: dependencyList.length,
+      dependencyList,
+      circularDeps: circularDeps.filter((cycle) => cycle.includes(file)),
+      cohesionScore,
+      domains,
+      exportCount: node.exports.length,
+      contextBudget,
+      fragmentationScore,
+      relatedFiles,
+      severity,
+      issues,
+      recommendations,
+      potentialSavings
+    });
+  }
+  const issuesOnly = results.filter((r) => r.severity !== "info");
+  const sorted = issuesOnly.sort((a, b) => {
+    const severityOrder = { critical: 0, major: 1, minor: 2, info: 3 };
+    const severityDiff = severityOrder[a.severity] - severityOrder[b.severity];
+    if (severityDiff !== 0) return severityDiff;
+    return b.contextBudget - a.contextBudget;
+  });
+  return sorted.length > 0 ? sorted : results;
+}
+function generateSummary(results) {
+  if (results.length === 0) {
+    return {
+      totalFiles: 0,
+      totalTokens: 0,
+      avgContextBudget: 0,
+      maxContextBudget: 0,
+      avgImportDepth: 0,
+      maxImportDepth: 0,
+      deepFiles: [],
+      avgFragmentation: 0,
+      fragmentedModules: [],
+      avgCohesion: 0,
+      lowCohesionFiles: [],
+      criticalIssues: 0,
+      majorIssues: 0,
+      minorIssues: 0,
+      totalPotentialSavings: 0,
+      topExpensiveFiles: []
+    };
+  }
+  const totalFiles = results.length;
+  const totalTokens = results.reduce((sum, r) => sum + r.tokenCost, 0);
+  const totalContextBudget = results.reduce(
+    (sum, r) => sum + r.contextBudget,
+    0
+  );
+  const avgContextBudget = totalContextBudget / totalFiles;
+  const maxContextBudget = Math.max(...results.map((r) => r.contextBudget));
+  const avgImportDepth = results.reduce((sum, r) => sum + r.importDepth, 0) / totalFiles;
+  const maxImportDepth = Math.max(...results.map((r) => r.importDepth));
+  const deepFiles = results.filter((r) => r.importDepth >= 5).map((r) => ({ file: r.file, depth: r.importDepth })).sort((a, b) => b.depth - a.depth).slice(0, 10);
+  const avgFragmentation = results.reduce((sum, r) => sum + r.fragmentationScore, 0) / totalFiles;
+  const moduleMap = /* @__PURE__ */ new Map();
+  for (const result of results) {
+    for (const domain of result.domains) {
+      if (!moduleMap.has(domain)) {
+        moduleMap.set(domain, []);
+      }
+      moduleMap.get(domain).push(result);
+    }
+  }
+  const fragmentedModules = [];
+  for (const [domain, files] of moduleMap.entries()) {
+    if (files.length < 2) continue;
+    const fragmentationScore = files.reduce((sum, f) => sum + f.fragmentationScore, 0) / files.length;
+    if (fragmentationScore < 0.3) continue;
+    const totalTokens2 = files.reduce((sum, f) => sum + f.tokenCost, 0);
+    const avgCohesion2 = files.reduce((sum, f) => sum + f.cohesionScore, 0) / files.length;
+    const targetFiles = Math.max(1, Math.ceil(files.length / 3));
+    fragmentedModules.push({
+      domain,
+      files: files.map((f) => f.file),
+      totalTokens: totalTokens2,
+      fragmentationScore,
+      avgCohesion: avgCohesion2,
+      suggestedStructure: {
+        targetFiles,
+        consolidationPlan: [
+          `Consolidate ${files.length} ${domain} files into ${targetFiles} cohesive file(s)`,
+          `Current token cost: ${totalTokens2.toLocaleString()}`,
+          `Estimated savings: ${Math.floor(totalTokens2 * 0.3).toLocaleString()} tokens (30%)`
+        ]
+      }
+    });
+  }
+  fragmentedModules.sort((a, b) => b.fragmentationScore - a.fragmentationScore);
+  const avgCohesion = results.reduce((sum, r) => sum + r.cohesionScore, 0) / totalFiles;
+  const lowCohesionFiles = results.filter((r) => r.cohesionScore < 0.6).map((r) => ({ file: r.file, score: r.cohesionScore })).sort((a, b) => a.score - b.score).slice(0, 10);
+  const criticalIssues = results.filter((r) => r.severity === "critical").length;
+  const majorIssues = results.filter((r) => r.severity === "major").length;
+  const minorIssues = results.filter((r) => r.severity === "minor").length;
+  const totalPotentialSavings = results.reduce(
+    (sum, r) => sum + r.potentialSavings,
+    0
+  );
+  const topExpensiveFiles = results.sort((a, b) => b.contextBudget - a.contextBudget).slice(0, 10).map((r) => ({
+    file: r.file,
+    contextBudget: r.contextBudget,
+    severity: r.severity
+  }));
+  return {
+    totalFiles,
+    totalTokens,
+    avgContextBudget,
+    maxContextBudget,
+    avgImportDepth,
+    maxImportDepth,
+    deepFiles,
+    avgFragmentation,
+    fragmentedModules: fragmentedModules.slice(0, 10),
+    avgCohesion,
+    lowCohesionFiles,
+    criticalIssues,
+    majorIssues,
+    minorIssues,
+    totalPotentialSavings,
+    topExpensiveFiles
+  };
+}
+function analyzeIssues(params) {
+  const {
+    file,
+    importDepth,
+    contextBudget,
+    cohesionScore,
+    fragmentationScore,
+    maxDepth,
+    maxContextBudget,
+    minCohesion,
+    maxFragmentation,
+    circularDeps
+  } = params;
+  const issues = [];
+  const recommendations = [];
+  let severity = "info";
+  let potentialSavings = 0;
+  if (circularDeps.length > 0) {
+    severity = "critical";
+    issues.push(
+      `Part of ${circularDeps.length} circular dependency chain(s)`
+    );
+    recommendations.push("Break circular dependencies by extracting interfaces or using dependency injection");
+    potentialSavings += contextBudget * 0.2;
+  }
+  if (importDepth > maxDepth * 1.5) {
+    severity = severity === "critical" ? "critical" : "critical";
+    issues.push(`Import depth ${importDepth} exceeds limit by 50%`);
+    recommendations.push("Flatten dependency tree or use facade pattern");
+    potentialSavings += contextBudget * 0.3;
+  } else if (importDepth > maxDepth) {
+    severity = severity === "critical" ? "critical" : "major";
+    issues.push(`Import depth ${importDepth} exceeds recommended maximum ${maxDepth}`);
+    recommendations.push("Consider reducing dependency depth");
+    potentialSavings += contextBudget * 0.15;
+  }
+  if (contextBudget > maxContextBudget * 1.5) {
+    severity = severity === "critical" ? "critical" : "critical";
+    issues.push(`Context budget ${contextBudget.toLocaleString()} tokens is 50% over limit`);
+    recommendations.push("Split into smaller modules or reduce dependency tree");
+    potentialSavings += contextBudget * 0.4;
+  } else if (contextBudget > maxContextBudget) {
+    severity = severity === "critical" || severity === "major" ? severity : "major";
+    issues.push(`Context budget ${contextBudget.toLocaleString()} exceeds ${maxContextBudget.toLocaleString()}`);
+    recommendations.push("Reduce file size or dependencies");
+    potentialSavings += contextBudget * 0.2;
+  }
+  if (cohesionScore < minCohesion * 0.5) {
+    severity = severity === "critical" ? "critical" : "major";
+    issues.push(`Very low cohesion (${(cohesionScore * 100).toFixed(0)}%) - mixed concerns`);
+    recommendations.push("Split file by domain - separate unrelated functionality");
+    potentialSavings += contextBudget * 0.25;
+  } else if (cohesionScore < minCohesion) {
+    severity = severity === "critical" || severity === "major" ? severity : "minor";
+    issues.push(`Low cohesion (${(cohesionScore * 100).toFixed(0)}%)`);
+    recommendations.push("Consider grouping related exports together");
+    potentialSavings += contextBudget * 0.1;
+  }
+  if (fragmentationScore > maxFragmentation) {
+    severity = severity === "critical" || severity === "major" ? severity : "minor";
+    issues.push(`High fragmentation (${(fragmentationScore * 100).toFixed(0)}%) - scattered implementation`);
+    recommendations.push("Consolidate with related files in same domain");
+    potentialSavings += contextBudget * 0.3;
+  }
+  if (issues.length === 0) {
+    issues.push("No significant issues detected");
+    recommendations.push("File is well-structured for AI context usage");
+  }
+  if (isBuildArtifact(file)) {
+    issues.push("Detected build artifact (bundled/output file)");
+    recommendations.push("Exclude build outputs (e.g., cdk.out, dist, build, .next) from analysis");
+    severity = downgradeSeverity(severity);
+    potentialSavings = 0;
+  }
+  return { severity, issues, recommendations, potentialSavings: Math.floor(potentialSavings) };
+}
+function isBuildArtifact(filePath) {
+  const lower = filePath.toLowerCase();
+  return lower.includes("/node_modules/") || lower.includes("/dist/") || lower.includes("/build/") || lower.includes("/out/") || lower.includes("/output/") || lower.includes("/cdk.out/") || lower.includes("/.next/") || /\/asset\.[^/]+\//.test(lower);
+}
+function downgradeSeverity(s) {
+  switch (s) {
+    case "critical":
+      return "minor";
+    case "major":
+      return "minor";
+    case "minor":
+      return "info";
+    default:
+      return "info";
+  }
+}
+
+export {
+  getSmartDefaults,
+  analyzeContext,
+  generateSummary
+};

package/dist/cli.js

@@ -150,9 +150,12 @@ function detectCircularDependencies(graph) {
   }
   return cycles;
 }
-function calculateCohesion(exports2) {
+function calculateCohesion(exports2, filePath) {
   if (exports2.length === 0) return 1;
   if (exports2.length === 1) return 1;
+  if (filePath && isTestFile(filePath)) {
+    return 1;
+  }
   const domains = exports2.map((e) => e.inferredDomain || "unknown");
   const domainCounts = /* @__PURE__ */ new Map();
   for (const domain of domains) {
@@ -169,6 +172,10 @@ function calculateCohesion(exports2) {
   const maxEntropy = Math.log2(total);
   return maxEntropy > 0 ? 1 - entropy / maxEntropy : 1;
 }
+function isTestFile(filePath) {
+  const lower = filePath.toLowerCase();
+  return lower.includes("test") || lower.includes("spec") || lower.includes("mock") || lower.includes("fixture") || lower.includes("__tests__") || lower.includes(".test.") || lower.includes(".spec.");
+}
 function calculateFragmentation(files, domain) {
   if (files.length <= 1) return 0;
   const directories = new Set(files.map((f) => f.split("/").slice(0, -1).join("/")));
@@ -194,7 +201,7 @@ function detectModuleClusters(graph) {
     const fragmentationScore = calculateFragmentation(files, domain);
     const avgCohesion = files.reduce((sum, file) => {
       const node = graph.nodes.get(file);
-      return sum + (node ? calculateCohesion(node.exports) : 0);
+      return sum + (node ? calculateCohesion(node.exports, file) : 0);
     }, 0) / files.length;
     const targetFiles = Math.max(1, Math.ceil(files.length / 3));
     const consolidationPlan = generateConsolidationPlan(
@@ -248,25 +255,33 @@ function extractExports(content) {
 function inferDomain(name) {
   const lower = name.toLowerCase();
   const domainKeywords = [
-    "user",
-    "auth",
-    "order",
-    "product",
+    "authentication",
+    "authorization",
     "payment",
-    "cart",
     "invoice",
     "customer",
+    "product",
+    "order",
+    "cart",
+    "user",
     "admin",
-    "api",
-    "util",
-    "helper",
-    "config",
-    "service",
     "repository",
     "controller",
+    "service",
+    "config",
     "model",
-    "view"
+    "view",
+    "auth",
+    "api",
+    "helper",
+    "util"
   ];
+  for (const keyword of domainKeywords) {
+    const wordBoundaryPattern = new RegExp(`\\b${keyword}\\b`, "i");
+    if (wordBoundaryPattern.test(name)) {
+      return keyword;
+    }
+  }
   for (const keyword of domainKeywords) {
     if (lower.includes(keyword)) {
       return keyword;
@@ -341,7 +356,7 @@ async function analyzeContext(options) {
     const importDepth = focus === "depth" || focus === "all" ? calculateImportDepth(file, graph) : 0;
     const dependencyList = focus === "depth" || focus === "all" ? getTransitiveDependencies(file, graph) : [];
     const contextBudget = focus === "all" ? calculateContextBudget(file, graph) : node.tokenCost;
-    const cohesionScore = focus === "cohesion" || focus === "all" ? calculateCohesion(node.exports) : 1;
+    const cohesionScore = focus === "cohesion" || focus === "all" ? calculateCohesion(node.exports, file) : 1;
     const fragmentationScore = fragmentationMap.get(file) || 0;
     const relatedFiles = [];
     for (const cluster of clusters) {

package/dist/cli.mjs

@@ -2,7 +2,7 @@
 import {
   analyzeContext,
   generateSummary
-} from "./chunk-NJUW6VED.mjs";
+} from "./chunk-EX7HCWAO.mjs";
 
 // src/cli.ts
 import { Command } from "commander";

package/dist/index.js

@@ -148,9 +148,12 @@ function detectCircularDependencies(graph) {
   }
   return cycles;
 }
-function calculateCohesion(exports2) {
+function calculateCohesion(exports2, filePath) {
   if (exports2.length === 0) return 1;
   if (exports2.length === 1) return 1;
+  if (filePath && isTestFile(filePath)) {
+    return 1;
+  }
   const domains = exports2.map((e) => e.inferredDomain || "unknown");
   const domainCounts = /* @__PURE__ */ new Map();
   for (const domain of domains) {
@@ -167,6 +170,10 @@ function calculateCohesion(exports2) {
   const maxEntropy = Math.log2(total);
   return maxEntropy > 0 ? 1 - entropy / maxEntropy : 1;
 }
+function isTestFile(filePath) {
+  const lower = filePath.toLowerCase();
+  return lower.includes("test") || lower.includes("spec") || lower.includes("mock") || lower.includes("fixture") || lower.includes("__tests__") || lower.includes(".test.") || lower.includes(".spec.");
+}
 function calculateFragmentation(files, domain) {
   if (files.length <= 1) return 0;
   const directories = new Set(files.map((f) => f.split("/").slice(0, -1).join("/")));
@@ -192,7 +199,7 @@ function detectModuleClusters(graph) {
     const fragmentationScore = calculateFragmentation(files, domain);
     const avgCohesion = files.reduce((sum, file) => {
       const node = graph.nodes.get(file);
-      return sum + (node ? calculateCohesion(node.exports) : 0);
+      return sum + (node ? calculateCohesion(node.exports, file) : 0);
     }, 0) / files.length;
     const targetFiles = Math.max(1, Math.ceil(files.length / 3));
     const consolidationPlan = generateConsolidationPlan(
@@ -246,25 +253,33 @@ function extractExports(content) {
 function inferDomain(name) {
   const lower = name.toLowerCase();
   const domainKeywords = [
-    "user",
-    "auth",
-    "order",
-    "product",
+    "authentication",
+    "authorization",
     "payment",
-    "cart",
     "invoice",
     "customer",
+    "product",
+    "order",
+    "cart",
+    "user",
     "admin",
-    "api",
-    "util",
-    "helper",
-    "config",
-    "service",
     "repository",
     "controller",
+    "service",
+    "config",
     "model",
-    "view"
+    "view",
+    "auth",
+    "api",
+    "helper",
+    "util"
   ];
+  for (const keyword of domainKeywords) {
+    const wordBoundaryPattern = new RegExp(`\\b${keyword}\\b`, "i");
+    if (wordBoundaryPattern.test(name)) {
+      return keyword;
+    }
+  }
   for (const keyword of domainKeywords) {
     if (lower.includes(keyword)) {
       return keyword;
@@ -383,7 +398,7 @@ async function analyzeContext(options) {
     const importDepth = focus === "depth" || focus === "all" ? calculateImportDepth(file, graph) : 0;
     const dependencyList = focus === "depth" || focus === "all" ? getTransitiveDependencies(file, graph) : [];
     const contextBudget = focus === "all" ? calculateContextBudget(file, graph) : node.tokenCost;
-    const cohesionScore = focus === "cohesion" || focus === "all" ? calculateCohesion(node.exports) : 1;
+    const cohesionScore = focus === "cohesion" || focus === "all" ? calculateCohesion(node.exports, file) : 1;
     const fragmentationScore = fragmentationMap.get(file) || 0;
     const relatedFiles = [];
     for (const cluster of clusters) {

package/dist/index.mjs

@@ -2,7 +2,7 @@ import {
   analyzeContext,
   generateSummary,
   getSmartDefaults
-} from "./chunk-NJUW6VED.mjs";
+} from "./chunk-EX7HCWAO.mjs";
 export {
   analyzeContext,
   generateSummary,

package/package.json

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

package/src/__tests__/analyzer.test.ts

@@ -148,6 +148,30 @@ describe('calculateCohesion', () => {
     const cohesion = calculateCohesion(exports);
     expect(cohesion).toBeLessThan(0.5);
   });
+
+  it('should return 1 for test files even with mixed domains', () => {
+    const exports = [
+      { name: 'mockUser', type: 'function' as const, inferredDomain: 'user' },
+      { name: 'mockOrder', type: 'function' as const, inferredDomain: 'order' },
+      { name: 'setupTestDb', type: 'function' as const, inferredDomain: 'helper' },
+    ];
+
+    // Test file - should return 1 despite mixed domains
+    const cohesionTestFile = calculateCohesion(exports, 'src/__tests__/helpers.test.ts');
+    expect(cohesionTestFile).toBe(1);
+
+    // Mock file - should return 1 despite mixed domains
+    const cohesionMockFile = calculateCohesion(exports, 'src/test-utils/mocks.ts');
+    expect(cohesionMockFile).toBe(1);
+
+    // Fixture file - should return 1 despite mixed domains
+    const cohesionFixtureFile = calculateCohesion(exports, 'src/fixtures/data.ts');
+    expect(cohesionFixtureFile).toBe(1);
+
+    // Regular file - should have low cohesion
+    const cohesionRegularFile = calculateCohesion(exports, 'src/utils/helpers.ts');
+    expect(cohesionRegularFile).toBeLessThan(0.5);
+  });
 });
 
 describe('calculateFragmentation', () => {

package/src/analyzer.ts

@@ -200,11 +200,19 @@ export function detectCircularDependencies(
 /**
  * Calculate cohesion score (how related are exports in a file)
  * Uses entropy: low entropy = high cohesion
+ * @param exports - Array of export information
+ * @param filePath - Optional file path for context-aware scoring
  */
-export function calculateCohesion(exports: ExportInfo[]): number {
+export function calculateCohesion(exports: ExportInfo[], filePath?: string): number {
   if (exports.length === 0) return 1;
   if (exports.length === 1) return 1; // Single export = perfect cohesion
 
+  // Special case: Test/mock/fixture files are expected to have multi-domain exports
+  // They serve a single purpose (testing) even if they mock different domains
+  if (filePath && isTestFile(filePath)) {
+    return 1; // Test utilities are inherently cohesive despite mixed domains
+  }
+
   const domains = exports.map((e) => e.inferredDomain || 'unknown');
   const domainCounts = new Map<string, number>();
 
@@ -228,6 +236,22 @@ export function calculateCohesion(exports: ExportInfo[]): number {
   return maxEntropy > 0 ? 1 - entropy / maxEntropy : 1;
 }
 
+/**
+ * Check if a file is a test/mock/fixture file
+ */
+function isTestFile(filePath: string): boolean {
+  const lower = filePath.toLowerCase();
+  return (
+    lower.includes('test') ||
+    lower.includes('spec') ||
+    lower.includes('mock') ||
+    lower.includes('fixture') ||
+    lower.includes('__tests__') ||
+    lower.includes('.test.') ||
+    lower.includes('.spec.')
+  );
+}
+
 /**
  * Calculate fragmentation score (how scattered is a domain)
  */
@@ -279,7 +303,7 @@ export function detectModuleClusters(
     const avgCohesion =
       files.reduce((sum, file) => {
         const node = graph.nodes.get(file);
-        return sum + (node ? calculateCohesion(node.exports) : 0);
+        return sum + (node ? calculateCohesion(node.exports, file) : 0);
       }, 0) / files.length;
 
     // Generate consolidation plan
@@ -349,33 +373,45 @@ function extractExports(content: string): ExportInfo[] {
 
 /**
  * Infer domain from export name
- * Uses common naming patterns
+ * Uses common naming patterns with word boundary matching
  */
 function inferDomain(name: string): string {
   const lower = name.toLowerCase();
 
-  // Common domain keywords
+  // Domain keywords ordered from most specific to most general
+  // This prevents generic terms like 'util' from matching before specific domains
   const domainKeywords = [
-    'user',
-    'auth',
-    'order',
-    'product',
+    'authentication',
+    'authorization',
     'payment',
-    'cart',
     'invoice',
     'customer',
+    'product',
+    'order',
+    'cart',
+    'user',
     'admin',
-    'api',
-    'util',
-    'helper',
-    'config',
-    'service',
     'repository',
     'controller',
+    'service',
+    'config',
     'model',
     'view',
+    'auth',
+    'api',
+    'helper',
+    'util',
   ];
 
+  // Try word boundary matching first for more accurate detection
+  for (const keyword of domainKeywords) {
+    const wordBoundaryPattern = new RegExp(`\\b${keyword}\\b`, 'i');
+    if (wordBoundaryPattern.test(name)) {
+      return keyword;
+    }
+  }
+
+  // Fallback to substring matching for compound words
   for (const keyword of domainKeywords) {
     if (lower.includes(keyword)) {
       return keyword;

package/src/index.ts

@@ -157,7 +157,7 @@ export async function analyzeContext(
 
     const cohesionScore =
       focus === 'cohesion' || focus === 'all'
-        ? calculateCohesion(node.exports)
+        ? calculateCohesion(node.exports, file)
         : 1;
 
     const fragmentationScore = fragmentationMap.get(file) || 0;