@optave/codegraph 3.12.0 → 3.15.0

package/src/features/structure.ts

@@ -90,6 +90,44 @@ interface SqliteStatement {
   run(...params: unknown[]): unknown;
 }
 
+/** Insert file→parent-directory contains edges (incremental-aware). */
+function insertFileToParentEdges(
+  insertEdge: SqliteStatement,
+  getNodeIdStmt: NodeIdStmt,
+  fileSymbols: Map<string, FileSymbolData>,
+  affectedDirs: Set<string> | null,
+): void {
+  for (const relPath of fileSymbols.keys()) {
+    const dir = normalizePath(path.dirname(relPath));
+    if (!dir || dir === '.') continue;
+    if (affectedDirs && !affectedDirs.has(dir)) continue;
+    const dirRow = getNodeIdStmt.get(dir, 'directory', dir, 0);
+    const fileRow = getNodeIdStmt.get(relPath, 'file', relPath, 0);
+    if (dirRow && fileRow) {
+      insertEdge.run(dirRow.id, fileRow.id, 'contains', 1.0, 0);
+    }
+  }
+}
+
+/** Insert child-directory→parent-directory contains edges (incremental-aware). */
+function insertDirToParentEdges(
+  insertEdge: SqliteStatement,
+  getNodeIdStmt: NodeIdStmt,
+  allDirs: Set<string>,
+  affectedDirs: Set<string> | null,
+): void {
+  for (const dir of allDirs) {
+    const parent = normalizePath(path.dirname(dir));
+    if (!parent || parent === '.' || parent === dir) continue;
+    if (affectedDirs && !affectedDirs.has(parent)) continue;
+    const parentRow = getNodeIdStmt.get(parent, 'directory', parent, 0);
+    const childRow = getNodeIdStmt.get(dir, 'directory', dir, 0);
+    if (parentRow && childRow) {
+      insertEdge.run(parentRow.id, childRow.id, 'contains', 1.0, 0);
+    }
+  }
+}
+
 function insertContainsEdges(
   db: BetterSqlite3Database,
   insertEdge: SqliteStatement,
@@ -102,26 +140,8 @@ function insertContainsEdges(
   const affectedDirs = isIncremental ? getAncestorDirs(changedFiles ?? []) : null;
 
   db.transaction(() => {
-    for (const relPath of fileSymbols.keys()) {
-      const dir = normalizePath(path.dirname(relPath));
-      if (!dir || dir === '.') continue;
-      if (affectedDirs && !affectedDirs.has(dir)) continue;
-      const dirRow = getNodeIdStmt.get(dir, 'directory', dir, 0);
-      const fileRow = getNodeIdStmt.get(relPath, 'file', relPath, 0);
-      if (dirRow && fileRow) {
-        insertEdge.run(dirRow.id, fileRow.id, 'contains', 1.0, 0);
-      }
-    }
-    for (const dir of allDirs) {
-      const parent = normalizePath(path.dirname(dir));
-      if (!parent || parent === '.' || parent === dir) continue;
-      if (affectedDirs && !affectedDirs.has(parent)) continue;
-      const parentRow = getNodeIdStmt.get(parent, 'directory', parent, 0);
-      const childRow = getNodeIdStmt.get(dir, 'directory', dir, 0);
-      if (parentRow && childRow) {
-        insertEdge.run(parentRow.id, childRow.id, 'contains', 1.0, 0);
-      }
-    }
+    insertFileToParentEdges(insertEdge, getNodeIdStmt, fileSymbols, affectedDirs);
+    insertDirToParentEdges(insertEdge, getNodeIdStmt, allDirs, affectedDirs);
   })();
 }
 
@@ -249,40 +269,59 @@ function buildFileToAncestorDirs(dirFiles: Map<string, string[]>): Map<string, S
   return fileToAncestorDirs;
 }
 
+/** Initialise a zero-count map for all known directories. */
+function initDirEdgeCounts(
+  allDirs: Set<string>,
+): Map<string, { intra: number; fanIn: number; fanOut: number }> {
+  const m = new Map<string, { intra: number; fanIn: number; fanOut: number }>();
+  for (const dir of allDirs) m.set(dir, { intra: 0, fanIn: 0, fanOut: 0 });
+  return m;
+}
+
+/** Accumulate source-side (intra / fanOut) counts for one import edge. */
+function accumulateSrcDirCounts(
+  srcDirs: Set<string>,
+  tgtDirs: Set<string> | undefined,
+  dirEdgeCounts: Map<string, { intra: number; fanIn: number; fanOut: number }>,
+): void {
+  for (const dir of srcDirs) {
+    const counts = dirEdgeCounts.get(dir);
+    if (!counts) continue;
+    if (tgtDirs?.has(dir)) {
+      counts.intra++;
+    } else {
+      counts.fanOut++;
+    }
+  }
+}
+
+/** Accumulate target-side (fanIn) counts for one import edge. */
+function accumulateTgtDirCounts(
+  tgtDirs: Set<string>,
+  srcDirs: Set<string> | undefined,
+  dirEdgeCounts: Map<string, { intra: number; fanIn: number; fanOut: number }>,
+): void {
+  for (const dir of tgtDirs) {
+    if (srcDirs?.has(dir)) continue;
+    const counts = dirEdgeCounts.get(dir);
+    if (!counts) continue;
+    counts.fanIn++;
+  }
+}
+
 /** Count intra-directory, fan-in, and fan-out edges per directory. */
 function countDirectoryEdges(
   allDirs: Set<string>,
   importEdges: ImportEdge[],
   fileToAncestorDirs: Map<string, Set<string>>,
 ): Map<string, { intra: number; fanIn: number; fanOut: number }> {
-  const dirEdgeCounts = new Map<string, { intra: number; fanIn: number; fanOut: number }>();
-  for (const dir of allDirs) {
-    dirEdgeCounts.set(dir, { intra: 0, fanIn: 0, fanOut: 0 });
-  }
+  const dirEdgeCounts = initDirEdgeCounts(allDirs);
   for (const { source_file, target_file } of importEdges) {
     const srcDirs = fileToAncestorDirs.get(source_file);
     const tgtDirs = fileToAncestorDirs.get(target_file);
     if (!srcDirs && !tgtDirs) continue;
-
-    if (srcDirs) {
-      for (const dir of srcDirs) {
-        const counts = dirEdgeCounts.get(dir);
-        if (!counts) continue;
-        if (tgtDirs?.has(dir)) {
-          counts.intra++;
-        } else {
-          counts.fanOut++;
-        }
-      }
-    }
-    if (tgtDirs) {
-      for (const dir of tgtDirs) {
-        if (srcDirs?.has(dir)) continue;
-        const counts = dirEdgeCounts.get(dir);
-        if (!counts) continue;
-        counts.fanIn++;
-      }
-    }
+    if (srcDirs) accumulateSrcDirCounts(srcDirs, tgtDirs, dirEdgeCounts);
+    if (tgtDirs) accumulateTgtDirCounts(tgtDirs, srcDirs, dirEdgeCounts);
   }
   return dirEdgeCounts;
 }
@@ -541,15 +580,50 @@ interface CallableNodeRow {
   fan_out: number;
 }
 
-/** Build the activeFiles set: files with at least one callable connected to the graph. */
-function buildActiveFilesSet(rows: CallableNodeRow[]): Set<string> {
+/**
+ * Kinds that are consumed via annotations/references rather than calls.
+ * These do not count as "active callables" for the hasActiveFileSiblings heuristic.
+ */
+const ANNOTATION_ONLY_KINDS = new Set([
+  'constant',
+  'struct',
+  'enum',
+  'trait',
+  'type',
+  'interface',
+  'record',
+]);
+
+/**
+ * Build two active-files sets from callable rows:
+ *
+ * - `activeFiles`: files with at least one non-annotation-only callable with
+ *   `fan_in > 0 || fan_out > 0`. Used for annotation-only kinds (constants,
+ *   type defs) which have no callers by design.
+ *
+ * - `calledActiveFiles`: files with at least one non-annotation-only callable
+ *   with `fan_in > 0` (strictly called). Used for method/function kinds to
+ *   prevent a self-sibling loop: a function with `fanIn=0, fanOut>0` as the
+ *   only callable in its file must NOT count itself as an "active sibling" and
+ *   thus promote itself to `leaf`.
+ */
+function buildActiveFilesSet(rows: CallableNodeRow[]): {
+  activeFiles: Set<string>;
+  calledActiveFiles: Set<string>;
+} {
   const activeFiles = new Set<string>();
+  const calledActiveFiles = new Set<string>();
   for (const r of rows) {
-    if ((r.fan_in > 0 || r.fan_out > 0) && r.kind !== 'constant') {
-      activeFiles.add(r.file);
+    if (!ANNOTATION_ONLY_KINDS.has(r.kind)) {
+      if (r.fan_in > 0 || r.fan_out > 0) {
+        activeFiles.add(r.file);
+      }
+      if (r.fan_in > 0) {
+        calledActiveFiles.add(r.file);
+      }
     }
   }
-  return activeFiles;
+  return { activeFiles, calledActiveFiles };
 }
 
 /** Map callable rows to classifier input objects, attaching exported/prod-fan-in/active-file metadata. */
@@ -558,6 +632,7 @@ function buildClassifierInput(
   exportedIds: Set<number>,
   prodFanInMap: Map<number, number>,
   activeFiles: Set<string>,
+  calledActiveFiles: Set<string>,
 ): Array<{
   id: string;
   name: string;
@@ -578,7 +653,20 @@ function buildClassifierInput(
     fanOut: r.fan_out,
     isExported: exportedIds.has(r.id),
     productionFanIn: prodFanInMap.get(r.id) || 0,
-    hasActiveFileSiblings: r.kind === 'constant' ? activeFiles.has(r.file) : undefined,
+    // Set hasActiveFileSiblings for annotation-only kinds (constants, type defs)
+    // AND for method/function — the latter two can have fanIn === 0 due to
+    // untraced call-site patterns (interface dispatch, logical-or defaults).
+    // The classifier interprets this field differently per kind (see classifyUnreferencedNode).
+    //
+    // IMPORTANT: method/function use calledActiveFiles (fan_in > 0 only) to
+    // prevent a self-sibling false negative: a function with fanIn=0, fanOut>0
+    // as the sole callable in its file must NOT see its own file as "active"
+    // and promote itself to leaf.
+    hasActiveFileSiblings: ANNOTATION_ONLY_KINDS.has(r.kind)
+      ? activeFiles.has(r.file)
+      : r.kind === 'method' || r.kind === 'function'
+        ? calledActiveFiles.has(r.file)
+        : undefined,
   }));
 }
 
@@ -660,7 +748,8 @@ function readCachedMedians(db: BetterSqlite3Database): { fanIn: number; fanOut:
     )
       return null;
     return { fanIn: cached.fanIn, fanOut: cached.fanOut };
-  } catch {
+  } catch (e) {
+    debug(`readCachedMedians: failed to parse cached medians — ${e}`);
     return null;
   }
 }
@@ -761,6 +850,20 @@ function classifyNodeRolesFull(db: BetterSqlite3Database, emptySummary: RoleSumm
     .all() as { id: number }[];
   for (const r of reexportExported) exportedIds.add(r.id);
 
+  // Mark symbols with exported=1 as exported — the extractor sets this flag when the
+  // author writes `export interface Foo { }` / `export type Bar = ...` / `export function`.
+  // Cross-file edge inference misses these when the symbol is only used as a type annotation
+  // within the same file (no calls/imports-type edge is produced for same-file type usage).
+  // This fixes false dead-unresolved classification for exported interfaces with no external callers (#1583).
+  const explicitlyExported = db
+    .prepare(
+      `SELECT id FROM nodes
+      WHERE exported = 1
+        AND kind NOT IN ('file', 'directory', 'parameter', 'property')`,
+    )
+    .all() as { id: number }[];
+  for (const r of explicitlyExported) exportedIds.add(r.id);
+
   // Compute production fan-in (excluding callers in test files)
   const prodFanInMap = new Map<number, number>();
   const prodRows = db
@@ -781,8 +884,14 @@ function classifyNodeRolesFull(db: BetterSqlite3Database, emptySummary: RoleSumm
   // Compute medians from the already-loaded rows (no extra DB round-trip),
   // pass them as overrides to avoid recomputing inside classifyRoles,
   // and cache them for subsequent incremental builds.
-  const activeFiles = buildActiveFilesSet(rows);
-  const classifierInput = buildClassifierInput(rows, exportedIds, prodFanInMap, activeFiles);
+  const { activeFiles, calledActiveFiles } = buildActiveFilesSet(rows);
+  const classifierInput = buildClassifierInput(
+    rows,
+    exportedIds,
+    prodFanInMap,
+    activeFiles,
+    calledActiveFiles,
+  );
   const nonZeroFanIn = classifierInput
     .filter((n) => n.fanIn > 0)
     .map((n) => n.fanIn)
@@ -928,6 +1037,21 @@ function classifyNodeRolesIncremental(
     .all(...allAffectedFiles) as { id: number }[];
   for (const r of reexportExported) exportedIds.add(r.id);
 
+  // 3c. Mark symbols with exported=1 as exported — the extractor sets this flag when the
+  // author writes `export interface Foo { }` / `export type Bar = ...` / `export function`.
+  // Cross-file edge inference misses these when the symbol is only used as a type annotation
+  // within the same file (no calls/imports-type edge is produced for same-file type usage).
+  // Scoped to affected files only for the incremental path (#1583).
+  const explicitlyExported = db
+    .prepare(
+      `SELECT id FROM nodes
+      WHERE exported = 1
+        AND kind NOT IN ('file', 'directory', 'parameter', 'property')
+        AND file IN (${placeholders})`,
+    )
+    .all(...allAffectedFiles) as { id: number }[];
+  for (const r of explicitlyExported) exportedIds.add(r.id);
+
   // 4. Production fan-in for affected nodes only
   const prodFanInMap = new Map<number, number>();
   const prodRows = db
@@ -947,8 +1071,14 @@ function classifyNodeRolesIncremental(
   }
 
   // 5. Classify affected nodes using global medians
-  const activeFiles = buildActiveFilesSet(rows);
-  const classifierInput = buildClassifierInput(rows, exportedIds, prodFanInMap, activeFiles);
+  const { activeFiles, calledActiveFiles } = buildActiveFilesSet(rows);
+  const classifierInput = buildClassifierInput(
+    rows,
+    exportedIds,
+    prodFanInMap,
+    activeFiles,
+    calledActiveFiles,
+  );
   const roleMap = classifyRoles(classifierInput, globalMedians);
 
   // 6. Build summary (only for affected nodes) and update only those nodes

package/src/features/triage.ts

@@ -116,6 +116,33 @@ interface TriageDataOpts {
   repo?: Repository;
 }
 
+interface ResolvedRiskConfig {
+  weights: RiskWeights;
+  riskOpts: { roleWeights?: Record<string, number>; defaultRoleWeight?: number };
+}
+
+/** Resolve risk weights and role-weight options from config + opts overrides. */
+function resolveRiskConfig(opts: TriageDataOpts): ResolvedRiskConfig {
+  const config = opts.config || loadConfig();
+  const riskConfig = ((config as unknown as Record<string, unknown>).risk || {}) as {
+    weights?: Partial<RiskWeights>;
+    roleWeights?: Record<string, number>;
+    defaultRoleWeight?: number;
+  };
+  const weights: RiskWeights = {
+    ...DEFAULT_WEIGHTS,
+    ...(riskConfig.weights || {}),
+    ...(opts.weights || {}),
+  };
+  return {
+    weights,
+    riskOpts: {
+      roleWeights: riskConfig.roleWeights,
+      defaultRoleWeight: riskConfig.defaultRoleWeight,
+    },
+  };
+}
+
 export function triageData(
   customDbPath?: string,
   opts: TriageDataOpts = {},
@@ -125,21 +152,7 @@ export function triageData(
     const noTests = opts.noTests || false;
     const minScore = opts.minScore != null ? Number(opts.minScore) : null;
     const sort = opts.sort || 'risk';
-    const config = opts.config || loadConfig();
-    const riskConfig = ((config as unknown as Record<string, unknown>).risk || {}) as {
-      weights?: Partial<RiskWeights>;
-      roleWeights?: Record<string, number>;
-      defaultRoleWeight?: number;
-    };
-    const weights: RiskWeights = {
-      ...DEFAULT_WEIGHTS,
-      ...(riskConfig.weights || {}),
-      ...(opts.weights || {}),
-    };
-    const riskOpts = {
-      roleWeights: riskConfig.roleWeights,
-      defaultRoleWeight: riskConfig.defaultRoleWeight,
-    };
+    const { weights, riskOpts } = resolveRiskConfig(opts);
 
     let rows: TriageNodeRow[];
     try {

package/src/graph/algorithms/bfs.ts

@@ -6,10 +6,17 @@ export interface BfsOpts {
   direction?: 'forward' | 'backward' | 'both';
 }
 
+/** Resolve the neighbor list for a node given traversal direction. */
+function getNeighbors(graph: CodeGraph, node: string, direction: string): string[] {
+  if (direction === 'forward') return graph.successors(node);
+  if (direction === 'backward') return graph.predecessors(node);
+  return graph.neighbors(node);
+}
+
 /**
  * Breadth-first traversal on a CodeGraph.
  *
- * Tries the native Rust implementation first, falls back to JS.
+ * Tries the native Rust implementation first, falls back to a pure-JS queue.
  *
  * @returns nodeId → depth from nearest start node
  */
@@ -46,7 +53,10 @@ export function bfs(
   return bfsJS(graph, starts, maxDepth, direction);
 }
 
-/** Pure JS fallback for BFS (used when native addon is unavailable). */
+/**
+ * Pure-JS BFS queue (used when native addon is unavailable).
+ * Separated from bfs() to keep each function's complexity within thresholds.
+ */
 function bfsJS(
   graph: CodeGraph,
   starts: string[],
@@ -70,16 +80,7 @@ function bfsJS(
     const depth = depths.get(current)!;
     if (depth >= maxDepth) continue;
 
-    let neighbors: string[];
-    if (direction === 'forward') {
-      neighbors = graph.successors(current);
-    } else if (direction === 'backward') {
-      neighbors = graph.predecessors(current);
-    } else {
-      neighbors = graph.neighbors(current);
-    }
-
-    for (const n of neighbors) {
+    for (const n of getNeighbors(graph, current, direction)) {
       if (!depths.has(n)) {
         depths.set(n, depth + 1);
         queue.push(n);

package/src/graph/algorithms/tarjan.ts

@@ -15,6 +15,7 @@ export function tarjan(graph: CodeGraph): string[][] {
   const sccs: string[][] = [];
 
   function strongconnect(v: string): void {
+    // Assign the next discovery index and initialise lowlink to self
     indices.set(v, index);
     lowlinks.set(v, index);
     index++;
@@ -23,13 +24,16 @@ export function tarjan(graph: CodeGraph): string[][] {
 
     for (const w of graph.successors(v)) {
       if (!indices.has(w)) {
+        // Tree edge: recurse then propagate lowlink upward
         strongconnect(w);
         lowlinks.set(v, Math.min(lowlinks.get(v)!, lowlinks.get(w)!));
       } else if (onStack.has(w)) {
+        // Back/cross edge to a node still on the stack: update lowlink via index
         lowlinks.set(v, Math.min(lowlinks.get(v)!, indices.get(w)!));
       }
     }
 
+    // v is the root of an SCC when its lowlink equals its own discovery index
     if (lowlinks.get(v) === indices.get(v)) {
       const scc: string[] = [];
       let w: string | undefined;
@@ -38,6 +42,7 @@ export function tarjan(graph: CodeGraph): string[][] {
         onStack.delete(w);
         scc.push(w);
       } while (w !== v);
+      // Only report non-trivial SCCs (length > 1 = a real cycle)
       if (scc.length > 1) sccs.push(scc);
     }
   }

package/src/graph/builders/dependency.ts

@@ -78,6 +78,37 @@ interface MinConfidenceEdgeRow {
   target_id: number;
 }
 
+/**
+ * Fetch call edges from `dbOrRepo`, optionally filtered by a minimum confidence
+ * threshold. When `minConfidence` is unset, all call edges are returned.
+ */
+function resolveCallEdges(
+  dbOrRepo: BetterSqlite3Database | Repository,
+  isRepo: boolean,
+  minConfidence?: number,
+): CallEdgeRow[] | MinConfidenceEdgeRow[] {
+  if (minConfidence == null) {
+    return isRepo
+      ? (dbOrRepo as Repository).getCallEdges()
+      : getCallEdges(dbOrRepo as BetterSqlite3Database);
+  }
+  if (isRepo) {
+    // Trade-off: Repository.getCallEdges() returns all call edges, so we
+    // filter in JS. This is O(all call edges) rather than the SQL path's
+    // indexed WHERE clause. Acceptable for current data sizes; a dedicated
+    // getCallEdgesByMinConfidence(threshold) method on the Repository
+    // interface would be the proper fix if this becomes a bottleneck.
+    return (dbOrRepo as Repository)
+      .getCallEdges()
+      .filter((e) => e.confidence != null && e.confidence >= minConfidence);
+  }
+  return (dbOrRepo as BetterSqlite3Database)
+    .prepare<MinConfidenceEdgeRow>(
+      "SELECT source_id, target_id FROM edges WHERE kind = 'calls' AND confidence >= ?",
+    )
+    .all(minConfidence);
+}
+
 function buildFunctionLevelGraph(
   dbOrRepo: BetterSqlite3Database | Repository,
   noTests: boolean,
@@ -86,7 +117,9 @@ function buildFunctionLevelGraph(
   const graph = new CodeGraph();
   const isRepo = dbOrRepo instanceof Repository;
 
-  let nodes: CallableNodeRow[] = isRepo ? dbOrRepo.getCallableNodes() : getCallableNodes(dbOrRepo);
+  let nodes: CallableNodeRow[] = isRepo
+    ? (dbOrRepo as Repository).getCallableNodes()
+    : getCallableNodes(dbOrRepo as BetterSqlite3Database);
   if (noTests) nodes = nodes.filter((n) => !isTestFile(n.file));
 
   const nodeIds = new Set<number>();
@@ -100,28 +133,7 @@ function buildFunctionLevelGraph(
     nodeIds.add(n.id);
   }
 
-  let edges: CallEdgeRow[] | MinConfidenceEdgeRow[];
-  if (minConfidence != null) {
-    if (isRepo) {
-      // Trade-off: Repository.getCallEdges() returns all call edges, so we
-      // filter in JS. This is O(all call edges) rather than the SQL path's
-      // indexed WHERE clause. Acceptable for current data sizes; a dedicated
-      // getCallEdgesByMinConfidence(threshold) method on the Repository
-      // interface would be the proper fix if this becomes a bottleneck.
-      edges = dbOrRepo
-        .getCallEdges()
-        .filter((e) => e.confidence != null && e.confidence >= minConfidence);
-    } else {
-      edges = (dbOrRepo as BetterSqlite3Database)
-        .prepare<MinConfidenceEdgeRow>(
-          "SELECT source_id, target_id FROM edges WHERE kind = 'calls' AND confidence >= ?",
-        )
-        .all(minConfidence);
-    }
-  } else {
-    edges = isRepo ? dbOrRepo.getCallEdges() : getCallEdges(dbOrRepo);
-  }
-
+  const edges = resolveCallEdges(dbOrRepo, isRepo, minConfidence);
   for (const e of edges) {
     if (!nodeIds.has(e.source_id) || !nodeIds.has(e.target_id)) continue;
     const src = String(e.source_id);

package/src/graph/classifiers/roles.ts

@@ -18,6 +18,14 @@ export const FRAMEWORK_ENTRY_PREFIXES: readonly string[] = ['route:', 'event:',
 
 const LEAF_KINDS = new Set(['parameter', 'property', 'constant']);
 
+/**
+ * Type definition kinds that are consumed via type annotations rather than calls.
+ * These have no inbound call edges by design — they are "used" by type references,
+ * struct literals, and generic parameters, none of which produce call edges.
+ * If the same file has active callables, type definitions are almost certainly live.
+ */
+const TYPE_DEF_KINDS = new Set(['struct', 'enum', 'trait', 'type', 'interface', 'record']);
+
 const FFI_EXTENSIONS = new Set(['.rs', '.c', '.cpp', '.h', '.go', '.java', '.cs']);
 
 /** Path patterns indicating framework-dispatched entry points. */
@@ -29,6 +37,17 @@ const ENTRY_PATH_PATTERNS: readonly RegExp[] = [
   /middleware[/\\]/,
 ];
 
+/**
+ * Well-known Commander.js dispatch method names.
+ * When a method with one of these names lives in a file that matches
+ * ENTRY_PATH_PATTERNS, it is the actual framework entry point — not merely a
+ * candidate — so it must be classified as `entry` rather than `dead-entry`.
+ *
+ * `execute` — the action callback invoked by Commander on `program.action()`.
+ * `validate` — a pre-execution argument/option validator called before `execute`.
+ */
+const COMMANDER_DISPATCH_NAMES = new Set(['execute', 'validate']);
+
 export interface ClassifiableNode {
   kind?: string;
   file?: string;
@@ -74,7 +93,16 @@ export interface RoleClassificationNode {
   isExported: boolean;
   testOnlyFanIn?: number;
   productionFanIn?: number;
-  /** True when the same file contains at least one non-constant callable connected to the graph (fanIn > 0 or fanOut > 0). */
+  /**
+   * True when the same file contains at least one callable connected to the graph
+   * (fanIn > 0 or fanOut > 0) that is not itself an annotation-only kind.
+   * Annotation-only kinds are `constant` and all members of `TYPE_DEF_KINDS`
+   * (struct, enum, trait, type, interface, record) — these are excluded because
+   * they are consumed via references/type-annotations rather than call edges and
+   * would otherwise produce a circular dependency in the active-file heuristic.
+   * Populated only for `constant` and `TYPE_DEF_KINDS` nodes; `undefined` for
+   * regular callables (functions, methods, classes, etc.) which don't need it.
+   */
   hasActiveFileSiblings?: boolean;
 }
 
@@ -99,11 +127,37 @@ function computeFanMedians(nodes: RoleClassificationNode[]): { fanIn: number; fa
  * Covers framework-active constants, test-only callables, and the dead-* family.
  */
 function classifyUnreferencedNode(node: RoleClassificationNode): Role {
-  if (node.kind === 'constant' && node.hasActiveFileSiblings) {
-    // Constants consumed via identifier reference (not calls) have no
-    // inbound call edges. If the same file has active callables, the
-    // constant is almost certainly used locally — classify as leaf.
-    return 'leaf';
+  if (node.hasActiveFileSiblings) {
+    if (node.kind === 'constant') {
+      // Constants consumed via identifier reference (not calls) have no
+      // inbound call edges. If the same file has active callables, the
+      // constant is almost certainly used locally — classify as leaf.
+      return 'leaf';
+    }
+    if (node.kind && TYPE_DEF_KINDS.has(node.kind)) {
+      // Type definitions (struct, enum, trait, type, interface, record) are
+      // consumed via type annotations and struct literals — not calls — so they
+      // never get inbound call edges. If the same file has active callables,
+      // these types are almost certainly live — classify as leaf.
+      return 'leaf';
+    }
+    if (node.kind === 'method' && node.fanOut > 0) {
+      // Methods implementing interfaces are dispatched via conditional property
+      // access e.g. `if (v.enterFunction) v.enterFunction(...)`. Codegraph
+      // resolves the call to the property accessor rather than to the concrete
+      // method implementation, so the method has no inbound call edge. We
+      // require `fanOut > 0` as evidence of non-triviality, mirroring the
+      // function case — trivially-inert dead helper methods remain visible.
+      return 'leaf';
+    }
+    if (node.kind === 'function' && node.fanOut > 0) {
+      // Functions referenced as logical-or fallback defaults — e.g.
+      // `const fn = options._fetchLatest || fetchLatestVersion` — appear as
+      // value references, not call sites, so no call edge is produced. We
+      // require `fanOut > 0` as evidence that the function is non-trivial
+      // (i.e. it calls something), ruling out truly inert dead helpers.
+      return 'leaf';
+    }
   }
   if (node.testOnlyFanIn != null && node.testOnlyFanIn > 0) return 'test-only';
   return classifyDeadSubRole(node);
@@ -129,7 +183,20 @@ function classifyNodeRole(node: RoleClassificationNode, medFanIn: number, medFan
   if (FRAMEWORK_ENTRY_PREFIXES.some((p) => node.name.startsWith(p))) return 'entry';
 
   if (node.fanIn === 0) {
-    return node.isExported ? 'entry' : classifyUnreferencedNode(node);
+    if (!node.isExported) {
+      // Well-known Commander.js dispatch methods (execute, validate) in framework
+      // directories are confirmed entry points, not candidates. Promote them to
+      // `entry` directly so they don't appear in `--role dead` output.
+      if (
+        node.file &&
+        COMMANDER_DISPATCH_NAMES.has(node.name) &&
+        ENTRY_PATH_PATTERNS.some((p) => p.test(node.file!))
+      ) {
+        return 'entry';
+      }
+      return classifyUnreferencedNode(node);
+    }
+    return 'entry';
   }
 
   const hasProdFanIn = typeof node.productionFanIn === 'number';

package/src/index.ts

@@ -52,7 +52,11 @@ export { ownersData } from './features/owners.js';
 export { sequenceData } from './features/sequence.js';
 export { hotspotsData, moduleBoundariesData, structureData } from './features/structure.js';
 export { triageData } from './features/triage.js';
-export { loadConfig } from './infrastructure/config.js';
+export {
+  loadConfig,
+  loadConfigWithProvenance,
+  resolveUserConfigPath,
+} from './infrastructure/config.js';
 export type { ArrayCompatSet } from './shared/constants.js';
 export { EXTENSIONS, IGNORE_DIRS } from './shared/constants.js';
 export {