@intentius/chant 0.57.0 → 0.59.0

package/src/audit/catalog.test.ts

@@ -1,14 +1,14 @@
 import { describe, test, expect } from "vitest";
 import { readdirSync } from "fs";
 import { join } from "path";
-import { RULE_CATALOG, RULE_CATEGORY, auditRule, resolveAuditCatalog } from "./catalog";
+import { PRIOR_ART, RULE_CATALOG, RULE_CATEGORY, auditRule, resolveAuditCatalog, canonicalRuleId } from "./catalog";
 import { loadPlugins } from "../cli/plugins";
 
 /**
  * Every lexicon in the repo, enumerated rather than listed (#1346).
  *
  * This was nine hardcoded names. It missed fountain, which contributes a
- * catalog, and could not notice fly and temporal, which did not — so their six
+ * catalog, and could not notice fly, which did not — so their six
  * post-synth checks reached `chant audit` with no title, tier, fix kind, or
  * category, and the guard meant to catch exactly that was blind to them. A
  * thirteenth lexicon would have been invisible to it on arrival.
@@ -67,6 +67,11 @@ describe("RULE_CATALOG (aggregated: core static + lexicon-contributed, #687)", (
       .filter((id) => !shipped.has(id))
       // Core's own cross-cutting ids are not any one lexicon's to ship.
       .filter((id) => !(id in RULE_CATALOG))
+      // A deprecated rule is deliberately kept in the catalog after its check
+      // stops shipping (chant #2113). That's the whole point of `deprecated`
+      // over deleting the entry, so it's not "stale" the way an orphaned
+      // entry with no explanation is.
+      .filter((id) => !catalog[id]?.deprecated)
       .sort();
     expect(stale).toEqual([]);
   });
@@ -123,6 +128,33 @@ describe("RULE_CATALOG (aggregated: core static + lexicon-contributed, #687)", (
     }
   });
 
+  test("lineage entries key into PRIOR_ART, link over https, and use a known relation", async () => {
+    const relations = new Set(["equivalent", "overlaps", "extends"]);
+    for (const [id, m] of Object.entries(await aggregate())) {
+      for (const l of m.lineage ?? []) {
+        expect(l.tool in PRIOR_ART, `${id} credits unregistered tool "${l.tool}"`).toBe(true);
+        expect(l.url.startsWith("https://"), `${id} lineage url ${l.url}`).toBe(true);
+        expect(relations.has(l.relation), `${id} lineage relation ${l.relation}`).toBe(true);
+      }
+    }
+  });
+
+  test("lineage is credit, not authority: it never forces a category or tier", () => {
+    const m = auditRule("ZZZ001", "report-only", "guidance", "t", "r", {
+      lineage: [{ tool: Object.keys(PRIOR_ART)[0] as never, url: "https://example.invalid/x", relation: "overlaps" }],
+    });
+    expect(m.category).toBe("best-practice");
+    expect(m.tier).toBe("report-only");
+    expect(m.lineage?.length).toBe(1);
+  });
+
+  test("every registered prior-art tool is credited by at least one rule", async () => {
+    const used = new Set<string>();
+    for (const m of Object.values(await aggregate())) for (const l of m.lineage ?? []) used.add(l.tool);
+    const idle = Object.keys(PRIOR_ART).filter((k) => !used.has(k)).sort();
+    expect(idle, "PRIOR_ART entries no rule credits").toEqual([]);
+  });
+
   test("flagship security rules carry an authority citation", async () => {
     const catalog = await aggregate();
     const flagship = ["GHA017", "GHA021", "GHA029", "GHA033", "GHA034", "GHA036", "GHA037", "WGL016", "WGL029"];
@@ -134,13 +166,34 @@ describe("RULE_CATALOG (aggregated: core static + lexicon-contributed, #687)", (
     }
   });
 
+  test("a deprecated id must still resolve (chant #2113): the inverse of the every-check-has-metadata test above", async () => {
+    // A retired check ships no runtime PostSynthCheck any more, so it is
+    // absent from `realCheckIds()`/`shippedRuleIds()` — that's what makes it
+    // "deprecated" rather than merely renamed. The catalog entry, and its
+    // resolution, must survive that removal.
+    const catalog = {
+      ...RULE_CATALOG,
+      ZZZ900: auditRule("ZZZ900", "report-only", "guidance", "Retired check", "No longer applicable.", {
+        category: "best-practice",
+      }),
+    };
+    catalog.ZZZ900.deprecated = "superseded by ZZZ901";
+    expect(catalog.ZZZ900).toBeDefined();
+    expect(catalog.ZZZ900.deprecated).toBe("superseded by ZZZ901");
+    expect(canonicalRuleId("ZZZ900", catalog)).toBe("ZZZ900");
+  });
+
   test("deterministic fixes are limited to the safe mechanical set", async () => {
     const deterministic = Object.values(await aggregate())
       .filter((m) => m.fixKind === "deterministic")
       .map((m) => m.id)
       .sort();
+    // TF016 and TF019 (#2110) are the first report-only rules in the set: both
+    // unquote or delete exactly the flagged line, which is as mechanical as
+    // pinning an action, and `report-model.ts` renders them as quick wins for
+    // that reason. Every entry here needs a case in `proof.ts`'s `proveFix`.
     expect(deterministic).toEqual(
-      ["GHA017", "GHA021", "GHA029", "GHA030", "GHA033", "WGL031"].sort(),
+      ["GHA017", "GHA021", "GHA029", "GHA030", "GHA033", "TF016", "TF019", "WGL031"].sort(),
     );
   });
 });
@@ -164,6 +217,29 @@ describe("auditRule (lexicon-facing catalog constructor, #687)", () => {
   });
 });
 
+describe("canonicalRuleId (chant #2113, alias resolution)", () => {
+  const catalog: Record<string, ReturnType<typeof auditRule>> = {
+    NEW001: { ...auditRule("NEW001", "report-only", "guidance", "T", "r"), aliases: ["OLD001", "LEGACY_OLD"] },
+  };
+
+  test("a canonical id passes through unchanged", () => {
+    expect(canonicalRuleId("NEW001", catalog)).toBe("NEW001");
+  });
+
+  test("an alias resolves to the canonical id", () => {
+    expect(canonicalRuleId("OLD001", catalog)).toBe("NEW001");
+    expect(canonicalRuleId("LEGACY_OLD", catalog)).toBe("NEW001");
+  });
+
+  test("an id that is neither a key nor an alias passes through unchanged", () => {
+    expect(canonicalRuleId("NOBODY_KNOWS_THIS", catalog)).toBe("NOBODY_KNOWS_THIS");
+  });
+
+  test("defaults to the static core RULE_CATALOG when no catalog is given", () => {
+    expect(canonicalRuleId("SEC001")).toBe("SEC001");
+  });
+});
+
 describe("resolveAuditCatalog (#687 aggregation seam)", () => {
   test("with no lexicons, returns a copy of the static core catalog", async () => {
     const resolved = await resolveAuditCatalog([]);

package/src/audit/catalog.ts

@@ -17,6 +17,11 @@
  * test asserts the aggregate stays in sync with the lexicons' post-synth checks.
  */
 
+import type { Lineage } from "./prior-art";
+import { applyLineage as attachLineage } from "./prior-art";
+import { coreAuditLineage } from "./lineage";
+export { PRIOR_ART, applyLineage, lineageLabel, type Lineage, type LineageRelation, type PriorArtEntry, type PriorArtTool } from "./prior-art";
+
 export type Tier = "merge-worthy" | "report-only";
 
 /** deterministic = safe auto-fix/diff; guidance = report text only (needs judgment). */
@@ -48,14 +53,42 @@ export interface RuleMeta {
   title: string;
   /** External backing so a finding isn't just chant's opinion. */
   authority?: Authority[];
+  /**
+   * Prior art: the open-source tools whose rules check the same condition
+   * (./prior-art.ts). Credit, not authority — never affects tier or category.
+   */
+  lineage?: Lineage[];
   /** One-line fix guidance (always present). */
   remediation: string;
   /**
    * False if the check reads the chant model (`ctx.entities`) rather than the
    * emitted YAML (`ctx.outputs`) — such a check won't fire on audited YAML.
-   * All current post-synth checks are output-based, so this is true.
+   * Most post-synth checks are output-based, but cpln, fly, fountain, k3s
+   * and render all ship model-based checks with this false.
    */
   yamlBased: boolean;
+  /**
+   * Retired ids this rule used to ship under (chant #2113). A rule id is
+   * public the day it ships. trivy's checks carry `id`, `long_id` and
+   * `aliases` for exactly this reason, so a rename or a scheme migration
+   * doesn't strand every existing reference to the old id. An alias resolves
+   * to this entry wherever a rule id is looked up by a human or a config.
+   * `canonicalRuleId()` (below) is the shared resolver; a `lint.rules` key
+   * and #2111's HCL suppression both go through it (or will, since #2111
+   * lands separately and is not touched by this change).
+   */
+  aliases?: string[];
+  /**
+   * Set when this rule is retired: `true`, or a string explaining what
+   * replaced it / why it no longer fires. A deprecated rule stays in the
+   * catalog rather than being deleted. trivy's `deprecated: true` field lets
+   * a ruleset retire a check without breaking every existing suppression or
+   * dashboard that still names it, so its id keeps resolving (via `aliases`
+   * on whichever rule superseded it, when there is one) and the rules page
+   * still lists it, greyed out, instead of the id going dark with no
+   * explanation.
+   */
+  deprecated?: boolean | string;
 }
 
 // ── Authority references ─────────────────────────────────────────────
@@ -147,6 +180,10 @@ export const CWE_HARDCODED_CREDS: Authority = {
   name: "CWE-798 — Use of Hard-coded Credentials",
   url: "https://cwe.mitre.org/data/definitions/798.html",
 };
+export const HASHICORP_STYLE_GITIGNORE: Authority = {
+  name: "HashiCorp Terraform style guide — .gitignore",
+  url: "https://developer.hashicorp.com/terraform/language/style#gitignore",
+};
 export const CWE_CLEARTEXT: Authority = {
   name: "CWE-319 — Cleartext Transmission of Sensitive Information",
   url: "https://cwe.mitre.org/data/definitions/319.html",
@@ -159,13 +196,14 @@ function meta(
   title: string,
   remediation: string,
   authority?: Authority[],
+  lineage?: Lineage[],
 ): RuleMeta {
   // An authority citation is the strongest security signal, so it wins. Otherwise
   // the curated RULE_CATEGORY map (defined below, before RULE_CATALOG runs)
   // decides correctness vs best-practice vs security-without-authority; the drift
   // test guarantees every id is mapped, so the fallback is only a type belt.
   const category: Category = authority && authority.length > 0 ? "security" : RULE_CATEGORY[id] ?? "best-practice";
-  return { id, tier, fixKind, category, title, remediation, authority, yamlBased: true };
+  return { id, tier, fixKind, category, title, remediation, authority, ...(lineage?.length ? { lineage } : {}), yamlBased: true };
 }
 
 const M = "merge-worthy" as const;
@@ -221,6 +259,10 @@ export const RULE_CATEGORY: Record<string, Category> = {
   NGX005: "security",
   NGX006: "best-practice",
   NGX007: "best-practice",
+  // TF023 — Terraform state committed to the repository. Core-owned for the
+  // same reason SEC/WRG/NGX are: it reads the discovered file list, not a
+  // parsed root module. See ./terraform-state.ts.
+  TF023: "security",
   // AGT — agent configuration (`chant audit --agents`). Core-owned like COR/EXT:
   // these run against the machine's own agent config, not against any one
   // lexicon's emitted output, so no lexicon ships them.
@@ -282,6 +324,21 @@ export const RULE_CATALOG: Record<string, RuleMeta> = {
   NGX006: meta("NGX006", R, G, "Server version disclosure", "Add `server_tokens off;` in the http block so nginx stops advertising its exact version in the Server header and error pages."),
   NGX007: meta("NGX007", R, G, "Access logging disabled at server scope", "Re-enable access_log at http/server scope (silencing a single noisy location is fine) so requests are recorded for incident investigation."),
 
+  // TF023 (#2110) — Terraform state, or the `.terraform/` working directory,
+  // committed to the repository. The one TF rule core owns: every other TF id
+  // is a post-synth check over a parsed root module (the terraform lexicon's
+  // `auditCatalog()`), while this one reads the discovered file list and never
+  // runs during `chant build`. Same shape as SEC/WRG/NGX above, and the same
+  // reason it lives here: `terraform-state.ts` needs no lexicon installed.
+  TF023: meta(
+    "TF023",
+    M,
+    G,
+    "Terraform state committed to the repository",
+    "Delete the state file (or `.terraform/`) from version control, add it to .gitignore, move the state to a remote backend, and rotate every credential the file held.",
+    [HASHICORP_STYLE_GITIGNORE],
+  ),
+
   // ── Agent configuration (`chant audit --agents`) ──────────────────
   AGT001: agentMeta(
     "AGT001",
@@ -337,6 +394,9 @@ export const RULE_CATALOG: Record<string, RuleMeta> = {
   ),
 };
 
+// Prior art credits for the core static rules (SEC/WRG/NGX/AGT/EXT) — ./lineage.ts.
+attachLineage(RULE_CATALOG, coreAuditLineage);
+
 /**
  * Build one catalog entry — the lexicon-facing constructor for
  * `LexiconPlugin.auditCatalog()` (#687), so a lexicon can declare its own rules'
@@ -351,10 +411,20 @@ export function auditRule(
   fixKind: FixKind,
   title: string,
   remediation: string,
-  opts?: { authority?: Authority[]; category?: Category },
+  opts?: { authority?: Authority[]; category?: Category; lineage?: Lineage[] },
 ): RuleMeta {
   const category: Category = opts?.authority && opts.authority.length > 0 ? "security" : (opts?.category ?? "best-practice");
-  return { id, tier, fixKind, category, title, remediation, authority: opts?.authority, yamlBased: true };
+  return {
+    id,
+    tier,
+    fixKind,
+    category,
+    title,
+    remediation,
+    authority: opts?.authority,
+    ...(opts?.lineage?.length ? { lineage: opts.lineage } : {}),
+    yamlBased: true,
+  };
 }
 
 /**
@@ -374,15 +444,18 @@ export async function resolveAuditCatalog(lexicons: string[]): Promise<Record<st
     lexicons.includes("forgejo") && !lexicons.includes("github") ? [...lexicons, "github"] : lexicons;
   if (needed.length === 0) return catalog;
   // Lazy import so importing this module doesn't pull in the plugin/config graph
-  // (matches ./core.ts's `load` — see #408).
-  const { loadPlugins } = await import("../cli/plugins");
-  let plugins: Array<{ auditCatalog?(): Record<string, RuleMeta> }>;
-  try {
-    plugins = await loadPlugins(needed);
-  } catch {
-    return catalog; // a lexicon package isn't installed — fall back to the static core catalog.
-  }
-  for (const plugin of plugins) {
+  // (matches ./core.ts's `load` — see #408). Loaded one at a time (rather than
+  // the bulk `loadPlugins`, which aborts on the first failure) so one
+  // not-yet-installed lexicon (e.g. terraform, #2085) doesn't drop every other
+  // lexicon's contributed catalog back to the static core map.
+  const { loadPlugin } = await import("../cli/plugins");
+  for (const name of needed) {
+    let plugin: { auditCatalog?(): Record<string, RuleMeta> };
+    try {
+      plugin = await loadPlugin(name);
+    } catch {
+      continue; // a lexicon package isn't installed, its catalog just doesn't contribute.
+    }
     const contributed = plugin?.auditCatalog?.();
     if (contributed) Object.assign(catalog, contributed);
   }
@@ -394,6 +467,31 @@ export function ruleMeta(id: string): RuleMeta | undefined {
   return RULE_CATALOG[id];
 }
 
+/**
+ * Resolve a rule id to its canonical form against `catalog` (chant #2113). An
+ * id that is itself a key of `catalog` passes through unchanged (this covers
+ * the common case without scanning every entry's `aliases`); otherwise every
+ * entry's `aliases` is searched for a match, and the id it belongs to is
+ * returned. An id neither a key nor anyone's alias passes through unchanged
+ * too, since this is a best-effort resolver, not a validator, so an unknown
+ * id is a caller's problem, not this function's.
+ *
+ * Exported so a `lint.rules`/preset key that names an alias resolves to the
+ * rule that actually runs (see `resolveConfiguredSeverity`,
+ * `../lint/config.ts`), and so #2111's HCL suppression code can key an
+ * inline `# chant-ignore <id>` off the same resolution once it lands — that
+ * suppression mechanism does not exist yet in this worktree (#2111 is a
+ * separate, parallel issue), so this function is exported now for it to call
+ * later rather than being wired into it here.
+ */
+export function canonicalRuleId(id: string, catalog: Record<string, RuleMeta> = RULE_CATALOG): string {
+  if (id in catalog) return id;
+  for (const [canonicalId, meta] of Object.entries(catalog)) {
+    if (meta.aliases?.includes(id)) return canonicalId;
+  }
+  return id;
+}
+
 /** Docs path for the audit rules reference (one anchor per rule id). */
 export const RULES_DOC_PATH = "/chant/lint-rules/audit-rules/";
 

package/src/audit/core.test.ts

@@ -208,6 +208,32 @@ describe("auditFiles", () => {
     expect(findings.map((f) => `${f.file}:${f.entity}`).sort()).toEqual(["a.yaml:one", "b.yaml:two"]);
   });
 
+  test("parse-to-graph with an async entities parser: auditFiles awaits it into ctx.entities (#2082)", async () => {
+    const entityCheck: PostSynthCheck = {
+      id: "ENT003",
+      description: "reads ctx.entities, not ctx.outputs",
+      check: (ctx) =>
+        [...ctx.entities.keys()].map((name) => ({ checkId: "ENT003", severity: "warning" as const, message: `saw ${name}`, entity: name })),
+    };
+    const findings = await auditFiles(
+      [
+        { path: "a.tf", content: "one", lexicon: "terraform" },
+        { path: "b.tf", content: "two", lexicon: "terraform" },
+      ],
+      {
+        checksProvider: async () => [entityCheck],
+        // The lexicon's parser is inherently async (a lazy-loaded wasm HCL
+        // parser, per #1567's terraform follow-up). The returned Promise
+        // must be awaited before the check sees ctx.entities.
+        entitiesProvider: async () => async (content) => {
+          await Promise.resolve();
+          return new Map([[content, { entityType: "T::X" } as never]]);
+        },
+      },
+    );
+    expect(findings.map((f) => `${f.file}:${f.entity}`).sort()).toEqual(["a.tf:one", "b.tf:two"]);
+  });
+
   test("parse-to-graph merge: the same entity name in two files keeps both — a duplicate check sees the collision cross-file", async () => {
     const dupCheck: PostSynthCheck = {
       id: "DUP001",

package/src/audit/core.ts

@@ -22,9 +22,10 @@
 
 import { basename } from "path";
 import type { Severity } from "../lint/rule";
-import type { PostSynthCheck, PostSynthContext } from "../lint/post-synth";
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "../lint/post-synth";
+import { applyInlineSuppressions, type SuppressionMetaFinding } from "../lint/suppressions";
 import type { SerializerResult } from "../serializer";
-import type { LexiconPlugin } from "../lexicon";
+import type { AuditEntitiesInput, LexiconPlugin } from "../lexicon";
 import type { Declarable } from "../declarable";
 
 /**
@@ -60,6 +61,16 @@ export interface AuditInput {
    * — checks that read `output.files` (helm, docker) see the whole bundle.
    */
   files?: Record<string, string>;
+  /**
+   * Absolute directory this input's files were read from, set by discovery on
+   * a local walk for the inputs whose `path` names a directory (#2217). It
+   * reaches a lexicon's `auditEntities` as `AuditEntitiesInput.dir`, which is
+   * what lets terraform follow a root module's local `module` calls. Undefined
+   * for a remote tree fetch and for a single-file input.
+   */
+  dir?: string;
+  /** Absolute path of the audited root, when discovery walked one (#2217). The boundary `dir` may read within. */
+  baseDir?: string;
 }
 
 /** A finding produced by a post-synth check against an audited file. */
@@ -82,6 +93,8 @@ export interface AuditFinding {
    * itself.
    */
   fingerprint?: string;
+  /** Carried verbatim from the producing `PostSynthDiagnostic.missing` (chant #2113) — see its doc comment. */
+  missing?: { kind: string; scope: string };
 }
 
 /**
@@ -94,8 +107,18 @@ export type ChecksProvider = (lexicon: AuditLexicon) => Promise<PostSynthCheck[]
  * Parse one classified file's content into the lexicon's entity graph — the
  * parse-to-graph half of the audit (#1567). The returned map is what
  * `ctx.entities` holds during a build, so entity-reading checks run unchanged.
+ * May return a `Promise` for a lexicon whose parser is inherently async (e.g.
+ * terraform's HCL parser); `auditLexicon`'s `entitiesFor` awaits it.
+ *
+ * The second argument carries the input's discovery facts (its path, and the
+ * directory it was read from on a local walk), so a lexicon whose unit of
+ * parsing is a directory can name its scope after that directory and read the
+ * directories it references (#2217).
  */
-export type EntitiesParser = (content: string) => Map<string, Declarable>;
+export type EntitiesParser = (
+  content: string,
+  input?: AuditEntitiesInput,
+) => Map<string, Declarable> | Promise<Map<string, Declarable>>;
 
 /**
  * Resolve the entities parser for a lexicon (its plugin's `auditEntities`,
@@ -179,13 +202,25 @@ async function defaultEntitiesProvider(lexicon: AuditLexicon): Promise<EntitiesP
   return parser;
 }
 
+/**
+ * Mutable out-param for the inline (`# chant-ignore*`) suppression count
+ * (chant #2111): `auditFiles`'s return type stays `AuditFinding[]` for every
+ * existing caller, so a caller that wants the count (`chant audit`'s CLI, for
+ * its summary line) passes this in and reads `.count` back afterward, rather
+ * than `auditFiles` growing a `{findings, suppressedCount}` shape that would
+ * touch every existing call site.
+ */
+export interface SuppressionStats {
+  count: number;
+}
+
 /**
  * Audit a set of CI files and return all findings. Pure with respect to the
  * filesystem and network — callers supply file contents.
  */
 export async function auditFiles(
   inputs: AuditInput[],
-  opts: { checksProvider?: ChecksProvider; entitiesProvider?: EntitiesProvider } = {},
+  opts: { checksProvider?: ChecksProvider; entitiesProvider?: EntitiesProvider; suppressionStats?: SuppressionStats } = {},
 ): Promise<AuditFinding[]> {
   const provider = opts.checksProvider ?? defaultChecksProvider;
   const entitiesProvider = opts.entitiesProvider ?? defaultEntitiesProvider;
@@ -203,7 +238,7 @@ export async function auditFiles(
     const checks = await provider(lexicon);
     if (checks.length === 0) continue;
     const parseEntities = await entitiesProvider(lexicon);
-    findings.push(...auditLexicon(lexicon, files, checks, parseEntities));
+    findings.push(...(await auditLexicon(lexicon, files, checks, parseEntities, opts.suppressionStats)));
   }
 
   return findings;
@@ -224,14 +259,20 @@ function toOutput(file: AuditInput): string | SerializerResult {
   return { primary: file.content, files: { [basename(file.path)]: file.content } };
 }
 
+interface CheckRunResult {
+  diagnostics: PostSynthDiagnostic[];
+  suppressed: PostSynthDiagnostic[];
+  meta: SuppressionMetaFinding[];
+}
+
 function runChecks(
   checks: PostSynthCheck[],
   outputs: Map<string, string | SerializerResult>,
   entities: Map<string, Declarable> = new Map(),
-): ReturnType<PostSynthCheck["check"]> {
+): CheckRunResult {
   const buildResult: PostSynthContext["buildResult"] = { outputs, entities, warnings: [], errors: [], sourceFileCount: outputs.size };
   const ctx: PostSynthContext = { outputs, entities: buildResult.entities, buildResult };
-  const diags = [];
+  const diags: PostSynthDiagnostic[] = [];
   for (const check of checks) {
     try {
       diags.push(...check.check(ctx));
@@ -239,7 +280,11 @@ function runChecks(
       // A check that throws on unusual external YAML must not abort the audit.
     }
   }
-  return diags;
+  // chant #2111: `rules` (for `ignorable: false`) is omitted, since `chant audit`
+  // has no project `lint.rules` to read here (see `applyInlineSuppressions`'s
+  // doc comment for why that's a deliberate scope line, not an oversight), so
+  // every rule id reads as ignorable, same as an unconfigured one everywhere.
+  return applyInlineSuppressions(diags, entities);
 }
 
 function diagKey(d: { checkId: string; entity?: string; message: string }): string {
@@ -281,40 +326,61 @@ function mergeEntities(maps: Array<Map<string, Declarable>>): Map<string, Declar
  * the entity graph parsed from its files — per file for the per-file pass, all
  * files merged for the all-files pass — so entity-reading checks fire and
  * cross-file facts (an Agent's Environment declared elsewhere, a name declared
- * twice across the apply directory) resolve in the all-files pass.
+ * twice across the apply directory) resolve in the all-files pass. The parser
+ * may be async (a lexicon's own choice, e.g. a wasm-backed HCL parser); this
+ * function awaits each file's entities before either pass runs.
  */
-function auditLexicon(lexicon: AuditLexicon, files: AuditInput[], checks: PostSynthCheck[], parseEntities?: EntitiesParser): AuditFinding[] {
-  const entitiesFor = (file: AuditInput): Map<string, Declarable> => {
+async function auditLexicon(
+  lexicon: AuditLexicon,
+  files: AuditInput[],
+  checks: PostSynthCheck[],
+  parseEntities?: EntitiesParser,
+  suppressionStats?: SuppressionStats,
+): Promise<AuditFinding[]> {
+  const entitiesFor = async (file: AuditInput): Promise<Map<string, Declarable>> => {
     if (!parseEntities) return new Map();
     try {
-      return parseEntities(file.content);
+      return await parseEntities(file.content, {
+        path: file.path,
+        ...(file.dir !== undefined ? { dir: file.dir } : {}),
+        ...(file.baseDir !== undefined ? { baseDir: file.baseDir } : {}),
+      });
     } catch {
       // The audit contract is "runs against any repo" — unparseable content
       // contributes no entities, never a crash.
       return new Map();
     }
   };
-  const perEntities = new Map(files.map((f) => [f.path, entitiesFor(f)]));
+  const perEntities = new Map(await Promise.all(files.map(async (f) => [f.path, await entitiesFor(f)] as const)));
 
   const perFindings: AuditFinding[] = [];
   const perKeys = new Set<string>();
+  // chant #2111: meta findings (an expired/misplaced/denied suppression
+  // directive) are collected from the per-file pass only: the all-files pass
+  // below sees the same entities merged, so it would report the identical
+  // directive again. Counted the same way, once, here too.
+  const metaFindings: AuditFinding[] = [];
   for (const file of files) {
-    const diags = runChecks(checks, new Map([[file.path, toOutput(file)]]), perEntities.get(file.path));
+    const { diagnostics: diags, suppressed, meta } = runChecks(checks, new Map([[file.path, toOutput(file)]]), perEntities.get(file.path));
+    if (suppressionStats) suppressionStats.count += suppressed.length;
+    for (const m of meta) {
+      metaFindings.push({ checkId: m.checkId, severity: m.severity, message: m.message, file: m.file, lexicon, line: m.line });
+    }
     for (const d of diags) {
-      perFindings.push({ checkId: d.checkId, severity: d.severity, message: d.message, file: file.path, lexicon: d.lexicon ?? lexicon, entity: d.entity });
+      perFindings.push({ checkId: d.checkId, severity: d.severity, message: d.message, file: file.path, lexicon: d.lexicon ?? lexicon, entity: d.entity, missing: d.missing });
       perKeys.add(diagKey(d));
     }
   }
 
   const allOutputs = new Map<string, string | SerializerResult>(files.map((f) => [f.path, toOutput(f)]));
-  const allDiags = runChecks(checks, allOutputs, mergeEntities([...perEntities.values()]));
+  const { diagnostics: allDiags } = runChecks(checks, allOutputs, mergeEntities([...perEntities.values()]));
   const allKeys = new Set(allDiags.map(diagKey));
 
   const out: AuditFinding[] = perFindings.filter((f) => allKeys.has(diagKey(f)));
   for (const d of allDiags) {
     if (!perKeys.has(diagKey(d))) {
-      out.push({ checkId: d.checkId, severity: d.severity, message: d.message, file: CROSS_FILE, lexicon: d.lexicon ?? lexicon, entity: d.entity });
+      out.push({ checkId: d.checkId, severity: d.severity, message: d.message, file: CROSS_FILE, lexicon: d.lexicon ?? lexicon, entity: d.entity, missing: d.missing });
     }
   }
-  return out;
+  return [...out, ...metaFindings];
 }

package/src/audit/discover.test.ts

@@ -92,6 +92,45 @@ describe("discoverByDetection (unified, detectTemplate-driven)", () => {
     const plugins = await loadAuditPlugins(["github", "definitely-not-a-real-lexicon"]);
     expect(plugins.map((p) => p.name)).toEqual(["github"]);
   });
+
+  test("loadAuditPlugins skips a lexicon whose package is not installed, quietly", async () => {
+    const plugins = await loadAuditPlugins(["github", "not-a-lexicon"]);
+    expect(plugins.map((p) => p.name)).toEqual(["github"]);
+  });
+
+  describe("Terraform directories as bundles, modeled on classifyHelm", () => {
+    // No real @intentius/chant-lexicon-terraform package exists yet (#2085), so
+    // these tests supply a bare stand-in plugin rather than loadAuditPlugins().
+    const terraform = { name: "terraform" };
+
+    test("a directory with two .tf files, and a nested subdirectory with its own .tf file, classify as two separate terraform inputs", () => {
+      const found = discoverByDetection(fixture("audit-terraform"), [terraform]);
+      const tf = found.filter((i) => i.lexicon === "terraform");
+      expect(targets(tf)).toEqual(["terraform:infra", "terraform:infra/modules/foo"]);
+      const root = tf.find((i) => i.path === "infra")!;
+      expect(Object.keys(root.files!).sort()).toEqual(["main.tf", "variables.tf"]);
+      const nested = tf.find((i) => i.path === "infra/modules/foo")!;
+      expect(Object.keys(nested.files!).sort()).toEqual(["main.tf"]);
+    });
+
+    test("a bundle's content is the whole root module in filename order, each file behind a `# file:` marker", () => {
+      const found = discoverByDetection(fixture("audit-terraform"), [terraform]);
+      const root = found.find((i) => i.lexicon === "terraform" && i.path === "infra")!;
+      expect(root.content).toContain("# file: main.tf\nresource \"null_resource\" \"root\" {}");
+      expect(root.content).toContain("# file: variables.tf\nvariable \"region\"");
+      expect(root.content.indexOf("# file: main.tf")).toBeLessThan(root.content.indexOf("# file: variables.tf"));
+    });
+
+    test(".terraform/ contributes no bundle (walkFiles already skips dot-directories outside WALK_DOT_DIRS)", () => {
+      const found = discoverByDetection(fixture("audit-terraform"), [terraform]);
+      expect(found.some((i) => i.path.includes(".terraform"))).toBe(false);
+    });
+
+    test("without the terraform plugin, .tf files are classified into nothing (skipped, same as an unloaded helm)", () => {
+      const found = discoverByDetection(fixture("audit-terraform"), []);
+      expect(found).toEqual([]);
+    });
+  });
 });
 
 describe("lexicon hints for unclaimed files (#1623)", () => {