terramend 0.2.0

package/src/mcp/moduleExtraction.ts

@@ -0,0 +1,313 @@
+/**
+ * Modularization-as-remediation (M2, the hepcare pattern) — DETECTION.
+ *
+ * Finds clusters of raw resources that look like they should be a module call,
+ * and matches each cluster against the modules the repo already trusts: the
+ * operator's `module_catalogue` and the repo's own local ("house") modules.
+ * The agent turns a candidate into a refactor PR; `terraform_plan`'s
+ * `refactor_safe` gate (pure `moved {}` plan) is what makes that PR provably a
+ * no-op on live infrastructure.
+ *
+ * Everything here is pure parsing + set arithmetic over files already on disk —
+ * no subprocess, no network — mirroring the modules.ts design.
+ */
+
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { type } from "arktype";
+import type { LocalToolContext } from "#app/mcp/localContext";
+import {
+  collectModuleGraph,
+  collectModuleInterface,
+  isInLocalModule,
+  type ModuleCatalogueEntry,
+  type ModuleSourceKind,
+  parseModuleCatalogue,
+  walkTfFiles,
+} from "#app/mcp/modules";
+import { execute, tool, toolOk } from "#app/mcp/shared";
+import { log } from "#app/utils/cli";
+
+// --- resource parsing (pure) -------------------------------------------------
+
+export interface ParsedResource {
+  type: string;
+  name: string;
+}
+
+/** parse every `resource "<type>" "<name>" {` header in some HCL. Headers are
+ * enough here — clustering and signature matching only need type + name. */
+export function parseResourceBlocks(hcl: string): ParsedResource[] {
+  const out: ParsedResource[] = [];
+  const re = /(?:^|\n)\s*resource\s+"([^"]+)"\s+"([^"]+)"\s*\{/g;
+  let m: RegExpExecArray | null;
+  // biome-ignore lint/suspicious/noAssignInExpressions: idiomatic regex-exec iteration
+  while ((m = re.exec(hcl)) !== null) {
+    const resourceType = m[1];
+    const name = m[2];
+    if (resourceType !== undefined && name !== undefined) {
+      out.push({ type: resourceType, name });
+    }
+  }
+  return out;
+}
+
+// --- clustering (pure) ---------------------------------------------------------
+
+/** a cluster below this size isn't worth a module refactor PR. */
+const MIN_CLUSTER_SIZE = 3;
+
+export interface ExtractionCluster {
+  /** the file the resources live in (clusters never span files — one file is
+   * the unit a reviewer can hold in their head, and the unit `moved {}` blocks
+   * keep reviewable). */
+  file: string;
+  /** the shared resource-NAME prefix that bound the cluster, or null for a
+   * whole-file cluster. */
+  name_prefix: string | null;
+  resources: ParsedResource[];
+  /** distinct resource types, sorted — the cluster's signature. */
+  resource_types: string[];
+}
+
+function distinctTypes(resources: ParsedResource[]): string[] {
+  return [...new Set(resources.map((r) => r.type))].sort();
+}
+
+/** the leading token of a resource name (`web_server` → `web`, `db-main` → `db`). */
+function namePrefix(name: string): string {
+  const token = name.split(/[_-]/, 1)[0] ?? name;
+  return token.toLowerCase();
+}
+
+/**
+ * Cluster one file's resources into extraction candidates:
+ *   - groups sharing a name prefix with ≥ MIN_CLUSTER_SIZE members, else
+ *   - the whole file when it holds ≥ MIN_CLUSTER_SIZE+1 resources of ≥2 types
+ *     (a single-type pile is usually `count`/`for_each` material, not a module).
+ * Prefix clusters that would equal the whole-file cluster collapse into one.
+ */
+export function clusterResources(file: string, resources: ParsedResource[]): ExtractionCluster[] {
+  if (resources.length < MIN_CLUSTER_SIZE) return [];
+
+  const byPrefix = new Map<string, ParsedResource[]>();
+  for (const r of resources) {
+    const prefix = namePrefix(r.name);
+    const list = byPrefix.get(prefix) ?? [];
+    list.push(r);
+    byPrefix.set(prefix, list);
+  }
+  const clusters: ExtractionCluster[] = [];
+  for (const [prefix, members] of [...byPrefix.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+    if (members.length < MIN_CLUSTER_SIZE) continue;
+    clusters.push({
+      file,
+      name_prefix: members.length === resources.length ? null : prefix,
+      resources: members,
+      resource_types: distinctTypes(members),
+    });
+  }
+  // whole-file fallback: cohesive multi-type file none of whose prefixes qualified.
+  if (clusters.length === 0) {
+    const types = distinctTypes(resources);
+    if (resources.length > MIN_CLUSTER_SIZE && types.length >= 2) {
+      clusters.push({ file, name_prefix: null, resources, resource_types: types });
+    }
+  }
+  return clusters;
+}
+
+// --- candidate matching (pure) ------------------------------------------------
+
+export interface CandidateModule {
+  name: string;
+  source: string;
+  version: string | null;
+  kind: ModuleSourceKind;
+  /** how the match was made: a house module's actual resource types, or a
+   * catalogue module's name matching the cluster's service keywords. */
+  match: "resource_signature" | "name_keyword";
+  /** fraction of the cluster's resource types the candidate covers (signature
+   * matches) or whose service keyword hits the candidate's name (keyword). */
+  overlap: number;
+  /** house modules only — what the call site must wire up. */
+  required_variables?: string[];
+}
+
+/** minimum signature/keyword overlap for a candidate to be worth reporting. */
+const MIN_OVERLAP = 0.5;
+
+/** provider prefixes carry no service meaning for keyword matching. */
+const PROVIDER_PREFIXES = new Set(["aws", "azurerm", "google", "azuread", "kubernetes", "helm"]);
+
+/** service keywords of a resource type: `aws_s3_bucket` → ["s3", "bucket"]. */
+export function serviceKeywords(resourceType: string): string[] {
+  return resourceType
+    .split("_")
+    .filter((tok) => tok.length > 1 && !PROVIDER_PREFIXES.has(tok))
+    .map((tok) => tok.toLowerCase());
+}
+
+export interface HouseModuleSignature {
+  dir: string;
+  resourceTypes: string[];
+  requiredVariables: string[];
+}
+
+/** fraction of cluster types present in the module's own resource-type set. */
+function signatureOverlap(clusterTypes: string[], moduleTypes: string[]): number {
+  if (clusterTypes.length === 0) return 0;
+  const moduleSet = new Set(moduleTypes);
+  const hit = clusterTypes.filter((t) => moduleSet.has(t)).length;
+  return hit / clusterTypes.length;
+}
+
+/** fraction of cluster types with ≥1 service keyword in the candidate's name/source. */
+function keywordOverlap(clusterTypes: string[], haystack: string): number {
+  if (clusterTypes.length === 0) return 0;
+  const target = haystack.toLowerCase();
+  const hit = clusterTypes.filter((t) =>
+    serviceKeywords(t).some((kw) => target.includes(kw)),
+  ).length;
+  return hit / clusterTypes.length;
+}
+
+export function matchCluster(
+  cluster: ExtractionCluster,
+  houseModules: HouseModuleSignature[],
+  catalogue: ModuleCatalogueEntry[],
+): CandidateModule[] {
+  const out: CandidateModule[] = [];
+  for (const house of houseModules) {
+    const overlap = signatureOverlap(cluster.resource_types, house.resourceTypes);
+    if (overlap < MIN_OVERLAP) continue;
+    out.push({
+      name: house.dir.split("/").filter(Boolean).pop() ?? house.dir,
+      source: `./${house.dir}`,
+      version: null,
+      kind: "local",
+      match: "resource_signature",
+      overlap: Number(overlap.toFixed(2)),
+      required_variables: house.requiredVariables,
+    });
+  }
+  for (const entry of catalogue) {
+    // local catalogue entries are house modules — already covered by signature.
+    if (entry.kind === "local") continue;
+    const overlap = keywordOverlap(cluster.resource_types, `${entry.name} ${entry.source}`);
+    if (overlap < MIN_OVERLAP) continue;
+    out.push({
+      name: entry.name,
+      source: entry.source,
+      version: entry.version,
+      kind: entry.kind,
+      match: "name_keyword",
+      overlap: Number(overlap.toFixed(2)),
+    });
+  }
+  // strongest candidates first; signature beats keyword at equal overlap.
+  return out.sort((a, b) => {
+    if (b.overlap !== a.overlap) return b.overlap - a.overlap;
+    if (a.match !== b.match) return a.match === "resource_signature" ? -1 : 1;
+    return a.name.localeCompare(b.name);
+  });
+}
+
+// --- workspace scan (I/O composition) ------------------------------------------
+
+export interface ExtractionCandidate {
+  cluster: ExtractionCluster;
+  candidates: CandidateModule[];
+}
+
+/** non-recursive resource-type signature of a local module dir. */
+function houseModuleSignature(cwd: string, dir: string): HouseModuleSignature {
+  let text = "";
+  try {
+    for (const f of readdirSync(join(cwd, dir))) {
+      if (!f.endsWith(".tf")) continue;
+      try {
+        text += `${readFileSync(join(cwd, dir, f), "utf8")}\n`;
+      } catch {
+        /* skip unreadable file */
+      }
+    }
+  } catch {
+    /* missing dir → empty signature */
+  }
+  return {
+    dir,
+    resourceTypes: distinctTypes(parseResourceBlocks(text)),
+    requiredVariables: collectModuleInterface(cwd, dir)
+      .variables.filter((v) => v.required)
+      .map((v) => v.name),
+  };
+}
+
+const MAX_CANDIDATES = 20;
+
+export function findExtractionCandidates(
+  cwd: string,
+  rawCatalogue: string | undefined,
+): ExtractionCandidate[] {
+  const graph = collectModuleGraph(cwd);
+  const houseModules = graph.localModuleDirs.map((d) => houseModuleSignature(cwd, d.dir));
+  const catalogue = parseModuleCatalogue(rawCatalogue);
+
+  const out: ExtractionCandidate[] = [];
+  for (const file of walkTfFiles(cwd)) {
+    // resources already inside a module dir ARE the module — never re-extract.
+    if (isInLocalModule(file, graph)) continue;
+    let text: string;
+    try {
+      text = readFileSync(join(cwd, file), "utf8");
+    } catch {
+      continue;
+    }
+    for (const cluster of clusterResources(file, parseResourceBlocks(text))) {
+      out.push({ cluster, candidates: matchCluster(cluster, houseModules, catalogue) });
+      if (out.length >= MAX_CANDIDATES) return out;
+    }
+  }
+  return out;
+}
+
+// --- the tool -------------------------------------------------------------------
+
+export const ModuleExtractionCandidatesParams = type({});
+
+export function ModuleExtractionCandidatesTool(ctx: LocalToolContext) {
+  return tool({
+    name: "module_extraction_candidates",
+    description:
+      "Find clusters of RAW resources that should likely be a module call (M2 modularization-as-" +
+      "remediation). Deterministically clusters each root file's resources by shared name prefix " +
+      "(falling back to a cohesive whole file), then matches every cluster against the repo's house " +
+      "modules (by their REAL resource-type signature, with `required_variables` so you wire the actual " +
+      "interface) and the operator's `module_catalogue` (by service keyword). Files already inside a " +
+      "local module dir are never re-extracted. Refactor contract: ONE PR per cluster on branch " +
+      "`remediate/modularize-<group>`; replace the raw resources with the candidate module call; add a " +
+      "`moved {}` block per resource (old address → module address) so state is preserved; the PR may " +
+      "proceed ONLY when terraform_validate passes AND terraform_plan reports `refactor_safe: true` " +
+      "(a pure-move plan — zero add/change/destroy). A missing required variable is a PR question for " +
+      "the reviewer, never a guessed value.",
+    parameters: ModuleExtractionCandidatesParams,
+    execute: execute(async () => {
+      const cwd = ctx.payload.cwd ?? process.cwd();
+      const candidates = findExtractionCandidates(cwd, ctx.payload.moduleCatalogue);
+      const matched = candidates.filter((c) => c.candidates.length > 0);
+      log.info(
+        `» module_extraction_candidates: ${candidates.length} cluster(s), ${matched.length} with a module match`,
+      );
+      return toolOk({
+        cluster_count: candidates.length,
+        matched_count: matched.length,
+        candidates,
+        note:
+          candidates.length === 0
+            ? "no extraction-worthy resource clusters found (root files with ≥3 related raw resources)"
+            : "verify any refactor with terraform_validate + terraform_plan (refactor_safe must be true)",
+      });
+    }),
+  });
+}

package/src/mcp/moduleTests.test.ts

@@ -0,0 +1,269 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import type { LocalToolContext } from "#app/mcp/localContext";
+import {
+  analyzeModuleTests,
+  computeInterfaceDrift,
+  discoverModuleTestAssets,
+  parseExampleModuleVariables,
+  parseGoTestVariables,
+  parseNativeTestVariables,
+  TerraformModuleTestsTool,
+  topLevelAttributeNames,
+} from "#app/mcp/moduleTests";
+
+describe("topLevelAttributeNames", () => {
+  it("captures top-level attributes and ignores nested-block/object keys", () => {
+    const body = `
+      bucket_name = "b"
+      tags = {
+        Name = "x"
+        default = "y"
+      }
+      logging {
+        target_bucket = "t"
+      }
+    `;
+    // `logging { … }` is a nested block (no `=`), so it is not an attribute; the
+    // nested `Name`/`default`/`target_bucket` keys are stripped with the braces.
+    expect(topLevelAttributeNames(body)).toEqual(["bucket_name", "tags"]);
+  });
+
+  it("does not treat `==`/`>=` comparisons as assignments", () => {
+    const body = `count = var.enabled == true ? 1 : 0`;
+    expect(topLevelAttributeNames(body)).toEqual(["count"]);
+  });
+});
+
+describe("parseExampleModuleVariables", () => {
+  const hcl = `
+    module "vpc" {
+      source = "../../modules/vpc"
+      cidr   = "10.0.0.0/16"
+      name   = "ex"
+      tags   = { env = "dev" }
+    }
+    module "other" {
+      source = "../../modules/other"
+      foo    = "bar"
+    }
+  `;
+
+  it("returns the args of only the module blocks whose source matches, minus meta-args", () => {
+    const vars = parseExampleModuleVariables(hcl, (s) => s === "../../modules/vpc");
+    expect(vars.sort()).toEqual(["cidr", "name", "tags"]);
+    expect(vars).not.toContain("source");
+    expect(vars).not.toContain("foo"); // belongs to the non-matching module
+  });
+
+  it("returns [] when no module block targets the module", () => {
+    expect(parseExampleModuleVariables(hcl, () => false)).toEqual([]);
+  });
+});
+
+describe("parseNativeTestVariables", () => {
+  it("unions variables across the top-level and per-run variables blocks", () => {
+    const hcl = `
+      variables {
+        bucket_name = "b"
+      }
+      run "plan" {
+        command = plan
+        variables {
+          tags = { env = "dev" }
+        }
+        assert {
+          condition     = output.id != ""
+          error_message = "needs id"
+        }
+      }
+    `;
+    expect(parseNativeTestVariables(hcl).sort()).toEqual(["bucket_name", "tags"]);
+  });
+});
+
+describe("parseGoTestVariables", () => {
+  it("extracts the Vars map keys, including commented TODO placeholders", () => {
+    const go = `
+      opts := &terraform.Options{
+        TerraformDir: "../modules/s3",
+        Vars: map[string]interface{}{
+          "bucket_name": "b",
+          // "tags": nil, // (optional)
+        },
+      }
+    `;
+    expect(parseGoTestVariables(go).sort()).toEqual(["bucket_name", "tags"]);
+  });
+
+  it("supports the map[string]any form and returns [] when there's no Vars map", () => {
+    expect(parseGoTestVariables(`Vars: map[string]any{ "x": 1 }`)).toEqual(["x"]);
+    expect(parseGoTestVariables(`no vars here`)).toEqual([]);
+  });
+});
+
+describe("computeInterfaceDrift", () => {
+  it("flags missing required vars and unknown set vars", () => {
+    const d = computeInterfaceDrift({
+      setVariables: ["name", "old_name"],
+      requiredVariables: ["name", "new_required"],
+      variableNames: ["name", "new_required", "tags"],
+    });
+    expect(d.missing_required).toEqual(["new_required"]);
+    expect(d.unknown_set).toEqual(["old_name"]);
+  });
+
+  it("is clean when the asset matches the interface", () => {
+    const d = computeInterfaceDrift({
+      setVariables: ["name", "tags"],
+      requiredVariables: ["name"],
+      variableNames: ["name", "tags"],
+    });
+    expect(d.missing_required).toEqual([]);
+    expect(d.unknown_set).toEqual([]);
+  });
+});
+
+describe("discoverModuleTestAssets + analyzeModuleTests (fs)", () => {
+  let root: string;
+
+  beforeAll(() => {
+    root = mkdtempSync(join(tmpdir(), "tf-modtests-"));
+    // the module under test: requires `bucket_name`, optional `tags`.
+    mkdirSync(join(root, "modules", "s3"), { recursive: true });
+    writeFileSync(
+      join(root, "modules", "s3", "variables.tf"),
+      `variable "bucket_name" { type = string }
+       variable "tags" { type = map(string)
+         default = {}
+       }`,
+    );
+    // a module-local example that is STALE: it sets a removed `acl` var and
+    // omits the required `bucket_name`.
+    mkdirSync(join(root, "modules", "s3", "examples", "basic"), { recursive: true });
+    writeFileSync(
+      join(root, "modules", "s3", "examples", "basic", "main.tf"),
+      `module "s3" {
+         source = "../../"
+         acl    = "private"
+         tags   = { env = "dev" }
+       }`,
+    );
+    // a repo-root example that is CONSISTENT (sets the required var).
+    mkdirSync(join(root, "examples", "complete"), { recursive: true });
+    writeFileSync(
+      join(root, "examples", "complete", "main.tf"),
+      `module "s3" {
+         source      = "../../modules/s3"
+         bucket_name = "b"
+       }`,
+    );
+    // a repo-root example for a DIFFERENT module — must be ignored.
+    mkdirSync(join(root, "examples", "other"), { recursive: true });
+    writeFileSync(
+      join(root, "examples", "other", "main.tf"),
+      `module "vpc" { source = "../../modules/vpc"\n cidr = "10.0.0.0/16" }`,
+    );
+    // a native test in the module's tests/ dir, missing the required var.
+    mkdirSync(join(root, "modules", "s3", "tests"), { recursive: true });
+    writeFileSync(
+      join(root, "modules", "s3", "tests", "s3.tftest.hcl"),
+      `run "plan" {
+         command = plan
+         variables {
+           tags = {}
+         }
+       }`,
+    );
+  });
+
+  afterAll(() => {
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  it("discovers the module's own examples, repo-root examples, and native tests (not sibling modules')", () => {
+    const assets = discoverModuleTestAssets(root, "modules/s3");
+    const paths = assets.map((a) => a.path).sort();
+    expect(paths).toEqual([
+      "examples/complete",
+      "modules/s3/examples/basic",
+      "modules/s3/tests/s3.tftest.hcl",
+    ]);
+    // the vpc example under examples/other is not attributed to s3.
+    expect(paths).not.toContain("examples/other");
+  });
+
+  it("computes drift only for the stale assets", () => {
+    const report = analyzeModuleTests(root, "modules/s3");
+    expect(report.required_variables).toEqual(["bucket_name"]);
+    expect(report.variable_names.sort()).toEqual(["bucket_name", "tags"]);
+
+    const byPath = Object.fromEntries(report.drift.map((d) => [d.path, d]));
+    // module-local example: unknown `acl`, missing required `bucket_name`.
+    expect(byPath["modules/s3/examples/basic"]).toMatchObject({
+      missing_required: ["bucket_name"],
+      unknown_set: ["acl"],
+    });
+    // native test: missing the required `bucket_name`.
+    expect(byPath["modules/s3/tests/s3.tftest.hcl"]).toMatchObject({
+      missing_required: ["bucket_name"],
+      unknown_set: [],
+    });
+    // the consistent repo-root example does not appear in drift.
+    expect(byPath["examples/complete"]).toBeUndefined();
+  });
+
+  it("returns no assets for a module that ships none", () => {
+    mkdirSync(join(root, "modules", "bare"), { recursive: true });
+    writeFileSync(join(root, "modules", "bare", "main.tf"), `variable "x" { type = string }`);
+    expect(discoverModuleTestAssets(root, "modules/bare")).toEqual([]);
+  });
+});
+
+describe("TerraformModuleTestsTool", () => {
+  let root: string;
+
+  beforeAll(() => {
+    root = mkdtempSync(join(tmpdir(), "tf-modtests-tool-"));
+    mkdirSync(join(root, "modules", "s3", "examples", "basic"), { recursive: true });
+    writeFileSync(
+      join(root, "modules", "s3", "variables.tf"),
+      `variable "bucket_name" { type = string }`,
+    );
+    writeFileSync(
+      join(root, "modules", "s3", "examples", "basic", "main.tf"),
+      `module "s3" { source = "../../"\n acl = "private" }`,
+    );
+  });
+
+  afterAll(() => {
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  async function run(moduleDir: string): Promise<string> {
+    const ctx = { payload: { cwd: root } } as unknown as LocalToolContext;
+    const t = TerraformModuleTestsTool(ctx);
+    const exec = t.execute as (
+      p: unknown,
+      c: unknown,
+    ) => Promise<{ content: [{ type: "text"; text: string }] }>;
+    const result = await exec({ module_dir: moduleDir }, {});
+    return result.content[0].text;
+  }
+
+  it("reports drift for a stale example and the consistency note", async () => {
+    const text = await run("modules/s3");
+    expect(text).toContain("ok: true");
+    expect(text).toContain("modules/s3/examples/basic");
+    expect(text).toContain("bucket_name"); // missing required
+    expect(text).toContain("acl"); // unknown set
+    expect(text).toContain("never weaken an assertion");
+  });
+
+  it("rejects a module dir that escapes the workspace", async () => {
+    const text = await run("../../../etc");
+    expect(text).toMatch(/Error:|escapes the workspace/);
+  });
+});