Skip to content

Commit 1c3d4c5

Browse files
SutuSebastianSutuSebastian
committed
harden: snippet help and rule parity for lookup tiers
Mirror show lookup-tier docs on snippet --help; extend served rule and MCP instructions fast-tier row for show/snippet parity.
1 parent b77c987 commit 1c3d4c5

3 files changed

Lines changed: 24 additions & 18 deletions

File tree

‎src/cli/cmd-snippet.ts‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,12 @@ Look up symbol(s) by exact name and return the source text from disk
3737
as \`show\`; difference is the response carries the actual code body
3838
sliced from disk at line_start..line_end.
3939
40+
Lookup tiers (same as \`codemap show\`):
41+
Fast (equality index) — positional <name>, or \`name:<Token>\` with no
42+
wildcards (% / _) and no other query fields.
43+
Slow (broader scan) — \`name:%pat%\` substring LIKE, multi-field query,
44+
free-text tokens (name LIKE or source_fts when --with-fts / fts5: true).
45+
4046
Args:
4147
<name> Exact symbol name (case-sensitive). Omit when using
4248
--query.

‎templates/agent-content/mcp-instructions.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@ Key fields: `pending_sync` (watcher debounce queue or in-flight reindex), `commi
3131

3232
| Goal | MCP tool | Recipe twin (`query_recipe`) |
3333
| -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
34-
| Exact symbol lookup (fast tier) | **`show`** (`name`, optional `in`) — equality index; same rows as lone `query: 'name:Token'` when Token has no `%`/`_` wildcards and no other query fields | `find-symbol-definitions` (`name = ?`) |
34+
| Exact symbol lookup (fast tier) | **`show`** / **`snippet`** (`name`, optional `kind`, `in`) — equality index; same rows as lone `query: 'name:Token'` when Token has no `%`/`_` wildcards and no other query fields | `find-symbol-definitions` (`name = ?`) |
3535
| Field-qualified symbol discovery (slow tier) | **`show`** or **`snippet`** (`query` with `kind:` / `name:` / `path:` / `in:` + free text; `name:%pat%` substring LIKE; `with_fts` for file-body search) | `find-symbol-by-kind` for kind-heavy patterns; CLI `codemap show --query '…' --print-sql` to inspect generated SQL (no MCP `print_sql` arg) |
3636
| Kind / pattern lookup | **`query_recipe`** | `find-symbol-by-kind` |
3737
| Source at symbol | **`snippet`** | same rows as `show` + disk text |

‎templates/agent-content/rule/00-full.md‎

Lines changed: 17 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -77,23 +77,23 @@ If the question matches any of these, use the index instead of grepping:
7777

7878
## Quick reference queries
7979

80-
| I need to... | Query |
81-
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
82-
| Find a symbol | `SELECT name, kind, file_path, line_start, signature FROM symbols WHERE name = '...'` |
83-
| Field-qualified search | `codemap show --query 'kind:function name:Auth path:src/'` (MCP: `show` / `snippet` with `query`) |
84-
| Call path / neighborhood | `codemap trace` / `explore` / `node` (or MCP twins; recipes: `call-path`, `symbol-neighborhood`) |
85-
| Affected tests | `codemap affected --json` or MCP `affected` (recipe: `affected-tests`) |
86-
| Find a symbol (fuzzy) | `SELECT name, kind, file_path, line_start FROM symbols WHERE name LIKE '%...%'` |
87-
| Symbol docs | `SELECT name, signature, doc_comment FROM symbols WHERE name = '...'` |
88-
| Who imports this file? | `SELECT DISTINCT from_path FROM dependencies WHERE to_path LIKE '%...'` |
89-
| What does this depend on? | `SELECT DISTINCT to_path FROM dependencies WHERE from_path LIKE '%...'` |
90-
| Who calls X? | `SELECT DISTINCT caller_name, file_path FROM calls WHERE callee_name = '...' AND (provenance IS NULL OR provenance = 'ast')` |
91-
| Component info | `SELECT name, props_type, hooks_used FROM components WHERE name = '...'` |
92-
| TODOs in a file | `SELECT line_number, content FROM markers WHERE file_path LIKE '%...' AND kind = 'TODO'` |
93-
| Deprecated symbols | `SELECT name, kind, file_path FROM symbols WHERE doc_comment LIKE '%@deprecated%'` |
94-
| Symbol coverage | `SELECT name, hit_statements, total_statements, coverage_pct FROM coverage WHERE file_path = '...'` |
95-
| Untested + dead exports | `codemap query --json --recipe untested-and-dead` |
96-
| Coverage-confirmed dead | `codemap query --json --recipe coverage-confirmed-dead` (sort by `confidence`) |
80+
| I need to... | Query |
81+
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
82+
| Find a symbol (fast tier) | `codemap show <name>` or lone `codemap show --query 'name:Token'` (no `%`/`_` wildcards) — equality index; recipe: `find-symbol-definitions` |
83+
| Field-qualified search (slow tier) | `codemap show --query 'kind:function name:Auth path:src/'` or `name:%pat%` substring; MCP: `show` / `snippet` with `query` (+ `with_fts` for free text) |
84+
| Call path / neighborhood | `codemap trace` / `explore` / `node` (or MCP twins; recipes: `call-path`, `symbol-neighborhood`) |
85+
| Affected tests | `codemap affected --json` or MCP `affected` (recipe: `affected-tests`) |
86+
| Find a symbol (fuzzy) | `SELECT name, kind, file_path, line_start FROM symbols WHERE name LIKE '%...%'` |
87+
| Symbol docs | `SELECT name, signature, doc_comment FROM symbols WHERE name = '...'` |
88+
| Who imports this file? | `SELECT DISTINCT from_path FROM dependencies WHERE to_path LIKE '%...'` |
89+
| What does this depend on? | `SELECT DISTINCT to_path FROM dependencies WHERE from_path LIKE '%...'` |
90+
| Who calls X? | `SELECT DISTINCT caller_name, file_path FROM calls WHERE callee_name = '...' AND (provenance IS NULL OR provenance = 'ast')` |
91+
| Component info | `SELECT name, props_type, hooks_used FROM components WHERE name = '...'` |
92+
| TODOs in a file | `SELECT line_number, content FROM markers WHERE file_path LIKE '%...' AND kind = 'TODO'` |
93+
| Deprecated symbols | `SELECT name, kind, file_path FROM symbols WHERE doc_comment LIKE '%@deprecated%'` |
94+
| Symbol coverage | `SELECT name, hit_statements, total_statements, coverage_pct FROM coverage WHERE file_path = '...'` |
95+
| Untested + dead exports | `codemap query --json --recipe untested-and-dead` |
96+
| Coverage-confirmed dead | `codemap query --json --recipe coverage-confirmed-dead` (sort by `confidence`) |
9797

9898
## When Grep / Read IS appropriate
9999

0 commit comments

Comments
 (0)