@intentius/chant 0.13.0 → 0.15.0

package/src/audit/fetch.test.ts

@@ -54,14 +54,51 @@ function gitTreeMock(files: Record<string, string>, sizes: Record<string, number
   return { impl, calls };
 }
 
-/** A GitLab-shaped mock: project default_branch, paginated repository/tree, raw files. */
-function gitlabMock(files: Record<string, string>) {
+/**
+ * GitLab mock for authenticated search-based discovery. `searchMap` maps search
+ * term → array of blob paths the search API returns. `files` maps path → content.
+ * Pass `token` to fetchRepoFiles when using this mock so the code takes the
+ * search path (unauthenticated calls fall back to BFS).
+ */
+function gitlabMock(searchMap: Record<string, string[]>, files: Record<string, string>) {
+  const impl = (async (url: string | URL | Request) => {
+    const u = String(url);
+    if (u.includes("/search")) {
+      const params = new URL(u).searchParams;
+      const term = params.get("search") ?? "";
+      const page = Number(params.get("page") ?? "1");
+      const paths = page === 1 ? (searchMap[term] ?? []) : [];
+      return new Response(JSON.stringify(paths.map((p) => ({ path: p }))), { status: 200 });
+    }
+    const rm = u.match(/\/repository\/files\/(.+?)\/raw\?/);
+    if (rm) {
+      const path = decodeURIComponent(rm[1]);
+      if (files[path] === undefined) return new Response("not found", { status: 404 });
+      return new Response(files[path], { status: 200 });
+    }
+    if (/\/projects\/[^/]+(\?|$)/.test(u)) return new Response(JSON.stringify({ default_branch: "main" }), { status: 200 });
+    return new Response("not found", { status: 404 });
+  }) as unknown as typeof fetch;
+  return { impl };
+}
+
+/**
+ * GitLab mock for the unauthenticated BFS fallback. `dirEntries` maps directory
+ * path (empty = root) to entries returned by the non-recursive tree API. `files`
+ * maps path → content for the raw endpoint.
+ */
+function gitlabBfsMock(
+  dirEntries: Record<string, Array<{ path: string; type: "blob" | "tree" }>>,
+  files: Record<string, string>,
+) {
   const impl = (async (url: string | URL | Request) => {
     const u = String(url);
     if (u.includes("/repository/tree")) {
-      const page = Number(new URL(u).searchParams.get("page") ?? "1");
-      const all = Object.keys(files).map((path) => ({ path, type: "blob" }));
-      return new Response(JSON.stringify(page === 1 ? all : []), { status: 200 });
+      const params = new URL(u).searchParams;
+      const dir = params.get("path") ?? "";
+      const page = Number(params.get("page") ?? "1");
+      const entries = dirEntries[dir] ?? [];
+      return new Response(JSON.stringify(page === 1 ? entries : []), { status: 200 });
     }
     const rm = u.match(/\/repository\/files\/(.+?)\/raw\?/);
     if (rm) {
@@ -174,13 +211,80 @@ describe("fetchRepoFiles", () => {
     await expect(fetchRepoFiles("https://evil.example.com/o/r")).rejects.toThrow(/Host not allowed/);
   });
 
-  test("gitlab: paginated tree + raw file content", async () => {
-    const { impl } = gitlabMock({ ".gitlab-ci.yml": "stages:\n  - build\n" });
-    const files = await fetchRepoFiles("https://gitlab.com/acme/widgets", { fetchImpl: impl });
+  test("gitlab: authenticated search finds .gitlab-ci.yml via stages: term", async () => {
+    const { impl } = gitlabMock(
+      { "stages:": [".gitlab-ci.yml"] },
+      { ".gitlab-ci.yml": "stages:\n  - build\n" },
+    );
+    const files = await fetchRepoFiles("https://gitlab.com/acme/widgets", { fetchImpl: impl, token: "tok" });
     expect(files.map((f) => f.path)).toEqual([".gitlab-ci.yml"]);
     expect(files[0].content).toContain("stages:");
   });
 
+  test("gitlab: search finds CI at non-canonical paths (include targets) (#520)", async () => {
+    // A .gitlab-ci.yml with `include:` referencing other CI files — the included
+    // file also has `stages:` so the search finds it without knowing the path.
+    const { impl } = gitlabMock(
+      { "stages:": [".gitlab-ci.yml", ".gitlab/ci/build.gitlab-ci.yml"] },
+      {
+        ".gitlab-ci.yml": "stages:\n  - build\ninclude:\n  - .gitlab/ci/build.gitlab-ci.yml\n",
+        ".gitlab/ci/build.gitlab-ci.yml": "stages:\n  - build\nscript:\n  - make\n",
+      },
+    );
+    const files = await fetchRepoFiles("https://gitlab.com/acme/widgets", { fetchImpl: impl, token: "tok" });
+    expect(files.map((f) => f.path)).toContain(".gitlab/ci/build.gitlab-ci.yml");
+  });
+
+  test("gitlab: search finds IaC files by content, unaffected by repo size (#518)", async () => {
+    // Previously, gitlab-org/gitlab returned 0 files because the recursive tree
+    // API listed thousands of directories before any blobs. Search-based discovery
+    // is independent of directory count — it goes directly to content.
+    const { impl } = gitlabMock(
+      {
+        "AWSTemplateFormatVersion": ["infra/stack.json"],
+        "stages:": [".gitlab-ci.yml"],
+      },
+      {
+        "infra/stack.json": '{"AWSTemplateFormatVersion":"2010-09-09","Resources":{}}',
+        ".gitlab-ci.yml": "stages:\n  - deploy\n",
+      },
+    );
+    const files = await fetchRepoFiles("https://gitlab.com/acme/monorepo", { fetchImpl: impl, token: "tok" });
+    const paths = files.map((f) => f.path);
+    expect(paths).toContain(".gitlab-ci.yml");
+    expect(paths).toContain("infra/stack.json");
+  });
+
+  test("gitlab: search deduplicates paths found by multiple terms", async () => {
+    // A Helm Chart.yaml matches both "apiVersion: v2" and the broader "apiVersion".
+    const { impl } = gitlabMock(
+      {
+        "apiVersion: v2": ["helm/Chart.yaml"],
+        "apiVersion": ["helm/Chart.yaml", "k8s/deploy.yaml"],
+      },
+      {
+        "helm/Chart.yaml": "apiVersion: v2\nname: myapp\nversion: 1.0.0\n",
+        "k8s/deploy.yaml": "apiVersion: apps/v1\nkind: Deployment\n",
+      },
+    );
+    const files = await fetchRepoFiles("https://gitlab.com/acme/widgets", { fetchImpl: impl, token: "tok" });
+    const paths = files.map((f) => f.path);
+    expect(paths.filter((p) => p === "helm/Chart.yaml")).toHaveLength(1);
+    expect(paths).toContain("k8s/deploy.yaml");
+  });
+
+  test("gitlab: unauthenticated falls back to BFS tree walk", async () => {
+    // Without a token, GitLab search returns 401. The BFS fallback walks
+    // directories non-recursively so root blobs appear on the first request.
+    const { impl } = gitlabBfsMock(
+      { "": [{ path: ".gitlab-ci.yml", type: "blob" }] },
+      { ".gitlab-ci.yml": "stages:\n  - build\n" },
+    );
+    // No token → BFS path
+    const files = await fetchRepoFiles("https://gitlab.com/acme/widgets", { fetchImpl: impl });
+    expect(files.map((f) => f.path)).toContain(".gitlab-ci.yml");
+  });
+
   test("forgejo (codeberg): gitea tree + contents", async () => {
     const { impl } = gitTreeMock({ ".forgejo/workflows/ci.yml": CI_YAML });
     const files = await fetchRepoFiles("https://codeberg.org/acme/widgets", { fetchImpl: impl });

package/src/audit/fetch.ts

@@ -157,16 +157,61 @@ interface TreeEntry {
 /** List every blob path in the repo (recursive), with size where the host reports it. */
 async function listTree(host: HostConfig, owner: string, repo: string, ref: string, doFetch: typeof fetch, headers: Record<string, string>, ms: number): Promise<TreeEntry[]> {
   if (host.kind === "gitlab") {
+    // GitLab search API requires authentication even for public projects. When a
+    // token is present, use content search — one query per lexicon finds only
+    // relevant files regardless of repo size, and catches non-canonical CI paths
+    // that path-based detection misses (#518, #520). Without a token, fall back
+    // to the non-recursive BFS which works for public repos.
+    if ("PRIVATE-TOKEN" in headers) {
+      const out: TreeEntry[] = [];
+      const seen = new Set<string>();
+      const addPath = (p: string) => { if (typeof p === "string" && !seen.has(p)) { seen.add(p); out.push({ path: p, type: "blob" }); } };
+      // Ordered most → least selective so the seen-set dedup reduces noise from
+      // broader terms (e.g. `apiVersion` won't re-add files already found by
+      // the more specific `apiVersion: v2`).
+      const SEARCH_TERMS = [
+        "AWSTemplateFormatVersion", // CloudFormation
+        "deploymentTemplate",        // Azure ARM ($schema substring)
+        "cnrm.cloud.google.com",     // GCP Config Connector
+        "apiVersion: v2",            // Helm Chart.yaml
+        "stages:",                   // GitLab CI — root file + non-canonical includes (#520)
+        "FROM ",                     // Dockerfiles (content-based; space avoids false matches)
+        "services:",                 // Docker Compose
+        "apiVersion",                // k8s manifests (broad; runs last)
+      ];
+      for (const term of SEARCH_TERMS) {
+        for (let page = 1; page <= 3; page++) {
+          const url = `${host.api}/projects/${projectId(owner, repo)}/search?scope=blobs&search=${encodeURIComponent(term)}&per_page=100&page=${page}&ref=${encodeURIComponent(ref)}`;
+          const { body } = await getJsonAt(url, headers, doFetch, ms);
+          if (!Array.isArray(body) || body.length === 0) break;
+          for (const e of body as Array<{ path: string }>) addPath(e.path);
+          if (body.length < 100) break;
+        }
+      }
+      return out;
+    }
+    // Unauthenticated fallback: non-recursive BFS. GitLab's recursive tree API
+    // lists ALL directories before any blobs for large repos (#518), so we walk
+    // directories breadth-first to ensure root blobs appear on the first request.
     const out: TreeEntry[] = [];
-    const MAX_PAGES = 20; // 20 * 100 = 2000 entries — bounded; candidate filter + caps trim further
-    for (let page = 1; page <= MAX_PAGES; page++) {
-      const url = `${host.api}/projects/${projectId(owner, repo)}/repository/tree?recursive=true&per_page=100&page=${page}&ref=${encodeURIComponent(ref)}`;
-      const { body } = await getJsonAt(url, headers, doFetch, ms);
-      if (!Array.isArray(body) || body.length === 0) break;
-      for (const e of body as Array<{ path: string; type: string }>) {
-        if (e.type === "blob") out.push({ path: e.path, type: "blob" });
+    const queue: string[] = [""]; // "" = repo root
+    const MAX_DIRS = 30;
+    const MAX_BLOBS = 200;
+    let dirs = 0;
+    while (queue.length > 0 && dirs < MAX_DIRS && out.length < MAX_BLOBS) {
+      const dir = queue.shift()!;
+      dirs++;
+      const pathParam = dir ? `&path=${encodeURIComponent(dir)}` : "";
+      for (let page = 1; page <= 5; page++) {
+        const url = `${host.api}/projects/${projectId(owner, repo)}/repository/tree?per_page=100&page=${page}&ref=${encodeURIComponent(ref)}${pathParam}`;
+        const { body } = await getJsonAt(url, headers, doFetch, ms);
+        if (!Array.isArray(body) || body.length === 0) break;
+        for (const e of body as Array<{ path: string; type: string }>) {
+          if (e.type === "blob") out.push({ path: e.path, type: "blob" });
+          else if (e.type === "tree") queue.push(e.path);
+        }
+        if (body.length < 100) break;
       }
-      if (body.length < 100) break;
     }
     return out;
   }

package/src/audit/proof.ts

@@ -12,13 +12,15 @@
  * the patched output differs only where intended — the diff proves it.
  */
 
-import { RULE_CATALOG } from "./catalog";
+import { RULE_CATALOG, type RuleMeta } 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;
+  /** Resolved audit catalog for the check's `fixKind`/remediation lookup (#687). Defaults to core's static `RULE_CATALOG`. */
+  catalog?: Record<string, RuleMeta>;
 }
 
 export interface ProofResult {
@@ -150,7 +152,7 @@ function narrowWriteAll(content: string): { patched: string; changed: boolean }
  * Returns `applied: false` with guidance for non-deterministic findings.
  */
 export function proveFix(checkId: string, content: string, opts: ProveOptions = {}): ProofResult {
-  const cat = RULE_CATALOG[checkId];
+  const cat = (opts.catalog ?? RULE_CATALOG)[checkId];
   if (cat && cat.fixKind !== "deterministic") {
     return notApplied(checkId, "guidance", cat.remediation || "Manual fix required.");
   }

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

@@ -1,4 +1,5 @@
-import { describe, test, expect } from "vitest";
+import { describe, test, expect, beforeAll } from "vitest";
+import { resolveAuditCatalog, type RuleMeta } from "./catalog";
 import { renderHtml, type AuditSnapshot } from "./report-html";
 import type { AuditFinding } from "./core";
 
@@ -29,9 +30,15 @@ const SNAPSHOT: AuditSnapshot = {
   toolVersion: "0.4.0",
 };
 
+
+let CATALOG: Record<string, RuleMeta>;
+beforeAll(async () => { CATALOG = await resolveAuditCatalog(["github", "gitlab"]); });
+/** renderHtml with the migrated github/gitlab catalog injected (#687). */
+const html2 = (findings: AuditFinding[], opts: Parameters<typeof renderHtml>[1] = {}) => renderHtml(findings, { ...opts, catalog: CATALOG });
+
 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 });
+    const html = html2(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");
@@ -43,7 +50,7 @@ describe("renderHtml", () => {
   });
 
   test("embeds the machine-readable JSON report (parseable, escaped)", () => {
-    const html = renderHtml(FINDINGS, { snapshot: SNAPSHOT });
+    const html = html2(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.
@@ -58,25 +65,25 @@ describe("renderHtml", () => {
     const evil: AuditFinding[] = [
       { checkId: "GHA036", severity: "error", message: "<script>alert(1)</script>", file: "a.yml", lexicon: "github" },
     ];
-    const html = renderHtml(evil);
+    const html = html2(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" } });
+    const html = html2(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" } });
+    const html = html2(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([]);
+    const html = html2([]);
     expect(html).toContain("No issues found.");
     expect(html).not.toContain("Quick wins");
   });

package/src/audit/report-model.ts

@@ -112,9 +112,9 @@ export interface AuditReportJson {
   findings: SerializedFinding[];
 }
 
-export function metaFor(id: string): RuleMeta {
+export function metaFor(id: string, catalog: Record<string, RuleMeta> = RULE_CATALOG): RuleMeta {
   return (
-    RULE_CATALOG[id] ?? {
+    catalog[id] ?? {
       id,
       tier: "report-only" as Tier,
       fixKind: "guidance",
@@ -146,7 +146,12 @@ function clusterName(m: RuleMeta): string {
   return m.authority?.[0]?.name ?? "General hardening";
 }
 
-function buildQuickWins(findings: EnrichedFinding[], contents: Map<string, string>, proveOpts: ProveOptions): QuickWinFile[] {
+function buildQuickWins(
+  findings: EnrichedFinding[],
+  contents: Map<string, string>,
+  proveOpts: ProveOptions,
+  catalog: Record<string, RuleMeta> = RULE_CATALOG,
+): QuickWinFile[] {
   const out: QuickWinFile[] = [];
   for (const [file, group] of byFile(findings)) {
     const ids = [...new Set(group.map((f) => f.checkId))].sort();
@@ -157,10 +162,10 @@ function buildQuickWins(findings: EnrichedFinding[], contents: Map<string, strin
 
     if (original !== undefined) {
       for (const id of ids) {
-        const res = proveFix(id, patched ?? original, proveOpts);
+        const res = proveFix(id, patched ?? original, { ...proveOpts, catalog });
         if (res.applied && res.patched !== undefined) {
           patched = res.patched;
-          addressed.push(metaFor(id));
+          addressed.push(metaFor(id, catalog));
         } else if (res.reason === "needs-input") {
           needsInput.push(...group.filter((f) => f.checkId === id));
         }
@@ -215,11 +220,14 @@ export interface BuildModelOptions {
   files?: Array<{ path: string; content: string }>;
   resolveSha?: ProveOptions["resolveSha"];
   resolveDigest?: ProveOptions["resolveDigest"];
+  /** The resolved audit catalog (core static + active lexicons' contributions, #687). Defaults to core's static `RULE_CATALOG`. */
+  catalog?: Record<string, RuleMeta>;
 }
 
 /** 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 catalog = opts.catalog ?? RULE_CATALOG;
+  const enriched: EnrichedFinding[] = findings.map((f) => ({ ...f, meta: metaFor(f.checkId, catalog) }));
   const contents = new Map((opts.files ?? []).map((f) => [f.path, f.content]));
 
   const mergeWorthy = enriched.filter((f) => f.meta.tier === "merge-worthy");
@@ -252,7 +260,7 @@ export function buildReportModel(findings: AuditFinding[], opts: BuildModelOptio
 
   return {
     counts,
-    quickWins: buildQuickWins(quickWinFindings, contents, { resolveSha: opts.resolveSha, resolveDigest: opts.resolveDigest }),
+    quickWins: buildQuickWins(quickWinFindings, contents, { resolveSha: opts.resolveSha, resolveDigest: opts.resolveDigest }, catalog),
     needsReview: buildClusters(needsReviewFindings),
     reportOnly: [...reportOnly].sort(sortFindings),
     findings: [...shown].sort(sortFindings),
@@ -260,8 +268,11 @@ export function buildReportModel(findings: AuditFinding[], opts: BuildModelOptio
 }
 
 /** Build the versioned, machine-readable JSON report (stable contract). */
-export function buildReportJson(findings: AuditFinding[], opts: { snapshot?: AuditSnapshot; toolVersion?: string } = {}): AuditReportJson {
-  const model = buildReportModel(findings);
+export function buildReportJson(
+  findings: AuditFinding[],
+  opts: { snapshot?: AuditSnapshot; toolVersion?: string; catalog?: Record<string, RuleMeta> } = {},
+): AuditReportJson {
+  const model = buildReportModel(findings, { catalog: opts.catalog });
   const version = opts.toolVersion ?? opts.snapshot?.toolVersion ?? "0.0.0";
   return {
     schemaVersion: REPORT_SCHEMA_VERSION,

package/src/audit/report.test.ts

@@ -1,5 +1,6 @@
-import { describe, test, expect } from "vitest";
-import { renderMarkdown } from "./report";
+import { describe, test, expect, beforeAll } from "vitest";
+import { resolveAuditCatalog, type RuleMeta } from "./catalog";
+import { renderMarkdown, type RenderOptions } from "./report";
 import type { AuditFinding } from "./core";
 
 const CI = `name: CI
@@ -21,15 +22,21 @@ const FINDINGS: AuditFinding[] = [
   { checkId: "GHA022", severity: "info", message: "no timeout.", file: ".github/workflows/ci.yml", lexicon: "github" },
 ];
 
+
+let CATALOG: Record<string, RuleMeta>;
+beforeAll(async () => { CATALOG = await resolveAuditCatalog(["github", "gitlab"]); });
+/** renderMarkdown with the migrated github/gitlab catalog injected (#687). */
+const md = (findings: AuditFinding[], opts: RenderOptions = {}) => renderMarkdown(findings, { ...opts, catalog: CATALOG });
+
 describe("renderMarkdown — reworked structure", () => {
   test("summary counts by tier and severity", () => {
-    const out = renderMarkdown(FINDINGS, { target: "owner/repo" });
+    const out = md(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 }] });
+    const out = md(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)");
     // merge-worthy findings cite their external authority (#351 links surfaced in the layout)
@@ -41,14 +48,14 @@ describe("renderMarkdown — reworked structure", () => {
   });
 
   test("pin findings without a SHA resolver are listed, not diffed", () => {
-    const out = renderMarkdown(FINDINGS, { files: [{ path: ".github/workflows/ci.yml", content: CI }] });
+    const out = md(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, {
+    const out = md(FINDINGS, {
       files: [{ path: ".github/workflows/ci.yml", content: CI }],
       resolveSha: () => sha,
     });
@@ -62,14 +69,14 @@ describe("renderMarkdown — reworked structure", () => {
       { 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 });
+    const out = md(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);
+    const out = md(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");
@@ -80,7 +87,7 @@ describe("renderMarkdown — reworked structure", () => {
   });
 
   test("report-only hygiene goes in a collapsible table", () => {
-    const out = renderMarkdown(FINDINGS);
+    const out = md(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) |");
@@ -91,7 +98,7 @@ describe("renderMarkdown — reworked structure", () => {
       { 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);
+    const out = md(findings);
     expect(out).toContain("WGL016");
     expect(out).not.toContain("WGL021"); // suppressed — same entity already flagged
     expect(out).toContain("1 finding — ");
@@ -102,20 +109,36 @@ describe("renderMarkdown — reworked structure", () => {
       { 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);
+    const out = md(findings);
     expect(out).toContain("GHA022"); // unrelated hygiene on the same job is kept
   });
 
   test("clean report when there are no findings", () => {
-    const out = renderMarkdown([]);
+    const out = md([]);
     expect(out).toContain("No issues found.");
     expect(out).not.toContain("Quick wins");
   });
 
   test("omits empty sections", () => {
-    const onlyGuidance = renderMarkdown([FINDINGS[2]]); // GHA035 only
+    const onlyGuidance = md([FINDINGS[2]]); // GHA035 only
     expect(onlyGuidance).toContain("<summary>Needs review (guidance)");
     expect(onlyGuidance).not.toContain("## Quick wins");
     expect(onlyGuidance).not.toContain("Report-only");
   });
 });
+
+describe("catalog threading (#687)", () => {
+  test("buildReportModel uses a passed-in catalog over core's static one", async () => {
+    const { buildReportModel } = await import("./report-model");
+    const findings: AuditFinding[] = [
+      { checkId: "ZZZ999", severity: "warning", message: "made up", file: "x.yml", lexicon: "github" },
+    ];
+    // Not in the static catalog → default model treats it as report-only.
+    expect(buildReportModel(findings).counts.quickWin).toBe(0);
+    // A resolved catalog (as a lexicon would contribute) makes it a deterministic merge-worthy fix.
+    const catalog = {
+      ZZZ999: { id: "ZZZ999", tier: "merge-worthy" as const, fixKind: "deterministic" as const, category: "security" as const, title: "Made up", remediation: "fix it", yamlBased: true },
+    };
+    expect(buildReportModel(findings, { catalog }).counts.quickWin).toBe(1);
+  });
+});

package/src/audit/report.ts

@@ -37,6 +37,8 @@ export interface RenderOptions {
   resolveDigest?: ProveOptions["resolveDigest"];
   /** Coverage caveats shown near the top (e.g. unresolved GitLab includes). */
   notes?: string[];
+  /** Resolved audit catalog (core static + active lexicons' contributions, #687). Defaults to core's static catalog. */
+  catalog?: Record<string, RuleMeta>;
 }
 
 function escapeCell(s: string): string {

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

@@ -2,19 +2,21 @@ 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";
+import { resolveAuditCatalog, ruleDocUrl } from "./catalog";
+import { AUDIT_LEXICONS } from "./discover";
 
 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)", () => {
+  test("committed page is in sync with the catalog (regenerate if this fails)", async () => {
     const committed = readFileSync(PAGE, "utf-8");
-    expect(committed).toBe(renderRulesReference());
+    expect(committed).toBe(await renderRulesReference());
   });
 
-  test("every rule has an anchor reachable from ruleDocUrl", () => {
-    const page = renderRulesReference();
-    for (const id of Object.keys(RULE_CATALOG)) {
+  test("every rule has an anchor reachable from ruleDocUrl", async () => {
+    const page = await renderRulesReference();
+    const catalog = await resolveAuditCatalog([...AUDIT_LEXICONS]);
+    for (const id of Object.keys(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

@@ -7,7 +7,8 @@
  * (lowercased) — the anchor `ruleDocUrl()` links to.
  */
 
-import { RULE_CATALOG, type RuleMeta } from "./catalog";
+import { resolveAuditCatalog, type RuleMeta } from "./catalog";
+import { AUDIT_LEXICONS } from "./discover";
 
 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." },
@@ -29,11 +30,18 @@ function ruleBlock(m: RuleMeta): string {
   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();
+/**
+ * Render the full audit rules reference page (frontmatter + body). Aggregates
+ * the catalog across every audit lexicon (#687) — each provider's rule metadata
+ * now lives in its own lexicon and is merged over core's static entries — so the
+ * doc lists them all. Async because it loads the lexicon plugins to collect
+ * their contributed catalogs; a doc-build step has all lexicons installed.
+ */
+export async function renderRulesReference(): Promise<string> {
+  const catalog = await resolveAuditCatalog([...AUDIT_LEXICONS]);
+  const ids = Object.keys(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]));
+    const blocks = ids.filter((id) => prefixes.some((p) => id.startsWith(p))).map((id) => ruleBlock(catalog[id]));
     if (blocks.length === 0) return "";
     return `## ${heading}\n${blurb ? `\n${blurb}\n` : ""}\n${blocks.join("\n\n")}`;
   }).filter(Boolean);