feat(cli): codemap pr-comment + action.yml integration (Slice 3 of #73 plan)

Slice 3 — markdown PR-summary writer for the cases SARIF→Code-Scanning
doesn't cover well: private repos without GHAS, repos that haven't
enabled Code Scanning, aggregate audit deltas without a single
file:line anchor, and bot-context seeding (review bots read PR
conversation, not workflow artifacts).

Architecture (engine + CLI separation, mirrors show / impact / audit):

- src/application/pr-comment-engine.ts — pure transport-agnostic
  renderer. Auto-detects input shape (audit envelope vs SARIF doc) +
  renders markdown grouped by delta key (audit) or rule id (SARIF).
  Lists >50 entries collapse to `… and N more`. Removed rows surface
  in their own collapsed section (audit only).
- src/cli/cmd-pr-comment.ts — CLI wrapper. Reads JSON from a file or
  stdin (`-`). `--shape audit|sarif` overrides autodetection;
  `--json` emits structured envelope `{ markdown, findings_count,
  kind }` for action.yml steps.
- src/cli/main.ts + src/cli/bootstrap.ts wire the new `pr-comment`
  verb (whitelist + dispatch).

action.yml integration (Slice 2 stub replaced):

- pr-comment toggle now actually invokes `codemap pr-comment` against
  the SARIF / JSON output file produced by the run step, then posts
  via `gh pr comment <PR> -F -`. Same binary that produced the output
  renders the comment — version stream stays coherent.

Tests:

- 12 new pr-comment-engine unit tests (input shape detection,
  no-drift / no-findings ✅ rendering, audit summary line + per-delta
  sections, SARIF rule grouping, location formatting, >50 collapse).
- Smoke verified: real audit envelope produces markdown with file:
  links + delta sections; SARIF doc groups findings by rule id.

Lockstep updates (per docs/README.md Rule 10):

- .agents/rules/codemap.md + templates/agents/rules/codemap.md
  gain rows for `--ci` aggregate flag (Slice 1b) and `pr-comment`
  renderer (Slice 3).

Author: SutuSebastian

.agents/rules/codemap.md

@@ -37,6 +37,8 @@ A local database (default **`.codemap/index.db`**) indexes structure: symbols, i
 | Impact (blast-radius walker)   | —                  | `bun src/index.ts impact <target> [--direction up\|down\|both] [--depth N] [--via <b>] [--limit N] [--summary] [--json]` — replaces hand-composed `WITH RECURSIVE` queries                                                                                                                                 |
 | Coverage ingest                | —                  | `bun src/index.ts ingest-coverage <path> [--json]` — Istanbul (`coverage-final.json`) or LCOV (`lcov.info`); format auto-detected. Joinable to `symbols` for "untested AND dead" queries.                                                                                                                  |
 | SARIF / GH annotations         | —                  | `bun src/index.ts query --recipe deprecated-symbols --format sarif` · `… --format annotations`                                                                                                                                                                                                             |
+| `--ci` aggregate flag          | —                  | `bun src/index.ts query -r deprecated-symbols --ci` (or `audit --base origin/main --ci`) — aliases `--format sarif` + non-zero exit when findings/additions surfaced + suppresses no-findings stderr warning. Mutually exclusive with `--json` / `--format <other>`.                                       |
+| PR-comment renderer            | —                  | `bun src/index.ts pr-comment <input.json>` (or `-` for stdin) — renders an audit JSON envelope or SARIF doc as a markdown PR-summary comment. Pipe to `gh pr comment <PR> -F -`. Useful for private repos without GHAS, aggregate audit deltas, or bot-context seeding.                                    |
 | Mermaid graph (≤50 edges)      | —                  | `bun src/index.ts query --format mermaid 'SELECT from_path AS "from", to_path AS "to" FROM dependencies LIMIT 50'` — recipes / SQL must alias columns to `{from, to, label?, kind?}`; rejects unbounded inputs.                                                                                            |
 | Diff preview                   | —                  | `bun src/index.ts query --format diff '<SQL returning file_path, line_start, before_pattern, after_pattern>'` — read-only unified diff; `--format diff-json` returns structured hunks for agents.                                                                                                          |
 | FTS5 full-text (opt-in)        | `--with-fts`       | `bun src/index.ts --with-fts --full` enables `source_fts` virtual table; `query --recipe text-in-deprecated-functions` demos JOINs.                                                                                                                                                                        |

action.yml

@@ -244,13 +244,22 @@ runs:
     - name: Post PR summary comment
       if: steps.gate.outputs.skip != 'true' && inputs.pr-comment == 'true' && github.event_name == 'pull_request' && always()
       shell: bash
+      working-directory: ${{ inputs.working-directory }}
       env:
         EXEC: ${{ steps.detect-pm.outputs.exec }}
-        OUTPUT_PATH: ${{ inputs.working-directory }}/${{ inputs.output-path }}
-        FORMAT: ${{ inputs.format }}
+        OUTPUT_PATH: ${{ inputs.output-path }}
         PR_NUMBER: ${{ github.event.pull_request.number }}
         GH_TOKEN: ${{ inputs.token }}
       run: |
-        # Slice 3 lands `codemap pr-comment` later; until then, just stub a
-        # short marker comment so downstream consumers can see the toggle works.
-        echo "::warning::codemap action: pr-comment writer (Slice 3) not yet implemented; toggle was set but no comment was posted."
+        # Render the markdown body via `codemap pr-comment`, then post via
+        # `gh pr comment`. The same binary that produced the SARIF / JSON
+        # output renders the comment — keeps the version stream coherent.
+        BODY=$($EXEC pr-comment "$OUTPUT_PATH" 2>/dev/null) || {
+          echo "::warning::codemap action: pr-comment renderer failed; skipping PR comment."
+          exit 0
+        }
+        if [ -z "$BODY" ]; then
+          echo "::notice::codemap action: pr-comment produced empty body; skipping."
+          exit 0
+        fi
+        echo "$BODY" | gh pr comment "$PR_NUMBER" -F -

src/application/pr-comment-engine.test.ts

@@ -0,0 +1,220 @@
+import { describe, expect, it } from "bun:test";
+
+import {
+  detectCommentInputShape,
+  renderAuditComment,
+  renderSarifComment,
+} from "./pr-comment-engine";
+
+describe("detectCommentInputShape", () => {
+  it("identifies audit envelopes by the deltas field", () => {
+    expect(detectCommentInputShape({ head: {}, deltas: {} })).toBe("audit");
+  });
+
+  it("identifies SARIF docs by the runs[] field", () => {
+    expect(detectCommentInputShape({ version: "2.1.0", runs: [] })).toBe(
+      "sarif",
+    );
+  });
+
+  it("returns 'empty' for {}", () => {
+    expect(detectCommentInputShape({})).toBe("empty");
+  });
+
+  it("returns 'unknown' for arbitrary objects", () => {
+    expect(detectCommentInputShape({ something: "else" })).toBe("unknown");
+  });
+
+  it("returns 'unknown' for non-objects", () => {
+    expect(detectCommentInputShape("hello")).toBe("unknown");
+    expect(detectCommentInputShape(null)).toBe("unknown");
+    expect(detectCommentInputShape(42)).toBe("unknown");
+  });
+});
+
+describe("renderAuditComment", () => {
+  it("emits ✅ when no drift across deltas", () => {
+    const r = renderAuditComment({
+      head: {},
+      deltas: {
+        files: { base: { source: "ref", ref: "main" }, added: [], removed: [] },
+      },
+    });
+    expect(r.findings_count).toBe(0);
+    expect(r.kind).toBe("audit");
+    expect(r.markdown).toContain("✅");
+    expect(r.markdown).toContain("No structural drift");
+  });
+
+  it("renders summary line + per-delta sections for added rows", () => {
+    const r = renderAuditComment({
+      head: { sha: "abc12345" },
+      deltas: {
+        files: {
+          base: { source: "ref", ref: "origin/main", sha: "deadbeef0000" },
+          added: [{ path: "src/new.ts" }],
+          removed: [],
+        },
+        dependencies: {
+          base: { source: "baseline", name: "base-dependencies" },
+          added: [
+            { from_path: "src/a.ts", to_path: "src/b.ts" },
+            { from_path: "src/c.ts", to_path: "src/d.ts" },
+          ],
+          removed: [],
+        },
+      },
+    });
+    expect(r.findings_count).toBe(3);
+    // Summary line surfaces non-zero deltas.
+    expect(r.markdown).toContain("**files**: +1 / -0");
+    expect(r.markdown).toContain("**dependencies**: +2 / -0");
+    // Sections per delta.
+    expect(r.markdown).toContain("### files");
+    expect(r.markdown).toContain("### dependencies");
+    // File-added row → location-only formatting.
+    expect(r.markdown).toContain("`src/new.ts`");
+    // Dependency-added row → from → to formatting.
+    expect(r.markdown).toContain("`src/a.ts` → `src/b.ts`");
+    // Baseline metadata visible.
+    expect(r.markdown).toContain("origin/main");
+    expect(r.markdown).toContain("base-dependencies");
+  });
+
+  it("collapses lists >50 rows", () => {
+    const added: Record<string, unknown>[] = [];
+    for (let i = 0; i < 75; i++) added.push({ path: `src/f${i}.ts` });
+    const r = renderAuditComment({
+      head: {},
+      deltas: {
+        files: {
+          base: { source: "ref", ref: "main", sha: "abc" },
+          added,
+          removed: [],
+        },
+      },
+    });
+    expect(r.findings_count).toBe(75);
+    expect(r.markdown).toContain("… and 25 more");
+  });
+
+  it("includes removed rows in their own collapsed section", () => {
+    const r = renderAuditComment({
+      head: {},
+      deltas: {
+        deprecated: {
+          base: { source: "ref", ref: "main", sha: "abc" },
+          added: [],
+          removed: [{ name: "oldFn", kind: "function", file_path: "src/x.ts" }],
+        },
+      },
+    });
+    expect(r.markdown).toContain("➖ 1 removed");
+    expect(r.markdown).toContain("`oldFn`");
+  });
+});
+
+describe("renderSarifComment", () => {
+  it("emits ✅ when no findings", () => {
+    const r = renderSarifComment({
+      version: "2.1.0",
+      runs: [
+        {
+          tool: { driver: { name: "codemap", rules: [] } },
+          results: [],
+        },
+      ],
+    });
+    expect(r.findings_count).toBe(0);
+    expect(r.markdown).toContain("✅");
+  });
+
+  it("groups results by ruleId in summary + sections", () => {
+    const r = renderSarifComment({
+      version: "2.1.0",
+      runs: [
+        {
+          tool: {
+            driver: {
+              name: "codemap",
+              rules: [
+                {
+                  id: "codemap.deprecated-symbols",
+                  name: "deprecated-symbols",
+                },
+                { id: "codemap.untested-and-dead", name: "untested-and-dead" },
+              ],
+            },
+          },
+          results: [
+            {
+              ruleId: "codemap.deprecated-symbols",
+              message: { text: "oldFn is deprecated" },
+              locations: [
+                {
+                  physicalLocation: {
+                    artifactLocation: { uri: "src/a.ts" },
+                    region: { startLine: 12 },
+                  },
+                },
+              ],
+            },
+            {
+              ruleId: "codemap.deprecated-symbols",
+              message: { text: "anotherFn is deprecated" },
+            },
+            {
+              ruleId: "codemap.untested-and-dead",
+              message: { text: "deadFn never called" },
+              locations: [
+                {
+                  physicalLocation: {
+                    artifactLocation: { uri: "src/b.ts" },
+                  },
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    });
+    expect(r.findings_count).toBe(3);
+    // Summary line.
+    expect(r.markdown).toContain("**codemap.deprecated-symbols**: 2");
+    expect(r.markdown).toContain("**codemap.untested-and-dead**: 1");
+    // Per-rule sections.
+    expect(r.markdown).toContain("### codemap.deprecated-symbols (2)");
+    expect(r.markdown).toContain("### codemap.untested-and-dead (1)");
+    // Result lines with location.
+    expect(r.markdown).toContain("`src/a.ts:12`");
+    expect(r.markdown).toContain("`src/b.ts`");
+    // Result without location still renders the message.
+    expect(r.markdown).toContain("anotherFn is deprecated");
+  });
+
+  it("collapses results lists >50 entries per rule", () => {
+    const results = [];
+    for (let i = 0; i < 75; i++) {
+      results.push({
+        ruleId: "codemap.bulk",
+        message: { text: `finding ${i}` },
+      });
+    }
+    const r = renderSarifComment({
+      version: "2.1.0",
+      runs: [
+        {
+          tool: {
+            driver: {
+              name: "codemap",
+              rules: [{ id: "codemap.bulk", name: "bulk" }],
+            },
+          },
+          results,
+        },
+      ],
+    });
+    expect(r.findings_count).toBe(75);
+    expect(r.markdown).toContain("… and 25 more");
+  });
+});