infraweaver 0.1.0

package/src/mcp/terraform/moduleDocs.ts

@@ -0,0 +1,303 @@
+/**
+ * Evidence-backed module documentation (`terraform_module_docs`) — the docs
+ * half of the Refactor flow. When a refactor lifts resources behind a module
+ * boundary, the same PR writes/refreshes the module's README with EVERY claim
+ * grounded in a tool result:
+ *
+ *   - the interface table is parsed from the module's real `variable`/`output`
+ *     blocks ([[modules]]); HCL `description`s are quoted verbatim or left
+ *     empty — never invented;
+ *   - the refactor-provenance section (when supplied) lists the moved
+ *     addresses and words the verdict exactly as the evidence layer does
+ *     (`equivalence-proven` / `equivalence-failed` / `proposed-unproven`) —
+ *     never "behaviour preserved" without a passing equivalence result;
+ *   - the metadata footer carries the generator, tool version and repo
+ *     `gitHead`, plus a commented placeholder for a future Infragram-rendered
+ *     diagram link (the cross-sell seam — no built-in diagram).
+ *
+ * Deterministic: identical inputs ⇒ byte-identical output (the builder is
+ * pure; clock-free). Incremental: when the footer's `git-head` is still the
+ * ancestor of HEAD with no change under the module dir (the README itself
+ * excluded — the commit that landed it always postdates its recorded head),
+ * the tool skips.
+ *
+ * Writes are additionally fenced at push time by DOCS_ALLOWED_PATHS in
+ * guardrails.ts — only `modules/x/README.md` / `docs/infraweaver/**` are
+ * pushable, and only when the `docs` input is enabled.
+ */
+import { readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { type } from "arktype";
+import { PRODUCT_NAME } from "#app/brand";
+import type { LocalToolContext } from "#app/mcp/localContext";
+import { collectModuleInterface, type ModuleInterface } from "#app/mcp/modules";
+import { resolveWithinCwd } from "#app/mcp/pathSafety";
+import { execute, tool, toolOk, toolSkip } from "#app/mcp/shared";
+import { scanSessionOf } from "#app/mcp/terraform/scanSession";
+import { log } from "#app/utils/cli";
+import { $ } from "#app/utils/shell";
+import packageJson from "#package.json" with { type: "json" };
+
+export type ModuleDocsVerdict =
+  | "equivalence-proven"
+  | "equivalence-failed"
+  | "proposed-unproven";
+
+export interface ModuleDocsRefactorInput {
+  /** every relocated address, `from → to` — from terraform_generate_moved. */
+  moves: { from: string; to: string }[];
+  /** worded exactly as the evidence layer's refactor statement. */
+  verdict: ModuleDocsVerdict;
+}
+
+export interface ModuleDocsInput {
+  /** repo-relative module dir, e.g. `modules/logging`. */
+  moduleDir: string;
+  iface: ModuleInterface;
+  /** present only for a refactor run (omits the section entirely otherwise). */
+  refactor?: ModuleDocsRefactorInput | undefined;
+  version?: string;
+  /** the repo HEAD the doc was generated at (footer metadata; drives the
+   * incremental refresh). null when git is unavailable. */
+  gitHead: string | null;
+}
+
+/** what each verdict may honestly claim — mirrored from the evidence layer's
+ * asserts/does-not-assert discipline. */
+const VERDICT_CLAIM: Record<ModuleDocsVerdict, string> = {
+  "equivalence-proven":
+    "The relocation was **proven behaviour-preserving** by `terraform_equivalence_check`: same resource set, identical arguments, every relocated address covered by a `moved {}` block, validate + fmt clean.",
+  "equivalence-failed":
+    "The equivalence proof **did NOT pass** — this change must not be treated as behaviour-preserving. See the run's reasons before relying on it.",
+  "proposed-unproven":
+    "This module adoption is **proposed — unproven**: it alters behaviour and was not verified against a plan. It asserts nothing about runtime behaviour.",
+};
+
+function escapeCell(text: string | null): string {
+  if (!text) return "";
+  return text
+    .replaceAll("|", "\\|")
+    .replaceAll(/\s*\n\s*/g, " ")
+    .trim();
+}
+
+function moduleName(moduleDir: string): string {
+  return (
+    moduleDir.replace(/\\/g, "/").replace(/\/+$/, "").split("/").pop() ??
+    moduleDir
+  );
+}
+
+/**
+ * Build the README from tool outputs only (pure — same inputs, same bytes).
+ * No prose is invented: descriptions come verbatim from the HCL or stay empty.
+ */
+export function buildModuleReadme(input: ModuleDocsInput): string {
+  const { iface, refactor } = input;
+  const name = moduleName(input.moduleDir);
+  const lines: string[] = [];
+
+  lines.push(`# \`${name}\` module`);
+  lines.push("");
+  lines.push(
+    `Evidence-backed documentation generated by ${PRODUCT_NAME} from the module's parsed interface` +
+      (refactor ? " and the refactor's recorded proof" : "") +
+      ". Descriptions are quoted verbatim from the HCL (empty when the HCL has none).",
+  );
+  lines.push("");
+
+  lines.push("## Interface");
+  lines.push("");
+  if (iface.variables.length > 0) {
+    lines.push("### Inputs");
+    lines.push("");
+    lines.push("| Name | Type | Required | Description |");
+    lines.push("| ---- | ---- | :------: | ----------- |");
+    for (const v of iface.variables) {
+      lines.push(
+        `| \`${v.name}\` | ${v.type ? `\`${escapeCell(v.type)}\`` : ""} | ${v.required ? "**yes**" : "no"} | ${escapeCell(v.description)} |`,
+      );
+    }
+    lines.push("");
+  }
+  if (iface.outputs.length > 0) {
+    lines.push("### Outputs");
+    lines.push("");
+    lines.push("| Name | Description |");
+    lines.push("| ---- | ----------- |");
+    for (const o of iface.outputs) {
+      lines.push(`| \`${o.name}\` | ${escapeCell(o.description)} |`);
+    }
+    lines.push("");
+  }
+  if (iface.variables.length === 0 && iface.outputs.length === 0) {
+    lines.push("The module declares no `variable` or `output` blocks.");
+    lines.push("");
+  }
+
+  if (refactor) {
+    lines.push("## Refactor provenance");
+    lines.push("");
+    lines.push(`Verdict: \`${refactor.verdict}\``);
+    lines.push("");
+    lines.push(VERDICT_CLAIM[refactor.verdict]);
+    lines.push("");
+    if (refactor.moves.length > 0) {
+      lines.push("Relocated addresses:");
+      lines.push("");
+      for (const m of refactor.moves) {
+        lines.push(`- \`${m.from}\` → \`${m.to}\``);
+      }
+      lines.push("");
+    }
+  }
+
+  lines.push("<!--");
+  lines.push("generated-by: infraweaver");
+  lines.push(`infraweaver-version: ${input.version ?? packageJson.version}`);
+  lines.push(`git-head: ${input.gitHead ?? "unknown"}`);
+  lines.push(
+    "diagram: placeholder — link a Infragram-rendered architecture diagram of this module here",
+  );
+  lines.push("-->");
+
+  return `${lines.join("\n")}\n`;
+}
+
+/** the `git-head` recorded in an existing generated README's footer, or null
+ * (no README / not infraweaver-generated / no head recorded). */
+export function readFooterGitHead(readme: string | null): string | null {
+  if (!readme?.includes("generated-by: infraweaver")) return null;
+  const m = readme.match(/^git-head: ([0-9a-f]{7,64})$/m);
+  return m?.[1] ?? null;
+}
+
+export const TerraformModuleDocsParams = type({
+  module_dir: type.string.describe(
+    "the module's repo-relative dir (the one the refactor created/adopted, e.g. 'modules/logging').",
+  ),
+  "moves?": type({ from: "string", to: "string" })
+    .array()
+    .describe(
+      "the relocated addresses (from terraform_generate_moved / the equivalence check) — rendered as the provenance list. Omit for a non-refactor regeneration.",
+    ),
+  "proposed_unproven?": type("boolean").describe(
+    "set true when documenting a b.4 third-party adoption shipped WITHOUT a plan, so the README records the `proposed-unproven` verdict. Ignored when an equivalence proof was recorded this run.",
+  ),
+});
+
+export function TerraformModuleDocsTool(ctx: LocalToolContext) {
+  return tool({
+    name: "terraform_module_docs",
+    description:
+      "Write/refresh an EVIDENCE-BACKED README for a module the refactor created or adopted (call only " +
+      "when the `docs` input is enabled). Do not hand-write module docs: this tool builds the README " +
+      "exclusively from tool results — an interface table parsed from the module's real " +
+      "`variable`/`output` blocks (HCL descriptions verbatim, never invented), the relocated-address " +
+      "list you pass in `moves`, and the equivalence verdict recorded this run (worded exactly as the " +
+      "evidence layer: equivalence-proven / equivalence-failed / proposed-unproven — never 'behaviour " +
+      "preserved' without a passing proof). Deterministic (same inputs ⇒ identical bytes) and " +
+      "incremental: when the existing README's footer git-head shows no change under the module dir, it " +
+      "skips instead of rewriting. Writes ONLY `<module_dir>/README.md`; pushes are fenced to " +
+      "`modules/**/README.md` + `docs/infraweaver/**/*.md` by the docs allow-list carve-out.",
+    parameters: TerraformModuleDocsParams,
+    // writes a file that lands in the PR diff — a mutating tool for subagent purposes.
+    mutates: true,
+    execute: execute(async ({ module_dir, moves, proposed_unproven }) => {
+      const cwd = ctx.payload.cwd ?? process.cwd();
+      if (ctx.payload.docs !== true) {
+        return toolSkip(
+          "docs_disabled",
+          "the `docs` input is not enabled for this run — module README writes are opt-in (set `docs: true` on the action)",
+        );
+      }
+      // SECURITY: confine the agent-supplied module dir to the workspace.
+      const absDir = resolveWithinCwd(cwd, module_dir);
+      const target = join(absDir, "README.md");
+
+      // current repo HEAD for the footer (and the next run's refresh check).
+      let gitHead: string | null = null;
+      try {
+        gitHead = $("git", ["rev-parse", "HEAD"], { cwd, log: false });
+      } catch {
+        /* no git → footer records "unknown" and refresh always regenerates */
+      }
+
+      // incremental refresh: if the committed footer head is still current for
+      // this module dir (empty diff), there is nothing to rewrite. The README
+      // itself is excluded from the pathspec — its footer records the HEAD from
+      // BEFORE it was committed, so the commit that landed it always postdates
+      // the recorded head and would otherwise defeat the skip on every run.
+      let existing: string | null = null;
+      try {
+        existing = readFileSync(target, "utf8");
+      } catch {
+        /* no README yet */
+      }
+      const priorHead = readFooterGitHead(existing);
+      if (priorHead && gitHead) {
+        try {
+          const dirSpec = module_dir.replace(/\\/g, "/").replace(/\/+$/, "");
+          const changed = $(
+            "git",
+            [
+              "diff",
+              "--name-only",
+              `${priorHead}..HEAD`,
+              "--",
+              dirSpec,
+              `:(exclude)${dirSpec}/README.md`,
+            ],
+            { cwd, log: false },
+          );
+          if (!changed.trim()) {
+            log.info(
+              `» terraform_module_docs: ${module_dir} unchanged since ${priorHead} — skipped`,
+            );
+            return toolSkip(
+              "module_unchanged",
+              `README is current: no change under ${module_dir} since the recorded git-head ${priorHead}`,
+            );
+          }
+        } catch {
+          /* unknown prior sha (rebase/shallow) → regenerate */
+        }
+      }
+
+      const iface = collectModuleInterface(cwd, module_dir);
+      // the refactor verdict comes from the RECORDED proof, never self-report:
+      // a proof recorded this run wins; the proposed_unproven flag only applies
+      // when no proof ran (the b.4 no-plan path); otherwise no refactor section.
+      const equivalence = scanSessionOf(ctx.toolState).refactorEquivalence;
+      const verdict: ModuleDocsVerdict | undefined = equivalence
+        ? equivalence.equivalent
+          ? "equivalence-proven"
+          : "equivalence-failed"
+        : proposed_unproven
+          ? "proposed-unproven"
+          : undefined;
+      const refactor =
+        verdict === undefined ? undefined : { moves: moves ?? [], verdict };
+
+      const readme = buildModuleReadme({
+        moduleDir: module_dir,
+        iface,
+        refactor,
+        gitHead,
+      });
+      writeFileSync(target, readme);
+      log.info(
+        `» terraform_module_docs: ${module_dir} — ${iface.variables.length} input(s), ${iface.outputs.length} output(s)` +
+          (verdict ? `, verdict ${verdict}` : "") +
+          ` → ${target}`,
+      );
+      return toolOk({
+        output_path: target,
+        inputs_documented: iface.variables.length,
+        outputs_documented: iface.outputs.length,
+        moves_documented: refactor?.moves.length ?? 0,
+        ...(verdict ? { verdict } : {}),
+      });
+    }),
+  });
+}

package/src/mcp/terraform/nativeRules.ts

@@ -0,0 +1,152 @@
+/**
+ * The NATIVE rule pack — the small set of findings Infraweaver produces itself,
+ * rather than normalising out of trivy / checkov / tflint.
+ *
+ * WHY A NATIVE SOURCE AT ALL. Everything else here is deliberately a
+ * normalisation layer over other people's scanners, and that is the right
+ * default: re-implementing Checkov would be worse Checkov. These three rules
+ * exist because no upstream scanner can produce them:
+ *
+ *   - `secret-persisted-to-state` needs the INSTALLED provider schema to know a
+ *     write-only (`_wo`) equivalent exists for this provider version. It is a
+ *     fact about the customer's pinned provider, not about a rule database.
+ *   - the two governance rules are about IaC *shape* (imperative side-effects,
+ *     input-bound destroy protection), which config scanners do not model at all.
+ *
+ * BANDS, AND WHY THEY ARE NOT ALL PASS/FAIL. A finding that says "this is a
+ * violation" when it is really "a human should look at this" is the fastest way
+ * to lose an assessor. Each rule declares a band, and the band — not the
+ * severity — decides what the five-status verdict may claim:
+ *
+ *   - `verified`        → `fail`. Code-verified from evidence we hold.
+ *   - `review-required` → `not-code-verifiable`. Real signal, but whether it is
+ *                         acceptable is a governance decision, not a code fact.
+ *   - `advisory`        → `not-code-verifiable`. Legitimate patterns live here;
+ *                         we surface them and explicitly decline to judge.
+ *
+ * [[verification]] reads the band, so a rule cannot quietly upgrade itself into a
+ * verdict it has no evidence for, and [[crosswalk]] can cite a control without
+ * the citation implying a pass/fail the engine never proved.
+ */
+import { TOOL_NAME } from "#app/brand";
+import type { Concern, Severity } from "#app/mcp/terraform/types";
+
+/** The `Concern.source` every native rule carries. Equal to the emitted-artifact
+ *  wordmark, so a SARIF report we produce round-trips back through
+ *  `read_findings` as native (not `reviewer`) and stays ✗→✓ verifiable. */
+export const NATIVE_SOURCE = TOOL_NAME;
+
+/** What a rule's finding is allowed to claim. See the module note. */
+export type NativeBand = "verified" | "review-required" | "advisory";
+
+export interface NativeRule {
+  /** bare rule id — the `rule_id` is `infraweaver:<id>` and the content hash uses
+   *  this bare form (see `buildConcern`). */
+  id: string;
+  title: string;
+  band: NativeBand;
+  category: Concern["category"];
+  /** the precise claim the finding makes. Copied into evidence/docs verbatim so
+   *  the report and the code can never drift apart. */
+  asserts: string;
+  /** the claim a reader might infer that this rule explicitly does NOT make. */
+  doesNotAssert: string;
+}
+
+export const SECRET_PERSISTED_TO_STATE = "secret-persisted-to-state";
+export const IMPERATIVE_ACTION_TRIGGER = "imperative-action-trigger";
+export const DYNAMIC_DESTROY_PROTECTION = "dynamic-destroy-protection";
+export const DEPRECATED_STATE_LOCKING = "deprecated-state-locking";
+
+export const NATIVE_RULES: readonly NativeRule[] = [
+  {
+    id: SECRET_PERSISTED_TO_STATE,
+    title:
+      "Secret argument persisted to state where a write-only equivalent exists",
+    band: "verified",
+    category: "security",
+    asserts:
+      "the INSTALLED provider's schema declares a write-only counterpart for this argument, and the " +
+      "configuration assigns the persisted form — so the value is written to Terraform state in plain text",
+    doesNotAssert:
+      "that the state file is exposed, or that the value is a real credential — state may be encrypted " +
+      "and the value may be a placeholder; the finding is about persistence, not about who can read it",
+  },
+  {
+    id: IMPERATIVE_ACTION_TRIGGER,
+    title:
+      "Imperative side-effect invoked from declarative IaC (action / action_trigger)",
+    band: "review-required",
+    category: "correctness",
+    asserts:
+      "this configuration invokes a provider action as a side-effect of a resource lifecycle event, so an " +
+      "apply performs work that is not described by the resource graph and is not reproducible from state",
+    doesNotAssert:
+      "that the action is wrong or unsafe — actions are a supported Terraform feature and many uses are " +
+      "legitimate; the change-control question of who approved an out-of-graph side-effect is a human one",
+  },
+  {
+    id: DYNAMIC_DESTROY_PROTECTION,
+    title:
+      "Destroy protection on a stateful resource is bound to an input variable",
+    band: "advisory",
+    category: "correctness",
+    asserts:
+      "`prevent_destroy` is set from an expression rather than a literal, so whether this resource is " +
+      "protected depends on the values supplied at plan time and cannot be determined from the code alone",
+    doesNotAssert:
+      "that protection is absent — the dynamic form is the documented OpenTofu pattern for varying " +
+      "protection across environments; this is reported as UNVERIFIABLE, never as a failure",
+  },
+  {
+    id: DEPRECATED_STATE_LOCKING,
+    title: "S3 backend relies on deprecated DynamoDB state locking",
+    band: "advisory",
+    category: "correctness",
+    asserts:
+      'this `backend "s3"` block configures DynamoDB-based locking (`dynamodb_table`) without also ' +
+      "setting `use_lockfile`, so the only thing preventing two concurrent applies from corrupting state " +
+      "is a mechanism HashiCorp has deprecated and will remove in a future release",
+    doesNotAssert:
+      "that state is currently unlocked or at risk — DynamoDB locking works today; this is a currency " +
+      "finding about a mechanism with an end date, not a security failure, and the backend block cannot " +
+      "be changed without an operator running `terraform init -migrate-state`",
+  },
+];
+
+const BY_ID: ReadonlyMap<string, NativeRule> = new Map(
+  NATIVE_RULES.map((r) => [r.id, r]),
+);
+
+/**
+ * The native rule a concern belongs to, or null when it isn't one of ours.
+ * Accepts both the namespaced `infraweaver:<id>` and the bare `<id>` form so it
+ * works on a concern before and after `buildConcern` namespaces it.
+ */
+export function nativeRuleOf(ruleId: string): NativeRule | null {
+  const prefix = `${NATIVE_SOURCE}:`;
+  const bare = ruleId.startsWith(prefix) ? ruleId.slice(prefix.length) : ruleId;
+  return BY_ID.get(bare) ?? null;
+}
+
+/** The severity floor a band implies. A rule may report HIGHER than its floor for
+ *  a worse instance (a hardcoded literal secret beats a referenced one), but a
+ *  non-`verified` band can never present as a critical/high violation — that is
+ *  the loudness a code-verified `fail` has earned and these have not. */
+export const BAND_SEVERITY: Record<NativeBand, Severity> = {
+  verified: "medium",
+  "review-required": "medium",
+  advisory: "low",
+};
+
+/** The reason text a non-`verified` band carries into the five-status verdict. */
+export function bandVerdictReason(rule: NativeRule): string | null {
+  switch (rule.band) {
+    case "verified":
+      return null;
+    case "review-required":
+      return `${rule.doesNotAssert} — reported for review, not as a violation`;
+    case "advisory":
+      return `${rule.doesNotAssert} — reported as advisory, not as a violation`;
+  }
+}

package/src/mcp/terraform/nativeScan.ts

@@ -0,0 +1,67 @@
+/**
+ * The native rule pack as a scanner — one `ScannerOutcome` alongside trivy /
+ * checkov / tflint, so everything downstream (grouping, severity gating,
+ * suppressions, SARIF, the evidence bundle, the ✗→✓ verifier) treats our own
+ * findings exactly like anyone else's, with no special-casing.
+ *
+ * It re-derives every finding from the tree on each run, which is what makes the
+ * ✗→✓ loop work: fix the code and the finding's content id is simply absent from
+ * the re-scan.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { walkTfFiles } from "#app/mcp/modules";
+import { scanGovernanceFile } from "#app/mcp/terraform/governance";
+import { NATIVE_SOURCE } from "#app/mcp/terraform/nativeRules";
+import {
+  deprecatedStateLockingToConcerns,
+  findDeprecatedStateLocking,
+} from "#app/mcp/terraform/stateLocking";
+import type { Concern, ScannerOutcome } from "#app/mcp/terraform/types";
+import { scanWriteOnlyFiles } from "#app/mcp/terraform/writeOnly";
+
+/**
+ * Read every `.tf` under `cwd` ONCE, as `[repo-relative POSIX path, contents]`.
+ * Both rule families get the same text: re-reading the tree per rule would double
+ * the I/O of every scan, on exactly the monorepos where that is felt. An
+ * unreadable file is skipped — it makes the scan smaller, never wrong.
+ */
+function readTree(cwd: string): [string, string][] {
+  const out: [string, string][] = [];
+  for (const rel of walkTfFiles(cwd)) {
+    try {
+      out.push([rel.replace(/\\/g, "/"), readFileSync(join(cwd, rel), "utf8")]);
+    } catch {
+      /* skip unreadable file */
+    }
+  }
+  return out;
+}
+
+/**
+ * Run the native pack over `cwd`.
+ *
+ * `ran` is always true: the governance rules need nothing but the source text, so
+ * the pack itself never fails to run. When the persisted-secret half could not
+ * run (no provider schema) that is reported through `partial` — a coverage gap
+ * the verification summary surfaces as INCONCLUSIVE, rather than being folded
+ * into a silent "the native pack found nothing".
+ */
+export function scanNative(cwd: string): ScannerOutcome {
+  const files = readTree(cwd);
+  const writeOnly = scanWriteOnlyFiles(cwd, files);
+  const concerns: Concern[] = [...writeOnly.concerns];
+  for (const [file, text] of files) {
+    concerns.push(...scanGovernanceFile(text, file).concerns);
+    concerns.push(...deprecatedStateLockingToConcerns(findDeprecatedStateLocking(text), file));
+  }
+
+  return {
+    source: NATIVE_SOURCE,
+    ran: true,
+    concerns,
+    ...(writeOnly.coverageGap
+      ? { partial: { check: `${NATIVE_SOURCE}:write-only`, reason: writeOnly.coverageGap } }
+      : {}),
+  };
+}