Summary
graphify explain "<symbol>" silently returns one arbitrary match when a symbol name is defined in more than one file. There is no ambiguity warning, no match count, and no hint that other candidates exist — so a wrong node is indistinguishable from a right one.
This matters more than a normal wrong answer because explain is the verb users are told to trust. In our internal guidance it is documented as "the only reliably-correct verb" (as opposed to query, which is explicitly a keyword heuristic). A silently-wrong explain result therefore gets cited as fact.
Version
graphify 0.8.14 (graphifyy-0.8.14), graph of ~28,800 nodes over a mixed Python/Rust repo.
Reproduction
In a repo where the same function name is defined in two files:
$ grep -rn "^def run_sweep" --include=*.py src/ scripts/
src/research/loop_runner.py:558:def run_sweep(
scripts/backtesting/sweep_backtest.py:3207:def run_sweep(
Then:
$ graphify explain "run_sweep"
Node: run_sweep()
ID: research_loop_runner_run_sweep
Source: src/research/loop_runner.py L558
Type: code
Community: 837
Degree: 10
The second definition — the one that was actually being asked about, and the larger of the two — is not mentioned. Same behaviour for the very common name main:
$ graphify explain "main"
Node: main()
ID: backtesting_d2l_leg1_metrics_main
Source: src/backtesting/d2l_leg1_metrics.py L474
That repo contains many main() definitions; one is returned with no indication that it was a choice.
What makes this hard to notice
There is no distinguishing signal in the output. A correct result and an arbitrary-pick result are byte-identical in shape, so the only way to detect the mis-anchor is to already know the right answer — which defeats the purpose of asking. Two independent people here cited explain output that pointed at an unrelated file before anyone checked.
Attempted workaround (does not work)
Qualifying the name returns nothing rather than disambiguating:
$ graphify explain "sweep_backtest.run_sweep"
No node matching found
$ graphify explain "path::run_sweep"
No node matching found
So today there is no way to ask for a specific one of several same-named symbols.
Suggested fix, in rough priority order
- When more than one node matches, say so. Even a single line —
3 matches; showing 1. Others: <id> (<path>:<line>), ... — converts a silent wrong answer into an obvious next step.
- Support a qualified lookup so a caller can name the file or module:
explain "src/foo/bar.py:run_sweep" or explain "run_sweep" --in src/foo/bar.py.
- Optionally, a
--all flag that prints every match rather than one.
(1) alone would close the failure mode; (2) makes it actionable.
Why we care
Agent tooling reads explain output and cites it as ground truth. An answer that is wrong and confident is worse for us than no answer, because the "no node matching found" case is at least visibly a miss.
Summary
graphify explain "<symbol>"silently returns one arbitrary match when a symbol name is defined in more than one file. There is no ambiguity warning, no match count, and no hint that other candidates exist — so a wrong node is indistinguishable from a right one.This matters more than a normal wrong answer because
explainis the verb users are told to trust. In our internal guidance it is documented as "the only reliably-correct verb" (as opposed toquery, which is explicitly a keyword heuristic). A silently-wrongexplainresult therefore gets cited as fact.Version
graphify 0.8.14(graphifyy-0.8.14), graph of ~28,800 nodes over a mixed Python/Rust repo.Reproduction
In a repo where the same function name is defined in two files:
Then:
The second definition — the one that was actually being asked about, and the larger of the two — is not mentioned. Same behaviour for the very common name
main:That repo contains many
main()definitions; one is returned with no indication that it was a choice.What makes this hard to notice
There is no distinguishing signal in the output. A correct result and an arbitrary-pick result are byte-identical in shape, so the only way to detect the mis-anchor is to already know the right answer — which defeats the purpose of asking. Two independent people here cited
explainoutput that pointed at an unrelated file before anyone checked.Attempted workaround (does not work)
Qualifying the name returns nothing rather than disambiguating:
So today there is no way to ask for a specific one of several same-named symbols.
Suggested fix, in rough priority order
3 matches; showing 1. Others: <id> (<path>:<line>), ...— converts a silent wrong answer into an obvious next step.explain "src/foo/bar.py:run_sweep"orexplain "run_sweep" --in src/foo/bar.py.--allflag that prints every match rather than one.(1) alone would close the failure mode; (2) makes it actionable.
Why we care
Agent tooling reads
explainoutput and cites it as ground truth. An answer that is wrong and confident is worse for us than no answer, because the "no node matching found" case is at least visibly a miss.