fix(cli): reject the structural query routes and sql cannot honour - #137

Fixes #97

vera structural routes <query> and vera structural sql <query> accepted a positional
query, dropped it, and returned the unfiltered result set with exit 0. The user reads the
top hits as "no match for my query" when the query was never applied.

This PR makes the two kinds reject a query instead of ignoring it, in vera-core so both
the CLI and the MCP structural_search tool inherit the behaviour.

Reproduction

Released binary as control, vera 1.0.0, on the Vera repo's own index. Same index, same
queries, only the binary changes.

$ vera --version
vera 1.0.0

$ vera structural sql find_user_by_email --json > sql-query.json;    echo exit=$?
exit=0
$ vera structural sql --json                > sql-noquery.json;      echo exit=$?
exit=0
$ cmp -s sql-query.json sql-noquery.json && echo IDENTICAL
IDENTICAL

$ vera structural routes /api/does-not-exist --json > routes-query.json;   echo exit=$?
exit=0
$ vera structural routes --json                    > routes-noquery.json;  echo exit=$?
exit=0
$ cmp -s routes-query.json routes-noquery.json && echo IDENTICAL
IDENTICAL

Result counts and whether any hit mentions the term:

The query mechanism itself works, which is what makes the two kinds outliers rather than a
general limitation. Same released binary, same index:

$ count() { "$@" --json 2>/dev/null | python3 -c 'import json,sys;print(len(json.load(sys.stdin)))'; }
$ count vera structural env                            # 20
$ count vera structural env NO_SUCH_VAR_XYZ            # 0
$ count vera structural env VERA_NO_UPDATE_CHECK       # 1
$ vera structural definitions
Error: definitions requires a query

The same counting helper produced every result count quoted in this PR.

After the fix, same index, same queries:

$ vera structural sql find_user_by_email
Error: SQL queries accepts no query term; got "find_user_by_email". Narrow with path, language, or scope filters instead.
$ echo $?
1

$ vera structural routes /api/does-not-exist
Error: route handlers accepts no query term; got "/api/does-not-exist". Narrow with path, language, or scope filters instead.
$ echo $?
1

Nothing else moved. structural sql still returns 11 and structural routes still returns 3,
both exit 0; env still returns 20 / 0 / 1 for the three cases above; definitions with no
query still fails with its existing message.

Root cause

Two layers, both on master at e3d79b3, and either one alone would have swallowed the
argument.

1. crates/vera-core/src/retrieval/structural.rs:72-75. search_route_handlers and
   search_sql_queries take no query parameter at all, so the two match arms drop the
   query: Option<&str> that search_structural was handed. This is the layer the MCP tool
   hits: crates/vera-mcp/src/tools.rs:876 forwards query for every kind.
2. crates/vera-cli/src/commands/structural.rs:43-47. The CLI's intent dispatch hardcodes
   None for those two arms, so even a fixed core would never see the argument.

The help text at crates/vera-cli/src/cli.rs:345 read "Optional query term. Required for
definitions and impls", which says optional-but-honoured rather than ignored.

Why reject rather than filter

The project already documents these two kinds as taking no argument, in three places, and
the loose one-line clap help was the only surface saying otherwise:

• crates/vera-mcp/src/tools.rs schema: "Required for definitions and implementation lookups.
  Optional for env_reads to narrow to one env var." Route handlers and SQL queries are absent.
• docs/features.md: env [NAME] is listed with its optional argument, routes and sql
  are listed with none.
• docs/query-guide.md and the installed agent skill text both show vera structural routes
  and vera structural sql bare, narrowed with --path / --lang.

The code agrees. ENV_PATTERNS carries a capture group per alternative and is consumed with
captures_iter plus first_capture, precisely so the captured variable name can be compared
against the query. ROUTE_PATTERNS and SQL_PATTERNS carry no capture group and are consumed
with find_iter. There is no term-bearing entity to narrow against, so the query has no
defined meaning for either kind.

The two kinds do not differ from each other here, and it is worth saying why, because they
look like they might. A route pattern does match the path literal as part of its span, so
substring-filtering routes would be implementable; a SQL pattern matches only the call prefix
(db.query(), never the statement, so the issue's own example find_user_by_email could not
match a SQL span under any term filter. Adding term filtering to routes alone would split the
two kinds apart, add a capability that vera grep already covers, and would be a feature
rather than a fix. Rejecting keeps them symmetric and matches the documented contract.

Changes

Regression test and reinjection

routes_and_sql_reject_a_query_they_cannot_honour in crates/vera-core/src/retrieval/structural.rs.
It asserts presence before absence: the fixture must first produce exactly one route hit and
one SQL hit with None, which is the hit a dropped query would have returned, then asserts
the Some("find_user_by_email") call errors and that the message names both the kind and the
rejected term, then asserts blank and whitespace-only queries remain a no-op.

Reverted reject_query from both arms and reran. The test fails with the production symptom,
the unfiltered hit returned for a query that does not appear in it:

running 1 test
test retrieval::structural::tests::routes_and_sql_reject_a_query_they_cannot_honour ... FAILED

failures:

---- retrieval::structural::tests::routes_and_sql_reject_a_query_they_cannot_honour stdout ----

thread 'retrieval::structural::tests::routes_and_sql_reject_a_query_they_cannot_honour' (20664790) panicked at crates/vera-core/src/retrieval/structural.rs:1004:14:
route handlers accepted a query it cannot honour: [SearchResult { file_path: "src/router.ts", line_start: 1, line_end: 1, content: "router.get('/users', handler)", language: TypeScript, score: 1.0, symbol_name: None, symbol_type: Some(Block) }]

test result: FAILED. 0 passed; 1 failed; 0 ignored; 0 measured; 793 filtered out; finished in 0.23s

Fix restored, test passes.

Verification

Every number below is from a command run on this branch at the commit being submitted.

The five pre-existing vera-core warnings are unused import: super::ort::command_exists,
unused variable: gpu_suffix, CUDA_RUNTIME_LIBRARY_PREFIXES,
parse_cuda_major_from_runtime_library_entry, and pip_package_for_ep.

Review hotspots and what I did not do

• The CLI half has no unit test. There is no harness in this repo that drives the vera
  binary from a test, and commands::structural::run reads the stored runtime config, so it
  is not reachable from a unit test. The CLI half is covered two other ways: the end-to-end
  runs quoted above only produce an error if the CLI forwards the query and core rejects it,
  and the change deletes the per-arm decision rather than correcting it, so there is no branch
  left in the CLI to regress. Stated plainly because it is the weakest point of the diff.
• This is a behaviour change for existing MCP callers. An agent calling structural_search
  with kind: "route_handlers" and a query gets an error where it previously got results.
  That is the point of the fix, but it is a break, and it is why the schema description moved
  in the same commit.
• The error message is worded for both surfaces. It says "path, language, or scope filters"
  rather than naming --path / --lang, because the same string is returned through MCP where
  those are JSON properties.
• env was deliberately left alone. It has a capture group, it honours the query today,
  and the released-binary numbers above are the evidence that it does.
• No retrieval ranking can move. This change only adds an early error on an input that
  previously produced results; the no-query paths are untouched. The identical before/after
  counts for structural sql (11) and structural routes (3) on the same index are the
  evidence. No benchmark applies.

Summary by cubic

Rejects positional queries for structural routes and SQL to prevent silent no-ops. Previously routes <query> and sql <query> were accepted then ignored, returning unfiltered results with exit 0; now they error with guidance (blank/whitespace still treated as absent).

• Unchanged behavior: routes/sql without a query return the same results as before; env, definitions, and impls are unchanged.

Changes

• Centralized in vera-core: search_structural now rejects non-blank queries for RouteHandlers and SqlQueries via reject_query; added a regression test that asserts the error and blank handling.
• vera-cli: always forwards the positional query; help text clarifies the per-intent contract (required for definitions/impls, optional for env, rejected by routes/sql).
• vera-mcp: updates structural_search schema to mark route_handlers and sql_queries as rejecting query.
• Docs: adds guidance to narrow routes/sql with --path, --lang, --type, or --scope.

Migration

• Do not pass a query for routes or sql in the CLI or MCP. Use filters instead.
• Expect exit code 1 with an error if a non-blank query is provided to these kinds.

^{Written for commit 96f392f. Summary will update on new commits.}

Summary by CodeRabbit

• Bug Fixes
  • Structural searches now reject unsupported query terms for route-handler and SQL searches instead of silently ignoring them.
  • Blank queries are handled consistently across structural search types.
• Documentation
  • Clarified when queries are required, optional, or rejected in the CLI, tool schema, and feature documentation.
  • Documented alternative filters for narrowing route-handler and SQL searches.