@intentius/chant 0.57.0 → 0.58.0

package/src/claimed-fields.ts

@@ -0,0 +1,208 @@
+/**
+ * The claimed-field set (#2160) — which properties this declaration ever set.
+ *
+ * chant's ownership question has always been answered per resource, from a
+ * marker: is this thing mine. The finer question was never asked. A live
+ * property tree carries fields nobody declared — an autoscaler's replica count,
+ * a controller's annotation, a value a person typed into a console — and the
+ * deep diff (./lifecycle/deep-diff.ts) reported every one of them as a
+ * difference, because a difference is all a two-way comparison can produce.
+ *
+ * Every lexicon has been paying for that in hand-written knowledge.
+ * `DeepNormalizationHooks.prune` is where the noise goes, and three of the four
+ * hooks exist because the live tree holds fields the declaration never
+ * mentions. Kubernetes is the one substrate that escapes it: the API server
+ * records a field manager per field (`metadata.managedFields`), so a foreign
+ * write is a fact about the object rather than a rule somebody maintains.
+ * `lexicons/gcp/src/deep-observe.ts` says why nobody else can do that — "a REST
+ * payload carries no field ownership" — and answers with a static per-kind
+ * table instead.
+ *
+ * The declaration is the table they are missing. A `ResourceDeclarable`'s
+ * `props` are exactly the fields chant set, they are available on every
+ * substrate, and they come from the same build that produced the entity.
+ * Nothing has to come back from the provider.
+ *
+ * ## The grammar is the diff's grammar
+ *
+ * A claim is a set of property paths in the form `flattenDeepProperties`
+ * produces: `spec.replicas`, `Tags[#env].Value`, `ingress[0].fromPort`. Same
+ * hooks, same normalization, same flattening — so a path in the claim and a
+ * path in the diff are the same string or they are different fields. Deriving
+ * the claim any other way (walking raw props, say) would give a set that agrees
+ * with the diff for most trees and disagrees for exactly the ones the hooks
+ * were written for.
+ *
+ * ## Membership is exact, deliberately
+ *
+ * A claimed path is matched exactly, never by its index-erased pattern
+ * (`Tags[].Value`). The pattern is the right test for
+ * {@link import("./deep-observation").DeepNode.counterpart}, which asks a
+ * shape question ("did source declare tag values at all") before array order is
+ * canonical. Classification asks a value question, and it pairs a declared
+ * value with a live one at the same path. A pattern match would answer
+ * "declared" for a path that has no declared value to compare against, which is
+ * neither of the two declared classifications and would quietly become a third
+ * meaning of "drift".
+ *
+ * ## What the claim does not decide
+ *
+ * It does not prune. A field chant never declared still reaches the diff, still
+ * appears in the report, and still carries its live value — it is reported as
+ * unclaimed rather than dropped, because chant #1191 already lost a
+ * console-added label by pruning what it could not attribute. What the claim
+ * changes is the verdict: unclaimed is not drift, and drift is the only thing
+ * that may become an update.
+ */
+
+import {
+  deepValueEqual,
+  flattenDeepProperties,
+  normalizeDeepProperties,
+  type DeepNormalizationHooks,
+} from "./deep-observation";
+
+/**
+ * The set of property paths one declaration claims — every path its `props`
+ * flatten to, in the diff's own grammar.
+ *
+ * Opaque on purpose: {@link isClaimed} is the only membership test, so a
+ * consumer cannot accidentally invent a looser one (see the module doc on
+ * pattern matching).
+ */
+export interface ClaimedFieldSet {
+  /** Flattened property paths, exactly as the diff addresses them. */
+  readonly paths: ReadonlySet<string>;
+}
+
+/**
+ * How one LIVE value relates to the claim. Three answers where a two-way diff
+ * had two:
+ *
+ * - `declared-equal` — chant set this field and the cloud agrees. Nothing to say.
+ * - `declared-changed` — chant set this field and the cloud holds something
+ *   else. This is drift, and it is the only classification that may become an
+ *   update.
+ * - `undeclared` — the field has a value and chant never set it. Somebody else
+ *   holds it. Reported, never proposed, never counted as drift.
+ *
+ * A declared path with no live value at all is not in this enumeration: there
+ * is no live value to classify. The diff keeps reporting that case as `absent`.
+ */
+export type FieldClaim = "declared-equal" | "declared-changed" | "undeclared";
+
+/** Which source answered "who holds this field". */
+export type FieldClaimSource =
+  /**
+   * The substrate named the manager. Kubernetes' `metadata.managedFields`, and
+   * nowhere else today — strictly better than the claim, because it says who.
+   */
+  | "field-manager"
+  /**
+   * The declaration answered: the path is not in the claimed-field set, so
+   * chant never set it. Says that it is somebody else's without saying whose,
+   * which is the best any substrate without ownership metadata can do.
+   */
+  | "claimed-fields";
+
+/** An empty claim — a declaration with no props, and the safe default. */
+export const NO_CLAIMED_FIELDS: ClaimedFieldSet = { paths: new Set<string>() };
+
+/**
+ * Build a claim from an already-normalized declared property tree.
+ *
+ * `options` must be the same {@link FlattenDeepOptions} the diff flattens the
+ * declared side with, or the two disagree about keyed list segments.
+ */
+export function claimedFieldsOfTree(
+  declared: Record<string, unknown>,
+  options: { entityType: string; hooks?: DeepNormalizationHooks },
+): ClaimedFieldSet {
+  const flat = flattenDeepProperties(declared, {
+    entityType: options.entityType,
+    side: "declared",
+    ...(options.hooks ? { hooks: options.hooks } : {}),
+  });
+  return { paths: new Set(flat.keys()) };
+}
+
+/**
+ * Build a claim straight from a declaration's raw `props` — the entry point for
+ * a consumer that has an entity and no diff.
+ *
+ * Normalizes with the lexicon's own hooks first, exactly as the diff does, so
+ * pruned and masked paths land the same way on both routes. `livePaths` is the
+ * counterpart set (`deepPathSet` over the live tree) where the caller has one:
+ * without it the pass runs one-sided and any hook gated on
+ * {@link import("./deep-observation").DeepNode.counterpart} sees `"unknown"`,
+ * which is the honest answer and prunes nothing default-related.
+ */
+export function claimedFieldsOfProps(
+  props: Record<string, unknown>,
+  options: {
+    entityType: string;
+    hooks?: DeepNormalizationHooks;
+    livePaths?: ReadonlySet<string>;
+  },
+): ClaimedFieldSet {
+  const normalized = normalizeDeepProperties(props, {
+    entityType: options.entityType,
+    side: "declared",
+    ...(options.hooks ? { hooks: options.hooks } : {}),
+    ...(options.livePaths ? { counterpartPaths: options.livePaths } : {}),
+  });
+  return claimedFieldsOfTree(normalized, options);
+}
+
+/** True when this declaration set the property at `path`. */
+export function isClaimed(claimed: ClaimedFieldSet | undefined, path: string): boolean {
+  return claimed !== undefined && claimed.paths.has(path);
+}
+
+/**
+ * The claim as a sorted array — the wire form, for
+ * {@link import("./deep-observation").DeepResourceObservation.claimedFields}
+ * and for anything serializing a result to JSON.
+ */
+export function claimedFieldPaths(claimed: ClaimedFieldSet): string[] {
+  return [...claimed.paths].sort();
+}
+
+/** Rebuild a claim from its wire form. */
+export function claimedFieldsFromPaths(paths: Iterable<string>): ClaimedFieldSet {
+  return { paths: new Set(paths) };
+}
+
+/**
+ * Classify one live value against the claim.
+ *
+ * `declaredValue` is only read when the path is claimed; pass whatever the
+ * declared tree holds there (including `undefined`, which is a legal declared
+ * value on a claimed path only in the sense that the flattener never emits it).
+ */
+export function classifyLiveField(input: {
+  claimed: ClaimedFieldSet | undefined;
+  path: string;
+  declaredValue: unknown;
+  liveValue: unknown;
+}): FieldClaim {
+  if (!isClaimed(input.claimed, input.path)) return "undeclared";
+  return deepValueEqual(input.declaredValue, input.liveValue) ? "declared-equal" : "declared-changed";
+}
+
+/**
+ * Who holds an undeclared live field, and which source said so.
+ *
+ * The manager wins where the substrate records one: "owned by `hpa-controller`"
+ * and "chant never set it" are the same verdict with very different amounts of
+ * information in them, and an operator can act on the first. The claim is the
+ * fallback, and it answers on every substrate.
+ */
+export function heldBy(fieldOwners: Record<string, string> | undefined, path: string): {
+  holder?: string;
+  source: FieldClaimSource;
+} {
+  const manager = fieldOwners?.[path];
+  if (manager) return { holder: manager, source: "field-manager" };
+  return { source: "claimed-fields" };
+}

package/src/cli/build-params-cli.ts

@@ -9,8 +9,8 @@ import { formatError, formatInfo } from "./format";
  * out (chant #1108) so every command that discovers project source before
  * running it resolves `chant.config.ts`'s declared `buildParams` the exact
  * same way: `chant build` (`../commands/build.ts`'s `buildCommand`), the
- * component deploy driver (`./handlers/run.ts`'s `chant run --components`
- * local + `--temporal` paths), and generate mode (`./handlers/build.ts`'s
+ * component deploy driver (`./handlers/run.ts`'s `chant run --components`),
+ * and generate mode (`./handlers/build.ts`'s
  * `chant build --components --generate <lexicon>`).
  *
  * Before #1108, only `buildCommand` ran this sequence — `chant run

package/src/cli/command-group.ts

@@ -57,6 +57,20 @@ export interface CommandGroup {
   description: string;
   /** Verbs in this group. */
   commands: CommandGroupCommand[];
+  /**
+   * The verb to run when the group name is given on its own — `chant acp`
+   * rather than `chant acp serve` (#2125). Named here rather than assumed to
+   * be the first verb, because a group whose bare form should be a usage
+   * error (`chant kube`) must stay one: omitting this field is how a group
+   * says it has no default.
+   *
+   * The token after the group name decides which reading applies, and that
+   * decision belongs to the caller that still holds the raw argv
+   * (`../cli/main.ts`'s `tryPluginCommand`): with a default verb, `chant acp
+   * --durable-requests` has no verb token to consume, so the flag is the
+   * default verb's argument rather than a verb it does not have.
+   */
+  defaultVerb?: string;
 }
 
 /**

package/src/cli/commands/__fixtures__/audit-terraform/infra/.terraform/providers/lock.txt

@@ -0,0 +1 @@
+pretend-provider-lock-metadata

package/src/cli/commands/__fixtures__/audit-terraform/infra/main.tf

@@ -0,0 +1 @@
+resource "null_resource" "root" {}

package/src/cli/commands/__fixtures__/audit-terraform/infra/modules/foo/main.tf

@@ -0,0 +1 @@
+resource "null_resource" "foo" {}

package/src/cli/commands/__fixtures__/audit-terraform/infra/variables.tf

@@ -0,0 +1,3 @@
+variable "region" {
+  type = string
+}

package/src/cli/commands/__fixtures__/init-lexicon-output/package.json

@@ -8,8 +8,16 @@
     "dist/"
   ],
   "exports": {
-    ".": "./src/index.ts",
-    "./*": "./src/*",
+    ".": {
+      "development": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./src/index.ts"
+    },
+    "./*": {
+      "development": "./src/*.ts",
+      "types": "./dist/*.d.ts",
+      "default": "./src/*.ts"
+    },
     "./manifest": "./dist/manifest.json",
     "./meta": "./dist/meta.json",
     "./types": "./dist/types/index.d.ts"
@@ -18,8 +26,9 @@
     "generate": "npx tsx src/codegen/generate-cli.ts",
     "validate": "npx tsx src/validate-cli.ts",
     "docs": "npx tsx src/codegen/docs-cli.ts",
-    "build": "tsc -p tsconfig.build.json && tsc-alias -p tsconfig.build.json",
-    "prepack": "npm run generate && npm run validate && npm run build"
+    "build": "tsc -p tsconfig.build.json && tsc-alias -p tsconfig.build.json && find dist -type f \\( -name \"*.js\" -o -name \"*.js.map\" \\) -delete",
+    "prepack": "npm run generate && npm run bundle && npm run validate && npm run build",
+    "bundle": "tsx src/package-cli.ts"
   },
   "devDependencies": {
     "@intentius/chant": "*",

package/src/cli/commands/__fixtures__/init-lexicon-output/src/codegen/docs-cli.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env tsx
+import { generateDocs } from "./docs";
+
+await generateDocs({ verbose: true });

package/src/cli/commands/__fixtures__/init-lexicon-output/src/codegen/package.ts

@@ -15,6 +15,7 @@ export async function packageLexicon(options?: { verbose?: boolean; force?: bool
     buildManifest: (genResult) => ({
       name: "fixture",
       version: "0.0.1",
+      chantVersion: ">=0.1.0",
     }),
     srcDir,
     collectSkills: () => new Map(),

package/src/cli/commands/__fixtures__/init-lexicon-output/src/package-cli.ts

@@ -0,0 +1,21 @@
+#!/usr/bin/env tsx
+import { generate, writeGeneratedFiles } from "./codegen/generate";
+import { packageLexicon } from "./codegen/package";
+import { writeBundleSpec } from "@intentius/chant/codegen/package";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+
+const srcDir = dirname(fileURLToPath(import.meta.url));
+
+// 1. Generate src/generated/ files (writeGeneratedFiles resolves its own target)
+const genResult = await generate({ verbose: true });
+writeGeneratedFiles(genResult);
+
+// 2. Run package pipeline and write dist/
+const { spec, stats } = await packageLexicon({ verbose: true });
+
+const distDir = join(dirname(srcDir), "dist");
+writeBundleSpec(spec, distDir);
+
+console.error(`Packaged ${stats.resources} resources, ${stats.ruleCount} rules, ${stats.skillCount} skills`);
+console.error(`dist/ written to ${distDir}`);

package/src/cli/commands/__snapshots__/init-lexicon.test.ts.snap

@@ -97,6 +97,7 @@ export async function packageLexicon(options?: { verbose?: boolean; force?: bool
     buildManifest: (genResult) => ({
       name: "fixture",
       version: "0.0.1",
+      chantVersion: ">=0.1.0",
     }),
     srcDir,
     collectSkills: () => new Map(),

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

@@ -221,6 +221,35 @@ describe("auditCommand", () => {
     expect(none.exitCode).toBe(0);
   });
 
+  test("--fail-on error is a severity floor, decoupled from tier: a warning-severity finding does not fail it, an error-severity one does (chant #2113)", async () => {
+    const onlyWarning = await auditCommand({
+      path: REPO,
+      failOn: "error",
+      checksProvider: async () => [
+        {
+          id: "TEST900",
+          description: "always fires a warning, for the --fail-on error floor test",
+          check: () => [{ checkId: "TEST900", severity: "warning" as const, message: "a new rule shipped at warning" }],
+        },
+      ],
+    });
+    expect(onlyWarning.findings.some((f) => f.checkId === "TEST900")).toBe(true);
+    expect(onlyWarning.exitCode).toBe(0);
+
+    const withAnError = await auditCommand({
+      path: REPO,
+      failOn: "error",
+      checksProvider: async () => [
+        {
+          id: "TEST901",
+          description: "always fires an error, for the --fail-on error floor test",
+          check: () => [{ checkId: "TEST901", severity: "error" as const, message: "an actual error" }],
+        },
+      ],
+    });
+    expect(withAnError.exitCode).toBe(1);
+  });
+
   test("--tier merge-worthy filters out report-only findings", async () => {
     const all = await auditCommand({ path: REPO, tier: "all" });
     const mw = await auditCommand({ path: REPO, tier: "merge-worthy" });
@@ -267,12 +296,11 @@ describe("auditCommand", () => {
       expect(result.output).toContain("k8s/deploy.yaml  ->  k8s");
       expect(result.output).toContain("infra/stack.json  ->  aws");
       expect(result.output).toContain("Dockerfile  ->  docker");
-      expect(result.output).toContain("infra/main.tf  ->  terraform (not audited; see chant carve)");
-      // The install line names only the lexicons the files wanted, never terraform.
+      expect(result.output).toContain("infra/main.tf  ->  terraform");
+      // The install line names every lexicon the files wanted, terraform included.
       expect(result.output).toContain(
-        `npx -p @intentius/chant -p @intentius/chant-lexicon-github -p @intentius/chant-lexicon-docker -p @intentius/chant-lexicon-aws -p @intentius/chant-lexicon-k8s chant audit ${MIXED}`,
+        `npx -p @intentius/chant -p @intentius/chant-lexicon-github -p @intentius/chant-lexicon-docker -p @intentius/chant-lexicon-terraform -p @intentius/chant-lexicon-aws -p @intentius/chant-lexicon-k8s chant audit ${MIXED}`,
       );
-      expect(result.output).not.toContain("chant-lexicon-terraform");
     });
 
     test("zero lexicons with --json: status no-lexicons plus the unclaimed list and install line", async () => {
@@ -282,7 +310,7 @@ describe("auditCommand", () => {
       const json = JSON.parse(result.output);
       expect(json.status).toBe("no-lexicons");
       expect(json.findings).toEqual([]);
-      expect(json.missingLexicons).toEqual(["github", "docker", "aws", "k8s"]);
+      expect(json.missingLexicons).toEqual(["github", "docker", "terraform", "aws", "k8s"]);
       expect(json.unclaimed).toContainEqual({ path: "k8s/deploy.yaml", lexicon: "k8s" });
       expect(json.unclaimed).toContainEqual({ path: "infra/main.tf", lexicon: "terraform" });
       expect(json.install).toMatch(/^npx -p @intentius\/chant /);
@@ -307,9 +335,9 @@ describe("auditCommand", () => {
       expect(result.status).toBe("ok");
       expect(result.exitCode).toBe(0);
       expect(result.scanned).toEqual([".github/workflows/ci.yml"]);
-      expect(result.output).toMatch(/^Note: 3 files look like docker\/aws\/k8s but those lexicons are not installed, so they were skipped \(npm i @intentius\/chant-lexicon-docker @intentius\/chant-lexicon-aws @intentius\/chant-lexicon-k8s\)\./);
-      expect(result.output).toContain("1 Terraform file skipped; the audit does not read HCL (see chant carve).");
+      expect(result.output).toMatch(/^Note: 4 files look like docker\/terraform\/aws\/k8s but those lexicons are not installed, so they were skipped \(npm i @intentius\/chant-lexicon-docker @intentius\/chant-lexicon-terraform @intentius\/chant-lexicon-aws @intentius\/chant-lexicon-k8s\)\./);
       expect(result.unclaimed).toContainEqual({ path: "k8s/deploy.yaml", lexicon: "k8s" });
+      expect(result.unclaimed).toContainEqual({ path: "infra/main.tf", lexicon: "terraform" });
     });
 
     test("partial with --json: status ok and the unclaimed files ride along", async () => {
@@ -320,12 +348,13 @@ describe("auditCommand", () => {
       expect(json.unclaimed.map((u: { lexicon: string }) => u.lexicon).sort()).toEqual(["aws", "docker", "k8s", "terraform"]);
     });
 
-    test("all lexicons loaded: no coverage note, no unclaimed (terraform aside)", async () => {
+    test("every installable lexicon loaded: nothing is unclaimed, and the terraform root is scanned as one bundle (#2083)", async () => {
       const result = await auditCommand({ path: MIXED, plugins: await loadAuditPlugins() });
       expect(result.status).toBe("ok");
-      expect(result.unclaimed).toEqual([{ path: "infra/main.tf", lexicon: "terraform" }]);
-      expect(result.output).not.toContain("not installed");
-      expect(result.scanned.sort()).toEqual([".github/workflows/ci.yml", "Dockerfile", "infra/stack.json", "k8s/deploy.yaml"]);
+      expect(result.unclaimed).toEqual([]);
+      expect(result.output).not.toContain("looks like terraform");
+      // `infra` is the terraform root-module bundle (one input per directory of `.tf` files).
+      expect(result.scanned.sort()).toEqual([".github/workflows/ci.yml", "Dockerfile", "infra", "infra/stack.json", "k8s/deploy.yaml"]);
     });
 
     test("installLine puts every lexicon on the same npx -p path", () => {
@@ -441,6 +470,51 @@ describe("auditCommand", () => {
     expect(valid).toBe(true);
   });
 
+  describe("TF001's missing-resource shape renders in all three reporters (chant #2113)", () => {
+    const dir = join(tmpdir(), `chant-audit-tf-missing-${process.pid}`);
+
+    function setup(): void {
+      mkdirSync(join(dir, "infra"), { recursive: true });
+      writeFileSync(join(dir, "infra/main.tf"), 'terraform {\n  required_version = ">= 1.5.0"\n}\n');
+    }
+    function teardown(): void {
+      rmSync(dir, { recursive: true, force: true });
+    }
+
+    test("stylish names the missing kind and scope instead of falling back to entity", async () => {
+      setup();
+      const result = await auditCommand({ path: dir, format: "stylish" });
+      expect(result.output).toContain("(missing backend in audit-root)");
+      teardown();
+    });
+
+    test("json carries `missing` on the finding", async () => {
+      setup();
+      const result = await auditCommand({ path: dir, format: "json" });
+      const doc = JSON.parse(result.output) as { findings: Array<{ checkId: string; missing?: { kind: string; scope: string } }> };
+      const tf001 = doc.findings.find((f) => f.checkId === "TF001");
+      expect(tf001?.missing).toEqual({ kind: "backend", scope: "audit-root" });
+      teardown();
+    });
+
+    test("sarif carries `missing` in the result's properties, and still validates against the SARIF schema", async () => {
+      setup();
+      const result = await auditCommand({ path: dir, format: "sarif" });
+      const doc = JSON.parse(result.output) as {
+        runs: Array<{ results: Array<{ ruleId: string; properties?: { missing?: { kind: string; scope: string } } }> }>;
+      };
+      const tf001 = doc.runs[0].results.find((r) => r.ruleId === "TF001");
+      expect(tf001?.properties?.missing).toEqual({ kind: "backend", scope: "audit-root" });
+
+      const ajv = new Ajv({ strict: false, allErrors: true });
+      const validate = ajv.compile(loadSarifSchema() as object);
+      const valid = validate(doc);
+      if (!valid) throw new Error(ajv.errorsText(validate.errors));
+      expect(valid).toBe(true);
+      teardown();
+    });
+  });
+
   test("sarif schema validation also holds for the empty-result case (no findings)", async () => {
     const repo = fileURLToPath(new URL("./__fixtures__/audit-fountain-clean", import.meta.url));
     const result = await auditCommand({ path: repo, format: "sarif" });
@@ -555,6 +629,82 @@ describe("secrets detection (#443)", () => {
   });
 });
 
+describe("Terraform HCL suppression (chant #2111)", () => {
+  function tmpRepo(): string {
+    const dir = join(tmpdir(), `chant-audit-tf-suppress-${process.pid}-${Math.random().toString(36).slice(2)}`);
+    mkdirSync(dir, { recursive: true });
+    mkdirSync(join(dir, "infra"), { recursive: true });
+    return dir;
+  }
+
+  const BACKENDLESS = 'terraform {\n  required_version = ">= 1.5.0"\n}\n';
+
+  async function auditTerraform(dir: string): Promise<Awaited<ReturnType<typeof auditCommand>>> {
+    const all = await loadAuditPlugins();
+    return auditCommand({ path: dir, plugins: all.filter((p) => p.name === "terraform"), format: "json" });
+  }
+
+  test("chant-ignore-block suppresses TF001 through chant audit", async () => {
+    const dir = tmpRepo();
+    writeFileSync(join(dir, "infra", "main.tf"), `# chant-ignore-block: TF001\n${BACKENDLESS}`);
+    const result = await auditTerraform(dir);
+    expect(result.findings.map((f) => f.checkId)).not.toContain("TF001");
+    expect(result.suppressedCount).toBe(1);
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("a plain chant-ignore on the same block also suppresses TF001 through chant audit", async () => {
+    const dir = tmpRepo();
+    writeFileSync(join(dir, "infra", "main.tf"), `# chant-ignore: TF001\n${BACKENDLESS}`);
+    const result = await auditTerraform(dir);
+    expect(result.findings.map((f) => f.checkId)).not.toContain("TF001");
+    expect(result.suppressedCount).toBe(1);
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test('"all" suppresses TF001 through chant audit', async () => {
+    const dir = tmpRepo();
+    writeFileSync(join(dir, "infra", "main.tf"), `# chant-ignore-block: all\n${BACKENDLESS}`);
+    const result = await auditTerraform(dir);
+    expect(result.findings.map((f) => f.checkId)).not.toContain("TF001");
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("chant-ignore-file at the top of the file suppresses TF001 through chant audit", async () => {
+    const dir = tmpRepo();
+    writeFileSync(join(dir, "infra", "main.tf"), `# chant-ignore-file: TF001\n${BACKENDLESS}`);
+    const result = await auditTerraform(dir);
+    expect(result.findings.map((f) => f.checkId)).not.toContain("TF001");
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("a chant-ignore-file NOT at the top has no effect and is reported through chant audit", async () => {
+    const dir = tmpRepo();
+    writeFileSync(join(dir, "infra", "main.tf"), `# a header\n# chant-ignore-file: TF001\n${BACKENDLESS}`);
+    const result = await auditTerraform(dir);
+    expect(result.findings.map((f) => f.checkId)).toContain("TF001"); // still fires
+    expect(result.findings.map((f) => f.checkId)).toContain("SUPP002");
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("a directive naming a different rule id does not suppress TF001 through chant audit", async () => {
+    const dir = tmpRepo();
+    writeFileSync(join(dir, "infra", "main.tf"), `# chant-ignore-block: TF010\n${BACKENDLESS}`);
+    const result = await auditTerraform(dir);
+    expect(result.findings.map((f) => f.checkId)).toContain("TF001");
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("an already-expired suppression no longer suppresses TF001 and is reported through chant audit", async () => {
+    const dir = tmpRepo();
+    writeFileSync(join(dir, "infra", "main.tf"), `# chant-ignore-block: TF001 exp:2020-01-01\n${BACKENDLESS}`);
+    const result = await auditTerraform(dir);
+    expect(result.findings.map((f) => f.checkId)).toContain("TF001"); // still fires: expired
+    expect(result.findings.map((f) => f.checkId)).toContain("SUPP001");
+    rmSync(dir, { recursive: true, force: true });
+  });
+});
+
 describe("Wrangler config audit (#446)", () => {
   function tmpRepo(): string {
     const dir = join(tmpdir(), `chant-audit-wrangler-${process.pid}-${Math.random().toString(36).slice(2)}`);
@@ -649,3 +799,31 @@ describe("nginx config audit (#1979)", () => {
     rmSync(dir, { recursive: true, force: true });
   });
 });
+
+describe("committed Terraform state (TF023, #2110)", () => {
+  function tmpRepo(): string {
+    const dir = join(tmpdir(), `chant-audit-tfstate-${process.pid}-${Math.random().toString(36).slice(2)}`);
+    mkdirSync(dir, { recursive: true });
+    return dir;
+  }
+
+  test("fires end to end on a directory with a tracked state file, with no lexicon installed", async () => {
+    const dir = tmpRepo();
+    writeFileSync(join(dir, "main.tf"), 'resource "null_resource" "a" {}\n');
+    writeFileSync(join(dir, "terraform.tfstate"), JSON.stringify({ version: 4, resources: [] }));
+    const result = await auditCommand({ path: dir, plugins: [] });
+    expect(result.findings.map((f) => f.checkId)).toContain("TF023");
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("says nothing when the state is ignored rather than committed", async () => {
+    const dir = tmpRepo();
+    writeFileSync(join(dir, ".gitignore"), "*.tfstate\n.terraform/\n");
+    writeFileSync(join(dir, "main.tf"), 'resource "null_resource" "a" {}\n');
+    writeFileSync(join(dir, "terraform.tfstate"), JSON.stringify({ version: 4, resources: [] }));
+    mkdirSync(join(dir, ".terraform"), { recursive: true });
+    const result = await auditCommand({ path: dir, plugins: [] });
+    expect(result.findings.map((f) => f.checkId)).not.toContain("TF023");
+    rmSync(dir, { recursive: true, force: true });
+  });
+});