@intentius/chant 0.4.0 → 0.6.0

package/src/audit/proof.test.ts

@@ -0,0 +1,141 @@
+import { describe, test, expect } from "vitest";
+import { proveFix, unifiedDiff, extractUnpinnedImages } from "./proof";
+
+const WF = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: npm ci
+`;
+
+const WF_WRITE_ALL = `name: CI
+on:
+  push:
+permissions: write-all
+jobs:
+  build:
+    runs-on: ubuntu-latest
+`;
+
+describe("proveFix — pin action (GHA021/GHA029)", () => {
+  test("pins an unpinned action and the diff shows only that line", () => {
+    const sha = "11bd71901bbe5b1630ceea73d27597364c9af683";
+    const res = proveFix("GHA021", WF, { resolveSha: () => sha });
+    expect(res.applied).toBe(true);
+    expect(res.patched).toContain(`actions/checkout@${sha}  # v4`);
+    // Only the uses line changes: exactly one - and one + in the diff.
+    const removed = res.diff!.split("\n").filter((l) => l.startsWith("-") && !l.startsWith("---"));
+    const added = res.diff!.split("\n").filter((l) => l.startsWith("+") && !l.startsWith("+++"));
+    expect(removed).toEqual(["-      - uses: actions/checkout@v4"]);
+    expect(added).toEqual([`+      - uses: actions/checkout@${sha}  # v4`]);
+  });
+
+  test("needs a sha when none can be resolved", () => {
+    const res = proveFix("GHA021", WF, { resolveSha: () => undefined });
+    expect(res.applied).toBe(false);
+    expect(res.note).toMatch(/SHA is required/i);
+  });
+
+  test("no-op when the action is already pinned", () => {
+    const pinned = WF.replace("@v4", "@11bd71901bbe5b1630ceea73d27597364c9af683");
+    const res = proveFix("GHA021", pinned, { resolveSha: () => "x" });
+    expect(res.applied).toBe(false);
+    expect(res.note).toMatch(/no-op/i);
+  });
+});
+
+describe("proveFix — permissions", () => {
+  test("adds a least-privilege block additively (GHA017)", () => {
+    const res = proveFix("GHA017", WF);
+    expect(res.applied).toBe(true);
+    expect(res.patched).toContain("permissions:\n  contents: read");
+    // Purely additive: no removed lines.
+    const removed = res.diff!.split("\n").filter((l) => l.startsWith("-") && !l.startsWith("---"));
+    expect(removed).toEqual([]);
+    const added = res.diff!.split("\n").filter((l) => l.startsWith("+") && !l.startsWith("+++"));
+    expect(added).toEqual(["+permissions:", "+  contents: read"]);
+  });
+
+  test("no-op when a permissions block already exists", () => {
+    const withPerms = WF.replace("jobs:", "permissions:\n  contents: read\njobs:");
+    const res = proveFix("GHA017", withPerms);
+    expect(res.applied).toBe(false);
+  });
+
+  test("narrows write-all (GHA033)", () => {
+    const res = proveFix("GHA033", WF_WRITE_ALL);
+    expect(res.applied).toBe(true);
+    expect(res.patched).toContain("permissions:\n  contents: read");
+    expect(res.patched).not.toContain("write-all");
+  });
+});
+
+describe("proveFix — pin image digest (GHA030/WGL031)", () => {
+  const WF_IMG = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    container:
+      image: node:20
+`;
+  const digest = "sha256:" + "a".repeat(64);
+
+  test("pins an image to a digest and the diff shows only that line", () => {
+    const res = proveFix("GHA030", WF_IMG, { resolveDigest: () => digest });
+    expect(res.applied).toBe(true);
+    expect(res.patched).toContain(`image: node:20@${digest}`);
+    const removed = res.diff!.split("\n").filter((l) => l.startsWith("-") && !l.startsWith("---"));
+    const added = res.diff!.split("\n").filter((l) => l.startsWith("+") && !l.startsWith("+++"));
+    expect(removed).toEqual(["-      image: node:20"]);
+    expect(added).toEqual([`+      image: node:20@${digest}`]);
+  });
+
+  test("needs a value when no digest can be resolved", () => {
+    const res = proveFix("GHA030", WF_IMG, { resolveDigest: () => undefined });
+    expect(res.applied).toBe(false);
+    expect(res.reason).toBe("needs-input");
+  });
+
+  test("WGL031 uses the same image-pin fix", () => {
+    const gl = "build:\n  image: python:3.12\n  script:\n    - echo hi\n";
+    const res = proveFix("WGL031", gl, { resolveDigest: () => digest });
+    expect(res.applied).toBe(true);
+    expect(res.patched).toContain(`image: python:3.12@${digest}`);
+  });
+
+  test("extractUnpinnedImages finds pinnable images, skips digested/variable", () => {
+    const content = "image: node:20\nimage: foo@sha256:" + "b".repeat(64) + "\nimage: $REG/x:1\n";
+    expect(extractUnpinnedImages(content)).toEqual(["node:20"]);
+  });
+});
+
+describe("proveFix — guidance findings are not auto-fixed", () => {
+  test("a guidance rule returns remediation, not a patch", () => {
+    const res = proveFix("GHA036", WF); // script injection — guidance
+    expect(res.applied).toBe(false);
+    expect(res.patched).toBeUndefined();
+    expect(res.note && res.note.length).toBeGreaterThan(0);
+  });
+});
+
+describe("unifiedDiff", () => {
+  test("identical input produces an empty diff", () => {
+    expect(unifiedDiff(WF, WF)).toBe("");
+  });
+
+  test("emits a hunk header and the changed lines", () => {
+    const a = "a\nb\nc\n";
+    const b = "a\nB\nc\n";
+    const diff = unifiedDiff(a, b);
+    expect(diff).toContain("@@");
+    expect(diff).toContain("-b");
+    expect(diff).toContain("+B");
+    expect(diff).toContain(" a");
+  });
+});

package/src/audit/proof.ts

@@ -0,0 +1,290 @@
+/**
+ * Proof of minimal change — for a deterministic (fixKind: "deterministic")
+ * finding, produce a minimal patched YAML + unified diff so a PR can show it
+ * changes exactly the flagged line and nothing else.
+ *
+ * No LLM, no API key — purely mechanical text edits. Findings that need
+ * judgment (fixKind: "guidance") are NOT auto-fixed here; they return
+ * `applied: false` with the catalog remediation as guidance. Any LLM-assisted
+ * apply of a guidance fix is a separate, optional, local concern.
+ *
+ * Edits are applied directly to the YAML text (not via a model round-trip), so
+ * the patched output differs only where intended — the diff proves it.
+ */
+
+import { RULE_CATALOG } from "./catalog";
+
+export interface ProveOptions {
+  /** Resolve an action ref (e.g. "actions/checkout@v4") to a 40-char SHA. */
+  resolveSha?: (action: string, ref: string) => string | undefined;
+  /** Resolve a container image (e.g. "node:20") to a "sha256:..." digest. */
+  resolveDigest?: (image: string) => string | undefined;
+}
+
+export interface ProofResult {
+  checkId: string;
+  /** True when a deterministic fix was produced. */
+  applied: boolean;
+  /** Full patched content (only when applied). */
+  patched?: string;
+  /** Unified diff of the change (only when applied). */
+  diff?: string;
+  /** Guidance/explanation when not applied (guidance fix, no-op, or needs-sha). */
+  note?: string;
+  /**
+   * Why the result is what it is:
+   *  - applied: a fix was produced
+   *  - noop: nothing to fix (issue absent, or already resolved by a prior fix)
+   *  - needs-input: deterministic but blocked on external input (e.g. a SHA)
+   *  - guidance: not auto-fixable; needs human judgement
+   */
+  reason: "applied" | "noop" | "needs-input" | "guidance";
+}
+
+const SHA_RE = /^[0-9a-f]{40}$/;
+const USES_RE = /^(\s*-?\s*uses:\s*)([^@\s'"]+)@([^\s'"#]+)(.*)$/;
+const IMAGE_RE = /^(\s*image:\s*)(["']?)([^\s"'#]+)\2(.*)$/;
+
+function notApplied(checkId: string, reason: "noop" | "needs-input" | "guidance", note: string): ProofResult {
+  return { checkId, applied: false, reason, note };
+}
+
+/** Extract unpinned `uses: action@ref` references (deduped) from workflow YAML. */
+export function extractUnpinnedActions(content: string): Array<{ action: string; ref: string }> {
+  const seen = new Set<string>();
+  const out: Array<{ action: string; ref: string }> = [];
+  for (const line of content.split("\n")) {
+    const m = line.match(USES_RE);
+    if (!m) continue;
+    const [, , action, ref] = m;
+    if (SHA_RE.test(ref)) continue;
+    const key = `${action}@${ref}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push({ action, ref });
+  }
+  return out;
+}
+
+/** Pin unpinned `uses: action@ref` lines to a SHA. */
+function pinActions(content: string, opts: ProveOptions): { patched: string; changed: boolean; needsSha: boolean } {
+  const lines = content.split("\n");
+  let changed = false;
+  let needsSha = false;
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(USES_RE);
+    if (!m) continue;
+    const [, prefix, action, ref, rest] = m;
+    if (SHA_RE.test(ref)) continue; // already pinned
+    const sha = opts.resolveSha?.(action, ref);
+    if (!sha) {
+      needsSha = true;
+      continue;
+    }
+    lines[i] = `${prefix}${action}@${sha}  # ${ref}${rest.replace(/\s*#.*$/, "")}`;
+    changed = true;
+  }
+  return { patched: lines.join("\n"), changed, needsSha };
+}
+
+/** A container image is unpinnable here if it lacks a digest and isn't a variable. */
+function isPinnableImage(ref: string): boolean {
+  return !ref.includes("@sha256:") && !ref.includes("$");
+}
+
+/** Extract unpinned `image:` references (deduped) from CI YAML. */
+export function extractUnpinnedImages(content: string): string[] {
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const line of content.split("\n")) {
+    const m = line.match(IMAGE_RE);
+    if (!m) continue;
+    const ref = m[3];
+    if (!isPinnableImage(ref) || seen.has(ref)) continue;
+    seen.add(ref);
+    out.push(ref);
+  }
+  return out;
+}
+
+/** Pin unpinned `image:` references to a digest via the resolver. */
+function pinImages(content: string, opts: ProveOptions): { patched: string; changed: boolean; needsValue: boolean } {
+  const lines = content.split("\n");
+  let changed = false;
+  let needsValue = false;
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(IMAGE_RE);
+    if (!m) continue;
+    const [, prefix, , ref, rest] = m;
+    if (!isPinnableImage(ref)) continue;
+    const digest = opts.resolveDigest?.(ref);
+    if (!digest) {
+      needsValue = true;
+      continue;
+    }
+    lines[i] = `${prefix}${ref}@${digest}${rest.replace(/\s*#.*$/, "")}`;
+    changed = true;
+  }
+  return { patched: lines.join("\n"), changed, needsValue };
+}
+
+/** Insert a least-privilege top-level permissions block if absent. */
+function addPermissions(content: string): { patched: string; changed: boolean } {
+  if (/^permissions:/m.test(content)) return { patched: content, changed: false };
+  const lines = content.split("\n");
+  const jobsIdx = lines.findIndex((l) => /^jobs:\s*$/.test(l));
+  if (jobsIdx === -1) return { patched: content, changed: false };
+  lines.splice(jobsIdx, 0, "permissions:", "  contents: read");
+  return { patched: lines.join("\n"), changed: true };
+}
+
+/** Replace a top-level `permissions: write-all` with a least-privilege block. */
+function narrowWriteAll(content: string): { patched: string; changed: boolean } {
+  const re = /^permissions:[ \t]+write-all[ \t]*$/m;
+  if (!re.test(content)) return { patched: content, changed: false };
+  return { patched: content.replace(re, "permissions:\n  contents: read"), changed: true };
+}
+
+/**
+ * Produce a deterministic fix + diff for a finding, if one is mechanical.
+ * Returns `applied: false` with guidance for non-deterministic findings.
+ */
+export function proveFix(checkId: string, content: string, opts: ProveOptions = {}): ProofResult {
+  const cat = RULE_CATALOG[checkId];
+  if (cat && cat.fixKind !== "deterministic") {
+    return notApplied(checkId, "guidance", cat.remediation || "Manual fix required.");
+  }
+
+  let result: { patched: string; changed: boolean; needsSha?: boolean };
+  switch (checkId) {
+    case "GHA021":
+    case "GHA029":
+      result = pinActions(content, opts);
+      if (!result.changed && (result as { needsSha?: boolean }).needsSha) {
+        return notApplied(checkId, "needs-input", "A commit SHA is required to pin; resolve it (e.g. via the fetch layer) and re-run.");
+      }
+      break;
+    case "GHA030":
+    case "WGL031": {
+      const r = pinImages(content, opts);
+      if (!r.changed && r.needsValue) {
+        return notApplied(checkId, "needs-input", "A registry digest is required to pin the image; resolve it (e.g. via the fetch layer) and re-run.");
+      }
+      result = r;
+      break;
+    }
+    case "GHA017":
+      result = addPermissions(content);
+      break;
+    case "GHA033":
+      result = narrowWriteAll(content);
+      break;
+    default:
+      return notApplied(checkId, "needs-input", cat?.remediation || "No deterministic fix implemented for this rule yet.");
+  }
+
+  if (!result.changed) {
+    return notApplied(checkId, "noop", "Nothing to fix — the issue is not present (no-op).");
+  }
+  return {
+    checkId,
+    applied: true,
+    reason: "applied",
+    patched: result.patched,
+    diff: unifiedDiff(content, result.patched),
+  };
+}
+
+// ── Minimal line-based unified diff ──────────────────────────────────
+
+type Op = { type: "eq" | "del" | "add"; line: string };
+
+/** LCS-based line diff. */
+function diffOps(a: string[], b: string[]): Op[] {
+  const n = a.length;
+  const m = b.length;
+  const lcs: number[][] = Array.from({ length: n + 1 }, () => new Array(m + 1).fill(0));
+  for (let i = n - 1; i >= 0; i--) {
+    for (let j = m - 1; j >= 0; j--) {
+      lcs[i][j] = a[i] === b[j] ? lcs[i + 1][j + 1] + 1 : Math.max(lcs[i + 1][j], lcs[i][j + 1]);
+    }
+  }
+  const ops: Op[] = [];
+  let i = 0;
+  let j = 0;
+  while (i < n && j < m) {
+    if (a[i] === b[j]) {
+      ops.push({ type: "eq", line: a[i] });
+      i++;
+      j++;
+    } else if (lcs[i + 1][j] >= lcs[i][j + 1]) {
+      ops.push({ type: "del", line: a[i] });
+      i++;
+    } else {
+      ops.push({ type: "add", line: b[j] });
+      j++;
+    }
+  }
+  while (i < n) ops.push({ type: "del", line: a[i++] });
+  while (j < m) ops.push({ type: "add", line: b[j++] });
+  return ops;
+}
+
+/** Render a unified diff with up to `context` equal lines around changes. */
+export function unifiedDiff(oldStr: string, newStr: string, context = 3): string {
+  const a = oldStr.split("\n");
+  const b = newStr.split("\n");
+  const ops = diffOps(a, b);
+
+  // Mark which op indexes are within `context` of a change.
+  const keep = new Array(ops.length).fill(false);
+  for (let k = 0; k < ops.length; k++) {
+    if (ops[k].type !== "eq") {
+      for (let d = -context; d <= context; d++) {
+        const idx = k + d;
+        if (idx >= 0 && idx < ops.length) keep[idx] = true;
+      }
+    }
+  }
+
+  const lines: string[] = [];
+  let oldLine = 1;
+  let newLine = 1;
+  let k = 0;
+  while (k < ops.length) {
+    if (!keep[k]) {
+      if (ops[k].type !== "add") oldLine++;
+      if (ops[k].type !== "del") newLine++;
+      k++;
+      continue;
+    }
+    // Start of a hunk.
+    const hunk: string[] = [];
+    const oldStart = oldLine;
+    const newStart = newLine;
+    let oldCount = 0;
+    let newCount = 0;
+    while (k < ops.length && keep[k]) {
+      const op = ops[k];
+      if (op.type === "eq") {
+        hunk.push(` ${op.line}`);
+        oldCount++;
+        newCount++;
+        oldLine++;
+        newLine++;
+      } else if (op.type === "del") {
+        hunk.push(`-${op.line}`);
+        oldCount++;
+        oldLine++;
+      } else {
+        hunk.push(`+${op.line}`);
+        newCount++;
+        newLine++;
+      }
+      k++;
+    }
+    lines.push(`@@ -${oldStart},${oldCount} +${newStart},${newCount} @@`);
+    lines.push(...hunk);
+  }
+  return lines.join("\n");
+}

package/src/audit/report-html.test.ts

@@ -0,0 +1,83 @@
+import { describe, test, expect } from "vitest";
+import { renderHtml, type AuditSnapshot } from "./report-html";
+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: "GHA035", severity: "error", message: "elevated token on pull_request_target.", file: ".github/workflows/ci.yml", lexicon: "github" },
+  { checkId: "GHA022", severity: "info", message: "no timeout.", file: ".github/workflows/ci.yml", lexicon: "github" },
+];
+
+const SNAPSHOT: AuditSnapshot = {
+  target: "https://github.com/owner/repo",
+  host: "github.com",
+  repo: "owner/repo",
+  commit: "11bd71901bbe5b1630ceea73d27597364c9af683",
+  files: [".github/workflows/ci.yml"],
+  generatedAt: "2026-06-16T00:00:00.000Z",
+  toolVersion: "0.4.0",
+};
+
+describe("renderHtml", () => {
+  test("produces a self-contained HTML document with sections and snapshot", () => {
+    const html = renderHtml(FINDINGS, { files: [{ path: ".github/workflows/ci.yml", content: CI }], snapshot: SNAPSHOT });
+    expect(html.startsWith("<!doctype html>")).toBe(true);
+    expect(html).toContain("<style>"); // inline CSS, self-contained
+    expect(html).toContain("owner/repo");
+    expect(html).toContain("11bd71901b"); // short commit in snapshot meta
+    expect(html).toContain("Quick wins");
+    expect(html).toContain("Needs review");
+    expect(html).toContain('class="diff"'); // the permissions fix renders as a diff
+    expect(html).toContain("chant 0.4.0");
+  });
+
+  test("embeds the machine-readable JSON report (parseable, escaped)", () => {
+    const html = renderHtml(FINDINGS, { snapshot: SNAPSHOT });
+    const m = html.match(/<script type="application\/json" id="chant-audit-report">(.*?)<\/script>/s);
+    expect(m).not.toBeNull();
+    // No raw "<" can break out of the script element.
+    expect(m![1]).not.toContain("<");
+    const data = JSON.parse(m![1].replace(/\\u003c/g, "<"));
+    expect(data.schemaVersion).toBe("1.0");
+    expect(data.snapshot.commit).toBe(SNAPSHOT.commit);
+    expect(data.findings.length).toBe(3);
+  });
+
+  test("escapes HTML in finding content (no injection)", () => {
+    const evil: AuditFinding[] = [
+      { checkId: "GHA036", severity: "error", message: "<script>alert(1)</script>", file: "a.yml", lexicon: "github" },
+    ];
+    const html = renderHtml(evil);
+    expect(html).not.toContain("<script>alert(1)</script>");
+    expect(html).toContain("&lt;script&gt;");
+  });
+
+  test("applies theme knobs (title, accent)", () => {
+    const html = renderHtml(FINDINGS, { theme: { title: "Acme Security", accent: "#ff0000" } });
+    expect(html).toContain("<title>Acme Security</title>");
+    expect(html).toContain("#ff0000");
+  });
+
+  test("honours a full template override", () => {
+    const html = renderHtml(FINDINGS, { template: "<html>{{title}}::{{body}}</html>", theme: { title: "X" } });
+    expect(html.startsWith("<html>X::")).toBe(true);
+    expect(html).toContain("Quick wins"); // body still rendered
+  });
+
+  test("clean report when no findings", () => {
+    const html = renderHtml([]);
+    expect(html).toContain("No issues found.");
+    expect(html).not.toContain("Quick wins");
+  });
+});