fix(audit): address PR #33 CodeRabbit feedback (1 Major + 3 Minor)

All 4 verified correct against the actual code; all applied.

Major:

- audit-engine.ts: validate baseline rows_json is an array before
  diffing. JSON.parse("null") / "{}" / "true" all parse successfully
  but produce non-array values that crash computeDelta on .length /
  .map. New explicit check returns a structured AuditError naming
  the actual type so the user knows what to re-save. Tests cover
  both the null and object cases.

Minor:

- README.md: add a fourth example line showing the prefix + per-delta
  override composition (`--baseline base --files-baseline hotfix-files`).
  The behavior is implemented + tested in resolveAuditBaselines but
  the README only showed the standalone forms.
- cmd-audit.ts: harden consumeFlagValue's two-token path to reject
  empty-string values (`--flag ""`) and whitespace-only values
  (`--flag "   "`). The `--flag=` path was already strict; the
  positional path silently accepted these and the failure surfaced
  later as a less-clear baseline-not-found error. Two new parser
  tests cover both cases.
- SKILL.md (mirrored across .agents/ and templates/agents/ per Rule
  10): add the "no slot resolves → exit 1" failure mode to the
  Audit subsection. The "silently absent" wording read like
  --baseline <prefix> could produce an empty envelope; clarified
  that audit errors instead of doing nothing.

Author: SutuSebastian

.agents/skills/codemap/SKILL.md

@@ -48,7 +48,7 @@ Replace placeholders (`'...'`) with your module path, file glob, or symbol name.
 
 **Audit (`bun src/index.ts audit`)** — separate top-level command for structural-drift verdicts. Composes B.6 baselines into a per-delta `{head, deltas}` envelope; v1 ships `files` / `dependencies` / `deprecated`. Two snapshot-source shapes:
 
-- **`--baseline <prefix>`** — auto-resolves `<prefix>-files` / `<prefix>-dependencies` / `<prefix>-deprecated` in `query_baselines`. Slots that don't exist are silently absent (the convention-following user just saves what they need).
+- **`--baseline <prefix>`** — auto-resolves `<prefix>-files` / `<prefix>-dependencies` / `<prefix>-deprecated` in `query_baselines`. Slots that don't exist are silently absent (the convention-following user just saves what they need). **If no slot resolves at all** (every auto-resolved name is missing AND no `--<delta>-baseline` flag is passed), audit exits 1 — never produces an empty envelope.
 - **`--<delta>-baseline <name>`** — explicit per-delta override (e.g. `--files-baseline X --dependencies-baseline Y`). Names must exist or audit exits 1. Composes with `--baseline` (per-delta flag overrides one slot).
 
 Each emitted delta carries its own `base` metadata so mixed-baseline audits are first-class. `--summary` collapses each delta to `{added: N, removed: N}`. `--no-index` skips the auto-incremental-index prelude (default is to re-index first so `head` reflects current source). v1 ships no `verdict` / threshold config — `codemap audit --json | jq -e '.deltas.dependencies.added | length <= 50'` is the CI exit-code idiom until v1.x ships native thresholds. Each delta pins a canonical SQL projection and validates baseline column-set membership before diffing — schema-bump-resilient (extras dropped, missing columns surface a clean re-save command).

README.md

@@ -101,6 +101,7 @@ codemap query --save-baseline=base-deprecated   -r deprecated-symbols
 codemap audit --baseline base                                   # auto-resolves base-{files,dependencies,deprecated}
 codemap audit --json --summary --baseline base                  # counts-only — useful for CI dashboards
 codemap audit --files-baseline base-files                       # explicit per-delta — runs only the slots provided
+codemap audit --baseline base --files-baseline hotfix-files     # mixed — auto-resolve deps + deprecated; override files
 codemap audit --baseline base --no-index                        # skip the auto-incremental-index prelude (frozen-DB CI)
 # 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.

src/application/audit-engine.test.ts

@@ -142,6 +142,53 @@ describe("runAudit (engine)", () => {
     }
   });
 
+  it("rejects a baseline whose rows_json parses to non-array (null)", () => {
+    const db = freshDb();
+    try {
+      upsertQueryBaseline(db, {
+        name: "null-rows",
+        recipe_id: null,
+        sql: "SELECT 1",
+        rows_json: "null",
+        row_count: 0,
+        git_ref: null,
+        created_at: 1,
+      });
+      const result = runAudit({ db, baselines: { files: "null-rows" } });
+      expect(result).toHaveProperty("error");
+      if ("error" in result) {
+        expect(result.error).toContain('"null-rows"');
+        expect(result.error).toContain("invalid rows_json");
+        expect(result.error).toContain("null");
+      }
+    } finally {
+      db.close();
+    }
+  });
+
+  it("rejects a baseline whose rows_json parses to non-array (object)", () => {
+    const db = freshDb();
+    try {
+      upsertQueryBaseline(db, {
+        name: "object-rows",
+        recipe_id: null,
+        sql: "SELECT 1",
+        rows_json: "{}",
+        row_count: 0,
+        git_ref: null,
+        created_at: 1,
+      });
+      const result = runAudit({ db, baselines: { files: "object-rows" } });
+      expect(result).toHaveProperty("error");
+      if ("error" in result) {
+        expect(result.error).toContain("invalid rows_json");
+        expect(result.error).toContain("object");
+      }
+    } finally {
+      db.close();
+    }
+  });
+
   it("propagates a column-mismatch error from a delta", () => {
     const db = freshDb();
     try {

src/application/audit-engine.ts

@@ -160,7 +160,13 @@ export function runAudit(opts: {
 
     let baselineRows: unknown[];
     try {
-      baselineRows = JSON.parse(baseline.rows_json) as unknown[];
+      const parsed = JSON.parse(baseline.rows_json) as unknown;
+      if (!Array.isArray(parsed)) {
+        return {
+          error: `codemap audit: baseline "${baseline.name}" (delta "${spec.key}") has invalid rows_json (expected JSON array, got ${parsed === null ? "null" : typeof parsed}) — drop and re-save.`,
+        };
+      }
+      baselineRows = parsed;
     } catch {
       return {
         error: `codemap audit: baseline "${baseline.name}" (delta "${spec.key}") has corrupt rows_json — drop and re-save.`,

src/cli/cmd-audit.test.ts

@@ -132,6 +132,18 @@ describe("parseAuditRest", () => {
     if (r.kind === "error") expect(r.message).toContain("--files-baseline");
   });
 
+  it("errors when --baseline gets an empty-string value (two-token form)", () => {
+    const r = parseAuditRest(["audit", "--baseline", ""]);
+    expect(r.kind).toBe("error");
+    if (r.kind === "error") expect(r.message).toContain("--baseline");
+  });
+
+  it("errors when --files-baseline gets a whitespace-only value", () => {
+    const r = parseAuditRest(["audit", "--files-baseline", "   "]);
+    expect(r.kind).toBe("error");
+    if (r.kind === "error") expect(r.message).toContain("--files-baseline");
+  });
+
   it("errors on unknown options", () => {
     const r = parseAuditRest(["audit", "--unknown", "x", "--baseline", "n"]);
     expect(r.kind).toBe("error");

src/cli/cmd-audit.ts

@@ -128,7 +128,16 @@ function consumeFlagValue(
     return { kind: "value", value: v, next: i + 1 };
   }
   const next = rest[i + 1];
-  if (next === undefined || next.startsWith("-")) {
+  // `next === ""` catches the two-token empty-string case (`--flag ""`); the
+  // `--flag=` case is already caught above. Trim-zero check covers whitespace-
+  // only values (`--flag " "`) — those would silently sneak through to a
+  // baseline lookup that fails further downstream with a less clear error.
+  if (
+    next === undefined ||
+    next === "" ||
+    next.trim().length === 0 ||
+    next.startsWith("-")
+  ) {
     return {
       kind: "error",
       message: `codemap audit: "${flagName}" requires a value.`,

templates/agents/skills/codemap/SKILL.md

@@ -48,7 +48,7 @@ Replace placeholders (`'...'`) with your module path, file glob, or symbol name.
 
 **Audit (`codemap audit`)** — separate top-level command for structural-drift verdicts. Composes B.6 baselines into a per-delta `{head, deltas}` envelope; v1 ships `files` / `dependencies` / `deprecated`. Two snapshot-source shapes:
 
-- **`--baseline <prefix>`** — auto-resolves `<prefix>-files` / `<prefix>-dependencies` / `<prefix>-deprecated` in `query_baselines`. Slots that don't exist are silently absent (the convention-following user just saves what they need).
+- **`--baseline <prefix>`** — auto-resolves `<prefix>-files` / `<prefix>-dependencies` / `<prefix>-deprecated` in `query_baselines`. Slots that don't exist are silently absent (the convention-following user just saves what they need). **If no slot resolves at all** (every auto-resolved name is missing AND no `--<delta>-baseline` flag is passed), audit exits 1 — never produces an empty envelope.
 - **`--<delta>-baseline <name>`** — explicit per-delta override (e.g. `--files-baseline X --dependencies-baseline Y`). Names must exist or audit exits 1. Composes with `--baseline` (per-delta flag overrides one slot).
 
 Each emitted delta carries its own `base` metadata so mixed-baseline audits are first-class. `--summary` collapses each delta to `{added: N, removed: N}`. `--no-index` skips the auto-incremental-index prelude (default is to re-index first so `head` reflects current source). v1 ships no `verdict` / threshold config — `codemap audit --json | jq -e '.deltas.dependencies.added | length <= 50'` is the CI exit-code idiom until v1.x ships native thresholds. Each delta pins a canonical SQL projection and validates baseline column-set membership before diffing — schema-bump-resilient (extras dropped, missing columns surface a clean re-save command).