feat(affected): affected-tests recipe + codemap affected CLI (#132)

SutuSebastian · web-flow · commit 8a1de53ae978 · 2026-05-25T16:18:10.000+03:00
* feat(cli): add affected-tests recipe and codemap affected command

Reverse-dependency walk from changed files to test paths via test_suites
and default test suffix globs; stdin/git/positional path sources.

* docs: link PR 132 in agent-surface delivery tracker

* docs: fix quick-resume link for PR 132

* fix(cli): address PR 132 review findings

Document affected in README and skill; fix test_glob/max_depth docs;
attach recipe actions on --json; expand goldens and stdin e2e tests.

* docs: clarify affected-tests agent path is query_recipe

Moat A via recipe + query_recipe; codemap affected is CI-first.
No dedicated MCP tool planned unless eval shows friction.

* fix(affected): index minimal fixture in e2e beforeAll

CI has no committed index.db under fixtures/minimal; run --full once
with a 120s hook timeout so affected e2e matches cmd-query-recency.

* fix(affected): use pipe stdin in e2e spawn helper

Blob ReadableStream stdin was flaky on Linux CI — path reads returned []
while positional args worked. Write+end on an explicit pipe instead.
diff --git a/.changeset/affected-tests-recipe.md b/.changeset/affected-tests-recipe.md
@@ -0,0 +1,5 @@
+---
+"@stainless-code/codemap": patch
+---
+
+Add `affected-tests` recipe and `codemap affected` CLI for reverse-dependency test selection from changed files.
diff --git a/README.md b/README.md
@@ -198,6 +198,13 @@ codemap impact runWatchLoop --json --summary | jq '.summary.nodes'  # CI-gate fa
 # (default 3, --depth 0 = unbounded), limit-capped (default 500). Result envelope:
 # {target, matches: [{depth, edge, kind, name?, file_path}], summary: {nodes, terminated_by}}.
 
+# Affected tests — reverse dependency walk from changed sources → test files to run
+codemap affected --json                                         # working-tree changes vs HEAD (git status + diff)
+git diff --name-only origin/main | codemap affected --stdin --json
+codemap affected src/lib/cache.ts --json                        # explicit changed paths
+codemap affected --changed-since origin/main --json               # committed delta + working tree vs ref
+# Moat-A twin: `affected-tests` recipe. Output: [{test_path, impact_depth}] — CI composes the runner command.
+
 # Apply — substrate-shaped fix executor (recipe SQL describes hunks; codemap validates + writes)
 codemap apply rename-preview --params old=usePermissions,new=useAccess,kind=function --dry-run
 codemap apply rename-preview --params old=usePermissions,new=useAccess,kind=function --yes   # TTY prompts without --yes
diff --git a/docs/plans/affected-tests-recipe.md b/docs/plans/affected-tests-recipe.md
@@ -10,12 +10,12 @@
 
 ## Pre-locked decisions
 
-| #   | Decision                                                                                                                              | Source                                     |
-| --- | ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
-| L.1 | **Moat-A clean** — `affected-tests` recipe + optional CLI alias `codemap affected` (outcome alias cap: 5 total — audit alias budget). | [Moat A](../roadmap.md#moats-load-bearing) |
-| L.2 | Algorithm: reverse BFS on `dependencies` from changed files → filter test paths via `test_suites.file_path` and configurable globs.   | Uses existing substrate                    |
-| L.3 | **Stdin support** — accept changed paths from `git diff --name-only` (same ergonomics as CI scripts).                                 | CLI ergonomics                             |
-| L.4 | Not a verdict — output is file paths only; CI composes exit policy.                                                                   | Moat A                                     |
+| #   | Decision                                                                                                                                                                                                                             | Source                                     |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------ |
+| L.1 | **Moat-A clean** — `affected-tests` recipe satisfies the agent surface; **`query_recipe`** is the MCP/HTTP path. Optional dedicated CLI verb **`codemap affected`** for CI (`stdin` / git path discovery) — not a 6th outcome alias. | [Moat A](../roadmap.md#moats-load-bearing) |
+| L.2 | Algorithm: reverse BFS on `dependencies` from changed files → filter test paths via `test_suites.file_path` and configurable globs.                                                                                                  | Uses existing substrate                    |
+| L.3 | **Stdin support** — accept changed paths from `git diff --name-only` (same ergonomics as CI scripts).                                                                                                                                | CLI ergonomics                             |
+| L.4 | Not a verdict — output is file paths only; CI composes exit policy.                                                                                                                                                                  | Moat A                                     |
 
 ---
 
@@ -37,31 +37,37 @@
 
 ---
 
-## CLI alias
+## CLI verb (CI)
 
 ```bash
-codemap affected --json                    # git diff vs HEAD
+codemap affected --json                    # working tree vs HEAD
 git diff --name-only origin/main | codemap affected --stdin --json
 ```
 
-Implement in `src/cli/aliases.ts` if alias budget allows; else recipe-only with documented shell wrapper.
+Dedicated `cmd-affected.ts` (not an outcome alias — 5-alias cap unchanged). Shipped as **`codemap affected`**, not `aliases.ts`.
+
+## Agent surface (Moat A)
+
+No dedicated MCP tool required — agents call **`query_recipe`** with `recipe: "affected-tests"` and `params.changed_files` (ASCII RS between paths when multiple). The recipe is the Moat-A substrate; the CLI verb is CI ergonomics only.
 
 ---
 
 ## Implementation steps
 
 1. Recipe SQL + frontmatter + golden query fixture
-2. CLI stdin handling in `cmd-query` or dedicated thin `cmd-affected.ts`
+2. CLI stdin handling in dedicated `cmd-affected.ts`
 3. Document test-file conventions in recipe `.md`
 4. Optional GitHub Action input `mode: affected` in [github-marketplace-action](./github-marketplace-action.md) (follow-up)
 
+**Out of scope:** dedicated MCP/HTTP `affected` tool (same outcome reachable via `query_recipe`; revisit only if agent eval shows friction).
+
 ---
 
 ## Acceptance
 
-- [ ] Recipe returns test file paths for a known fixture delta
-- [ ] Stdin mode works in shell pipeline
-- [ ] Documented in README + skill
+- [x] Recipe returns test file paths for a known fixture delta
+- [x] Stdin mode works in shell pipeline
+- [x] Documented in README + skill
 
 ---
 
diff --git a/docs/plans/agent-surface-delivery.md b/docs/plans/agent-surface-delivery.md
@@ -10,11 +10,11 @@
 
 ## Quick resume
 
-| Next action          | Detail                                                                              |
-| -------------------- | ----------------------------------------------------------------------------------- |
-| **Review / merge**   | PR 4 — trace recipes ([#131](https://github.com/stainless-code/codemap/pull/131))   |
-| **Start next**       | **PR 5** — `affected-tests-recipe` or **PR 6** — MCP trace tools (after PR 4 lands) |
-| **Do not start yet** | PR 6 until PR 4 lands; PR 9 (eval harness) until PR 8                               |
+| Next action          | Detail                                                                             |
+| -------------------- | ---------------------------------------------------------------------------------- |
+| **Review / merge**   | PR 5 — affected tests ([#132](https://github.com/stainless-code/codemap/pull/132)) |
+| **Start next**       | **PR 6** — MCP trace tools (`trace` / `explore` / `node`)                          |
+| **Do not start yet** | PR 9 (eval harness) until PR 8                                                     |
 
 Update the table below when a PR merges or a new branch opens.
 
@@ -38,8 +38,8 @@ Max **3 parallel tracks** at once.
 | PR    | Plans                                                                                                                         | Status  | Blocked by                                                                                                             | Parallel with                     |
 | ----- | ----------------------------------------------------------------------------------------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------- | --------------------------------- |
 | **3** | [`index-lock-and-error-log`](./index-lock-and-error-log.md) → [`parse-worker-hardening`](./parse-worker-hardening.md) (stack) | merged  | [#129](https://github.com/stainless-code/codemap/pull/129), [#130](https://github.com/stainless-code/codemap/pull/130) | 4, 5                              |
-| **4** | Recipe half of [`mcp-trace-explore-tools`](./mcp-trace-explore-tools.md) (`call-path`, `symbol-neighborhood` SQL + tests)     | open    | [#131](https://github.com/stainless-code/codemap/pull/131)                                                             | 3, 5                              |
-| **5** | [`affected-tests-recipe`](./affected-tests-recipe.md)                                                                         | planned | —                                                                                                                      | 3, 4                              |
+| **4** | Recipe half of [`mcp-trace-explore-tools`](./mcp-trace-explore-tools.md) (`call-path`, `symbol-neighborhood` SQL + tests)     | merged  | [#131](https://github.com/stainless-code/codemap/pull/131)                                                             | 3, 5                              |
+| **5** | [`affected-tests-recipe`](./affected-tests-recipe.md)                                                                         | open    | [#132](https://github.com/stainless-code/codemap/pull/132)                                                             | 3, 4                              |
 | **6** | MCP half of trace (`trace` / `explore` / `node` tools) + update instructions                                                  | planned | PR 1, PR 4                                                                                                             | —                                 |
 | **7** | [`field-qualified-search`](./field-qualified-search.md)                                                                       | planned | PR 1                                                                                                                   | 4, 5 if `mcp-server.ts` untouched |
 | **8** | [`agents-init-mcp-wiring`](./agents-init-mcp-wiring.md)                                                                       | planned | PR 1                                                                                                                   | 3–5                               |
diff --git a/fixtures/golden/minimal/affected-tests-complexity.json b/fixtures/golden/minimal/affected-tests-complexity.json
@@ -0,0 +1,6 @@
+[
+  {
+    "test_path": "src/__tests__/smoke.test.ts",
+    "impact_depth": 1
+  }
+]
diff --git a/fixtures/golden/minimal/affected-tests-direct.json b/fixtures/golden/minimal/affected-tests-direct.json
@@ -0,0 +1,6 @@
+[
+  {
+    "test_path": "src/__tests__/smoke.test.ts",
+    "impact_depth": 0
+  }
+]
diff --git a/fixtures/golden/minimal/affected-tests-max-depth-0.json b/fixtures/golden/minimal/affected-tests-max-depth-0.json
@@ -0,0 +1 @@
+[]
diff --git a/fixtures/golden/minimal/affected-tests-multi-file.json b/fixtures/golden/minimal/affected-tests-multi-file.json
@@ -0,0 +1,6 @@
+[
+  {
+    "test_path": "src/__tests__/smoke.test.ts",
+    "impact_depth": 0
+  }
+]
diff --git a/fixtures/golden/minimal/affected-tests-no-tests.json b/fixtures/golden/minimal/affected-tests-no-tests.json
@@ -0,0 +1 @@
+[]
diff --git a/fixtures/golden/minimal/affected-tests-test-glob.json b/fixtures/golden/minimal/affected-tests-test-glob.json
@@ -0,0 +1,6 @@
+[
+  {
+    "test_path": "src/__tests__/smoke.test.ts",
+    "impact_depth": 1
+  }
+]
diff --git a/fixtures/golden/scenarios.json b/fixtures/golden/scenarios.json
@@ -182,6 +182,50 @@
       "recipe": "symbol-neighborhood",
       "params": { "name": "nonexistentSymbol", "depth": 1 }
     },
+    {
+      "id": "affected-tests-complexity",
+      "prompt": "Test file importing changed complexity fixture",
+      "recipe": "affected-tests",
+      "params": { "changed_files": "src/lib/complexity-fixture.ts" }
+    },
+    {
+      "id": "affected-tests-no-tests",
+      "prompt": "Changed file with no test importer returns empty",
+      "recipe": "affected-tests",
+      "params": { "changed_files": "src/api/client.ts" }
+    },
+    {
+      "id": "affected-tests-direct",
+      "prompt": "Changed test file is included at depth 0",
+      "recipe": "affected-tests",
+      "params": { "changed_files": "src/__tests__/smoke.test.ts" }
+    },
+    {
+      "id": "affected-tests-max-depth-0",
+      "prompt": "max_depth=0 excludes transitive test importers",
+      "recipe": "affected-tests",
+      "params": {
+        "changed_files": "src/lib/complexity-fixture.ts",
+        "max_depth": 0
+      }
+    },
+    {
+      "id": "affected-tests-test-glob",
+      "prompt": "test_glob replaces default suffix globs when no match",
+      "recipe": "affected-tests",
+      "params": {
+        "changed_files": "src/lib/complexity-fixture.ts",
+        "test_glob": "*.spec.ts"
+      }
+    },
+    {
+      "id": "affected-tests-multi-file",
+      "prompt": "Multi-file RS input uses MIN impact_depth across seeds",
+      "recipe": "affected-tests",
+      "params": {
+        "changed_files": "src/lib/complexity-fixture.ts\u001esrc/__tests__/smoke.test.ts"
+      }
+    },
     {
       "id": "find-async-functions",
       "prompt": "Parametrised recipe: list async function-shaped symbols with return_type",
diff --git a/src/cli/bootstrap.ts b/src/cli/bootstrap.ts
@@ -56,6 +56,9 @@ Targeted reads (precise lookup by symbol name):
 Impact analysis (graph walk for refactor blast-radius):
   codemap impact <target> [--direction up|down|both] [--depth N] [--via <b>] [--limit N] [--summary] [--json]
 
+Affected tests (reverse dep walk → test files to run):
+  codemap affected [--stdin] [--changed-since <ref>] [--json] [<path>...]
+
 Apply (substrate-shaped fix executor; consumes the diff-json row contract):
   codemap apply <recipe-id> [--params k=v[,k=v]] [--dry-run] [--yes] [--json]
 
@@ -127,6 +130,7 @@ export function validateIndexModeArgs(rest: string[]): void {
   if (rest[0] === "show") return;
   if (rest[0] === "snippet") return;
   if (rest[0] === "impact") return;
+  if (rest[0] === "affected") return;
   if (rest[0] === "apply") return;
   if (rest[0] === "ingest-coverage") return;
   if (rest[0] === "pr-comment") return;
diff --git a/src/cli/cmd-affected.test.ts b/src/cli/cmd-affected.test.ts
diff --git a/src/cli/cmd-affected.ts b/src/cli/cmd-affected.ts
diff --git a/src/cli/main.ts b/src/cli/main.ts
diff --git a/templates/agent-content/skill/10-recipes-context.md b/templates/agent-content/skill/10-recipes-context.md
diff --git a/templates/recipes/affected-tests.md b/templates/recipes/affected-tests.md
diff --git a/templates/recipes/affected-tests.sql b/templates/recipes/affected-tests.sql

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +"@stainless-code/codemap": patch
 +---
++
 +Add `affected-tests` recipe and `codemap affected` CLI for reverse-dependency test selection from changed files.