@intentius/chant 0.79.0 → 0.81.0

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

@@ -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,82 @@ 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 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)).toEqual([]);
+    expect(auditTerraformState(walk.files)).toHaveLength(0);
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  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 });
+    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"]);
+    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.
+ * The root `.gitignore` and every nested one on the way to the path can drop
+ * it (`nestedGitignoreCovering`, #2528).
  */
 
 import type { AuditFinding } from "./core";
@@ -83,6 +85,29 @@ 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 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,
+  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-truncation.test.ts

@@ -0,0 +1,167 @@
+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, one of the level-0 changes on #2525's exception list (warned in
+ * v0.80.0). A truncated local walk is stated in the report, with its limit and
+ * the flag that raises it, and TF023 honours every `.gitignore` between a path
+ * and the scan root.
+ */
+
+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 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("JSON carries truncated with the limit and the flag, and nothing goes to stderr", async () => {
+    const dir = treeWithTail();
+    const result = await audit(dir, { maxFiles: 6 });
+    expect(JSON.parse(result.output).truncated).toEqual({ limit: 6, flag: "--max-files" });
+    expect(result.warnings).toBeUndefined();
+    const { stdout, stderr } = printed(result);
+    expect(stdout).toBe(result.output);
+    expect(stderr).toBe("");
+    expect(result.findings.map((f) => f.file)).toEqual(["a/terraform.tfstate"]);
+  });
+
+  test("the text report leads with a note naming the limit and --max-files", async () => {
+    const dir = treeWithTail();
+    const result = await audit(dir, { maxFiles: 6, format: "stylish" });
+    const first = result.output.split("\n")[0];
+    expect(first).toBe(
+      `Note: The scan of ${dir} stopped at 6 files, so part of the tree was not audited. ` +
+        "The limit counts every file the walk reaches, not only the ones it audits. Raise it with --max-files <n>.",
+    );
+    expect(result.warnings).toBeUndefined();
+  });
+
+  test("markdown and HTML carry the note, and HTML's embedded JSON carries the field", async () => {
+    const dir = treeWithTail();
+    const md = await audit(dir, { maxFiles: 6, format: "markdown" });
+    expect(md.output).toContain("stopped at 6 files");
+    const html = await audit(dir, { maxFiles: 6, format: "html" });
+    expect(html.output).toContain("stopped at 6 files");
+    expect(html.output).toContain('"truncated":{"limit":6,"flag":"--max-files"}');
+  });
+
+  test("SARIF has no slot for it, so the truncation goes to stderr there", async () => {
+    const dir = treeWithTail();
+    const result = await audit(dir, { maxFiles: 6, format: "sarif" });
+    const { stdout, stderr } = printed(result);
+    expect(stdout).toBe(result.output);
+    expect(stderr).toContain(`The scan of ${dir} stopped at 6 files`);
+    expect(stderr).toContain("--max-files <n>");
+  });
+
+  test("a whole scan reports nothing: no field, no note", async () => {
+    const dir = treeWithTail();
+    const raised = await audit(dir, { maxFiles: 7 });
+    expect(JSON.parse(raised.output)).not.toHaveProperty("truncated");
+    expect(raised.warnings).toBeUndefined();
+    expect(raised.findings.map((f) => f.file).sort()).toEqual(["a/terraform.tfstate", "z/terraform.tfstate"]);
+    const text = await audit(dir, { format: "stylish" });
+    expect(text.output).not.toContain("stopped at");
+  });
+
+  test("the no-lexicons report states it too", async () => {
+    const dir = treeWithTail();
+    const json = await audit(dir, { maxFiles: 6, plugins: [] });
+    expect(JSON.parse(json.output).truncated).toEqual({ limit: 6, flag: "--max-files" });
+    const text = await audit(dir, { maxFiles: 6, plugins: [], format: "stylish" });
+    expect(text.output).toContain("stopped at 6 files");
+  });
+
+  test("an audit with nothing auditable still says the scan was cut short", async () => {
+    const dir = tmpRepo();
+    for (let i = 0; i < 4; i++) writeFileSync(join(dir, `${i}.md`), "x");
+    const result = await audit(dir, { maxFiles: 2, format: "stylish" });
+    expect(result.output).toContain("No auditable files found");
+    expect(result.output).toContain("stopped at 2 files");
+  });
+});
+
+describe("TF023 honours every .gitignore between a path and the scan root (#2528)", () => {
+  function nestedTree(nested: string | undefined): string {
+    const dir = tmpRepo();
+    mkdirSync(join(dir, "infra", "prod"), { 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"), "{}");
+    writeFileSync(join(dir, "infra", "prod", "terraform.tfstate"), "{}");
+    if (nested !== undefined) writeFileSync(join(dir, "infra", ".gitignore"), nested);
+    return dir;
+  }
+  const tf023 = (r: Awaited<ReturnType<typeof audit>>) =>
+    r.findings.filter((f) => f.checkId === "TF023").map((f) => f.file).sort();
+
+  test("a nested .gitignore drops the paths it covers, at any depth below it", async () => {
+    const result = await audit(nestedTree("*.tfstate\n"));
+    expect(tf023(result)).toEqual([]);
+    expect(result.warnings).toBeUndefined();
+  });
+
+  test("a nested .gitignore that does not cover the file changes nothing", async () => {
+    expect(tf023(await audit(nestedTree("*.log\n")))).toEqual(["infra/prod/terraform.tfstate", "infra/terraform.tfstate"]);
+  });
+
+  test("a .gitignore deeper than the file does not apply to it", async () => {
+    const dir = nestedTree(undefined);
+    writeFileSync(join(dir, "infra", "prod", ".gitignore"), "*.tfstate\n");
+    expect(tf023(await audit(dir))).toEqual(["infra/terraform.tfstate"]);
+  });
+
+  test("auditing from the root and from the subdirectory agree", async () => {
+    const dir = nestedTree(undefined);
+    writeFileSync(join(dir, "infra", "prod", ".gitignore"), "*.tfstate\n");
+    const fromRoot = tf023(await audit(dir));
+    const fromInfra = tf023(await audit(join(dir, "infra"))).map((p) => `infra/${p}`);
+    expect(fromRoot).toEqual(fromInfra);
+  });
+});