Module-qualified symbol lookup (e.g., `stage_apply::run`) returns 'not found' even when symbol is indexed; bare-name lookup silently picks a random collision

[joselhurtado]

Summary

codegraph_callees, codegraph_node, and similar lookup tools return Symbol "stage_apply::run" not found for a function that is in fact indexed (visible via codegraph_files at src/configurator/stage_apply.rs:43).

The bare-name form codegraph_callees run does NOT error, but silently resolves to a completely unrelated run_due_tasks function from another module. Functions with unique names in the same file (e.g., render_and_write) resolve correctly.

Root cause appears to be that the lookup vocabulary does not understand the module_path::symbol qualifier syntax that Rust (and most other languages) use to disambiguate same-named symbols across modules.

Reproduce

Tested on:

• codegraph 0.6.8
• macOS aarch64
• Node v25.5.0

Repo: https://github.com/kernex-dev/kernex-agent (Rust workspace consumer; commit 7eb5d13 is a stable target for this report).

The configurator pipeline at src/configurator/ contains seven sibling modules, each exporting pub async fn run:

stage_detect::run
stage_resolve::run
stage_review::run
stage_backup::run
stage_apply::run
stage_verify::run
stage_report::run

In a session with the codegraph MCP server:

codegraph_callees stage_apply::run
> Symbol "stage_apply::run" not found

codegraph_node stage_apply::run
> Symbol "stage_apply::run" not found

codegraph_callees run
> Symbol resolves to `run_due_tasks` (no callees returned)

codegraph_files src/configurator/stage_apply.rs
> Lists stage_apply.rs with `run` at line 43

codegraph_callees render_and_write
> Works correctly (returns `template_for`, `render`, etc.)

Expected

One of:

1. module_path::symbol resolution: lookup tools accept the canonical Rust-style qualifier stage_apply::run and resolve to the correct symbol.
2. Disambiguated bare-name response: when a bare-name lookup is ambiguous (run matches seven indexed symbols), return all matches with their file paths so the caller can disambiguate, rather than silently picking one.

Either fix would close this. Both would be nicer.

Why this matters

The current behavior makes codegraph less useful in Rust workspaces that use the conventional one-pub fn run-per-module pattern (sub-pipelines, plugin systems, sibling modules with consistent entry points). The user has to fall back to grep/read for these queries, which defeats the productivity claim.

The data is in the index. The lookup vocabulary is the missing piece.

Workaround

For now, work around by calling codegraph_files <path> to get the file's symbol list, then codegraph_node with whatever symbol-ID surface is available. Friction but functional.

Environment

• codegraph: 0.6.8 (installed via npm install -g @colbymchenry/codegraph)
• Node: v25.5.0 (Homebrew)
• macOS: 14+ (Apple Silicon)
• Claude Code: 2.1.143
• Repo language: Rust (edition 2021, 1.74 MSRV)
• Index size: 59 files, 1206 nodes, 1801 edges (62 Rust, 2 Python)

Happy to provide more detail if useful. Thanks for the tool.

[colbymchenry]

Fixed in #179, will ship in 0.7.10.

Two layered bugs, both addressed:

FTS5 tokenization — the query builder was stripping : as a special char without splitting on ::, so stage_apply::run was being searched as the literal stage_applyrun (no matches). It now treats :: as a token separator, so the FTS finds both halves as candidates.

matchesSymbol qualifier vocabulary — only understood .-style qualifiers and required the qualifier to appear inside qualifiedName. Rust file-level functions don't carry their module name in qualifiedName (it's encoded in the file path instead), so even stage_apply.run would have failed. Now accepts ::, ., and / qualifiers, with multi-level composition (crate::configurator::stage_apply::run works, Rust path prefixes crate/super/self are stripped), and falls back to file-path containment when needed.

No more silent fuzzy fallbacks on qualified misses — stage_apply::nonexistent_fn now returns "not found" instead of resolving to an unrelated rollback in the same file.

Verified end-to-end against your repo (cloned kernex-dev/kernex-agent at commit 7eb5d13, 59 files, 1,340 nodes):

findSymbol "stage_apply::run"        -> src/configurator/stage_apply.rs:43  ✓
findSymbol "stage_detect::run"       -> src/configurator/stage_detect.rs:14 ✓
findSymbol "stage_verify::run"       -> src/configurator/stage_verify.rs:36 ✓
findSymbol "stage_apply::nonexistent_fn"  -> NOT FOUND (correct)            ✓
findAllSymbols "run"                 -> 9 matches with disambiguation note  ✓
findSymbol "render_and_write"        -> src/configurator/stage_apply.rs:177 ✓

On the bare-name run concern: 0.7.x already aggregates callees/impact across all matches and surfaces a disambiguation note in _node — the "silently picks run_due_tasks" behaviour you saw on 0.6.8 was a separate older issue. This PR keeps that behaviour and pins it with a test.

Thanks for the report — really clean reproduction with the exact symbol, file, line, and commit. Made this one straightforward to chase down.