infraweaver 0.1.0

package/src/mcp/terraform/governance.ts

@@ -0,0 +1,231 @@
+/**
+ * Governance rules over IaC *shape* — the two Phase-3 finding classes that are
+ * about how a configuration behaves as a change-control artefact, not about
+ * whether a resource is misconfigured.
+ *
+ * Config scanners can't produce these. Checkov and Trivy answer "is this setting
+ * wrong?", which presumes a setting with a right answer. Neither of these has
+ * one:
+ *
+ * 1. **Imperative side-effects** (Terraform 1.14 `action` blocks invoked from
+ *    `lifecycle.action_trigger`). An apply now runs work — restart a VM, invoke a
+ *    Lambda — that is nowhere in the resource graph and leaves no trace in state.
+ *    That is a legitimate feature and also a change-control fact an auditor needs:
+ *    "what does an apply do?" stopped being answerable from the plan alone. So
+ *    this lands in the REVIEW-REQUIRED band. Calling it a failure would be wrong;
+ *    staying silent would let the one thing a plan can't show you go unmentioned.
+ *
+ * 2. **Input-bound destroy protection** (OpenTofu 1.12 dynamic `prevent_destroy`).
+ *    Terraform requires a literal here; OpenTofu allows an expression, which is
+ *    the documented way to protect production and not ephemeral environments.
+ *    Whether THIS resource is protected therefore depends on values supplied at
+ *    plan time. The honest verdict is UNVERIFIABLE — and the rule that matters is
+ *    the one written into the roadmap: any static rule asserting on
+ *    `prevent_destroy` must return unverifiable when the value is an unresolved
+ *    expression, never pass and never fail. This rule is that assertion, made
+ *    explicit and reported in the ADVISORY band, scoped to stateful resources so
+ *    it stays signal rather than noise.
+ *
+ * Pure: HCL text in, findings out. No filesystem, no subprocess, no schema.
+ */
+import { parseBlocks, stripTrailingComment, topLevelAssignments } from "#app/mcp/terraform/hcl";
+import {
+  BAND_SEVERITY,
+  DYNAMIC_DESTROY_PROTECTION,
+  IMPERATIVE_ACTION_TRIGGER,
+  NATIVE_SOURCE,
+} from "#app/mcp/terraform/nativeRules";
+import { buildConcern, type Concern } from "#app/mcp/terraform/types";
+
+// --- imperative side-effects (action blocks + action_trigger) ----------------
+
+export interface ActionTriggerSite {
+  /** the resource the trigger hangs off, `<type>.<name>`. */
+  resourceAddress: string;
+  /** 1-based line of the `action_trigger` block. */
+  line: number;
+  /** lifecycle events the trigger fires on, as written (`after_create`, …). */
+  events: string[];
+  /** the action references invoked, as written (`action.aws_lambda_invoke.x`). */
+  actions: string[];
+  /** true when the trigger is conditional — the side-effect may or may not run,
+   *  which is strictly harder to reason about, not easier. */
+  conditional: boolean;
+}
+
+/** Split an HCL list literal's elements. Tolerant: an unbracketed or multi-line
+ *  value yields whatever elements are recognisable, and an unrecognisable one
+ *  yields none — the finding still fires on the trigger itself. */
+function listElements(raw: string): string[] {
+  const v = stripTrailingComment(raw);
+  const inner = v.startsWith("[") ? v.slice(1, v.endsWith("]") ? -1 : undefined) : v;
+  return inner
+    .split(",")
+    .map((s) => s.trim().replace(/^"|"$/g, ""))
+    .filter(Boolean);
+}
+
+/**
+ * Every `lifecycle { action_trigger { … } }` in `hcl`, with the resource it
+ * belongs to. Walks resource → lifecycle → action_trigger explicitly rather than
+ * matching `action_trigger` anywhere, so a same-named argument elsewhere can't
+ * fabricate a governance finding.
+ */
+export function findActionTriggers(hcl: string): ActionTriggerSite[] {
+  const out: ActionTriggerSite[] = [];
+  for (const resource of parseBlocks(hcl, ["resource"])) {
+    const [type = "", name = ""] = resource.labels;
+    for (const lifecycle of parseBlocks(resource.body, ["lifecycle"])) {
+      const lifecycleBase = resource.bodyLine + lifecycle.bodyLine - 1;
+      for (const trigger of parseBlocks(lifecycle.body, ["action_trigger"])) {
+        const args = topLevelAssignments(trigger.body);
+        const get = (key: string): string | undefined => args.find((a) => a.name === key)?.value;
+        out.push({
+          resourceAddress: `${type}.${name}`,
+          line: lifecycleBase + trigger.line - 1,
+          events: listElements(get("events") ?? ""),
+          actions: listElements(get("actions") ?? ""),
+          // the docs spell it both ways across pages; accept either rather than
+          // silently mis-report a conditional trigger as unconditional.
+          conditional: get("condition") !== undefined || get("conditions") !== undefined,
+        });
+      }
+    }
+  }
+  return out;
+}
+
+/** Declared `action "<type>" "<name>" {}` blocks — the definitions the triggers
+ *  reference. Reported as inventory, never as a finding: declaring an action is
+ *  inert; only invoking one from a lifecycle event has an effect. */
+export function findActionDeclarations(hcl: string): { address: string; line: number }[] {
+  return parseBlocks(hcl, ["action"]).map((b) => ({
+    address: `action.${b.labels[0] ?? ""}.${b.labels[1] ?? ""}`,
+    line: b.line,
+  }));
+}
+
+export function actionTriggersToConcerns(sites: ActionTriggerSite[], file: string): Concern[] {
+  return sites.map((site) =>
+    buildConcern({
+      source: NATIVE_SOURCE,
+      rule: IMPERATIVE_ACTION_TRIGGER,
+      file,
+      line: site.line,
+      severity: BAND_SEVERITY["review-required"],
+      category: "correctness",
+      evidence:
+        `${site.resourceAddress}: an apply invokes ${site.actions.length || "one or more"} provider ` +
+        `action(s) on ${site.events.join(", ") || "a lifecycle event"}` +
+        (site.conditional ? ", conditionally" : "") +
+        (site.actions.length ? ` — ${site.actions.join(", ")}` : "") +
+        ". The side-effect is outside the resource graph and leaves no record in state",
+      remediation_hint:
+        "Not a defect to fix — a change to record. Confirm the invoked action is covered by your change " +
+        "approval process, that its effect is idempotent (Terraform will re-run it on the next matching " +
+        "event), and that whoever reads the plan knows the apply does more than the plan shows.",
+    }),
+  );
+}
+
+// --- input-bound destroy protection (OpenTofu dynamic prevent_destroy) -------
+
+/**
+ * Resource types whose destruction loses data rather than just capacity. Only
+ * these are worth an advisory: a dynamic `prevent_destroy` on a security group is
+ * a deployment-shape choice, on a database it is the difference between an
+ * environment teardown and an incident. Matched on TYPE SUFFIX so the list stays
+ * provider-agnostic (`aws_db_instance`, `azurerm_mssql_database`,
+ * `google_sql_database_instance` all end in a stateful noun).
+ */
+const STATEFUL_TYPE_SIGNAL =
+  /(?:^|_)(?:db|database|sql|instance|cluster|bucket|volume|disk|filesystem|file_system|table|vault|keyvault|key_vault|secret|snapshot|backup|registry|repository|share|queue|topic|stream|warehouse)$/;
+
+export function isStatefulResourceType(resourceType: string): boolean {
+  return STATEFUL_TYPE_SIGNAL.test(resourceType);
+}
+
+/** `true` / `false` — the only values standard Terraform accepts for
+ *  `prevent_destroy`. Anything else is an expression whose value we cannot know. */
+function isBooleanLiteral(value: string): boolean {
+  const v = stripTrailingComment(value);
+  return v === "true" || v === "false";
+}
+
+export interface DynamicDestroyProtectionSite {
+  resourceAddress: string;
+  resourceType: string;
+  /** 1-based line of the `prevent_destroy` assignment. */
+  line: number;
+  /** the expression as written, e.g. `var.protect`. */
+  expression: string;
+}
+
+/**
+ * Every `prevent_destroy` on a STATEFUL resource whose value is an expression
+ * rather than a literal. A literal `true` or `false` is decidable from the code
+ * and reported by nobody here; a non-stateful resource is out of scope by design.
+ */
+export function findDynamicDestroyProtection(hcl: string): DynamicDestroyProtectionSite[] {
+  const out: DynamicDestroyProtectionSite[] = [];
+  for (const resource of parseBlocks(hcl, ["resource"])) {
+    const [type = "", name = ""] = resource.labels;
+    if (!isStatefulResourceType(type)) continue;
+    for (const lifecycle of parseBlocks(resource.body, ["lifecycle"])) {
+      const lifecycleBase = resource.bodyLine + lifecycle.bodyLine - 1;
+      for (const a of topLevelAssignments(lifecycle.body)) {
+        if (a.name !== "prevent_destroy" || isBooleanLiteral(a.value)) continue;
+        out.push({
+          resourceAddress: `${type}.${name}`,
+          resourceType: type,
+          line: lifecycleBase + a.bodyLine - 1,
+          expression: stripTrailingComment(a.value),
+        });
+      }
+    }
+  }
+  return out;
+}
+
+export function dynamicDestroyProtectionToConcerns(
+  sites: DynamicDestroyProtectionSite[],
+  file: string,
+): Concern[] {
+  return sites.map((site) =>
+    buildConcern({
+      source: NATIVE_SOURCE,
+      rule: DYNAMIC_DESTROY_PROTECTION,
+      file,
+      line: site.line,
+      severity: BAND_SEVERITY.advisory,
+      category: "correctness",
+      evidence:
+        `${site.resourceAddress} is stateful and its destroy protection is bound to \`${site.expression}\` ` +
+        "— whether a destroy is blocked depends on plan-time input, so it cannot be determined from code",
+      remediation_hint:
+        "Legitimate for multi-environment stacks (protect production, not ephemeral environments) and " +
+        "reported as advisory for exactly that reason. If this resource should always be protected, a " +
+        "literal `prevent_destroy = true` makes the guarantee readable from the code; if it varies, record " +
+        "which environments resolve it to true so the protection claim is auditable.",
+    }),
+  );
+}
+
+// --- combined pack ------------------------------------------------------------
+
+export interface GovernanceScan {
+  concerns: Concern[];
+  /** action declarations found — inventory for the run summary, not findings. */
+  actionDeclarations: { address: string; line: number; file: string }[];
+}
+
+/** Both governance rules over one file's HCL. Pure. */
+export function scanGovernanceFile(hcl: string, file: string): GovernanceScan {
+  return {
+    concerns: [
+      ...actionTriggersToConcerns(findActionTriggers(hcl), file),
+      ...dynamicDestroyProtectionToConcerns(findDynamicDestroyProtection(hcl), file),
+    ],
+    actionDeclarations: findActionDeclarations(hcl).map((d) => ({ ...d, file })),
+  };
+}

package/src/mcp/terraform/hcl.ts

@@ -0,0 +1,273 @@
+/**
+ * Shared, tolerant HCL block scanning.
+ *
+ * Every native rule in this engine ([[writeOnly]], [[governance]], [[tfquery]],
+ * and the provider-schema cross-check in [[scanners]]) needs the same primitive:
+ * walk a file's `<keyword> "label" "label" { … }` blocks and read their top-level
+ * arguments, without being fooled by a `}` inside a string, a commented-out brace,
+ * or a heredoc body. Getting that wrong doesn't produce a parse error — it
+ * produces a WRONG FINDING at a wrong line, which is the failure mode this
+ * product can least afford. So there is exactly one implementation of it.
+ *
+ * Deliberately NOT a real HCL parser. We never evaluate expressions, resolve
+ * variables, or validate syntax — `terraform validate` (the customer's own
+ * binary) owns that. This reads structure only, and every consumer is written to
+ * degrade to "no finding" rather than guess when the structure is unclear.
+ *
+ * Pure: string in, structure out. No filesystem, no subprocess.
+ */
+
+/**
+ * A non-code span in HCL — a `"…"` string, a `#`/`//` line comment, or a
+ * `<<EOF` heredoc — that the brace/argument scanners must skip wholesale (an
+ * interpolation's `${…}`, a commented `}`, or a heredoc's `key = value` lines
+ * would otherwise corrupt brace depth or fabricate an argument). Returned for a
+ * span starting at `i`: `end` is the index of its LAST char (caller resumes at
+ * `end + 1`), and `endsLine` is true when the span finished at a line boundary
+ * (comment / heredoc — the next token begins a fresh statement). null when `i`
+ * isn't the start of a non-code span.
+ */
+export function skipNonCode(s: string, i: number): { end: number; endsLine: boolean } | null {
+  const ch = s[i];
+  // double-quoted string (with `\` escapes). Ends mid-line.
+  if (ch === '"') {
+    let j = i + 1;
+    while (j < s.length && s[j] !== '"') {
+      if (s[j] === "\\") j++;
+      j++;
+    }
+    return { end: j, endsLine: false };
+  }
+  // heredoc body (`<<EOF` / `<<-EOF` / `<<~EOF`) — arbitrary text.
+  if (ch === "<" && s[i + 1] === "<") {
+    const m = /^<<[-~]?([A-Za-z_][A-Za-z0-9_]*)/.exec(s.slice(i, i + 80));
+    if (m) {
+      const delim = m[1];
+      const openNl = s.indexOf("\n", i);
+      if (openNl === -1) return { end: s.length - 1, endsLine: true };
+      // the closing delimiter sits alone on its own line (optionally indented).
+      const closeRe = new RegExp(`\\n[ \\t]*${delim}[ \\t]*(?=\\n|$)`);
+      const cm = closeRe.exec(s.slice(openNl));
+      const end = cm ? openNl + cm.index + cm[0].length - 1 : s.length - 1;
+      return { end, endsLine: true };
+    }
+  }
+  // `#` or `//` line comment.
+  if (ch === "#" || (ch === "/" && s[i + 1] === "/")) {
+    const nl = s.indexOf("\n", i);
+    return { end: nl === -1 ? s.length - 1 : nl, endsLine: true };
+  }
+  return null;
+}
+
+/**
+ * Brace-match from an opening `{` at `open`; returns the inner text + end index
+ * (the matching `}`), string/comment/heredoc-aware so interpolation braces, a
+ * commented `}`, or a heredoc body don't fool it. null when the block never
+ * closes (a truncated or malformed file) — callers stop rather than guess.
+ */
+export function matchBraceBody(hcl: string, open: number): { text: string; end: number } | null {
+  if (open < 0) return null;
+  let depth = 0;
+  for (let i = open; i < hcl.length; i++) {
+    const span = skipNonCode(hcl, i);
+    if (span) {
+      i = span.end;
+      continue;
+    }
+    const ch = hcl[i];
+    if (ch === "{") depth++;
+    else if (ch === "}") {
+      depth--;
+      if (depth === 0) return { text: hcl.slice(open + 1, i), end: i };
+    }
+  }
+  return null;
+}
+
+/** 1-based line number of `index` in `hcl`. */
+export function lineOf(hcl: string, index: number): number {
+  let line = 1;
+  for (let i = 0; i < index && i < hcl.length; i++) if (hcl[i] === "\n") line++;
+  return line;
+}
+
+/** A top-level block (`resource "aws_s3_bucket" "b" { … }`) with its source span. */
+export interface HclBlock {
+  /** the block keyword — `resource`, `action`, `list`, … */
+  keyword: string;
+  /** the quoted labels after the keyword, in order. */
+  labels: string[];
+  /** the block's inner text (between the braces). */
+  body: string;
+  /** 1-based line of the block header. */
+  line: number;
+  /** 1-based line of the body's opening `{`. Body-relative lines add to this
+   *  (`absolute = bodyLine + bodyRelativeLine - 1`), so a caller never needs a
+   *  second `lineOf` scan to place an assignment. */
+  bodyLine: number;
+  /** 1-based line of the matching `}` — the block's last line. */
+  endLine: number;
+  /** index in `hcl` of the header's first char. */
+  start: number;
+  /** index in `hcl` of the body's opening `{`. */
+  bodyStart: number;
+  /** index in `hcl` of the matching `}`. */
+  end: number;
+}
+
+/**
+ * Every TOP-LEVEL block in `hcl` whose keyword is in `keywords`.
+ *
+ * Anchored to a line start so a `resource` mentioned inside a string or a nested
+ * body can't be mistaken for a declaration, and each match resumes past the
+ * block's closing brace so nested blocks of the same keyword are never
+ * double-reported. A block that doesn't close terminates the scan (see
+ * `matchBraceBody`) — an unparseable tail yields fewer findings, never wrong ones.
+ *
+ * Line numbers are counted forward as the scan advances rather than by rescanning
+ * from the start of the file for each one. Matches arrive in increasing index
+ * order, so this is exact — and it keeps a file with many blocks linear instead of
+ * quadratic, which matters on the monorepos this walks 2000 files of.
+ */
+export function parseBlocks(hcl: string, keywords: readonly string[]): HclBlock[] {
+  const out: HclBlock[] = [];
+  if (keywords.length === 0) return out;
+  const alternation = keywords.join("|");
+  const re = new RegExp(`(?:^|\\n)[ \\t]*(${alternation})((?:[ \\t]+"[^"\\n]*")*)[ \\t]*\\{`, "g");
+
+  let cursor = 0; // index up to which newlines have been counted
+  let line = 1;
+  /** the 1-based line of `index`; `index` must not go backwards. */
+  const lineAt = (index: number): number => {
+    for (; cursor < index && cursor < hcl.length; cursor++) {
+      if (hcl[cursor] === "\n") line++;
+    }
+    return line;
+  };
+
+  let m: RegExpExecArray | null;
+  // biome-ignore lint/suspicious/noAssignInExpressions: idiomatic regex-exec iteration
+  while ((m = re.exec(hcl)) !== null) {
+    const keyword = m[1] ?? "";
+    const labels = [...(m[2] ?? "").matchAll(/"([^"\n]*)"/g)].map((l) => l[1] ?? "");
+    const bodyStart = m.index + m[0].length - 1; // the `{` the header ends on
+    const body = matchBraceBody(hcl, bodyStart);
+    if (!body) break;
+    const start = m.index + (hcl[m.index] === "\n" ? 1 : 0);
+    out.push({
+      keyword,
+      labels,
+      body: body.text,
+      line: lineAt(start),
+      bodyLine: lineAt(bodyStart),
+      endLine: lineAt(body.end),
+      start,
+      bodyStart,
+      end: body.end,
+    });
+    re.lastIndex = body.end + 1;
+  }
+  return out;
+}
+
+/** One `name = <value>` assignment found at the top level of a block body. */
+export interface HclAssignment {
+  name: string;
+  /** the raw right-hand side, trimmed — an expression, not an evaluated value. */
+  value: string;
+  /** 1-based line of the assignment, RELATIVE TO THE BODY text. */
+  bodyLine: number;
+}
+
+/**
+ * Top-level `name = value` assignments in a block body, string/comment/heredoc-
+ * aware and depth-0 only (a `password` inside a nested block belongs to that
+ * block, not this one). Nested BLOCKS are ignored here — use `parseBlocks` on the
+ * body for those.
+ *
+ * The value is captured raw to the end of its line, which is right for the
+ * single-line assignments every rule here inspects (`password = var.x`,
+ * `prevent_destroy = true`). A multi-line value (a list or object literal
+ * spanning lines) is captured only as far as its first line; no rule asserts on
+ * such a value, and each is written to skip what it cannot read.
+ */
+export function topLevelAssignments(body: string): HclAssignment[] {
+  const out: HclAssignment[] = [];
+  let depth = 0;
+  let atStmtStart = true;
+  for (let i = 0; i < body.length; i++) {
+    const span = skipNonCode(body, i);
+    if (span) {
+      i = span.end;
+      atStmtStart = span.endsLine;
+      continue;
+    }
+    const ch = body[i] as string;
+    if (ch === "{" || ch === "[" || ch === "(") {
+      if (ch === "{") depth++;
+      atStmtStart = false;
+      continue;
+    }
+    if (ch === "}" || ch === "]" || ch === ")") {
+      if (ch === "}") depth--;
+      atStmtStart = false;
+      continue;
+    }
+    if (ch === "\n") {
+      atStmtStart = true;
+      continue;
+    }
+    if (ch === " " || ch === "\t" || ch === "\r") continue;
+    if (depth === 0 && atStmtStart && /[A-Za-z_]/.test(ch)) {
+      let j = i;
+      while (j < body.length && /[A-Za-z0-9_-]/.test(body[j] as string)) j++;
+      const name = body.slice(i, j);
+      let k = j;
+      while (k < body.length && (body[k] === " " || body[k] === "\t")) k++;
+      // `=` but not `==` — an equality inside a bare expression is not an assignment.
+      if (body[k] === "=" && body[k + 1] !== "=") {
+        const eol = body.indexOf("\n", k);
+        const value = body.slice(k + 1, eol === -1 ? body.length : eol).trim();
+        out.push({ name, value, bodyLine: lineOf(body, i) });
+      }
+      i = j - 1;
+      atStmtStart = false;
+      continue;
+    }
+    atStmtStart = false;
+  }
+  return out;
+}
+
+/**
+ * Strip a trailing `# …` / `// …` comment from a captured right-hand side.
+ *
+ * Deliberately handles ONLY strings and comments, not the full `skipNonCode` set:
+ * a heredoc opener (`<<EOF`) is part of the value, and treating it as a span to
+ * stop at would silently truncate the value to the empty string — which then
+ * flows into a proposed edit as `password_wo = ` and produces a broken rewrite.
+ */
+export function stripTrailingComment(value: string): string {
+  for (let i = 0; i < value.length; i++) {
+    const ch = value[i];
+    if (ch === '"') {
+      const span = skipNonCode(value, i);
+      if (span) i = span.end;
+      continue;
+    }
+    if (ch === "#" || (ch === "/" && value[i + 1] === "/")) return value.slice(0, i).trim();
+  }
+  return value.trim();
+}
+
+/** True when a right-hand side is a bare quoted string LITERAL with no
+ *  interpolation — i.e. the value is written into the config, not referenced. */
+export function isStringLiteral(value: string): boolean {
+  const v = stripTrailingComment(value);
+  if (v.length < 2 || !v.startsWith('"') || !v.endsWith('"')) return false;
+  // one span only: the closing quote must be the last character.
+  const span = skipNonCode(v, 0);
+  if (!span || span.end !== v.length - 1) return false;
+  return !/\$\{/.test(v);
+}