fix(ci-formats): address PR review — docs, tests, warning parity.

Hoist noLocatableFindingsWarning for CLI/MCP/HTTP; extend consumer surfaces (README, agent-content, MCP descriptions); add HTTP/MCP/formatter tests; reject badge_style without format=badge on all transports.

Author: SutuSebastian

README.md

@@ -131,7 +131,7 @@ codemap audit --base v1.0.0 --files-baseline pre-release-files  # mix --base wit
 # non-git projects get a clean `codemap audit: --base requires a git repository.` error.
 # 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.
-# --format <text|json|sarif|annotations|mermaid|diff|diff-json> — pipe results into GitHub Code Scanning
+# --format <text|json|sarif|annotations|mermaid|diff|diff-json|codeclimate|badge> — pipe results into GitHub Code Scanning
 # (SARIF 2.1.0), surface findings inline on PRs (GH Actions ::notice file=…,line=…::msg), or
 # render edge-shaped recipes as Mermaid `flowchart LR`, or preview edits as unified diffs. All
 # formatted outputs require a flat row list
@@ -142,6 +142,11 @@ codemap audit --base v1.0.0 --files-baseline pre-release-files  # mix --base wit
 codemap query --recipe deprecated-symbols --format sarif > findings.sarif
 codemap query --recipe deprecated-symbols --ci                    # CI shortcut: --format sarif + non-zero exit + quiet
 codemap query --recipe deprecated-symbols --format annotations    # one ::notice per row
+# GitLab Code Quality artifact (locatable rows only; flat minor severity):
+codemap query --recipe boundary-violations --format codeclimate > gl-code-quality-report.json
+# Badge summary for README paste or CI (counts locatable rows only):
+codemap query --recipe boundary-violations --format badge
+codemap query --recipe boundary-violations --format badge --badge-style json | jq -e '.status == "pass"'
 # Render any audit/SARIF output as a markdown PR-summary comment (for repos without
 # Code Scanning / aggregate audit deltas / bot-context seeding):
 codemap audit --base origin/main --json | codemap pr-comment - | gh pr comment <PR> -F -

docs/plans/ci-output-formats.md

@@ -62,7 +62,7 @@ Moat A: formatters only — no new analysis.
 
 1. `formatCodeClimate(opts: FormatOpts): string` in `output-formatters.ts`.
 2. `buildBadgeSummary(opts)` + `formatBadge` (markdown default) + `formatBadgeJson` (`codemap-badge/v1`; see F.8). CLI/MCP flag `--badge-style markdown|json` (default `markdown`).
-3. Wire `--format codeclimate|badge` in `cmd-query.ts` + `query-engine.ts` validation list.
+3. Wire `--format codeclimate|badge` in `cmd-query.ts` + `tool-handlers.ts` (MCP/HTTP dispatch).
 4. MCP/HTTP `format` enum extension + `badge_style` on query tools when `format=badge`.
 5. Snapshot tests in `output-formatters.test.ts` — Code Climate golden JSON; badge markdown + `codemap-badge/v1` JSON goldens.
 6. Docs — `architecture.md` output formatters §; README GitLab CI artifact example; agent note: badge is presentation — use JSON rows for triage.
@@ -83,11 +83,11 @@ bun src/index.ts query --recipe boundary-violations --format badge --badge-style
 
 ## Acceptance
 
-- [ ] `codemap query --recipe boundary-violations --format codeclimate` emits valid GitLab-ingestible JSON
-- [ ] Fingerprints stable across two runs with identical rows
-- [ ] `badge` markdown: `codemap: N issues` / `codemap: clean` for N>0 and N=0
-- [ ] `badge --badge-style json` emits stable `codemap-badge/v1` with matching `count` / `status`
-- [ ] Incompatible with `summary` / `group_by` / `baseline` (same rules as SARIF)
+- [x] `codemap query --recipe boundary-violations --format codeclimate` emits valid GitLab-ingestible JSON
+- [x] Fingerprints stable across two runs with identical rows
+- [x] `badge` markdown: `codemap: N issues` / `codemap: clean` for N>0 and N=0
+- [x] `badge --badge-style json` emits stable `codemap-badge/v1` with matching `count` / `status`
+- [x] Incompatible with `summary` / `group_by` / `baseline` (same rules as SARIF)
 
 ---
 

src/application/http-server.test.ts

@@ -289,6 +289,56 @@ describe("http-server — POST /tool/query", () => {
     expect(doc.version).toBe("2.1.0");
   });
 
+  it("format=codeclimate returns application/json", async () => {
+    serverHandle = await startServer();
+    const r = await fetch(`http://127.0.0.1:${serverHandle.port}/tool/query`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        sql: "SELECT name, file_path, line_start FROM symbols WHERE name = 'bar'",
+        format: "codeclimate",
+      }),
+    });
+    expect(r.status).toBe(200);
+    expect(r.headers.get("content-type")).toContain("application/json");
+    const issues = (await r.json()) as unknown[];
+    expect(Array.isArray(issues)).toBe(true);
+    expect(issues.length).toBeGreaterThan(0);
+  });
+
+  it("format=badge markdown returns text/plain", async () => {
+    serverHandle = await startServer();
+    const r = await fetch(`http://127.0.0.1:${serverHandle.port}/tool/query`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        sql: "SELECT name, file_path, line_start FROM symbols WHERE name = 'bar'",
+        format: "badge",
+      }),
+    });
+    expect(r.status).toBe(200);
+    expect(r.headers.get("content-type")).toContain("text/plain");
+    expect(await r.text()).toBe("codemap: 1 issue");
+  });
+
+  it("format=badge badge_style=json returns application/json", async () => {
+    serverHandle = await startServer();
+    const r = await fetch(`http://127.0.0.1:${serverHandle.port}/tool/query`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        sql: "SELECT name, file_path, line_start FROM symbols WHERE name = 'bar'",
+        format: "badge",
+        badge_style: "json",
+      }),
+    });
+    expect(r.status).toBe(200);
+    expect(r.headers.get("content-type")).toContain("application/json");
+    const doc = (await r.json()) as { schema: string; count: number };
+    expect(doc.schema).toBe("codemap-badge/v1");
+    expect(doc.count).toBe(1);
+  });
+
   it("format=annotations returns text/plain", async () => {
     serverHandle = await startServer();
     const r = await fetch(`http://127.0.0.1:${serverHandle.port}/tool/query`, {

src/application/mcp-server.test.ts

@@ -517,6 +517,45 @@ describe("MCP server — query_recipe tool", () => {
     }
   });
 
+  it("rejects format=codeclimate combined with summary", async () => {
+    const { client, server } = await makeClient();
+    try {
+      const r = await client.callTool({
+        name: "query_recipe",
+        arguments: {
+          recipe: "deprecated-symbols",
+          format: "codeclimate",
+          summary: true,
+        },
+      });
+      expect((r as { isError?: boolean }).isError).toBe(true);
+      expect(readJson(r)).toMatchObject({
+        error: expect.stringContaining("summary"),
+      });
+    } finally {
+      await server.close();
+    }
+  });
+
+  it("rejects badge_style without format=badge", async () => {
+    const { client, server } = await makeClient();
+    try {
+      const r = await client.callTool({
+        name: "query",
+        arguments: {
+          sql: "SELECT 1",
+          badge_style: "json",
+        },
+      });
+      expect((r as { isError?: boolean }).isError).toBe(true);
+      expect(readJson(r)).toMatchObject({
+        error: expect.stringContaining("badge_style"),
+      });
+    } finally {
+      await server.close();
+    }
+  });
+
   it("rejects format=sarif combined with summary", async () => {
     const { client, server } = await makeClient();
     try {

src/application/mcp-server.ts

@@ -204,7 +204,7 @@ function registerQueryTool(server: McpServer, opts: ServerOpts): void {
     "query",
     withToolAnnotations("query", {
       description:
-        'Run one read-only SQL statement against the codemap index (default `.codemap/index.db`). Returns the JSON envelope `codemap query --json` would print: row array by default, {count} under `summary`, {group_by, groups} under `group_by`, baseline diff under `baseline` (incompatible with non-json `format` / `group_by`). Pass `format: "sarif"` / `"annotations"` / `"mermaid"` / `"diff"` / `"diff-json"` to receive a formatted payload (incompatible with `summary` / `group_by` / `baseline`). Mermaid requires `{from, to, label?, kind?}` rows; diff requires `{file_path, line_start, before_pattern, after_pattern}` rows.',
+        'Run one read-only SQL statement against the codemap index (default `.codemap/index.db`). Returns the JSON envelope `codemap query --json` would print: row array by default, {count} under `summary`, {group_by, groups} under `group_by`, baseline diff under `baseline` (incompatible with non-json `format` / `group_by`). Pass `format: "sarif"` / `"annotations"` / `"mermaid"` / `"diff"` / `"diff-json"` / `"codeclimate"` / `"badge"` to receive a formatted payload (incompatible with `summary` / `group_by` / `baseline`). With `format: "badge"`, optional `badge_style: "markdown"` (default) or `"json"` (`codemap-badge/v1`). Mermaid requires `{from, to, label?, kind?}` rows; diff requires `{file_path, line_start, before_pattern, after_pattern}` rows; codeclimate/badge count locatable rows only.',
       inputSchema: queryArgsSchema,
     }),
     (args) => wrapToolResult(handleQuery(args, opts.root)),
@@ -216,7 +216,7 @@ function registerQueryRecipeTool(server: McpServer, opts: ServerOpts): void {
     "query_recipe",
     withToolAnnotations("query_recipe", {
       description:
-        'Run a recipe by id (bundled or project-local). Output rows carry per-row `actions` hints (recipe-only — `query` never adds them). Parametrised recipes accept `params: {key: value}` validated against recipe frontmatter. Compose with `summary` / `changed_since` / `group_by` / `baseline` exactly like `query` (`baseline` adds `actions` on `added` rows only). Pass `format: "sarif"` / `"annotations"` / `"mermaid"` / `"diff"` / `"diff-json"` to receive a formatted payload (incompatible with `summary` / `group_by` / `baseline`); SARIF rule id derives from the recipe id (`codemap.<recipe>`). List available recipes via the `codemap://recipes` resource.',
+        'Run a recipe by id (bundled or project-local). Output rows carry per-row `actions` hints (recipe-only — `query` never adds them). Parametrised recipes accept `params: {key: value}` validated against recipe frontmatter. Compose with `summary` / `changed_since` / `group_by` / `baseline` exactly like `query` (`baseline` adds `actions` on `added` rows only). Pass `format: "sarif"` / `"annotations"` / `"mermaid"` / `"diff"` / `"diff-json"` / `"codeclimate"` / `"badge"` to receive a formatted payload (incompatible with `summary` / `group_by` / `baseline`); SARIF rule id derives from the recipe id (`codemap.<recipe>`). With `format: "badge"`, optional `badge_style: "markdown"` or `"json"`. List available recipes via the `codemap://recipes` resource.',
       inputSchema: queryRecipeArgsSchema,
     }),
     (args) => wrapToolResult(handleQueryRecipe(args, opts.root)),

src/application/output-formatters.test.ts

@@ -18,6 +18,7 @@ import {
   escapeAnnotationProperty,
   formatAuditSarif,
   formatBadge,
+  countLocatableFindings,
   formatBadgeJson,
   formatCodeClimate,
   formatDiff,
@@ -27,6 +28,7 @@ import {
   formatSarif,
   hasLocatableRows,
   MERMAID_MAX_EDGES,
+  noLocatableFindingsWarning,
 } from "./output-formatters";
 
 let workDir: string;
@@ -72,6 +74,26 @@ describe("detectLocationColumn", () => {
   });
 });
 
+describe("noLocatableFindingsWarning", () => {
+  it("returns undefined for locatable rows", () => {
+    expect(
+      noLocatableFindingsWarning("badge", [{ file_path: "a.ts" }]),
+    ).toBeUndefined();
+  });
+
+  it("returns message for aggregate-only rows", () => {
+    expect(noLocatableFindingsWarning("codeclimate", [{ count: 5 }])).toContain(
+      "codeclimate",
+    );
+  });
+
+  it("skips mermaid", () => {
+    expect(
+      noLocatableFindingsWarning("mermaid", [{ count: 5 }]),
+    ).toBeUndefined();
+  });
+});
+
 describe("hasLocatableRows", () => {
   it("false on empty rows", () => {
     expect(hasLocatableRows([])).toBe(false);
@@ -295,6 +317,24 @@ describe("formatCodeClimate", () => {
     expect(JSON.parse(out)).toHaveLength(1);
   });
 
+  it("omits location.lines when line_start is absent", () => {
+    const out = formatCodeClimate({
+      rows: [{ file_path: "a.ts", fan_in: 17 }],
+      recipeId: "fan-in",
+    });
+    const issues = JSON.parse(out);
+    expect(issues[0].location).toEqual({ path: "a.ts" });
+  });
+
+  it("buildCodeClimateFingerprint uses adhoc when recipeId omitted", () => {
+    expect(
+      buildCodeClimateFingerprint(undefined, "a.ts", 1, "adhoc"),
+    ).toHaveLength(16);
+    expect(buildCodeClimateFingerprint(undefined, "a.ts", 1, "adhoc")).toBe(
+      buildCodeClimateFingerprint(undefined, "a.ts", 1, "adhoc"),
+    );
+  });
+
   it("fingerprints are stable across identical inputs", () => {
     const row = { file_path: "a.ts", line_start: 1, name: "foo" };
     const a = JSON.parse(
@@ -352,6 +392,24 @@ describe("formatBadge", () => {
     });
   });
 
+  it("json clean when no locatable rows", () => {
+    const doc = JSON.parse(
+      formatBadgeJson({ rows: [], recipeId: "index-summary" }),
+    );
+    expect(doc).toMatchObject({
+      schema: "codemap-badge/v1",
+      count: 0,
+      status: "pass",
+      message: "clean",
+    });
+  });
+
+  it("countLocatableFindings matches locatable row semantics", () => {
+    const rows = [{ kind: "TODO" }, { file_path: "a.ts" }];
+    expect(countLocatableFindings(rows)).toBe(1);
+    expect(hasLocatableRows(rows)).toBe(true);
+  });
+
   it("buildBadgeSummary matches markdown/json count", () => {
     const rows = [{ file_path: "a.ts" }, { file_path: "b.ts" }];
     const summary = buildBadgeSummary({ rows, recipeId: "fan-in" });

src/application/output-formatters.ts

@@ -10,9 +10,11 @@
  * aggregates (`index-summary`, `markers-by-kind`), not findings. See
  * [`docs/architecture.md` § Output formatters](../../docs/architecture.md#cli-usage).
  *
- * Both formatters are pure: take rows + recipe metadata, return a string.
+ * Formatters are pure: take rows + recipe metadata, return a string.
  * No I/O, no DB access. Same engine wired into both the CLI (`cmd-query.ts`)
- * and the MCP `query` / `query_recipe` tools.
+ * and the MCP `query` / `query_recipe` tools. Also ships
+ * {@link formatCodeClimate} (GitLab Code Quality JSON) and
+ * {@link formatBadge} / {@link formatBadgeJson} (issue-count summary).
  */
 
 import { createHash } from "node:crypto";
@@ -64,6 +66,21 @@ export function hasLocatableRows(rows: Record<string, unknown>[]): boolean {
   return rows.some((r) => detectLocationColumn(r) !== null);
 }
 
+/**
+ * Warning text when a formatted output skips aggregate rows (plan F.5). Returns
+ * `undefined` when no warning applies (mermaid, empty rows, or ≥1 locatable row).
+ */
+export function noLocatableFindingsWarning(
+  format: string,
+  rows: Record<string, unknown>[],
+  opts?: { ci?: boolean },
+): string | undefined {
+  if (opts?.ci === true) return undefined;
+  if (format === "mermaid") return undefined;
+  if (rows.length === 0 || hasLocatableRows(rows)) return undefined;
+  return `codemap: --format ${format}: recipe / SQL emitted ${rows.length} row(s) with no file_path / path / to_path / from_path column — these aren't findings, skipping. (Aggregate recipes like index-summary / markers-by-kind don't map to ${format} v1.)`;
+}
+
 /**
  * Build a one-line message for a result row. Strips location columns and
  * stringifies what's left; if `name` is present, leads with it (e.g.

src/application/tool-handlers.test.ts

@@ -162,6 +162,62 @@ describe("handleQuery baseline", () => {
     });
   });
 
+  it("rejects badge_style=json when format is omitted", () => {
+    const result = handleQuery(
+      { sql: "SELECT 1", badge_style: "json" },
+      projectRoot,
+    );
+    expect(result).toMatchObject({
+      ok: false,
+      error: expect.stringContaining(
+        "badge_style is only valid with format=badge",
+      ),
+    });
+  });
+
+  it("rejects format=codeclimate + summary", () => {
+    const result = handleQuery(
+      {
+        sql: "SELECT file_path FROM symbols",
+        format: "codeclimate",
+        summary: true,
+      },
+      projectRoot,
+    );
+    expect(result).toMatchObject({
+      ok: false,
+      error: expect.stringContaining("cannot be combined with summary"),
+    });
+  });
+
+  it("rejects format=badge + group_by", () => {
+    const result = handleQuery(
+      {
+        sql: "SELECT file_path FROM symbols",
+        format: "badge",
+        group_by: "directory",
+      },
+      projectRoot,
+    );
+    expect(result).toMatchObject({
+      ok: false,
+      error: expect.stringContaining("cannot be combined with group_by"),
+    });
+  });
+
+  it("handleQueryRecipe format=codeclimate uses recipe check_name", () => {
+    const result = handleQueryRecipe(
+      { recipe: "fan-in", format: "codeclimate" },
+      projectRoot,
+    );
+    expect(result.ok).toBe(true);
+    if (!result.ok || result.format !== "codeclimate") return;
+    const issues = JSON.parse(result.payload) as Array<{ check_name: string }>;
+    if (issues.length > 0) {
+      expect(issues[0]?.check_name).toBe("fan-in");
+    }
+  });
+
   it("rejects baseline + group_by", () => {
     const result = handleQuery(
       { sql: "SELECT 1", baseline: "pre", group_by: "directory" },