feat: tiered show lookup fast paths and covering index

Route lone name:Token queries to equality lookup; add
idx_symbols_name_covering; document fast vs slow tiers in CLI/MCP help.

Author: SutuSebastian

.changeset/tiered-lookup-fast-paths.md

@@ -0,0 +1,5 @@
+---
+"@stainless-code/codemap": patch
+---
+
+Route lone `name:Token` show/snippet queries to equality index (`name = ?`) instead of substring LIKE. Add `idx_symbols_name_covering` for full `findSymbolsByName` SELECT. CLI and MCP tool descriptions document fast vs slow lookup tiers.

docs/architecture.md

@@ -190,7 +190,7 @@ Three **mutually exclusive** CLI entry shapes; all converge on `applyDiffPayload
 
 **Backlog (not rejected):** `organize-imports` diff-shape recipe; `codemap-to-tsmorph` Path B adapter — tracked in [roadmap.md § Backlog](./roadmap.md#backlog). **Tracked elsewhere:** C.9 entry-point integration — [`plans/c9-plugin-layer.md`](./plans/c9-plugin-layer.md).
 
-**Show / snippet wiring:** **`src/cli/show-snippet-args.ts`** (shared argv parser) + **`src/cli/show-snippet-render.ts`** (shared terminal/JSON error helpers) + **`src/cli/cmd-show.ts`** + **`src/cli/cmd-snippet.ts`** — sibling CLI verbs sharing the same parser shape (`<name>` or **`--query '<field:value …>'`** + **`--with-fts`** + `--kind` + `--in <path>` + `--json`; show adds **`--print-sql`**) and the pure engines **`src/application/show-engine.ts`** (exact lookup + envelope builders), **`src/application/search-query-parser.ts`** + **`src/application/search-engine.ts`** (field-qualified search → parameterized SQL on `symbols`, optional `source_fts` join), and **`src/application/show-search-mode.ts`** (shared parse/normalize + FTS resolution + **`executeShowLookup`** + **`formatShowSearchSqlForQuery`** for CLI/MCP/HTTP). Exact lookup: `findSymbolsByName({db, name, kind?, inPath?})`. Query lookup: `searchSymbols({db, parsed, withFts?})`. Snippet FS read: `readSymbolSource({match, projectRoot, indexedContentHash?})` + `getIndexedContentHash(db, filePath)`. **`buildShowResult`** + **`buildSnippetResult`** envelope builders — same engines the MCP show/snippet tools call. Both verbs return the same `{matches, disambiguation?, warning?}` envelope — single match → `{matches: [{...}]}`; multi-match adds `{n, by_kind, files, hint}`; optional **`warning`** when FTS was requested but `source_fts` is empty. Snippet matches add `source` / `stale` / `missing` fields (additive — no shape divergence). **`--in <path>`** and **`path:`** inside **`--query`** normalize through `toProjectRelative(projectRoot, p)` (from **`src/application/validate-engine.ts`**). Stale-file behavior on `snippet`: `hashContent` (from **`src/hash.ts`**) compares on-disk content against `files.content_hash`; mismatch sets `stale: true` but source IS still returned. MCP tools `show` and `snippet` register parallel to the CLI surface (see [§ MCP wiring](#cli-usage)).
+**Show / snippet wiring:** **`src/cli/show-snippet-args.ts`** (shared argv parser) + **`src/cli/show-snippet-render.ts`** (shared terminal/JSON error helpers) + **`src/cli/cmd-show.ts`** + **`src/cli/cmd-snippet.ts`** — sibling CLI verbs sharing the same parser shape (`<name>` or **`--query '<field:value …>'`** + **`--with-fts`** + `--kind` + `--in <path>` + `--json`; show adds **`--print-sql`**) and the pure engines **`src/application/show-engine.ts`** (exact lookup + envelope builders), **`src/application/search-query-parser.ts`** + **`src/application/search-engine.ts`** (field-qualified search → parameterized SQL on `symbols`, optional `source_fts` join), and **`src/application/show-search-mode.ts`** (shared parse/normalize + FTS resolution + tiered routing via **`resolveExactNameFromParsedQuery`** / **`isExactNamePattern`** + **`executeShowLookup`** + **`formatShowSearchSqlForQuery`** for CLI/MCP/HTTP). **Fast tier:** positional `<name>` or lone `name:Token` without `%`/`_` wildcards (no `kind`/`path`/`in`/free text) → `findSymbolsByName` (`name = ?`, **`idx_symbols_name_covering`**). **Slow tier:** `name LIKE` substring, multi-field query, or FTS free-text → `searchSymbols`. Exact lookup with filters: `findSymbolsByName({db, name, kind?, inPath?})`. Snippet FS read: `readSymbolSource({match, projectRoot, indexedContentHash?})` + `getIndexedContentHash(db, filePath)`. **`buildShowResult`** + **`buildSnippetResult`** envelope builders — same engines the MCP show/snippet tools call. Both verbs return the same `{matches, disambiguation?, warning?}` envelope — single match → `{matches: [{...}]}`; multi-match adds `{n, by_kind, files, hint}`; optional **`warning`** when FTS was requested but `source_fts` is empty. Snippet matches add `source` / `stale` / `missing` fields (additive — no shape divergence). **`--in <path>`** and **`path:`** inside **`--query`** normalize through `toProjectRelative(projectRoot, p)` (from **`src/application/validate-engine.ts`**). Stale-file behavior on `snippet`: `hashContent` (from **`src/hash.ts`**) compares on-disk content against `files.content_hash`; mismatch sets `stale: true` but source IS still returned. MCP tools `show` and `snippet` register parallel to the CLI surface (see [§ MCP wiring](#cli-usage)).
 
 **Evidence columns (high-judgment recipes):** Some bundled recipes add optional **`reason`** and **`evidence_json`** TEXT columns on each result row — factual detection path for agents, not pass/fail verdicts. Contract: [golden-queries.md § Evidence columns](./golden-queries.md#evidence-columns-high-judgment-recipes).
 
@@ -1053,16 +1053,17 @@ A covering index includes all columns needed by a query, so SQLite never touches
 
 Key covering indexes:
 
-| Index                    | Columns                                                               | Covers                     |
-| ------------------------ | --------------------------------------------------------------------- | -------------------------- |
-| `idx_symbols_name`       | `name, kind, file_path, line_start, line_end, signature, is_exported` | Symbol lookup by name      |
-| `idx_imports_source`     | `source, file_path`                                                   | "Who imports X?" queries   |
-| `idx_imports_resolved`   | `resolved_path, file_path`                                            | Resolved path lookups      |
-| `idx_exports_name`       | `name, file_path, kind, is_default`                                   | Export lookup by name      |
-| `idx_components_name`    | `name, file_path, props_type, hooks_used`                             | Component search by name   |
-| `idx_components_file`    | `file_path, name`                                                     | Components in a directory  |
-| `idx_dependencies_to`    | `to_path, from_path`                                                  | Reverse dependency lookups |
-| `idx_markers_kind`       | `kind, file_path, line_number, content`                               | Marker listing by kind     |
-| `idx_css_variables_name` | `name, value, scope, file_path`                                       | CSS token lookup by name   |
-| `idx_css_classes_name`   | `name, file_path, is_module`                                          | CSS class lookup           |
-| `idx_css_keyframes_name` | `name, file_path`                                                     | Keyframe lookup            |
+| Index                       | Columns                                                                                        | Covers                                               |
+| --------------------------- | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
+| `idx_symbols_name`          | `name, kind, file_path, line_start, line_end, signature, is_exported`                          | Symbol lookup by name                                |
+| `idx_symbols_name_covering` | `name, kind, file_path, line_start, line_end, signature, is_exported, parent_name, visibility` | Full `findSymbolsByName` SELECT without table lookup |
+| `idx_imports_source`        | `source, file_path`                                                                            | "Who imports X?" queries                             |
+| `idx_imports_resolved`      | `resolved_path, file_path`                                                                     | Resolved path lookups                                |
+| `idx_exports_name`          | `name, file_path, kind, is_default`                                                            | Export lookup by name                                |
+| `idx_components_name`       | `name, file_path, props_type, hooks_used`                                                      | Component search by name                             |
+| `idx_components_file`       | `file_path, name`                                                                              | Components in a directory                            |
+| `idx_dependencies_to`       | `to_path, from_path`                                                                           | Reverse dependency lookups                           |
+| `idx_markers_kind`          | `kind, file_path, line_number, content`                                                        | Marker listing by kind                               |
+| `idx_css_variables_name`    | `name, value, scope, file_path`                                                                | CSS token lookup by name                             |
+| `idx_css_classes_name`      | `name, file_path, is_module`                                                                   | CSS class lookup                                     |
+| `idx_css_keyframes_name`    | `name, file_path`                                                                              | Keyframe lookup                                      |