@intentius/chant 0.57.0 → 0.59.0

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")}
 `;
 }

package/src/audit/secrets.ts

@@ -173,7 +173,13 @@ export function parseSecretsConfig(content: string): SecretsScanOptions {
 
 // ── Shannon entropy ─────────────────────────────────────────────────────
 
-function shannonEntropy(s: string): number {
+/**
+ * Shannon entropy in bits per character. Exported so a lexicon's own
+ * secret-shape heuristic can score a candidate on the same scale this
+ * module's SEC010 catch-all uses (the terraform lexicon's
+ * `lint/secret-shape.ts`, #2110) instead of inventing a second one.
+ */
+export function shannonEntropy(s: string): number {
   const freq = new Map<string, number>();
   for (const ch of s) freq.set(ch, (freq.get(ch) ?? 0) + 1);
   let entropy = 0;
@@ -188,8 +194,14 @@ function shannonEntropy(s: string): number {
 
 const PLACEHOLDER_RE = /example|placeholder|dummy|changeme|change-me|redacted|sample|fixme|todo|xxxxxxxx|your[-_]?(api[-_]?)?(key|token|secret)|fake[-_]?(key|token|secret)|test[-_]?(key|token|secret)/i;
 
-/** Cheap, format-agnostic "this doesn't look like a real secret" filter. */
-function looksLikePlaceholder(value: string): boolean {
+/**
+ * Cheap, format-agnostic "this doesn't look like a real secret" filter.
+ * Exported for the same reason {@link shannonEntropy} is: the placeholder
+ * vocabulary a scanner has to ignore (`changeme`, `example`, `your-api-key`,
+ * a run of one repeated character) is the same wherever the candidate came
+ * from, and a second copy of this list would drift from this one.
+ */
+export function looksLikePlaceholder(value: string): boolean {
   if (PLACEHOLDER_RE.test(value)) return true;
   const uniq = new Set(value.toLowerCase()).size;
   if (value.length > 8 && uniq <= 2) return true; // e.g. "0000000000000000"

package/src/audit/terraform-state.test.ts

@@ -0,0 +1,144 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { describe, expect, test } from "vitest";
+import {
+  auditTerraformState,
+  gitignoreCoversTerraformState,
+  isTerraformStateFile,
+  isTerraformStatePath,
+  isTerraformWorkDir,
+  type ScannableFile,
+} from "./terraform-state";
+import { collectCandidates } from "./discover";
+import { RULE_CATALOG, RULE_CATEGORY } from "./catalog";
+
+const file = (path: string): ScannableFile => ({ path, content: "" });
+
+function tmpRepo(): string {
+  return mkdtempSync(join(tmpdir(), "chant-tf023-"));
+}
+
+describe("the TF023 path detectors", () => {
+  test.each([
+    "terraform.tfstate",
+    "terraform.tfstate.backup",
+    "infra/prod/terraform.tfstate",
+    "infra/prod.tfstate",
+    "infra/prod.tfstate.backup",
+  ])("%s is state", (path) => {
+    expect(isTerraformStateFile(path)).toBe(true);
+    expect(isTerraformStatePath(path)).toBe(true);
+  });
+
+  test.each(["main.tf", "terraform.tfvars", "state.json", "docs/tfstate.md"])("%s is not", (path) => {
+    expect(isTerraformStateFile(path)).toBe(false);
+  });
+
+  test("the working directory is matched as a path segment, at any depth", () => {
+    expect(isTerraformWorkDir(".terraform")).toBe(true);
+    expect(isTerraformWorkDir(".terraform/providers/registry.terraform.io/hashicorp/aws/5.0.0")).toBe(true);
+    expect(isTerraformWorkDir("infra/prod/.terraform")).toBe(true);
+    expect(isTerraformWorkDir("infra/terraform/main.tf")).toBe(false);
+  });
+});
+
+describe("auditTerraformState", () => {
+  test("reports a committed state file as an error, without reading it", () => {
+    const findings = auditTerraformState([file("infra/prod/terraform.tfstate")]);
+    expect(findings).toHaveLength(1);
+    expect(findings[0].checkId).toBe("TF023");
+    expect(findings[0].severity).toBe("error");
+    expect(findings[0].lexicon).toBe("terraform");
+    expect(findings[0].file).toBe("infra/prod/terraform.tfstate");
+    expect(findings[0].message).toContain("secret store");
+  });
+
+  test("reports a backup state file too", () => {
+    expect(auditTerraformState([file("terraform.tfstate.backup")])).toHaveLength(1);
+  });
+
+  test("reports a `.terraform` directory once, not once per file inside it", () => {
+    const findings = auditTerraformState([
+      file(".terraform"),
+      file(".terraform/modules/modules.json"),
+      file(".terraform/providers/registry.terraform.io/hashicorp/aws/5.0.0/terraform-provider-aws"),
+    ]);
+    expect(findings).toHaveLength(1);
+    expect(findings[0].file).toBe(".terraform");
+    expect(findings[0].entity).toBe(".terraform");
+  });
+
+  test("reports each root's own working directory separately", () => {
+    const findings = auditTerraformState([file("infra/prod/.terraform"), file("infra/staging/.terraform")]);
+    expect(findings.map((f) => f.file)).toEqual(["infra/prod/.terraform", "infra/staging/.terraform"]);
+  });
+
+  test("says nothing about a repository with neither", () => {
+    expect(auditTerraformState([{ path: "main.tf", content: 'resource "null_resource" "a" {}' }])).toEqual([]);
+  });
+
+  test("is catalogued in core, as a merge-worthy security rule", () => {
+    expect(RULE_CATALOG.TF023.tier).toBe("merge-worthy");
+    expect(RULE_CATALOG.TF023.category).toBe("security");
+    expect(RULE_CATEGORY.TF023).toBe("security");
+    expect(RULE_CATALOG.TF023.authority?.[0].url).toContain("#gitignore");
+  });
+});
+
+describe("gitignoreCoversTerraformState", () => {
+  test.each([
+    ["*.tfstate", "terraform.tfstate"],
+    ["*.tfstate.*", "terraform.tfstate.backup"],
+    [".terraform/", ".terraform"],
+    [".terraform*", ".terraform"],
+    ["/terraform.tfstate", "terraform.tfstate"],
+    ["**/.terraform", "infra/prod/.terraform"],
+    ["# comment\n\n*.tfstate\n", "infra/prod/terraform.tfstate"],
+  ])("%s covers %s", (gitignore, path) => {
+    expect(gitignoreCoversTerraformState(gitignore, path)).toBe(true);
+  });
+
+  test.each([
+    ["node_modules/\ndist/", "terraform.tfstate"],
+    ["*.tfvars", "terraform.tfstate"],
+    ["!terraform.tfstate", "terraform.tfstate"],
+  ])("%s does not cover %s", (gitignore, path) => {
+    expect(gitignoreCoversTerraformState(gitignore, path)).toBe(false);
+  });
+});
+
+describe("discovery hands TF023 its paths, and nothing else changes", () => {
+  test("a state file becomes a candidate with no content, so nothing reads it", () => {
+    const dir = tmpRepo();
+    writeFileSync(join(dir, "main.tf"), 'resource "null_resource" "a" {}\n');
+    writeFileSync(join(dir, "terraform.tfstate"), JSON.stringify({ version: 4, resources: [] }));
+    const candidates = collectCandidates(dir);
+    const state = candidates.find((c) => c.path === "terraform.tfstate");
+    expect(state).toBeDefined();
+    expect(state!.content).toBe("");
+    expect(auditTerraformState(candidates)).toHaveLength(1);
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("the walk records `.terraform` without descending into it", () => {
+    const dir = tmpRepo();
+    writeFileSync(join(dir, "main.tf"), 'resource "null_resource" "a" {}\n');
+    mkdirSync(join(dir, ".terraform", "providers"), { recursive: true });
+    writeFileSync(join(dir, ".terraform", "providers", "huge.json"), "{}");
+    const candidates = collectCandidates(dir);
+    expect(candidates.map((c) => c.path).sort()).toEqual([".terraform", "main.tf"]);
+    expect(auditTerraformState(candidates)).toHaveLength(1);
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("a gitignored state file is on disk, not in the repository, so it is dropped", () => {
+    const dir = tmpRepo();
+    writeFileSync(join(dir, ".gitignore"), ".terraform/\n*.tfstate\n*.tfstate.*\n");
+    writeFileSync(join(dir, "main.tf"), 'resource "null_resource" "a" {}\n');
+    writeFileSync(join(dir, "terraform.tfstate"), "{}");
+    mkdirSync(join(dir, ".terraform"), { recursive: true });
+    expect(auditTerraformState(collectCandidates(dir))).toEqual([]);
+    rmSync(dir, { recursive: true, force: true });
+  });
+});