feat(cli): --ci aggregate flag on query + audit (Slice 1b of #73 plan)

Second half of Slice 1. `--ci` is the GitHub-Action-shaped CI flag:
- Aliases `--format sarif`
- Sets process.exitCode = 1 when ≥1 finding/addition surfaced
- Suppresses the no-locatable-rows stderr warning (CI templates would
  surface it as red noise; the row-set itself is the gating signal)

Lands on both `query` and `audit` (the two finding-producing verbs).
Same parser / resolver semantics on both:
- Mutually exclusive with `--json` (different format aliases)
- Mutually exclusive with `--format <other>` (contradicts the alias)
- `--ci --format sarif` redundant but accepted (consumers may set both
  for clarity in CI templates)

Wiring:
- `parseQueryRest` / `parseAuditRest` gain `--ci` token + `ci: boolean`
  in the run-shape union.
- `runQueryCmd` / `runAuditCmd` gain `ci?: boolean` opt; threaded
  through to `printFormattedQuery` (query) and the post-render
  exit-code branch (audit).
- `query`: exit 1 if `rows.length > 0` after SARIF emit.
- `audit`: exit 1 if any delta has `added.length > 0` after SARIF emit.

Tests:
- 4 new `cmd-query` parser tests (--ci alias; --ci+--json reject;
  --ci+--format json reject; --ci+--format sarif accept).
- 4 new `cmd-audit` parser tests (same matrix).
- All existing toEqual tests updated for the `ci: false` field default.

Smoke verified end-to-end:
- `query --ci` with results → SARIF stdout, exit 1.
- `audit --baseline X --ci` against identical baseline → 0 additions,
  exit 0. Diff with adds → exit 1.
- Contradiction tests (`--ci --json`) emit clear error + exit 1.

Author: SutuSebastian

src/cli/cmd-audit.test.ts

@@ -45,6 +45,7 @@ describe("parseAuditRest", () => {
       base: undefined,
       perDelta: {},
       format: "text",
+      ci: false,
       summary: false,
       noIndex: false,
     });
@@ -58,6 +59,7 @@ describe("parseAuditRest", () => {
       base: undefined,
       perDelta: {},
       format: "text",
+      ci: false,
       summary: false,
       noIndex: false,
     });
@@ -79,6 +81,7 @@ describe("parseAuditRest", () => {
       base: undefined,
       perDelta: { files: "X", dependencies: "Y", deprecated: "Z" },
       format: "text",
+      ci: false,
       summary: false,
       noIndex: false,
     });
@@ -98,6 +101,7 @@ describe("parseAuditRest", () => {
       base: undefined,
       perDelta: { dependencies: "experimental-deps" },
       format: "text",
+      ci: false,
       summary: false,
       noIndex: false,
     });
@@ -175,6 +179,46 @@ describe("parseAuditRest", () => {
     expect(r.format).toBe("json");
   });
 
+  it("parses --ci as alias for --format sarif + ci flag", () => {
+    const r = parseAuditRest(["audit", "--ci", "--baseline", "base"]);
+    if (r.kind !== "run") throw new Error("expected run");
+    expect(r.format).toBe("sarif");
+    expect(r.ci).toBe(true);
+  });
+
+  it("rejects --ci + --json (mutually exclusive aliases)", () => {
+    const r = parseAuditRest(["audit", "--ci", "--json", "--baseline", "base"]);
+    expect(r.kind).toBe("error");
+    if (r.kind === "error") expect(r.message).toContain("--ci");
+  });
+
+  it("rejects --ci + --format json (contradicting alias)", () => {
+    const r = parseAuditRest([
+      "audit",
+      "--ci",
+      "--format",
+      "json",
+      "--baseline",
+      "base",
+    ]);
+    expect(r.kind).toBe("error");
+    if (r.kind === "error") expect(r.message).toContain("--ci");
+  });
+
+  it("accepts --ci + --format sarif (redundant but consistent)", () => {
+    const r = parseAuditRest([
+      "audit",
+      "--ci",
+      "--format",
+      "sarif",
+      "--baseline",
+      "base",
+    ]);
+    if (r.kind !== "run") throw new Error("expected run");
+    expect(r.format).toBe("sarif");
+    expect(r.ci).toBe(true);
+  });
+
   it("errors when --baseline has no value", () => {
     const r = parseAuditRest(["audit", "--baseline"]);
     expect(r.kind).toBe("error");
@@ -219,6 +263,7 @@ describe("parseAuditRest", () => {
       base: "origin/main",
       perDelta: {},
       format: "text",
+      ci: false,
       summary: false,
       noIndex: false,
     });

src/cli/cmd-audit.ts

@@ -44,6 +44,8 @@ export function parseAuditRest(rest: string[]):
       base: string | undefined;
       perDelta: Record<string, string>;
       format: AuditOutputFormat;
+      /** `--ci` was set: SARIF + non-zero exit when any delta has additions. */
+      ci: boolean;
       summary: boolean;
       noIndex: boolean;
     } {
@@ -56,6 +58,9 @@ export function parseAuditRest(rest: string[]):
   // `--json` so we can reject `--json --format sarif` as a contradiction.
   let jsonShortcut = false;
   let format: AuditOutputFormat | undefined;
+  // `--ci` is the CI-aggregate flag: aliases `--format sarif` + non-zero
+  // exit-on-issue + suppresses chatty stderr. Plan: docs/plans/github-marketplace-action.md (Slice 1b).
+  let ci = false;
   let summary = false;
   let noIndex = false;
   let baselinePrefix: string | undefined;
@@ -70,6 +75,11 @@ export function parseAuditRest(rest: string[]):
       i++;
       continue;
     }
+    if (a === "--ci") {
+      ci = true;
+      i++;
+      continue;
+    }
     if (a === "--format" || a.startsWith("--format=")) {
       const value = consumeFlagValue(rest, i, "--format");
       if (value.kind === "error") return value;
@@ -153,10 +163,26 @@ export function parseAuditRest(rest: string[]):
     };
   }
 
-  // Reconcile --json shortcut with --format. Both → must agree on `json`.
-  // Neither → default to `text`.
+  // Reconcile --json / --ci / --format. `--ci` aliases `--format sarif`; mutually
+  // exclusive with --json (different format aliases) and with --format <other>
+  // (contradicts the alias). `--ci --format sarif` is redundant but accepted.
   let resolvedFormat: AuditOutputFormat;
-  if (jsonShortcut && format !== undefined) {
+  if (ci) {
+    if (jsonShortcut) {
+      return {
+        kind: "error",
+        message:
+          'codemap audit: "--ci" and "--json" are mutually exclusive (--ci aliases --format sarif; --json aliases --format json).',
+      };
+    }
+    if (format !== undefined && format !== "sarif") {
+      return {
+        kind: "error",
+        message: `codemap audit: "--ci" aliases "--format sarif"; cannot combine with --format ${format}.`,
+      };
+    }
+    resolvedFormat = "sarif";
+  } else if (jsonShortcut && format !== undefined) {
     if (format !== "json") {
       return {
         kind: "error",
@@ -176,6 +202,7 @@ export function parseAuditRest(rest: string[]):
     base,
     perDelta,
     format: resolvedFormat,
+    ci,
     summary,
     noIndex,
   };
@@ -262,6 +289,10 @@ Other flags:
                       one result per added row) for GitHub Code Scanning.
   --json              Shortcut for --format json. Cannot combine with --format
                       <other>. Emits {head, deltas} envelope; on error: {"error":"<message>"}.
+  --ci                CI-aggregate flag. Aliases --format sarif + non-zero exit
+                      when any delta has additions. Mutually exclusive with --json
+                      and --format <other>. Recommended in GitHub Actions / GitLab
+                      CI to fail the runner step on structural drift.
   --summary           Collapse rows to counts. With --format json: deltas.<key>.{added: N, removed: N}.
                       With --format text: a single line "drift: files +1/-0, dependencies +3/-2, ...".
                       No-op with --format sarif (results are per-row).
@@ -312,6 +343,8 @@ export async function runAuditCmd(opts: {
   base: string | undefined;
   perDelta: Record<string, string>;
   format: AuditOutputFormat;
+  /** `--ci`: exit non-zero when any delta has `added.length > 0`. */
+  ci?: boolean;
   summary: boolean;
   noIndex: boolean;
 }): Promise<void> {
@@ -351,6 +384,16 @@ export async function runAuditCmd(opts: {
         return;
       }
       renderAudit(result, { format: opts.format, summary: opts.summary });
+
+      // `--ci`: exit non-zero when any delta has additions. SARIF results
+      // already surfaced via Code Scanning; non-zero exit fails the runner
+      // step so the workflow gates the PR.
+      if (opts.ci === true) {
+        const hasAdditions = Object.values(result.deltas).some(
+          (d) => d.added.length > 0,
+        );
+        if (hasAdditions) process.exitCode = 1;
+      }
     } finally {
       closeDb(db, { readonly: opts.noIndex });
     }

src/cli/cmd-query.test.ts

@@ -26,6 +26,7 @@ describe("parseQueryRest", () => {
       sql: "SELECT 1",
       json: false,
       format: "text",
+      ci: false,
       summary: false,
       changedSince: undefined,
       recipeId: undefined,
@@ -42,6 +43,7 @@ describe("parseQueryRest", () => {
       sql: "SELECT 1",
       json: true,
       format: "json",
+      ci: false,
       summary: false,
       changedSince: undefined,
       recipeId: undefined,
@@ -58,6 +60,7 @@ describe("parseQueryRest", () => {
       sql: "SELECT 1",
       json: false,
       format: "text",
+      ci: false,
       summary: true,
       changedSince: undefined,
       recipeId: undefined,
@@ -74,6 +77,7 @@ describe("parseQueryRest", () => {
       sql: "SELECT 1",
       json: true,
       format: "json",
+      ci: false,
       summary: true,
       changedSince: undefined,
       recipeId: undefined,
@@ -92,6 +96,7 @@ describe("parseQueryRest", () => {
       sql: sql!,
       json: false,
       format: "text",
+      ci: false,
       summary: true,
       changedSince: undefined,
       recipeId: "fan-out",
@@ -113,6 +118,7 @@ describe("parseQueryRest", () => {
       sql: "SELECT 1",
       json: false,
       format: "text",
+      ci: false,
       summary: false,
       changedSince: "origin/main",
       recipeId: undefined,
@@ -138,6 +144,7 @@ describe("parseQueryRest", () => {
       sql: sql!,
       json: true,
       format: "json",
+      ci: false,
       summary: false,
       changedSince: "HEAD~3",
       recipeId: "fan-out",
@@ -160,6 +167,7 @@ describe("parseQueryRest", () => {
       sql: "SELECT * FROM symbols",
       json: true,
       format: "json",
+      ci: false,
       summary: false,
       changedSince: undefined,
       recipeId: undefined,
@@ -178,6 +186,7 @@ describe("parseQueryRest", () => {
       sql: sql!,
       json: false,
       format: "text",
+      ci: false,
       summary: false,
       changedSince: undefined,
       recipeId: "fan-in",
@@ -187,6 +196,52 @@ describe("parseQueryRest", () => {
     });
   });
 
+  it("parses --ci as alias for --format sarif + ci flag", () => {
+    const r = parseQueryRest(["query", "--ci", "-r", "deprecated-symbols"]);
+    if (r.kind !== "run") throw new Error("expected run");
+    expect(r.format).toBe("sarif");
+    expect(r.ci).toBe(true);
+  });
+
+  it("rejects --ci + --json (mutually exclusive aliases)", () => {
+    const r = parseQueryRest([
+      "query",
+      "--ci",
+      "--json",
+      "-r",
+      "deprecated-symbols",
+    ]);
+    expect(r.kind).toBe("error");
+    if (r.kind === "error") expect(r.message).toContain("--ci");
+  });
+
+  it("rejects --ci + --format json (contradicting alias)", () => {
+    const r = parseQueryRest([
+      "query",
+      "--ci",
+      "--format",
+      "json",
+      "-r",
+      "deprecated-symbols",
+    ]);
+    expect(r.kind).toBe("error");
+    if (r.kind === "error") expect(r.message).toContain("--ci");
+  });
+
+  it("accepts --ci + --format sarif (redundant but consistent)", () => {
+    const r = parseQueryRest([
+      "query",
+      "--ci",
+      "--format",
+      "sarif",
+      "-r",
+      "deprecated-symbols",
+    ]);
+    if (r.kind !== "run") throw new Error("expected run");
+    expect(r.format).toBe("sarif");
+    expect(r.ci).toBe(true);
+  });
+
   it("errors when --group-by has no mode", () => {
     const r = parseQueryRest(["query", "--group-by"]);
     expect(r.kind).toBe("error");
@@ -382,6 +437,7 @@ describe("parseQueryRest (continued — these were mis-nested in a prior PR)", (
       sql: sql!,
       json: false,
       format: "text",
+      ci: false,
       summary: false,
       changedSince: undefined,
       recipeId: "fan-out-sample-json",
@@ -400,6 +456,7 @@ describe("parseQueryRest (continued — these were mis-nested in a prior PR)", (
       sql: sql!,
       json: false,
       format: "text",
+      ci: false,
       summary: false,
       changedSince: undefined,
       recipeId: "fan-out",
@@ -465,6 +522,7 @@ describe("parseQueryRest (continued — these were mis-nested in a prior PR)", (
       sql: sql!,
       json: true,
       format: "json",
+      ci: false,
       summary: false,
       changedSince: undefined,
       recipeId: "fan-out-sample",
@@ -483,6 +541,7 @@ describe("parseQueryRest (continued — these were mis-nested in a prior PR)", (
       sql: sql!,
       json: true,
       format: "json",
+      ci: false,
       summary: false,
       changedSince: undefined,
       recipeId: "fan-out",
@@ -501,6 +560,7 @@ describe("parseQueryRest (continued — these were mis-nested in a prior PR)", (
       sql: sql!,
       json: true,
       format: "json",
+      ci: false,
       summary: false,
       changedSince: undefined,
       recipeId: "fan-out",