@intentius/chant 0.80.0 → 0.81.0

package/dist/workspace/trust/verify-cli.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `chant workspace verify [--base <rev>] [--head <rev>] [--require attested] [--json]`
+ * (#2547): check a change against the trust policy at its base. See ./verify.ts.
+ *
+ * Exit 0 when the change passes, 1 when it does not or cannot be checked.
+ */
+import type { CommandContext } from "../../cli/registry.js";
+export declare function runWorkspaceVerify(ctx: CommandContext): Promise<number>;
+//# sourceMappingURL=verify-cli.d.ts.map

package/dist/workspace/trust/verify-cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify-cli.d.ts","sourceRoot":"","sources":["../../../src/workspace/trust/verify-cli.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAOzD,wBAAsB,kBAAkB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAqB7E"}

package/dist/workspace/trust/verify.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Verify a change against the policy at its base (#2524 D5, Threat model).
+ *
+ * This is what CI runs on a protected branch: every commit in `base..head` is
+ * asked of the attestors with the policy read at base, so nothing the change
+ * does to its own copy of the policy counts. A change that edits the policy
+ * (the signers file or `.chant/trust.json`) is a protected write: every commit
+ * that touches those files must be attested by a signer the base policy
+ * trusts, and by an admin when the base policy grants the admin role.
+ *
+ * Attestation is opt-in (#2525 rule 6). Without a signers file at base the
+ * check passes and says so, unless `--require attested` asks for more.
+ */
+import { type CommitAttestor, type ProvenanceLevel } from "./attestor.js";
+import { type BaseSource, type RecordProvenance } from "./provenance.js";
+import { type ExcludedSigner } from "./policy.js";
+export interface CommitVerdict extends RecordProvenance {
+    commit: string;
+    subject: string;
+    /** A merge that changes nothing of its own; its parents are checked instead. */
+    skipped?: string;
+}
+export interface ProtectedWrite {
+    commit: string;
+    paths: string[];
+    level: ProvenanceLevel;
+    principal?: string;
+    allowed: boolean;
+    reason: string;
+}
+export interface ChangeReport {
+    base: string | null;
+    baseFrom: BaseSource | null;
+    head: string | null;
+    policy: {
+        active: boolean;
+        signersPath: string;
+        principals: string[];
+        excluded: ExcludedSigner[];
+        writers: string[];
+        problems: string[];
+    };
+    require: ProvenanceLevel | null;
+    commits: CommitVerdict[];
+    protectedPaths: string[];
+    /** Protected paths whose content differs between the merge base and head. */
+    protectedChanged: string[];
+    protectedWrites: ProtectedWrite[];
+    notes: string[];
+    failures: string[];
+    ok: boolean;
+}
+export interface VerifyOptions {
+    repo: string;
+    base?: string;
+    head?: string;
+    require?: ProvenanceLevel;
+    attestors: readonly CommitAttestor[];
+}
+/**
+ * Commits in `range` that change any of `paths`, each with the paths it
+ * changes. Merges count only for what they change beyond every parent.
+ */
+export declare function commitsTouching(repo: string, range: string, paths: string[]): Map<string, string[]>;
+export declare function verifyChange(opts: VerifyOptions): ChangeReport;
+//# sourceMappingURL=verify.d.ts.map

package/dist/workspace/trust/verify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../../../src/workspace/trust/verify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAAE,KAAK,cAAc,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AACvE,OAAO,EAA+C,KAAK,UAAU,EAAE,KAAK,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACnH,OAAO,EAAiC,KAAK,cAAc,EAAoB,MAAM,UAAU,CAAC;AAEhG,MAAM,WAAW,aAAc,SAAQ,gBAAgB;IACrD,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,gFAAgF;IAChF,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,EAAE,eAAe,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,QAAQ,EAAE,UAAU,GAAG,IAAI,CAAC;IAC5B,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,MAAM,EAAE;QACN,MAAM,EAAE,OAAO,CAAC;QAChB,WAAW,EAAE,MAAM,CAAC;QACpB,UAAU,EAAE,MAAM,EAAE,CAAC;QACrB,QAAQ,EAAE,cAAc,EAAE,CAAC;QAC3B,OAAO,EAAE,MAAM,EAAE,CAAC;QAClB,QAAQ,EAAE,MAAM,EAAE,CAAC;KACpB,CAAC;IACF,OAAO,EAAE,eAAe,GAAG,IAAI,CAAC;IAChC,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,6EAA6E;IAC7E,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,eAAe,EAAE,cAAc,EAAE,CAAC;IAClC,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,EAAE,EAAE,OAAO,CAAC;CACb;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,eAAe,CAAC;IAC1B,SAAS,EAAE,SAAS,cAAc,EAAE,CAAC;CACtC;AAMD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAUnG;AAQD,wBAAgB,YAAY,CAAC,IAAI,EAAE,aAAa,GAAG,YAAY,CAqG9D"}

package/dist/workspace/which-chant.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Where a workspace read starts, and which chant does it (#2536; #2524 D15,
+ * ws-016, ws-021).
+ *
+ * {@link locateWorkspace} finds the declaration from a directory, in the
+ * working tree or in one commit's git objects (`--at <rev>`), and gives the
+ * tree every read-contract command reads from.
+ *
+ * Which chant reads the declaration: the root's. The root names its chant by
+ * pinning `@intentius/chant` in the declaration's `pins`. When it pins one,
+ * that version reads the declaration, and any other chant refuses with
+ * `root-chant-required` (`parseDeclaration`'s `rootChant` option). The CLI
+ * first hands the whole command to the pinned chant when the root has it
+ * installed ({@link handToRootChant}), so a user sees the refusal only when
+ * it isn't. When the root pins no chant, the reader's own chant reads the
+ * declaration if it meets `minReader`, and refuses with `reader-too-old`
+ * otherwise. Members are always read by their own toolchains.
+ */
+import { type WorkspaceTree } from "./tree.js";
+export interface LocatedWorkspace {
+    /** The files, rooted at the workspace root. */
+    tree: WorkspaceTree;
+    /** The workspace root relative to the git root, `"."` for the git root itself. Absolute outside git. */
+    root: string;
+    /** The workspace root on disk, where pinned packages and toolchains are installed. Also for `--at`. */
+    rootOnDisk: string;
+    /** The full commit id for `--at`, or null for the working tree. */
+    at: string | null;
+    /** The top of the git repository, when there is one. */
+    top: string | undefined;
+}
+/**
+ * Find the workspace whose declaration is nearest above `cwd`, in the working
+ * tree or at revision `at`. Throws a {@link WorkspaceReadError}:
+ * `declaration-missing`, or for `--at`, `not-a-git-repository` and
+ * `revision-unknown`.
+ */
+export declare function locateWorkspace(cwd: string, at?: string): LocatedWorkspace;
+/**
+ * The `bin/chant` of `@intentius/chant` at `version`, installed where the
+ * workspace root resolves packages. Undefined when it isn't installed there,
+ * or is installed at another version.
+ */
+export declare function rootChantBin(rootOnDisk: string, version: string): string | undefined;
+/** Set in the environment of a command handed to the root's chant, so it is handed on once at most. */
+export declare const HANDED_TO_ROOT_ENV = "CHANT_WORKSPACE_ROOT_CHANT";
+/** The version the declaration at `located` pins for `@intentius/chant`, or undefined. Never throws. */
+export declare function declaredChantPin(located: LocatedWorkspace): string | undefined;
+/**
+ * Hand a read-contract command to the root's chant (ws-021). When the
+ * declaration above `cwd` (at `at`, for `--at`) pins a chant other than this
+ * one, and the root has that chant installed, run the same command line
+ * under it and return its exit code. Otherwise return undefined, and this
+ * chant runs the command: it reads the declaration itself, or refuses with
+ * `root-chant-required` when the pinned chant isn't installed.
+ */
+export declare function handToRootChant(cwd: string, at: string | undefined, argv?: string[]): Promise<number | undefined>;
+//# sourceMappingURL=which-chant.d.ts.map

package/dist/workspace/which-chant.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"which-chant.d.ts","sourceRoot":"","sources":["../../src/workspace/which-chant.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AASH,OAAO,EAA+C,KAAK,aAAa,EAAE,MAAM,QAAQ,CAAC;AAEzF,MAAM,WAAW,gBAAgB;IAC/B,+CAA+C;IAC/C,IAAI,EAAE,aAAa,CAAC;IACpB,wGAAwG;IACxG,IAAI,EAAE,MAAM,CAAC;IACb,uGAAuG;IACvG,UAAU,EAAE,MAAM,CAAC;IACnB,mEAAmE;IACnE,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAClB,wDAAwD;IACxD,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;CACzB;AAID;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,gBAAgB,CAgC1E;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAcpF;AAED,uGAAuG;AACvG,eAAO,MAAM,kBAAkB,+BAA+B,CAAC;AAE/D,wGAAwG;AACxG,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,gBAAgB,GAAG,MAAM,GAAG,SAAS,CAY9E;AAED;;;;;;;GAOG;AACH,wBAAsB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,GAAE,MAAM,EAA0B,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAoB9I"}

package/dist/workspace/workspace-kinds.schema.json

@@ -0,0 +1,133 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://intentius.io/chant/schemas/workspace/kinds/v1/workspace-kinds.schema.json",
+    "title": "workspace-kinds.json",
+    "description": "Member kinds a plugin supplies (#2524 D3, #2535, ws-031). A package publishes this file as data at its ./workspace-kinds subpath. chant reads it with the file system and never imports the package, so reading kinds never loads a lexicon.",
+    "type": "object",
+    "required": [
+        "schema",
+        "kinds"
+    ],
+    "properties": {
+        "$schema": {
+            "type": "string",
+            "description": "An editor hint. chant ignores it."
+        },
+        "$comment": {
+            "type": "string",
+            "description": "A note for people. chant ignores it."
+        },
+        "schema": {
+            "const": 1,
+            "description": "The kinds format version."
+        },
+        "kinds": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+                "$ref": "#/$defs/kind"
+            }
+        }
+    },
+    "patternProperties": {
+        "^x-": true
+    },
+    "additionalProperties": false,
+    "$defs": {
+        "kind": {
+            "type": "object",
+            "required": [
+                "name",
+                "description",
+                "precedence",
+                "probe"
+            ],
+            "properties": {
+                "name": {
+                    "type": "string",
+                    "pattern": "^[a-z][a-z0-9-]{0,39}$",
+                    "description": "The kind's name, as a member's kind field names it. chant, workspace, other and examples are built in and can't be supplied."
+                },
+                "description": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "One line saying what the member's directory holds, for listings and error messages."
+                },
+                "precedence": {
+                    "type": "integer",
+                    "minimum": 1,
+                    "maximum": 999,
+                    "description": "When the probes of several kinds claim one directory, the highest precedence decides. Two claiming kinds with the same highest precedence are a tie, and a tie fails. The built-in chant kind has 500 and workspace has 1000."
+                },
+                "probe": {
+                    "$ref": "#/$defs/probe"
+                },
+                "outputs": {
+                    "type": "array",
+                    "uniqueItems": true,
+                    "description": "The outputs every member of this kind exposes as link targets (#2524 D6, #2539). A member entry of the kind may list more in its own outputs field. Without this field the kind exposes only what each entry lists.",
+                    "items": {
+                        "type": "string",
+                        "minLength": 1,
+                        "maxLength": 255,
+                        "pattern": "^[^\\u0000-\\u001f]+$"
+                    }
+                }
+            },
+            "patternProperties": {
+                "^x-": true
+            },
+            "additionalProperties": false
+        },
+        "probe": {
+            "type": "object",
+            "description": "What the probe checks in a member's directory. It runs no code. It passes when any of its clauses does, and it needs at least one.",
+            "minProperties": 1,
+            "properties": {
+                "anyFile": {
+                    "type": "array",
+                    "minItems": 1,
+                    "uniqueItems": true,
+                    "description": "The directory passes when a file matching one of these names sits directly in it. A * in a name matches any run of characters, so *.tf matches every Terraform file.",
+                    "items": {
+                        "$ref": "#/$defs/fileName"
+                    }
+                },
+                "anyBlock": {
+                    "type": "object",
+                    "description": "The directory passes when a file directly in it, whose name matches one of in, has a line opening an unlabelled block named in blocks: leading space, the name, optional space, then {. No file is parsed.",
+                    "required": [
+                        "in",
+                        "blocks"
+                    ],
+                    "properties": {
+                        "in": {
+                            "type": "array",
+                            "minItems": 1,
+                            "uniqueItems": true,
+                            "items": {
+                                "$ref": "#/$defs/fileName"
+                            }
+                        },
+                        "blocks": {
+                            "type": "array",
+                            "minItems": 1,
+                            "uniqueItems": true,
+                            "items": {
+                                "type": "string",
+                                "pattern": "^[A-Za-z_][A-Za-z0-9_-]{0,63}$"
+                            }
+                        }
+                    },
+                    "additionalProperties": false
+                }
+            },
+            "additionalProperties": false
+        },
+        "fileName": {
+            "type": "string",
+            "description": "A file name, with no directory part. A * matches any run of characters.",
+            "pattern": "^(?!\\.\\.?$)[^/\\\\]+$"
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant",
-  "version": "0.80.0",
+  "version": "0.81.0",
   "description": "Declarative infrastructure-as-code toolkit — TypeScript on Node.js",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -49,6 +49,7 @@
       "types": "./dist/cli/index.d.ts",
       "default": "./src/cli/index.ts"
     },
+    "./workspace/*.schema.json": "./src/workspace/*.schema.json",
     "./cli/*": {
       "development": "./src/cli/*.ts",
       "types": "./dist/cli/*.d.ts",

package/src/audit/discover.ts

@@ -34,12 +34,15 @@
  *     normalized to a JSON string here.
  */
 
-import { readdirSync, readFileSync, statSync } from "fs";
+import { readFileSync, statSync } from "fs";
 import { basename, join, relative, resolve } from "path";
 import { parseYAML } from "../yaml";
 import type { LexiconPlugin } from "../lexicon";
 import type { AuditInput, AuditLexicon } from "./core";
 import { isNginxConfigPath } from "./nginx";
+import { walkDiscovery } from "../discovery/walk";
+import { findProjectConfig } from "../project-root";
+import type { DiscoveryGlobs } from "../config";
 import { gitignoreCoversTerraformState, isTerraformStatePath, nestedGitignoreCovering } from "./terraform-state";
 
 /** Lexicons the auditor knows how to detect and run checks for. */
@@ -69,11 +72,8 @@ export async function loadAuditPlugins(names: readonly string[] = AUDIT_LEXICONS
   return plugins;
 }
 
-const WALK_SKIP = new Set(["node_modules", ".git", "dist"]);
 /** Terraform's local working directory: recorded by the walk, never entered (TF023). */
 const TERRAFORM_WORK_DIR = ".terraform";
-/** Dot-directories the walk descends into anyway (CI lives here). */
-const WALK_DOT_DIRS = new Set([".github", ".forgejo"]);
 /**
  * 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
@@ -83,53 +83,54 @@ 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;
 
-/** The walk's limit, and whether it left anything behind because of it. */
-interface WalkState {
-  limit: number;
-  truncated: boolean;
+/**
+ * The project's `exclude`/`include` globs for the audit walk, read from a
+ * `chant.config.json` only. The audit reads repositories it has no reason to
+ * trust, so it never runs a `chant.config.ts` to find them.
+ */
+function auditGlobs(root: string): DiscoveryGlobs | undefined {
+  const { dir, configPath } = findProjectConfig(root);
+  if (!configPath?.endsWith(".json")) return undefined;
+  let raw: unknown;
+  try {
+    raw = JSON.parse(readFileSync(configPath, "utf-8"));
+  } catch {
+    return undefined;
+  }
+  const list = (v: unknown): string[] => (Array.isArray(v) ? v.filter((x): x is string => typeof x === "string" && x !== "") : []);
+  const exclude = list((raw as Record<string, unknown>)?.exclude);
+  const include = list((raw as Record<string, unknown>)?.include);
+  return exclude.length === 0 && include.length === 0 ? undefined : { root: dir, exclude, include };
 }
 
 /**
- * Recursively collect file paths under a root, skipping noise dirs.
+ * Collect file paths under a root through the one discovery walk
+ * (`../discovery/walk.ts`, #2527), sorted per directory.
+ *
+ * The audit's own departures from the other walkers: `.github` and `.forgejo`
+ * are entered, since they hold the CI files it audits; `.terraform/` is
+ * recorded but never entered, since it is machine-generated, routinely
+ * hundreds of megabytes of provider binaries, and its presence is itself the
+ * finding (TF023); and Terraform state paths are left to TF023's own
+ * `.gitignore` reading rather than dropped for being git-ignored.
  *
- * Stops at `state.limit` paths. Once full it keeps looking only until it meets
+ * Stops at `state.max` 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.
+ * exactly `max` files, or one whose remaining entries are all skipped
+ * directories, was not truncated.
  */
-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 (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 && !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, state);
-    else if (!take(full)) return;
-  }
+function walkFiles(root: string, state: { max: number; truncated: boolean }, excludeDirs?: readonly string[]): string[] {
+  return walkDiscovery({
+    walker: "audit",
+    root,
+    excludeDirs,
+    globs: auditGlobs(root),
+    sorted: true,
+    limit: state,
+    takeSkippedDir: (name) => name === TERRAFORM_WORK_DIR,
+    keepIgnored: (full) => isTerraformStatePath(relative(root, full)),
+    accept: () => true,
+  });
 }
 
 function readSafe(full: string): string | undefined {
@@ -625,18 +626,12 @@ export function discoverByDetection(root: string, plugins: DetectPlugin[]): Audi
 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;
+  /**
+   * Directories the walk leaves out, absolute: the workspace members and
+   * example-group matches below the root, from `workspaceMemberDirs`. The
+   * caller resolves them, since that is async and this walk is not.
+   */
+  excludeDirs?: readonly string[];
 }
 
 /** What the local walk read, plus what it knows about its own limits. */
@@ -646,8 +641,6 @@ export interface CandidateWalk {
   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. */
@@ -656,39 +649,34 @@ export function collectCandidates(root: string): RepoFile[] {
 }
 
 /**
- * `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).
+ * `collectCandidates` plus whether the walk stopped at its limit with files
+ * left unread, which the audit report states (#2528).
  */
 export function walkCandidates(root: string, opts: CandidateWalkOptions = {}): CandidateWalk {
-  const all: string[] = [];
-  const state: WalkState = { limit: opts.maxFiles ?? DEFAULT_MAX_WALK_FILES, truncated: false };
-  walkFiles(root, all, state);
+  const state = { max: opts.maxFiles ?? DEFAULT_MAX_WALK_FILES, truncated: false };
+  const all = walkFiles(root, state, opts.excludeDirs);
   // 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
-  // disk" here — a Terraform working tree almost always has an ignored
+  // all. The `.gitignore` files are what separate "committed" from "merely on
+  // disk" here. A Terraform working tree almost always has an ignored
   // `.terraform/` in it, and reporting that would make TF023 fire on every
-  // local audit. A fetched repository has no such ambiguity (its file list is
-  // the tracked files) and is not filtered.
+  // local audit. Every `.gitignore` from the scan root down to the file's own
+  // directory is read (#2528), so auditing from the root and from a
+  // subdirectory agree. 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: "" });
-        const dir = nestedGitignoreCovering(path, nestedGitignoreAt);
-        if (dir !== undefined) nestedGitignore.push({ path, gitignore: `${dir}/.gitignore` });
-      }
+      const ignored =
+        gitignoreCoversTerraformState(gitignore, path) || nestedGitignoreCovering(path, nestedGitignoreAt) !== undefined;
+      if (!ignored) files.push({ path, content: "" });
       continue;
     }
     // `.tf` is read locally so `classifyTerraform` can bundle real content.
@@ -702,5 +690,5 @@ export function walkCandidates(root: string, opts: CandidateWalkOptions = {}): C
     const content = readSafe(full);
     if (content !== undefined) files.push({ path, content });
   }
-  return { files, maxFiles: state.limit, truncated: state.truncated, nestedGitignore };
+  return { files, maxFiles: state.max, truncated: state.truncated };
 }

package/src/audit/report-html.ts

@@ -31,6 +31,8 @@ export interface RenderHtmlOptions extends BuildModelOptions {
   /** Full template override; `{{title}} {{accent}} {{logo}} {{meta}} {{body}} {{footer}}` slots. */
   template?: string;
   notes?: string[];
+  /** A truncated local walk (#2528), carried into the embedded JSON report. */
+  truncated?: { limit: number; flag: string };
 }
 
 const DEFAULT_ACCENT = "#7c3aed";
@@ -194,7 +196,7 @@ export function renderHtml(findings: AuditFinding[], opts: RenderHtmlOptions = {
 
   // Machine-readable data embedded so the HTML report is also parseable.
   // `<` escaped so the JSON can't break out of the <script> element.
-  const dataJson = JSON.stringify(buildReportJson(findings, { snapshot: opts.snapshot }), null, 0).replace(/</g, "\\u003c");
+  const dataJson = JSON.stringify(buildReportJson(findings, { snapshot: opts.snapshot, truncated: opts.truncated }), null, 0).replace(/</g, "\\u003c");
   const dataScript = `<script type="application/json" id="chant-audit-report">${dataJson}</script>`;
 
   let body: string;

package/src/audit/report-model.ts

@@ -129,6 +129,12 @@ export interface AuditReportJson {
   findings: SerializedFinding[];
   /** Candidate files that looked like they wanted a lexicon that is not installed. */
   unclaimed?: UnclaimedFile[];
+  /**
+   * Present when the local walk stopped at its file limit with files left
+   * unread (#2528): the limit, and the flag that raises it. Absent for a whole
+   * scan and for a repository URL.
+   */
+  truncated?: { limit: number; flag: string };
 }
 
 export function metaFor(id: string, catalog: Record<string, RuleMeta> = RULE_CATALOG): RuleMeta {
@@ -298,7 +304,13 @@ export function buildReportModel(findings: AuditFinding[], opts: BuildModelOptio
 /** Build the versioned, machine-readable JSON report (stable contract). */
 export function buildReportJson(
   findings: AuditFinding[],
-  opts: { snapshot?: AuditSnapshot; toolVersion?: string; catalog?: Record<string, RuleMeta>; unclaimed?: UnclaimedFile[] } = {},
+  opts: {
+    snapshot?: AuditSnapshot;
+    toolVersion?: string;
+    catalog?: Record<string, RuleMeta>;
+    unclaimed?: UnclaimedFile[];
+    truncated?: { limit: number; flag: string };
+  } = {},
 ): AuditReportJson {
   const model = buildReportModel(findings, { catalog: opts.catalog });
   const version = opts.toolVersion ?? opts.snapshot?.toolVersion ?? "0.0.0";
@@ -328,5 +340,6 @@ export function buildReportJson(
       docUrl: ruleDocUrl(f.checkId),
     })),
     unclaimed: opts.unclaimed && opts.unclaimed.length > 0 ? opts.unclaimed : undefined,
+    truncated: opts.truncated,
   };
 }

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

@@ -196,22 +196,18 @@ describe("walkCandidates reports what the next release changes, and changes noth
     rmSync(dir, { recursive: true, force: true });
   });
 
-  test("a state file a nested .gitignore ignores is still a candidate, and is named for the warning", () => {
+  test("a state file a nested .gitignore ignores is not a candidate (#2528)", () => {
     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" },
-    ]);
+    expect(walk.files.map((f) => f.path)).toEqual([]);
+    expect(auditTerraformState(walk.files)).toHaveLength(0);
     rmSync(dir, { recursive: true, force: true });
   });
 
-  test("nothing is named when the root .gitignore already drops the path, or no nested one covers it", () => {
+  test("only the .gitignore files between the path and the root apply, not a sibling's", () => {
     const dir = tmpRepo();
     mkdirSync(join(dir, "a"), { recursive: true });
     mkdirSync(join(dir, "b"), { recursive: true });
@@ -223,7 +219,6 @@ describe("walkCandidates reports what the next release changes, and changes noth
     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,8 +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.
+ * The root `.gitignore` and every nested one on the way to the path can drop
+ * it (`nestedGitignoreCovering`, #2528).
  */
 
 import type { AuditFinding } from "./core";
@@ -92,9 +92,8 @@ export function gitignoreCoversTerraformState(gitignore: string, path: string):
  * 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).
+ * The local walk drops a TF023 path this returns a directory for, as it drops
+ * one the root `.gitignore` covers (#2528).
  */
 export function nestedGitignoreCovering(
   path: string,