feat(show + snippet): targeted-read CLI verbs + MCP tools

[SutuSebastian]

Summary

Two sibling CLI verbs (and matching MCP tools) for precise reads — close the "agent wants to read this thing" loop without composing SQL:

• codemap show <name> — returns metadata (file_path:line_start-line_end + signature + kind) for the symbol(s) matching the exact name
• codemap snippet <name> — same lookup; each match also carries source (file lines from disk), stale (true when content_hash drifted since indexing), missing (true when file is gone)

Both share the same flag set (--kind <k> filter, --in <path> file scope) and the same agent-friendly {matches, disambiguation?} envelope shape.

Status: Ready for review. All 6 grill questions settled (recorded inline in the now-deleted plan; canonical bits lifted into architecture.md / glossary.md / agent rule + skill per Rules 2 + 10). All 6 tracers shipped.

Settled grill questions (agent-first lens applied throughout)

#	Question	Answer
Q-1	MCP show tool — separate from query?	Dedicated MCP tool. Discoverability + token savings; mirrors the every-CLI-verb-is-an-MCP-tool pattern from PR #35.
Q-2	Multiple matches — error or list?	Always-wrap {matches, disambiguation?}. Single match → {matches: [{...}]}; multi-match adds {n, by_kind, files, hint}. Forward-extensible (future nearest_to_cursor etc. land as additive keys). Reframed from "error by default" — that was 2023-era reasoning; today's frontier models reason fine over 2-5 candidates.
Q-3	Exact match or substring/regex?	Exact only. Agents have the exact name 95% of the time; fuzzy belongs in query with LIKE. Error message routes the agent to that escape hatch.
Q-4	File-scope filter (--in <path>)?	Ship --in. Closes the loop with the disambiguation envelope. Path normalized via existing toProjectRelative (verified — already handles leading ./, trailing /, Windows backslash → POSIX).
Q-5	Snippet sibling — now or later?	Ship together. Fact-check showed the marginal cost is ~2-3h on top of show (lookup helper shared, readFileSync + hashContent + files.content_hash is the literal pattern cmd-validate.ts already uses). Splitting would duplicate docs / changeset / Rule-10 mirror overhead.
Q-6	Stale-file behavior for snippet?	Read + flag. source always returned when file exists; stale: true is metadata the agent reads. No refusal (hostile round-trips), no auto-reindex (read tool stays read-only).

Tracer-bullet sequence (all shipped)

• 1 — engine — src/application/show-engine.ts findSymbolsByName + 12 tests
• 2 — codemap show CLI — src/cli/cmd-show.ts (parser, envelope builder, terminal renderer, error UX) + 13 tests
• 3 — snippet engine — readSymbolSource + getIndexedContentHash + 7 stale-detection tests
• 4 — codemap snippet CLI — src/cli/cmd-snippet.ts mirrors show's parser + adds source enrichment + 11 tests
• 5 — MCP tools — show + snippet registered parallel to CLI; 8 in-process integration tests via @modelcontextprotocol/sdk's InMemoryTransport
• 6 — docs — architecture / glossary / README / rule + skill across .agents/ and templates/agents/ (Rule 10), plan deleted (Rule 2), minor changeset

Architecture

Mirrors the cmd-* ↔ *-engine seam from PRs #33 / #35 / #37:

• src/application/show-engine.ts — pure transport-agnostic engine. findSymbolsByName (DB-only) is shared between show + snippet; readSymbolSource (FS-only) is snippet-side; getIndexedContentHash is the staleness-check primitive.
• src/cli/cmd-show.ts + src/cli/cmd-snippet.ts — sibling CLI verbs sharing the parser + envelope shape; differ only in the source-enrichment step and terminal rendering.
• src/application/mcp-server.ts — registerShowTool + registerSnippetTool follow the established register-tool pattern; both reuse the engine helpers + envelope builders directly.

toProjectRelative (newly exported from cmd-validate.ts — was private) handles --in path normalization across CLI + MCP. hashContent from src/hash.ts powers stale detection (same primitive cmd-validate.ts uses).

Test plan

• bun run check green after every tracer
• 51 unit + integration tests — 19 engine, 13 cmd-show, 11 cmd-snippet, 8 MCP integration
• Smoke tested end-to-end: bun src/index.ts show runQueryCmd / --json / --in src/cli / unknown-name; bun src/index.ts snippet runQueryCmd --json returns metadata + source + stale flag

Self-audit

• ✅ .agents/ rules respected: tracer-bullets (6 small commits), verify-after-each-step (full check after each), concise-comments (no exposition prose), preserve-comments (no deletions), docs-governance Rules 2 + 9 + 10
• ✅ Performance: pure engine; no new deps; reuses existing primitives end-to-end
• ✅ Architecture: clean engine seam; backwards-compat preserved (only one new export — toProjectRelative)
• ✅ Agent-first reasoning explicit on Q-2 / Q-3 / Q-5 / Q-6 — disambiguation envelope, exact-match + escape-hatch routing, ship-snippet-together for skill-prompt cohesion, read-tool-stays-read-only
• ✅ Stale-file behavior verified against cmd-validate.ts's pattern (same code path)

Composition with shipped surface

Reuses findSymbolsByName across show + snippet + MCP tools; reuses hashContent + toProjectRelative + files.content_hash from PRs #23 + #28 (validate primitives). MCP tool exposure follows the every-verb-becomes-a-tool pattern from PR #35. No new MCP tools other than show + snippet; no new CLI flags on existing verbs; no schema changes.

Summary by CodeRabbit

Release Notes

• New Features

  • Added codemap show command: precise symbol lookup by exact name with optional filtering by kind (--kind) and file path (--in)
  • Added codemap snippet command: same symbol lookup plus on-disk source code retrieval
  • Both commands support --json output and return multi-match disambiguation metadata
  • Added corresponding MCP tools for AI agent integrations

• Documentation

  • Updated README, architecture guides, and glossary with targeted reads documentation
  • Removed completed roadmap items

[changeset-bot]

🦋 Changeset detected

Latest commit: a8fb0b8

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@stainless-code/codemap	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[coderabbitai]

Warning

Rate limit exceeded

@SutuSebastian has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 46 minutes and 55 seconds before requesting another review.

To keep reviews running without waiting, you can enable usage-based add-on for your organization. This allows additional reviews beyond the hourly cap. Account admins can enable it under billing.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 1610e81f-1d9d-4775-9388-073326de0178

📥 Commits

Reviewing files that changed from the base of the PR and between 5cc8b0d and a8fb0b8.

📒 Files selected for processing (7)

• .github/workflows/ci.yml
• src/agents-init.test.ts
• src/agents-init.ts
• src/application/show-engine.test.ts
• src/application/show-engine.ts
• src/cli/cmd-show.ts
• src/cli/cmd-snippet.ts

📝 Walkthrough

Walkthrough

This PR introduces two new targeted-read CLI commands (show and snippet) that perform exact symbol lookups without composing SQL queries. The show command returns symbol metadata (location and signature), while snippet augments that with on-disk source text and staleness indicators. Both share common flags (--kind, --in) and return a consistent JSON envelope with optional multi-match disambiguation. The implementation includes a transport-agnostic show engine, CLI wiring, MCP tool registration, comprehensive test coverage, and documentation updates.

Changes

Show and Snippet Targeted Reads

Layer / File(s)	Summary
Core Engine src/application/show-engine.ts, src/application/show-engine.test.ts	New findSymbolsByName() queries the database with optional kind and inPath filters, returning ordered results. readSymbolSource() slices on-disk source text and computes stale/missing flags by comparing content hashes. getIndexedContentHash() retrieves cached hashes from the files table.
CLI Command Implementation src/cli/cmd-show.ts, src/cli/cmd-show.test.ts, src/cli/cmd-snippet.ts, src/cli/cmd-snippet.test.ts	cmd-show implements symbol lookup with help text, argument parsing, and JSON/terminal rendering via printShowCmdHelp(), parseShowRest(), buildShowResult(), and runShowCmd(). cmd-snippet extends the same surface with readSymbolSource() integration, enriching each match with source text and stale/missing indicators via buildSnippetResult() and runSnippetCmd(). Both generate { matches, disambiguation? } envelopes for multi-match disambiguation.
CLI Dispatch & Path Normalization src/cli/main.ts, src/cli/bootstrap.ts, src/cli/cmd-validate.ts	main() recognizes show and snippet subcommands, dynamically imports their modules, parses arguments, and delegates to command runners. printCliUsage() documents both commands with flags. validateIndexModeArgs() permits these verbs without unknown-flag rejection. toProjectRelative() is exported for --in flag normalization.
MCP Server Integration src/application/mcp-server.ts, src/application/mcp-server.test.ts	Two new MCP tools (show and snippet) are registered via registerShowTool() and registerSnippetTool(), reusing the CLI result builders (buildShowResult(), buildSnippetResult()) to ensure uniform output across CLI and MCP. MCP integration test verifies tool discovery, single/multi-match behavior, filtering, and stale/missing metadata.
Documentation & Changesets .agents/rules/codemap.md, .agents/skills/codemap/SKILL.md, .changeset/targeted-read-cli.md, README.md, docs/architecture.md, docs/glossary.md, docs/roadmap.md, templates/agents/*	Documented show and snippet CLI commands and MCP tools, their shared {matches, disambiguation?} envelope, filter flags, and snippet-specific source/stale/missing fields. Removed "Targeted-read CLI" from roadmap backlog. Updated agent rules and skill documentation to include the new tools.

Sequence Diagram(s)

sequenceDiagram
    actor User
    participant CLI as CLI Handler<br/>(cmd-show.ts)
    participant Engine as Show Engine<br/>(show-engine.ts)
    participant DB as Database
    participant Result as buildShowResult()
    
    User->>CLI: codemap show foo [--kind <k>] [--in <path>]
    CLI->>CLI: parseShowRest(args)
    CLI->>Engine: findSymbolsByName(db, {name, kind?, inPath?})
    Engine->>DB: SELECT * FROM symbols WHERE name=? (+ filters)
    DB-->>Engine: SymbolMatch[]
    Engine-->>CLI: matches
    CLI->>Result: buildShowResult(matches)
    Result-->>CLI: {matches, disambiguation?}
    CLI-->>User: JSON or terminal output

Loading

sequenceDiagram
    actor User
    participant CLI as CLI Handler<br/>(cmd-snippet.ts)
    participant Engine as Show Engine<br/>(show-engine.ts)
    participant DB as Database
    participant FS as File System
    participant Result as buildSnippetResult()
    
    User->>CLI: codemap snippet foo [--kind <k>] [--in <path>]
    CLI->>CLI: parseSnippetRest(args)
    CLI->>Engine: findSymbolsByName(db, {name, kind?, inPath?})
    Engine->>DB: SELECT * FROM symbols WHERE name=? (+ filters)
    DB-->>Engine: SymbolMatch[]
    Engine-->>CLI: matches
    CLI->>Result: buildSnippetResult({db, matches, projectRoot})
    loop for each match
        Result->>Engine: getIndexedContentHash(db, filePath)
        DB-->>Engine: content_hash
        Engine-->>Result: indexed hash (or undefined)
        Result->>Engine: readSymbolSource({match, projectRoot, indexedContentHash})
        Engine->>FS: read file & slice lines [line_start:line_end]
        FS-->>Engine: source text (or undefined)
        Engine->>Engine: compute stale (hash mismatch?) & missing
        Engine-->>Result: {source, stale, missing}
        Result->>Result: enrich match with source/stale/missing
    end
    Result-->>CLI: {matches[{..., source, stale, missing}], disambiguation?}
    CLI-->>User: JSON or terminal output with [STALE]/[MISSING] markers

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~50 minutes

Possibly related PRs

• feat(mcp): codemap mcp — agent-transports v1 (Tracer 1 of 7) #35: Introduces the MCP server infrastructure that this PR extends with show and snippet tool registration.
• feat(cli): codemap validate / context / --performance, four new query recipes, friendlier no-DB error #23: Modifies CLI dispatch and bootstrap validation, similar integration patterns for new top-level commands.

Suggested labels

enhancement, documentation

Poem

🐰 A show and a snippet, two commands so neat,
With symbols by name, the lookup's complete!
Slice source from disk, mark stale with a flag,
No SQL composed—just data we drag!
Through MCP and CLI, the queries now flow,
Exact symbol reads: that's how shows go! 🎯

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 56.67% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title accurately describes the primary change: adding two new CLI verbs (show and snippet) and their corresponding MCP tools for targeted symbol lookup.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/targeted-read-cli

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Review rate limit: 0/1 reviews remaining, refill in 46 minutes and 55 seconds.}

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[SutuSebastian]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 1

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

README.md (1)

130-134: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

MCP tools comment doesn't include show / snippet.

Every other doc updated in this PR lists them as MCP tools (SKILL.md, .agents/rules/codemap.md, templates/agents/rules/codemap.md), but the inline comment here was not updated.

📝 Proposed fix

-# Tools: query, query_batch (MCP-only — N statements in one round-trip), query_recipe, audit,
-#        save_baseline, list_baselines, drop_baseline, context, validate
+# Tools: query, query_batch (MCP-only — N statements in one round-trip), query_recipe, audit,
+#        save_baseline, list_baselines, drop_baseline, context, validate, show, snippet

As per coding guidelines: "Use consistent terminology across all documentation" and "Documentation files must be kept up-to-date with code changes."

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@README.md` around lines 130 - 134, Update the inline MCP tools comment so it
matches the rest of the docs by adding the missing "show" and "snippet" tools to
the tools list; specifically edit the comment line that begins with "Tools:
query, query_batch (MCP-only — N statements in one round-trip), query_recipe,
audit, save_baseline, list_baselines, drop_baseline, context, validate" to
include "show" and "snippet" in that comma-separated list so the README's MCP
tools section matches SKILL.md and the other codemap docs.

🧹 Nitpick comments (2)

src/application/mcp-server.test.ts (1)

755-763: ⚡ Quick win

Replace inline require() with a top-level ESM import.

require("../hash") is CommonJS style inside an ESM module. cmd-snippet.test.ts already imports hashContent at the module level — keep the same pattern here.

♻️ Proposed fix

 import { resolveCodemapConfig } from "../config";
 import { closeDb, createTables, openDb, upsertQueryBaseline } from "../db";
+import { hashContent } from "../hash";
 import { initCodemap } from "../runtime";
 import { createMcpServer } from "./mcp-server";

-      const realHash = (
-        require("../hash") as typeof import("../hash")
-      ).hashContent("export const A = 1;\n");
+      const realHash = hashContent("export const A = 1;\n");

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/application/mcp-server.test.ts` around lines 755 - 763, The test uses a
runtime CommonJS require to call hashContent; replace that by importing
hashContent at module top like the other tests and use the imported symbol here
(remove require("../hash") and call hashContent("export const A = 1;\n"));
update any references in this file to use the top-level imported hashContent and
keep the rest of the logic around openDb() and db.run unchanged.

src/cli/cmd-snippet.test.ts (1)

12-69: ⚡ Quick win

Add tests for --kind and --in missing-value error paths.

The implementation in parseSnippetRest (context: src/cli/cmd-snippet.ts lines 125–150) returns a structured error when --kind or --in has no following value, but neither case is exercised here. The pattern is already established for "errors on unknown flag" and "errors when no <name> given".

✅ Suggested additions

   it("errors on unknown flag", () => {
     const r = parseSnippetRest(["snippet", "foo", "--with-context"]);
     expect(r.kind).toBe("error");
     if (r.kind === "error") expect(r.message).toContain("--with-context");
   });
+
+  it("errors when --kind has no value", () => {
+    const r = parseSnippetRest(["snippet", "foo", "--kind"]);
+    expect(r.kind).toBe("error");
+    if (r.kind === "error") expect(r.message).toContain("--kind");
+  });
+
+  it("errors when --in has no value", () => {
+    const r = parseSnippetRest(["snippet", "foo", "--in"]);
+    expect(r.kind).toBe("error");
+    if (r.kind === "error") expect(r.message).toContain("--in");
+  });

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/cli/cmd-snippet.test.ts` around lines 12 - 69, The test suite for
parseSnippetRest is missing cases that exercise the error paths when the flags
"--kind" or "--in" are provided without a following value; add two new tests
(similar to the existing "errors on unknown flag" and "errors when no <name>
given") that call parseSnippetRest(["snippet", "--kind"]) and
parseSnippetRest(["snippet", "--in"]) (and also with a name present, e.g.
["snippet","foo","--kind"] / ["snippet","foo","--in"] if your implementation
expects the name position) and assert the returned result.kind is "error" and
that result.message contains "--kind" or "--in" respectively so the structured
error branches in parseSnippetRest are covered. Ensure tests reference
parseSnippetRest and the flag strings exactly.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@src/application/show-engine.ts`:
- Around line 60-70: The LIKE branch is vulnerable because raw opts.inPath may
contain SQL wildcard chars (%) and (_) — escape backslashes, percent and
underscore before appending the trailing wildcard and use an explicit ESCAPE
clause. Update the directory branch (the code building clauses and params) to
escape opts.inPath (e.g. replace backslash, '%' and '_' with escaped versions),
then push the escaped prefix + '%' into params and change the SQL clause to
"file_path LIKE ? ESCAPE '\\'"; leave the exact-match branch (file_path = ?)
unchanged. Ensure you reference the existing symbols looksLikeDirectory,
opts.inPath, clauses, and params when making the change.

---

Outside diff comments:
In `@README.md`:
- Around line 130-134: Update the inline MCP tools comment so it matches the
rest of the docs by adding the missing "show" and "snippet" tools to the tools
list; specifically edit the comment line that begins with "Tools: query,
query_batch (MCP-only — N statements in one round-trip), query_recipe, audit,
save_baseline, list_baselines, drop_baseline, context, validate" to include
"show" and "snippet" in that comma-separated list so the README's MCP tools
section matches SKILL.md and the other codemap docs.

---

Nitpick comments:
In `@src/application/mcp-server.test.ts`:
- Around line 755-763: The test uses a runtime CommonJS require to call
hashContent; replace that by importing hashContent at module top like the other
tests and use the imported symbol here (remove require("../hash") and call
hashContent("export const A = 1;\n")); update any references in this file to use
the top-level imported hashContent and keep the rest of the logic around
openDb() and db.run unchanged.

In `@src/cli/cmd-snippet.test.ts`:
- Around line 12-69: The test suite for parseSnippetRest is missing cases that
exercise the error paths when the flags "--kind" or "--in" are provided without
a following value; add two new tests (similar to the existing "errors on unknown
flag" and "errors when no <name> given") that call parseSnippetRest(["snippet",
"--kind"]) and parseSnippetRest(["snippet", "--in"]) (and also with a name
present, e.g. ["snippet","foo","--kind"] / ["snippet","foo","--in"] if your
implementation expects the name position) and assert the returned result.kind is
"error" and that result.message contains "--kind" or "--in" respectively so the
structured error branches in parseSnippetRest are covered. Ensure tests
reference parseSnippetRest and the flag strings exactly.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 597d0677-79b4-4196-88b3-82186c35ca1f

📥 Commits

Reviewing files that changed from the base of the PR and between abee731 and 5cc8b0d.

📒 Files selected for processing (20)

• .agents/rules/codemap.md
• .agents/skills/codemap/SKILL.md
• .changeset/targeted-read-cli.md
• README.md
• docs/architecture.md
• docs/glossary.md
• docs/roadmap.md
• src/application/mcp-server.test.ts
• src/application/mcp-server.ts
• src/application/show-engine.test.ts
• src/application/show-engine.ts
• src/cli/bootstrap.ts
• src/cli/cmd-show.test.ts
• src/cli/cmd-show.ts
• src/cli/cmd-snippet.test.ts
• src/cli/cmd-snippet.ts
• src/cli/cmd-validate.ts
• src/cli/main.ts
• templates/agents/rules/codemap.md
• templates/agents/skills/codemap/SKILL.md

💤 Files with no reviewable changes (1)

• docs/roadmap.md