terramend 0.2.0 → 0.2.1

package/src/utils/terraformMcp.ts

@@ -16,7 +16,7 @@
  */
 
 import { spawnSync } from "node:child_process";
-import type { ResolvedPayload } from "#app/utils/payload";
+import { resolveToolSelection, type ToolSelectionFlags } from "#app/utils/toolSelection";
 
 /** pinned release of hashicorp/terraform-mcp-server. Bump deliberately. */
 export const TERRAFORM_MCP_IMAGE = "hashicorp/terraform-mcp-server:0.5.2";
@@ -66,10 +66,11 @@ function dockerAvailable(): boolean {
  * server (`available`), log the degrade-green note (`docker_missing`), or do
  * nothing (`disabled`).
  */
-export function resolveTerraformMcp(
-  payload: Pick<ResolvedPayload, "terraformMcp">,
-): TerraformMcpResolution {
-  if (!payload.terraformMcp) return { kind: "disabled" };
+export function resolveTerraformMcp(payload: ToolSelectionFlags): TerraformMcpResolution {
+  // terraform-mcp-server is licence-gated (HashiCorp, §1.5): on via the
+  // `terraform_mcp` input OR by naming "terraform_mcp" in tools_enabled; an
+  // explicit `-terraform_mcp` there turns it off.
+  if (!resolveToolSelection(payload).enabled("terraform_mcp")) return { kind: "disabled" };
   if (!dockerAvailable()) {
     return {
       kind: "docker_missing",

package/src/utils/terramendConfig.test.ts

@@ -0,0 +1,98 @@
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { loadTerramendConfig, parseTerramendConfig } from "#app/utils/terramendConfig";
+
+describe("parseTerramendConfig", () => {
+  it("reads scalar values verbatim", () => {
+    const { values, warnings } = parseTerramendConfig(
+      ["scan_scope: diff", "severity_threshold: high", "module_catalogue: ./modules/net"].join(
+        "\n",
+      ),
+    );
+    expect(values).toEqual({
+      scan_scope: "diff",
+      severity_threshold: "high",
+      module_catalogue: "./modules/net",
+    });
+    expect(warnings).toEqual([]);
+  });
+
+  it("joins list values with newlines (so the input parsers split them)", () => {
+    const { values } = parseTerramendConfig(
+      [
+        "tools_enabled:",
+        "  - trivy",
+        "  - -tflint",
+        "protected_paths:",
+        "  - prod/**",
+        "  - '**/state/**'",
+      ].join("\n"),
+    );
+    expect(values.tools_enabled).toBe("trivy\n-tflint");
+    expect(values.protected_paths).toBe("prod/**\n**/state/**");
+  });
+
+  it("warns and skips an unrecognised key", () => {
+    const { values, warnings } = parseTerramendConfig("nope: 1\ntools_enabled: trivy");
+    expect(values).toEqual({ tools_enabled: "trivy" });
+    expect(warnings).toEqual([expect.stringContaining('unrecognised key "nope"')]);
+  });
+
+  it("warns and skips a value of the wrong shape (a mapping)", () => {
+    const { values, warnings } = parseTerramendConfig("tools_enabled:\n  a: 1");
+    expect(values).toEqual({});
+    expect(warnings).toEqual([expect.stringContaining("expected a string or a list")]);
+  });
+
+  it("ignores blank list entries, dropping the key when nothing remains", () => {
+    const { values } = parseTerramendConfig("allowed_paths:\n  - ''\n  - '   '");
+    expect(values.allowed_paths).toBeUndefined();
+  });
+
+  it("treats an empty / comment-only file as a valid no-op", () => {
+    expect(parseTerramendConfig("# just a comment\n")).toEqual({ values: {}, warnings: [] });
+    expect(parseTerramendConfig("")).toEqual({ values: {}, warnings: [] });
+  });
+
+  it("warns on malformed YAML instead of throwing", () => {
+    const { values, warnings } = parseTerramendConfig("tools_enabled: [unterminated");
+    expect(values).toEqual({});
+    expect(warnings).toEqual([expect.stringContaining("not valid YAML")]);
+  });
+
+  it("warns when the document is a list, not a mapping", () => {
+    const { values, warnings } = parseTerramendConfig("- trivy\n- checkov");
+    expect(values).toEqual({});
+    expect(warnings).toEqual([expect.stringContaining("must be a YAML mapping")]);
+  });
+});
+
+describe("loadTerramendConfig", () => {
+  const dirs: string[] = [];
+  const makeDir = (files: Record<string, string>): string => {
+    const dir = mkdtempSync(join(tmpdir(), "terramend-cfg-"));
+    dirs.push(dir);
+    for (const [name, content] of Object.entries(files)) writeFileSync(join(dir, name), content);
+    return dir;
+  };
+  afterEach(() => {
+    for (const d of dirs.splice(0)) rmSync(d, { recursive: true, force: true });
+  });
+
+  it("reads a .terramend.yml from the given dir", () => {
+    const dir = makeDir({ ".terramend.yml": "tools_enabled: tflint\nscan_scope: diff" });
+    expect(loadTerramendConfig(dir)).toEqual({ tools_enabled: "tflint", scan_scope: "diff" });
+  });
+
+  it("falls back to the .yaml spelling", () => {
+    const dir = makeDir({ ".terramend.yaml": "severity_threshold: high" });
+    expect(loadTerramendConfig(dir)).toEqual({ severity_threshold: "high" });
+  });
+
+  it("returns {} when no config file is present", () => {
+    const dir = makeDir({ "main.tf": "" });
+    expect(loadTerramendConfig(dir)).toEqual({});
+  });
+});

package/src/utils/terramendConfig.ts

@@ -0,0 +1,143 @@
+/**
+ * Repo-committed `.terramend.yml` config (the §1.5 follow-up to the unified
+ * `tools_enabled` input). A thin layer that sits **under** the action inputs: an
+ * explicit workflow input always wins; the file only fills the gaps. It versions
+ * the toolchain + scoping policy *with the code* (and doubles as the auditable
+ * record of which non-permissive tools the repo owner opted into), so the
+ * workflow file can stay minimal and the policy lives next to the Terraform.
+ *
+ * Scope is deliberate — only repo-level **policy** knobs live here. Each maps
+ * 1:1 to the matching action input and flows through the SAME parser, so the file
+ * and the input validate identically. Secrets (`module_fetch_token`) and
+ * per-run/workflow knobs (`mode`, `max_prs`, `base_branch`, `allow_replace`) are
+ * intentionally NOT read from the file: a committed file is the wrong place for a
+ * credential, and the run's shape belongs to the workflow that dispatches it.
+ *
+ * Trust boundary: `.terramend.yml` is controlled by whoever can push to the repo
+ * — the same surface as the Terraform being remediated. It can only RELAX within
+ * the licence gate's structure (naming a non-permissive tool is the repo owner's
+ * licence acknowledgement, exactly as on the input) and it can never disable the
+ * required substrate. A workflow author who needs to *enforce* a policy sets the
+ * action input, which wins over the file.
+ *
+ * Degrade-green: a missing file is silent; malformed YAML, a non-mapping
+ * document, an unknown key, or a value of the wrong shape yields a warning and is
+ * ignored — never a hard failure.
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { log } from "#app/utils/cli";
+
+/** filenames checked, in order; the first that exists wins. */
+export const TERRAMEND_CONFIG_FILENAMES = [".terramend.yml", ".terramend.yaml"] as const;
+
+/** the repo-level keys `.terramend.yml` may set. Each is the snake_case name of
+ * the matching action input, so the file value can be fed straight through the
+ * input's own parser in `resolvePayload`. */
+export const TERRAMEND_CONFIG_KEYS = [
+  "tools_enabled",
+  "protected_paths",
+  "allowed_paths",
+  "scan_scope",
+  "severity_threshold",
+  "autonomy_threshold",
+  "module_catalogue",
+] as const;
+
+export type TerramendConfigKey = (typeof TERRAMEND_CONFIG_KEYS)[number];
+
+/** normalized string values (lists newline-joined), keyed by input name. */
+export type TerramendFileValues = Partial<Record<TerramendConfigKey, string>>;
+
+export interface ParsedTerramendConfig {
+  values: TerramendFileValues;
+  /** non-fatal problems (malformed value, unknown key) for the caller to log. */
+  warnings: string[];
+}
+
+const KEY_SET: ReadonlySet<string> = new Set(TERRAMEND_CONFIG_KEYS);
+
+/**
+ * Normalize a YAML value to the string shape the action-input parsers expect:
+ * a scalar → its trimmed string; a list → newline-joined (the tool-selection,
+ * glob, and module-catalogue parsers all split on newlines *or* commas). Returns
+ * null for an unusable value (a mapping, an empty/blank string, null) so the
+ * caller can warn and skip it.
+ */
+function normalizeValue(value: unknown): string | null {
+  if (value === null || value === undefined) return null;
+  if (typeof value === "string") return value.trim() || null;
+  if (typeof value === "number" || typeof value === "boolean") return String(value);
+  if (Array.isArray(value)) {
+    const items = value
+      .filter((v) => v !== null && v !== undefined && typeof v !== "object")
+      .map((v) => String(v).trim())
+      .filter(Boolean);
+    return items.length > 0 ? items.join("\n") : null;
+  }
+  return null; // a nested mapping isn't a valid value for any of these keys.
+}
+
+/**
+ * Parse raw `.terramend.yml` text into normalized string values + warnings.
+ * Pure — no I/O, no logging — so the parsing/validation is unit-testable.
+ */
+export function parseTerramendConfig(raw: string): ParsedTerramendConfig {
+  let doc: unknown;
+  try {
+    doc = parseYaml(raw);
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    return { values: {}, warnings: [`.terramend.yml is not valid YAML — ignored (${detail})`] };
+  }
+  // an empty file / only comments parses to null|undefined — a valid no-op.
+  if (doc === null || doc === undefined) return { values: {}, warnings: [] };
+  if (typeof doc !== "object" || Array.isArray(doc)) {
+    return {
+      values: {},
+      warnings: [".terramend.yml must be a YAML mapping (key: value) — ignored"],
+    };
+  }
+
+  const values: TerramendFileValues = {};
+  const warnings: string[] = [];
+  for (const [key, value] of Object.entries(doc as Record<string, unknown>)) {
+    if (!KEY_SET.has(key)) {
+      warnings.push(`.terramend.yml: ignoring unrecognised key "${key}"`);
+      continue;
+    }
+    const normalized = normalizeValue(value);
+    if (normalized === null) {
+      warnings.push(`.terramend.yml: ignoring "${key}" — expected a string or a list of strings`);
+      continue;
+    }
+    values[key as TerramendConfigKey] = normalized;
+  }
+  return { values, warnings };
+}
+
+/**
+ * Read + parse the repo's `.terramend.yml` (first of the supported filenames
+ * found under `cwd`). Returns the normalized values, logging any warnings. A
+ * missing file resolves to `{}` silently — the common, valid case.
+ */
+export function loadTerramendConfig(cwd: string | undefined): TerramendFileValues {
+  const root = cwd ?? process.cwd();
+  for (const name of TERRAMEND_CONFIG_FILENAMES) {
+    let raw: string;
+    try {
+      raw = readFileSync(join(root, name), "utf-8");
+    } catch {
+      continue; // not this filename — try the next, or fall through to {}.
+    }
+    const { values, warnings } = parseTerramendConfig(raw);
+    for (const w of warnings) log.warning(`» ${w}`);
+    if (Object.keys(values).length > 0) {
+      log.info(`» loaded ${name} (${Object.keys(values).join(", ")})`);
+    }
+    return values;
+  }
+  return {};
+}

package/src/utils/toolLicensing.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, it } from "vitest";
+import {
+  ALL_TOOL_IDS,
+  isLicenseGated,
+  isPermissive,
+  LICENSE_GATED_TOOLS,
+  TOOL_LICENSES,
+  type ToolId,
+} from "#app/utils/toolLicensing";
+
+describe("TOOL_LICENSES catalogue", () => {
+  it("classifies every tool with a self-consistent id", () => {
+    for (const id of ALL_TOOL_IDS) {
+      const t = TOOL_LICENSES[id];
+      expect(t.id).toBe(id);
+      expect(t.name).toBeTruthy();
+      expect(t.license).toBeTruthy();
+      expect(["permissive", "copyleft", "source-available"]).toContain(t.class);
+    }
+  });
+
+  it("treats only MIT/Apache/BSD-style licences as permissive", () => {
+    expect(isPermissive("permissive")).toBe(true);
+    expect(isPermissive("copyleft")).toBe(false);
+    expect(isPermissive("source-available")).toBe(false);
+  });
+});
+
+describe("isLicenseGated", () => {
+  it("gates non-permissive optional tools (tflint, terraform_mcp)", () => {
+    expect(isLicenseGated("tflint")).toBe(true);
+    expect(isLicenseGated("terraform_mcp")).toBe(true);
+  });
+
+  it("does not gate permissive tools (trivy, checkov, gitleaks)", () => {
+    expect(isLicenseGated("trivy")).toBe(false);
+    expect(isLicenseGated("checkov")).toBe(false);
+    expect(isLicenseGated("gitleaks")).toBe(false);
+  });
+
+  it("exempts the required substrate even though Terraform is BUSL", () => {
+    expect(TOOL_LICENSES.terraform.class).toBe("source-available");
+    expect(TOOL_LICENSES.terraform.required).toBe(true);
+    // required ⇒ never gated, so a Terraform fixer always has Terraform.
+    expect(isLicenseGated("terraform")).toBe(false);
+  });
+
+  it("LICENSE_GATED_TOOLS is exactly the gated set", () => {
+    const expected = ALL_TOOL_IDS.filter((id: ToolId) => isLicenseGated(id));
+    expect([...LICENSE_GATED_TOOLS].sort()).toEqual([...expected].sort());
+    // and it matches the documented gated tools.
+    expect([...LICENSE_GATED_TOOLS].sort()).toEqual(["terraform_mcp", "tflint"]);
+  });
+});

package/src/utils/toolLicensing.ts

@@ -0,0 +1,103 @@
+/**
+ * Tool-licence classification (§5 dependency posture; §1.5 "non-permissive-tool
+ * confirmation gate").
+ *
+ * Terramend ORCHESTRATES external tools — it never bundles or redistributes
+ * their binaries (§5 "be an orchestrator, not a redistributor"). This module
+ * makes the licence of every selectable tool explicit so the engine can DEFAULT
+ * to the permissively-licensed tools and treat a non-permissive one (tflint's
+ * embedded BUSL Terraform fork, HashiCorp's terraform-mcp-server) as an
+ * *informed, named opt-in* rather than something whose output is consumed
+ * silently. Pure data + pure predicates — the gate that consumes it lives in
+ * [[toolSelection]].
+ */
+
+/** every external tool the engine can be configured to run. */
+export type ToolId =
+  | "terraform"
+  | "tflint"
+  | "trivy"
+  | "checkov"
+  | "infracost"
+  | "gitleaks"
+  | "conftest"
+  | "terratest"
+  | "terraform_mcp";
+
+/**
+ * Coarse licence family the gate reasons about:
+ *   - `permissive`     — MIT / Apache-2.0 / BSD / ISC: default-enabled.
+ *   - `copyleft`       — MPL / (L)GPL / AGPL: gated (explicit opt-in).
+ *   - `source-available` — BUSL / SSPL / Elastic: gated (explicit opt-in).
+ */
+export type LicenseClass = "permissive" | "copyleft" | "source-available";
+
+export interface ToolLicense {
+  id: ToolId;
+  /** display name for logs / PR notes. */
+  name: string;
+  /** human-facing SPDX-ish identifier (shown, never parsed). */
+  license: string;
+  class: LicenseClass;
+  /**
+   * The core Terraform CLI is the SUBSTRATE the engine cannot run without and
+   * which the operator installs themselves — invoking it is never
+   * redistribution. It is licence-classified for honesty (Terraform moved to
+   * BUSL-1.1 at v1.6) but EXEMPT from the opt-in gate, so a Terraform fixer
+   * always has Terraform.
+   */
+  required?: boolean;
+}
+
+/**
+ * The single source of truth for what each tool is licensed under. Verified
+ * against the §5 "third-party dependency posture" note (June 2026). Keep in sync
+ * when a tool's licence changes (e.g. a vendor relicensing event).
+ */
+export const TOOL_LICENSES: Readonly<Record<ToolId, ToolLicense>> = {
+  terraform: {
+    id: "terraform",
+    name: "Terraform CLI",
+    license: "BUSL-1.1",
+    class: "source-available",
+    required: true,
+  },
+  // tflint is MPL-2.0, but it embeds a BUSL Terraform fork — §5 flags it as the
+  // canonical "never bundle/redistribute; invoke as an external process" case.
+  tflint: { id: "tflint", name: "TFLint", license: "MPL-2.0", class: "copyleft" },
+  trivy: { id: "trivy", name: "Trivy", license: "Apache-2.0", class: "permissive" },
+  checkov: { id: "checkov", name: "Checkov", license: "Apache-2.0", class: "permissive" },
+  infracost: { id: "infracost", name: "Infracost CLI", license: "Apache-2.0", class: "permissive" },
+  gitleaks: { id: "gitleaks", name: "gitleaks", license: "MIT", class: "permissive" },
+  conftest: { id: "conftest", name: "Conftest (OPA)", license: "Apache-2.0", class: "permissive" },
+  terratest: { id: "terratest", name: "Terratest", license: "Apache-2.0", class: "permissive" },
+  // HashiCorp's terraform-mcp-server, run as a Docker image — a redistribution-
+  // sensitive HashiCorp surface, so it is gated like tflint.
+  terraform_mcp: {
+    id: "terraform_mcp",
+    name: "terraform-mcp-server",
+    license: "MPL-2.0",
+    class: "copyleft",
+  },
+} as const;
+
+export const ALL_TOOL_IDS = Object.keys(TOOL_LICENSES) as ToolId[];
+
+/** a permissively-licensed tool can be enabled by default; anything else needs
+ * an explicit, licence-named opt-in. */
+export function isPermissive(c: LicenseClass): boolean {
+  return c === "permissive";
+}
+
+/**
+ * A tool whose output must NOT be consumed without an explicit, licence-named
+ * opt-in: non-permissive AND not the required substrate. This is the predicate
+ * the confirmation gate is built on.
+ */
+export function isLicenseGated(id: ToolId): boolean {
+  const t = TOOL_LICENSES[id];
+  return !t.required && !isPermissive(t.class);
+}
+
+/** every tool currently behind the licence gate (for docs / reporting). */
+export const LICENSE_GATED_TOOLS: ToolId[] = ALL_TOOL_IDS.filter(isLicenseGated);

package/src/utils/toolSelection.test.ts

@@ -0,0 +1,140 @@
+import { describe, expect, it } from "vitest";
+import {
+  parseToolSelection,
+  resolveToolSelection,
+  scannerToolId,
+  type ToolSelectionFlags,
+} from "#app/utils/toolSelection";
+
+describe("parseToolSelection", () => {
+  it("returns undefined for an unset / blank input", () => {
+    expect(parseToolSelection(undefined)).toBeUndefined();
+    expect(parseToolSelection("   ")).toBeUndefined();
+  });
+
+  it("reads the all / none bases", () => {
+    expect(parseToolSelection("all")?.base).toBe("all");
+    expect(parseToolSelection("none")?.base).toBe("none");
+    expect(parseToolSelection("*")?.base).toBe("all");
+  });
+
+  it("parses +/-/bare overrides, comma or newline separated", () => {
+    const d = parseToolSelection("trivy, -tflint\n+gitleaks");
+    expect(d?.explicit.get("trivy")).toBe(true);
+    expect(d?.explicit.get("tflint")).toBe(false);
+    expect(d?.explicit.get("gitleaks")).toBe(true);
+  });
+
+  it("canonicalises aliases (tf, terraform-mcp-server, opa)", () => {
+    const d = parseToolSelection("tf, terraform-mcp-server, opa");
+    expect(d?.explicit.get("terraform")).toBe(true);
+    expect(d?.explicit.get("terraform_mcp")).toBe(true);
+    expect(d?.explicit.get("conftest")).toBe(true);
+  });
+
+  it("collects unrecognised tokens instead of failing", () => {
+    const d = parseToolSelection("trivy, banana");
+    expect(d?.explicit.get("trivy")).toBe(true);
+    expect(d?.unknown).toEqual(["banana"]);
+  });
+});
+
+describe("resolveToolSelection — default (no tools_enabled)", () => {
+  const sel = resolveToolSelection({});
+
+  it("enables permissive scanners and the required substrate", () => {
+    expect(sel.enabled("terraform")).toBe(true);
+    expect(sel.enabled("trivy")).toBe(true);
+    expect(sel.enabled("checkov")).toBe(true);
+    expect(sel.enabled("infracost")).toBe(true);
+    expect(sel.enabled("conftest")).toBe(true);
+  });
+
+  it("gates non-permissive tools off with a licence-named reason", () => {
+    expect(sel.enabled("tflint")).toBe(false);
+    expect(sel.offReason("tflint")).toMatch(/licence-gated.*tflint/i);
+    expect(sel.enabled("terraform_mcp")).toBe(false);
+    expect(sel.gated).toEqual(expect.arrayContaining(["tflint", "terraform_mcp"]));
+  });
+
+  it("keeps the flag-opt-in extras off until their input is set", () => {
+    expect(sel.enabled("gitleaks")).toBe(false);
+    expect(sel.enabled("terratest")).toBe(false);
+  });
+});
+
+describe("resolveToolSelection — dedicated booleans still opt in", () => {
+  it("gitleaks: true enables it", () => {
+    expect(resolveToolSelection({ gitleaks: true }).enabled("gitleaks")).toBe(true);
+  });
+
+  it("terraform_mcp: true is the licence opt-in for the gated server", () => {
+    const sel = resolveToolSelection({ terraformMcp: true });
+    expect(sel.enabled("terraform_mcp")).toBe(true);
+    expect(sel.gated).not.toContain("terraform_mcp");
+  });
+
+  it("terratest: true enables the scaffold", () => {
+    expect(resolveToolSelection({ terratest: true }).enabled("terratest")).toBe(true);
+  });
+});
+
+describe("resolveToolSelection — tools_enabled overrides", () => {
+  const resolve = (raw: string, flags: ToolSelectionFlags = {}) =>
+    resolveToolSelection({ ...flags, toolsEnabled: parseToolSelection(raw) });
+
+  it("naming a gated tool is the explicit licence opt-in", () => {
+    expect(resolve("tflint").enabled("tflint")).toBe(true);
+  });
+
+  it("an explicit disable always wins, even over its dedicated flag", () => {
+    const sel = resolve("-gitleaks", { gitleaks: true });
+    expect(sel.enabled("gitleaks")).toBe(false);
+    expect(sel.disabled).toContain("gitleaks");
+  });
+
+  it("an explicit disable wins over the all base", () => {
+    const sel = resolve("all, -trivy");
+    expect(sel.enabled("trivy")).toBe(false);
+    expect(sel.enabled("tflint")).toBe(true); // all enables the gated tool too
+  });
+
+  it("base all accepts every tool (incl. gated + flag-opt-in)", () => {
+    const sel = resolve("all");
+    expect(sel.enabled("tflint")).toBe(true);
+    expect(sel.enabled("terraform_mcp")).toBe(true);
+    expect(sel.enabled("gitleaks")).toBe(true);
+    expect(sel.gated).toEqual([]);
+  });
+
+  it("base none enables nothing but the substrate + the explicitly/flag-added", () => {
+    const sel = resolve("none, +trivy");
+    expect(sel.enabled("terraform")).toBe(true); // required, always on
+    expect(sel.enabled("trivy")).toBe(true);
+    expect(sel.enabled("checkov")).toBe(false);
+    expect(sel.enabled("tflint")).toBe(false);
+  });
+
+  it("the required substrate cannot be disabled", () => {
+    expect(resolve("-terraform").enabled("terraform")).toBe(true);
+    expect(resolve("none").enabled("terraform")).toBe(true);
+  });
+
+  it("surfaces unknown tokens for a warning", () => {
+    expect(resolve("trivy, nope").unknownTokens).toEqual(["nope"]);
+  });
+});
+
+describe("scannerToolId", () => {
+  it("maps scanner sources to their tool id", () => {
+    expect(scannerToolId("terraform-fmt")).toBe("terraform");
+    expect(scannerToolId("terraform-validate")).toBe("terraform");
+    expect(scannerToolId("tflint")).toBe("tflint");
+    expect(scannerToolId("trivy")).toBe("trivy");
+    expect(scannerToolId("checkov")).toBe("checkov");
+  });
+
+  it("returns null for the reviewer pseudo-source the gate never governs", () => {
+    expect(scannerToolId("reviewer")).toBeNull();
+  });
+});