feat(recipes): project-local loader for .codemap/recipes/<id>.sql (Tracer 3 of 6)

Wires up the actually-new user-facing capability per plan §1: teams ship internal SQL recipes via git-tracked .codemap/recipes/<id>.sql files.

Three pieces:

1. loadAllRecipes now reads opts.projectDir (was stubbed in Tracer 1). Composes via mergeRecipes — project wins on id collision with shadows: true flag (per Q-E settled).

2. resolveProjectRecipesDir(projectRoot) — root-only resolution per Q-C (no walk-up). Returns undefined if .codemap/recipes/ is missing or is a file rather than a directory; absence is not an error.

3. cli/query-recipes.ts shim's getRegistry() now resolves projectDir via getProjectRoot() (falls back to bundled-only if initCodemap hasn't run — covers direct unit-test paths). Cache key includes projectDir so multi-root sessions (test fixtures) re-resolve cleanly. _resetRecipesCacheForTests clears both halves.

5 new loader-engine tests: bundled-only / bundled+project / shadow detection / sorted ordering / missing-dir. 7 new shim tests: 3 for resolveProjectRecipesDir (absent / present / file-not-dir) + 4 for the end-to-end shim path (bundled-only baseline / project-local id surfaces / project shadows bundled / catalog merging).

Project recipes get actions: undefined through Tracer 5 — that tracer adds the YAML frontmatter parser.

Author: SutuSebastian

src/application/recipes-loader.test.ts

@@ -170,25 +170,54 @@ describe("mergeRecipes", () => {
   });
 });
 
-describe("loadAllRecipes (Tracer 1 — bundled-only path)", () => {
-  it("loads bundled, ignores projectDir stub", () => {
-    const dir = makeRecipeDir("bundled-stub");
+describe("loadAllRecipes — bundled + project composition", () => {
+  it("loads bundled-only when projectDir is undefined", () => {
+    const dir = makeRecipeDir("bundled-only");
     writeFileSync(join(dir, "fan-out.sql"), "SELECT 1\n");
     const r = loadAllRecipes({ bundledDir: dir, projectDir: undefined });
     expect(r).toHaveLength(1);
     expect(r[0]!.source).toBe("bundled");
   });
 
-  it("ignores a projectDir argument in Tracer 1 (project loader stubbed)", () => {
+  it("loads bundled + project, sorted by id", () => {
     const bundledDir = makeRecipeDir("bundled");
     const projectDir = makeRecipeDir("project");
-    writeFileSync(join(bundledDir, "x.sql"), "SELECT 1\n");
+    writeFileSync(join(bundledDir, "fan-out.sql"), "SELECT 1\n");
+    writeFileSync(
+      join(projectDir, "internal-flaky-tests.sql"),
+      "SELECT path FROM files\n",
+    );
+    const r = loadAllRecipes({ bundledDir, projectDir });
+    expect(r.map((x) => `${x.id}:${x.source}`)).toEqual([
+      "fan-out:bundled",
+      "internal-flaky-tests:project",
+    ]);
+  });
+
+  it("project recipe shadows bundled with same id (project wins, shadows: true)", () => {
+    const bundledDir = makeRecipeDir("bundled-shadowed");
+    const projectDir = makeRecipeDir("project-shadowing");
+    writeFileSync(join(bundledDir, "fan-out.sql"), "SELECT 1\n");
     writeFileSync(
-      join(projectDir, "y.sql"),
-      "SELECT 2\n",
-      // Will load in Tracer 3; for now project recipes are silently dropped.
+      join(projectDir, "fan-out.sql"),
+      "SELECT 'project version'\n",
     );
     const r = loadAllRecipes({ bundledDir, projectDir });
-    expect(r.map((x) => x.id)).toEqual(["x"]);
+    expect(r).toHaveLength(1);
+    const recipe = r[0]!;
+    expect(recipe.source).toBe("project");
+    expect(recipe.shadows).toBe(true);
+    expect(recipe.sql).toContain("project version");
+  });
+
+  it("missing .codemap/recipes/ directory is not an error", () => {
+    const bundledDir = makeRecipeDir("bundled");
+    writeFileSync(join(bundledDir, "x.sql"), "SELECT 1\n");
+    const r = loadAllRecipes({
+      bundledDir,
+      projectDir: join(workDir, "does-not-exist"),
+    });
+    expect(r).toHaveLength(1);
+    expect(r[0]!.source).toBe("bundled");
   });
 });

src/application/recipes-loader.ts

@@ -61,12 +61,10 @@ export interface LoadRecipesOpts {
  */
 export function loadAllRecipes(opts: LoadRecipesOpts): LoadedRecipe[] {
   const bundled = readRecipesFromDir(opts.bundledDir, "bundled");
-
-  // Tracer 1: project loader is a stub. Tracer 3 implements it + the
-  // shadow-flag merge logic (project wins; sets shadows: true when
-  // an id matches a bundled recipe).
-  const project: LoadedRecipe[] = [];
-
+  const project =
+    opts.projectDir !== undefined
+      ? readRecipesFromDir(opts.projectDir, "project")
+      : [];
   return mergeRecipes(bundled, project);
 }
 

src/cli/query-recipes.test.ts

@@ -0,0 +1,99 @@
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { resolveCodemapConfig } from "../config";
+import { initCodemap } from "../runtime";
+import {
+  _resetRecipesCacheForTests,
+  getQueryRecipeActions,
+  getQueryRecipeSql,
+  listQueryRecipeCatalog,
+  listQueryRecipeIds,
+  resolveProjectRecipesDir,
+} from "./query-recipes";
+
+let projectRoot: string;
+
+beforeEach(() => {
+  projectRoot = mkdtempSync(join(tmpdir(), "query-recipes-"));
+  initCodemap(resolveCodemapConfig(projectRoot, undefined));
+  _resetRecipesCacheForTests();
+});
+
+afterEach(() => {
+  rmSync(projectRoot, { recursive: true, force: true });
+  _resetRecipesCacheForTests();
+});
+
+describe("resolveProjectRecipesDir", () => {
+  it("returns undefined when .codemap/recipes/ is absent", () => {
+    expect(resolveProjectRecipesDir(projectRoot)).toBeUndefined();
+  });
+
+  it("returns the directory path when present", () => {
+    const recipesDir = join(projectRoot, ".codemap", "recipes");
+    mkdirSync(recipesDir, { recursive: true });
+    expect(resolveProjectRecipesDir(projectRoot)).toBe(recipesDir);
+  });
+
+  it("returns undefined when .codemap/recipes is a file (not directory)", () => {
+    mkdirSync(join(projectRoot, ".codemap"), { recursive: true });
+    writeFileSync(join(projectRoot, ".codemap", "recipes"), "not a dir");
+    expect(resolveProjectRecipesDir(projectRoot)).toBeUndefined();
+  });
+});
+
+describe("query-recipes shim — project recipes via runtime root", () => {
+  it("bundled-only when no .codemap/recipes/ exists", () => {
+    const ids = listQueryRecipeIds();
+    expect(ids).toContain("fan-out");
+    expect(ids).toContain("deprecated-symbols");
+    // No project recipes; every entry in the catalog has source: "bundled".
+    // (catalog shape is the legacy QueryRecipeCatalogEntry through Tracer 4
+    // — Tracer 4 adds source/body/shadows fields. For now confirm presence.)
+    expect(ids.length).toBeGreaterThan(0);
+  });
+
+  it("loads project-local recipes from .codemap/recipes/<id>.sql", () => {
+    const recipesDir = join(projectRoot, ".codemap", "recipes");
+    mkdirSync(recipesDir, { recursive: true });
+    writeFileSync(
+      join(recipesDir, "internal-flaky-tests.sql"),
+      "SELECT path FROM files WHERE 1=0\n",
+    );
+    _resetRecipesCacheForTests();
+
+    expect(listQueryRecipeIds()).toContain("internal-flaky-tests");
+    expect(getQueryRecipeSql("internal-flaky-tests")).toContain("WHERE 1=0");
+  });
+
+  it("project recipe shadows bundled — getQueryRecipeSql returns project version", () => {
+    const recipesDir = join(projectRoot, ".codemap", "recipes");
+    mkdirSync(recipesDir, { recursive: true });
+    writeFileSync(
+      join(recipesDir, "fan-out.sql"),
+      "SELECT 'project override' AS marker\n",
+    );
+    _resetRecipesCacheForTests();
+
+    const sql = getQueryRecipeSql("fan-out");
+    expect(sql).toContain("project override");
+    // The bundled fan-out had `actions` (review-coupling) — project version
+    // doesn't carry actions until Tracer 5 wires YAML frontmatter.
+    expect(getQueryRecipeActions("fan-out")).toBeUndefined();
+  });
+
+  it("listQueryRecipeCatalog includes project recipes alongside bundled", () => {
+    const recipesDir = join(projectRoot, ".codemap", "recipes");
+    mkdirSync(recipesDir, { recursive: true });
+    writeFileSync(join(recipesDir, "owner-fanout.sql"), "SELECT 1 AS x\n");
+    _resetRecipesCacheForTests();
+
+    const catalog = listQueryRecipeCatalog();
+    const ids = catalog.map((c) => c.id);
+    expect(ids).toContain("owner-fanout");
+    expect(ids).toContain("fan-out");
+  });
+});

src/cli/query-recipes.ts

@@ -1,8 +1,10 @@
+import { existsSync, statSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
 import { loadAllRecipes } from "../application/recipes-loader";
 import type { LoadedRecipe } from "../application/recipes-loader";
+import { getProjectRoot } from "../runtime";
 
 export type { RecipeAction } from "../application/recipes-loader";
 import type { RecipeAction } from "../application/recipes-loader";
@@ -38,6 +40,20 @@ export function resolveBundledRecipesDir(): string {
   );
 }
 
+/**
+ * Returns `<projectRoot>/.codemap/recipes/` if it exists as a directory,
+ * else `undefined`. Per plan §9 Q-C, root-only — no walk-up; same root
+ * the CLI's `--root` / `CODEMAP_ROOT` resolves to.
+ */
+export function resolveProjectRecipesDir(
+  projectRoot: string,
+): string | undefined {
+  const dir = join(projectRoot, ".codemap", "recipes");
+  if (!existsSync(dir)) return undefined;
+  if (!statSync(dir).isDirectory()) return undefined;
+  return dir;
+}
+
 /**
  * Bundled recipe `actions` templates. Per-row hint that surfaces in `--json`
  * output so agents see the recommended follow-up alongside each row. Lives
@@ -96,24 +112,39 @@ const BUNDLED_RECIPE_ACTIONS: Record<string, RecipeAction[]> = {
 /**
  * Module-cached registry — populated lazily on first access (loader is pure;
  * the cache means we pay the filesystem read once per process lifetime per
- * plan §9 Q-B). Project recipes (Tracer 3) will wire `projectDir` here once
- * the bootstrap layer can pass it in.
+ * plan §9 Q-B). Cache key includes `projectDir` so that a process running
+ * against multiple roots (test fixtures, multi-root MCP sessions later)
+ * re-resolves when the root changes.
  */
 let cachedRegistry: LoadedRecipe[] | undefined;
+let cachedRegistryProjectDir: string | undefined;
 
 function getRegistry(): LoadedRecipe[] {
-  if (cachedRegistry === undefined) {
-    cachedRegistry = loadAllRecipes({
-      bundledDir: resolveBundledRecipesDir(),
-      projectDir: undefined,
-    }).map((r) => ({
-      ...r,
-      // Stitch in the bundled actions map until Tracer 5 lifts them into
-      // frontmatter on each `.md` file.
-      actions:
-        r.source === "bundled" ? BUNDLED_RECIPE_ACTIONS[r.id] : r.actions,
-    }));
+  // `getProjectRoot()` throws if `initCodemap()` hasn't run; that only
+  // happens for direct unit tests of this module pre-bootstrap. Treat
+  // that as "no project recipes" — bundled-only registry.
+  let projectDir: string | undefined;
+  try {
+    projectDir = resolveProjectRecipesDir(getProjectRoot());
+  } catch {
+    projectDir = undefined;
   }
+
+  if (cachedRegistry !== undefined && cachedRegistryProjectDir === projectDir) {
+    return cachedRegistry;
+  }
+
+  cachedRegistry = loadAllRecipes({
+    bundledDir: resolveBundledRecipesDir(),
+    projectDir,
+  }).map((r) => ({
+    ...r,
+    // Stitch in the bundled actions map until Tracer 5 lifts them into
+    // frontmatter on each `.md` file. Project recipes get `actions: undefined`
+    // until Tracer 5 plugs the YAML frontmatter parser.
+    actions: r.source === "bundled" ? BUNDLED_RECIPE_ACTIONS[r.id] : r.actions,
+  }));
+  cachedRegistryProjectDir = projectDir;
   return cachedRegistry;
 }
 
@@ -122,6 +153,7 @@ function getRegistry(): LoadedRecipe[] {
  */
 export function _resetRecipesCacheForTests(): void {
   cachedRegistry = undefined;
+  cachedRegistryProjectDir = undefined;
 }
 
 /**