@intentius/chant 0.124.12 → 0.124.14

package/dist/audit/report-model.js

@@ -0,0 +1,198 @@
+/**
+ * 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 { RULE_CATALOG, ruleDocUrl } from "./catalog.js";
+import { proveFix, unifiedDiff } from "./proof.js";
+/**
+ * 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`.
+ */
+// Additive changes (new fields like `category`, #415) keep the same version per
+// the stability contract; only renamed/removed fields bump it.
+export const REPORT_SCHEMA_VERSION = "1.0";
+export const SEVERITY_WEIGHT = { error: 0, warning: 1, info: 2 };
+/** Report-only rules made redundant by a specific merge-worthy rule on the same entity. */
+const SUPERSEDED_BY = {
+    WGL021: ["WGL016"], // "unused variable" is noise when the var is a flagged hardcoded secret
+};
+export function metaFor(id, catalog = RULE_CATALOG) {
+    return (catalog[id] ?? {
+        id,
+        tier: "report-only",
+        fixKind: "guidance",
+        title: id,
+        remediation: "",
+        yamlBased: true,
+    });
+}
+export function sortFindings(a, b) {
+    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) {
+    const map = new Map();
+    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) {
+    return m.authority?.[0]?.name ?? "General hardening";
+}
+function buildQuickWins(findings, contents, proveOpts, catalog = RULE_CATALOG) {
+    const out = [];
+    for (const [file, group] of byFile(findings)) {
+        const ids = [...new Set(group.map((f) => f.checkId))].sort();
+        const original = contents.get(file);
+        const addressed = [];
+        const needsInput = [];
+        let patched = original;
+        if (original !== undefined) {
+            for (const id of ids) {
+                const res = proveFix(id, patched ?? original, { ...proveOpts, catalog });
+                if (res.applied && res.patched !== undefined) {
+                    patched = res.patched;
+                    addressed.push(metaFor(id, catalog));
+                }
+                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();
+        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) {
+    const clusters = new Map();
+    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();
+        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 })),
+        };
+    });
+}
+/** Build the structured report model from raw findings. */
+export function buildReportModel(findings, opts = {}) {
+    const catalog = opts.catalog ?? RULE_CATALOG;
+    const enriched = 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");
+    // A deterministic fix is a quick win whatever the finding's tier. Every
+    // deterministic rule was merge-worthy until terraform's TF016 and TF019
+    // (#2110): both are hygiene, and both delete or unquote exactly the flagged
+    // line, which is the same safe mechanical patch a merge-worthy quick win
+    // offers. Filing them under "needs a judgement call" or in the hygiene table
+    // would hide a ready-to-apply diff.
+    const quickWinFindings = enriched.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;
+        // Counted and rendered as a quick win instead, so the three buckets stay disjoint.
+        if (f.meta.fixKind === "deterministic")
+            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 = {
+        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,
+        security: shown.filter((f) => f.meta.category === "security").length,
+        correctness: shown.filter((f) => f.meta.category === "correctness").length,
+        bestPractice: shown.filter((f) => f.meta.category === "best-practice").length,
+        efficiency: shown.filter((f) => f.meta.category === "efficiency").length,
+    };
+    return {
+        counts,
+        quickWins: buildQuickWins(quickWinFindings, contents, { resolveSha: opts.resolveSha, resolveDigest: opts.resolveDigest }, catalog),
+        needsReview: buildClusters(needsReviewFindings),
+        reportOnly: [...reportOnly].sort(sortFindings),
+        findings: [...shown].sort(sortFindings),
+    };
+}
+/** Build the versioned, machine-readable JSON report (stable contract). */
+export function buildReportJson(findings, opts = {}) {
+    const model = buildReportModel(findings, { catalog: opts.catalog });
+    const version = opts.toolVersion ?? opts.snapshot?.toolVersion ?? "0.0.0";
+    return {
+        schemaVersion: REPORT_SCHEMA_VERSION,
+        tool: { name: "chant-audit", version },
+        status: "ok",
+        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,
+            line: f.line,
+            fingerprint: f.fingerprint,
+            missing: f.missing,
+            lexicon: f.lexicon,
+            tier: f.meta.tier,
+            fixKind: f.meta.fixKind,
+            category: f.meta.category,
+            title: f.meta.title,
+            remediation: f.meta.remediation,
+            authority: f.meta.authority ?? [],
+            lineage: f.meta.lineage ?? [],
+            docUrl: ruleDocUrl(f.checkId),
+        })),
+        unclaimed: opts.unclaimed && opts.unclaimed.length > 0 ? opts.unclaimed : undefined,
+        truncated: opts.truncated,
+    };
+}

package/dist/audit/report.js

@@ -0,0 +1,102 @@
+/**
+ * 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 { lineageLabel, ruleDocUrl } from "./catalog.js";
+import { buildReportModel } from "./report-model.js";
+/** A rule id as a Markdown link to its reference entry. */
+function ruleLink(id) {
+    return `[${id}](${ruleDocUrl(id)})`;
+}
+/** External backing for a merge-worthy rule (OSSF Scorecard, CIS, vendor docs). */
+function authorityLinks(meta) {
+    const authority = meta.authority?.length ? ` — per ${meta.authority.map((a) => `[${a.name}](${a.url})`).join(", ")}` : "";
+    // Prior art rides beside the authority: the tool that checked this first.
+    const lineage = meta.lineage?.length ? ` · prior art: ${meta.lineage.map((l) => `[${lineageLabel(l)}](${l.url})`).join(", ")}` : "";
+    return authority + lineage;
+}
+function escapeCell(s) {
+    return s.replace(/\|/g, "\\|").replace(/\n/g, " ").trim();
+}
+function renderQuickWins(files) {
+    const lines = ["## 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})${authorityLinks(m)}`).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}${authorityLinks(f.meta)}`);
+            }
+        }
+        lines.push("");
+    }
+    return lines;
+}
+function renderNeedsReview(clusters) {
+    const lines = ["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}${authorityLinks(meta)}`);
+            for (const f of findings) {
+                const loc = f.line ? `${f.file}:${f.line}` : f.file;
+                const where = f.entity ? `\`${loc}\` (\`${f.entity}\`)` : `\`${loc}\``;
+                lines.push(`  - ${where} — ${escapeCell(f.message)}`);
+            }
+        }
+        lines.push("");
+    }
+    return lines;
+}
+function renderReportOnly(findings) {
+    const lines = ["", "| 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, opts = {}) {
+    const model = buildReportModel(findings, opts);
+    const { counts } = model;
+    const lines = [`${"#".repeat(opts.headingLevel ?? 1)} ${opts.title ?? "chant 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).`, "", `By category: ${counts.security} security, ${counts.correctness} correctness, ${counts.bestPractice} best-practice, ${counts.efficiency} efficiency.`, "");
+    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/dist/audit/rules-doc.js

@@ -0,0 +1,144 @@
+/**
+ * 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 { PRIOR_ART, resolveAuditCatalog } from "./catalog.js";
+import { AUDIT_LEXICONS } from "./discover.js";
+const GROUPS = [
+    { 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 / FLUX)", prefixes: ["WK8", "ARGO", "FLUX"], blurb: "Run against Kubernetes manifests." },
+    { heading: "Docker (DKRD)", prefixes: ["DKRD"], blurb: "Run against Dockerfiles and Compose files." },
+    { heading: "AWS CloudFormation (WAW / COR / EXT)", prefixes: ["WAW", "COR", "EXT"], blurb: "Run against CloudFormation templates (JSON or YAML)." },
+    { heading: "Azure ARM (AZR)", prefixes: ["AZR"], blurb: "Run against ARM deployment templates (JSON)." },
+    { heading: "GCP Config Connector (WGC)", prefixes: ["WGC"], blurb: "Run against Config Connector (cnrm.cloud.google.com) manifests." },
+    { heading: "Helm (WHM)", prefixes: ["WHM"], blurb: "Run against Helm charts (Chart.yaml + templates)." },
+    { heading: "fountain (FTN)", prefixes: ["FTN"], blurb: "Run against fountain manifests (`apiVersion: fountain.dev/v1`) — standalone `fountain apply` YAML is parsed back into the entity graph, so the same rules fire on `chant build` and `chant audit`." },
+    { heading: "Terraform (TF)", prefixes: ["TF"], blurb: "Run against Terraform root modules (a directory of `.tf` files) parsed into the entity graph, so the same rules fire on `chant build` over `terraform.roots` and on `chant audit` (#2083)." },
+    { heading: "Secrets & credentials (SEC)", prefixes: ["SEC"], blurb: "Lexicon-independent — scans the raw text of every scanned file for likely credentials, regardless of which audit lexicons are installed. Matched values are always redacted; see [suppressing false positives](/chant/cli/audit/#suppressing-a-secrets-finding)." },
+    { heading: "Wrangler config (WRG)", prefixes: ["WRG"], blurb: "Lexicon-independent, audit-only (#446) — scans `wrangler.toml`, Cloudflare Workers' native deploy config, which the engine cannot otherwise parse (it is not YAML/JSON). No authoring surface: chant does not write Wrangler config, it only reads it for these checks." },
+    { heading: "nginx config (NGX)", prefixes: ["NGX"], blurb: "Lexicon-independent, audit-only (#1979) — parses nginx's native directive/block config (`nginx.conf` and `.conf` files under nginx-ish directories, confirmed by content). No authoring surface: chant does not write nginx config, it only reads it for these checks." },
+    {
+        heading: "Agent configuration (AGT)",
+        prefixes: ["AGT"],
+        blurb: "Run by `chant audit --agents` against the agent configuration on a machine — instruction files, MCP servers, skills, plugins, and permissions at system, user, and project scope. Unlike every other family here, these do not fire on repository YAML.",
+    },
+];
+/**
+ * MDX treats `{expr}` as a JavaScript expression and `<x` as JSX, so rule
+ * text containing literal braces (`${VAR}` substitution references) or angle
+ * brackets must be escaped or the docs build fails at render time.
+ */
+function mdxEscape(text) {
+    return text.replace(/\{/g, "\\{").replace(/</g, "\\<");
+}
+function lineageLink(l) {
+    const tool = PRIOR_ART[l.tool]?.name ?? l.tool;
+    const label = l.rule ? `${tool} \`${l.rule}\`` : tool;
+    return `[${mdxEscape(label)}](${l.url}) (${l.relation})`;
+}
+/**
+ * A rule's backing, as a two-column table: the authority that says the finding
+ * matters, and the prior art that checked it first. A table rather than two
+ * "Label: ..." lines so that 379 rules do not read as 379 repeated sentences.
+ */
+function backingTable(m) {
+    const rows = [];
+    if (m.authority?.length)
+        rows.push(`| Authority | ${m.authority.map((a) => `[${a.name}](${a.url})`).join(" · ")} |`);
+    if (m.lineage?.length)
+        rows.push(`| Prior art | ${m.lineage.map(lineageLink).join(" · ")} |`);
+    return rows.length ? `\n\n| | |\n|---|---|\n${rows.join("\n")}` : "";
+}
+/**
+ * A rule kept the day it retires (chant #2113) rather than dropped: still
+ * gets a heading (so old links and `lint.rules`/suppression entries that
+ * name it still land somewhere), but greyed via a `:::note` aside instead of
+ * reading like a live rule, and with the `deprecated` string, when one was
+ * given, saying what replaced it.
+ */
+function deprecatedNote(deprecated) {
+    const reason = typeof deprecated === "string" ? mdxEscape(deprecated) : "This rule no longer runs.";
+    return `\n\n:::note[Deprecated]\n${reason} The id is kept so a reference to it still resolves.\n:::`;
+}
+function aliasesLine(aliases) {
+    return `\n\nAlso known as: ${aliases.map((a) => `\`${mdxEscape(a)}\``).join(", ")}.`;
+}
+/** Exported for `rules-doc.test.ts` to exercise the alias/deprecated rendering directly against a synthetic `RuleMeta`, without needing a real catalog entry to carry either (chant #2113). */
+export function ruleBlock(m) {
+    // The heading text is what Starlight slugifies into `#<id>`, the anchor
+    // `ruleDocUrl()` links to (`./catalog.ts`), so it stays exactly `### <ID>`
+    // even for a deprecated rule. The "greyed out" treatment goes below the
+    // heading instead, so an old link/alias reference still lands on the id.
+    const tags = m.deprecated ? `${m.tier} · ${m.fixKind} · ~~deprecated~~` : `${m.tier} · ${m.fixKind}`;
+    return (`### ${m.id}\n\n**${mdxEscape(m.title)}** — ${tags}\n\n${mdxEscape(m.remediation)}` +
+        `${backingTable(m)}` +
+        `${m.aliases?.length ? aliasesLine(m.aliases) : ""}` +
+        `${m.deprecated ? deprecatedNote(m.deprecated) : ""}`);
+}
+/**
+ * The closing section: every tool the rules credit, with its licence and how
+ * many rules point at it. Rendered from the same registry the entries key into,
+ * so a tool cannot be credited on a rule without appearing here.
+ */
+function priorArtSection(catalog) {
+    const counts = new Map();
+    for (const m of Object.values(catalog)) {
+        for (const l of m.lineage ?? [])
+            counts.set(l.tool, (counts.get(l.tool) ?? 0) + 1);
+    }
+    const rows = Object.entries(PRIOR_ART)
+        .filter(([key]) => counts.has(key))
+        .sort(([a], [b]) => (counts.get(b) ?? 0) - (counts.get(a) ?? 0) || a.localeCompare(b))
+        .map(([key, t]) => `| [${t.name}](${t.url}) | ${t.kind} | ${t.license} | ${counts.get(key)} |`);
+    if (rows.length === 0)
+        return "";
+    return `## Prior art
+
+chant's rules were written against the output chant emits, but much of what they check was checked first by a dedicated tool. Each rule above that has a counterpart names it under **Prior art**, with the upstream rule id and how the two relate.
+
+- \`equivalent\` is the same condition at the same scope.
+- \`overlaps\` shares the core condition, with one side narrower or broader, or expressed for a different dialect of the same control.
+- \`extends\` means chant checks a strict superset of the upstream rule.
+
+This is credit rather than authority, and it never changes a rule's tier or category. A credit counts once per upstream rule cited, so a chant rule that names two zizmor audits adds two.
+
+| Tool | Kind | Licence | Credits |
+|---|---|---|---|
+${rows.join("\n")}
+`;
+}
+/**
+ * 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() {
+    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(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.
+diataxis: reference
+---
+
+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). Where an open-source tool checks the same thing, the rule says so under **Prior art**; the [Prior art](#prior-art) section at the end lists every tool the rules on this page credit.
+
+${[...sections, priorArtSection(catalog)].filter(Boolean).join("\n\n")}
+`;
+}