fix(cli): warn when a symbol name is ambiguous

[r0h1tb]

Description

find_definition returns every symbol matching a name; the commands took
defs[0] and reported on that one. For names that are ambiguous by nature —
main, run, parse, __init__ — the answer is usually about a symbol the
user did not mean, and nothing in the output said which one was chosen.

Before:

$ ast-rag blocks main
No blocks found.

…while another main in the same repo had 45 blocks.

After:

$ ast-rag blocks main
ambiguous: 'main' matched 3 symbols (3 python). Reporting on
embedding_server.main. Re-run with a qualified name to pick another, for
example server.main, watcher_service.main
No blocks found.

Related Issue

Fixes #64

Type of Change

• Bug fix (non-breaking change that fixes an issue)

Following your direction on the issue

You asked for a stat and a message suggesting how to narrow the query, with
"ambiguous" at the beginning so an LLM reading the output hits it first, and
without the exclamation mark. That is what this does: leading ambiguous:,
the match count, a per-language breakdown, the symbol actually used, and up to
three alternatives to re-run with.

--filter is deliberately not here. Your comment carries an open
"TODO research about needed filter params", so the filter vocabulary is a
decision rather than something to guess at in a bug fix. Happy to do it as a
follow-up once you have settled the shape.

It was six sites, not one

The issue reported blocks. The same silent defs[0] was in:

command	line
callers	cli.py:526
call-graph	cli.py:615
symbol-impact	cli.py:658
sandbox find_callers tool	cli.py:868
blocks	cli.py:1403
summarize	cli.py:1620

All six now route through one _warn_if_ambiguous helper.

Compatibility

Behaviour is otherwise unchanged. The unambiguous case stays a single command
with no extra output, and defs[0] is still what gets used — so nothing that
worked before now fails or changes its result. The note is additive.

Checklist

• My code follows the code style of this project
• I have added tests that prove my fix works
• All new and existing tests passed (pytest tests/ -v)
• I have updated the documentation accordingly (docstrings)
• I have run ast-rag evaluate --all — needs the summarizer LLM, see below
• My changes generate no new warnings

Testing

Five unit tests on the note itself, covering the wording rules from your
comment (leads with "ambiguous", no !), the count, the per-language
breakdown, and that it names both the chosen symbol and an alternative. They
fail on main with ImportError since the helper does not exist there.

	passed	failed	skipped	xfailed
baseline (main @ 41e48af)	232	0	1	1
this branch	237	0	1	1

+5, the new tests.

$ ruff check ast_rag/            # All checks passed!
$ ruff format --check ast_rag/ tests/   # 88 files already formatted

Verified live against Neo4j 5.18 with this repo indexed — that is where the
"3 symbols (3 python)" output above comes from.

ast-rag evaluate --all not run: it needs the summarizer LLM and I have no
model serving locally. This change only adds an advisory line to command
output and does not touch scoring.

Note on ordering

This sits on top of main, so it is independent of #70 and #71 — merge in any
order. If #71 lands first there will be a small context overlap in cli.py
around _build_api; I am happy to rebase whichever comes second.