@intentius/chant 0.57.0 → 0.58.0

package/src/audit/prior-art.ts

@@ -0,0 +1,153 @@
+/**
+ * Prior art for chant's audit rules.
+ *
+ * Most of what `chant audit` checks has been checked before by a dedicated
+ * open-source tool: zizmor and poutine for GitHub Actions, hadolint for
+ * Dockerfiles, cfn-lint and cfn_nag for CloudFormation, kube-linter and
+ * kube-score for Kubernetes manifests, gitleaks for secrets, and so on. chant's
+ * rules were written independently against the emitted output, but the ideas
+ * are shared, and the people who wrote them down first deserve the credit.
+ *
+ * A rule declares its lineage as `Lineage[]` on its `RuleMeta` entry: which
+ * tool, which upstream rule, where it is documented, and how the two relate.
+ * `PRIOR_ART` is the registry those entries key into, so a tool is named,
+ * linked and licensed once. The audit rules reference renders both, the
+ * markdown and HTML reports credit the tool beside the finding, and the SARIF
+ * and JSON outputs carry the entries verbatim for consumers.
+ *
+ * Lineage is credit, not authority. `authority` (./catalog.ts) is a standard
+ * or vendor document that says a finding matters; lineage is a tool that
+ * checks the same condition. The two are independent: a rule may have either,
+ * both, or neither, and lineage never changes a rule's category or tier.
+ */
+
+/** How a chant rule relates to the upstream check it credits. */
+export type LineageRelation =
+  /** Same condition, same scope. */
+  | "equivalent"
+  /** The core condition is shared; one side is narrower or broader, or a different dialect of the same control. */
+  | "overlaps"
+  /** chant checks a strict superset of the upstream check. */
+  | "extends";
+
+/** One credit: an upstream tool's rule that checks what this chant rule checks. */
+export interface Lineage {
+  /** A key of {@link PRIOR_ART}. */
+  tool: PriorArtTool;
+  /** The upstream rule id or check name, in the tool's own vocabulary (e.g. `template-injection`, `DL3007`, `CKV_AWS_18`). Omitted when the tool has no per-rule ids. */
+  rule?: string;
+  /** Where the upstream rule is documented. */
+  url: string;
+  relation: LineageRelation;
+}
+
+/** A tool (or, for a few families, a vendor validator) that chant's rules credit. */
+export interface PriorArtEntry {
+  name: string;
+  url: string;
+  /** SPDX identifier where confirmed, else "unverified" or "n/a" for documentation. */
+  license: string;
+  /** What kind of thing this is, so the rendered credit is honest about it. */
+  kind: "scanner" | "vendor-validator" | "specification";
+}
+
+/**
+ * The registry of prior art. Keys are the slugs `Lineage.tool` uses. Populated
+ * from the per-family research recorded in the PR that introduced lineage; the
+ * prior-art sweep (scripts/prior-art-sweep.ts) reads the same table.
+ */
+export const PRIOR_ART = {
+  "checkov": { name: "Checkov", url: "https://www.checkov.io/", license: "Apache-2.0", kind: "scanner" },
+  "kics": { name: "KICS", url: "https://docs.kics.io/", license: "Apache-2.0", kind: "scanner" },
+  "zizmor": { name: "zizmor", url: "https://docs.zizmor.sh/", license: "MIT", kind: "scanner" },
+  "cfn-nag": { name: "cfn_nag", url: "https://github.com/stelligent/cfn_nag", license: "MIT", kind: "scanner" },
+  "gitlab-docs": { name: "GitLab CI/CD YAML reference", url: "https://docs.gitlab.com/ci/yaml/", license: "CC-BY-SA-4.0", kind: "specification" },
+  "guard-rules-registry": { name: "AWS Guard Rules Registry", url: "https://github.com/aws-cloudformation/aws-guard-rules-registry", license: "Apache-2.0", kind: "scanner" },
+  "polaris": { name: "Fairwinds Polaris", url: "https://polaris.docs.fairwinds.com/", license: "Apache-2.0", kind: "scanner" },
+  "kube-linter": { name: "KubeLinter", url: "https://github.com/stackrox/kube-linter", license: "Apache-2.0", kind: "scanner" },
+  "kube-score": { name: "kube-score", url: "https://github.com/zegl/kube-score", license: "MIT", kind: "scanner" },
+  "psrule-azure": { name: "PSRule for Azure", url: "https://azure.github.io/PSRule.Rules.Azure/", license: "MIT", kind: "scanner" },
+  "gcp-policy-library": { name: "Google Cloud Policy Library", url: "https://github.com/GoogleCloudPlatform/policy-library", license: "Apache-2.0", kind: "scanner" },
+  "poutine": { name: "poutine", url: "https://boostsecurityio.github.io/poutine/", license: "Apache-2.0", kind: "scanner" },
+  "scorecard": { name: "OpenSSF Scorecard", url: "https://github.com/ossf/scorecard", license: "Apache-2.0", kind: "scanner" },
+  "cfn-lint": { name: "cfn-lint", url: "https://github.com/aws-cloudformation/cfn-lint", license: "MIT-0", kind: "scanner" },
+  "controlplane-docs": { name: "Control Plane reference documentation", url: "https://docs.controlplane.com", license: "n/a", kind: "specification" },
+  "gitleaks": { name: "gitleaks", url: "https://github.com/gitleaks/gitleaks", license: "MIT", kind: "scanner" },
+  "octoscan": { name: "octoscan", url: "https://github.com/synacktiv/octoscan", license: "GPL-3.0", kind: "scanner" },
+  "detect-secrets": { name: "detect-secrets", url: "https://github.com/Yelp/detect-secrets", license: "Apache-2.0", kind: "scanner" },
+  "actionlint": { name: "actionlint", url: "https://github.com/rhysd/actionlint", license: "MIT", kind: "scanner" },
+  "trufflehog": { name: "TruffleHog", url: "https://github.com/trufflesecurity/trufflehog", license: "AGPL-3.0", kind: "scanner" },
+  "gixy-ng": { name: "gixy-ng (maintained Gixy fork)", url: "https://github.com/dvershinin/gixy", license: "MPL-2.0", kind: "scanner" },
+  "kubesec": { name: "kubesec", url: "https://kubesec.io/", license: "Apache-2.0", kind: "scanner" },
+  "datree": { name: "Datree", url: "https://hub.datree.io/built-in-rules", license: "Apache-2.0", kind: "scanner" },
+  "helm-lint": { name: "helm lint", url: "https://helm.sh/docs/helm/helm_lint/", license: "Apache-2.0", kind: "vendor-validator" },
+  "cedar-validator": { name: "Cedar policy validator", url: "https://docs.cedarpolicy.com/policies/validation.html", license: "Apache-2.0", kind: "vendor-validator" },
+  "flux-docs": { name: "Flux Kustomization API reference", url: "https://fluxcd.io/flux/components/kustomize/kustomizations/", license: "n/a", kind: "specification" },
+  "hadolint": { name: "hadolint", url: "https://github.com/hadolint/hadolint", license: "GPL-3.0", kind: "scanner" },
+  "agent-audit": { name: "agent-audit", url: "https://github.com/piiiico/agent-audit", license: "MIT", kind: "scanner" },
+  "arm-ttk": { name: "ARM Template Toolkit (arm-ttk)", url: "https://github.com/Azure/arm-ttk", license: "MIT", kind: "scanner" },
+  "bicep-linter": { name: "Bicep linter", url: "https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/linter", license: "MIT", kind: "scanner" },
+  "cedar-cli": { name: "Cedar CLI", url: "https://github.com/cedar-policy/cedar/tree/main/cedar-policy-cli", license: "Apache-2.0", kind: "vendor-validator" },
+  "dockle": { name: "Dockle", url: "https://github.com/goodwithtech/dockle", license: "Apache-2.0", kind: "scanner" },
+  "mcp-audit": { name: "mcp-audit (APIsec)", url: "https://github.com/apisec-inc/mcp-audit", license: "MIT", kind: "scanner" },
+  "render-docs": { name: "Render Blueprint YAML reference", url: "https://render.com/docs/blueprint-spec", license: "n/a", kind: "specification" },
+  "agent-scan": { name: "Snyk Agent Scan (formerly mcp-scan)", url: "https://github.com/invariantlabs-ai/mcp-scan", license: "Apache-2.0", kind: "scanner" },
+  "cedar-docs": { name: "Cedar policy language reference", url: "https://docs.cedarpolicy.com/policies/json-format.html", license: "n/a", kind: "specification" },
+  "cedar-policy-crate": { name: "cedar-policy crate (PolicySet loader)", url: "https://docs.rs/cedar-policy/latest/cedar_policy/", license: "Apache-2.0", kind: "vendor-validator" },
+  "chart-testing": { name: "chart-testing (ct)", url: "https://github.com/helm/chart-testing", license: "Apache-2.0", kind: "vendor-validator" },
+  "fly-docs": { name: "Fly Machines API reference", url: "https://fly.io/docs/machines/api/machines-resource/", license: "n/a", kind: "specification" },
+  "gixy": { name: "Gixy", url: "https://github.com/yandex/gixy", license: "MPL-2.0", kind: "scanner" },
+  "kube-bench": { name: "kube-bench", url: "https://github.com/aquasecurity/kube-bench", license: "Apache-2.0", kind: "scanner" },
+  "pluto": { name: "Pluto", url: "https://github.com/FairwindsOps/pluto", license: "Apache-2.0", kind: "scanner" },
+  "choudoufu": { name: "choudoufu", url: "https://github.com/INTENTIUS/choudoufu", license: "MPL-2.0", kind: "scanner" },
+  // Terraform lint family (#2107). Registry entries recorded in
+  // lexicons/terraform/src/lint/audit-lineage.ts's header comment; added here
+  // the first time a shipped rule cites them (#2109).
+  "tflint-ruleset-terraform": { name: "tflint-ruleset-terraform", url: "https://github.com/terraform-linters/tflint-ruleset-terraform", license: "MPL-2.0", kind: "scanner" },
+  "terraform-sentinel-policies": { name: "HashiCorp reference Sentinel policies", url: "https://github.com/hashicorp/terraform-sentinel-policies", license: "MPL-2.0", kind: "specification" },
+  "hashicorp-style-guide": { name: "HashiCorp Terraform style guide", url: "https://developer.hashicorp.com/terraform/language/style", license: "n/a", kind: "specification" },
+  "aws-terraform-prescriptive-guidance": { name: "AWS prescriptive guidance for Terraform", url: "https://docs.aws.amazon.com/prescriptive-guidance/latest/terraform-aws-provider-best-practices/", license: "n/a", kind: "specification" },
+  // A multi-page series; a credit cites the specific page and fragment, not
+  // this landing URL. First cited by TF014 and TF015 (#2112).
+  "gcp-terraform-best-practices": { name: "Google Cloud Terraform best-practices series", url: "https://docs.cloud.google.com/docs/terraform/best-practices/general-style-structure", license: "n/a", kind: "specification" },
+  "tflint-ruleset-redeploy": { name: "tflint-ruleset-redeploy", url: "https://github.com/RedeployAB/tflint-ruleset-redeploy", license: "0BSD", kind: "scanner" },
+  "tflint-ruleset-avm": { name: "tflint-ruleset-avm (Azure Verified Modules)", url: "https://github.com/Azure/tflint-ruleset-avm", license: "MIT", kind: "scanner" },
+  // tfsec is frozen rather than archived, and its docs site 404s above v0.61.x,
+  // so its credits cite pinned repository paths (a tag or `master`), never the
+  // docs site. The three `general/secrets` checks chant credits live only here:
+  // trivy dropped them when it absorbed tfsec.
+  "tfsec": { name: "tfsec", url: "https://github.com/aquasecurity/tfsec", license: "MIT", kind: "scanner" },
+  // Semgrep's engine is LGPL-2.1 but its rules are not: they ship under the
+  // proprietary Semgrep Rules License v1.0, which forbids redistribution. So
+  // this entry carries no SPDX id, and no semgrep rule text is ever copied into
+  // this repository — a credit by name and link is the whole of it (#2107).
+  "semgrep": { name: "Semgrep Registry rules", url: "https://github.com/semgrep/semgrep-rules", license: "Semgrep Rules License v1.0 (proprietary, not an SPDX id)", kind: "scanner" },
+} as const satisfies Record<string, PriorArtEntry>;
+
+export type PriorArtTool = keyof typeof PRIOR_ART;
+
+/**
+ * Attach lineage to a catalog in place. A lexicon keeps its lineage in a
+ * sibling `audit-lineage.ts` (one `Record<ruleId, Lineage[]>`) and calls this
+ * once at the bottom of its `audit-catalog.ts`, so the prose metadata and the
+ * credits stay next to each other but the credits can be regenerated by the
+ * prior-art sweep without touching the rule text. Throws at module load if the
+ * lineage names a rule the catalog does not have: a stale id is a bug, not a
+ * silent no-op.
+ */
+export function applyLineage<T extends { id: string; lineage?: Lineage[] }>(
+  catalog: Record<string, T>,
+  lineage: Record<string, Lineage[]>,
+): void {
+  for (const [id, entries] of Object.entries(lineage)) {
+    const rule = catalog[id];
+    if (!rule) throw new Error(`audit lineage names ${id}, which this catalog does not define`);
+    if (entries.length > 0) rule.lineage = entries;
+  }
+}
+
+/** Render one lineage entry as "tool rule (relation)" for prose contexts. */
+export function lineageLabel(l: Lineage): string {
+  const tool = (PRIOR_ART as Record<string, PriorArtEntry>)[l.tool]?.name ?? l.tool;
+  return l.rule ? `${tool} ${l.rule}` : tool;
+}

package/src/audit/proof.test.ts

@@ -124,6 +124,73 @@ describe("proveFix — guidance findings are not auto-fixed", () => {
   });
 });
 
+/** A Terraform root with both of #2110's deterministic findings in it. */
+const TF_ROOT = `variable "log_level" {
+  type      = string
+  sensitive = false
+}
+
+resource "aws_s3_bucket" "assets" {
+  bucket = "\${var.assets_bucket}"
+  tags = {
+    name = "\${var.project}-assets"
+  }
+
+  lifecycle {
+    prevent_destroy       = false
+    create_before_destroy = var.replace_first
+  }
+}
+`;
+
+describe("proveFix — TF019, delete a meta-argument set to its default false", () => {
+  test("drops both redundant lines and leaves the expression alone", () => {
+    const res = proveFix("TF019", TF_ROOT);
+    expect(res.applied).toBe(true);
+    expect(res.patched).not.toContain("sensitive = false");
+    expect(res.patched).not.toContain("prevent_destroy       = false");
+    expect(res.patched).toContain("create_before_destroy = var.replace_first");
+    expect(res.diff).toContain("-  sensitive = false");
+    expect(res.diff).toContain("-    prevent_destroy       = false");
+    // Deletions only: nothing is added.
+    expect((res.diff ?? "").split("\n").filter((l) => l.startsWith("+") && !l.startsWith("+++"))).toEqual([]);
+  });
+
+  test("a root with no redundant default is a no-op, not a patch", () => {
+    const res = proveFix("TF019", 'resource "aws_s3_bucket" "assets" {\n  bucket = var.assets_bucket\n}\n');
+    expect(res.applied).toBe(false);
+    expect(res.reason).toBe("noop");
+  });
+
+  test("a line with a trailing comment is left alone: deleting it would delete the comment", () => {
+    const res = proveFix("TF019", "  sensitive = false # deliberate, see #123\n");
+    expect(res.applied).toBe(false);
+  });
+});
+
+describe("proveFix — TF016, unwrap an interpolation-only value", () => {
+  test("unquotes the single interpolation and leaves a real template alone", () => {
+    const res = proveFix("TF016", TF_ROOT);
+    expect(res.applied).toBe(true);
+    expect(res.patched).toContain("bucket = var.assets_bucket");
+    expect(res.patched).toContain('name = "${var.project}-assets"');
+    expect(res.diff).toContain("+  bucket = var.assets_bucket");
+  });
+
+  test("the two fixes combine into one patch, as a quick-win diff does", () => {
+    const first = proveFix("TF016", TF_ROOT);
+    const second = proveFix("TF019", first.patched ?? TF_ROOT);
+    expect(second.patched).toContain("bucket = var.assets_bucket");
+    expect(second.patched).not.toContain("prevent_destroy");
+  });
+
+  test("a root written the modern way is a no-op", () => {
+    const res = proveFix("TF016", 'output "arn" {\n  value = aws_s3_bucket.assets.arn\n}\n');
+    expect(res.applied).toBe(false);
+    expect(res.reason).toBe("noop");
+  });
+});
+
 describe("unifiedDiff", () => {
   test("identical input produces an empty diff", () => {
     expect(unifiedDiff(WF, WF)).toBe("");

package/src/audit/proof.ts

@@ -147,6 +147,70 @@ function narrowWriteAll(content: string): { patched: string; changed: boolean }
   return { patched: content.replace(re, "permissions:\n  contents: read"), changed: true };
 }
 
+/**
+ * TF019 — drop a meta-argument explicitly set to its own default `false`
+ * (`sensitive`, `ephemeral`, `prevent_destroy`, `create_before_destroy`). The
+ * fix is the deletion of the whole line, which is what tflint-ruleset-redeploy's
+ * own autofix for `terraform_redundant_default` does. Only a literal `false` is
+ * touched: `prevent_destroy = var.protect` is left alone, and so is a line with
+ * a trailing comment, where deleting the line would delete prose too.
+ */
+const REDUNDANT_DEFAULT_RE = /^[ \t]*(?:sensitive|ephemeral|prevent_destroy|create_before_destroy)[ \t]*=[ \t]*false[ \t]*$/;
+
+function dropRedundantDefaults(content: string): { patched: string; changed: boolean } {
+  const kept = content.split("\n").filter((line) => !REDUNDANT_DEFAULT_RE.test(line));
+  const patched = kept.join("\n");
+  return { patched, changed: patched !== content };
+}
+
+/**
+ * TF016 — unwrap an attribute whose whole value is one interpolation
+ * (`x = "${var.y}"` becomes `x = var.y`), the deprecated pre-0.12 style
+ * tflint's `terraform_deprecated_interpolation` reports. Anchored on the
+ * source text rather than the parsed body for the reason TF016's own module
+ * gives: `@cdktf/hcl2json` renders a bare reference and a quoted interpolation
+ * identically, so the quotes only exist here.
+ */
+const INTERPOLATION_ONLY_RE = /^([ \t]*)([A-Za-z_][A-Za-z0-9_-]*)([ \t]*=[ \t]*)"\$\{([^"]+)\}"([ \t]*(?:#.*)?)$/;
+
+/** One `name = "${expr}"` line, split into the parts the fix reassembles. */
+export interface InterpolationOnlyLine {
+  /** The attribute's name. */
+  name: string;
+  /** The expression inside the interpolation, without the `${` and `}`. */
+  expr: string;
+  /** The same line with the quotes and the `${}` taken off. */
+  unwrapped: string;
+}
+
+/**
+ * Parse a line whose whole value is one interpolation. Exported because a rule
+ * and its fix have to agree on what counts: the terraform lexicon's TF016
+ * check calls this over a block's source text, and `unwrapInterpolations`
+ * below rewrites exactly the lines it accepts.
+ */
+export function interpolationOnlyLine(line: string): InterpolationOnlyLine | undefined {
+  const m = INTERPOLATION_ONLY_RE.exec(line);
+  if (!m) return undefined;
+  const expr = m[4];
+  // A nested `${` means the template is not one interpolation (it embeds
+  // another), and a `}` before the end means the interpolation closed early,
+  // so the quotes are carrying literal text as well.
+  if (expr.includes("${") || expr.includes("}")) return undefined;
+  return { name: m[2], expr, unwrapped: `${m[1]}${m[2]}${m[3]}${expr}${m[5]}` };
+}
+
+function unwrapInterpolations(content: string): { patched: string; changed: boolean } {
+  let changed = false;
+  const lines = content.split("\n").map((line) => {
+    const parsed = interpolationOnlyLine(line);
+    if (!parsed) return line;
+    changed = true;
+    return parsed.unwrapped;
+  });
+  return { patched: lines.join("\n"), changed };
+}
+
 /**
  * Produce a deterministic fix + diff for a finding, if one is mechanical.
  * Returns `applied: false` with guidance for non-deterministic findings.
@@ -181,6 +245,12 @@ export function proveFix(checkId: string, content: string, opts: ProveOptions =
     case "GHA033":
       result = narrowWriteAll(content);
       break;
+    case "TF016":
+      result = unwrapInterpolations(content);
+      break;
+    case "TF019":
+      result = dropRedundantDefaults(content);
+      break;
     default:
       return notApplied(checkId, "needs-input", cat?.remediation || "No deterministic fix implemented for this rule yet.");
   }

package/src/audit/report-html.ts

@@ -9,7 +9,7 @@
  */
 
 import type { AuditFinding } from "./core";
-import { ruleDocUrl, type RuleMeta } from "./catalog";
+import { ruleDocUrl, type RuleMeta, lineageLabel } from "./catalog";
 import { buildReportModel, buildReportJson, type AuditSnapshot, type BuildModelOptions, type EnrichedFinding, type GuidanceCluster, type QuickWinFile, type ReportCounts } from "./report-model";
 
 export type { AuditSnapshot } from "./report-model";
@@ -48,9 +48,14 @@ function ruleLink(id: string): string {
 
 /** External backing for a merge-worthy rule (OSSF Scorecard, CIS, vendor docs). */
 function authorityLinks(meta: RuleMeta): string {
-  if (!meta.authority?.length) return "";
-  const links = meta.authority.map((a) => `<a href="${esc(a.url)}">${esc(a.name)}</a>`).join(", ");
-  return ` <span class="muted">per ${links}</span>`;
+  const parts: string[] = [];
+  if (meta.authority?.length) {
+    parts.push(`per ${meta.authority.map((a) => `<a href="${esc(a.url)}">${esc(a.name)}</a>`).join(", ")}`);
+  }
+  if (meta.lineage?.length) {
+    parts.push(`prior art: ${meta.lineage.map((l) => `<a href="${esc(l.url)}">${esc(lineageLabel(l))}</a>`).join(", ")}`);
+  }
+  return parts.length ? ` <span class="muted">${parts.join(" · ")}</span>` : "";
 }
 
 function renderDiff(diff: string): string {

package/src/audit/report-model.ts

@@ -7,7 +7,7 @@
 
 import type { AuditFinding } from "./core";
 import type { UnclaimedFile } from "./discover";
-import { RULE_CATALOG, ruleDocUrl, type Authority, type Category, type FixKind, type RuleMeta, type Tier } from "./catalog";
+import { RULE_CATALOG, ruleDocUrl, type Authority, type Category, type FixKind, type Lineage, type RuleMeta, type Tier } from "./catalog";
 import { proveFix, unifiedDiff, type ProveOptions } from "./proof";
 import type { Severity } from "../lint/rule";
 
@@ -98,6 +98,8 @@ export interface SerializedFinding {
   line?: number;
   /** Redaction-safe fingerprint of a flagged value, when applicable (see `secrets.ts`). */
   fingerprint?: string;
+  /** Set when the finding is an absence rather than a defect — see `PostSynthDiagnostic.missing` (chant #2113). */
+  missing?: { kind: string; scope: string };
   lexicon: string;
   tier: Tier;
   fixKind: FixKind;
@@ -106,6 +108,8 @@ export interface SerializedFinding {
   title: string;
   remediation: string;
   authority: Authority[];
+  /** Prior art: upstream tools whose rules check the same condition (credit, not authority). */
+  lineage: Lineage[];
   /** Link to this rule's entry in the audit rules reference. */
   docUrl: string;
 }
@@ -246,7 +250,13 @@ export function buildReportModel(findings: AuditFinding[], opts: BuildModelOptio
   const contents = new Map((opts.files ?? []).map((f) => [f.path, f.content]));
 
   const mergeWorthy = enriched.filter((f) => f.meta.tier === "merge-worthy");
-  const quickWinFindings = mergeWorthy.filter((f) => f.meta.fixKind === "deterministic");
+  // 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
@@ -254,6 +264,8 @@ export function buildReportModel(findings: AuditFinding[], opts: BuildModelOptio
   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;
@@ -304,6 +316,7 @@ export function buildReportJson(
       entity: f.entity,
       line: f.line,
       fingerprint: f.fingerprint,
+      missing: f.missing,
       lexicon: f.lexicon,
       tier: f.meta.tier,
       fixKind: f.meta.fixKind,
@@ -311,6 +324,7 @@ export function buildReportJson(
       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,

package/src/audit/report.test.ts

@@ -149,6 +149,39 @@ describe("efficiency dimension (#444)", () => {
   });
 });
 
+describe("a report-only rule with a deterministic fix (#2110)", () => {
+  const TF_ROOT = `variable "log_level" {
+  type      = string
+  sensitive = false
+}
+`;
+  const findings: AuditFinding[] = [
+    {
+      checkId: "TF019",
+      severity: "info",
+      message: "sensitive = false is already the default.",
+      file: "infra/prod",
+      lexicon: "terraform",
+      entity: "infra/prod/var.log_level.sensitive",
+    },
+  ];
+
+  test("renders in quick wins with its diff, not in the hygiene table", async () => {
+    const catalog = await resolveAuditCatalog(["terraform"]);
+    const out = renderMarkdown(findings, { catalog, files: [{ path: "infra/prod", content: TF_ROOT }] });
+    expect(out).toContain("## Quick wins (deterministic)");
+    expect(out).toContain("-  sensitive = false");
+    expect(out).toContain("1 finding — 1 quick-win, 0 needs-review, 0 report-only");
+    expect(out).not.toContain("Report-only (hygiene)");
+  });
+
+  test("the credit rides beside the fix", async () => {
+    const catalog = await resolveAuditCatalog(["terraform"]);
+    const out = renderMarkdown(findings, { catalog, files: [{ path: "infra/prod", content: TF_ROOT }] });
+    expect(out).toContain("prior art: [tflint-ruleset-redeploy terraform_redundant_default]");
+  });
+});
+
 describe("catalog threading (#687)", () => {
   test("buildReportModel uses a passed-in catalog over core's static one", async () => {
     const { buildReportModel } = await import("./report-model");

package/src/audit/report.ts

@@ -11,7 +11,7 @@
  */
 
 import type { AuditFinding } from "./core";
-import { ruleDocUrl, type RuleMeta } from "./catalog";
+import { lineageLabel, ruleDocUrl, type RuleMeta } from "./catalog";
 import type { ProveOptions } from "./proof";
 import { buildReportModel, type EnrichedFinding, type GuidanceCluster, type QuickWinFile } from "./report-model";
 
@@ -22,8 +22,10 @@ function ruleLink(id: string): string {
 
 /** External backing for a merge-worthy rule (OSSF Scorecard, CIS, vendor docs). */
 function authorityLinks(meta: RuleMeta): string {
-  if (!meta.authority?.length) return "";
-  return ` — per ${meta.authority.map((a) => `[${a.name}](${a.url})`).join(", ")}`;
+  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;
 }
 
 export interface RenderOptions {

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

@@ -1,8 +1,8 @@
 import { describe, test, expect } from "vitest";
 import { readFileSync } from "fs";
 import { fileURLToPath } from "url";
-import { renderRulesReference } from "./rules-doc";
-import { resolveAuditCatalog, ruleDocUrl } from "./catalog";
+import { renderRulesReference, ruleBlock } from "./rules-doc";
+import { resolveAuditCatalog, ruleDocUrl, auditRule } from "./catalog";
 import { AUDIT_LEXICONS } from "./discover";
 
 const PAGE = fileURLToPath(new URL("../../../../docs/src/content/docs/lint-rules/audit-rules.mdx", import.meta.url));
@@ -23,3 +23,35 @@ describe("audit rules reference", () => {
     }
   });
 });
+
+describe("ruleBlock, aliases and deprecated (chant #2113)", () => {
+  test("renders aliases as a list", () => {
+    const m = { ...auditRule("NEW001", "report-only", "guidance", "T", "r"), aliases: ["OLD001", "LEGACY_OLD"] };
+    const block = ruleBlock(m);
+    expect(block).toContain("Also known as: `OLD001`, `LEGACY_OLD`.");
+  });
+
+  test("greys a deprecated rule (tags line, not the heading; the heading is the anchor `ruleDocUrl` targets)", () => {
+    const m = { ...auditRule("OLD002", "report-only", "guidance", "T", "r") };
+    m.deprecated = "superseded by NEW002";
+    const block = ruleBlock(m);
+    expect(block).toContain("### OLD002"); // heading unchanged: `ruleDocUrl("OLD002")` must still resolve
+    expect(block).toContain("~~deprecated~~");
+    expect(block).toContain(":::note[Deprecated]");
+    expect(block).toContain("superseded by NEW002");
+  });
+
+  test("a deprecated rule with no string reason gets a generic note", () => {
+    const m = { ...auditRule("OLD003", "report-only", "guidance", "T", "r") };
+    m.deprecated = true;
+    expect(ruleBlock(m)).toContain("This rule no longer runs.");
+  });
+
+  test("a rule with neither aliases nor deprecated renders unchanged from before #2113", () => {
+    const m = auditRule("PLAIN001", "report-only", "guidance", "T", "r");
+    const block = ruleBlock(m);
+    expect(block).not.toContain("Also known as");
+    expect(block).not.toContain(":::note[Deprecated]");
+    expect(block).not.toContain("~~deprecated~~");
+  });
+});

package/src/audit/rules-doc.ts

@@ -7,7 +7,7 @@
  * (lowercased) — the anchor `ruleDocUrl()` links to.
  */
 
-import { resolveAuditCatalog, type RuleMeta } from "./catalog";
+import { PRIOR_ART, resolveAuditCatalog, type Lineage, type PriorArtEntry, type RuleMeta } from "./catalog";
 import { AUDIT_LEXICONS } from "./discover";
 
 const GROUPS: Array<{ heading: string; prefixes: string[]; blurb: string }> = [
@@ -21,6 +21,7 @@ const GROUPS: Array<{ heading: string; prefixes: string[]; blurb: string }> = [
   { 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." },
@@ -41,12 +42,84 @@ function mdxEscape(text: string): string {
   return text.replace(/\{/g, "\\{").replace(/</g, "\\<");
 }
 
-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**${mdxEscape(m.title)}** — ${tags}\n\n${mdxEscape(m.remediation)}${authority}`;
+function lineageLink(l: Lineage): string {
+  const tool = (PRIOR_ART as Record<string, PriorArtEntry>)[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: RuleMeta): string {
+  const rows: string[] = [];
+  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: boolean | string): string {
+  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: string[]): string {
+  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: RuleMeta): string {
+  // 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: Record<string, RuleMeta>): string {
+  const counts = new Map<string, number>();
+  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) as Array<[string, PriorArtEntry]>)
+    .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")}
+`;
 }
 
 /**
@@ -73,8 +146,8 @@ 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).
+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.join("\n\n")}
+${[...sections, priorArtSection(catalog)].filter(Boolean).join("\n\n")}
 `;
 }