infraweaver 0.3.7 → 0.3.8

package/src/mcp/terraform/scanners.ts

@@ -1,11 +1,27 @@
-import { existsSync, mkdtempSync, readdirSync, rmSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { join, posix } from "node:path";
+import { join, posix, relative } from "node:path";
+import { errorMessage } from "@infraweaver-io/core/errors";
 import { type } from "arktype";
-import { MAX_TF_TOTAL_BYTES, readTextCapped, walkTfFiles } from "#app/mcp/modules";
+import {
+  MAX_TF_TOTAL_BYTES,
+  parseModuleBlocks,
+  readTextCapped,
+  walkTfFiles,
+} from "#app/mcp/modules";
 import { loadProvidersSchema, unknownArgsForResource } from "#app/mcp/providerSchema";
-import { matchBraceBody, skipNonCode } from "#app/mcp/terraform/hcl";
+import { CHECKOV_SEVERITIES } from "#app/mcp/terraform/checkovSeverities";
+import { matchBraceBody, RESOURCE_HEADER, skipNonCode, unquoteLabel } from "#app/mcp/terraform/hcl";
 import { checkovTypeToLanguage, trivyTypeToLanguage } from "#app/mcp/terraform/iacLanguages";
+import { configFilesIn, localModuleClosure } from "#app/mcp/terraform/localModules";
+import {
+  type FetchDir,
+  isFetchedModulePath,
+  type ModuleFinding,
+  moduleCallLine,
+  relocateToCalls,
+  topModuleName,
+} from "#app/mcp/terraform/moduleFindings";
 import { scanNative } from "#app/mcp/terraform/nativeScan";
 import {
   type ResolvedRoot,
@@ -16,14 +32,16 @@ import {
 import { egressEnvFor, type ToolsNetworkDirective } from "#app/mcp/terraform/scannerEgress";
 import { parseScannerJson } from "#app/mcp/terraform/scannerJson";
 import { egressIsolationOf, scannerSpawn } from "#app/mcp/terraform/scannerNetns";
-import {
-  run,
-  runAsync,
-  type RunResult,
-  runTf,
-  runTfAsync,
-} from "#app/mcp/terraform/subprocess";
+import { type RunResult, run, runAsync, runTfAsync } from "#app/mcp/terraform/subprocess";
 import { assertToolchainIntegrity } from "#app/mcp/terraform/toolchainIntegrity";
+import {
+  isWithin,
+  type RootLayout,
+  skipDirsFor,
+  type TreeLayout,
+  treeLayout,
+  type VarFileMapping,
+} from "#app/mcp/terraform/treeLayout";
 import {
   buildConcern,
   type Concern,
@@ -39,20 +57,41 @@ import { log } from "#app/utils/cli";
 import { mapWithConcurrency } from "#app/utils/concurrency";
 import { type ResolvedToolSelection, scannerToolId } from "#app/utils/prompt/toolSelection";
 
-// dirs already `terraform init`-ed this process, so repeated scans don't re-init.
-const initedDirs = new Set<string>();
+// dirs already `terraform init`-ed this process, each with the module calls and
+// provider requirements it was initialised for, so repeated scans don't re-init
+// an unchanged root but one an edit gave a new module call is.
+const initedDirs = new Map<string, string>();
 
 /**
- * Run `terraform init -backend=false` once per dir so `terraform validate` has
- * provider schemas to check against (Bug 3 / gap B). Without init, validate only
- * emits "missing required provider" — which VALIDATE_NOISE drops — so it was
- * effectively inert. `-backend=false` avoids needing real backend credentials;
- * `-input=false` keeps it non-interactive. Network-dependent and best-effort: if
- * it fails (offline, private module, etc.) validate still runs, just shallow.
+ * What `terraform init` installs for a root: every module call and provider
+ * requirement across the root and the local modules it reaches. A refactor adds
+ * a module call between two validates; the init the first one ran never
+ * installed it, and validate's "Module not installed" is dropped as noise.
  */
+function initFingerprint(absDir: string): string {
+  const parts: string[] = [];
+  for (const dir of localModuleClosure(absDir).dirs) {
+    for (const file of configFilesIn(dir)) {
+      const text = readTextCapped(file) ?? "";
+      if (file.endsWith(".json")) {
+        parts.push(`${file}\n${text}`);
+        continue;
+      }
+      for (const m of parseModuleBlocks(text)) {
+        parts.push(`${file}|module|${m.name}|${m.source}|${m.version ?? ""}`);
+      }
+      for (const p of parseRequiredProviders(text)) {
+        parts.push(`${file}|provider|${p.name}|${p.source ?? ""}|${p.version ?? ""}`);
+      }
+    }
+  }
+  return parts.sort().join("\n");
+}
+
 /** Forget every init, so the next validate re-runs it — after its artefacts were removed. */
 export function resetTerraformInitCache(): void {
   initedDirs.clear();
+  initFailedDirs.clear();
 }
 
 let pluginCacheDir: string | undefined;
@@ -62,14 +101,21 @@ let pluginCacheDir: string | undefined;
  * cache for the whole process. A repository with many roots otherwise downloads
  * the same provider once per root, and a PR review inits every root twice (base
  * and head). The cache is private to the process (a fresh `mkdtemp`) and removed
- * on exit. Using it without a lock file checksum is admitted: the lock file
+ * on exit, unless the workflow names one in `TF_PLUGIN_CACHE_DIR` to keep it
+ * between runs. Using it without a lock file checksum is admitted: the lock file
  * init writes here is an artefact the scan removes, not a dependency decision.
  */
 function initEnv(extraEnv?: Record<string, string>): Record<string, string> {
   if (!pluginCacheDir) {
-    const dir = mkdtempSync(join(tmpdir(), "iw-tf-plugins-"));
-    pluginCacheDir = dir;
-    process.once("exit", () => rmSync(dir, { recursive: true, force: true }));
+    const kept = process.env.TF_PLUGIN_CACHE_DIR;
+    if (kept) {
+      mkdirSync(kept, { recursive: true });
+      pluginCacheDir = kept;
+    } else {
+      const dir = mkdtempSync(join(tmpdir(), "iw-tf-plugins-"));
+      pluginCacheDir = dir;
+      process.once("exit", () => rmSync(dir, { recursive: true, force: true }));
+    }
   }
   return {
     TF_PLUGIN_CACHE_DIR: pluginCacheDir,
@@ -78,25 +124,62 @@ function initEnv(extraEnv?: Record<string, string>): Record<string, string> {
   };
 }
 
-function ensureTerraformInit(cwd: string, extraEnv?: Record<string, string>): void {
-  if (initedDirs.has(cwd)) return;
-  // `extraEnv` carries the optional module-fetch credential so init can
-  // resolve a private cross-repo `git::` module; absent for the common case.
-  // runTf falls back to `tofu` when `terraform` isn't installed.
-  const r = runTf(["init", "-backend=false", "-input=false", "-no-color"], cwd, initEnv(extraEnv));
-  // mark done even on non-zero: a failed init won't succeed on retry within the
-  // same run, and we don't want to re-run it for every scanner call.
-  initedDirs.add(cwd);
+// roots whose last init did not complete, with what init said: validate there
+// reads only what it can without the modules and providers init would have
+// installed.
+const initFailedDirs = new Map<string, string>();
+
+/** init's own `Error:` headline and the line that explains it — "no available
+ *  releases match the given constraints >= 6.42.0, ~> 5.0" is the whole story
+ *  of a module bump the provider pin cannot satisfy. */
+function initErrorOf(r: RunResult): string {
+  const lines = r.stderr.split("\n").map((l) => l.replace(/^[│╷╵\s]+/, "").trim());
+  const at = lines.findIndex((l) => l.startsWith("Error:"));
+  if (at === -1) return `terraform init exited ${r.status}`;
+  // the explanation is the first paragraph after it, which terraform wraps
+  const rest = lines.slice(at + 1);
+  const start = rest.findIndex((l) => l !== "");
+  const end = start === -1 ? -1 : rest.indexOf("", start);
+  const detail = start === -1 ? "" : rest.slice(start, end === -1 ? undefined : end).join(" ");
+  return [lines[at], detail].filter(Boolean).join(" — ").slice(0, 400);
+}
+
+function recordInit(dir: string, fingerprint: string, r: RunResult): void {
+  // mark done even on non-zero: a failed init won't succeed on retry until the
+  // module calls or provider requirements change, and we don't want to re-run
+  // it for every scanner call.
+  initedDirs.set(dir, fingerprint);
   if (r.status !== 0 && !r.missing) {
+    initFailedDirs.set(dir, initErrorOf(r));
     log.info(`» terraform init (for validate) did not complete cleanly — validate may be shallow`);
+  } else {
+    initFailedDirs.delete(dir);
   }
 }
 
 /**
- * `ensureTerraformInit` for every root, awaited — the ONE step in a scan that
- * writes into the tree being scanned (`.terraform/modules`, `.terraform.lock.hcl`).
+ * The roots under `cwd` whose last `terraform init` failed, with init's error.
+ * Their validate is shallow — "Module not installed" is all it can say, and that
+ * is dropped as noise — so nothing that leans on validate may count them as
+ * checked.
+ */
+export function initFailures(cwd: string): { root: string; error: string }[] {
+  return resolveRoots(cwd).flatMap((r) => {
+    const error = initFailedDirs.get(r.absDir);
+    return error === undefined ? [] : [{ root: r.relDir || ".", error }];
+  });
+}
+
+/** {@link initFailures}, the roots only. */
+export function initFailedRoots(cwd: string): string[] {
+  return initFailures(cwd).map((f) => f.root);
+}
+
+/**
+ * `initRoots`, queued and awaited — the ONE step in a scan that writes into the
+ * tree being scanned (`.terraform/modules`, `.terraform.lock.hcl`).
  *
- * It is hoisted out of `scanValidate` and awaited before any scanner starts so
+ * It is awaited before any scanner starts so
  * that the parallel phase reads a tree in exactly the state the old sequential
  * order produced. Racing init against trivy/checkov would let them read a
  * half-populated module directory, and this product hashes findings into ids —
@@ -107,25 +190,42 @@ async function primeTerraformInit(
   roots: ResolvedRoot[],
   extraEnv?: Record<string, string>,
 ): Promise<void> {
+  // one init at a time across concurrent scans (a review scans its base and
+  // head together): they share the provider plugin cache, which Terraform does
+  // not make safe for concurrent writers.
+  const mine = initQueue.then(() => initRoots(roots, extraEnv));
+  initQueue = mine.catch(() => {});
+  return mine;
+}
+
+let initQueue: Promise<void> = Promise.resolve();
+
+/**
+ * Run `terraform init -backend=false` once per root so `terraform validate` has
+ * provider schemas to check against. Without init, validate only emits "missing
+ * required provider" — which VALIDATE_NOISE drops — so it was effectively inert.
+ * `-backend=false` avoids needing real backend credentials; `-input=false` keeps
+ * it non-interactive. Network-dependent and best-effort: if it fails (offline,
+ * private module, etc.) validate still runs, just shallow. `extraEnv` carries
+ * the optional module-fetch credential so a private cross-repo `git::` module
+ * resolves.
+ */
+async function initRoots(roots: ResolvedRoot[], extraEnv?: Record<string, string>): Promise<void> {
   for (const root of roots) {
-    if (initedDirs.has(root.absDir)) continue;
+    const fingerprint = initFingerprint(root.absDir);
+    if (initedDirs.get(root.absDir) === fingerprint) continue;
     const r = await runTfAsync(
       ["init", "-backend=false", "-input=false", "-no-color"],
       root.absDir,
       initEnv(extraEnv),
     );
-    initedDirs.add(root.absDir);
-    if (r.status !== 0 && !r.missing) {
-      log.info(
-        `» terraform init (for validate) did not complete cleanly — validate may be shallow`,
-      );
-    }
+    recordInit(root.absDir, fingerprint, r);
   }
 }
 
 // --- terraform fmt -------------------------------------------------------
 
-/** shape a `terraform fmt` result into an outcome; shared by both call styles. */
+/** shape a `terraform fmt` result into an outcome. */
 function fmtOutcome(r: RunResult, cwd: string): ScannerOutcome {
   if (r.missing) return skipped("terraform-fmt", "terraform (or tofu) not installed");
   // exit 0 = all formatted; exit 3 = files need formatting (lists them on stdout);
@@ -138,19 +238,16 @@ function fmtOutcome(r: RunResult, cwd: string): ScannerOutcome {
   };
 }
 
-export function scanFmt(cwd: string): ScannerOutcome {
-  // `terraform` when installed, else `tofu` — OpenTofu-only runners keep fmt
-  // coverage (identical CLI surface; the source label stays "terraform-fmt" so
-  // rule ids and content hashes never fork on the binary name).
-  return fmtOutcome(runTf(["fmt", "-check", "-recursive", "-list=true"], cwd), cwd);
-}
-
 /**
+ * `terraform` when installed, else `tofu` — OpenTofu-only runners keep fmt
+ * coverage (identical CLI surface; the source label stays "terraform-fmt" so
+ * rule ids and content hashes never fork on the binary name).
+ *
  * Safe to run alongside `terraform init`: `fmt -recursive` skips dot-directories,
  * so it never reads the `.terraform/` tree init is writing (verified against the
  * installed CLI — an unformatted file planted under `.terraform/` is not reported).
  */
-async function scanFmtAsync(cwd: string): Promise<ScannerOutcome> {
+export async function scanFmt(cwd: string): Promise<ScannerOutcome> {
   return fmtOutcome(await runTfAsync(["fmt", "-check", "-recursive", "-list=true"], cwd), cwd);
 }
 
@@ -193,35 +290,41 @@ const VALIDATE_NOISE = [
   "could not load plugin",
 ];
 
-/** run `terraform validate` in one root and return concerns re-based onto cwd. */
-function scanValidateRoot(root: ResolvedRoot, extraEnv?: Record<string, string>): ScannerOutcome {
-  ensureTerraformInit(root.absDir, extraEnv);
-  const r = runTf(["validate", "-json"], root.absDir);
-  if (r.missing) return skipped("terraform-validate", "terraform (or tofu) not installed");
-  try {
-    const concerns = parseValidateOutput(r.stdout, root.absDir).map((c) =>
-      rebaseConcern(c, root.relDir),
-    );
-    return { source: "terraform-validate", ran: true, concerns };
-  } catch {
-    // terraform ran but emitted output we couldn't parse — a real CLI-level
-    // failure (corrupted .terraform, a crash, an ancient terraform without
-    // `-json`), NOT a clean tree. Flag it as unvalidated so the tool fails
-    // closed rather than reporting this root as passing.
-    return {
-      ...skipped("terraform-validate", "could not parse `terraform validate -json` output"),
-      unvalidated: 1,
-    };
-  }
-}
-
 /**
- * Run `terraform validate` across EVERY root and aggregate. `validate` is the
- * one scanner that's per-root (fmt/tflint/trivy/checkov are recursive over the
- * whole tree), so a multi-root repo only catches subdir-root validate errors
- * when we visit each root.
+ * A local module source that resolves to no Terraform configuration, for every
+ * call the root reaches. Validate would report it only as "Module not
+ * installed", which is dropped as noise because an init that failed for an
+ * environmental reason says the same; a local source involves no environment.
  */
-/** aggregate per-root validate outcomes; shared by both call styles. */
+function missingLocalModules(root: ResolvedRoot): Concern[] {
+  return localModuleClosure(root.absDir)
+    .calls.filter((call) => !call.exists)
+    .map((call) => {
+      const file = posix.normalize(relative(root.absDir, call.file).replace(/\\/g, "/"));
+      const target = posix.normalize(
+        `${root.relDir || "."}/${relative(root.absDir, call.dir).replace(/\\/g, "/")}`,
+      );
+      return rebaseConcern(
+        buildConcern({
+          source: "terraform-validate",
+          rule: "Unreadable module directory",
+          file,
+          line: call.line,
+          severity: "high",
+          category: "correctness",
+          evidence:
+            `module "${call.name}" has source "${call.source}", which resolves to ${target} — ` +
+            "no Terraform configuration there.",
+          remediation_hint:
+            "A local module source is relative to the directory of the file that declares the " +
+            "call: from env/dev, a module at modules/s3 is `../../modules/s3`.",
+        }),
+        root.relDir,
+      );
+    });
+}
+
+/** aggregate per-root validate outcomes. */
 function validateOutcome(outcomes: ScannerOutcome[]): ScannerOutcome {
   const concerns: Concern[] = [];
   let anyRan = false;
@@ -257,16 +360,21 @@ function validateOutcome(outcomes: ScannerOutcome[]): ScannerOutcome {
  * `primeTerraformInit` has already done it for every root before the parallel
  * phase starts. Read-only from here, so the roots run concurrently.
  */
-async function scanValidateAsync(roots: ResolvedRoot[]): Promise<ScannerOutcome> {
+async function validateRoots(roots: ResolvedRoot[]): Promise<ScannerOutcome> {
   const outcomes = await mapWithConcurrency(roots, 4, async (root) => {
     const r = await runTfAsync(["validate", "-json"], root.absDir);
     if (r.missing) return skipped("terraform-validate", "terraform (or tofu) not installed");
     try {
-      const concerns = parseValidateOutput(r.stdout, root.absDir).map((c) =>
-        rebaseConcern(c, root.relDir),
-      );
+      const concerns = [
+        ...missingLocalModules(root),
+        ...parseValidateOutput(r.stdout, root.absDir).map((c) => rebaseConcern(c, root.relDir)),
+      ];
       return { source: "terraform-validate" as const, ran: true, concerns };
     } catch {
+      // terraform ran but emitted output we couldn't parse — a real CLI-level
+      // failure (corrupted .terraform, a crash, an ancient terraform without
+      // `-json`), NOT a clean tree. Flag it as unvalidated so the tool fails
+      // closed rather than reporting this root as passing.
       return {
         ...skipped("terraform-validate", "could not parse `terraform validate -json` output"),
         unvalidated: 1,
@@ -276,36 +384,19 @@ async function scanValidateAsync(roots: ResolvedRoot[]): Promise<ScannerOutcome>
   return validateOutcome(outcomes);
 }
 
-export function scanValidate(cwd: string, extraEnv?: Record<string, string>): ScannerOutcome {
+/**
+ * Run `terraform validate` across EVERY root and aggregate. `validate` is the
+ * one scanner that's per-root (fmt/tflint/trivy/checkov are recursive over the
+ * whole tree), so a multi-root repo only catches subdir-root validate errors
+ * when we visit each root. Inits first, through the same queue a scan uses.
+ */
+export async function scanValidate(
+  cwd: string,
+  extraEnv?: Record<string, string>,
+): Promise<ScannerOutcome> {
   const roots = resolveRoots(cwd);
-  const concerns: Concern[] = [];
-  let anyRan = false;
-  let sawMissing = false;
-  let unvalidated = 0;
-  for (const root of roots) {
-    const outcome = scanValidateRoot(root, extraEnv);
-    unvalidated += outcome.unvalidated ?? 0;
-    if (outcome.ran) {
-      anyRan = true;
-      concerns.push(...outcome.concerns);
-    } else if (outcome.skipped_reason?.includes("not installed")) {
-      sawMissing = true;
-    }
-  }
-  if (!anyRan) {
-    return sawMissing
-      ? skipped("terraform-validate", "terraform not installed")
-      : {
-          ...skipped("terraform-validate", "could not parse `terraform validate -json` output"),
-          unvalidated,
-        };
-  }
-  return {
-    source: "terraform-validate",
-    ran: true,
-    concerns: dedupe(concerns),
-    unvalidated,
-  };
+  await primeTerraformInit(roots, extraEnv);
+  return validateRoots(roots);
 }
 
 /** parse `terraform validate -json`; keeps real errors, drops uninitialized-dir noise. */
@@ -501,11 +592,12 @@ const RESOURCE_META_ARGUMENTS: ReadonlySet<string> = new Set([
  */
 export function parseResourceArguments(hcl: string): ResourceArguments[] {
   const out: ResourceArguments[] = [];
-  const re = /(?:^|\n)\s*resource\s+"([^"]+)"\s+"([^"]+)"\s*\{/g;
+  const re = new RegExp(RESOURCE_HEADER, "g");
   let m: RegExpExecArray | null;
   // biome-ignore lint/suspicious/noAssignInExpressions: idiomatic regex-exec iteration
   while ((m = re.exec(hcl)) !== null) {
-    const [, resourceType = "", name = ""] = m;
+    const resourceType = unquoteLabel(m[1] ?? "");
+    const name = unquoteLabel(m[2] ?? "");
     const braceStart = hcl.indexOf("{", m.index);
     if (braceStart === -1) break;
     const body = matchBraceBody(hcl, braceStart);
@@ -688,7 +780,7 @@ const tflintInitedDirs = new Set<string>();
  * repo. Best-effort and network-dependent: a failed init just leaves tflint
  * running its core rules, exactly as before.
  */
-function ensureTflintInit(cwd: string, extraEnv?: Record<string, string>): void {
+async function ensureTflintInit(cwd: string, extraEnv?: Record<string, string>): Promise<void> {
   if (tflintInitedDirs.has(cwd)) return;
   // mark first: a failed init won't succeed on retry within the same run, and
   // we don't want to re-attempt the network fetch on every scanner call.
@@ -699,7 +791,7 @@ function ensureTflintInit(cwd: string, extraEnv?: Record<string, string>): void
   // fetch needs a route, so it never runs in the namespace — which is what makes
   // a denied tflint `partial` whenever the repo ships a `.tflint.hcl`.
   const init = scannerSpawn("tflint", ["--init"], extraEnv ?? null, true);
-  const r = run(init.cmd, init.args, cwd, extraEnv);
+  const r = await runAsync(init.cmd, init.args, cwd, extraEnv);
   if (r.status !== 0 && !r.missing) {
     log.info(
       "» tflint --init did not complete cleanly — provider ruleset plugins may be unavailable",
@@ -707,7 +799,7 @@ function ensureTflintInit(cwd: string, extraEnv?: Record<string, string>): void
   }
 }
 
-/** shape a tflint result into an outcome; shared by both call styles. */
+/** shape a tflint result into an outcome. */
 /**
  * A scanner that exited non-zero with nothing on stdout produced no report — it
  * crashed, timed out or was killed. The JSON parsers read empty stdout as `{}`,
@@ -716,7 +808,7 @@ function ensureTflintInit(cwd: string, extraEnv?: Record<string, string>): void
 /** Why a scanner's report could not be read. The scanner then counts as not
  *  run, so the reason must say more than "could not parse". */
 function unparsedReason(tool: "tflint" | "trivy" | "checkov", error: unknown): string {
-  const why = (error instanceof Error ? error.message : String(error)).slice(0, 200);
+  const why = errorMessage(error).slice(0, 200);
   return `could not parse ${tool} json output: ${why}`;
 }
 
@@ -744,16 +836,7 @@ function tflintOutcome(r: RunResult, cwd: string, egress: unknown): ScannerOutco
 
 const TFLINT_SCAN_ARGS = ["--format", "json", "--recursive"];
 
-export function scanTflint(cwd: string, network?: ToolsNetworkDirective): ScannerOutcome {
-  const egress = egressEnvFor("tflint", network);
-  assertToolchainIntegrity("tflint", cwd, probeUnder("tflint", egress));
-  ensureTflintInit(cwd, egress ?? undefined);
-  const scan = scannerSpawn("tflint", TFLINT_SCAN_ARGS, egress, operatorHostsAdmitted(network));
-  const r = run(scan.cmd, scan.args, cwd, egress ?? undefined);
-  return tflintOutcome(r, cwd, egress);
-}
-
-async function scanTflintAsync(
+export async function scanTflint(
   cwd: string,
   network?: ToolsNetworkDirective,
 ): Promise<ScannerOutcome> {
@@ -765,7 +848,7 @@ async function scanTflintAsync(
   // `tflint --init` installs ruleset plugins outside the scanned tree, and is
   // awaited before the scan proper, so it neither races the other scanners nor
   // reorders within this one.
-  ensureTflintInit(cwd, egress ?? undefined);
+  await ensureTflintInit(cwd, egress ?? undefined);
   const scan = scannerSpawn("tflint", TFLINT_SCAN_ARGS, egress, operatorHostsAdmitted(network));
   const r = await runAsync(scan.cmd, scan.args, cwd, egress ?? undefined);
   return tflintOutcome(r, cwd, egress);
@@ -818,8 +901,10 @@ function trivyOutcome(r: RunResult, cwd: string, egress: unknown): ScannerOutcom
 // tfsec was archived by Aqua and folded into Trivy; `trivy config` is its
 // maintained successor with a larger ruleset (the AVD-* checks). `--quiet`
 // keeps Trivy's progress chatter off stdout so the JSON parses cleanly.
-async function scanTrivyAsync(
+async function scanTrivy(
   cwd: string,
+  layout: TreeLayout,
+  scope: readonly string[] | undefined,
   network?: ToolsNetworkDirective,
 ): Promise<ScannerOutcome> {
   // Supply-chain gate: refuse to execute a known-compromised trivy build
@@ -829,43 +914,100 @@ async function scanTrivyAsync(
   // `trivy config` pulls its misconfiguration checks bundle from the registries
   // the overlay admits, so the scan needs a route and a denied trivy stays
   // `partial`.
-  const scan = scannerSpawn("trivy", trivyArgs(cwd), egress, true);
-  const r = await runAsync(scan.cmd, scan.args, cwd, egress ?? undefined);
-  return trivyOutcome(r, cwd, egress);
+  const runTrivy = async (args: string[]) => {
+    const scan = scannerSpawn("trivy", args, egress, true);
+    return trivyOutcome(await runAsync(scan.cmd, scan.args, cwd, egress ?? undefined), cwd, egress);
+  };
+  const plan = trivyRuns(layout, scope);
+  const [whole, ...perRoot] = plan;
+  const outcome = await runTrivy(trivyArgs(whole as TrivyRun));
+  if (!outcome.ran) return outcome;
+  // one at a time: each run is a few seconds, and the runs of the base and the
+  // head of a review already overlap
+  const merged = mergeVariableRuns(outcome.concerns, perRoot, async (run) => {
+    const r = await runTrivy(trivyArgs(run));
+    if (!r.ran) {
+      log.warning(`» trivy with ${run.tfVars.join(", ")} did not run — ${r.skipped_reason}`);
+    }
+    return r.ran ? r.concerns : [];
+  });
+  return { ...outcome, concerns: await merged };
 }
 
-/** The variable files Terraform loads by itself in a root module, in its order. */
-const AUTO_TFVARS = /^(?:terraform\.tfvars|.+\.auto\.tfvars)(?:\.json)?$/;
+/** One `trivy config` run: the variable files it loads, the directories it skips. */
+interface TrivyRun {
+  tfVars: string[];
+  skipDirs: string[];
+  /** a root's run keeps only findings in that root's closure */
+  keep?: string[];
+}
 
 /**
- * `trivy config` arguments for `cwd`. trivy evaluates variables from their
- * defaults unless told otherwise, so a value set in `terraform.tfvars` — an open
- * CIDR, a public flag — is invisible to it. With ONE root module its auto-loaded
- * variable files are passed, exactly as `terraform plan` would load them. With
- * several, trivy would apply one root's values to every root, so none are.
+ * The trivy runs that cover `layout`. trivy evaluates variables from their
+ * defaults unless told otherwise, so a value set in a `.tfvars` file is
+ * invisible to a plain run, and a file passed to a whole-tree run applies to
+ * every root in it. So the whole tree is scanned once without variable files,
+ * then each root that has some once per file set, with every other root
+ * skipped (a root's own directory alone would lose its `../modules`): its
+ * auto-loaded files, then those plus each `-var-file` file in turn, as each
+ * `terraform plan` would load them. A tree with a single root loads its
+ * auto-loaded files in the whole-tree run.
  */
-export function trivyArgs(cwd: string): string[] {
-  const args = ["config", "--format", "json", "--quiet"];
-  const roots = resolveRoots(cwd);
-  const root = roots.length === 1 ? roots[0] : undefined;
-  if (root) {
-    let names: string[] = [];
-    try {
-      names = readdirSync(root.absDir).filter((n) => AUTO_TFVARS.test(n));
-    } catch {
-      // an unreadable root just has no variable files
-    }
-    // terraform.tfvars(.json) first, then *.auto.tfvars in lexical order
-    const ordered = [
-      ...names.filter((n) => n.startsWith("terraform.tfvars")).sort(),
-      ...names.filter((n) => !n.startsWith("terraform.tfvars")).sort(),
+export function trivyRuns(layout: TreeLayout, scope: readonly string[] | undefined): TrivyRun[] {
+  const inScope = (root: RootLayout) => !scope || scope.includes(root.dir);
+  const single = layout.roots.length === 1 ? layout.roots[0] : undefined;
+  const runs: TrivyRun[] = [
+    {
+      tfVars: single && inScope(single) ? single.autoVarFiles : [],
+      skipDirs: scope ? skipDirsFor(layout.tfDirs, scope) : [],
+    },
+  ];
+  for (const root of layout.roots.filter(inScope)) {
+    const sets = [
+      ...(root === single || root.autoVarFiles.length === 0 ? [] : [root.autoVarFiles]),
+      ...root.varFiles.map((f) => [...root.autoVarFiles, f]),
     ];
-    for (const n of ordered) args.push("--tf-vars", posix.join(root.relDir || ".", n));
+    for (const tfVars of sets) {
+      runs.push({ tfVars, skipDirs: skipDirsFor(layout.tfDirs, root.closure), keep: root.closure });
+    }
   }
+  return runs;
+}
+
+/** `trivy config` arguments for one run over the scan directory. */
+export function trivyArgs(run: TrivyRun): string[] {
+  // the memory cache: concurrent runs over two trees would otherwise contend
+  // for the lock on trivy's on-disk scan cache, which a config scan never reuses
+  const args = ["config", "--format", "json", "--quiet", "--cache-backend", "memory"];
+  for (const f of run.tfVars) args.push("--tf-vars", f);
+  for (const d of run.skipDirs) args.push("--skip-dirs", d);
   args.push(".");
   return args;
 }
 
+/**
+ * Add each variable-file run's findings to the plain run's: only those in the
+ * run's root closure, and only those the plain run lacks, each noting the
+ * variable files that produce it.
+ */
+async function mergeVariableRuns<R extends { tfVars: string[]; keep?: string[] }>(
+  plain: Concern[],
+  runs: readonly R[],
+  scan: (run: R) => Promise<Concern[]>,
+): Promise<Concern[]> {
+  const out = [...plain];
+  const seen = new Set(plain.map((c) => c.id));
+  for (const run of runs) {
+    for (const c of await scan(run)) {
+      const dir = posix.dirname(c.location.file);
+      if (seen.has(c.id) || !run.keep?.some((k) => (k || ".") === dir)) continue;
+      seen.add(c.id);
+      out.push({ ...c, evidence: `${c.evidence} (with the values in ${run.tfVars.join(", ")})` });
+    }
+  }
+  return out;
+}
+
 /**
  * Parse `trivy config --format json` output into concerns. Trivy nests
  * misconfigurations under `Results[].Misconfigurations[]`, keyed to the result's
@@ -879,6 +1021,7 @@ export function trivyArgs(cwd: string): string[] {
 export function parseTrivyOutput(stdout: string, cwd = ""): Concern[] {
   const parsed = parseScannerJson(TrivyOutput, stdout, "trivy");
   const concerns: Concern[] = [];
+  const inModules: ModuleFinding[] = [];
   for (const result of parsed.Results ?? []) {
     const file = toRepoRelative(result.Target, cwd);
     const language = trivyTypeToLanguage(result.Type);
@@ -886,23 +1029,52 @@ export function parseTrivyOutput(stdout: string, cwd = ""): Concern[] {
       if (m.Status === "PASS") continue;
       const rule = m.AVDID || m.ID || "issue";
       const start = m.CauseMetadata?.StartLine;
-      concerns.push(
-        buildConcern({
-          source: "trivy",
-          rule,
-          file,
-          line: typeof start === "number" && start > 0 ? start : null,
-          severity: lowerSeverity(m.Severity),
-          category: "security",
-          evidence: m.Message || m.Description || m.Title || rule,
-          code_snippet: trivyCodeSnippet(m.CauseMetadata?.Code?.Lines),
-          remediation_hint: m.Resolution || m.References?.[0] || null,
-          language,
-        }),
-      );
+      const concern = buildConcern({
+        source: "trivy",
+        rule,
+        file,
+        line: typeof start === "number" && start > 0 ? start : null,
+        severity: lowerSeverity(m.Severity),
+        category: "security",
+        evidence: m.Message || m.Description || m.Title || rule,
+        code_snippet: trivyCodeSnippet(m.CauseMetadata?.Code?.Lines),
+        remediation_hint: m.Resolution || m.References?.[0] || null,
+        language,
+      });
+      const call = isFetchedModulePath(file) ? trivyModuleCall(m.CauseMetadata, cwd) : null;
+      if (call) inModules.push({ concern, ...call });
+      else concerns.push(concern);
     }
   }
-  return concerns;
+  return [...concerns, ...relocateToCalls(inModules)];
+}
+
+/**
+ * The repository call a trivy finding inside a fetched module traces back to.
+ * Trivy lists the finding's occurrences from the resource outwards — the
+ * resource in the module, any module call inside it, then the call in the
+ * repository — so the first occurrence in repository code is the call.
+ */
+function trivyModuleCall(
+  cause: TrivyCause | undefined,
+  cwd: string,
+): Omit<ModuleFinding, "concern"> | null {
+  const occurrences = cause?.Occurrences ?? [];
+  const at = occurrences.findIndex(
+    (o) => o.Filename && !isFetchedModulePath(toRepoRelative(o.Filename, cwd)),
+  );
+  const site = occurrences[at];
+  if (!site?.Filename) return null;
+  const inner = occurrences
+    .slice(0, at)
+    .map((o) => o.Resource)
+    .filter((r): r is string => !!r)
+    .reverse();
+  const address = [cause?.Resource, ...inner].filter(Boolean).join(".");
+  return {
+    call: { file: toRepoRelative(site.Filename, cwd), line: site.Location?.StartLine ?? null },
+    address: address || site.Resource || "the module",
+  };
 }
 
 const TrivyCodeLine = type({
@@ -924,11 +1096,20 @@ const TrivyMisconfiguration = type({
   "References?": "string[]",
   "Status?": "string",
   "CauseMetadata?": {
+    "Resource?": "string",
     "StartLine?": "number",
     "EndLine?": "number",
     "Code?": { "Lines?": TrivyCodeLine.array().or("null") },
+    "Occurrences?": type({
+      "Resource?": "string",
+      "Filename?": "string",
+      "Location?": { "StartLine?": "number" },
+    })
+      .array()
+      .or("null"),
   },
 });
+type TrivyCause = NonNullable<(typeof TrivyMisconfiguration.infer)["CauseMetadata"]>;
 
 // Max source lines (and chars) we keep for a finding's snippet — enough to show
 // the offending block, bounded so a pathological scan can't bloat the report.
@@ -1003,7 +1184,7 @@ const TrivyOutput = type({ "Results?": TrivyResult.array().or("null") });
 
 // --- checkov --------------------------------------------------------------
 
-function checkovArgs(downloadExternalModules: boolean, frameworks: string[]): string[] {
+function checkovArgs(downloadDir: string | undefined, frameworks: string[]): string[] {
   // `--framework` pins checkov to EXACTLY the languages this run scopes to
   // (derived from `iac_languages` ∩ what the tree contains — see
   // checkovFrameworksFor). The default stays Terraform-only so the fix loop's
@@ -1020,13 +1201,47 @@ function checkovArgs(downloadExternalModules: boolean, frameworks: string[]): st
   // naive re-scan with it off stops looking inside the adopted module, so a pile
   // of findings would vanish without being fixed — a false ✗→✓ ("finding-
   // laundering"). Off by default keeps the normal scan fast and offline.
+  //
+  // The download goes to `downloadDir`, outside the tree. Left at checkov's
+  // default it lands in `.external_modules/` in the checkout: the whole git
+  // repository of every module, examples and all, which every later scan then
+  // reads as the repository's own code, and which dirties the tree a push
+  // refuses.
   const args = ["-d", ".", "--framework", ...frameworks, "-o", "json", "--quiet"];
-  if (downloadExternalModules) args.push("--download-external-modules", "true");
+  if (downloadDir) {
+    args.push("--download-external-modules", "true");
+    args.push("--external-modules-download-path", downloadDir);
+  }
   return args;
 }
 
+// not RegExp.escape: these patterns are handed to checkov's Python `re` as
+// --skip-path values, where JS's `\xNN`-escaped leading character is noise
+const escapeRegExp = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+/**
+ * checkov `--skip-path` values for the directories a scoped scan leaves out.
+ * checkov matches each as a regular expression against a path whose form
+ * depends on how it walked there, so a pattern is anchored at a path
+ * separator and the end; one that would also match a directory the scan
+ * keeps (`envs/prod` and `nested/envs/prod`) is not passed — the scope filter
+ * still drops its findings, the scan just reads it.
+ */
+export function checkovSkipPaths(tfDirs: readonly string[], skip: readonly string[]): string[] {
+  const read = tfDirs.filter((d) => !skip.some((s) => isWithin(d, s)));
+  return skip
+    .map((d) => ({ d, re: new RegExp(`(^|/)${escapeRegExp(d)}$`) }))
+    .filter(({ re }) => !read.some((k) => re.test(k)))
+    .flatMap(({ d }) => ["--skip-path", `(^|/)${escapeRegExp(d)}$`]);
+}
+
 /** shape a checkov result into an outcome. */
-function checkovOutcome(r: RunResult, cwd: string, egress: unknown): ScannerOutcome {
+function checkovOutcome(
+  r: RunResult,
+  cwd: string,
+  egress: unknown,
+  downloadDir: string | undefined,
+): ScannerOutcome {
   if (r.missing) return skipped("checkov", "checkov not installed");
   const crashed = noReport("checkov", r);
   if (crashed) return crashed;
@@ -1034,7 +1249,7 @@ function checkovOutcome(r: RunResult, cwd: string, egress: unknown): ScannerOutc
     return {
       source: "checkov",
       ran: true,
-      concerns: parseCheckovOutput(r.stdout, cwd),
+      concerns: parseCheckovOutput(r.stdout, cwd, downloadDir),
       ...(egress ? { egress_isolation: egressIsolationOf("checkov") } : {}),
     };
   } catch (error) {
@@ -1042,8 +1257,10 @@ function checkovOutcome(r: RunResult, cwd: string, egress: unknown): ScannerOutc
   }
 }
 
-async function scanCheckovAsync(
+async function scanCheckov(
   cwd: string,
+  layout: TreeLayout,
+  scope: readonly string[] | undefined,
   downloadExternalModules = false,
   frameworks: string[] = ["terraform", "terraform_json"],
   network?: ToolsNetworkDirective,
@@ -1054,26 +1271,71 @@ async function scanCheckovAsync(
   // the exact scanner builds that produced its findings.
   const egress = egressEnvFor("checkov", network);
   assertToolchainIntegrity("checkov", cwd, probeUnder("checkov", egress));
-  // checkov scans offline unless it is fetching external modules.
-  const scan = scannerSpawn(
-    "checkov",
-    checkovArgs(downloadExternalModules, frameworks),
-    egress,
-    downloadExternalModules || operatorHostsAdmitted(network),
-  );
-  // Python's UTF-8 mode: on a Windows host checkov otherwise decodes source
-  // files as cp1252 and dies on the first non-ASCII byte.
-  const r = await runAsync(scan.cmd, scan.args, cwd, { ...egress, PYTHONUTF8: "1" });
-  return checkovOutcome(r, cwd, egress);
+  const downloadDir = downloadExternalModules
+    ? mkdtempSync(join(tmpdir(), "iw-checkov-modules-"))
+    : undefined;
+  try {
+    return await checkovRuns(cwd, layout, scope, downloadDir, frameworks, egress, network);
+  } finally {
+    if (downloadDir) rmSync(downloadDir, { recursive: true, force: true });
+  }
+}
+
+/** The plain checkov run and one per variable file, sharing one module download. */
+async function checkovRuns(
+  cwd: string,
+  layout: TreeLayout,
+  scope: readonly string[] | undefined,
+  downloadDir: string | undefined,
+  frameworks: string[],
+  egress: Record<string, string> | null,
+  network: ToolsNetworkDirective | undefined,
+): Promise<ScannerOutcome> {
+  const runCheckov = async (args: string[], dir: string) => {
+    // checkov scans offline unless it is fetching external modules.
+    const scan = scannerSpawn(
+      "checkov",
+      args,
+      egress,
+      downloadDir !== undefined || operatorHostsAdmitted(network),
+    );
+    // Python's UTF-8 mode: on a Windows host checkov otherwise decodes source
+    // files as cp1252 and dies on the first non-ASCII byte.
+    const r = await runAsync(scan.cmd, scan.args, cwd, { ...egress, PYTHONUTF8: "1" });
+    return checkovOutcome(r, join(cwd, dir), egress, downloadDir);
+  };
+  const skip = scope ? checkovSkipPaths(layout.tfDirs, skipDirsFor(layout.tfDirs, scope)) : [];
+  const outcome = await runCheckov([...checkovArgs(downloadDir, frameworks), ...skip], "");
+  if (!outcome.ran) return outcome;
+  // checkov loads each directory's terraform.tfvars and *.auto.tfvars itself.
+  // A `-var-file` file applies to every directory it scans, so each runs over
+  // its own root — checkov follows `../modules` from there, and reports their
+  // files relative to it.
+  const runs = layout.roots
+    .filter((root) => !scope || scope.includes(root.dir))
+    .flatMap((root) => root.varFiles.map((f) => ({ root, tfVars: [f], keep: root.closure })));
+  const merged = await mergeVariableRuns(outcome.concerns, runs, async ({ root, ...run }) => {
+    const args = checkovArgs(downloadDir, frameworks);
+    args[1] = root.dir || ".";
+    const r = await runCheckov([...args, "--var-file", join(cwd, run.tfVars[0] ?? "")], root.dir);
+    if (!r.ran) {
+      log.warning(`» checkov with ${run.tfVars.join(", ")} did not run — ${r.skipped_reason}`);
+      return [];
+    }
+    return r.concerns.map((c) => rebaseConcern(c, root.dir));
+  });
+  return { ...outcome, concerns: merged };
 }
 
 /** parse `checkov -o json` output (object for one framework, array for several).
  *  Each block's `check_type` names the framework that produced it (terraform /
  *  cloudformation / kubernetes / …) — carried onto every concern as its language. */
-export function parseCheckovOutput(stdout: string, cwd = ""): Concern[] {
+export function parseCheckovOutput(stdout: string, cwd = "", downloadDir?: string): Concern[] {
+  const fetched = downloadDir ? { cwd, dir: downloadDir } : undefined;
   const parsed = parseScannerJson(CheckovOutputs, stdout, "checkov");
   const blocks = Array.isArray(parsed) ? parsed : [parsed];
   const concerns: Concern[] = [];
+  const inModules: ModuleFinding[] = [];
   for (const block of blocks) {
     const language = checkovTypeToLanguage(block.check_type);
     for (const check of block.results?.failed_checks ?? []) {
@@ -1082,23 +1344,56 @@ export function parseCheckovOutput(stdout: string, cwd = ""): Concern[] {
       // stable and a reviewer-loaded checkov concern re-verifies ✗→✓.
       const startLine = check.file_line_range?.[0];
       const rule = check.check_id ?? "issue";
-      concerns.push(
-        buildConcern({
-          source: "checkov",
-          rule,
-          file: toRepoRelative(check.file_path ?? undefined, cwd),
-          line: typeof startLine === "number" && startLine > 0 ? startLine : null,
-          severity: lowerSeverity(check.severity ?? undefined),
-          category: "security",
-          evidence: check.check_name ?? rule,
-          code_snippet: checkovCodeSnippet(check.code_block),
-          remediation_hint: check.guideline ?? null,
-          language,
-        }),
-      );
+      const file = toRepoRelative(check.file_path ?? undefined, cwd);
+      const concern = buildConcern({
+        source: "checkov",
+        rule,
+        file,
+        line: typeof startLine === "number" && startLine > 0 ? startLine : null,
+        // open-source checkov reports a severity only with a Prisma Cloud key;
+        // without one, the engine's own rating of the check (checkovSeverities.ts)
+        severity: check.severity
+          ? lowerSeverity(check.severity)
+          : (CHECKOV_SEVERITIES[rule] ?? "medium"),
+        category: "security",
+        evidence: check.check_name ?? rule,
+        code_snippet: checkovCodeSnippet(check.code_block),
+        remediation_hint: check.guideline ?? null,
+        language,
+      });
+      const call = isFetchedModulePath(file, fetched)
+        ? checkovModuleCall(check, cwd, fetched)
+        : null;
+      if (call) inModules.push({ concern, ...call });
+      else concerns.push(concern);
     }
   }
-  return concerns;
+  return [...concerns, ...relocateToCalls(inModules)];
+}
+
+/**
+ * The repository call a checkov finding inside a fetched module traces back to.
+ * `caller_file_path` names it when the finding depends on the call's inputs;
+ * otherwise the `source_module_` breadcrumb names the file, and the call is
+ * found in it by the module's name.
+ */
+function checkovModuleCall(
+  check: CheckovFailedCheck,
+  cwd: string,
+  fetched: FetchDir | undefined,
+): Omit<ModuleFinding, "concern"> | null {
+  const address = check.resource ?? "";
+  const caller = check.caller_file_path ? toRepoRelative(check.caller_file_path, cwd) : null;
+  if (caller && !isFetchedModulePath(caller, fetched)) {
+    const line = check.caller_file_line_range?.[0];
+    return { call: { file: caller, line: line && line > 0 ? line : null }, address };
+  }
+  const name = topModuleName(address);
+  const crumb = check.breadcrumbs?.source_module_?.find((b) => b.path)?.path;
+  if (!name || !crumb) return null;
+  const file = toRepoRelative(crumb, cwd);
+  if (isFetchedModulePath(file, fetched)) return null;
+  return { call: { file, line: moduleCallLine(cwd, file, name) }, address };
 }
 
 /** The offending source from a checkov finding's `code_block` — an array of
@@ -1113,6 +1408,12 @@ function checkovCodeSnippet(block: [number, string][] | null | undefined): strin
 // parse — so every optional field here also admits null.
 const CheckovFailedCheck = type({
   "check_id?": "string | null",
+  "resource?": "string | null",
+  "caller_file_path?": "string | null",
+  "caller_file_line_range?": "number[] | null",
+  "breadcrumbs?": type({
+    "source_module_?": type({ "path?": "string | null" }).array().or("null"),
+  }).or("null"),
   "check_name?": "string | null",
   "severity?": "string | null",
   "file_path?": "string | null",
@@ -1120,6 +1421,7 @@ const CheckovFailedCheck = type({
   "code_block?": type(["number", "string"]).array().or("null"),
   "guideline?": "string | null",
 });
+type CheckovFailedCheck = typeof CheckovFailedCheck.infer;
 const CheckovOutput = type({
   "check_type?": "string",
   "results?": { "failed_checks?": CheckovFailedCheck.array() },
@@ -1196,6 +1498,12 @@ export interface RunScannersOptions {
    * `"partial"` accordingly. Absent ⇒ open egress (today's behaviour) — deny is
    * opt-in. */
   toolsNetwork?: ToolsNetworkDirective | undefined;
+  /** the directories a scoped scan covers (`scopeFor`), relative to the scan
+   * directory; a finding elsewhere is dropped and roots outside are not
+   * initialised. Undefined scans the whole tree. */
+  scope?: string[] | undefined;
+  /** `-var-file` files whose root the `var_files` setting names. */
+  varFiles?: VarFileMapping[] | undefined;
 }
 
 /** run every scanner once over `cwd`. shared by `terraform_scan` and the
@@ -1206,8 +1514,16 @@ export async function runScanners(
   cwd: string,
   opts: RunScannersOptions = {},
 ): Promise<ScannerOutcome[]> {
-  const { selection, terraformEnv, downloadExternalModules, checkovFrameworks, toolsNetwork } =
-    opts;
+  const {
+    selection,
+    terraformEnv,
+    downloadExternalModules,
+    checkovFrameworks,
+    toolsNetwork,
+    scope,
+  } = opts;
+  const layout = treeLayout(cwd, opts.varFiles);
+  reportUnmatchedVarFiles(layout);
   const gate = async (
     source: Concern["source"],
     runner: () => Promise<ScannerOutcome>,
@@ -1228,29 +1544,23 @@ export async function runScanners(
   const validateOn = !selection || !validateToolId || selection.enabled(validateToolId);
   // one root walk, shared by init and validate — the sequential version resolved
   // them once inside scanValidate, and this must not become two walks.
-  const roots = validateOn ? resolveRoots(cwd) : [];
+  const roots = validateOn
+    ? resolveRoots(cwd).filter((r) => !scope || scope.includes(r.relDir))
+    : [];
   if (validateOn) await primeTerraformInit(roots, terraformEnv);
 
   // PHASE 2 — read-only scanners, concurrently. This is the win: the wall clock
-  // becomes the slowest scanner rather than the sum of all of them.
-  //
-  // checkov joins this phase ONLY when it is not downloading external modules.
-  // With `--download-external-modules true` it WRITES `.external_modules/` into
-  // the tree, which tflint and trivy are reading — today it runs last, so they
-  // never see it, and that must not change on a timing race.
-  const checkovIsWriter = downloadExternalModules === true;
+  // becomes the slowest scanner rather than the sum of all of them. checkov is
+  // read-only here even when it downloads external modules: they go to a
+  // directory outside the tree (see checkovArgs).
   const parallel: Promise<ScannerOutcome>[] = [
-    gate("terraform-fmt", () => scanFmtAsync(cwd)),
-    gate("terraform-validate", () => scanValidateAsync(roots)),
-    gate("tflint", () => scanTflintAsync(cwd, toolsNetwork)),
-    gate("trivy", () => scanTrivyAsync(cwd, toolsNetwork)),
-    ...(checkovIsWriter
-      ? []
-      : [
-          gate("checkov", () =>
-            scanCheckovAsync(cwd, downloadExternalModules, checkovFrameworks, toolsNetwork),
-          ),
-        ]),
+    gate("terraform-fmt", () => scanFmt(cwd)),
+    gate("terraform-validate", () => validateRoots(roots)),
+    gate("tflint", () => scanTflint(cwd, toolsNetwork)),
+    gate("trivy", () => scanTrivy(cwd, layout, scope, toolsNetwork)),
+    gate("checkov", () =>
+      scanCheckov(cwd, layout, scope, downloadExternalModules, checkovFrameworks, toolsNetwork),
+    ),
   ];
   // Not `Promise.all`: an integrity gate REFUSING a compromised scanner throws,
   // and with Promise.all the other rejections would surface as unhandled while
@@ -1261,22 +1571,32 @@ export async function runScanners(
   if (rejection?.status === "rejected") throw rejection.reason;
   const upstream = settled.map((s) => (s as PromiseFulfilledResult<ScannerOutcome>).value);
 
-  // PHASE 3 — the tree-writing checkov, after every reader has finished.
-  if (checkovIsWriter) {
-    upstream.push(
-      await gate("checkov", () =>
-        scanCheckovAsync(cwd, downloadExternalModules, checkovFrameworks, toolsNetwork),
-      ),
-    );
-  }
-
   // The native pack is never gated: it is our own code, carries no third-party
   // licence, and shells out to nothing (`scannerToolId` returns null for it).
   // It reads the provider schema that PHASE 1's init produced.
-  return [
+  const outcomes = [
     ...upstream,
     scanNative(cwd, { repeatedLiteralThreshold: opts.repeatedLiteralThreshold }),
   ];
+  if (!scope) return outcomes;
+  const kept = new Set(scope);
+  const inScope = (c: Concern) => {
+    const dir = posix.dirname(c.location.file);
+    return kept.has(dir === "." ? "" : dir);
+  };
+  return outcomes.map((o) => ({ ...o, concerns: o.concerns.filter(inScope) }));
+}
+
+const reportedVarFiles = new Set<string>();
+
+/** Say once per run which variable files no scan loads, and why. */
+function reportUnmatchedVarFiles(layout: TreeLayout): void {
+  for (const { file, reason } of layout.unmatched) {
+    const line = `» ${file} is not loaded by the scan: ${reason}`;
+    if (reportedVarFiles.has(line)) continue;
+    reportedVarFiles.add(line);
+    log.info(line);
+  }
 }
 
 export interface RemediationVerdict {