@optave/codegraph 3.1.5 → 3.2.0

package/src/features/structure.js

@@ -5,73 +5,41 @@ import { isTestFile } from '../infrastructure/test-filter.js';
 import { normalizePath } from '../shared/constants.js';
 import { paginateResult } from '../shared/paginate.js';
 
-// ─── Build-time: insert directory nodes, contains edges, and metrics ────
-
-/**
- * Build directory structure nodes, containment edges, and compute metrics.
- * Called from builder.js after edge building.
- *
- * @param {import('better-sqlite3').Database} db - Open read-write database
- * @param {Map<string, object>} fileSymbols - Map of relPath → { definitions, imports, exports, calls }
- * @param {string} rootDir - Absolute root directory
- * @param {Map<string, number>} lineCountMap - Map of relPath → line count
- * @param {Set<string>} directories - Set of relative directory paths
- */
-export function buildStructure(db, fileSymbols, _rootDir, lineCountMap, directories, changedFiles) {
-  const insertNode = db.prepare(
-    'INSERT OR IGNORE INTO nodes (name, kind, file, line, end_line) VALUES (?, ?, ?, ?, ?)',
-  );
-  const getNodeIdStmt = {
-    get: (name, kind, file, line) => {
-      const id = getNodeId(db, name, kind, file, line);
-      return id != null ? { id } : undefined;
-    },
-  };
-  const insertEdge = db.prepare(
-    'INSERT INTO edges (source_id, target_id, kind, confidence, dynamic) VALUES (?, ?, ?, ?, ?)',
-  );
-  const upsertMetric = db.prepare(`
-    INSERT OR REPLACE INTO node_metrics
-      (node_id, line_count, symbol_count, import_count, export_count, fan_in, fan_out, cohesion, file_count)
-    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
-  `);
+// ─── Build-time helpers ───────────────────────────────────────────────
 
-  const isIncremental = changedFiles != null && changedFiles.length > 0;
+function getAncestorDirs(filePaths) {
+  const dirs = new Set();
+  for (const f of filePaths) {
+    let d = normalizePath(path.dirname(f));
+    while (d && d !== '.') {
+      dirs.add(d);
+      d = normalizePath(path.dirname(d));
+    }
+  }
+  return dirs;
+}
 
+function cleanupPreviousData(db, getNodeIdStmt, isIncremental, changedFiles) {
   if (isIncremental) {
-    // Incremental: only clean up data for changed files and their ancestor directories
-    const affectedDirs = new Set();
-    for (const f of changedFiles) {
-      let d = normalizePath(path.dirname(f));
-      while (d && d !== '.') {
-        affectedDirs.add(d);
-        d = normalizePath(path.dirname(d));
-      }
-    }
+    const affectedDirs = getAncestorDirs(changedFiles);
     const deleteContainsForDir = db.prepare(
       "DELETE FROM edges WHERE kind = 'contains' AND source_id IN (SELECT id FROM nodes WHERE name = ? AND kind = 'directory')",
     );
     const deleteMetricForNode = db.prepare('DELETE FROM node_metrics WHERE node_id = ?');
     db.transaction(() => {
-      // Delete contains edges only from affected directories
       for (const dir of affectedDirs) {
         deleteContainsForDir.run(dir);
       }
-      // Delete metrics for changed files
       for (const f of changedFiles) {
         const fileRow = getNodeIdStmt.get(f, 'file', f, 0);
         if (fileRow) deleteMetricForNode.run(fileRow.id);
       }
-      // Delete metrics for affected directories
       for (const dir of affectedDirs) {
         const dirRow = getNodeIdStmt.get(dir, 'directory', dir, 0);
         if (dirRow) deleteMetricForNode.run(dirRow.id);
       }
     })();
   } else {
-    // Full rebuild: clean previous directory nodes/edges (idempotent)
-    // Scope contains-edge delete to directory-sourced edges only,
-    // preserving symbol-level contains edges (file→def, class→method, etc.)
     db.exec(`
       DELETE FROM edges WHERE kind = 'contains'
         AND source_id IN (SELECT id FROM nodes WHERE kind = 'directory');
@@ -79,8 +47,9 @@ export function buildStructure(db, fileSymbols, _rootDir, lineCountMap, director
       DELETE FROM nodes WHERE kind = 'directory';
     `);
   }
+}
 
-  // Step 1: Ensure all directories are represented (including intermediate parents)
+function collectAllDirectories(directories, fileSymbols) {
   const allDirs = new Set();
   for (const dir of directories) {
     let d = dir;
@@ -89,7 +58,6 @@ export function buildStructure(db, fileSymbols, _rootDir, lineCountMap, director
       d = normalizePath(path.dirname(d));
     }
   }
-  // Also add dirs derived from file paths
   for (const relPath of fileSymbols.keys()) {
     let d = normalizePath(path.dirname(relPath));
     while (d && d !== '.') {
@@ -97,37 +65,17 @@ export function buildStructure(db, fileSymbols, _rootDir, lineCountMap, director
       d = normalizePath(path.dirname(d));
     }
   }
+  return allDirs;
+}
 
-  // Step 2: Insert directory nodes (INSERT OR IGNORE — safe for incremental)
-  const insertDirs = db.transaction(() => {
-    for (const dir of allDirs) {
-      insertNode.run(dir, 'directory', dir, 0, null);
-    }
-  });
-  insertDirs();
-
-  // Step 3: Insert 'contains' edges (dir → file, dir → subdirectory)
-  // On incremental, only re-insert for affected directories (others are intact)
-  const affectedDirs = isIncremental
-    ? (() => {
-        const dirs = new Set();
-        for (const f of changedFiles) {
-          let d = normalizePath(path.dirname(f));
-          while (d && d !== '.') {
-            dirs.add(d);
-            d = normalizePath(path.dirname(d));
-          }
-        }
-        return dirs;
-      })()
-    : null;
+function insertContainsEdges(db, insertEdge, getNodeIdStmt, fileSymbols, allDirs, changedFiles) {
+  const isIncremental = changedFiles != null && changedFiles.length > 0;
+  const affectedDirs = isIncremental ? getAncestorDirs(changedFiles) : null;
 
-  const insertContains = db.transaction(() => {
-    // dir → file
+  db.transaction(() => {
     for (const relPath of fileSymbols.keys()) {
       const dir = normalizePath(path.dirname(relPath));
       if (!dir || dir === '.') continue;
-      // On incremental, skip dirs whose contains edges are intact
       if (affectedDirs && !affectedDirs.has(dir)) continue;
       const dirRow = getNodeIdStmt.get(dir, 'directory', dir, 0);
       const fileRow = getNodeIdStmt.get(relPath, 'file', relPath, 0);
@@ -135,11 +83,9 @@ export function buildStructure(db, fileSymbols, _rootDir, lineCountMap, director
         insertEdge.run(dirRow.id, fileRow.id, 'contains', 1.0, 0);
       }
     }
-    // dir → subdirectory
     for (const dir of allDirs) {
       const parent = normalizePath(path.dirname(dir));
       if (!parent || parent === '.' || parent === dir) continue;
-      // On incremental, skip parent dirs whose contains edges are intact
       if (affectedDirs && !affectedDirs.has(parent)) continue;
       const parentRow = getNodeIdStmt.get(parent, 'directory', parent, 0);
       const childRow = getNodeIdStmt.get(dir, 'directory', dir, 0);
@@ -147,11 +93,10 @@ export function buildStructure(db, fileSymbols, _rootDir, lineCountMap, director
         insertEdge.run(parentRow.id, childRow.id, 'contains', 1.0, 0);
       }
     }
-  });
-  insertContains();
+  })();
+}
 
-  // Step 4: Compute per-file metrics
-  // Pre-compute fan-in/fan-out per file from import edges
+function computeImportEdgeMaps(db) {
   const fanInMap = new Map();
   const fanOutMap = new Map();
   const importEdges = db
@@ -169,14 +114,24 @@ export function buildStructure(db, fileSymbols, _rootDir, lineCountMap, director
     fanOutMap.set(source_file, (fanOutMap.get(source_file) || 0) + 1);
     fanInMap.set(target_file, (fanInMap.get(target_file) || 0) + 1);
   }
+  return { fanInMap, fanOutMap, importEdges };
+}
 
-  const computeFileMetrics = db.transaction(() => {
+function computeFileMetrics(
+  db,
+  upsertMetric,
+  getNodeIdStmt,
+  fileSymbols,
+  lineCountMap,
+  fanInMap,
+  fanOutMap,
+) {
+  db.transaction(() => {
     for (const [relPath, symbols] of fileSymbols) {
       const fileRow = getNodeIdStmt.get(relPath, 'file', relPath, 0);
       if (!fileRow) continue;
 
       const lineCount = lineCountMap.get(relPath) || 0;
-      // Deduplicate definitions by name+kind+line
       const seen = new Set();
       let symbolCount = 0;
       for (const d of symbols.definitions) {
@@ -203,11 +158,17 @@ export function buildStructure(db, fileSymbols, _rootDir, lineCountMap, director
         null,
       );
     }
-  });
-  computeFileMetrics();
+  })();
+}
 
-  // Step 5: Compute per-directory metrics
-  // Build a map of dir → descendant files
+function computeDirectoryMetrics(
+  db,
+  upsertMetric,
+  getNodeIdStmt,
+  fileSymbols,
+  allDirs,
+  importEdges,
+) {
   const dirFiles = new Map();
   for (const dir of allDirs) {
     dirFiles.set(dir, []);
@@ -222,7 +183,6 @@ export function buildStructure(db, fileSymbols, _rootDir, lineCountMap, director
     }
   }
 
-  // Build reverse index: file → set of ancestor directories (O(files × depth))
   const fileToAncestorDirs = new Map();
   for (const [dir, files] of dirFiles) {
     for (const f of files) {
@@ -231,7 +191,6 @@ export function buildStructure(db, fileSymbols, _rootDir, lineCountMap, director
     }
   }
 
-  // Single O(E) pass: pre-aggregate edge counts per directory
   const dirEdgeCounts = new Map();
   for (const dir of allDirs) {
     dirEdgeCounts.set(dir, { intra: 0, fanIn: 0, fanOut: 0 });
@@ -241,7 +200,6 @@ export function buildStructure(db, fileSymbols, _rootDir, lineCountMap, director
     const tgtDirs = fileToAncestorDirs.get(target_file);
     if (!srcDirs && !tgtDirs) continue;
 
-    // For each directory that contains the source file
     if (srcDirs) {
       for (const dir of srcDirs) {
         const counts = dirEdgeCounts.get(dir);
@@ -253,10 +211,9 @@ export function buildStructure(db, fileSymbols, _rootDir, lineCountMap, director
         }
       }
     }
-    // For each directory that contains the target but NOT the source
     if (tgtDirs) {
       for (const dir of tgtDirs) {
-        if (srcDirs?.has(dir)) continue; // already counted as intra
+        if (srcDirs?.has(dir)) continue;
         const counts = dirEdgeCounts.get(dir);
         if (!counts) continue;
         counts.fanIn++;
@@ -264,7 +221,7 @@ export function buildStructure(db, fileSymbols, _rootDir, lineCountMap, director
     }
   }
 
-  const computeDirMetrics = db.transaction(() => {
+  db.transaction(() => {
     for (const [dir, files] of dirFiles) {
       const dirRow = getNodeIdStmt.get(dir, 'directory', dir, 0);
       if (!dirRow) continue;
@@ -286,7 +243,6 @@ export function buildStructure(db, fileSymbols, _rootDir, lineCountMap, director
         }
       }
 
-      // O(1) lookup from pre-aggregated edge counts
       const counts = dirEdgeCounts.get(dir) || { intra: 0, fanIn: 0, fanOut: 0 };
       const totalEdges = counts.intra + counts.fanIn + counts.fanOut;
       const cohesion = totalEdges > 0 ? counts.intra / totalEdges : null;
@@ -303,11 +259,69 @@ export function buildStructure(db, fileSymbols, _rootDir, lineCountMap, director
         fileCount,
       );
     }
-  });
-  computeDirMetrics();
+  })();
+}
+
+// ─── Build-time: insert directory nodes, contains edges, and metrics ────
+
+/**
+ * Build directory structure nodes, containment edges, and compute metrics.
+ * Called from builder.js after edge building.
+ *
+ * @param {import('better-sqlite3').Database} db - Open read-write database
+ * @param {Map<string, object>} fileSymbols - Map of relPath → { definitions, imports, exports, calls }
+ * @param {string} rootDir - Absolute root directory
+ * @param {Map<string, number>} lineCountMap - Map of relPath → line count
+ * @param {Set<string>} directories - Set of relative directory paths
+ */
+export function buildStructure(db, fileSymbols, _rootDir, lineCountMap, directories, changedFiles) {
+  const insertNode = db.prepare(
+    'INSERT OR IGNORE INTO nodes (name, kind, file, line, end_line) VALUES (?, ?, ?, ?, ?)',
+  );
+  const getNodeIdStmt = {
+    get: (name, kind, file, line) => {
+      const id = getNodeId(db, name, kind, file, line);
+      return id != null ? { id } : undefined;
+    },
+  };
+  const insertEdge = db.prepare(
+    'INSERT INTO edges (source_id, target_id, kind, confidence, dynamic) VALUES (?, ?, ?, ?, ?)',
+  );
+  const upsertMetric = db.prepare(`
+    INSERT OR REPLACE INTO node_metrics
+      (node_id, line_count, symbol_count, import_count, export_count, fan_in, fan_out, cohesion, file_count)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `);
+
+  const isIncremental = changedFiles != null && changedFiles.length > 0;
+
+  cleanupPreviousData(db, getNodeIdStmt, isIncremental, changedFiles);
 
-  const dirCount = allDirs.size;
-  debug(`Structure: ${dirCount} directories, ${fileSymbols.size} files with metrics`);
+  const allDirs = collectAllDirectories(directories, fileSymbols);
+
+  db.transaction(() => {
+    for (const dir of allDirs) {
+      insertNode.run(dir, 'directory', dir, 0, null);
+    }
+  })();
+
+  insertContainsEdges(db, insertEdge, getNodeIdStmt, fileSymbols, allDirs, changedFiles);
+
+  const { fanInMap, fanOutMap, importEdges } = computeImportEdgeMaps(db);
+
+  computeFileMetrics(
+    db,
+    upsertMetric,
+    getNodeIdStmt,
+    fileSymbols,
+    lineCountMap,
+    fanInMap,
+    fanOutMap,
+  );
+
+  computeDirectoryMetrics(db, upsertMetric, getNodeIdStmt, fileSymbols, allDirs, importEdges);
+
+  debug(`Structure: ${allDirs.size} directories, ${fileSymbols.size} files with metrics`);
 }
 
 // ─── Node role classification ─────────────────────────────────────────
@@ -335,7 +349,7 @@ export function classifyNodeRoles(db) {
     .all();
 
   if (rows.length === 0) {
-    return { entry: 0, core: 0, utility: 0, adapter: 0, dead: 0, leaf: 0 };
+    return { entry: 0, core: 0, utility: 0, adapter: 0, dead: 0, 'test-only': 0, leaf: 0 };
   }
 
   const exportedIds = new Set(
@@ -351,6 +365,22 @@ export function classifyNodeRoles(db) {
       .map((r) => r.target_id),
   );
 
+  // Compute production fan-in (excluding callers in test files)
+  const prodFanInMap = new Map();
+  const prodRows = db
+    .prepare(
+      `SELECT e.target_id, COUNT(*) AS cnt
+      FROM edges e
+      JOIN nodes caller ON e.source_id = caller.id
+      WHERE e.kind = 'calls'
+        ${testFilterSQL('caller.file')}
+      GROUP BY e.target_id`,
+    )
+    .all();
+  for (const r of prodRows) {
+    prodFanInMap.set(r.target_id, r.cnt);
+  }
+
   // Delegate classification to the pure-logic classifier
   const classifierInput = rows.map((r) => ({
     id: String(r.id),
@@ -358,12 +388,13 @@ export function classifyNodeRoles(db) {
     fanIn: r.fan_in,
     fanOut: r.fan_out,
     isExported: exportedIds.has(r.id),
+    productionFanIn: prodFanInMap.get(r.id) || 0,
   }));
 
   const roleMap = classifyRoles(classifierInput);
 
   // Build summary and updates
-  const summary = { entry: 0, core: 0, utility: 0, adapter: 0, dead: 0, leaf: 0 };
+  const summary = { entry: 0, core: 0, utility: 0, adapter: 0, dead: 0, 'test-only': 0, leaf: 0 };
   const updates = [];
   for (const row of rows) {
     const role = roleMap.get(String(row.id)) || 'leaf';

package/src/features/triage.js

@@ -4,8 +4,83 @@ import { warn } from '../infrastructure/logger.js';
 import { isTestFile } from '../infrastructure/test-filter.js';
 import { paginateResult } from '../shared/paginate.js';
 
+// ─── Scoring ─────────────────────────────────────────────────────────
+
+const SORT_FNS = {
+  risk: (a, b) => b.riskScore - a.riskScore,
+  complexity: (a, b) => b.cognitive - a.cognitive,
+  churn: (a, b) => b.churn - a.churn,
+  'fan-in': (a, b) => b.fanIn - a.fanIn,
+  mi: (a, b) => a.maintainabilityIndex - b.maintainabilityIndex,
+};
+
+/**
+ * Build scored triage items from raw rows and risk metrics.
+ * @param {object[]} rows - Raw DB rows
+ * @param {object[]} riskMetrics - Per-row risk metric objects from scoreRisk
+ * @returns {object[]}
+ */
+function buildTriageItems(rows, riskMetrics) {
+  return rows.map((r, i) => ({
+    name: r.name,
+    kind: r.kind,
+    file: r.file,
+    line: r.line,
+    role: r.role || null,
+    fanIn: r.fan_in,
+    cognitive: r.cognitive,
+    churn: r.churn,
+    maintainabilityIndex: r.mi,
+    normFanIn: riskMetrics[i].normFanIn,
+    normComplexity: riskMetrics[i].normComplexity,
+    normChurn: riskMetrics[i].normChurn,
+    normMI: riskMetrics[i].normMI,
+    roleWeight: riskMetrics[i].roleWeight,
+    riskScore: riskMetrics[i].riskScore,
+  }));
+}
+
+/**
+ * Compute signal coverage and summary statistics.
+ * @param {object[]} filtered - All filtered rows
+ * @param {object[]} scored - Scored and filtered items
+ * @param {object} weights - Active weights
+ * @returns {object}
+ */
+function computeTriageSummary(filtered, scored, weights) {
+  const signalCoverage = {
+    complexity: round4(filtered.filter((r) => r.cognitive > 0).length / filtered.length),
+    churn: round4(filtered.filter((r) => r.churn > 0).length / filtered.length),
+    fanIn: round4(filtered.filter((r) => r.fan_in > 0).length / filtered.length),
+    mi: round4(filtered.filter((r) => r.mi > 0).length / filtered.length),
+  };
+
+  const scores = scored.map((it) => it.riskScore);
+  const avgScore =
+    scores.length > 0 ? round4(scores.reduce((a, b) => a + b, 0) / scores.length) : 0;
+  const maxScore = scores.length > 0 ? round4(Math.max(...scores)) : 0;
+
+  return {
+    total: filtered.length,
+    analyzed: scored.length,
+    avgScore,
+    maxScore,
+    weights,
+    signalCoverage,
+  };
+}
+
 // ─── Data Function ────────────────────────────────────────────────────
 
+const EMPTY_SUMMARY = (weights) => ({
+  total: 0,
+  analyzed: 0,
+  avgScore: 0,
+  maxScore: 0,
+  weights,
+  signalCoverage: {},
+});
+
 /**
  * Compute composite risk scores for all symbols.
  *
@@ -17,9 +92,6 @@ export function triageData(customDbPath, opts = {}) {
   const { repo, close } = openRepo(customDbPath, opts);
   try {
     const noTests = opts.noTests || false;
-    const fileFilter = opts.file || null;
-    const kindFilter = opts.kind || null;
-    const roleFilter = opts.role || null;
     const minScore = opts.minScore != null ? Number(opts.minScore) : null;
     const sort = opts.sort || 'risk';
     const weights = { ...DEFAULT_WEIGHTS, ...(opts.weights || {}) };
@@ -28,86 +100,29 @@ export function triageData(customDbPath, opts = {}) {
     try {
       rows = repo.findNodesForTriage({
         noTests,
-        file: fileFilter,
-        kind: kindFilter,
-        role: roleFilter,
+        file: opts.file || null,
+        kind: opts.kind || null,
+        role: opts.role || null,
       });
     } catch (err) {
       warn(`triage query failed: ${err.message}`);
-      return {
-        items: [],
-        summary: { total: 0, analyzed: 0, avgScore: 0, maxScore: 0, weights, signalCoverage: {} },
-      };
+      return { items: [], summary: EMPTY_SUMMARY(weights) };
     }
 
-    // Post-filter test files (belt-and-suspenders)
     const filtered = noTests ? rows.filter((r) => !isTestFile(r.file)) : rows;
-
     if (filtered.length === 0) {
-      return {
-        items: [],
-        summary: { total: 0, analyzed: 0, avgScore: 0, maxScore: 0, weights, signalCoverage: {} },
-      };
+      return { items: [], summary: EMPTY_SUMMARY(weights) };
     }
 
-    // Delegate scoring to classifier
     const riskMetrics = scoreRisk(filtered, weights);
+    const items = buildTriageItems(filtered, riskMetrics);
 
-    // Compute risk scores
-    const items = filtered.map((r, i) => ({
-      name: r.name,
-      kind: r.kind,
-      file: r.file,
-      line: r.line,
-      role: r.role || null,
-      fanIn: r.fan_in,
-      cognitive: r.cognitive,
-      churn: r.churn,
-      maintainabilityIndex: r.mi,
-      normFanIn: riskMetrics[i].normFanIn,
-      normComplexity: riskMetrics[i].normComplexity,
-      normChurn: riskMetrics[i].normChurn,
-      normMI: riskMetrics[i].normMI,
-      roleWeight: riskMetrics[i].roleWeight,
-      riskScore: riskMetrics[i].riskScore,
-    }));
-
-    // Apply minScore filter
     const scored = minScore != null ? items.filter((it) => it.riskScore >= minScore) : items;
-
-    // Sort
-    const sortFns = {
-      risk: (a, b) => b.riskScore - a.riskScore,
-      complexity: (a, b) => b.cognitive - a.cognitive,
-      churn: (a, b) => b.churn - a.churn,
-      'fan-in': (a, b) => b.fanIn - a.fanIn,
-      mi: (a, b) => a.maintainabilityIndex - b.maintainabilityIndex,
-    };
-    scored.sort(sortFns[sort] || sortFns.risk);
-
-    // Signal coverage: % of items with non-zero signal
-    const signalCoverage = {
-      complexity: round4(filtered.filter((r) => r.cognitive > 0).length / filtered.length),
-      churn: round4(filtered.filter((r) => r.churn > 0).length / filtered.length),
-      fanIn: round4(filtered.filter((r) => r.fan_in > 0).length / filtered.length),
-      mi: round4(filtered.filter((r) => r.mi > 0).length / filtered.length),
-    };
-
-    const scores = scored.map((it) => it.riskScore);
-    const avgScore =
-      scores.length > 0 ? round4(scores.reduce((a, b) => a + b, 0) / scores.length) : 0;
-    const maxScore = scores.length > 0 ? round4(Math.max(...scores)) : 0;
+    scored.sort(SORT_FNS[sort] || SORT_FNS.risk);
 
     const result = {
       items: scored,
-      summary: {
-        total: filtered.length,
-        analyzed: scored.length,
-        avgScore,
-        maxScore,
-        weights,
-        signalCoverage,
-      },
+      summary: computeTriageSummary(filtered, scored, weights),
     };
 
     return paginateResult(result, 'items', {

package/src/graph/classifiers/risk.js

@@ -16,14 +16,15 @@ export const DEFAULT_WEIGHTS = {
 
 // Role weights reflect structural importance: core modules are central to the
 // dependency graph, utilities are widely imported, entry points are API
-// surfaces. Adapters bridge subsystems but are replaceable. Leaves and dead
-// code have minimal downstream impact.
+// surfaces. Adapters bridge subsystems but are replaceable. Leaves, dead
+// code, and test-only symbols have minimal downstream impact.
 export const ROLE_WEIGHTS = {
   core: 1.0,
   utility: 0.9,
   entry: 0.8,
   adapter: 0.5,
   leaf: 0.2,
+  'test-only': 0.1,
   dead: 0.1,
 };
 

package/src/graph/classifiers/roles.js

@@ -1,7 +1,7 @@
 /**
  * Node role classification — pure logic, no DB.
  *
- * Roles: entry, core, utility, adapter, leaf, dead
+ * Roles: entry, core, utility, adapter, leaf, dead, test-only
  */
 
 export const FRAMEWORK_ENTRY_PREFIXES = ['route:', 'event:', 'command:'];
@@ -15,7 +15,7 @@ function median(sorted) {
 /**
  * Classify nodes into architectural roles based on fan-in/fan-out metrics.
  *
- * @param {{ id: string, name: string, fanIn: number, fanOut: number, isExported: boolean }[]} nodes
+ * @param {{ id: string, name: string, fanIn: number, fanOut: number, isExported: boolean, testOnlyFanIn?: number }[]} nodes
  * @returns {Map<string, string>} nodeId → role
  */
 export function classifyRoles(nodes) {
@@ -38,15 +38,18 @@ export function classifyRoles(nodes) {
   for (const node of nodes) {
     const highIn = node.fanIn >= medFanIn && node.fanIn > 0;
     const highOut = node.fanOut >= medFanOut && node.fanOut > 0;
+    const hasProdFanIn = typeof node.productionFanIn === 'number';
 
     let role;
     const isFrameworkEntry = FRAMEWORK_ENTRY_PREFIXES.some((p) => node.name.startsWith(p));
     if (isFrameworkEntry) {
       role = 'entry';
     } else if (node.fanIn === 0 && !node.isExported) {
-      role = 'dead';
+      role = node.testOnlyFanIn > 0 ? 'test-only' : 'dead';
     } else if (node.fanIn === 0 && node.isExported) {
       role = 'entry';
+    } else if (hasProdFanIn && node.fanIn > 0 && node.productionFanIn === 0) {
+      role = 'test-only';
     } else if (highIn && !highOut) {
       role = 'core';
     } else if (highIn && highOut) {

package/src/index.js

@@ -12,6 +12,7 @@
 export { buildGraph } from './domain/graph/builder.js';
 export { findCycles } from './domain/graph/cycles.js';
 export {
+  briefData,
   childrenData,
   contextData,
   diffImpactData,