@intentius/chant-lexicon-terraform 0.57.0 → 0.58.0

package/src/hcl/references.ts

@@ -0,0 +1,172 @@
+/**
+ * Which declarations does a module scope actually reference (chant #2112)?
+ *
+ * One pass over every entity's body, collecting the reference forms Terraform
+ * writes as expressions: `var.<name>`, `local.<name>`, `data.<type>.<name>`,
+ * `module.<name>`, and the `provider = <type>.<alias>` / `providers = { <type>
+ * = <type>.<alias> }` meta-arguments. The result is keyed per module scope
+ * (`./parse.ts`'s `scopeOfKey`), because Terraform's own namespaces are: a
+ * `var.region` inside `module.cdn` is the child module's variable, never the
+ * root's, and a rule that pooled the two would call a genuinely unused root
+ * variable used.
+ *
+ * ## It is a string scan, and the rules built on it say so
+ *
+ * hcl2json gives back an expression as a STRING, with the `${...}` wrapper
+ * preserved: `count = length(var.subnets)` arrives as `"${length(var.subnets)}"`
+ * and `bucket = var.name` as `"${var.name}"`. There is no expression tree to
+ * walk, so this scans the strings with regexes. That reads a reference inside
+ * a comment-free body correctly and is deliberately generous at the edges: a
+ * name that appears inside a quoted literal (`description = "set var.region"`)
+ * counts as a reference, and a reference built dynamically
+ * (`lookup(local.by_env, terraform.workspace)` reaching a value nothing names
+ * directly) does not. Both directions are why TF020 is report-only and credits
+ * tflint's `terraform_unused_declarations` as `overlaps` rather than
+ * `equivalent`: it is the same question answered with a coarser instrument.
+ *
+ * The index records WHICH entity each reference came from, so a check can ask
+ * "is anything other than the declaration itself referring to this?". A
+ * `variable "port"` whose own `validation` block reads `var.port` is the case
+ * that needs it: without the exclusion every validated variable would look
+ * used.
+ */
+
+import { isResourceDeclarable, type Declarable } from "@intentius/chant/declarable";
+import { scopeOfKey, type BlockBody, type TerraformEntity } from "./parse";
+
+/** An identifier as Terraform's grammar allows it: letters, digits, `_`, `-`. */
+const NAME = "[A-Za-z_][A-Za-z0-9_-]*";
+
+const VAR_RE = new RegExp(`\\bvar\\.(${NAME})`, "g");
+const LOCAL_RE = new RegExp(`\\blocal\\.(${NAME})`, "g");
+const DATA_RE = new RegExp(`\\bdata\\.(${NAME})\\.(${NAME})`, "g");
+const MODULE_RE = new RegExp(`\\bmodule\\.(${NAME})`, "g");
+/** A provider reference once any `${...}` wrapper is off: `aws.west`. */
+const PROVIDER_REF_RE = new RegExp(`^(${NAME})\\.(${NAME})$`);
+/** hcl2json's wrapper around a bare expression, which a `provider` value always is. */
+const INTERPOLATION_RE = /^\$\{(.*)\}$/s;
+
+/**
+ * Every reference token in one string, in the vocabulary the index keys by:
+ * `var.region`, `local.tags`, `data.aws_ami.ubuntu`, `module.cdn`.
+ *
+ * `data.` is matched before `local.`/`var.` can see it, and a `module.cdn.url`
+ * yields `module.cdn`, since the call is what a reference makes used.
+ */
+export function collectReferences(text: string): string[] {
+  const found = new Set<string>();
+  for (const m of text.matchAll(DATA_RE)) found.add(`data.${m[1]}.${m[2]}`);
+  for (const m of text.matchAll(VAR_RE)) found.add(`var.${m[1]}`);
+  for (const m of text.matchAll(LOCAL_RE)) found.add(`local.${m[1]}`);
+  for (const m of text.matchAll(MODULE_RE)) found.add(`module.${m[1]}`);
+  return [...found];
+}
+
+/**
+ * The `provider`/`providers` meta-argument's own reference form, which is not
+ * an interpolation and has no prefix of its own: `provider = aws.west` names
+ * the `provider "aws" { alias = "west" }` block. Returned in the index's
+ * vocabulary, `provider.aws.west`, so it cannot collide with a resource
+ * address that happens to look the same.
+ */
+export function providerReference(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  const inner = INTERPOLATION_RE.exec(trimmed);
+  const m = PROVIDER_REF_RE.exec((inner ? inner[1] : trimmed).trim());
+  return m ? `provider.${m[1]}.${m[2]}` : undefined;
+}
+
+/** Every reference in one block body, provider meta-arguments included. */
+export function referencesInBody(body: BlockBody): string[] {
+  const found = new Set<string>();
+
+  const visit = (value: unknown, key: string, depth: number): void => {
+    if (depth > 6) return;
+    if (typeof value === "string") {
+      for (const ref of collectReferences(value)) found.add(ref);
+      if (key === "provider") {
+        const provider = providerReference(value);
+        if (provider) found.add(provider);
+      }
+      return;
+    }
+    if (Array.isArray(value)) {
+      for (const item of value) visit(item, key, depth + 1);
+      return;
+    }
+    if (typeof value === "object" && value !== null) {
+      for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+        // `providers = { aws = aws.west }` maps a child module's provider name
+        // to the caller's block, so every VALUE under `providers` is a
+        // provider reference, whatever its key.
+        visit(v, key === "providers" ? "provider" : k, depth + 1);
+      }
+    }
+  };
+
+  visit(body, "", 0);
+  return [...found];
+}
+
+/**
+ * Every reference in one module scope: token to the entity keys whose body
+ * mentions it.
+ */
+export type ScopeReferences = Map<string, Set<string>>;
+
+/** Reference tokens per module scope (`<root>`, `<root>/module.<name>`). */
+export interface ReferenceIndex {
+  readonly scopes: Map<string, ScopeReferences>;
+}
+
+/**
+ * Build the index over a whole build's entities. Scopes come from the entity
+ * keys, so a root and each of its descended child modules are separate, and
+ * two roots never pool.
+ */
+export function buildReferenceIndex(entities: Map<string, Declarable>): ReferenceIndex {
+  const scopes = new Map<string, ScopeReferences>();
+
+  for (const [key, entity] of entities) {
+    if (!isResourceDeclarable(entity)) continue;
+    const props = (entity as TerraformEntity).props as Partial<TerraformEntity["props"]>;
+    const body = (typeof props.body === "object" && props.body !== null ? props.body : {}) as BlockBody;
+    const scope = scopeOfKey(key);
+    let refs = scopes.get(scope);
+    if (!refs) {
+      refs = new Map();
+      scopes.set(scope, refs);
+    }
+    for (const ref of referencesInBody(body)) {
+      const from = refs.get(ref);
+      if (from) from.add(key);
+      else refs.set(ref, new Set([key]));
+    }
+  }
+
+  return { scopes };
+}
+
+/** The entity keys in `scope` whose body references `token`. */
+export function referencesTo(index: ReferenceIndex, scope: string, token: string): Set<string> {
+  return index.scopes.get(scope)?.get(token) ?? new Set();
+}
+
+/**
+ * Is `token` referenced anywhere in `scope` other than by `declaredBy` itself?
+ * The exclusion is what keeps a variable read only by its own `validation`
+ * block, or a local read only by its own `locals` block, from looking used.
+ */
+export function isReferenced(
+  index: ReferenceIndex,
+  scope: string,
+  token: string,
+  declaredBy?: string,
+): boolean {
+  const from = referencesTo(index, scope, token);
+  for (const key of from) {
+    if (key !== declaredBy) return true;
+  }
+  return false;
+}

package/src/hcl/roots.ts

@@ -13,14 +13,20 @@
  * someone else's estate is the whole job here, and half of it parsing is more
  * useful than none of it, especially when the audit path (#2085) walks
  * repositories it did not write.
+ *
+ * A root's own directory is not the end of the parse: a `module` block with a
+ * local source is followed into its directory and parsed as a child scope of
+ * the root (#2112). `./descend.ts` owns that walk and every refusal in it; the
+ * refusals surface here as this render's warnings.
  */
 
 import { existsSync } from "node:fs";
 import { isAbsolute, resolve } from "node:path";
-import type { Declarable } from "@intentius/chant/declarable";
+import { isResourceDeclarable, type Declarable } from "@intentius/chant/declarable";
 import type { Hcl2Json } from "@intentius/chant/terraform/parse";
 import type { TerraformRootConfig } from "../config";
-import { parseTerraformRootDir } from "./parse";
+import { LIVE_TYPE, parseTerraformRootDir } from "./parse";
+import { descendModules, resolveCallModuleType, type CallModuleType } from "./descend";
 
 export interface TerraformRootsResult {
   entities: Map<string, Declarable>;
@@ -32,13 +38,26 @@ export interface RenderTerraformRootsOptions {
   projectRoot: string;
   /** `terraform.roots`: name to root-module config. */
   roots: Readonly<Record<string, TerraformRootConfig>>;
+  /**
+   * `terraform.binary`. A root is live only when this is `"choudoufu"` and it
+   * declares an estate; anything else runs stock (#2103).
+   */
+  binary?: string;
+  /**
+   * `terraform.callModuleType` (#2112): how far each root's parse follows its
+   * `module` calls. Defaults to `"local"`, so a module sourced from `./` or
+   * `../` is parsed as a child scope of the root that calls it.
+   */
+  callModuleType?: CallModuleType;
   /** Injectable parser (tests); defaults to core's lazy-loaded `@cdktf/hcl2json`. */
   hcl2json?: Hcl2Json;
 }
 
 /**
- * Parse each configured root into entities keyed `<root>/<address>`. Roots are
- * visited in declaration order, and one root's failure never stops the next.
+ * Parse each configured root into entities keyed `<root>/<address>`, plus its
+ * local child modules, keyed `<root>/module.<name>/<address>` (#2112). Roots
+ * are visited in declaration order, and one root's failure never stops the
+ * next.
  */
 export async function renderTerraformRoots(
   opts: RenderTerraformRootsOptions,
@@ -46,6 +65,11 @@ export async function renderTerraformRoots(
   const entities = new Map<string, Declarable>();
   const warnings: string[] = [];
 
+  // One verdict for the whole render: the mode is a project-level setting, so
+  // a refused `"all"` is said once rather than once per root (#2112).
+  const callModuleType = resolveCallModuleType(opts.callModuleType);
+  if (callModuleType.warning) warnings.push(callModuleType.warning);
+
   for (const [name, root] of Object.entries(opts.roots)) {
     const dir = isAbsolute(root.dir) ? root.dir : resolve(opts.projectRoot, root.dir);
 
@@ -55,8 +79,38 @@ export async function renderTerraformRoots(
     }
 
     try {
-      const parsed = await parseTerraformRootDir(dir, name, opts.hcl2json);
+      const modeOptions = { binary: opts.binary, workspace: root.workspace, delete: root.delete };
+      const parsed = await parseTerraformRootDir(dir, name, opts.hcl2json, modeOptions);
       for (const [key, entity] of parsed) entities.set(key, entity);
+
+      // Local child modules, keyed `<root>/module.<name>/<address>` (#2112).
+      // Their refusals are warnings on the root that called them, since the
+      // call site is where a reader can act on one.
+      const descended = await descendModules(parsed, {
+        dir,
+        root: name,
+        projectRoot: opts.projectRoot,
+        callModuleType: callModuleType.effective,
+        hcl2json: opts.hcl2json,
+        modeOptions,
+      });
+      for (const [key, entity] of descended.entities) entities.set(key, entity);
+      warnings.push(...descended.warnings);
+
+      // A `live` block or `estate.chdf.hcl` sidecar only takes effect under
+      // choudoufu; under any other binary it parses fine but is inert, which
+      // is worth a warning rather than silence (#2103).
+      for (const entity of parsed.values()) {
+        if (entity.entityType !== LIVE_TYPE || !isResourceDeclarable(entity)) continue;
+        if ((entity.props as { mode?: string }).mode === "state") {
+          warnings.push(
+            `terraform.roots.${name}: declares a live estate (a \`live\` block or ${JSON.stringify(
+              "estate.chdf.hcl",
+            )} sidecar), but terraform.binary is ${JSON.stringify(opts.binary ?? "terraform")}, not "choudoufu", so the live declaration is inert.`,
+          );
+        }
+        break;
+      }
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
       warnings.push(`terraform.roots.${name}: could not parse ${dir}, ${message}`);

package/src/hcl/suppressions.test.ts

@@ -0,0 +1,147 @@
+import { describe, test, expect } from "vitest";
+import { scanSuppressions, directivesFor } from "./suppressions";
+
+describe("scanSuppressions: block start lines", () => {
+  test("finds a bare block's start line", () => {
+    const scan = scanSuppressions("main.tf", `terraform {\n  required_version = ">= 1.5.0"\n}\n`);
+    expect(scan.blockLineQueues.get("terraform")).toEqual([1]);
+  });
+
+  test("finds a one-label block's start line and address", () => {
+    const scan = scanSuppressions("main.tf", `variable "region" {\n  type = string\n}\n`);
+    expect(scan.blockLineQueues.get("var.region")).toEqual([1]);
+  });
+
+  test("finds a two-label block's start line and address", () => {
+    const scan = scanSuppressions(
+      "main.tf",
+      `resource "aws_s3_bucket" "assets" {\n  bucket = "x"\n}\n`,
+    );
+    expect(scan.blockLineQueues.get("aws_s3_bucket.assets")).toEqual([1]);
+  });
+
+  test("a data block's address is prefixed with data.", () => {
+    const scan = scanSuppressions("main.tf", `data "aws_ami" "x" {\n  most_recent = true\n}\n`);
+    expect(scan.blockLineQueues.get("data.aws_ami.x")).toEqual([1]);
+  });
+
+  test("ignores a nested block of the same keyword shape (brace depth)", () => {
+    // `required_providers` isn't itself a tracked keyword, but its nested
+    // `aws = { ... }` map must not confuse the depth counter into missing the
+    // close of the outer `terraform` block.
+    const scan = scanSuppressions(
+      "main.tf",
+      [
+        "terraform {",
+        "  required_providers {",
+        '    aws = { source = "hashicorp/aws" }',
+        "  }",
+        "}",
+        "",
+        'variable "x" {',
+        "  type = string",
+        "}",
+      ].join("\n"),
+    );
+    expect(scan.blockLineQueues.get("terraform")).toEqual([1]);
+    expect(scan.blockLineQueues.get("var.x")).toEqual([7]);
+  });
+
+  test("two blocks sharing one address queue in file order", () => {
+    const scan = scanSuppressions(
+      "main.tf",
+      ['locals {', "  a = 1", "}", "", "locals {", "  b = 2", "}"].join("\n"),
+    );
+    expect(scan.blockLineQueues.get("locals")).toEqual([1, 5]);
+  });
+});
+
+describe("scanSuppressions: directive forms", () => {
+  test("chant-ignore anchors to the very next line", () => {
+    const scan = scanSuppressions("main.tf", `# chant-ignore: TF010, TF011\nvariable "x" {\n  type = string\n}\n`);
+    const directives = scan.byAnchorLine.get(2);
+    expect(directives).toHaveLength(1);
+    expect(directives?.[0].form).toBe("chant-ignore");
+    expect(directives?.[0].ids).toEqual(new Set(["TF010", "TF011"]));
+  });
+
+  test("chant-ignore-block parses distinctly from bare chant-ignore", () => {
+    const scan = scanSuppressions("main.tf", `# chant-ignore-block: TF001\nterraform {\n}\n`);
+    const directives = scan.byAnchorLine.get(2);
+    expect(directives?.[0].form).toBe("chant-ignore-block");
+    expect(directives?.[0].ids).toEqual(new Set(["TF001"]));
+  });
+
+  test('"all" is the wildcard', () => {
+    const scan = scanSuppressions("main.tf", `# chant-ignore: all\nvariable "x" {\n  type = string\n}\n`);
+    expect(scan.byAnchorLine.get(2)?.[0].ids).toBe("all");
+  });
+
+  test("also works with // comments", () => {
+    const scan = scanSuppressions("main.tf", `// chant-ignore: TF010\nvariable "x" {\n  type = string\n}\n`);
+    expect(scan.byAnchorLine.get(2)?.[0].ids).toEqual(new Set(["TF010"]));
+  });
+
+  test("an exp: term sets expiry and is excluded from the id list", () => {
+    const scan = scanSuppressions("main.tf", `# chant-ignore: TF010 exp:2026-12-31\nvariable "x" {\n  type = string\n}\n`);
+    const d = scan.byAnchorLine.get(2)?.[0];
+    expect(d?.ids).toEqual(new Set(["TF010"]));
+    expect(d?.expires).toBe("2026-12-31");
+  });
+
+  test("a comment not on the line immediately before a block has no effect on that block", () => {
+    // The comment anchors to line 2 (its own line + 1); the block starts at
+    // line 3 because of the blank line between them, so `directivesFor` never
+    // finds a directive at the block's actual start line.
+    const scan = scanSuppressions("main.tf", `# chant-ignore: TF010\n\nvariable "x" {\n  type = string\n}\n`);
+    const { line, suppressions } = directivesFor(scan, "var.x");
+    expect(line).toBe(3);
+    expect(suppressions).toBeUndefined();
+  });
+
+  test("chant-ignore-file as the first non-blank line is not misplaced", () => {
+    const scan = scanSuppressions("main.tf", `# chant-ignore-file: TF011\nvariable "x" {\n  type = string\n}\n`);
+    expect(scan.fileDirective?.misplaced).toBeFalsy();
+    expect(scan.fileDirective?.ids).toEqual(new Set(["TF011"]));
+  });
+
+  test("chant-ignore-file after another line is misplaced", () => {
+    const scan = scanSuppressions("main.tf", `# a license header\n# chant-ignore-file: TF011\nvariable "x" {\n  type = string\n}\n`);
+    expect(scan.fileDirective?.misplaced).toBe(true);
+  });
+
+  test("chant-ignore-file after leading blank lines is not misplaced (blank lines don't count)", () => {
+    const scan = scanSuppressions("main.tf", `\n\n# chant-ignore-file: TF011\nvariable "x" {\n  type = string\n}\n`);
+    expect(scan.fileDirective?.misplaced).toBeFalsy();
+  });
+});
+
+describe("directivesFor", () => {
+  test("combines an anchored directive with the file-level one, and reports the block's line", () => {
+    const source = [
+      "# chant-ignore-file: TF011",
+      "# chant-ignore: TF010",
+      'variable "x" {',
+      "  type = string",
+      "}",
+    ].join("\n");
+    const scan = scanSuppressions("main.tf", source);
+    const { line, suppressions } = directivesFor(scan, "var.x");
+    expect(line).toBe(3);
+    expect(suppressions?.map((d) => d.form).sort()).toEqual(["chant-ignore", "chant-ignore-file"]);
+  });
+
+  test("an address with no recorded block line yields no line and no suppressions", () => {
+    const scan = scanSuppressions("main.tf", `variable "x" {\n  type = string\n}\n`);
+    const { line, suppressions } = directivesFor(scan, "var.y");
+    expect(line).toBeUndefined();
+    expect(suppressions).toBeUndefined();
+  });
+
+  test("popping the same address twice returns each recorded line once (FIFO)", () => {
+    const scan = scanSuppressions("main.tf", `locals {\n  a = 1\n}\n\nlocals {\n  b = 2\n}\n`);
+    expect(directivesFor(scan, "locals").line).toBe(1);
+    expect(directivesFor(scan, "locals").line).toBe(5);
+    expect(directivesFor(scan, "locals").line).toBeUndefined();
+  });
+});

package/src/hcl/suppressions.ts

@@ -0,0 +1,204 @@
+/**
+ * Read `# chant-ignore*` comments out of raw `.tf` text.
+ *
+ * `hcl2json` drops comments entirely, and a probe of its output confirmed it
+ * exposes no source ranges either, so a suppression comment has nothing to
+ * attach to once a file goes through `@cdktf/hcl2json`. This module runs a
+ * second, cheap pass over the SAME raw text `./parse.ts` hands the parser,
+ * entirely with line-oriented regexes: a brace-depth counter to find each
+ * top-level block's start line (`terraform`, `locals`, `provider "x"`,
+ * `module "x"`, `variable "x"`, `output "x"`, `resource "t" "n"`,
+ * `data "t" "n"`, the exact set `blocksToEntities` turns into entities, and
+ * the address format below MUST stay in sync with that function's `add()`
+ * calls), and a directive regex for the three comment forms.
+ *
+ * `scanSuppressions` returns per-file lookups keyed by ADDRESS (`./parse.ts`'s
+ * `TerraformEntity.props.address`, e.g. `provider.aws`, `aws_s3_bucket.assets`)
+ * rather than by entity, because `blocksToEntities` computes an entity's final
+ * map key (with a `~2`/`~3` collision suffix) only after this scan has already
+ * run. A FIFO queue per address reconciles the two traversal orders: this
+ * scan reads the file top to bottom, but `blocksToEntities` walks hcl2json's
+ * tree grouped by section (all `variable` blocks together, then all
+ * `resource` blocks, etc.), not in source order. Two blocks that share one
+ * address (the same genuinely-duplicated declaration) are matched to their
+ * queue slot in file order, same as they're numbered `~2`/`~3` in file order.
+ */
+
+import type { SuppressionDirective, SuppressionIds } from "@intentius/chant/lint/suppressions";
+
+/** A block header keyword with zero labels (`terraform {`, `locals {`). */
+const BARE_RE = /^\s*(terraform|locals)\s*\{/;
+/** One label (`provider "aws" {`, `module "vpc" {`, `variable "x" {`, `output "x" {`). */
+const ONE_LABEL_RE = /^\s*(provider|module|variable|output)\s+"([^"]*)"\s*\{/;
+/** Two labels (`resource "aws_s3_bucket" "assets" {`, `data "aws_ami" "x" {`). */
+const TWO_LABEL_RE = /^\s*(resource|data)\s+"([^"]*)"\s+"([^"]*)"\s*\{/;
+
+/** A `#`/`//` comment naming one of the three suppression forms. */
+const DIRECTIVE_RE = /^\s*(?:#|\/\/)\s*chant-ignore(-file|-block)?\s*:?\s*(.*)$/;
+
+/** `./parse.ts`'s own address format per block kind, kept in sync by hand. */
+function addressFor(keyword: string, labels: string[]): string {
+  switch (keyword) {
+    case "terraform":
+      return "terraform";
+    case "locals":
+      return "locals";
+    case "provider":
+      return `provider.${labels[0]}`;
+    case "module":
+      return `module.${labels[0]}`;
+    case "variable":
+      return `var.${labels[0]}`;
+    case "output":
+      return `output.${labels[0]}`;
+    case "resource":
+      return `${labels[0]}.${labels[1]}`;
+    case "data":
+      return `data.${labels[0]}.${labels[1]}`;
+    default:
+      return "";
+  }
+}
+
+/** Strip quoted string contents so a brace inside a literal (a jsonencode payload) doesn't skew depth tracking. */
+function stripStrings(line: string): string {
+  return line.replace(/"(?:[^"\\]|\\.)*"/g, '""');
+}
+
+function braceDelta(line: string): number {
+  const stripped = stripStrings(line);
+  let delta = 0;
+  for (const ch of stripped) {
+    if (ch === "{") delta++;
+    else if (ch === "}") delta--;
+  }
+  return delta;
+}
+
+function parseDirectiveBody(rest: string): { ids: SuppressionIds; expires?: string } {
+  const tokens = rest.split(/\s+/).filter(Boolean);
+  let expires: string | undefined;
+  const idTokens: string[] = [];
+  for (const tok of tokens) {
+    const m = /^exp:(\d{4}-\d{2}-\d{2})$/.exec(tok);
+    if (m) {
+      expires = m[1];
+      continue;
+    }
+    idTokens.push(tok);
+  }
+  const joined = idTokens.join(" ").trim();
+  if (joined === "" || joined.toLowerCase() === "all") return { ids: "all", expires };
+  const ids = new Set(
+    joined
+      .split(/[,\s]+/)
+      .map((s) => s.trim().toUpperCase())
+      .filter(Boolean),
+  );
+  return { ids, expires };
+}
+
+/** One file's suppression scan: block start lines by address, and the parsed directives. */
+export interface FileScan {
+  /** address -> start lines, in file order (a FIFO queue for repeated addresses). */
+  blockLineQueues: Map<string, number[]>;
+  /** The block start line a `chant-ignore`/`chant-ignore-block` comment anchors to -> directives found there. */
+  byAnchorLine: Map<number, SuppressionDirective[]>;
+  /** The file's `chant-ignore-file` directive, if any (`misplaced` set when it wasn't the first non-blank line). */
+  fileDirective?: SuppressionDirective;
+}
+
+function recordBlockLine(queues: Map<string, number[]>, address: string, lineNo: number): void {
+  const q = queues.get(address) ?? [];
+  q.push(lineNo);
+  queues.set(address, q);
+}
+
+/**
+ * Scan one `.tf` file's raw text. `fileName` only labels the directives it
+ * returns (for messages and dedup); the scan itself is pure text.
+ */
+export function scanSuppressions(fileName: string, source: string): FileScan {
+  const lines = source.split("\n");
+  const blockLineQueues = new Map<string, number[]>();
+  const byAnchorLine = new Map<number, SuppressionDirective[]>();
+  let fileDirective: SuppressionDirective | undefined;
+  let firstNonBlankLine: number | undefined;
+  let depth = 0;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const lineNo = i + 1;
+    const trimmed = line.trim();
+
+    if (firstNonBlankLine === undefined && trimmed !== "") firstNonBlankLine = lineNo;
+
+    const directiveMatch = DIRECTIVE_RE.exec(line);
+    if (directiveMatch) {
+      const suffix = directiveMatch[1];
+      const { ids, expires } = parseDirectiveBody(directiveMatch[2].trim());
+
+      if (suffix === "-file") {
+        fileDirective = {
+          form: "chant-ignore-file",
+          ids,
+          expires,
+          file: fileName,
+          line: lineNo,
+          misplaced: lineNo !== firstNonBlankLine,
+          key: `${fileName}:${lineNo}:chant-ignore-file`,
+        };
+      } else {
+        const form = suffix === "-block" ? "chant-ignore-block" : "chant-ignore";
+        const directive: SuppressionDirective = {
+          form,
+          ids,
+          expires,
+          file: fileName,
+          line: lineNo,
+          key: `${fileName}:${lineNo}:${form}`,
+        };
+        const anchorLine = lineNo + 1;
+        const list = byAnchorLine.get(anchorLine) ?? [];
+        list.push(directive);
+        byAnchorLine.set(anchorLine, list);
+      }
+    } else if (depth === 0) {
+      // Only look for a block header on a line that isn't itself a directive
+      // comment, and only at top-level nesting (depth 0 before this line).
+      let m: RegExpExecArray | null = BARE_RE.exec(line);
+      if (m) {
+        recordBlockLine(blockLineQueues, addressFor(m[1], []), lineNo);
+      } else if ((m = ONE_LABEL_RE.exec(line))) {
+        recordBlockLine(blockLineQueues, addressFor(m[1], [m[2]]), lineNo);
+      } else if ((m = TWO_LABEL_RE.exec(line))) {
+        recordBlockLine(blockLineQueues, addressFor(m[1], [m[2], m[3]]), lineNo);
+      }
+    }
+
+    depth += braceDelta(line);
+  }
+
+  return { blockLineQueues, byAnchorLine, fileDirective };
+}
+
+/** Pop the next recorded start line for `address` (FIFO; see module doc). */
+export function popBlockLine(scan: FileScan, address: string): number | undefined {
+  const q = scan.blockLineQueues.get(address);
+  if (!q || q.length === 0) return undefined;
+  return q.shift();
+}
+
+/**
+ * Directives to attach to the entity being added for `address`: the ones
+ * anchored to its own start line (`chant-ignore`/`chant-ignore-block`), plus
+ * the file-level one, if any. Every entity in a file carries a file-level
+ * directive, misplaced or not (misplaced ones report themselves but suppress
+ * nothing; see `applyInlineSuppressions`).
+ */
+export function directivesFor(scan: FileScan, address: string): { line?: number; suppressions?: SuppressionDirective[] } {
+  const line = popBlockLine(scan, address);
+  const anchored = line !== undefined ? (scan.byAnchorLine.get(line) ?? []) : [];
+  const all = scan.fileDirective ? [...anchored, scan.fileDirective] : anchored;
+  return { line, suppressions: all.length > 0 ? all : undefined };
+}