@intentius/chant 0.4.0 → 0.6.0

package/src/audit/report.ts

@@ -0,0 +1,121 @@
+/**
+ * Markdown report generator (the "minimized" mode) — renders the shared
+ * report model as Markdown that pastes cleanly into a PR or issue.
+ *
+ *  - **Quick wins (deterministic)** lead, per file, with one combined unified
+ *    diff so the report doubles as a ready-to-apply patch.
+ *  - **Needs review (guidance)** and **Report-only (hygiene)** collapse into
+ *    `<details>` so a pasted report opens on the actionable fix.
+ *
+ * For a presentable/branded report, see `renderHtml` (report-html.ts).
+ */
+
+import type { AuditFinding } from "./core";
+import { ruleDocUrl } from "./catalog";
+import type { ProveOptions } from "./proof";
+import { buildReportModel, type EnrichedFinding, type GuidanceCluster, type QuickWinFile } from "./report-model";
+
+/** A rule id as a Markdown link to its reference entry. */
+function ruleLink(id: string): string {
+  return `[${id}](${ruleDocUrl(id)})`;
+}
+
+export interface RenderOptions {
+  /** Repo URL or path shown in the header. */
+  target?: string;
+  /** Audited file contents (path → YAML), enabling inline fix diffs. */
+  files?: Array<{ path: string; content: string }>;
+  /** Resolve an action ref to a SHA so pin fixes can be diffed. */
+  resolveSha?: ProveOptions["resolveSha"];
+  /** Resolve a container image to a digest so image-pin fixes can be diffed. */
+  resolveDigest?: ProveOptions["resolveDigest"];
+  /** Coverage caveats shown near the top (e.g. unresolved GitLab includes). */
+  notes?: string[];
+}
+
+function escapeCell(s: string): string {
+  return s.replace(/\|/g, "\\|").replace(/\n/g, " ").trim();
+}
+
+function renderQuickWins(files: QuickWinFile[]): string[] {
+  const lines: string[] = ["## Quick wins (deterministic)", "", "Safe mechanical fixes — the diff changes only the flagged lines.", ""];
+  for (const qw of files) {
+    lines.push(`### \`${qw.file}\``);
+    if (qw.diff) {
+      const labels = qw.addressed.map((m) => `${ruleLink(m.id)} (${m.title})`).join(", ");
+      lines.push("", `Addresses ${labels}:`, "", "```diff", qw.diff, "```");
+    }
+    if (qw.needsInput.length > 0) {
+      lines.push("", "Needs a value before it can be auto-patched:");
+      for (const f of qw.needsInput) {
+        const where = f.entity ? ` (\`${f.entity}\`)` : "";
+        lines.push(`- **${ruleLink(f.checkId)}**${where} — ${f.meta.remediation}`);
+      }
+    }
+    lines.push("");
+  }
+  return lines;
+}
+
+function renderNeedsReview(clusters: GuidanceCluster[]): string[] {
+  const lines: string[] = ["These need a judgement call — remediation guidance, not an auto-fix.", ""];
+  for (const cluster of clusters) {
+    lines.push(`### ${cluster.url ? `[${cluster.name}](${cluster.url})` : cluster.name}`, "");
+    for (const { meta, findings } of cluster.rules) {
+      lines.push(`- **${ruleLink(meta.id)}** — ${meta.title} (${findings[0].severity}). ${meta.remediation}`);
+      for (const f of findings) {
+        const where = f.entity ? `\`${f.file}\` (\`${f.entity}\`)` : `\`${f.file}\``;
+        lines.push(`  - ${where} — ${escapeCell(f.message)}`);
+      }
+    }
+    lines.push("");
+  }
+  return lines;
+}
+
+function renderReportOnly(findings: EnrichedFinding[]): string[] {
+  const lines: string[] = ["", "| Rule | Title | File | Detail |", "| --- | --- | --- | --- |"];
+  for (const f of findings) {
+    lines.push(`| ${ruleLink(f.checkId)} | ${escapeCell(f.meta.title)} | \`${f.file}\` | ${escapeCell(f.message)} |`);
+  }
+  lines.push("");
+  return lines;
+}
+
+/** Render an audit report as Markdown. */
+export function renderMarkdown(findings: AuditFinding[], opts: RenderOptions = {}): string {
+  const model = buildReportModel(findings, opts);
+  const { counts } = model;
+
+  const lines: string[] = ["# CI security audit"];
+  if (opts.target) lines.push("", `Target: ${opts.target}`);
+  lines.push("");
+  for (const note of opts.notes ?? []) lines.push(`> Note: ${note}`, "");
+
+  if (counts.total === 0) {
+    lines.push("No issues found.", "", "---", "Generated by [chant audit](https://intentius.io/chant/cli/audit/).", "");
+    return lines.join("\n");
+  }
+
+  lines.push(
+    `${counts.total} finding${counts.total === 1 ? "" : "s"} — ` +
+      `${counts.quickWin} quick-win, ${counts.needsReview} needs-review, ${counts.reportOnly} report-only ` +
+      `(${counts.errors} error, ${counts.warnings} warning, ${counts.infos} info).`,
+    "",
+  );
+
+  if (model.quickWins.length > 0) lines.push(...renderQuickWins(model.quickWins));
+  if (model.needsReview.length > 0) {
+    lines.push("<details>", `<summary>Needs review (guidance) — ${counts.needsReview}</summary>`, "");
+    lines.push(...renderNeedsReview(model.needsReview));
+    lines.push("</details>", "");
+  }
+  if (model.reportOnly.length > 0) {
+    lines.push("<details>", `<summary>Report-only (hygiene) — ${counts.reportOnly}</summary>`, "");
+    lines.push(...renderReportOnly(model.reportOnly));
+    lines.push("</details>", "");
+  }
+
+  lines.push("---", "Generated by [chant audit](https://intentius.io/chant/cli/audit/).", "");
+  return lines.join("\n");
+}

package/src/audit/rules-doc.test.ts

@@ -0,0 +1,23 @@
+import { describe, test, expect } from "vitest";
+import { readFileSync } from "fs";
+import { fileURLToPath } from "url";
+import { renderRulesReference } from "./rules-doc";
+import { RULE_CATALOG, ruleDocUrl } from "./catalog";
+
+const PAGE = fileURLToPath(new URL("../../../../docs/src/content/docs/lint-rules/audit-rules.mdx", import.meta.url));
+
+describe("audit rules reference", () => {
+  test("committed page is in sync with the catalog (regenerate if this fails)", () => {
+    const committed = readFileSync(PAGE, "utf-8");
+    expect(committed).toBe(renderRulesReference());
+  });
+
+  test("every rule has an anchor reachable from ruleDocUrl", () => {
+    const page = renderRulesReference();
+    for (const id of Object.keys(RULE_CATALOG)) {
+      // `### GHA033` → Starlight slug `#gha033`, which ruleDocUrl targets.
+      expect(page).toContain(`### ${id}`);
+      expect(ruleDocUrl(id)).toBe(`https://intentius.io/chant/lint-rules/audit-rules/#${id.toLowerCase()}`);
+    }
+  });
+});

package/src/audit/rules-doc.ts

@@ -0,0 +1,48 @@
+/**
+ * Generator for the audit rules reference docs page. The page is derived from
+ * RULE_CATALOG so report rule-id links always have a target, and a sync test
+ * (rules-doc.test.ts) keeps the committed page in step with the catalog.
+ *
+ * Each rule gets an `### <ID>` heading, which Starlight slugifies to `#<id>`
+ * (lowercased) — the anchor `ruleDocUrl()` links to.
+ */
+
+import { RULE_CATALOG, type RuleMeta } from "./catalog";
+
+const GROUPS: Array<{ heading: string; prefixes: string[]; blurb: string }> = [
+  { heading: "GitHub Actions (GHA)", prefixes: ["GHA"], blurb: "Also applied to Forgejo workflows, which are GitHub-dialect." },
+  { heading: "GitLab CI (WGL)", prefixes: ["WGL"], blurb: "" },
+  { heading: "Forgejo (WFJ)", prefixes: ["WFJ"], blurb: "" },
+  { heading: "Kubernetes (WK8 / ARGO)", prefixes: ["WK8", "ARGO"], blurb: "Run against Kubernetes manifests." },
+  { heading: "Docker (DKRD)", prefixes: ["DKRD"], blurb: "Run against Dockerfiles and Compose files." },
+];
+
+function ruleBlock(m: RuleMeta): string {
+  const tags = `${m.tier} · ${m.fixKind}`;
+  const authority = m.authority?.length
+    ? `\n\nAuthority: ${m.authority.map((a) => `[${a.name}](${a.url})`).join(" · ")}`
+    : "";
+  return `### ${m.id}\n\n**${m.title}** — ${tags}\n\n${m.remediation}${authority}`;
+}
+
+/** Render the full audit rules reference page (frontmatter + body). */
+export function renderRulesReference(): string {
+  const ids = Object.keys(RULE_CATALOG).sort();
+  const sections = GROUPS.map(({ heading, prefixes, blurb }) => {
+    const blocks = ids.filter((id) => prefixes.some((p) => id.startsWith(p))).map((id) => ruleBlock(RULE_CATALOG[id]));
+    if (blocks.length === 0) return "";
+    return `## ${heading}\n${blurb ? `\n${blurb}\n` : ""}\n${blocks.join("\n\n")}`;
+  }).filter(Boolean);
+
+  return `---
+title: Audit rules reference
+description: Every rule chant audit can report, with its tier, fix kind, and remediation.
+---
+
+This is the reference for every rule [\`chant audit\`](/chant/cli/audit/) can report. Each finding in a report links to its rule here.
+
+Each rule is tagged with its **tier** — \`merge-worthy\` (a security or correctness issue worth a PR) or \`report-only\` (hygiene) — and its **fix kind** — \`deterministic\` (a safe mechanical fix the report can apply as a diff) or \`guidance\` (needs a judgement call).
+
+${sections.join("\n\n")}
+`;
+}

package/src/cli/commands/__fixtures__/audit-docker/app/Dockerfile

@@ -0,0 +1,4 @@
+FROM node:20
+RUN apt-get update && apt-get install -y curl
+COPY . /app
+CMD ["node", "server.js"]

package/src/cli/commands/__fixtures__/audit-docker/docker-compose.yml

@@ -0,0 +1,5 @@
+services:
+  web:
+    image: myapp:latest
+    ports:
+      - "22:22"

package/src/cli/commands/__fixtures__/audit-k8s/manifests/deploy.yaml

@@ -0,0 +1,18 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: web
+spec:
+  selector:
+    matchLabels:
+      app: web
+  template:
+    metadata:
+      labels:
+        app: web
+    spec:
+      containers:
+        - name: web
+          image: nginx:latest
+          securityContext:
+            privileged: true

package/src/cli/commands/__fixtures__/audit-repo/.github/workflows/ci.yml

@@ -0,0 +1,11 @@
+name: CI
+on:
+  push:
+permissions: write-all
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: acme/deploy-action@v1
+      - run: npm ci

package/src/cli/commands/audit.test.ts

@@ -0,0 +1,201 @@
+import { describe, test, expect } from "vitest";
+import { fileURLToPath } from "url";
+import { auditCommand, discoverCiFiles, discoverManifests, discoverDocker, tokenForHost, coverageNotes } from "./audit";
+import { MissingLexiconError, type AuditInput } from "../../audit/core";
+import { readFileSync, existsSync, rmSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+
+const REPO = fileURLToPath(new URL("./__fixtures__/audit-repo", import.meta.url));
+
+describe("auditCommand", () => {
+  test("selects a host-specific token (no cross-host leakage)", () => {
+    const env = { GITHUB_TOKEN: "gh", GITLAB_TOKEN: "gl", CODEBERG_TOKEN: "cb" } as unknown as NodeJS.ProcessEnv;
+    expect(tokenForHost("https://github.com/o/r", env)).toBe("gh");
+    expect(tokenForHost("https://gitlab.com/o/r", env)).toBe("gl");
+    expect(tokenForHost("https://codeberg.org/o/r", env)).toBe("cb");
+    // A GitHub token is never offered to other hosts.
+    const onlyGh = { GITHUB_TOKEN: "gh" } as unknown as NodeJS.ProcessEnv;
+    expect(tokenForHost("https://gitlab.com/o/r", onlyGh)).toBeUndefined();
+    expect(tokenForHost("https://codeberg.org/o/r", onlyGh)).toBeUndefined();
+  });
+
+  test("coverageNotes flags unresolved GitLab includes", () => {
+    const withInc: AuditInput[] = [{ path: ".gitlab-ci.yml", content: "include:\n  - local: a.yml\nbuild:\n  script: [echo]\n", lexicon: "gitlab" }];
+    expect(coverageNotes(withInc)[0]).toMatch(/include:/);
+    const without: AuditInput[] = [{ path: ".gitlab-ci.yml", content: "build:\n  script: [echo]\n", lexicon: "gitlab" }];
+    expect(coverageNotes(without)).toEqual([]);
+    // github files never produce the gitlab include note
+    const gh: AuditInput[] = [{ path: ".github/workflows/ci.yml", content: "on: push\n", lexicon: "github" }];
+    expect(coverageNotes(gh)).toEqual([]);
+  });
+
+  test("discovers and audits Kubernetes manifests", async () => {
+    const repo = fileURLToPath(new URL("./__fixtures__/audit-k8s", import.meta.url));
+    const files = discoverManifests(repo);
+    expect(files.map((f) => f.path)).toContain("manifests/deploy.yaml");
+    expect(files.every((f) => f.lexicon === "k8s")).toBe(true);
+
+    const result = await auditCommand({ path: repo, format: "stylish" });
+    expect(result.success).toBe(true);
+    const ids = new Set(result.findings.map((f) => f.checkId));
+    expect(ids).toContain("WK8202"); // privileged container
+    expect(ids).toContain("WK8006"); // :latest image
+  });
+
+  test("discovers and audits Docker artifacts (nested Dockerfile + compose)", async () => {
+    const repo = fileURLToPath(new URL("./__fixtures__/audit-docker", import.meta.url));
+    const files = discoverDocker(repo);
+    const paths = files.map((f) => f.path).sort();
+    expect(paths).toContain("app/Dockerfile");
+    expect(paths).toContain("docker-compose.yml");
+
+    const result = await auditCommand({ path: repo, format: "stylish" });
+    expect(result.success).toBe(true);
+    const ids = new Set(result.findings.map((f) => f.checkId));
+    expect(ids).toContain("DKRD012"); // Dockerfile has no USER (nested — basename-key fix)
+    expect(ids).toContain("DKRD010"); // apt-get without --no-install-recommends
+    expect(ids).toContain("DKRD003"); // compose exposes SSH port 22
+  });
+
+  test("discovers CI files under a repo root", () => {
+    const files = discoverCiFiles(REPO);
+    expect(files.map((f) => f.path)).toContain(".github/workflows/ci.yml");
+    expect(files.every((f) => f.lexicon === "github")).toBe(true);
+  });
+
+  test("reports merge-worthy findings on the fixture repo", async () => {
+    const result = await auditCommand({ path: REPO, format: "stylish" });
+    expect(result.success).toBe(true);
+    const ids = new Set(result.findings.map((f) => f.checkId));
+    expect(ids).toContain("GHA033");
+    expect(ids).toContain("GHA021");
+    expect(result.output).toContain("Merge-worthy:");
+  });
+
+  test("--json emits the versioned envelope with snapshot, summary, findings", async () => {
+    const result = await auditCommand({ path: REPO, format: "json", toolVersion: "0.4.0" });
+    const parsed = JSON.parse(result.output);
+    expect(parsed.schemaVersion).toBe("1.0");
+    expect(parsed.tool).toEqual({ name: "chant-audit", version: "0.4.0" });
+    expect(parsed.snapshot.files).toContain(".github/workflows/ci.yml");
+    expect(parsed.snapshot.toolVersion).toBe("0.4.0");
+    expect(parsed.summary.total).toBeGreaterThan(0);
+    expect(Array.isArray(parsed.findings)).toBe(true);
+    // Each finding carries its classification, so consumers can filter.
+    const f = parsed.findings.find((x: { checkId: string }) => x.checkId === "GHA033");
+    expect(f.tier).toBe("merge-worthy");
+    expect(f.fixKind).toBe("deterministic");
+    expect(Array.isArray(f.authority)).toBe(true);
+  });
+
+  test("--fail-on merge-worthy exits nonzero when merge-worthy findings exist", async () => {
+    const fail = await auditCommand({ path: REPO, failOn: "merge-worthy" });
+    expect(fail.exitCode).toBe(1);
+    const none = await auditCommand({ path: REPO, failOn: "none" });
+    expect(none.exitCode).toBe(0);
+  });
+
+  test("--tier merge-worthy filters out report-only findings", async () => {
+    const all = await auditCommand({ path: REPO, tier: "all" });
+    const mw = await auditCommand({ path: REPO, tier: "merge-worthy" });
+    expect(mw.findings.length).toBeLessThanOrEqual(all.findings.length);
+    expect(mw.findings.some((f) => f.checkId === "GHA022")).toBe(false); // report-only
+  });
+
+  test("writes the report to --output instead of returning it for stdout", async () => {
+    const out = join(tmpdir(), `chant-audit-test-${process.pid}.md`);
+    if (existsSync(out)) rmSync(out);
+    const result = await auditCommand({ path: REPO, format: "markdown", output: out });
+    expect(result.success).toBe(true);
+    expect(result.wroteTo).toBe(out);
+    expect(existsSync(out)).toBe(true);
+    expect(readFileSync(out, "utf-8")).toContain("# CI security audit");
+    rmSync(out);
+  });
+
+  test("surfaces a friendly error when a lexicon package is missing", async () => {
+    const result = await auditCommand({
+      path: REPO,
+      checksProvider: async () => {
+        throw new MissingLexiconError("Missing lexicon package needed to audit github workflows. Install it with: npm i @intentius/chant-lexicon-github");
+      },
+    });
+    expect(result.success).toBe(false);
+    expect(result.exitCode).toBe(1);
+    expect(result.error).toMatch(/npm i @intentius\/chant-lexicon-github/);
+  });
+
+  test("a path with no CI files succeeds with a clear message", async () => {
+    const tmp = join(tmpdir(), `chant-audit-empty-${process.pid}`);
+    const { mkdirSync } = await import("fs");
+    mkdirSync(tmp, { recursive: true });
+    const result = await auditCommand({ path: tmp });
+    expect(result.success).toBe(true);
+    expect(result.exitCode).toBe(0);
+    expect(result.output).toContain("No CI files found");
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  test("audits a remote repo URL via injected fetch", async () => {
+    const b64 = (s: string) => Buffer.from(s, "utf-8").toString("base64");
+    const yaml = "name: CI\non:\n  push:\npermissions: write-all\njobs:\n  build:\n    runs-on: ubuntu-latest\n";
+    const impl = (async (url: string | URL | Request) => {
+      const u = String(url);
+      if (u.includes("/contents/.github/workflows/ci.yml")) {
+        return new Response(JSON.stringify({ name: "ci.yml", path: ".github/workflows/ci.yml", type: "file", content: b64(yaml), encoding: "base64" }), { status: 200 });
+      }
+      if (u.includes("/contents/.github/workflows")) {
+        return new Response(JSON.stringify([{ name: "ci.yml", path: ".github/workflows/ci.yml", type: "file", size: 100 }]), { status: 200 });
+      }
+      return new Response("not found", { status: 404 });
+    }) as unknown as typeof fetch;
+
+    const result = await auditCommand({ path: "https://github.com/acme/widgets", fetchImpl: impl });
+    expect(result.success).toBe(true);
+    expect(result.scanned).toContain(".github/workflows/ci.yml");
+    expect(result.findings.some((f) => f.checkId === "GHA033")).toBe(true);
+  });
+
+  test("remote markdown audit inlines a pin diff using resolved SHAs", async () => {
+    const b64 = (s: string) => Buffer.from(s, "utf-8").toString("base64");
+    const sha = "11bd71901bbe5b1630ceea73d27597364c9af683";
+    const yaml = "name: CI\non:\n  push:\njobs:\n  build:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n";
+    const impl = (async (url: string | URL | Request) => {
+      const u = String(url);
+      if (u.includes("/commits/v4")) return new Response(JSON.stringify({ sha }), { status: 200 });
+      if (u.includes("/contents/.github/workflows/ci.yml")) {
+        return new Response(JSON.stringify({ name: "ci.yml", path: ".github/workflows/ci.yml", type: "file", content: b64(yaml), encoding: "base64" }), { status: 200 });
+      }
+      if (u.includes("/contents/.github/workflows")) {
+        return new Response(JSON.stringify([{ name: "ci.yml", path: ".github/workflows/ci.yml", type: "file", size: 100 }]), { status: 200 });
+      }
+      return new Response("not found", { status: 404 });
+    }) as unknown as typeof fetch;
+
+    const result = await auditCommand({ path: "https://github.com/acme/widgets", format: "markdown", fetchImpl: impl });
+    expect(result.output).toContain(`actions/checkout@${sha}`);
+    expect(result.output).toContain("```diff");
+  });
+
+  test("html format renders a self-contained document with a snapshot", async () => {
+    const result = await auditCommand({ path: REPO, format: "html", now: "2026-06-16T00:00:00.000Z", toolVersion: "0.4.0" });
+    expect(result.success).toBe(true);
+    expect(result.output.startsWith("<!doctype html>")).toBe(true);
+    expect(result.output).toContain("chant 0.4.0");
+    expect(result.output).toContain("local"); // host for a local audit
+  });
+
+  test("a non-allowlisted URL fails cleanly", async () => {
+    const result = await auditCommand({ path: "https://evil.example.com/o/r" });
+    expect(result.success).toBe(false);
+    expect(result.error).toMatch(/Host not allowed/);
+  });
+
+  test("sarif output is valid JSON with results", async () => {
+    const result = await auditCommand({ path: REPO, format: "sarif" });
+    const sarif = JSON.parse(result.output);
+    expect(sarif.version).toBe("2.1.0");
+    expect(sarif.runs[0].results.length).toBeGreaterThan(0);
+  });
+});