fix: restrict entry-role classification to function/method-kind symbols (docs check acknowledged)

codegraph roles --role entry classified any exported, zero-fan-in node as
`entry` regardless of kind, so non-exported interfaces/constants (e.g.
ParsedUserConfig, WorkspaceEntry, _configCache in config.ts) were also
sweeping into the entry bucket via a separate bug: the barrel-reexport-chain
"exported" inference (#837) marks every symbol in a re-exported file as
exported, including symbols that were never independently exportable
(class/interface methods) and symbols without the `export` keyword.

Two fixes, mirrored in the TS classifier and the Rust native engine:

- classifyNodeRole / classify_node: the exported+zero-fan-in branch now
  requires kind IN ('function', 'method') to return `entry`. Every other
  exported kind (interface/type/constant/class) is classified `leaf` instead
  — a live, intentional part of the public surface, but not something
  invoked from outside the codebase. This also refines two #1583 cases
  (exported interface with same-file-only type usage) from `entry` to the
  more accurate `leaf`, while keeping their "never dead" guarantee intact.

- classifyNodeRolesFull / classifyNodeRolesIncremental (structure.ts) and
  do_classify_full / do_classify_incremental (roles.rs): exclude `method`
  from the barrel-reexport-chain exported-inference query. A `reexports`
  edge only ever concerns top-level module bindings, so a class method can
  never be an independently re-exportable binding — without this exclusion,
  abstract base-class methods (e.g. Repository.findNodeById) were promoted
  to `entry` merely because a sibling symbol in the same file was
  re-exported through a barrel.

Verified real entry points are unaffected: CLI command execute/validate
methods, MCP tool handlers, ESM loader hooks, and event:/route:/command:
framework-prefixed handlers all still classify as `entry`.

Symptom 2 from the same issue (dead-unresolved for LanguageRules interface
members in visitor-utils.ts) was already fully fixed by #1723's
isTypeDeclarationMember exemption — verified via fresh build, no changes
needed.

Fixes #1780

Impact: 3 functions changed, 4 affected

Author: carlos-alm

crates/codegraph-core/src/graph/classifiers/roles.rs

@@ -256,7 +256,20 @@ fn classify_node(
     }
 
     if fan_in == 0 && is_exported {
-        return "entry";
+        // Exported, zero fan-in. A genuine entry point (CLI command handler,
+        // exported API function called from outside the codebase, ESM loader
+        // hook, MCP tool handler, etc.) is always a function or method. Every
+        // other exported kind (interface/type/constant/class) is a live,
+        // intentional part of the public surface — but a data shape or config
+        // value, not something invoked from outside the codebase — so it's
+        // `leaf`: never `dead-*` (#1583) and never `entry` (#1780), regardless
+        // of whether the file has other active siblings. Mirrors JS
+        // `classifyNodeRole`.
+        return if kind == "function" || kind == "method" {
+            "entry"
+        } else {
+            "leaf"
+        };
     }
 
     // Test-only: has callers but all are in test files
@@ -403,6 +416,15 @@ pub(crate) fn do_classify_full(conn: &Connection) -> rusqlite::Result<RoleSummar
     //     (e.g. index.ts re-exports from internal.ts which re-exports from core.ts).
     // Then: any symbol whose file is a reexport target of a prod-reachable barrel
     // is considered exported (prevents false dead-code classification).
+    //
+    // `method` is excluded (#1780): a `reexports` edge only ever concerns
+    // top-level module bindings (functions, classes, types, constants, ...) —
+    // a class/interface method can never be an independently re-exportable
+    // binding on its own, so inheriting "exported" status from a co-located
+    // top-level re-export is a category error. Without this exclusion, e.g. an
+    // abstract base class's zero-fan-in method declarations were promoted to
+    // `entry` merely because some other symbol in the same file was re-exported
+    // through a barrel.
     {
         let sql = format!(
             "WITH RECURSIVE prod_reachable(file_id) AS (
@@ -426,7 +448,7 @@ pub(crate) fn do_classify_full(conn: &Connection) -> rusqlite::Result<RoleSummar
                 WHERE e.kind = 'reexports'
                   AND e.source_id IN (SELECT file_id FROM prod_reachable)
               )
-              AND n.kind NOT IN ('file', 'directory', 'parameter', 'property')",
+              AND n.kind NOT IN ('file', 'directory', 'parameter', 'property', 'method')",
             test_file_filter_col("src.file")
         );
         let mut stmt = tx.prepare(&sql)?;
@@ -810,6 +832,7 @@ pub(crate) fn do_classify_incremental(
     // from production-reachable barrels (traces through multi-level chains) (#837).
     // Same recursive CTE logic as the full-classify path (step 3b), but scoped
     // to affected files only via the additional `AND n.file IN (...)` filter.
+    // `method` is excluded (#1780) — see the full-classify path for rationale.
     {
         let reexport_sql = format!(
             "WITH RECURSIVE prod_reachable(file_id) AS (
@@ -833,7 +856,7 @@ pub(crate) fn do_classify_incremental(
                 WHERE e.kind = 'reexports'
                   AND e.source_id IN (SELECT file_id FROM prod_reachable)
               )
-              AND n.kind NOT IN ('file', 'directory', 'parameter', 'property')
+              AND n.kind NOT IN ('file', 'directory', 'parameter', 'property', 'method')
               AND n.file IN ({})",
             test_file_filter_col("src.file"),
             affected_ph

src/features/structure.ts

@@ -816,6 +816,15 @@ function classifyNodeRolesFull(db: BetterSqlite3Database, emptySummary: RoleSumm
 
   // Mark symbols as exported when their files are targets of reexports edges
   // from production-reachable barrels (traces through multi-level chains) (#837)
+  //
+  // `method` is excluded (#1780): a `reexports` edge only ever concerns
+  // top-level module bindings (functions, classes, types, constants, ...) — a
+  // class/interface method can never be an independently re-exportable
+  // binding on its own, so inheriting "exported" status from a co-located
+  // top-level re-export is a category error. Without this exclusion, e.g. an
+  // abstract base class's zero-fan-in method declarations were promoted to
+  // `entry` merely because some other symbol in the same file was re-exported
+  // through a barrel.
   const reexportExported = db
     .prepare(
       `WITH RECURSIVE prod_reachable(file_id) AS (
@@ -839,7 +848,7 @@ function classifyNodeRolesFull(db: BetterSqlite3Database, emptySummary: RoleSumm
         WHERE e.kind = 'reexports'
           AND e.source_id IN (SELECT file_id FROM prod_reachable)
       )
-      AND n.kind NOT IN ('file', 'directory', 'parameter', 'property')`,
+      AND n.kind NOT IN ('file', 'directory', 'parameter', 'property', 'method')`,
     )
     .all() as { id: number }[];
   for (const r of reexportExported) exportedIds.add(r.id);
@@ -1004,6 +1013,7 @@ function classifyNodeRolesIncremental(
 
   // 3b. Mark symbols as exported when their files are targets of reexports edges
   // from production-reachable barrels (traces through multi-level chains) (#837)
+  // `method` is excluded (#1780) — see classifyNodeRolesFull for rationale.
   const reexportExported = db
     .prepare(
       `WITH RECURSIVE prod_reachable(file_id) AS (
@@ -1027,7 +1037,7 @@ function classifyNodeRolesIncremental(
         WHERE e.kind = 'reexports'
           AND e.source_id IN (SELECT file_id FROM prod_reachable)
       )
-      AND n.kind NOT IN ('file', 'directory', 'parameter', 'property')
+      AND n.kind NOT IN ('file', 'directory', 'parameter', 'property', 'method')
       AND n.file IN (${placeholders})`,
     )
     .all(...allAffectedFiles) as { id: number }[];

src/graph/classifiers/roles.ts

@@ -21,6 +21,13 @@
  * `isTypeDeclarationMember` and classified `leaf` unconditionally — they can
  * never gain inbound call edges by construction, so call-graph reachability
  * doesn't apply to them either (#1723).
+ *
+ * `entry` requires `kind IN ('function', 'method')` (plus the framework-prefix/
+ * Commander-dispatch shortcuts, which are already kind-appropriate by
+ * construction). An exported interface/type/constant/class with zero fan-in is
+ * a data-shape declaration or config value — never invoked from outside the
+ * codebase — so it can't be a real entry point; it's classified `leaf` instead
+ * of inheriting `entry` merely from being exported (#1780).
  */
 
 import type { DeadSubRole, Role } from '../../types.js';
@@ -281,7 +288,14 @@ function classifyNodeRole(
       }
       return classifyUnreferencedNode(node);
     }
-    return 'entry';
+    // Exported, zero fan-in. A genuine entry point (CLI command handler, exported
+    // API function called from outside the codebase, ESM loader hook, MCP tool
+    // handler, etc.) is always a function or method. Every other exported kind
+    // (interface/type/constant/class) is a live, intentional part of the public
+    // surface — but a data shape or config value, not something invoked from
+    // outside the codebase — so it's `leaf`: never `dead-*` (#1583) and never
+    // `entry` (#1780), regardless of whether the file has other active siblings.
+    return node.kind === 'function' || node.kind === 'method' ? 'entry' : 'leaf';
   }
 
   const hasProdFanIn = typeof node.productionFanIn === 'number';

tests/graph/classifiers/roles.test.ts

@@ -6,8 +6,10 @@ describe('classifyRoles', () => {
     expect(classifyRoles([]).size).toBe(0);
   });
 
-  it('classifies entry nodes (no fan-in, exported)', () => {
-    const nodes = [{ id: '1', name: 'init', fanIn: 0, fanOut: 3, isExported: true }];
+  it('classifies entry nodes (no fan-in, exported, function kind)', () => {
+    const nodes = [
+      { id: '1', name: 'init', kind: 'function', fanIn: 0, fanOut: 3, isExported: true },
+    ];
     const roles = classifyRoles(nodes);
     expect(roles.get('1')).toBe('entry');
   });
@@ -628,4 +630,140 @@ describe('classifyRoles', () => {
     const roles = classifyRoles(nodes);
     expect(roles.get('2')).toBe('dead-unresolved');
   });
+
+  // ── entry role requires function/method kind (#1780) ───────────────
+
+  it('classifies an exported interface with zero fan-in as leaf, not entry', () => {
+    // Mirrors the #1780 repro: `interface ParsedUserConfig { ... }` in
+    // src/infrastructure/config.ts. Even if the symbol were exported, an
+    // interface is a data-shape declaration, never a callable entry point.
+    const nodes = [
+      {
+        id: '1',
+        name: 'ParsedUserConfig',
+        kind: 'interface',
+        file: 'src/infrastructure/config.ts',
+        fanIn: 0,
+        fanOut: 0,
+        isExported: true,
+      },
+    ];
+    const roles = classifyRoles(nodes);
+    expect(roles.get('1')).toBe('leaf');
+  });
+
+  it('classifies an exported constant with zero fan-in as leaf, not entry', () => {
+    // Mirrors the #1780 repro: module-level `const BUILD_HASH_KEYS = [...]`.
+    // A constant can never be an invoked entry point regardless of export status.
+    const nodes = [
+      {
+        id: '1',
+        name: 'BUILD_HASH_KEYS',
+        kind: 'constant',
+        file: 'src/infrastructure/config.ts',
+        fanIn: 0,
+        fanOut: 0,
+        isExported: true,
+      },
+    ];
+    const roles = classifyRoles(nodes);
+    expect(roles.get('1')).toBe('leaf');
+  });
+
+  it('classifies an exported class with zero fan-in as leaf, not entry', () => {
+    // A class declaration itself is instantiated via `new`, not "invoked" the
+    // way a CLI command handler or API function is — not a real entry point.
+    const nodes = [
+      {
+        id: '1',
+        name: 'Widget',
+        kind: 'class',
+        file: 'src/widget.ts',
+        fanIn: 0,
+        fanOut: 0,
+        isExported: true,
+      },
+    ];
+    const roles = classifyRoles(nodes);
+    expect(roles.get('1')).toBe('leaf');
+  });
+
+  it('classifies an exported type alias with zero fan-in as leaf, not entry', () => {
+    const nodes = [
+      {
+        id: '1',
+        name: 'WorkspaceEntry',
+        kind: 'type',
+        file: 'src/infrastructure/config.ts',
+        fanIn: 0,
+        fanOut: 0,
+        isExported: true,
+      },
+    ];
+    const roles = classifyRoles(nodes);
+    expect(roles.get('1')).toBe('leaf');
+  });
+
+  it('still classifies an exported function with zero fan-in as entry (no over-correction)', () => {
+    // Genuine entry points (CLI handlers, MCP tool handlers, ESM loader hooks)
+    // are, by definition, called from outside the codebase, so zero in-repo
+    // fan-in is expected and correct for them — the fix must not lose this.
+    const nodes = [
+      {
+        id: '1',
+        name: 'handler',
+        kind: 'function',
+        file: 'src/mcp/tools/audit.ts',
+        fanIn: 0,
+        fanOut: 4,
+        isExported: true,
+      },
+    ];
+    const roles = classifyRoles(nodes);
+    expect(roles.get('1')).toBe('entry');
+  });
+
+  it('still classifies an exported method with zero fan-in as entry (no over-correction)', () => {
+    const nodes = [
+      {
+        id: '1',
+        name: 'run',
+        kind: 'method',
+        file: 'src/cli/commands/custom.ts',
+        fanIn: 0,
+        fanOut: 2,
+        isExported: true,
+      },
+    ];
+    const roles = classifyRoles(nodes);
+    expect(roles.get('1')).toBe('entry');
+  });
+
+  it('classifies a non-exported interface with zero fan-in the same as an exported one (leaf, active siblings)', () => {
+    // Whether or not the interface itself is exported, it's still not a
+    // callable entry point — both must land on the same non-entry path.
+    const nodes = [
+      {
+        id: '1',
+        name: 'ConsentResolutionResult',
+        kind: 'interface',
+        file: 'src/infrastructure/config.ts',
+        fanIn: 0,
+        fanOut: 0,
+        isExported: false,
+        hasActiveFileSiblings: true,
+      },
+      {
+        id: '2',
+        name: 'loadConfig',
+        kind: 'function',
+        file: 'src/infrastructure/config.ts',
+        fanIn: 5,
+        fanOut: 3,
+        isExported: true,
+      },
+    ];
+    const roles = classifyRoles(nodes);
+    expect(roles.get('1')).toBe('leaf');
+  });
 });

tests/integration/roles.test.ts

@@ -115,6 +115,9 @@ describe('barrel re-export role classification', () => {
     const _helperFn = insertNode(db, 'helperFn', 'function', 'src/inspect.ts', 30);
     const _appMain = insertNode(db, 'appMain', 'function', 'src/app.ts', 1);
     const testFn = insertNode(db, 'testQueryName', 'function', 'tests/inspect.test.ts', 1);
+    // A class-method-kind member (e.g. an abstract base-class method) in the same
+    // re-exported file, with no callers and no outgoing calls (#1780).
+    const _abstractHelper = insertNode(db, 'abstractHelper', 'method', 'src/inspect.ts', 50);
 
     // Barrel re-exports inspect.ts
     insertEdge(db, fBarrel, fInspect, 'reexports');
@@ -156,6 +159,20 @@ describe('barrel re-export role classification', () => {
     // With fanIn=0 and isExported=true → entry (exported but uncalled)
     expect(helperResult!.role).toBe('entry');
   });
+
+  test('method-kind member in a re-exported file does not inherit exported status (#1780)', () => {
+    // A `reexports` edge only ever concerns top-level module bindings — a class
+    // method can never be an independently re-exportable binding on its own, so
+    // it must not inherit "exported" status merely because a sibling top-level
+    // symbol (helperFn/queryName) in the same file is re-exported through the
+    // barrel. Before the fix, this method landed on `entry` the same way
+    // `helperFn` incorrectly did; it must now fall through to normal dead-code
+    // classification instead (no callers, no outgoing calls → dead-unresolved).
+    const data = rolesData(barrelDbPath);
+    const methodResult = data.symbols.find((s) => s.name === 'abstractHelper');
+    expect(methodResult).toBeDefined();
+    expect(methodResult!.role).toBe('dead-unresolved');
+  });
 });
 
 // ─── Multi-level barrel re-export chain (#837) ───────────────────────

tests/unit/roles.test.ts

@@ -235,7 +235,43 @@ describe('classifyNodeRoles', () => {
 
     classifyNodeRoles(db);
     const role = db.prepare("SELECT role FROM nodes WHERE name = 'MyOpts'").get();
-    // Should be entry (exported, fan-in 0), not dead-unresolved
+    // Should be leaf (exported, fan-in 0), not dead-unresolved. An interface is a
+    // data-shape declaration, never a callable entry point, so exported+zero-fanin
+    // interfaces land on `leaf` rather than `entry` (#1780) — but #1583's original
+    // guarantee (never `dead-*`) still holds.
+    expect(role.role).toBe('leaf');
+  });
+
+  it('classifies exported constant with no callers as leaf, not entry (#1780)', () => {
+    // A module-level constant is a data value, never a callable entry point,
+    // regardless of its exported=1 flag.
+    db.prepare('INSERT INTO nodes (name, kind, file, line, exported) VALUES (?, ?, ?, ?, ?)').run(
+      'DEFAULT_OPTIONS',
+      'constant',
+      'src/helpers.ts',
+      5,
+      1,
+    );
+
+    classifyNodeRoles(db);
+    const role = db.prepare("SELECT role FROM nodes WHERE name = 'DEFAULT_OPTIONS'").get();
+    expect(role.role).toBe('leaf');
+  });
+
+  it('still classifies an exported function with no callers as entry (#1780 no over-correction)', () => {
+    // A genuinely exported, callable function with zero fan-in is exactly what
+    // `entry` is meant to capture — e.g. a public API function invoked only by
+    // external consumers of the package. The kind-gate fix must not lose this.
+    db.prepare('INSERT INTO nodes (name, kind, file, line, exported) VALUES (?, ?, ?, ?, ?)').run(
+      'publicApiFn',
+      'function',
+      'src/helpers.ts',
+      40,
+      1,
+    );
+
+    classifyNodeRoles(db);
+    const role = db.prepare("SELECT role FROM nodes WHERE name = 'publicApiFn'").get();
     expect(role.role).toBe('entry');
   });
 
@@ -364,7 +400,7 @@ describe('classifyNodeRoles', () => {
 
   it('incremental path: does not classify exported interface as dead when used only as same-file type annotation (#1583)', () => {
     // Exercises classifyNodeRolesIncremental (triggered by passing changedFiles).
-    // An exported=1 interface with no cross-file edges must be promoted to entry,
+    // An exported=1 interface with no cross-file edges must be promoted to leaf,
     // not dead-unresolved, on the incremental path just as on the full path.
     db.prepare('INSERT INTO nodes (name, kind, file, line, exported) VALUES (?, ?, ?, ?, ?)').run(
       'IncrementalOpts',
@@ -377,8 +413,9 @@ describe('classifyNodeRoles', () => {
     // Pass the file as the changed-files list to trigger the incremental path.
     classifyNodeRoles(db, ['src/helpers.ts']);
     const role = db.prepare("SELECT role FROM nodes WHERE name = 'IncrementalOpts'").get();
-    // Should be entry (exported, fan-in 0), not dead-unresolved
-    expect(role.role).toBe('entry');
+    // Should be leaf (exported, fan-in 0), not dead-unresolved or entry — an
+    // interface is a data-shape declaration, never a callable entry point (#1780).
+    expect(role.role).toBe('leaf');
   });
 
   // ── Parameters and interface members are not dead-code targets (#1723) ──