feat(recipes): recipes-as-content registry — bundled .md + project-local .codemap/recipes/

[SutuSebastian]

Summary

Implements the recipes-as-content registry — pairs every bundled recipe with a sibling .md description body AND lets projects ship their own recipes via .codemap/recipes/<id>.{sql,md}. Surfaces uniformly in --recipes-json, codemap query --recipe <id>, and the codemap://recipes / codemap://recipes/{id} MCP resources shipped in PR #35.

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 Rule 2 / Rule 10). All 6 tracers shipped.

Wins

• Bundled recipes get room to teach. SQL stays as .sql (editor highlighting, sqlite3 .read works); .md body holds the long-form "when to use" / "follow-up SQL" notes. Per-row actions templates lifted from the in-code map into YAML frontmatter on the .md — uniform shape across bundled + project.
• Project teams ship internal SQL without forking: drop <id>.sql into .codemap/recipes/, every team member runs codemap query --recipe internal-flaky-tests. Git-tracked source code, code-reviewable in PRs.
• MCP discovery auto-inherits. codemap://recipes carries source: "bundled" | "project" on every entry + shadows: true on project entries that override bundled. Agents reading the catalog at session start see the override before they call the tool.

Settled grill questions

#	Question	Answer
Q-A	Bundled storage layout	File-pair <id>.{sql,md} (uniform with project; .sql syntax highlighting; single loader code path)
Q-B	Loading time	Eager at startup (sub-millisecond cost; "registry always populated")
Q-C	Project recipe discovery	Root-only — <projectRoot>/.codemap/recipes/ (consistent with .codemap.db resolution; walk-up is forward-compatible if a consumer asks)
Q-D	Project recipe actions	YAML frontmatter on <id>.md; hand-rolled parser (~50 LOC, no js-yaml dep)
Q-E	Conflict resolution	Silent at runtime + shadows: true flag at discovery + agent-skill prompt update (per-execution shape unchanged for plan §4 uniformity)
Q-F	Validation strictness	Both — load-time DML/DDL deny-list (recipe-aware UX) + runtime PRAGMA query_only=1 backstop (parser-proof safety net from PR #35)

Tracer-bullet sequence (all shipped)

• 1 — loader scaffold — src/application/recipes-loader.ts (pure transport-agnostic) + 15 tests
• 2 — migrate bundled recipes — 12 entries × .{sql,md} files in templates/recipes/; query-recipes.ts becomes a thin Proxy shim that preserves backwards-compat (QUERY_RECIPES, getQueryRecipeSql, etc.)
• 3 — project-local loader — .codemap/recipes/<id>.sql discovery + sibling .md + shadow detection
• 4 — catalog payload extension — --recipes-json and MCP resources gain body / source / shadows fields
• 5 — YAML frontmatter parser + DML/DDL deny-list — bundled BUNDLED_RECIPE_ACTIONS map deleted; uniform shape end-to-end
• 6 — docs + agents update — 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:

• src/application/recipes-loader.ts — pure loader (file-pair reading, frontmatter parsing, validation, merging with shadow detection). No CLI / runtime dependency.
• src/cli/query-recipes.ts — thin shim. Caches loader output keyed by (bundledDir, projectDir) so multi-root sessions re-resolve cleanly. Preserves legacy QUERY_RECIPES Proxy + getQueryRecipeSql / getQueryRecipeActions / listQueryRecipeIds / listQueryRecipeCatalog exports for callers.
• src/application/mcp-server.ts — codemap://recipes/{id} resource now uses getQueryRecipeCatalogEntry() so per-id payload includes body / source / shadows.

Test plan

• bun run check green (typecheck + lint + format + tests + benchmark)
• 54 unit tests across recipes-loader.test.ts (43) + query-recipes.test.ts (11) — covers every grill decision: file-pair loading, sibling-md pairing, shadow detection, DML/DDL deny-list (every keyword + case-insensitive + comment-stripping), YAML frontmatter (no-frontmatter / type-only / type+description / auto_fixable boolean / multiple items / no-actions-key / malformed), root-only resolution, eager cache invalidation across roots
• Smoke tested: bun src/index.ts query --recipes-json and --print-sql fan-out against the new file-based registry — output unchanged
• CI green on every push

Self-audit

• ✅ .agents/ rules respected (tracer-bullets, verify-after-each-step, concise-comments — backticks-in-comments lessons re-learned twice and already in .agents/lessons.md)
• ✅ Performance: eager-cached, projectDir-keyed; no new deps; hand-rolled YAML scoped to actions only
• ✅ Architecture: clean engine seam; backwards-compat Proxy shim
• ✅ Gitignore verified via git check-ignore: .codemap/recipes/ is not matched by the existing .codemap.* literal-dot pattern; recipes are git-tracked source by default
• ✅ Defence in depth on safety: load-time lexical check + runtime PRAGMA query_only=1 backstop

Composition with shipped surface

Reuses every bundled-recipe entry-point from PRs #26 / #28 / #30 / #33 / #35. The MCP resources auto-inherit project recipes since they call listQueryRecipeCatalog() (which becomes the loader). No new MCP tools, no new CLI flags.

Summary by CodeRabbit

• New Features
  • Create project-local recipes in .codemap/recipes/ (SQL + optional Markdown actions/body)
  • Project recipes override bundled ones; catalog marks overrides with shadows and reports recipe source and body
  • Catalog/CLI now exposes enriched recipe metadata (body, source, shadows) and supports --recipes-json output
• Documentation
  • Added docs and README examples for creating, overriding, and git-tracking recipes
• Tests
  • Comprehensive tests for loading, merging, frontmatter parsing, and SQL safety validation

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 5c527625-ea1f-4b83-9d7a-eb0d48ad62c5

📥 Commits

Reviewing files that changed from the base of the PR and between 126a518 and e71dddc.

📒 Files selected for processing (11)

• .agents/rules/codemap.md
• .agents/skills/codemap/SKILL.md
• README.md
• docs/glossary.md
• src/application/recipes-loader.test.ts
• src/application/recipes-loader.ts
• templates/agents/rules/codemap.md
• templates/agents/skills/codemap/SKILL.md
• templates/recipes/deprecated-symbols.md
• templates/recipes/fan-in.md
• templates/recipes/fan-out.md

✅ Files skipped from review due to trivial changes (7)

• templates/agents/rules/codemap.md
• .agents/rules/codemap.md
• docs/glossary.md
• templates/recipes/fan-in.md
• README.md
• src/application/recipes-loader.test.ts
• templates/agents/skills/codemap/SKILL.md

🚧 Files skipped from review as they are similar to previous changes (4)

• .agents/skills/codemap/SKILL.md
• templates/recipes/deprecated-symbols.md
• templates/recipes/fan-out.md
• src/application/recipes-loader.ts

---

📝 Walkthrough

Walkthrough

Adds a transport-agnostic recipes loader and runtime shim that loads bundled templates/recipes/*.sql (+ optional *.md frontmatter), auto-discovers project-local <projectRoot>/.codemap/recipes/*.sql (optional *.md), validates SQL at load time (deny-list for DML/DDL), and surfaces enriched catalog entries with body, source, and shadows metadata.

Changes

Recipes-as-Content Registry & Project-Local Overrides

Layer / File(s)	Summary
Data Shape src/application/recipes-loader.ts	Adds RecipeAction, LoadedRecipe (includes source and shadows), and LoadRecipesOpts interfaces.
Core Recipe Loader src/application/recipes-loader.ts	Implements loadAllRecipes, readRecipesFromDir, mergeRecipes, validateRecipeSql, extractFrontmatterAndBody. Handles .sql discovery, optional .md YAML-frontmatter actions parsing (restricted), empty-SQL rejection, DML/DDL deny-list, deterministic sorting, and project-over-bundled shadowing.
Loader Tests src/application/recipes-loader.test.ts	Comprehensive tests for read/merge/load/validation/frontmatter behaviors and integration of .md actions/description.
CLI Runtime Wiring src/cli/query-recipes.ts	Replaces in-file QUERY_RECIPES with a lazily-loaded registry (cached by project root) backed by loadAllRecipes. Adds resolveBundledRecipesDir, resolveProjectRecipesDir, _resetRecipesCacheForTests, expands QueryRecipeCatalogEntry to include body?, source, shadows?, and adds getQueryRecipeCatalogEntry. Re-exports RecipeAction from loader.
CLI Runtime Tests src/cli/query-recipes.test.ts	Tests directory resolution, runtime shim behavior (bundled vs project overrides), catalog source/body/shadows fields, and single-entry lookup.
MCP Transport Wiring src/application/mcp-server.ts	Switches MCP resource handlers to use listQueryRecipeCatalog() and getQueryRecipeCatalogEntry(id); throws for unknown recipe IDs and surfaces source/shadows/body.
Bundled Recipes Content templates/recipes/*.{sql,md}	Adds/updates multiple SQL recipe templates and optional .md frontmatter documents (e.g., barrel-files, components-by-hooks, deprecated-symbols, fan-in, fan-out, files-hashes, files-largest, index-summary, markers-by-kind, visibility-tags, etc.) where actions live in .md frontmatter.
Docs & Templates README.md, docs/*, .agents/*, templates/agents/*	Documents project-local recipes, override semantics (shadows: true), frontmatter actions shape, load-time SQL validation, and git-tracking rules (.codemap/recipes/ tracked; .codemap.db gitignored). Removes backlog roadmap item.

Sequence Diagram

sequenceDiagram
    participant CLI as CLI: codemap query
    participant QR as QueryRuntime (src/cli/query-recipes.ts)
    participant RL as RecipesLoader (src/application/recipes-loader.ts)
    participant FS as Filesystem
    participant DB as Query Engine

    CLI->>QR: listQueryRecipeCatalog() / getQueryRecipeSql(id)
    QR->>QR: check cache for projectRoot
    alt cache miss
        QR->>RL: loadAllRecipes({bundledDir, projectDir?})
        RL->>FS: read bundledDir (*.sql / *.md)
        RL->>FS: read projectDir (*.sql / *.md) [if exists]
        RL->>RL: validateRecipeSql (strip comments, deny DML/DDL)
        RL->>RL: extractFrontmatterAndBody (parse actions)
        RL->>RL: mergeRecipes (project shadows bundled)
        RL-->>QR: LoadedRecipe[] (with source/shadows/body)
        QR->>QR: cache registry by projectRoot
    end
    QR->>CLI: catalog entries or SQL
    CLI->>DB: execute recipe SQL (PRAGMA query_only=1 enforced)
    DB-->>CLI: results

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• feat(cli): codemap validate / context / --performance, four new query recipes, friendlier no-DB error #23 — overlapping changes to bundled recipes and query-recipes/catalog wiring (many same recipe templates and catalog shape).
• feat(mcp): codemap mcp — agent-transports v1 (Tracer 1 of 7) #35 — MCP server recipe resource wiring updates consuming the new catalog APIs (source/shadows) touched here.
• feat(query): Tier A flags (--summary, --changed-since, --group-by) + per-row recipe actions #26 — touches RecipeAction and catalog entry structures; related to the expanded recipe schema.

Suggested labels

enhancement, documentation

Poem

🐰
Recipes scattered like seeds in a bed,
SQL and Markdown now both share a shed.
Project recipes whisper, "I shadow the rest,"
Safe queries first — then the agents do the rest. 🌱

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 65.38% 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 title directly and accurately describes the main change: implementing a recipes-as-content registry with bundled Markdown files and project-local recipes support.
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 docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/recipes-content-registry

---

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 60 minutes.}

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

[changeset-bot]

🦋 Changeset detected

Latest commit: e71dddc

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

[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: 7

Caution

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

⚠️ Outside diff range comments (1)

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

202-204: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Update MCP descriptions to include project-local recipes.

Both descriptions still say “bundled” even though this PR now serves bundled + project entries. This can mislead host UIs and tool introspection output.

Suggested wording patch

- "Run a bundled SQL recipe by id. Output rows carry per-row `actions` hints ...
+ "Run a cataloged SQL recipe by id (bundled or project-local). Output rows carry per-row `actions` hints ...

- "Bundled SQL recipes catalog (id, description, sql, optional per-row actions). Same payload as `codemap query --recipes-json`."
+ "SQL recipes catalog (bundled + project-local) with id, description, sql, optional actions, and provenance fields. Same payload as `codemap query --recipes-json`."

Also applies to: 587-589

🤖 Prompt for AI Agents

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

In `@src/application/mcp-server.ts` around lines 202 - 204, Update the user-facing
description strings that currently say “bundled” to indicate the server serves
both bundled and project-local recipes; specifically edit the description
property for the recipe-running RPC (the string mentioning "Run a bundled SQL
recipe by id" and the reference to "codemap://recipes") and the other similar
description later in the file so they read e.g. "Run a bundled and project-local
SQL recipe by id" (or "bundled + project-local") and include the same
clarification where the other description appears (the second description block
that mirrors the first).

🧹 Nitpick comments (1)

.agents/rules/codemap.md (1)

32-32: ⚡ Quick win

Add a concrete YAML frontmatter example for actions.
This line describes the shape, but a copy-pasteable example would make project recipe config unambiguous.

Proposed doc patch

 **Project-local recipes:** drop `<id>.sql` (and optional `<id>.md` for description + actions) into **`<projectRoot>/.codemap/recipes/`** — auto-discovered, runs via `--recipe <id>` like bundled. Project recipes win on id collision; check `--recipes-json` for **`shadows: true`** entries to know when a project recipe overrides the documented bundled version. `<id>.md` supports YAML frontmatter (`actions: [{type, auto_fixable?, description?}]`) for the per-row action template — same shape as bundled recipes. Validation: SQL is rejected at load time if it starts with DML/DDL (DELETE/DROP/UPDATE/etc.); the runtime `PRAGMA query_only=1` is the parser-proof backstop.
+
+Example `<projectRoot>/.codemap/recipes/fan-out.md`:
+
+```md
+---
+actions:
+  - type: review-coupling
+    description: "Inspect high fan-out files for extraction opportunities."
+---
+Top fan-out files to review first.
+```

As per coding guidelines: **/*.{json,yaml,yml,md}: Document all configuration options with examples.

🤖 Prompt for AI Agents

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

In @.agents/rules/codemap.md at line 32, Add a concrete YAML frontmatter example
for the per-recipe `actions` schema referenced in the `.codemap/recipes/` docs:
update the paragraph that currently shows the shape `actions: [{type,
auto_fixable?, description?}]` for `<id>.md` to include a copy-pasteable example
showing at least one action entry (fields: `type`, optional `auto_fixable`, and
`description`) so readers can see exact YAML syntax and placement; reference the
`<id>.md` frontmatter usage and ensure the example aligns with the documented
action types (e.g., `review-coupling`) and clarifies that the example sits
between `---` markers in the recipe markdown.

🤖 Prompt for all review comments with AI agents

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

Inline comments:
In `@docs/glossary.md`:
- Around line 328-334: Update the earlier "Recipe" convention that still
describes recipes as only bundled SQL in src/cli/query-recipes.ts to match the
new global definition in docs/glossary.md and src/application/recipes-loader.ts:
state that recipes are a .sql file with an optional sibling .md (bundled under
templates/recipes/<id>.{sql,md} or project-local under
<projectRoot>/.codemap/recipes/<id>.{sql,md}), note project-local overrides
bundled (shadows: true), that actions live in YAML frontmatter of the .md, and
keep the run CLI hint (codemap query --recipe / -r) and validation/runtime
protections (load-time checks + PRAGMA query_only=1).

In `@README.md`:
- Around line 113-119: The example recipe uses the wrong language value — update
the SQL in the example and the recipe file (.codemap/recipes/big-ts-files.sql
and the README snippet) to use Codemap's indexed language code for TypeScript
(e.g. language = 'ts') instead of 'typescript' so the query will actually match
TypeScript files; ensure the README command example remains the same (codemap
query --recipe big-ts-files) but with the corrected SQL content.

In `@src/application/recipes-loader.ts`:
- Around line 199-215: The current empty-SQL check only strips line comments via
stripLineComments and lets recipes consisting solely of /* ... */ block comments
pass or wrongly trigger deny-list matches; update the logic so block comments
are removed prior to validation: either extend stripLineComments (or create a
new stripComments function) to remove all /* ... */ block comments (multi-line)
as well as -- line comments, then have isEffectivelyEmpty call that function and
ensure validateRecipeSql runs its deny-list checks against the comment-stripped
SQL; reference stripLineComments, isEffectivelyEmpty and validateRecipeSql when
making the change.

In `@templates/agents/rules/codemap.md`:
- Line 39: The documentation for project recipe `<id>.md` frontmatter currently
shows an inline/flow YAML example that could be copied incorrectly; update the
`<id>.md` frontmatter example to show the block-list YAML form that the loader
expects (top-level actions: followed by newline-prefixed - type: entries) and
explicitly state that only the top-level actions: key with list items like -
type: ... (and optional auto_fixable?, description?) is parsed; reference the
loader's expected keys by name (`actions:`, `- type:`, `auto_fixable?`,
`description?`) and add a short note warning that inline flow syntax will be
ignored so authors should use the block list format.

In `@templates/recipes/deprecated-symbols.md`:
- Around line 7-9: The template references a non-existent column `name` in the
example query; update the guidance in deprecated-symbols.md to use the actual
column `callee_name` when instructing agents to find call sites (replace the
suggested `WHERE name = '<symbol>'` with `WHERE callee_name = '<symbol>'` and
ensure the text mentions the `calls` table and `callee_name` explicitly so
agents run valid queries).

In `@templates/recipes/fan-in.md`:
- Line 9: Replace the phrase "most-imported" with "most depended-on" in the
templates/recipes/fan-in.md content (and any other occurrences in that file) so
the description aligns with the dependency-edge data model; update surrounding
sentence to read something like "Files at the top are the most depended-on in
the codebase — changes here ripple through many consumers." and ensure
terminology consistency across the file.

In `@templates/recipes/fan-out.md`:
- Line 9: The sentence uses "import from many other files" which narrows the
metric; update the wording by replacing that phrase with "depend on many other
files" so the recipe describes dependency fan-out accurately, and scan the
surrounding text in the same document for similar occurrences to standardize
terminology to "depend" instead of "import" where appropriate.

---

Outside diff comments:
In `@src/application/mcp-server.ts`:
- Around line 202-204: Update the user-facing description strings that currently
say “bundled” to indicate the server serves both bundled and project-local
recipes; specifically edit the description property for the recipe-running RPC
(the string mentioning "Run a bundled SQL recipe by id" and the reference to
"codemap://recipes") and the other similar description later in the file so they
read e.g. "Run a bundled and project-local SQL recipe by id" (or "bundled +
project-local") and include the same clarification where the other description
appears (the second description block that mirrors the first).

---

Nitpick comments:
In @.agents/rules/codemap.md:
- Line 32: Add a concrete YAML frontmatter example for the per-recipe `actions`
schema referenced in the `.codemap/recipes/` docs: update the paragraph that
currently shows the shape `actions: [{type, auto_fixable?, description?}]` for
`<id>.md` to include a copy-pasteable example showing at least one action entry
(fields: `type`, optional `auto_fixable`, and `description`) so readers can see
exact YAML syntax and placement; reference the `<id>.md` frontmatter usage and
ensure the example aligns with the documented action types (e.g.,
`review-coupling`) and clarifies that the example sits between `---` markers in
the recipe markdown.

🪄 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: e33620f9-0a01-48e8-87da-1268c804ead2

📥 Commits

Reviewing files that changed from the base of the PR and between bb59905 and 126a518.

📒 Files selected for processing (38)

• .agents/rules/codemap.md
• .agents/skills/codemap/SKILL.md
• .changeset/recipes-content-registry.md
• README.md
• docs/architecture.md
• docs/glossary.md
• docs/roadmap.md
• src/application/mcp-server.ts
• src/application/recipes-loader.test.ts
• src/application/recipes-loader.ts
• src/cli/query-recipes.test.ts
• src/cli/query-recipes.ts
• templates/agents/rules/codemap.md
• templates/agents/skills/codemap/SKILL.md
• templates/recipes/barrel-files.md
• templates/recipes/barrel-files.sql
• templates/recipes/components-by-hooks.md
• templates/recipes/components-by-hooks.sql
• templates/recipes/deprecated-symbols.md
• templates/recipes/deprecated-symbols.sql
• templates/recipes/fan-in.md
• templates/recipes/fan-in.sql
• templates/recipes/fan-out-sample-json.md
• templates/recipes/fan-out-sample-json.sql
• templates/recipes/fan-out-sample.md
• templates/recipes/fan-out-sample.sql
• templates/recipes/fan-out.md
• templates/recipes/fan-out.sql
• templates/recipes/files-hashes.md
• templates/recipes/files-hashes.sql
• templates/recipes/files-largest.md
• templates/recipes/files-largest.sql
• templates/recipes/index-summary.md
• templates/recipes/index-summary.sql
• templates/recipes/markers-by-kind.md
• templates/recipes/markers-by-kind.sql
• templates/recipes/visibility-tags.md
• templates/recipes/visibility-tags.sql

💤 Files with no reviewable changes (1)

• docs/roadmap.md