fix(cli): address PR #23 review — recent_markers misnomer, validate TOCTOU, --compact, --for guard, README

Adopts the 7 valid items from CodeRabbit review.

A1 — `recent_markers` was alphabetical-first-20, not recency-ordered (the
markers table has no timestamp column). Rename to `sample_markers` with a
JSDoc note pointing at the proper time-ordered query (join `files.last_modified`).

A2 — `cmd-validate.ts` had a TOCTOU between existsSync and readFileSync.
Replace with a single guarded read; also drops one syscall in the common
path (open instead of stat + open).

N2 — Rename `performance` local in cmd-index.ts to `reportPerformance`
to avoid shadowing the global `performance` API.

N4 — Route the `files-hashes` golden through the bundled recipe (was
inline SQL); now exercises the recipe SQL itself and prevents drift.
Snapshot refreshed.

N5 — Add `validate` and `context` to the README "Daily commands" stripe;
they were the headline additions in this PR but weren't on the showcase.

N7 — `--for ""` was accepted as a valid intent and silently classified
as "other". Reject empty-string values with the same error as missing.

N8 — `--compact` now actually compacts: `JSON.stringify` is called
without indent in compact mode (was unconditional 2-space pretty-print).

Tests: +1 case for `--for ""` rejection. 19/19 goldens green, 24/24
cmd-context + cmd-validate tests pass.

Author: SutuSebastian

README.md

@@ -46,9 +46,11 @@ bun add @stainless-code/codemap
 
 ```bash
 codemap                                                      # incremental index (run once per session)
-codemap query --json --recipe fan-out                        # bundled SQL via recipe id
+codemap query --json --recipe fan-out                        # bundled SQL via recipe id (alias: -r)
 codemap query --json "SELECT name, file_path FROM symbols WHERE name = 'foo'"  # ad-hoc SQL
 codemap --files src/a.ts src/b.tsx                           # targeted re-index after edits
+codemap validate --json                                      # detect stale / missing / unindexed files
+codemap context --compact --for "refactor auth"              # JSON envelope + intent-matched recipes
 codemap agents init                                          # scaffold .agents/ rules + skills
 ```
 

fixtures/golden/minimal/files-hashes.json

@@ -1,56 +1,67 @@
 [
   {
     "path": "README.md",
+    "content_hash": "428564b4ac5e4864ca2292a4195b726be3d4c7c5cac3d19dd01f17714d026c66",
     "language": "md",
     "line_count": 11
   },
   {
     "path": "package.json",
+    "content_hash": "a8e79efc943697cee4d4435360de9150bd7261376abe9e2c34c0c7238177c7de",
     "language": "json",
     "line_count": 11
   },
   {
     "path": "src/api/client.ts",
+    "content_hash": "4d0ec5edad3f758e7f84898dd602dbacaf3ea65ad87614ae9f179bd2383bbf56",
     "language": "ts",
     "line_count": 9
   },
   {
     "path": "src/components/shop/ShopButton.tsx",
+    "content_hash": "481b9ff2e493fd69b36b67d2738e298999ce55040bce64c4c38a2e736c0573fd",
     "language": "tsx",
     "line_count": 8
   },
   {
     "path": "src/consumer.ts",
+    "content_hash": "420ad98f7fedaf07ec07d1a64ef6ade100be4a7973883718a3942c68b1350903",
     "language": "ts",
     "line_count": 11
   },
   {
     "path": "src/notes.md",
+    "content_hash": "1a2bff433137690132077b15032ba3f07f5ed1b576b894816890342155ab640a",
     "language": "md",
     "line_count": 4
   },
   {
     "path": "src/styles/button.module.css",
+    "content_hash": "1c385277a506b2cb1c70c2d2128bbd280bf080796c83ab37f6f3434655c17348",
     "language": "css",
     "line_count": 16
   },
   {
     "path": "src/theme.css",
+    "content_hash": "19ff92a0acce67e5a385e8f1b1607f787462626669d3b941ee0fc91030672b67",
     "language": "css",
     "line_count": 9
   },
   {
     "path": "src/usePermissions.ts",
+    "content_hash": "8758cc9ba2756e08198f11fca9ff58a0612fc9219173d06784e0b7e2f2ca1e1f",
     "language": "ts",
     "line_count": 4
   },
   {
     "path": "src/utils/date.ts",
+    "content_hash": "89e6301076caeb9f4c13cee8ea06f7f25a5e1aa239daf921f7ff984236ffa177",
     "language": "ts",
     "line_count": 15
   },
   {
     "path": "tsconfig.json",
+    "content_hash": "6b8ead4b09e6885483c805937a35fa0df3cbc47de346abb2d0ed8b73dc7f9e92",
     "language": "json",
     "line_count": 17
   }

fixtures/golden/scenarios.json

@@ -86,8 +86,8 @@
   },
   {
     "id": "files-hashes",
-    "prompt": "All indexed file paths with language and line count (powers `codemap validate`)",
-    "sql": "SELECT path, language, line_count FROM files ORDER BY path"
+    "prompt": "All indexed files with content_hash (recipe powers `codemap validate`)",
+    "recipe": "files-hashes"
   },
   {
     "id": "barrel-files",

src/cli/cmd-context.test.ts

@@ -48,6 +48,11 @@ describe("parseContextRest", () => {
     expect(r.kind).toBe("error");
   });
 
+  it("errors when --for value is an empty string", () => {
+    const r = parseContextRest(["context", "--for", ""]);
+    expect(r.kind).toBe("error");
+  });
+
   it("rejects unknown options", () => {
     expect(parseContextRest(["context", "--nope"]).kind).toBe("error");
   });

src/cli/cmd-context.ts

@@ -22,7 +22,13 @@ export interface ContextEnvelope {
     languages: { language: string; files: number }[];
   };
   hubs?: { to_path: string; fan_in: number }[];
-  recent_markers?: {
+  /**
+   * A flavor sample of TODO/FIXME/HACK/NOTE markers — the alphabetically-first
+   * 20 across the repo, ordered by `(file_path, line_number)`. Not a recency
+   * signal; for time-ordered output query `markers` directly, joining
+   * `files.last_modified`.
+   */
+  sample_markers?: {
     file_path: string;
     line_number: number;
     kind: string;
@@ -51,11 +57,12 @@ export function printContextCmdHelp(): void {
   console.log(`Usage: codemap context [--compact] [--for "<intent>"]
 
 Emit a JSON envelope describing the current index — project metadata, top
-hubs (fan-in), recent markers, and the bundled recipe catalog. Designed for
-agents and editors that want a single-command "give me everything cheap".
+hubs (fan-in), a sample of markers, and the bundled recipe catalog. Designed
+for agents and editors that want a single-command "give me everything cheap".
 
 Flags:
-  --compact          Drop hubs and recent_markers (smaller payload).
+  --compact          Drop hubs and sample_markers; emit JSON without
+                     pretty-print (smaller payload).
   --for "<intent>"   Pre-classify a free-text intent (refactor, debug, test,
                      feature, explore) and recommend recipes that match.
   --help, -h         Show this help.
@@ -90,7 +97,7 @@ export function parseContextRest(
     }
     if (a === "--for") {
       const v = rest[i + 1];
-      if (v === undefined || v.startsWith("--")) {
+      if (v === undefined || v === "" || v.startsWith("--")) {
         return {
           kind: "error",
           message: 'codemap: "--for" requires an intent string in quotes.',
@@ -210,11 +217,11 @@ export function buildContextEnvelope(
     envelope.hubs = db
       .query(QUERY_RECIPES["fan-in"]!.sql)
       .all() as ContextEnvelope["hubs"];
-    envelope.recent_markers = db
+    envelope.sample_markers = db
       .query(
         "SELECT file_path, line_number, kind, content FROM markers ORDER BY file_path ASC, line_number ASC LIMIT 20",
       )
-      .all() as ContextEnvelope["recent_markers"];
+      .all() as ContextEnvelope["sample_markers"];
   }
 
   if (opts.intent !== null) {
@@ -248,7 +255,11 @@ export async function runContextCmd(opts: ContextOpts): Promise<void> {
     } finally {
       closeDb(db, { readonly: true });
     }
-    console.log(JSON.stringify(envelope, null, 2));
+    console.log(
+      opts.compact
+        ? JSON.stringify(envelope)
+        : JSON.stringify(envelope, null, 2),
+    );
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     console.log(JSON.stringify({ error: msg }));

src/cli/cmd-index.ts

@@ -34,10 +34,10 @@ export async function runIndexCmd(opts: {
       }
     } else {
       const fullRebuild = args.includes("--full");
-      const performance = args.includes("--performance");
+      const reportPerformance = args.includes("--performance");
       await runCodemapIndex(db, {
         mode: fullRebuild ? "full" : "incremental",
-        performance,
+        performance: reportPerformance,
       });
     }
   } finally {

src/cli/cmd-validate.ts

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync } from "node:fs";
+import { readFileSync } from "node:fs";
 import { isAbsolute, relative, resolve } from "node:path";
 
 import { loadUserConfig, resolveCodemapConfig } from "../config";
@@ -116,18 +116,24 @@ export function computeValidateRows(
 
     const indexedHash = indexByPath.get(rel);
     const abs = resolve(projectRoot, rel);
-    const onDisk = existsSync(abs);
+    let source: string | undefined;
+    try {
+      source = readFileSync(abs, "utf8");
+    } catch {
+      source = undefined;
+    }
 
     if (indexedHash === undefined) {
-      if (onDisk) rows.push({ path: rel, status: "unindexed" });
+      if (source !== undefined) rows.push({ path: rel, status: "unindexed" });
       continue;
     }
-    if (!onDisk) {
+    if (source === undefined) {
       rows.push({ path: rel, status: "missing" });
       continue;
     }
-    const diskHash = hashContent(readFileSync(abs, "utf8"));
-    if (diskHash !== indexedHash) rows.push({ path: rel, status: "stale" });
+    if (hashContent(source) !== indexedHash) {
+      rows.push({ path: rel, status: "stale" });
+    }
   }
   rows.sort((a, b) => a.path.localeCompare(b.path));
   return rows;