@intentius/chant 0.78.0 → 0.80.0

package/dist/workspace/records.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Records read through a record kind (#2524 D4), first-test slice (#2546).
+ *
+ * A record kind is data. It says where its records live, which JSON Schema
+ * they follow and which of their states are closed. This module reads every
+ * record a kind locates, parses its front matter as the JSON subset of YAML,
+ * validates it against the kind's schema and derives supersession from the
+ * records' own `supersedes` links. It never writes a record.
+ *
+ * A record that fails any of that is still returned, with reason codes, and the
+ * read succeeds. Only a failure to read the kind, its schema or the revision is
+ * an error. Seals, attestation and the workspace declaration come later (#2546,
+ * #2534); nothing here needs a `chant.workspace.json`.
+ *
+ * Everything under `workspace/` loads only when a `chant workspace` command
+ * runs. The level-0 goldens (#2526) fail if a level-0 command loads it.
+ */
+import { z } from "zod";
+import type { RecordSource } from "./record-source.js";
+/**
+ * Why one record is not valid. The list is closed: a reader may switch on it,
+ * and a new code is a contract change (#2536).
+ */
+export declare const RECORD_REASON_CODES: readonly ["record-unparseable", "record-schema-invalid", "record-id-duplicate", "record-supersedes-unknown", "record-supersedes-conflict"];
+export type RecordReasonCode = (typeof RECORD_REASON_CODES)[number];
+/**
+ * Why the read as a whole failed. Also closed. The command exits 1 with one of
+ * these and returns no records.
+ */
+export declare const READ_ERROR_CODES: readonly ["kind-unreadable", "kind-invalid", "schema-unreadable", "schema-id-mismatch", "schema-invalid", "location-missing", "not-a-git-repository", "revision-unknown"];
+export type ReadErrorCode = (typeof READ_ERROR_CODES)[number];
+export declare class RecordReadError extends Error {
+    readonly code: ReadErrorCode;
+    constructor(code: ReadErrorCode, message: string);
+}
+/** The data a kind file exports as `recordKind`. */
+export declare const recordKindSchema: z.ZodObject<{
+    name: z.ZodString;
+    location: z.ZodObject<{
+        dir: z.ZodString;
+        match: z.ZodString;
+    }, z.core.$strict>;
+    format: z.ZodLiteral<"markdown-front-matter">;
+    schema: z.ZodObject<{
+        id: z.ZodString;
+        path: z.ZodString;
+    }, z.core.$strict>;
+    idField: z.ZodString;
+    stateField: z.ZodString;
+    states: z.ZodArray<z.ZodString>;
+    closedStates: z.ZodArray<z.ZodString>;
+    supersedes: z.ZodObject<{
+        field: z.ZodString;
+        key: z.ZodString;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type RecordKind = z.infer<typeof recordKindSchema>;
+/** A kind as loaded: its data, where it came from, and its schema. */
+export interface LoadedRecordKind {
+    kind: RecordKind;
+    /** Absolute path of the kind file. */
+    file: string;
+    /** Absolute path of the records directory in the working tree. */
+    dir: string;
+    schema: Record<string, unknown>;
+}
+/** Load a kind file and the schema it names. `path` is resolved against `cwd`. */
+export declare function loadRecordKind(path: string, cwd?: string): Promise<LoadedRecordKind>;
+export type FrontMatter = {
+    ok: true;
+    value: Record<string, unknown>;
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * The front matter of a Markdown file, limited to what YAML and JSON share
+ * (#2524 D4). Line endings are normalised first. Aliases, and any value JSON
+ * cannot hold, are refused, so the same text always reads as the same JSON.
+ */
+export declare function parseFrontMatter(text: string): FrontMatter;
+export interface RecordReason {
+    code: RecordReasonCode;
+    message: string;
+}
+export interface RecordEntry {
+    /** The record's id, or null when it could not be read. */
+    id: string | null;
+    /** Path from the repository root (or the working directory outside git), with `/` separators. */
+    path: string;
+    /** The record's state as written, or null when it could not be read. */
+    state: string | null;
+    valid: boolean;
+    reasons: RecordReason[];
+    /** The id of the closed record whose `supersedes` link replaces this one, or null. */
+    supersededBy: string | null;
+    /** The front matter as JSON, or null when it could not be parsed. */
+    data: Record<string, unknown> | null;
+}
+export interface ReadRecordsOptions {
+    /** Where record paths are reported from, and what `source` reads relative to. */
+    root: string;
+    source: RecordSource;
+    /** Leave out records a closed record supersedes. */
+    current?: boolean;
+}
+export interface ReadRecordsResult {
+    records: RecordEntry[];
+    summary: {
+        total: number;
+        valid: number;
+        invalid: number;
+        superseded: number;
+    };
+}
+/** Read every record `loaded` locates, through `options.source`. */
+export declare function readRecords(loaded: LoadedRecordKind, options: ReadRecordsOptions): Promise<ReadRecordsResult>;
+//# sourceMappingURL=records.d.ts.map

package/dist/workspace/records.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"records.d.ts","sourceRoot":"","sources":["../../src/workspace/records.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAKH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAIpD;;;GAGG;AACH,eAAO,MAAM,mBAAmB,4IAWtB,CAAC;AACX,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEpE;;;GAGG;AACH,eAAO,MAAM,gBAAgB,2KAiBnB,CAAC;AACX,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE9D,qBAAa,eAAgB,SAAQ,KAAK;IAEtC,QAAQ,CAAC,IAAI,EAAE,aAAa;gBAAnB,IAAI,EAAE,aAAa,EAC5B,OAAO,EAAE,MAAM;CAKlB;AAMD,oDAAoD;AACpD,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;kBAoCzB,CAAC;AAEL,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D,sEAAsE;AACtE,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,UAAU,CAAC;IACjB,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAmBD,kFAAkF;AAClF,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,GAAE,MAAsB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAiCzG;AAID,MAAM,MAAM,WAAW,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAExG;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAgB1D;AA0BD,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,gBAAgB,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,0DAA0D;IAC1D,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAClB,iGAAiG;IACjG,IAAI,EAAE,MAAM,CAAC;IACb,wEAAwE;IACxE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,KAAK,EAAE,OAAO,CAAC;IACf,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,sFAAsF;IACtF,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CACtC;AAED,MAAM,WAAW,kBAAkB;IACjC,iFAAiF;IACjF,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,YAAY,CAAC;IACrB,oDAAoD;IACpD,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,OAAO,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;CAChF;AAsBD,oEAAoE;AACpE,wBAAsB,WAAW,CAAC,MAAM,EAAE,gBAAgB,EAAE,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAgFnH"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant",
-  "version": "0.78.0",
+  "version": "0.80.0",
   "description": "Declarative infrastructure-as-code toolkit — TypeScript on Node.js",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -91,6 +91,7 @@
   },
   "dependencies": {
     "@dagrejs/dagre": "^3.0.0",
+    "ajv": "^8.20.0",
     "esbuild": "^0.28.1",
     "fflate": "^0.8.2",
     "js-yaml": "^4.3.1",
@@ -100,8 +101,7 @@
     "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@cdktn/hcl2json": "^0.24.0",
-    "ajv": "^8.20.0"
+    "@cdktn/hcl2json": "^0.24.0"
   },
   "overrides": {
     "esbuild": "^0.28.1"

package/src/audit/core.ts

@@ -27,6 +27,7 @@ import { applyInlineSuppressions, type SuppressionMetaFinding } from "../lint/su
 import type { SerializerResult } from "../serializer";
 import type { AuditEntitiesInput, LexiconPlugin } from "../lexicon";
 import type { Declarable } from "../declarable";
+import { lexiconModulePath, lexiconPackagesToInstall, lexiconSourceLabel } from "../lexicon-module";
 
 /**
  * The lexicon whose post-synth checks run against an audited file. Any lexicon
@@ -155,9 +156,19 @@ async function load(names: string[]): Promise<LexiconPlugin[]> {
     const { loadPlugins } = await import("../cli/plugins");
     return await loadPlugins(names);
   } catch (err) {
-    const pkgs = names.map((n) => `@intentius/chant-lexicon-${n}`).join(" ");
+    const detail = err instanceof Error ? err.message : String(err);
+    // chant#2578 — a lexicon declared by path in chant.config.ts has no
+    // package: name its module and print no install line for it.
+    const pkgs = lexiconPackagesToInstall(names);
+    const paths = names.filter((n) => lexiconModulePath(n) !== undefined).map((n) => lexiconSourceLabel(n));
+    if (pkgs.length === 0) {
+      throw new MissingLexiconError(
+        `Could not load the lexicon module ${paths.join(", ")} needed to audit ${names.join("/")} workflows.\n(${detail})`,
+      );
+    }
+    const fromPath = paths.length > 0 ? ` The lexicon module ${paths.join(", ")} is declared by path and has nothing to install.` : "";
     throw new MissingLexiconError(
-      `Missing lexicon package needed to audit ${names.join("/")} workflows. Install it with: npm i ${pkgs}\n(${err instanceof Error ? err.message : String(err)})`,
+      `Missing lexicon package needed to audit ${names.join("/")} workflows. Install it with: npm i ${pkgs.join(" ")}${fromPath}\n(${detail})`,
     );
   }
 }

package/src/audit/discover.ts

@@ -40,7 +40,7 @@ import { parseYAML } from "../yaml";
 import type { LexiconPlugin } from "../lexicon";
 import type { AuditInput, AuditLexicon } from "./core";
 import { isNginxConfigPath } from "./nginx";
-import { gitignoreCoversTerraformState, isTerraformStatePath } from "./terraform-state";
+import { gitignoreCoversTerraformState, isTerraformStatePath, nestedGitignoreCovering } from "./terraform-state";
 
 /** Lexicons the auditor knows how to detect and run checks for. */
 export const AUDIT_LEXICONS = ["github", "gitlab", "forgejo", "k8s", "docker", "aws", "azure", "gcp", "helm", "fountain", "terraform"] as const;
@@ -74,34 +74,61 @@ const WALK_SKIP = new Set(["node_modules", ".git", "dist"]);
 const TERRAFORM_WORK_DIR = ".terraform";
 /** Dot-directories the walk descends into anyway (CI lives here). */
 const WALK_DOT_DIRS = new Set([".github", ".forgejo"]);
-const MAX_WALK_FILES = 1000;
+/**
+ * How many files the local walk takes before it stops. Every file it reaches
+ * counts, candidate or not, so a tree with a large `docs/` or `assets/` can hit
+ * it long before a thousand auditable files. `--max-files` raises it (#2528).
+ */
+export const DEFAULT_MAX_WALK_FILES = 1000;
 /** Skip absurdly large files before parsing — mirrors the fetch layer's caps. */
 const MAX_FILE_BYTES = 2 * 1024 * 1024;
 
-/** Recursively collect file paths under a root, skipping noise dirs. */
-function walkFiles(dir: string, out: string[]): void {
-  if (out.length >= MAX_WALK_FILES) return;
+/** The walk's limit, and whether it left anything behind because of it. */
+interface WalkState {
+  limit: number;
+  truncated: boolean;
+}
+
+/**
+ * Recursively collect file paths under a root, skipping noise dirs.
+ *
+ * Stops at `state.limit` paths. Once full it keeps looking only until it meets
+ * one more path it would have taken, which is what sets `truncated`: a tree of
+ * exactly `limit` files, or one whose remaining entries are all skipped
+ * directories, was not truncated. The paths it returns are the same first
+ * `limit` either way.
+ */
+function walkFiles(dir: string, out: string[], state: WalkState): void {
+  if (state.truncated) return;
   let entries;
   try {
     entries = readdirSync(dir, { withFileTypes: true });
   } catch {
     return;
   }
+  const take = (path: string): boolean => {
+    if (out.length >= state.limit) {
+      state.truncated = true;
+      return false;
+    }
+    out.push(path);
+    return true;
+  };
   for (const e of entries.sort((a, b) => (a.name < b.name ? -1 : 1))) {
-    if (out.length >= MAX_WALK_FILES) return;
+    if (state.truncated) return;
     if (e.name.startsWith(".") && e.isDirectory() && !WALK_DOT_DIRS.has(e.name)) {
       // `.terraform/` is never descended into: it is machine-generated,
       // routinely hundreds of megabytes of provider binaries, and nothing in
       // it is worth reading. Its presence is itself the finding (TF023), so
       // the directory path alone is recorded and `collectCandidates` hands it
       // on with no content.
-      if (e.name === TERRAFORM_WORK_DIR) out.push(join(dir, e.name));
+      if (e.name === TERRAFORM_WORK_DIR && !take(join(dir, e.name))) return;
       continue;
     }
     if (WALK_SKIP.has(e.name)) continue;
     const full = join(dir, e.name);
-    if (e.isDirectory()) walkFiles(full, out);
-    else out.push(full);
+    if (e.isDirectory()) walkFiles(full, out, state);
+    else if (!take(full)) return;
   }
 }
 
@@ -594,10 +621,49 @@ export function discoverByDetection(root: string, plugins: DetectPlugin[]): Audi
   return classifyFiles(collectCandidates(root), plugins, { baseDir: root });
 }
 
+/** Options for the local walk. */
+export interface CandidateWalkOptions {
+  /** Files the walk takes before it stops, counting every file. Defaults to {@link DEFAULT_MAX_WALK_FILES}. */
+  maxFiles?: number;
+}
+
+/**
+ * A TF023 path the root `.gitignore` does not cover but a `.gitignore` in a
+ * directory between it and the scan root does (#2528). TF023 reports it today;
+ * from the next release, which reads every such `.gitignore`, it will not.
+ */
+export interface NestedGitignoreChange {
+  /** The TF023 path, relative to the scan root. */
+  path: string;
+  /** The nested `.gitignore` that ignores it, relative to the scan root. */
+  gitignore: string;
+}
+
+/** What the local walk read, plus what it knows about its own limits. */
+export interface CandidateWalk {
+  files: RepoFile[];
+  /** The limit the walk ran with. */
+  maxFiles: number;
+  /** True when the walk stopped at `maxFiles` with files left unread. */
+  truncated: boolean;
+  /** TF023 paths whose finding changes once nested `.gitignore` files are read. */
+  nestedGitignore: NestedGitignoreChange[];
+}
+
 /** The walk half of `discoverByDetection`: candidate files read into memory, paths relative to the root. */
 export function collectCandidates(root: string): RepoFile[] {
+  return walkCandidates(root).files;
+}
+
+/**
+ * `collectCandidates` with the facts the audit CLI warns about: whether the
+ * walk was truncated, and which TF023 paths a nested `.gitignore` would drop.
+ * Neither changes `files`; the CLI prints them on stderr (#2528).
+ */
+export function walkCandidates(root: string, opts: CandidateWalkOptions = {}): CandidateWalk {
   const all: string[] = [];
-  walkFiles(root, all);
+  const state: WalkState = { limit: opts.maxFiles ?? DEFAULT_MAX_WALK_FILES, truncated: false };
+  walkFiles(root, all, state);
   // TF023 reads paths, not content: a `.tfstate` can be tens of megabytes of
   // machine-generated JSON, and the finding is that it is in the repository at
   // all. The root `.gitignore` is what separates "committed" from "merely on
@@ -606,11 +672,23 @@ export function collectCandidates(root: string): RepoFile[] {
   // local audit. A fetched repository has no such ambiguity (its file list is
   // the tracked files) and is not filtered.
   const gitignore = readSafe(join(root, ".gitignore")) ?? "";
+  // Only the root one decides, for now. The nested ones are read to say which
+  // findings the next release, which honours them, will stop reporting.
+  const nestedBodies = new Map<string, string | undefined>();
+  const nestedGitignoreAt = (dir: string): string | undefined => {
+    if (!nestedBodies.has(dir)) nestedBodies.set(dir, readSafe(join(root, dir, ".gitignore")));
+    return nestedBodies.get(dir);
+  };
   const files: RepoFile[] = [];
+  const nestedGitignore: NestedGitignoreChange[] = [];
   for (const full of all) {
     const path = relative(root, full);
     if (isTerraformStatePath(path)) {
-      if (!gitignoreCoversTerraformState(gitignore, path)) files.push({ path, content: "" });
+      if (!gitignoreCoversTerraformState(gitignore, path)) {
+        files.push({ path, content: "" });
+        const dir = nestedGitignoreCovering(path, nestedGitignoreAt);
+        if (dir !== undefined) nestedGitignore.push({ path, gitignore: `${dir}/.gitignore` });
+      }
       continue;
     }
     // `.tf` is read locally so `classifyTerraform` can bundle real content.
@@ -624,5 +702,5 @@ export function collectCandidates(root: string): RepoFile[] {
     const content = readSafe(full);
     if (content !== undefined) files.push({ path, content });
   }
-  return files;
+  return { files, maxFiles: state.limit, truncated: state.truncated, nestedGitignore };
 }

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

@@ -8,9 +8,10 @@ import {
   isTerraformStateFile,
   isTerraformStatePath,
   isTerraformWorkDir,
+  nestedGitignoreCovering,
   type ScannableFile,
 } from "./terraform-state";
-import { collectCandidates } from "./discover";
+import { collectCandidates, walkCandidates } from "./discover";
 import { RULE_CATALOG, RULE_CATEGORY } from "./catalog";
 
 const file = (path: string): ScannableFile => ({ path, content: "" });
@@ -142,3 +143,87 @@ describe("discovery hands TF023 its paths, and nothing else changes", () => {
     rmSync(dir, { recursive: true, force: true });
   });
 });
+
+describe("nestedGitignoreCovering (#2528)", () => {
+  const reader = (bodies: Record<string, string>) => (dir: string) => bodies[dir];
+
+  test("finds a .gitignore between the path and the root, matched relative to its own directory", () => {
+    expect(nestedGitignoreCovering("infra/prod/terraform.tfstate", reader({ infra: "*.tfstate\n" }))).toBe("infra");
+    expect(nestedGitignoreCovering("infra/.terraform", reader({ infra: ".terraform/\n" }))).toBe("infra");
+  });
+
+  test("prefers the nearest one, as git does", () => {
+    const bodies = reader({ infra: "*.tfstate\n", "infra/prod": "*.tfstate\n" });
+    expect(nestedGitignoreCovering("infra/prod/terraform.tfstate", bodies)).toBe("infra/prod");
+  });
+
+  test("never reads the root's own .gitignore, and ignores one that does not cover the path", () => {
+    const bodies = reader({ "": "*.tfstate\n", infra: "*.log\n", other: "*.tfstate\n" });
+    expect(nestedGitignoreCovering("infra/terraform.tfstate", bodies)).toBeUndefined();
+    expect(nestedGitignoreCovering("terraform.tfstate", bodies)).toBeUndefined();
+  });
+});
+
+describe("walkCandidates reports what the next release changes, and changes nothing now (#2528)", () => {
+  function writeFiles(dir: string, n: number): void {
+    mkdirSync(join(dir, "docs"), { recursive: true });
+    for (let i = 0; i < n; i++) writeFileSync(join(dir, "docs", `${String(i).padStart(3, "0")}.md`), "x");
+  }
+
+  test("a walk that reaches its limit with files left says it was truncated, and keeps the same first files", () => {
+    const dir = tmpRepo();
+    writeFiles(dir, 5);
+    writeFileSync(join(dir, "terraform.tfstate"), "{}");
+    const cut = walkCandidates(dir, { maxFiles: 5 });
+    expect(cut.truncated).toBe(true);
+    expect(cut.maxFiles).toBe(5);
+    // `docs/` sorts first, so the state file is the one left behind.
+    expect(cut.files).toEqual([]);
+    const whole = walkCandidates(dir);
+    expect(whole.truncated).toBe(false);
+    expect(whole.maxFiles).toBe(1000);
+    expect(whole.files.map((f) => f.path)).toEqual(["terraform.tfstate"]);
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("a tree of exactly the limit, or one whose remainder is skipped, is not truncated", () => {
+    const dir = tmpRepo();
+    writeFiles(dir, 5);
+    mkdirSync(join(dir, "node_modules", "x"), { recursive: true });
+    writeFileSync(join(dir, "node_modules", "x", "index.js"), "");
+    mkdirSync(join(dir, "empty"), { recursive: true });
+    expect(walkCandidates(dir, { maxFiles: 5 }).truncated).toBe(false);
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("a state file a nested .gitignore ignores is still a candidate, and is named for the warning", () => {
+    const dir = tmpRepo();
+    mkdirSync(join(dir, "infra", ".terraform"), { recursive: true });
+    writeFileSync(join(dir, "infra", ".gitignore"), "*.tfstate\n.terraform/\n");
+    writeFileSync(join(dir, "infra", "terraform.tfstate"), "{}");
+    const walk = walkCandidates(dir);
+    expect(walk.files.map((f) => f.path).sort()).toEqual(["infra/.terraform", "infra/terraform.tfstate"]);
+    expect(auditTerraformState(walk.files)).toHaveLength(2);
+    expect(walk.nestedGitignore).toEqual([
+      { path: "infra/.terraform", gitignore: "infra/.gitignore" },
+      { path: "infra/terraform.tfstate", gitignore: "infra/.gitignore" },
+    ]);
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("nothing is named when the root .gitignore already drops the path, or no nested one covers it", () => {
+    const dir = tmpRepo();
+    mkdirSync(join(dir, "a"), { recursive: true });
+    mkdirSync(join(dir, "b"), { recursive: true });
+    writeFileSync(join(dir, ".gitignore"), "*.tfstate.backup\n");
+    writeFileSync(join(dir, "a", ".gitignore"), "*.tfstate.backup\n*.log\n");
+    writeFileSync(join(dir, "a", "terraform.tfstate"), "{}");
+    writeFileSync(join(dir, "a", "terraform.tfstate.backup"), "{}");
+    // A sibling's .gitignore is not between `a/` and the root.
+    writeFileSync(join(dir, "b", ".gitignore"), "*.tfstate\n");
+    const walk = walkCandidates(dir);
+    expect(walk.files.map((f) => f.path)).toEqual(["a/terraform.tfstate"]);
+    expect(walk.nestedGitignore).toEqual([]);
+    rmSync(dir, { recursive: true, force: true });
+  });
+});

package/src/audit/terraform-state.ts

@@ -22,6 +22,8 @@
  * walk that decides which paths reach here is `discover.ts`'s
  * `collectCandidates`, which is also where a locally ignored path is dropped:
  * see `isTerraformStatePath` there and `gitignoreCoversTerraformState` below.
+ * Only the root `.gitignore` drops a path today; `nestedGitignoreCovering`
+ * finds the ones a nested `.gitignore` would drop from the next release.
  */
 
 import type { AuditFinding } from "./core";
@@ -83,6 +85,30 @@ export function gitignoreCoversTerraformState(gitignore: string, path: string):
   return false;
 }
 
+/**
+ * The nearest directory strictly between a TF023 path and the scan root whose
+ * `.gitignore` covers that path, or undefined. Each `.gitignore` is matched
+ * against the path relative to its own directory, the way git scopes it, with
+ * the same narrow matcher as the root one. `readGitignore` takes a directory
+ * relative to the scan root and returns its `.gitignore` body, if any.
+ *
+ * The walk does not act on this yet: today only the root `.gitignore` decides
+ * TF023, and the audit CLI uses this to warn about the findings that go away
+ * once every `.gitignore` is read (#2528).
+ */
+export function nestedGitignoreCovering(
+  path: string,
+  readGitignore: (dir: string) => string | undefined,
+): string | undefined {
+  const parts = path.split("/");
+  for (let depth = parts.length - 1; depth > 0; depth--) {
+    const dir = parts.slice(0, depth).join("/");
+    const body = readGitignore(dir);
+    if (body !== undefined && gitignoreCoversTerraformState(body, parts.slice(depth).join("/"))) return dir;
+  }
+  return undefined;
+}
+
 /**
  * Report TF023 for every committed state file and `.terraform/` directory in
  * the file list. One finding per path, and one for the `.terraform` directory

package/src/cli/command-group.ts

@@ -81,11 +81,18 @@ export interface CommandGroup {
  * (./conflict-check.ts) treats a collision as a hard, loud failure at
  * plugin-load time rather than a silently-ignored command group. Hand
  * maintained alongside the registry; update both together.
+ *
+ * `workspace` is reserved before core has the command (#2529, #2524 D12), so
+ * no lexicon can claim the word first and later be shadowed by it. Only a
+ * command-group name is reserved: a lexicon's own config field or flag
+ * called `workspace` (the terraform lexicon's root config has one) is
+ * untouched.
  */
 export const RESERVED_COMMAND_NAMES: ReadonlySet<string> = new Set([
   "build", "lint", "list", "describe", "import", "audit", "migrate", "carve",
   "init", "update", "doctor", "dev", "run", "graph", "vendor", "lifecycle",
   "lc", "components", "emulator", "serve", "operator", "approve",
+  "workspace",
 ]);
 
 /**

package/src/cli/commands/audit-walk-warnings.test.ts

@@ -0,0 +1,156 @@
+import { afterEach, beforeAll, describe, expect, test, vi } from "vitest";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { auditCommand, printAuditResult, type AuditCommandOptions } from "./audit";
+import { loadAuditPlugins } from "../../audit/discover";
+
+/**
+ * #2528's warning release. `chant audit` warns on stderr about the two changes
+ * the next release makes (#2525's exception list), and the report itself stays
+ * byte-identical: every test here that runs with a warning also runs the same
+ * tree without its cause and compares the JSON.
+ */
+
+const NOW = "2026-09-23T00:00:00.000Z";
+const dirs: string[] = [];
+
+function tmpRepo(): string {
+  const dir = mkdtempSync(join(tmpdir(), "chant-2528-"));
+  dirs.push(dir);
+  return dir;
+}
+
+afterEach(() => {
+  for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true });
+  vi.restoreAllMocks();
+});
+
+let plugins: Awaited<ReturnType<typeof loadAuditPlugins>>;
+
+// Loading every audit lexicon is the slow part; once, outside any one test's timeout.
+beforeAll(async () => {
+  plugins = await loadAuditPlugins();
+}, 120_000);
+
+function audit(path: string, extra: Partial<AuditCommandOptions> = {}) {
+  return auditCommand({ path, format: "json", now: NOW, toolVersion: "0.0.0", plugins, ...extra });
+}
+
+/** Print a result the way the CLI does, and split what reached each stream. */
+function printed(result: Awaited<ReturnType<typeof auditCommand>>): { stdout: string; stderr: string } {
+  const out: string[] = [];
+  const err: string[] = [];
+  vi.spyOn(console, "log").mockImplementation((s: string) => void out.push(s));
+  vi.spyOn(console, "error").mockImplementation((s: string) => void err.push(s));
+  printAuditResult(result);
+  vi.restoreAllMocks();
+  return { stdout: out.join("\n"), stderr: err.join("\n") };
+}
+
+describe("a truncated walk is warned about, not yet reported (#2528)", () => {
+  function treeWithTail(): string {
+    const dir = tmpRepo();
+    mkdirSync(join(dir, "a"), { recursive: true });
+    for (let i = 0; i < 5; i++) writeFileSync(join(dir, "a", `${i}.md`), "x");
+    writeFileSync(join(dir, "a", "terraform.tfstate"), "{}");
+    // Past the limit: a state file TF023 would report if the walk reached it.
+    mkdirSync(join(dir, "z"), { recursive: true });
+    writeFileSync(join(dir, "z", "terraform.tfstate"), "{}");
+    return dir;
+  }
+
+  test("the warning names the limit and --max-files, on stderr only", async () => {
+    const dir = treeWithTail();
+    const result = await audit(dir, { maxFiles: 6 });
+    expect(result.warnings).toHaveLength(1);
+    const { stdout, stderr } = printed(result);
+    expect(stdout).toBe(result.output);
+    expect(stderr).toContain(`the scan of ${dir} stopped at 6 files, so part of the tree was not audited.`);
+    expect(stderr).toContain("Raise it with --max-files <n>.");
+    expect(stderr).toContain("From the next release, text and JSON output will also report a truncated scan.");
+    expect(result.findings.map((f) => f.file)).toEqual(["a/terraform.tfstate"]);
+  });
+
+  test("the JSON and text reports are what the same tree gives without the files past the limit", async () => {
+    const dir = treeWithTail();
+    const truncatedJson = await audit(dir, { maxFiles: 6 });
+    const truncatedText = await audit(dir, { maxFiles: 6, format: "stylish" });
+    rmSync(join(dir, "z"), { recursive: true, force: true });
+    const wholeJson = await audit(dir, { maxFiles: 6 });
+    const wholeText = await audit(dir, { maxFiles: 6, format: "stylish" });
+    expect(wholeJson.warnings).toBeUndefined();
+    expect(truncatedJson.output).toBe(wholeJson.output);
+    expect(truncatedText.output).toBe(wholeText.output);
+    expect(printed(truncatedJson).stdout).toBe(printed(wholeJson).stdout);
+  });
+
+  test("--max-files raises the limit, and the default walk does not warn on a small tree", async () => {
+    const dir = treeWithTail();
+    const raised = await audit(dir, { maxFiles: 7 });
+    expect(raised.warnings).toBeUndefined();
+    expect(raised.findings.map((f) => f.file).sort()).toEqual(["a/terraform.tfstate", "z/terraform.tfstate"]);
+    expect((await audit(dir)).warnings).toBeUndefined();
+  });
+});
+
+describe("TF023 warns when a nested .gitignore would change its finding (#2528)", () => {
+  function nestedTree(nested: string | undefined): string {
+    const dir = tmpRepo();
+    mkdirSync(join(dir, "infra"), { recursive: true });
+    writeFileSync(join(dir, ".gitignore"), "node_modules/\n");
+    writeFileSync(join(dir, "infra", "main.tf"), 'resource "null_resource" "a" {}\n');
+    writeFileSync(join(dir, "infra", "terraform.tfstate"), "{}");
+    if (nested !== undefined) writeFileSync(join(dir, "infra", ".gitignore"), nested);
+    return dir;
+  }
+
+  test("fires for the file a nested .gitignore ignores, naming both, and TF023 still reports it", async () => {
+    const dir = nestedTree("*.tfstate\n");
+    const result = await audit(dir);
+    expect(result.findings.filter((f) => f.checkId === "TF023").map((f) => f.file)).toEqual(["infra/terraform.tfstate"]);
+    expect(result.warnings).toEqual([
+      {
+        file: "infra/terraform.tfstate",
+        message: "TF023 reports this path because chant audit reads only the root .gitignore, but infra/.gitignore ignores it.",
+        hint: "From the next release chant audit reads every .gitignore between a file and the scan root, and TF023 will no longer report this path.",
+      },
+    ]);
+    const { stdout, stderr } = printed(result);
+    expect(stdout).toBe(result.output);
+    expect(stderr).toContain("infra/terraform.tfstate");
+    expect(stderr).toContain("infra/.gitignore ignores it");
+  });
+
+  test("does not fire when the nested .gitignore does not cover the file", async () => {
+    const result = await audit(nestedTree("*.log\n"));
+    expect(result.findings.some((f) => f.checkId === "TF023")).toBe(true);
+    expect(result.warnings).toBeUndefined();
+  });
+
+  test("does not fire when the root .gitignore already drops the file", async () => {
+    const dir = nestedTree("*.tfstate\n");
+    writeFileSync(join(dir, ".gitignore"), "*.tfstate\n");
+    const result = await audit(dir);
+    expect(result.findings.some((f) => f.checkId === "TF023")).toBe(false);
+    expect(result.warnings).toBeUndefined();
+  });
+
+  test("stdout JSON and the text report are byte-identical with and without the nested .gitignore", async () => {
+    const dir = nestedTree("*.tfstate\n");
+    const withJson = await audit(dir);
+    const withText = await audit(dir, { format: "stylish" });
+    const withSarif = await audit(dir, { format: "sarif" });
+    rmSync(join(dir, "infra", ".gitignore"));
+    const withoutJson = await audit(dir);
+    const withoutText = await audit(dir, { format: "stylish" });
+    const withoutSarif = await audit(dir, { format: "sarif" });
+    expect(withJson.warnings).toHaveLength(1);
+    expect(withoutJson.warnings).toBeUndefined();
+    expect(withJson.output).toBe(withoutJson.output);
+    expect(withText.output).toBe(withoutText.output);
+    expect(withSarif.output).toBe(withoutSarif.output);
+    expect(printed(withJson).stdout).toBe(printed(withoutJson).stdout);
+    JSON.parse(printed(withJson).stdout);
+  });
+});