@intentius/chant 0.4.0 → 0.6.0

package/src/audit/report-html.ts

@@ -0,0 +1,207 @@
+/**
+ * HTML report generator (the "expanded" mode) — a self-contained, presentable
+ * report rendered from the shared report model. Inline CSS, no external assets;
+ * opens in a browser and is shareable as a single file. Also the natural output
+ * for the future hosted service.
+ *
+ * Customization: a default template with `{{placeholder}}` slots, overridable
+ * via `template`, plus theme knobs (title, logo, accent, footer).
+ */
+
+import type { AuditFinding } from "./core";
+import { ruleDocUrl } from "./catalog";
+import { buildReportModel, buildReportJson, type AuditSnapshot, type BuildModelOptions, type EnrichedFinding, type GuidanceCluster, type QuickWinFile, type ReportCounts } from "./report-model";
+
+export type { AuditSnapshot } from "./report-model";
+
+/** Customizable theme knobs filled into the template. */
+export interface ReportTheme {
+  title?: string;
+  /** Logo: a URL (rendered as <img>) or inline text/SVG. */
+  logo?: string;
+  /** CSS color for accents. */
+  accent?: string;
+  /** Footer HTML (defaults to attribution). */
+  footer?: string;
+}
+
+export interface RenderHtmlOptions extends BuildModelOptions {
+  snapshot?: AuditSnapshot;
+  theme?: ReportTheme;
+  /** Full template override; `{{title}} {{accent}} {{logo}} {{meta}} {{body}} {{footer}}` slots. */
+  template?: string;
+  notes?: string[];
+}
+
+const DEFAULT_ACCENT = "#7c3aed";
+const DEFAULT_TITLE = "CI Security Audit";
+const DEFAULT_FOOTER = 'Generated by <a href="https://intentius.io/chant/cli/audit/">chant audit</a>.';
+
+function esc(s: string): string {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+
+/** A rule id as a link to its reference entry. */
+function ruleLink(id: string): string {
+  return `<a class="rule-id" href="${esc(ruleDocUrl(id))}">${esc(id)}</a>`;
+}
+
+function renderDiff(diff: string): string {
+  const rows = diff
+    .split("\n")
+    .map((l) => {
+      const cls = l.startsWith("@@") ? "hunk" : l.startsWith("+") ? "add" : l.startsWith("-") ? "del" : "ctx";
+      return `<span class="${cls}">${esc(l) || " "}</span>`;
+    })
+    .join("\n");
+  return `<pre class="diff">${rows}</pre>`;
+}
+
+function renderQuickWins(files: QuickWinFile[]): string {
+  const cards = files
+    .map((qw) => {
+      const chips = qw.addressed.map((m) => `<span class="chip">${ruleLink(m.id)} ${esc(m.title)}</span>`).join(" ");
+      const diff = qw.diff ? renderDiff(qw.diff) : "";
+      const needs = qw.needsInput.length
+        ? `<div class="needs"><strong>Needs a value to auto-patch:</strong><ul>${qw.needsInput
+            .map((f) => `<li>${ruleLink(f.checkId)}${f.entity ? ` (<code>${esc(f.entity)}</code>)` : ""} — ${esc(f.meta.remediation)}</li>`)
+            .join("")}</ul></div>`
+        : "";
+      return `<div class="card"><div class="card-head"><code class="file">${esc(qw.file)}</code> ${chips}</div>${diff}${needs}</div>`;
+    })
+    .join("\n");
+  return `<section><h2>Quick wins <span class="muted">deterministic</span></h2><p class="muted">Safe mechanical fixes — the diff changes only the flagged lines.</p>${cards}</section>`;
+}
+
+function renderNeedsReview(clusters: GuidanceCluster[], n: number): string {
+  const body = clusters
+    .map((c) => {
+      const head = c.url ? `<a href="${esc(c.url)}">${esc(c.name)}</a>` : esc(c.name);
+      const rules = c.rules
+        .map(({ meta, findings }) => {
+          const locs = findings
+            .map((f) => `<li><code>${esc(f.file)}</code>${f.entity ? ` (<code>${esc(f.entity)}</code>)` : ""} — ${esc(f.message)}</li>`)
+            .join("");
+          return `<div class="rule"><div><span class="sev ${findings[0].severity}"></span><strong>${ruleLink(meta.id)}</strong> — ${esc(meta.title)}. <span class="muted">${esc(meta.remediation)}</span></div><ul>${locs}</ul></div>`;
+        })
+        .join("");
+      return `<div class="cluster"><h3>${head}</h3>${rules}</div>`;
+    })
+    .join("\n");
+  return `<details open><summary>Needs review <span class="muted">guidance — ${n}</span></summary><p class="muted">These need a judgement call — remediation guidance, not an auto-fix.</p>${body}</details>`;
+}
+
+function renderReportOnly(findings: EnrichedFinding[], n: number): string {
+  const rows = findings
+    .map((f) => `<tr><td>${ruleLink(f.checkId)}</td><td>${esc(f.meta.title)}</td><td><code>${esc(f.file)}</code></td><td>${esc(f.message)}</td></tr>`)
+    .join("");
+  return `<details><summary>Report-only <span class="muted">hygiene — ${n}</span></summary><table><thead><tr><th>Rule</th><th>Title</th><th>File</th><th>Detail</th></tr></thead><tbody>${rows}</tbody></table></details>`;
+}
+
+function renderHeader(counts: ReportCounts, snapshot: AuditSnapshot | undefined, notes: string[]): string {
+  const sev = `<span class="sev error"></span>${counts.errors} error <span class="sev warning"></span>${counts.warnings} warning <span class="sev info"></span>${counts.infos} info`;
+  const tiers = `<span class="chip">${counts.quickWin} quick-win</span> <span class="chip">${counts.needsReview} needs-review</span> <span class="chip">${counts.reportOnly} hygiene</span>`;
+  const meta: string[] = [];
+  if (snapshot) {
+    if (snapshot.host) meta.push(esc(snapshot.host));
+    if (snapshot.repo) meta.push(esc(snapshot.repo));
+    else meta.push(esc(snapshot.target));
+    if (snapshot.ref) meta.push(`ref <code>${esc(snapshot.ref)}</code>`);
+    if (snapshot.commit) meta.push(`commit <code>${esc(snapshot.commit.slice(0, 10))}</code>`);
+    meta.push(esc(snapshot.generatedAt.slice(0, 10)));
+    meta.push(`${snapshot.files.length} file${snapshot.files.length === 1 ? "" : "s"}`);
+    meta.push(`chant ${esc(snapshot.toolVersion)}`);
+  }
+  const noteHtml = notes.map((n) => `<div class="note">${esc(n)}</div>`).join("");
+  return `<div class="summary"><div class="meta">${meta.join(" · ")}</div><div class="counts">${sev}</div><div class="tiers">${tiers}</div>${noteHtml}</div>`;
+}
+
+const STYLES = `
+:root { --accent: {{accent}}; }
+* { box-sizing: border-box; }
+body { font: 15px/1.55 -apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,Helvetica,Arial,sans-serif; color: #1f2328; margin: 0; background: #f6f8fa; }
+.wrap { max-width: 920px; margin: 0 auto; padding: 32px 20px 64px; }
+header { display: flex; align-items: center; gap: 12px; border-bottom: 3px solid var(--accent); padding-bottom: 16px; margin-bottom: 20px; }
+header h1 { font-size: 22px; margin: 0; }
+.logo { height: 32px; }
+.summary { background: #fff; border: 1px solid #d0d7de; border-radius: 10px; padding: 16px 18px; margin-bottom: 24px; }
+.summary .meta { color: #57606a; font-size: 13px; margin-bottom: 10px; }
+.counts { font-weight: 600; margin-bottom: 8px; }
+.sev { display: inline-block; width: 9px; height: 9px; border-radius: 50%; margin: 0 4px 0 10px; vertical-align: middle; }
+.sev.error { background: #cf222e; } .sev.warning { background: #d4a72c; } .sev.info { background: #8c959f; }
+.sev:first-child { margin-left: 0; }
+.chip { display: inline-block; background: #eef1f4; border: 1px solid #d0d7de; border-radius: 999px; padding: 1px 10px; font-size: 12px; color: #424a53; }
+.tiers .chip { margin-right: 4px; }
+.note { margin-top: 10px; background: #fff8c5; border: 1px solid #d4a72c66; border-radius: 6px; padding: 8px 10px; font-size: 13px; }
+h2 { font-size: 18px; margin: 28px 0 4px; } h3 { font-size: 15px; margin: 16px 0 6px; }
+.muted { color: #57606a; font-weight: 400; font-size: 13px; }
+.card { background: #fff; border: 1px solid #d0d7de; border-radius: 10px; padding: 14px 16px; margin: 12px 0; }
+.card-head { margin-bottom: 8px; display: flex; flex-wrap: wrap; gap: 6px; align-items: center; }
+.file { background: #eef1f4; padding: 2px 7px; border-radius: 6px; font-size: 13px; }
+.card-head .chip { background: var(--accent); border-color: var(--accent); color: #fff; }
+pre.diff { background: #0d1117; color: #c9d1d9; border-radius: 8px; padding: 12px 14px; overflow-x: auto; font: 12.5px/1.5 ui-monospace,SFMono-Regular,Menlo,Consolas,monospace; margin: 0; }
+pre.diff span { display: block; white-space: pre; }
+pre.diff .add { color: #3fb950; } pre.diff .del { color: #f85149; } pre.diff .hunk { color: #a371f7; } pre.diff .ctx { color: #8b949e; }
+.needs { margin-top: 10px; font-size: 13px; }
+details { background: #fff; border: 1px solid #d0d7de; border-radius: 10px; padding: 8px 16px; margin: 16px 0; }
+summary { cursor: pointer; font-size: 16px; font-weight: 600; }
+.cluster { margin: 10px 0; } .rule { margin: 8px 0; } .rule ul, .needs ul { margin: 4px 0 4px 0; }
+table { border-collapse: collapse; width: 100%; font-size: 13px; margin-top: 8px; }
+th, td { text-align: left; border-bottom: 1px solid #d0d7de; padding: 6px 8px; vertical-align: top; }
+th { color: #57606a; }
+code { font: 12.5px ui-monospace,SFMono-Regular,Menlo,Consolas,monospace; }
+footer { margin-top: 40px; padding-top: 16px; border-top: 1px solid #d0d7de; color: #57606a; font-size: 13px; }
+a { color: var(--accent); }
+.rule-id { color: var(--accent); text-decoration: none; font-weight: 600; }
+.rule-id:hover { text-decoration: underline; }
+.card-head .chip .rule-id { color: #fff; }
+`;
+
+const DEFAULT_TEMPLATE = `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
+<title>{{title}}</title>
+<style>{{styles}}</style>
+</head><body><div class="wrap">
+<header>{{logo}}<h1>{{title}}</h1></header>
+{{body}}
+<footer>{{footer}}</footer>
+</div></body></html>`;
+
+/** Render an audit report as a self-contained HTML document. */
+export function renderHtml(findings: AuditFinding[], opts: RenderHtmlOptions = {}): string {
+  const model = buildReportModel(findings, opts);
+  const theme = opts.theme ?? {};
+  const accent = theme.accent ?? DEFAULT_ACCENT;
+  const title = theme.title ?? DEFAULT_TITLE;
+  const logo = theme.logo ? (/^https?:\/\//.test(theme.logo) ? `<img class="logo" src="${esc(theme.logo)}" alt="">` : theme.logo) : "";
+  const footer = theme.footer ?? DEFAULT_FOOTER;
+
+  // Machine-readable data embedded so the HTML report is also parseable.
+  // `<` escaped so the JSON can't break out of the <script> element.
+  const dataJson = JSON.stringify(buildReportJson(findings, { snapshot: opts.snapshot }), null, 0).replace(/</g, "\\u003c");
+  const dataScript = `<script type="application/json" id="chant-audit-report">${dataJson}</script>`;
+
+  let body: string;
+  if (model.counts.total === 0) {
+    body = renderHeader(model.counts, opts.snapshot, opts.notes ?? []) + `<section><p>No issues found.</p></section>` + dataScript;
+  } else {
+    const parts = [renderHeader(model.counts, opts.snapshot, opts.notes ?? [])];
+    if (model.quickWins.length > 0) parts.push(renderQuickWins(model.quickWins));
+    if (model.needsReview.length > 0) parts.push(renderNeedsReview(model.needsReview, model.counts.needsReview));
+    if (model.reportOnly.length > 0) parts.push(renderReportOnly(model.reportOnly, model.counts.reportOnly));
+    parts.push(dataScript);
+    body = parts.join("\n");
+  }
+
+  const slots: Record<string, string> = {
+    title: esc(title),
+    accent,
+    styles: STYLES.replace("{{accent}}", accent),
+    logo,
+    body,
+    footer,
+  };
+  const template = opts.template ?? DEFAULT_TEMPLATE;
+  // Single pass over the template only, so injected body content isn't re-scanned.
+  return template.replace(/\{\{(\w+)\}\}/g, (_, k: string) => slots[k] ?? "");
+}

package/src/audit/report-model.ts

@@ -0,0 +1,275 @@
+/**
+ * Shared report model — turns raw findings into the structured shape both the
+ * Markdown and HTML renderers consume, so they can never drift. Computes the
+ * tier split, de-noising, per-file quick-win patches (combined unified diff via
+ * proof.ts), guidance clusters, and severity counts.
+ */
+
+import type { AuditFinding } from "./core";
+import { RULE_CATALOG, ruleDocUrl, type Authority, type FixKind, type RuleMeta, type Tier } from "./catalog";
+import { proveFix, unifiedDiff, type ProveOptions } from "./proof";
+import type { Severity } from "../lint/rule";
+
+/**
+ * Version of the machine-readable JSON report. Stability contract: additive
+ * changes (new fields) keep the same major; renamed/removed fields bump the
+ * major. Consumers should check the major and ignore unknown fields. See
+ * `docs/cli/audit`.
+ */
+export const REPORT_SCHEMA_VERSION = "1.0";
+
+export const SEVERITY_WEIGHT: Record<Severity, number> = { error: 0, warning: 1, info: 2 };
+
+/** Report-only rules made redundant by a specific merge-worthy rule on the same entity. */
+const SUPERSEDED_BY: Record<string, string[]> = {
+  WGL021: ["WGL016"], // "unused variable" is noise when the var is a flagged hardcoded secret
+};
+
+export interface EnrichedFinding extends AuditFinding {
+  meta: RuleMeta;
+}
+
+/** A per-file quick-win: a combined patch plus any findings still needing input. */
+export interface QuickWinFile {
+  file: string;
+  /** Combined unified diff of the deterministic fixes applied to this file. */
+  diff?: string;
+  /** Rules the diff addresses. */
+  addressed: RuleMeta[];
+  /** Deduped findings that are deterministic but blocked on a value (e.g. a SHA). */
+  needsInput: EnrichedFinding[];
+}
+
+/** Guidance findings grouped by their primary authority. */
+export interface GuidanceCluster {
+  name: string;
+  url?: string;
+  rules: Array<{ meta: RuleMeta; findings: EnrichedFinding[] }>;
+}
+
+export interface ReportCounts {
+  total: number;
+  quickWin: number;
+  needsReview: number;
+  reportOnly: number;
+  errors: number;
+  warnings: number;
+  infos: number;
+}
+
+export interface ReportModel {
+  counts: ReportCounts;
+  quickWins: QuickWinFile[];
+  needsReview: GuidanceCluster[];
+  reportOnly: EnrichedFinding[];
+  /** All shown findings (after de-noise), flat and sorted — for serialization. */
+  findings: EnrichedFinding[];
+}
+
+/** Provenance snapshot of what was audited (anchors findings to a commit). */
+export interface AuditSnapshot {
+  target: string;
+  host?: string;
+  repo?: string;
+  ref?: string;
+  commit?: string;
+  files: string[];
+  generatedAt: string;
+  toolVersion: string;
+}
+
+/** A finding flattened for the machine-readable JSON report. */
+export interface SerializedFinding {
+  checkId: string;
+  severity: Severity;
+  message: string;
+  file: string;
+  entity?: string;
+  lexicon: string;
+  tier: Tier;
+  fixKind: FixKind;
+  title: string;
+  remediation: string;
+  authority: Authority[];
+  /** Link to this rule's entry in the audit rules reference. */
+  docUrl: string;
+}
+
+/** The versioned machine-readable audit report. */
+export interface AuditReportJson {
+  schemaVersion: string;
+  tool: { name: string; version: string };
+  snapshot?: AuditSnapshot;
+  summary: ReportCounts;
+  findings: SerializedFinding[];
+}
+
+export function metaFor(id: string): RuleMeta {
+  return (
+    RULE_CATALOG[id] ?? {
+      id,
+      tier: "report-only" as Tier,
+      fixKind: "guidance",
+      title: id,
+      remediation: "",
+      yamlBased: true,
+    }
+  );
+}
+
+export function sortFindings(a: EnrichedFinding, b: EnrichedFinding): number {
+  const sev = SEVERITY_WEIGHT[a.severity] - SEVERITY_WEIGHT[b.severity];
+  if (sev !== 0) return sev;
+  if (a.checkId !== b.checkId) return a.checkId < b.checkId ? -1 : 1;
+  return a.file < b.file ? -1 : a.file > b.file ? 1 : 0;
+}
+
+function byFile(items: EnrichedFinding[]): Map<string, EnrichedFinding[]> {
+  const map = new Map<string, EnrichedFinding[]>();
+  for (const it of [...items].sort((a, b) => (a.file < b.file ? -1 : a.file > b.file ? 1 : 0))) {
+    const list = map.get(it.file) ?? [];
+    list.push(it);
+    map.set(it.file, list);
+  }
+  return map;
+}
+
+function clusterName(m: RuleMeta): string {
+  return m.authority?.[0]?.name ?? "General hardening";
+}
+
+function buildQuickWins(findings: EnrichedFinding[], contents: Map<string, string>, proveOpts: ProveOptions): QuickWinFile[] {
+  const out: QuickWinFile[] = [];
+  for (const [file, group] of byFile(findings)) {
+    const ids = [...new Set(group.map((f) => f.checkId))].sort();
+    const original = contents.get(file);
+    const addressed: RuleMeta[] = [];
+    const needsInput: EnrichedFinding[] = [];
+    let patched = original;
+
+    if (original !== undefined) {
+      for (const id of ids) {
+        const res = proveFix(id, patched ?? original, proveOpts);
+        if (res.applied && res.patched !== undefined) {
+          patched = res.patched;
+          addressed.push(metaFor(id));
+        } else if (res.reason === "needs-input") {
+          needsInput.push(...group.filter((f) => f.checkId === id));
+        }
+        // "noop" (already resolved by a prior fix in the combined patch) is dropped.
+      }
+    } else {
+      for (const f of group) needsInput.push(f);
+    }
+
+    const diff = original !== undefined && patched !== undefined && patched !== original ? unifiedDiff(original, patched) : undefined;
+
+    // Dedupe needs-input by check + entity.
+    const seen = new Set<string>();
+    const deduped = needsInput.filter((f) => {
+      const k = `${f.checkId}:${f.entity ?? ""}`;
+      if (seen.has(k)) return false;
+      seen.add(k);
+      return true;
+    });
+
+    out.push({ file, diff, addressed, needsInput: deduped });
+  }
+  return out;
+}
+
+function buildClusters(findings: EnrichedFinding[]): GuidanceCluster[] {
+  const clusters = new Map<string, EnrichedFinding[]>();
+  for (const f of [...findings].sort(sortFindings)) {
+    const key = clusterName(f.meta);
+    const list = clusters.get(key) ?? [];
+    list.push(f);
+    clusters.set(key, list);
+  }
+  return [...clusters.entries()]
+    .sort((a, b) => (a[0] < b[0] ? -1 : 1))
+    .map(([name, group]) => {
+      const byRule = new Map<string, EnrichedFinding[]>();
+      for (const f of group) {
+        const list = byRule.get(f.checkId) ?? [];
+        list.push(f);
+        byRule.set(f.checkId, list);
+      }
+      return {
+        name,
+        url: group[0].meta.authority?.[0]?.url,
+        rules: [...byRule.values()].map((findings) => ({ meta: findings[0].meta, findings })),
+      };
+    });
+}
+
+export interface BuildModelOptions {
+  files?: Array<{ path: string; content: string }>;
+  resolveSha?: ProveOptions["resolveSha"];
+  resolveDigest?: ProveOptions["resolveDigest"];
+}
+
+/** Build the structured report model from raw findings. */
+export function buildReportModel(findings: AuditFinding[], opts: BuildModelOptions = {}): ReportModel {
+  const enriched: EnrichedFinding[] = findings.map((f) => ({ ...f, meta: metaFor(f.checkId) }));
+  const contents = new Map((opts.files ?? []).map((f) => [f.path, f.content]));
+
+  const mergeWorthy = enriched.filter((f) => f.meta.tier === "merge-worthy");
+  const quickWinFindings = mergeWorthy.filter((f) => f.meta.fixKind === "deterministic");
+  const needsReviewFindings = mergeWorthy.filter((f) => f.meta.fixKind === "guidance");
+
+  // De-noise: drop a report-only finding only when a specific merge-worthy
+  // finding supersedes it on the same entity; keep unrelated hygiene.
+  const mwOnEntity = new Set(mergeWorthy.filter((f) => f.entity).map((f) => `${f.file}:${f.entity}:${f.checkId}`));
+  const reportOnly = enriched.filter((f) => {
+    if (f.meta.tier !== "report-only") return false;
+    const supers = SUPERSEDED_BY[f.checkId];
+    if (supers && f.entity && supers.some((id) => mwOnEntity.has(`${f.file}:${f.entity}:${id}`))) return false;
+    return true;
+  });
+
+  const shown = [...quickWinFindings, ...needsReviewFindings, ...reportOnly];
+  const counts: ReportCounts = {
+    total: shown.length,
+    quickWin: quickWinFindings.length,
+    needsReview: needsReviewFindings.length,
+    reportOnly: reportOnly.length,
+    errors: shown.filter((f) => f.severity === "error").length,
+    warnings: shown.filter((f) => f.severity === "warning").length,
+    infos: shown.filter((f) => f.severity === "info").length,
+  };
+
+  return {
+    counts,
+    quickWins: buildQuickWins(quickWinFindings, contents, { resolveSha: opts.resolveSha, resolveDigest: opts.resolveDigest }),
+    needsReview: buildClusters(needsReviewFindings),
+    reportOnly: [...reportOnly].sort(sortFindings),
+    findings: [...shown].sort(sortFindings),
+  };
+}
+
+/** Build the versioned, machine-readable JSON report (stable contract). */
+export function buildReportJson(findings: AuditFinding[], opts: { snapshot?: AuditSnapshot; toolVersion?: string } = {}): AuditReportJson {
+  const model = buildReportModel(findings);
+  const version = opts.toolVersion ?? opts.snapshot?.toolVersion ?? "0.0.0";
+  return {
+    schemaVersion: REPORT_SCHEMA_VERSION,
+    tool: { name: "chant-audit", version },
+    snapshot: opts.snapshot,
+    summary: model.counts,
+    findings: model.findings.map((f) => ({
+      checkId: f.checkId,
+      severity: f.severity,
+      message: f.message,
+      file: f.file,
+      entity: f.entity,
+      lexicon: f.lexicon,
+      tier: f.meta.tier,
+      fixKind: f.meta.fixKind,
+      title: f.meta.title,
+      remediation: f.meta.remediation,
+      authority: f.meta.authority ?? [],
+      docUrl: ruleDocUrl(f.checkId),
+    })),
+  };
+}

package/src/audit/report.test.ts

@@ -0,0 +1,119 @@
+import { describe, test, expect } from "vitest";
+import { renderMarkdown } from "./report";
+import type { AuditFinding } from "./core";
+
+const CI = `name: CI
+on:
+  pull_request_target:
+permissions: write-all
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+`;
+
+const FINDINGS: AuditFinding[] = [
+  { checkId: "GHA033", severity: "warning", message: "write-all permissions.", file: ".github/workflows/ci.yml", lexicon: "github" },
+  { checkId: "GHA021", severity: "warning", message: "unpinned checkout.", file: ".github/workflows/ci.yml", lexicon: "github", entity: "build" },
+  { checkId: "GHA035", severity: "error", message: "elevated token on pull_request_target.", file: ".github/workflows/ci.yml", lexicon: "github" },
+  { checkId: "GHA018", severity: "warning", message: "pull_request_target checks out PR code.", file: ".github/workflows/ci.yml", lexicon: "github", entity: "build" },
+  { checkId: "GHA022", severity: "info", message: "no timeout.", file: ".github/workflows/ci.yml", lexicon: "github" },
+];
+
+describe("renderMarkdown — reworked structure", () => {
+  test("summary counts by tier and severity", () => {
+    const out = renderMarkdown(FINDINGS, { target: "owner/repo" });
+    expect(out).toContain("Target: owner/repo");
+    expect(out).toContain("5 findings — 2 quick-win, 2 needs-review, 1 report-only (1 error, 3 warning, 1 info).");
+  });
+
+  test("quick wins show a real combined diff when file content is provided", () => {
+    const out = renderMarkdown(FINDINGS, { files: [{ path: ".github/workflows/ci.yml", content: CI }] });
+    expect(out).toContain("## Quick wins (deterministic)");
+    expect(out).toContain("Addresses [GHA033](https://intentius.io/chant/lint-rules/audit-rules/#gha033) (Blanket write-all permissions):");
+    expect(out).toContain("```diff");
+    expect(out).toContain("-permissions: write-all");
+    expect(out).toContain("+permissions:");
+    expect(out).toContain("+  contents: read");
+  });
+
+  test("pin findings without a SHA resolver are listed, not diffed", () => {
+    const out = renderMarkdown(FINDINGS, { files: [{ path: ".github/workflows/ci.yml", content: CI }] });
+    expect(out).toContain("Needs a value before it can be auto-patched:");
+    expect(out).toContain("**[GHA021](https://intentius.io/chant/lint-rules/audit-rules/#gha021)**");
+  });
+
+  test("pin findings are diffed when a SHA resolver is supplied", () => {
+    const sha = "11bd71901bbe5b1630ceea73d27597364c9af683";
+    const out = renderMarkdown(FINDINGS, {
+      files: [{ path: ".github/workflows/ci.yml", content: CI }],
+      resolveSha: () => sha,
+    });
+    expect(out).toContain(`actions/checkout@${sha}`);
+  });
+
+  test("does not list a finding already resolved by the combined patch", () => {
+    const sha = "11bd71901bbe5b1630ceea73d27597364c9af683";
+    const content = "name: CI\non:\n  push:\njobs:\n  build:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n      - uses: acme/deploy-action@v1\n";
+    const findings: AuditFinding[] = [
+      { checkId: "GHA021", severity: "warning", message: "unpinned checkout.", file: ".github/workflows/ci.yml", lexicon: "github", entity: "build" },
+      { checkId: "GHA029", severity: "warning", message: "unpinned acme.", file: ".github/workflows/ci.yml", lexicon: "github", entity: "build" },
+    ];
+    const out = renderMarkdown(findings, { files: [{ path: ".github/workflows/ci.yml", content }], resolveSha: () => sha });
+    // Both actions pinned in one combined diff; neither listed as "needs a value".
+    expect(out).toContain("```diff");
+    expect(out).not.toContain("Needs a value before it can be auto-patched");
+  });
+
+  test("guidance findings cluster by authority", () => {
+    const out = renderMarkdown(FINDINGS);
+    expect(out).toContain("<summary>Needs review (guidance)");
+    // GHA035 and GHA018 both share the pwn-request authority → one cluster.
+    expect(out).toContain("Preventing pwn requests");
+    const clusterIdx = out.indexOf("Preventing pwn requests");
+    const after = out.slice(clusterIdx);
+    expect(after).toContain("**[GHA035](https://intentius.io/chant/lint-rules/audit-rules/#gha035)**");
+    expect(after).toContain("**[GHA018](https://intentius.io/chant/lint-rules/audit-rules/#gha018)**");
+  });
+
+  test("report-only hygiene goes in a collapsible table", () => {
+    const out = renderMarkdown(FINDINGS);
+    expect(out).toContain("<details>");
+    expect(out).toContain("<summary>Report-only (hygiene)");
+    expect(out).toContain("| [GHA022](https://intentius.io/chant/lint-rules/audit-rules/#gha022) |");
+  });
+
+  test("suppresses a report-only finding on an entity already flagged merge-worthy", () => {
+    const findings: AuditFinding[] = [
+      { checkId: "WGL016", severity: "error", message: "hardcoded secret.", file: ".gitlab-ci.yml", lexicon: "gitlab", entity: "DB_PASSWORD" },
+      { checkId: "WGL021", severity: "warning", message: "unused variable.", file: ".gitlab-ci.yml", lexicon: "gitlab", entity: "DB_PASSWORD" },
+    ];
+    const out = renderMarkdown(findings);
+    expect(out).toContain("WGL016");
+    expect(out).not.toContain("WGL021"); // suppressed — same entity already flagged
+    expect(out).toContain("1 finding — ");
+  });
+
+  test("does not suppress unrelated hygiene sharing a job entity", () => {
+    const findings: AuditFinding[] = [
+      { checkId: "GHA021", severity: "warning", message: "unpinned.", file: ".github/workflows/ci.yml", lexicon: "github", entity: "build" },
+      { checkId: "GHA022", severity: "info", message: "no timeout.", file: ".github/workflows/ci.yml", lexicon: "github", entity: "build" },
+    ];
+    const out = renderMarkdown(findings);
+    expect(out).toContain("GHA022"); // unrelated hygiene on the same job is kept
+  });
+
+  test("clean report when there are no findings", () => {
+    const out = renderMarkdown([]);
+    expect(out).toContain("No issues found.");
+    expect(out).not.toContain("Quick wins");
+  });
+
+  test("omits empty sections", () => {
+    const onlyGuidance = renderMarkdown([FINDINGS[2]]); // GHA035 only
+    expect(onlyGuidance).toContain("<summary>Needs review (guidance)");
+    expect(onlyGuidance).not.toContain("## Quick wins");
+    expect(onlyGuidance).not.toContain("Report-only");
+  });
+});