feat(recipes): migrate bundled recipes to templates/recipes/<id>.{sql,md} (Tracer 2 of 6)

SutuSebastian · SutuSebastian · commit 7fec23e4b7f7 · 2026-05-01T22:19:48.000+03:00
QUERY_RECIPES TypeScript object map → templates/recipes/&lt;id&gt;.sql + sibling .md description files. cli/query-recipes.ts becomes a thin shim that calls loadAllRecipes() at first access and caches the result.

12 bundled recipes migrated: fan-out, fan-out-sample, fan-out-sample-json, fan-in, index-summary, files-largest, components-by-hooks, markers-by-kind, deprecated-symbols, visibility-tags, files-hashes, barrel-files. Each gets a .sql file (verbatim) + .md (description body — first non-empty line becomes the catalog 'description').

Backwards-compat preserved:
- QUERY_RECIPES exported as a Proxy so callers (cmd-query.ts, mcp-server.ts) can still use the legacy object-shape access (QUERY_RECIPES['fan-out'].description, Object.keys(QUERY_RECIPES), etc.) without changes
- getQueryRecipeSql / getQueryRecipeActions / listQueryRecipeIds / listQueryRecipeCatalog all derive from the registry — same return shapes
- Smoke tested: bun src/index.ts query --recipes-json + query --print-sql fan-out + query-golden all green

Bundled recipe actions stay in code (BUNDLED_RECIPE_ACTIONS map) through Tracer 5 — that tracer adds the YAML frontmatter parser and lifts these into the .md files alongside descriptions, completing the migration.

New: resolveBundledRecipesDir() in cli/query-recipes.ts mirrors resolveAgentsTemplateDir()'s npm-package layout (templates/recipes/ next to templates/agents/). _resetRecipesCacheForTests() escape hatch added for fixture swaps.

templates/ already shipped in the npm artifact (per package.json files); templates/recipes/ inherits.

Tracer 1's loader now has a real consumer; Tracer 3 will plug in projectDir for .codemap/recipes/&lt;id&gt;.sql discovery.
diff --git a/src/cli/query-recipes.ts b/src/cli/query-recipes.ts
diff --git a/templates/recipes/barrel-files.md b/templates/recipes/barrel-files.md
@@ -0,0 +1,3 @@
+Top 20 files by export count (barrel / public-API candidates)
+
+High export count can indicate either an intentional public API surface or accidental fan-out. Agents can use this to decide whether a new export should land here or stay local. If it's accidental fan-out, consider splitting into smaller barrels.
diff --git a/templates/recipes/barrel-files.sql b/templates/recipes/barrel-files.sql
@@ -0,0 +1,5 @@
+SELECT file_path, COUNT(*) AS exports
+FROM exports
+GROUP BY file_path
+ORDER BY exports DESC, file_path ASC
+LIMIT 20
diff --git a/templates/recipes/components-by-hooks.md b/templates/recipes/components-by-hooks.md
@@ -0,0 +1,3 @@
+React components with the most hooks (comma count on stored JSON array)
+
+Hook count uses comma tally + 1 on the stored JSON array (Codemap emits flat `["useFoo","useBar"]` shapes). Avoids SQLite JSON1 (`json_array_length`) so the recipe runs on any SQLite build the CLI already supports.
diff --git a/templates/recipes/components-by-hooks.sql b/templates/recipes/components-by-hooks.sql
@@ -0,0 +1,8 @@
+SELECT name, file_path,
+  CASE
+    WHEN hooks_used IS NULL OR trim(hooks_used) = '' OR trim(hooks_used) = '[]' THEN 0
+    ELSE (length(hooks_used) - length(replace(hooks_used, ',', ''))) + 1
+  END AS hook_count
+FROM components
+ORDER BY hook_count DESC, file_path ASC, name ASC
+LIMIT 20
diff --git a/templates/recipes/deprecated-symbols.md b/templates/recipes/deprecated-symbols.md
@@ -0,0 +1,3 @@
+Symbols whose JSDoc contains @deprecated (caller-warning candidates)
+
+Useful for agents to flag callers of soon-to-be-removed APIs before suggesting changes. Pair with `WHERE name = '<symbol>'` against the `calls` table to find the actual call sites.
diff --git a/templates/recipes/deprecated-symbols.sql b/templates/recipes/deprecated-symbols.sql
@@ -0,0 +1,5 @@
+SELECT name, kind, file_path, line_start, signature, doc_comment
+FROM symbols
+WHERE doc_comment LIKE '%@deprecated%'
+ORDER BY file_path ASC, line_start ASC
+LIMIT 50
diff --git a/templates/recipes/fan-in.md b/templates/recipes/fan-in.md
@@ -0,0 +1,3 @@
+Top 15 files by fan-in (how many other files depend on them)
+
+Files at the top are the most-imported in the codebase — changes here ripple through many consumers. Protect with tests before refactoring; treat as the project's de-facto stable API even if not formally exported.
diff --git a/templates/recipes/fan-in.sql b/templates/recipes/fan-in.sql
@@ -0,0 +1,5 @@
+SELECT to_path, COUNT(*) AS fan_in
+FROM dependencies
+GROUP BY to_path
+ORDER BY fan_in DESC, to_path ASC
+LIMIT 15
diff --git a/templates/recipes/fan-out-sample-json.md b/templates/recipes/fan-out-sample-json.md
@@ -0,0 +1,3 @@
+Like fan-out-sample, but sample_targets is a JSON array (requires JSON1)
+
+Same ranking as `fan-out-sample`, but uses SQLite's JSON1 `json_group_array`. Prefer `fan-out-sample` if your SQLite build doesn't include JSON1.
diff --git a/templates/recipes/fan-out-sample-json.sql b/templates/recipes/fan-out-sample-json.sql
@@ -0,0 +1,9 @@
+SELECT d.from_path,
+  COUNT(*) AS deps,
+  (SELECT json_group_array(to_path)
+   FROM (SELECT to_path FROM dependencies d2 WHERE d2.from_path = d.from_path ORDER BY to_path ASC LIMIT 5))
+    AS sample_targets
+FROM dependencies d
+GROUP BY d.from_path
+ORDER BY deps DESC, d.from_path ASC
+LIMIT 10
diff --git a/templates/recipes/fan-out-sample.md b/templates/recipes/fan-out-sample.md
@@ -0,0 +1 @@
+Top 10 by fan-out, plus up to five sample dependency targets per file
diff --git a/templates/recipes/fan-out-sample.sql b/templates/recipes/fan-out-sample.sql
@@ -0,0 +1,9 @@
+SELECT d.from_path,
+  COUNT(*) AS deps,
+  (SELECT GROUP_CONCAT(to_path, ' | ')
+   FROM (SELECT to_path FROM dependencies d2 WHERE d2.from_path = d.from_path ORDER BY to_path ASC LIMIT 5))
+    AS sample_targets
+FROM dependencies d
+GROUP BY d.from_path
+ORDER BY deps DESC, d.from_path ASC
+LIMIT 10
diff --git a/templates/recipes/fan-out.md b/templates/recipes/fan-out.md
@@ -0,0 +1,3 @@
+Top 10 files by dependency fan-out (edge count)
+
+Files at the top of this list act as orchestrators — they import from many other files. High fan-out usually means coordination logic that's a candidate for refactoring (extracting helpers, splitting responsibilities). Pair with `fan-in` to see hubs that are both depended-on AND depend-on-many.
diff --git a/templates/recipes/fan-out.sql b/templates/recipes/fan-out.sql
@@ -0,0 +1,5 @@
+SELECT from_path, COUNT(*) AS deps
+FROM dependencies
+GROUP BY from_path
+ORDER BY deps DESC, from_path ASC
+LIMIT 10
diff --git a/templates/recipes/files-hashes.md b/templates/recipes/files-hashes.md
@@ -0,0 +1,3 @@
+All indexed files with content_hash (input for staleness checks)
+
+Powers the `codemap validate` CLI: callers diff this list against on-disk content to detect stale entries without paying to re-read every file.
diff --git a/templates/recipes/files-hashes.sql b/templates/recipes/files-hashes.sql
@@ -0,0 +1,3 @@
+SELECT path, content_hash, language, line_count
+FROM files
+ORDER BY path ASC
diff --git a/templates/recipes/files-largest.md b/templates/recipes/files-largest.md
@@ -0,0 +1,3 @@
+Top 20 files by line count (size/complexity hotspots)
+
+Files this large are typical refactor candidates. Look for cohesive sub-modules to extract — each split should reduce coupling, not just shuffle lines.
diff --git a/templates/recipes/files-largest.sql b/templates/recipes/files-largest.sql
@@ -0,0 +1,4 @@
+SELECT path, line_count, size, language
+FROM files
+ORDER BY line_count DESC, path ASC
+LIMIT 20
diff --git a/templates/recipes/index-summary.md b/templates/recipes/index-summary.md
@@ -0,0 +1 @@
+Single row: row counts for main tables (quick health snapshot)
diff --git a/templates/recipes/index-summary.sql b/templates/recipes/index-summary.sql
@@ -0,0 +1,6 @@
+SELECT
+  (SELECT COUNT(*) FROM files) AS files,
+  (SELECT COUNT(*) FROM symbols) AS symbols,
+  (SELECT COUNT(*) FROM imports) AS imports,
+  (SELECT COUNT(*) FROM components) AS components,
+  (SELECT COUNT(*) FROM dependencies) AS dependencies
diff --git a/templates/recipes/markers-by-kind.md b/templates/recipes/markers-by-kind.md
@@ -0,0 +1 @@
+Marker counts by kind (TODO, FIXME, …)
diff --git a/templates/recipes/markers-by-kind.sql b/templates/recipes/markers-by-kind.sql
@@ -0,0 +1,4 @@
+SELECT kind, COUNT(*) AS count
+FROM markers
+GROUP BY kind
+ORDER BY count DESC, kind ASC
diff --git a/templates/recipes/visibility-tags.md b/templates/recipes/visibility-tags.md
@@ -0,0 +1,3 @@
+Symbols carrying a JSDoc visibility tag (public / private / internal / alpha / beta)
+
+Useful for agents to know what is _not_ part of the public API before suggesting imports or extending re-exports. The `visibility` column is structured (parsed at index time, not regex on `doc_comment`).
diff --git a/templates/recipes/visibility-tags.sql b/templates/recipes/visibility-tags.sql
@@ -0,0 +1,5 @@
+SELECT name, kind, visibility, file_path, line_start, signature, doc_comment
+FROM symbols
+WHERE visibility IS NOT NULL
+ORDER BY file_path ASC, line_start ASC
+LIMIT 100

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+Top 20 files by export count (barrel / public-API candidates)`
	`2`	`+`
	`3`	`+High export count can indicate either an intentional public API surface or accidental fan-out. Agents can use this to decide whether a new export should land here or stay local. If it's accidental fan-out, consider splitting into smaller barrels.`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+React components with the most hooks (comma count on stored JSON array)`
	`2`	`+`
	`3`	+Hook count uses comma tally + 1 on the stored JSON array (Codemap emits flat `["useFoo","useBar"]` shapes). Avoids SQLite JSON1 (`json_array_length`) so the recipe runs on any SQLite build the CLI already supports.
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+Symbols whose JSDoc contains @deprecated (caller-warning candidates)`
	`2`	`+`
	`3`	+Useful for agents to flag callers of soon-to-be-removed APIs before suggesting changes. Pair with `WHERE name = '<symbol>'` against the `calls` table to find the actual call sites.
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+Top 15 files by fan-in (how many other files depend on them)`
	`2`	`+`
	`3`	`+Files at the top are the most-imported in the codebase — changes here ripple through many consumers. Protect with tests before refactoring; treat as the project's de-facto stable API even if not formally exported.`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+Like fan-out-sample, but sample_targets is a JSON array (requires JSON1)`
	`2`	`+`
	`3`	+Same ranking as `fan-out-sample`, but uses SQLite's JSON1 `json_group_array`. Prefer `fan-out-sample` if your SQLite build doesn't include JSON1.