feat(query): Tier A flags (--summary, --changed-since, --group-by) + per-row recipe actions (#26)

## Summary

Implements the four Tier A items from [docs/research/fallow.md § Tier A](https://github.com/stainless-code/codemap/blob/main/docs/research/fallow.md). Pure CLI surface — no schema bump, no breaking changes to the `cm.query()` programmatic API, no changes to `templates/agents/`.

Four commits, reviewable independently:

1. **A.4 — `--summary`** — counts only, skips row emission
2. **A.2 — `--changed-since <ref>`** — PR-scoped row filter via `git diff <ref>...HEAD ∪ git status`
3. **A.1 — per-row `actions` on recipes** — agent-facing follow-up hints in `--json` output
4. **A.3 — `--group-by owner|directory|package`** — partition rows by CODEOWNERS / first directory segment / workspace package

## What's new

### Flags

| Flag | What it does | Pairs with |
| --- | --- | --- |
| `--summary` | Print only the row count (`{"count": N}` with `--json`, `count: N` without). With `--group-by`, output collapses to `{group_by, groups: [{key, count}]}`. | `--recipe`, ad-hoc SQL, `--changed-since`, `--group-by` |
| `--changed-since <ref>` | Post-filter rows by `path` / `file_path` / `from_path` / `to_path` / `resolved_path` against `git diff --name-only <ref>...HEAD ∪ git status --porcelain`. Bad refs surface a clean `{"error":"…"}` and exit 1. Rows with no recognised path column pass through. | All other flags |
| `--group-by <mode>` | `owner` (CODEOWNERS first owner, last-match-wins), `directory` (first path segment), `package` (workspace dir from `package.json` `workspaces` or `pnpm-workspace.yaml` `packages:`; out-of-workspace → `<root>`). Emits `{group_by, groups: [{key, count, rows}]}` with `--json`. | All other flags |

### Per-row recipe `actions`

Recipes can now declare an `actions: RecipeAction[]` template that gets appended to every row in `--json` output. Recipe-only and CLI-only — programmatic `cm.query(sql)` and ad-hoc CLI SQL never carry actions.

Initial templates:

- `fan-out` → `review-coupling`
- `fan-in` → `review-stability`
- `files-largest` → `split-file`
- `deprecated-symbols` → `flag-caller`
- `visibility-tags` → `flag-non-public`
- `barrel-files` → `split-barrel`

Aggregation recipes (`index-summary`, `markers-by-kind`) intentionally omit actions — counts-by-kind have no per-row target.

## What's not in this PR

- `actions` on the programmatic `cm.query(sql)` surface (would couple application layer to `cli/query-recipes`; intentional boundary).
- B.5 `codemap audit --base <ref>` — bigger design surface; warrants `docs/plans/<name>.md` first per the research note.
- Suppression comments / per-rule severity / `fallow fix`-style mutator — explicit non-goals per `docs/research/fallow.md § Defer / skip`.

## Test plan

- [x] `bun run check` passes locally (build, format:check, lint:ci, test, typecheck, test:golden — all 19 golden scenarios green; the test count grew with the new helpers).
- [x] Smoke tests against this clone:
  - `query --json --summary -r deprecated-symbols` → `{"count": N}`
  - `query --json --changed-since HEAD~3 "SELECT path FROM files"` → only paths in the diff
  - `query --json --changed-since not-a-real-ref -r fan-out` → clean `{"error":"--changed-since: cannot resolve …"}`
  - `query --json -r fan-out` → each row carries `actions: [{type:"review-coupling", description:"…"}]`
  - `query --json --summary --group-by directory -r fan-in` → `{"group_by":"directory","groups":[{"key":"src","count":15}]}`
  - `query --json --group-by owner -r fan-in` → clean error in repos without CODEOWNERS
- [x] Golden runner uses `cm.query()` (programmatic API) — confirms `actions` enrichment doesn't leak into the public surface.
- [x] Patch changeset added per `.agents/lessons.md` "changesets bump policy (pre-v1)" — additive features default to patch in `0.x`.
- [ ] CI green.

Author: SutuSebastian

.changeset/tier-a-query-flags.md

@@ -0,0 +1,5 @@
+---
+"@stainless-code/codemap": patch
+---
+
+`codemap query` Tier A flags — `--summary`, `--changed-since <ref>`, `--group-by owner|directory|package`, plus per-row `actions` templates on bundled recipes. All output filters; the SQL still executes against the index. Ad-hoc SQL and the `cm.query()` programmatic API stay unchanged.

README.md

@@ -76,6 +76,17 @@ codemap query "SELECT name, file_path FROM symbols LIMIT 10"
 # Bundled SQL (same as skill examples): fan-out rankings
 codemap query --json --recipe fan-out
 codemap query --json --recipe fan-out-sample
+# Counts only (skip the rows) — pairs well with --recipe for dashboards / agent context windows
+codemap query --json --summary -r deprecated-symbols
+# PR-scoped: filter result rows to those touching files changed since <ref>
+codemap query --json --changed-since origin/main -r fan-out
+codemap query --json --summary --changed-since HEAD~5 "SELECT file_path FROM symbols"
+# Group rows by directory, CODEOWNERS owner, or workspace package
+codemap query --json --summary --group-by directory -r fan-in
+codemap query --json --group-by owner -r deprecated-symbols
+codemap query --json --summary --group-by package "SELECT file_path FROM symbols"
+# Recipes that define per-row action templates append "actions" hints (kebab-case verb +
+# description) in --json output; ad-hoc SQL never carries actions. Inspect via --recipes-json.
 # List bundled recipes as JSON, or print one recipe's SQL (no DB required)
 codemap query --recipes-json
 codemap query --print-sql fan-out

docs/architecture.md

@@ -117,7 +117,7 @@ A local SQLite database (`.codemap.db`) indexes the project tree and stores stru
 
 **Commands and flags** (index, query, **`codemap agents init`**, **`--root`**, **`--config`**, environment): [../README.md § CLI](../README.md#cli) — **do not duplicate** flag lists here; this section only adds implementation notes. From this repository: **`bun run dev`** or **`bun src/index.ts`** (same flags).
 
-**Query wiring:** **`src/cli/cmd-query.ts`** (argv, **`printQueryResult`**, `--recipe` / `-r` alias), **`src/cli/query-recipes.ts`** (**`QUERY_RECIPES`** — bundled SQL only source), **`src/cli/main.ts`** (**`--recipes-json`** / **`--print-sql`** exit before config/DB). With **`--json`**, errors use **`{"error":"…"}`** on stdout for SQL failures, DB open, and bootstrap (same shape); **`runQueryCmd`** sets **`process.exitCode`** instead of **`process.exit`**. Friendlier "no `.codemap.db`" — `no such table: <X>` and `no such column: <X>` errors are rewritten in **`enrichQueryError`** to point at `codemap` / `codemap --full`. The **`components-by-hooks`** recipe ranks by hook count with a **comma-based tally** on **`hooks_used`** (no SQLite JSON1). Shipped **`templates/agents/`** documents **`codemap query --json`** as the primary agent example ([README § CLI](../README.md#cli)).
+**Query wiring:** **`src/cli/cmd-query.ts`** (argv, **`printQueryResult`**, `--recipe` / `-r` alias, **`--summary`**, **`--changed-since`**, **`--group-by`**), **`src/cli/query-recipes.ts`** (**`QUERY_RECIPES`** — bundled SQL only source; optional **`actions: RecipeAction[]`** per recipe), **`src/cli/main.ts`** (**`--recipes-json`** / **`--print-sql`** exit before config/DB). With **`--json`**, errors use **`{"error":"…"}`** on stdout for SQL failures, DB open, and bootstrap (same shape); **`runQueryCmd`** sets **`process.exitCode`** instead of **`process.exit`**. Friendlier "no `.codemap.db`" — `no such table: <X>` and `no such column: <X>` errors are rewritten in **`enrichQueryError`** to point at `codemap` / `codemap --full`. **`--summary`** filters output only — the SQL still executes against the index; output collapses to `{"count": N}` (with `--json`) or `count: N`. **`--changed-since <ref>`** post-filters result rows by `path` / `file_path` / `from_path` / `to_path` / `resolved_path` against `git diff --name-only <ref>...HEAD ∪ git status --porcelain` (helper: **`src/git-changed.ts`** — `getFilesChangedSince`, `filterRowsByChangedFiles`, `PATH_COLUMNS`); rows with no recognised path column pass through. **`--group-by <mode>`** (`owner` | `directory` | `package`) routes through **`runGroupedQuery`** in `cmd-query.ts` and emits `{"group_by": "<mode>", "groups": [{key, count, rows}]}` (or `[{key, count}]` with `--summary`); helpers in **`src/group-by.ts`** (`groupRowsBy`, `firstDirectory`, `loadCodeowners`, `discoverWorkspaceRoots`, `makePackageBucketizer`, `codeownersGlobToRegex`). CODEOWNERS lookup is last-match-wins (GitHub semantics); workspace discovery reads `package.json` `workspaces` and `pnpm-workspace.yaml` `packages:`. **Per-row recipe `actions`** are appended only when the user runs **`--recipe <id>`** with **`--json`** AND the recipe defines an `actions` template — programmatic `cm.query(sql)` and ad-hoc CLI SQL never carry actions. The **`components-by-hooks`** recipe ranks by hook count with a **comma-based tally** on **`hooks_used`** (no SQLite JSON1). Shipped **`templates/agents/`** documents **`codemap query --json`** as the primary agent example ([README § CLI](../README.md#cli)).
 
 **Validate wiring:** **`src/cli/cmd-validate.ts`** — **`computeValidateRows`** is a pure function over `(db, projectRoot, paths)` returning `{path, status}` rows where `status ∈ stale | missing | unindexed`. CLI wraps it with read-once-and-print + exits **1** on any drift (git-status semantics). Path normalization: **`toProjectRelative`** converts CLI input to POSIX-style relative keys matching the `files.path` storage format (Windows backslash → forward slash); same convention as `lint-staged.config.js`.
 

src/application/index-engine.ts

@@ -30,6 +30,7 @@ import {
   SCHEMA_VERSION,
 } from "../db";
 import type { CodemapDatabase, FileRow } from "../db";
+import { filterRowsByChangedFiles } from "../git-changed";
 import { globSync } from "../glob-sync";
 import { hashContent } from "../hash";
 import { extractMarkers } from "../markers";
@@ -527,19 +528,52 @@ export async function targetedReindex(
 /**
  * Run read-only SQL and print results to stdout (`console.table`, or JSON when `opts.json`).
  * Does not throw on invalid SQL: prints an error and returns **1** (CLI-style). With **`json`**, errors are printed as **`{"error":"<message>"}`** on stdout.
+ *
+ * When `opts.summary` is true, only the row count is emitted — `{"count": N}` with `--json`,
+ * `count: N` otherwise. The SQL still executes against the index; `--summary` filters output, not work.
+ *
+ * When `opts.changedFiles` is provided, rows are post-filtered to those whose path columns
+ * (`path`, `file_path`, `from_path`, `to_path`, `resolved_path`) match at least one entry.
+ * Rows with no recognised path column pass through (the filter cannot decide; pair with `--summary`
+ * if the count of changed-touching rows is what's wanted).
+ *
+ * When `opts.recipeActions` is provided AND `opts.json` is true, each row gets an `actions`
+ * key set to the same template (recipe-only feature; ad-hoc SQL never carries actions).
+ * Rows that already define their own `actions` column are not overwritten.
  * @returns **0** on success, **1** on SQL/runtime error.
  */
 export function printQueryResult(
   sql: string,
-  opts?: { json?: boolean },
+  opts?: {
+    json?: boolean;
+    summary?: boolean;
+    changedFiles?: Set<string> | undefined;
+    recipeActions?: ReadonlyArray<unknown> | undefined;
+  },
 ): number {
   const json = opts?.json === true;
+  const summary = opts?.summary === true;
+  const changedFiles = opts?.changedFiles;
+  const recipeActions = opts?.recipeActions;
   let db: CodemapDatabase | undefined;
   try {
     db = openDb();
-    const rows = db.query(sql).all();
-    if (json) {
-      console.log(JSON.stringify(rows));
+    let rows = db.query(sql).all();
+    if (changedFiles !== undefined) {
+      rows = filterRowsByChangedFiles(rows, changedFiles);
+    }
+    if (summary) {
+      if (json) {
+        console.log(JSON.stringify({ count: rows.length }));
+      } else {
+        console.log(`count: ${rows.length}`);
+      }
+    } else if (json) {
+      const enriched =
+        recipeActions !== undefined && recipeActions.length > 0
+          ? rows.map((row) => attachRecipeActions(row, recipeActions))
+          : rows;
+      console.log(JSON.stringify(enriched));
     } else if (rows.length === 0) {
       console.log("(no results)");
     } else {
@@ -561,6 +595,19 @@ export function printQueryResult(
   }
 }
 
+// Append the recipe's action template to a row without overwriting a pre-existing
+// `actions` column from the SQL itself (recipe authors should never collide, but
+// defensive: keep the SQL output authoritative).
+function attachRecipeActions(
+  row: unknown,
+  actions: ReadonlyArray<unknown>,
+): unknown {
+  if (typeof row !== "object" || row === null) return row;
+  const obj = row as Record<string, unknown>;
+  if ("actions" in obj) return obj;
+  return { ...obj, actions };
+}
+
 /**
  * Rewrites raw SQLite errors that almost always indicate a missing or empty
  * `.codemap.db` into an actionable hint. Other errors are returned unchanged.

src/cli.test.ts

@@ -36,10 +36,13 @@ describe("CLI --help", () => {
     expect(err).toBe("");
   });
 
-  test("query --help exits 0 and documents --json", async () => {
+  test("query --help exits 0 and documents --json + --summary + --group-by", async () => {
     const { exitCode, out, err } = await runCli(["query", "--help"]);
     expect(exitCode).toBe(0);
     expect(out).toContain("--json");
+    expect(out).toContain("--summary");
+    expect(out).toContain("--changed-since");
+    expect(out).toContain("--group-by");
     expect(out).toContain("--recipe");
     expect(out).toContain("fan-out");
     expect(out).toContain("codemap query");