infraweaver 0.1.0

package/dist/mcp/guardrails.d.ts

@@ -0,0 +1,222 @@
+import type { ToolState } from "#app/toolState";
+import type { OctokitWithPlugins } from "#app/utils/github";
+import type { ResolvedPayload } from "#app/utils/payload";
+import type { RunContextData } from "#app/utils/runContextData";
+/**
+ * The narrow context the push-time guardrails read: the payload (allow-lists,
+ * tool selection, protected paths, PR caps), the tool state (selected mode,
+ * run-start baseline, recorded plan verdicts), and tmpdir (a gitleaks report
+ * lands here). No GitHub/git tokens — these gates inspect local state + the local
+ * git tree, so both `GitToolContext` and the GitHub write context satisfy them.
+ */
+export interface GuardrailContext {
+    payload: ResolvedPayload;
+    toolState: ToolState;
+    tmpdir: string;
+}
+/**
+ * The cross-run open-PR flood guard additionally needs the GitHub client + repo
+ * coordinates to count PRs the run can't see in local state. Only
+ * {@link assertUnderOpenPrCaps} requires it; the pure push-time gates take the
+ * narrower {@link GuardrailContext}.
+ */
+export interface OpenPrCapContext extends GuardrailContext {
+    octokit: OctokitWithPlugins;
+    repo: RunContextData["repo"];
+}
+/**
+ * Terraform-write guardrails — hard, code-level limits that back the prompt
+ * rules of the modes that write Terraform and open PRs (**Remediate** and the
+ * **RefreshRemediation** sweep). They only engage for those modes, so every other
+ * mode (Build, Fix, Review, …) is completely unaffected.
+ */
+export declare const REMEDIATE_MODE = "Remediate";
+/** the stale-fix self-healing sweep re-derives + force-updates remediation
+ * PRs, so it writes Terraform and pushes exactly like Remediate and is bounded by
+ * the same guardrails. */
+export declare const REFRESH_REMEDIATION_MODE = "RefreshRemediation";
+/** the `refactor` verb relocates resources behind a module boundary and pushes
+ * Terraform like Remediate, so it is bounded by the same allow-list / secret /
+ * destroy guardrails — PLUS the equivalence hard-fail below (a refactor that
+ * can't prove behaviour-preservation must not reach a human). */
+export declare const REFACTOR_MODE = "Refactor";
+/** the dependency / deprecation / cost verbs each write Terraform and push
+ * exactly like Remediate, so they are bounded by the same allow-list / secret /
+ * destroy / PR-cap guardrails. UpdateDependencies also runs the equivalence
+ * check for config-preserving bumps and so inherits the equivalence hard-fail
+ * below; ModernizeDeprecated and CostOptimization are behaviour-altering and
+ * prove via plan, so they never record an equivalence verdict and that one gate
+ * no-ops for them. */
+export declare const UPDATE_DEPENDENCIES_MODE = "UpdateDependencies";
+export declare const MODERNIZE_DEPRECATED_MODE = "ModernizeDeprecated";
+export declare const COST_OPTIMIZATION_MODE = "CostOptimization";
+/** the combined verb: it both remediates (a ✗→✓ fix, like Remediate) and
+ * refactors (an equivalence-proven modularisation, like Refactor) on one branch,
+ * so it is bounded by EVERY guardrail of both — the allow-list / secret /
+ * destroy / PR caps AND the equivalence hard-fail (which gates the refactor half
+ * once terraform_equivalence_check runs; no-op until it does). */
+export declare const REMEDIATE_AND_REFACTOR_MODE = "RemediateAndRefactor";
+/** default paths these modes may modify/create: Terraform sources only. */
+export declare const DEFAULT_ALLOWED_PATHS: readonly ["**/*.tf", "**/*.tfvars"];
+/** extra paths the Terratest scaffold writes, allowed only when the
+ * `terratest` input is enabled (Go test files + native `*.tftest.hcl` tests fall
+ * outside the Terraform-only default). */
+export declare const TERRATEST_ALLOWED_PATHS: readonly ["**/*_test.go", "**/*.tftest.hcl", "test/**", "tests/**", "go.mod", "go.sum"];
+/** doc paths writable only when the `docs` input is enabled — the
+ * terraform_module_docs surface. Deliberately narrow: module READMEs and the
+ * infraweaver docs dir only; the repo root README and arbitrary `docs/**` stay
+ * blocked even with the input on (fail-closed, mirroring the Terratest
+ * carve-out above). */
+export declare const DOCS_ALLOWED_PATHS: readonly ["modules/**/README.md", "docs/infraweaver/**/*.md"];
+/** the cost artifact, writable only by the CostOptimization mode (§5.19). A
+ * single exact filename rather than a glob — the same fail-closed narrowness as
+ * the docs carve-out, so no other markdown becomes writable by accident. */
+export declare const COST_ALLOWED_PATHS: readonly ["cost.md"];
+/** modes whose pushes/PRs are bounded by these guardrails — exported (ordered)
+ * so the security-model doc generator renders the real list, not a copy. */
+export declare const GUARDED_MODE_NAMES: readonly ["Remediate", "RefreshRemediation", "Refactor", "RemediateAndRefactor", "UpdateDependencies", "ModernizeDeprecated", "CostOptimization"];
+/** Whether a mode NAME is one whose pushes/PRs are bounded by these guardrails.
+ *  Pure (no ctx) so read-only tools — e.g. terraform_plan, which can't see the
+ *  full push surface — can tell whether a destructive plan WOULD block a push. */
+export declare function isGuardedModeName(mode: string | undefined): boolean;
+export declare function resolveAllowedPaths(ctx: GuardrailContext): string[];
+/**
+ * Compile a glob to an anchored RegExp. Supports `**` (any path segments,
+ * including the `**\/` "zero or more leading dirs" idiom), `*` (within a
+ * segment), and `?`. Sufficient for the path allow-list patterns
+ * (`**\/*.tf`, `modules/**`, `*.tfvars`).
+ */
+export declare function globToRegex(glob: string): RegExp;
+export declare function isPathAllowed(path: string, globs: string[]): boolean;
+/**
+ * Enforce the path allow-list before a Remediate-mode push. Throws if the
+ * branch changed any file outside the allowed globs — the choke point is
+ * push_branch, the only way changes reach a PR. Fails closed: if the baseline
+ * can't be established it refuses rather than letting an unbounded change
+ * through.
+ */
+export declare function enforceRemediationPaths(ctx: GuardrailContext): void;
+/** glob patterns marking files the fixer must NEVER auto-modify (prod state,
+ * data stores, anything sensitive). The inverse of `allowed_paths`. */
+export declare function resolveProtectedPaths(ctx: GuardrailContext): string[];
+/**
+ * Block a push that touched any file matching `protected_paths`. This is the
+ * inverse of the allow-list: a changed file matching a protected glob fails the
+ * push, even though it's a `.tf`/`.tfvars` the allow-list would otherwise permit.
+ * No-op when `protected_paths` is unset or outside a guarded mode. Fails closed:
+ * if the run-start baseline can't be established it refuses, same as
+ * `enforceRemediationPaths`.
+ */
+export declare function enforceProtectedPaths(ctx: GuardrailContext): void;
+/** globs marking FETCHED (vendored) module code — a private cross-repo `git::`
+ * module (refactor b.1) or a third-party registry module (b.4) that `terraform
+ * init` resolved into the local module cache. The refactor contract is that such
+ * a module is READ-ONLY: a concern inside it is fixed at the CALL SITE via inputs,
+ * never by editing the vendored copy, and a separate-repo b.1 module must never
+ * receive a write change. This is the code-level backing for that rule. */
+export declare const VENDORED_MODULE_PATHS: readonly ["**/.terraform/modules/**", "**/.external_modules/**"];
+/**
+ * Block a push that committed an edit to FETCHED (vendored) module code. The
+ * Terraform-only allow-list (`**​/*.tf`) would otherwise PERMIT
+ * `.terraform/modules/<x>/main.tf`, so without this a refactor could silently
+ * vendor-and-edit a read-only module's source — exactly what the b.1/b.4 contract
+ * forbids ("never open a write PR against a read-only module repo; never edit
+ * vendored module code"). Engages only in a guarded mode; fails closed on a
+ * missing baseline, like {@link enforceRemediationPaths}. No-op when nothing under
+ * the module cache was committed (the normal case — it's usually gitignored).
+ */
+export declare function assertNoVendoredModuleEdits(ctx: GuardrailContext): void;
+export interface SecretHit {
+    file: string;
+    line: number;
+    rule: string;
+}
+/**
+ * Scan a unified `git diff` for inlined secrets on ADDED lines only. Tracks the
+ * current file from `+++ b/<path>` headers and the new-side line number from
+ * `@@` hunk headers, so each hit carries an accurate `file:line`. Pure — the
+ * guardrail feeds it `git diff` output. Removed/context lines are ignored (a
+ * secret already in the base isn't this run's doing).
+ */
+export declare function scanDiffForSecrets(diff: string): SecretHit[];
+/**
+ * Parse a `gitleaks detect --report-format json` report (an array of finding
+ * objects) into the shared `SecretHit` shape. Pure, so it's unit-testable
+ * without the binary. `gitleaks:` prefixes the rule so a hit's engine is
+ * obvious next to the built-in detectors. Tolerates an empty / non-array report.
+ */
+export declare function parseGitleaksReport(json: string): SecretHit[];
+/**
+ * Block a push whose diff (since run start) inlines a secret. Reuses the same
+ * run-start baseline as the path guardrail. No-op outside a guarded mode. Fails
+ * closed on a missing baseline. The diff is read with `$` (restricted env), so
+ * no secret leaks into the subprocess.
+ *
+ * The built-in detectors always run (the deterministic, fail-closed baseline).
+ * When the operator opts in via the `gitleaks` input, gitleaks ALSO runs for
+ * deeper coverage and its hits are merged — but its absence never weakens the
+ * baseline (see scanWithGitleaks).
+ */
+export declare function assertNoSecretsInDiff(ctx: GuardrailContext): void;
+/** resource addresses the operator has explicitly allowed to be destroyed/replaced. */
+export declare function resolveAllowReplace(ctx: GuardrailContext): string[];
+export declare function isReplaceAllowed(address: string, allowList: string[]): boolean;
+/** Split a plan's stateful destroy/replace set by whether the operator's
+ *  `allow_replace` list covers each address. `blocked` is what
+ *  {@link assertNoBlockedDestroy} throws on at push — surfacing it at plan time
+ *  lets a committing mode abandon BEFORE the wasted commit/push round-trip. */
+export declare function partitionStatefulDestroy<T extends {
+    address: string;
+}>(stateful: T[], allowList: string[]): {
+    blocked: T[];
+    allowed: T[];
+};
+/**
+ * Block a push that `terraform_plan` showed would DELETE or REPLACE a stateful
+ * (data-bearing) resource — RDS, S3, EBS, a SQL database, etc. A best-practice
+ * remediation should never destroy data; if the replacement is genuinely
+ * intended the operator opts in per-resource via the `allow_replace` input
+ * (an address, a glob, or `*`/`all`). No-op outside guarded modes. When no plan
+ * ran (no cloud credentials — `terraform_plan` degraded green), there is no
+ * evidence to act on and nothing is blocked: this gate engages only on what the
+ * plan actually reported, so it strengthens the run when creds are wired and is
+ * silent otherwise.
+ */
+export declare function assertNoBlockedDestroy(ctx: GuardrailContext): void;
+/**
+ * Block a push whose `refactor` did not PROVE behaviour-equivalence. Acts on the
+ * `terraform_equivalence_check` verdict recorded in tool state — most critically
+ * an UNCOVERED `moved {}` block, which would silently destroy and recreate live
+ * resources on apply (the single highest-risk refactor defect, a sin of
+ * commission far worse than a missed finding). Like the destroy-block gate, it
+ * engages only on evidence the proof tool actually produced: no equivalence check
+ * recorded → nothing to act on → no-op (so a remediation, which never runs the
+ * check, is unaffected). No-op outside a guarded mode. When the recorded verdict
+ * is `equivalent: false`, the push is refused with the proof's own reasons.
+ */
+export declare function assertRefactorEquivalence(ctx: GuardrailContext): void;
+/** maximum remediation PRs a single run may open (default 1). */
+export declare function resolveMaxPrs(ctx: GuardrailContext): number;
+/**
+ * Enforce the per-run PR cap before opening a remediation PR. Throws when the
+ * cap is already reached so the agent stops at the configured number of scoped
+ * PRs instead of fanning out.
+ */
+export declare function assertUnderPrCap(ctx: GuardrailContext): void;
+/** record that a guarded-mode PR was opened (after create_pull_request succeeds). */
+export declare function recordRemediationPrOpened(ctx: GuardrailContext): void;
+/** max simultaneously-open remediation PRs before new ones are held back
+ * (default 10; 0 disables the cap). Action-input only (see payload.ts). */
+export declare function resolvePrConcurrentLimit(ctx: GuardrailContext): number;
+/** max remediation PRs opened per rolling hour (default 0 = no hourly cap). */
+export declare function resolvePrHourlyLimit(ctx: GuardrailContext): number;
+/**
+ * Cross-run flood guard: cap how many remediation PRs may be simultaneously OPEN
+ * (`prConcurrentLimit`) and how many may be CREATED per rolling hour
+ * (`prHourlyLimit`). Unlike {@link assertUnderPrCap} — which counts only this
+ * run's PRs from in-memory tool state — this queries GitHub for PRs across runs,
+ * so a first scan on a messy repo (or a burst of push-triggered runs) can't bury
+ * the maintainer under remediation PRs. Engages only in a guarded mode; a 0 limit
+ * disables that check. Throws with an agent-actionable message, before creation.
+ */
+export declare function assertUnderOpenPrCaps(ctx: OpenPrCapContext): Promise<void>;

package/dist/mcp/issue.d.ts

@@ -0,0 +1,20 @@
+import type { GitHubWriteToolContext } from "#app/mcp/capabilityContext";
+export declare const Issue: import("arktype/internal/variants/object.ts").ObjectType<{
+    title: string;
+    body: string;
+    labels?: string[];
+    assignees?: string[];
+}, {}>;
+export declare function IssueTool(ctx: GitHubWriteToolContext): import("fastmcp").Tool<any, import("@standard-schema/spec").StandardSchemaV1<{
+    title: string;
+    body: string;
+    labels?: string[];
+    assignees?: string[];
+}, {
+    title: string;
+    body: string;
+    labels?: string[];
+    assignees?: string[];
+}>> & {
+    mutates?: boolean;
+};

package/dist/mcp/issueComments.d.ts

@@ -0,0 +1,11 @@
+import type { GitHubToolContext } from "#app/mcp/capabilityContext";
+export declare const GetIssueComments: import("arktype/internal/variants/object.ts").ObjectType<{
+    issue_number: number;
+}, {}>;
+export declare function GetIssueCommentsTool(ctx: GitHubToolContext): import("fastmcp").Tool<any, import("@standard-schema/spec").StandardSchemaV1<{
+    issue_number: number;
+}, {
+    issue_number: number;
+}>> & {
+    mutates?: boolean;
+};

package/dist/mcp/issueEvents.d.ts

@@ -0,0 +1,11 @@
+import type { GitHubToolContext } from "#app/mcp/capabilityContext";
+export declare const GetIssueEvents: import("arktype/internal/variants/object.ts").ObjectType<{
+    issue_number: number;
+}, {}>;
+export declare function GetIssueEventsTool(ctx: GitHubToolContext): import("fastmcp").Tool<any, import("@standard-schema/spec").StandardSchemaV1<{
+    issue_number: number;
+}, {
+    issue_number: number;
+}>> & {
+    mutates?: boolean;
+};

package/dist/mcp/issueInfo.d.ts

@@ -0,0 +1,11 @@
+import type { GitHubToolContext } from "#app/mcp/capabilityContext";
+export declare const IssueInfo: import("arktype/internal/variants/object.ts").ObjectType<{
+    issue_number: number;
+}, {}>;
+export declare function IssueInfoTool(ctx: GitHubToolContext): import("fastmcp").Tool<any, import("@standard-schema/spec").StandardSchemaV1<{
+    issue_number: number;
+}, {
+    issue_number: number;
+}>> & {
+    mutates?: boolean;
+};

package/dist/mcp/labels.d.ts

@@ -0,0 +1,14 @@
+import type { GitHubToolContext } from "#app/mcp/capabilityContext";
+export declare const AddLabelsParams: import("arktype/internal/variants/object.ts").ObjectType<{
+    issue_number: number;
+    labels: string[];
+}, {}>;
+export declare function AddLabelsTool(ctx: GitHubToolContext): import("fastmcp").Tool<any, import("@standard-schema/spec").StandardSchemaV1<{
+    issue_number: number;
+    labels: string[];
+}, {
+    issue_number: number;
+    labels: string[];
+}>> & {
+    mutates?: boolean;
+};

package/dist/mcp/localContext.d.ts

@@ -0,0 +1,26 @@
+import type { ToolState } from "#app/toolState";
+import type { ResolvedPayload } from "#app/utils/payload";
+/**
+ * The cwd-scoped, GitHub-free subset of `ToolContext` that the read-only
+ * Terraform tools depend on. Two providers exist:
+ *
+ *   - the GitHub Action run: the full `ToolContext` (structurally assignable —
+ *     it carries these fields plus the GitHub/auth surface), and
+ *   - `infraweaver mcp` (the local stdio MCP server): exactly this shape, built
+ *     from CLI flags — no octokit, no tokens, no event payload.
+ *
+ * Keep this interface to fields a LOCAL run can genuinely provide. A tool that
+ * needs more (octokit, push, PR state) belongs on `ToolContext`, not here.
+ */
+export interface LocalToolContext {
+    payload: Pick<ResolvedPayload, "cwd" | "scanScope" | "iacLanguages" | "severityThreshold" | "grouping" | "autonomyThreshold" | "costIncreaseBlockUsd" | "moduleCatalogue" | "allowReplace" | "toolsEnabled" | "toolsNetwork" | "gitleaks" | "terratest" | "docs" | "terraformMcp" | "moduleFetchToken" | "moduleFetchSshKey" | "registryToken" | "registryHost" | "opentofuMcp" | "fixMemory">;
+    toolState: ToolState;
+    tmpdir: string;
+    /** resolved upstream model specifier driving this run's agent (e.g.
+     * "anthropic/claude-opus-4-8"). The Action's full `ToolContext` carries it
+     * (structurally assignable); a local `infraweaver mcp` session has no agent of
+     * its own, so it is absent there. Read by `terraform_emit_evidence` for the
+     * bundle's PROVENANCE block (A.3) — recording WHO produced the evidence, not
+     * just what was found. */
+    resolvedModel?: string | undefined;
+}

package/dist/mcp/moduleExtraction.d.ts

@@ -0,0 +1,79 @@
+/**
+ * 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 type { LocalToolContext } from "#app/mcp/localContext";
+import { type ModuleCatalogueEntry, type ModuleSourceKind } from "#app/mcp/modules";
+import { type MovedBlock } from "#app/mcp/terraform/refactor";
+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 declare function parseResourceBlocks(hcl: string): ParsedResource[];
+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[];
+}
+/**
+ * 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 declare function clusterResources(file: string, resources: ParsedResource[]): ExtractionCluster[];
+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[];
+    /** the EXHAUSTIVE `moved {}` mapping for adopting THIS candidate — one entry
+     * per cluster resource (`<type>.<name>` → `module.<name>.<type>.<name>`). This
+     * is the denominator the equivalence proof checks coverage against: emit every
+     * one or terraform_equivalence_check hard-fails on the uncovered move. */
+    expected_moves: MovedBlock[];
+}
+/** service keywords of a resource type: `aws_s3_bucket` → ["s3", "bucket"]. */
+export declare function serviceKeywords(resourceType: string): string[];
+export interface HouseModuleSignature {
+    dir: string;
+    resourceTypes: string[];
+    requiredVariables: string[];
+}
+export declare function matchCluster(cluster: ExtractionCluster, houseModules: HouseModuleSignature[], catalogue: ModuleCatalogueEntry[]): CandidateModule[];
+export interface ExtractionCandidate {
+    cluster: ExtractionCluster;
+    candidates: CandidateModule[];
+}
+export declare function findExtractionCandidates(cwd: string, rawCatalogue: string | undefined): ExtractionCandidate[];
+export declare const ModuleExtractionCandidatesParams: import("arktype/internal/variants/object.ts").ObjectType<object, {}>;
+export declare function ModuleExtractionCandidatesTool(ctx: LocalToolContext): import("fastmcp").Tool<any, import("@standard-schema/spec").StandardSchemaV1<object, object>> & {
+    mutates?: boolean;
+};

package/dist/mcp/moduleTests.d.ts

@@ -0,0 +1,106 @@
+import type { LocalToolContext } from "#app/mcp/localContext";
+/**
+ * Keep a reusable module's EXISTING tests/examples
+ * consistent with a fix. `scaffold_terratest` covers the GENERATION direction
+ * (new module → new plan-only tests). This is the inverse: when Remediate fixes
+ * an existing local/house module and the fix changes the module's public
+ * interface (adds a required `variable`, renames or removes one, tightens a
+ * type), the module's `examples/` fixtures and `terraform test` / Terratest
+ * files that CALL it can silently go stale — a missing required variable breaks
+ * `terraform test`/`plan`, and a reference to a removed variable is an error.
+ *
+ * This module finds those test/example assets for a module dir and computes the
+ * DRIFT between what each asset passes and the module's CURRENT interface, so the
+ * agent updates exactly the assets that need it (and only those) after a fix —
+ * never weakening an assertion to go green. The parsing is pure + unit-tested;
+ * the collector just reads the conventional locations (no full-repo walk).
+ */
+export type ModuleTestAssetKind = "example" | "native-test" | "go-test";
+export interface ModuleTestAsset {
+    /** repo-relative path: a dir for examples, a file for native/go tests. */
+    path: string;
+    kind: ModuleTestAssetKind;
+    /** variable names the asset passes to the module (best-effort for go tests). */
+    set_variables: string[];
+}
+export interface ModuleTestDrift {
+    path: string;
+    kind: ModuleTestAssetKind;
+    /** required module variables the asset does NOT set (would break plan/test). */
+    missing_required: string[];
+    /** variables the asset sets that are NOT in the module interface — the fix
+     * renamed or removed them, so the reference is now stale/an error. */
+    unknown_set: string[];
+}
+export interface ModuleTestReport {
+    module_dir: string;
+    /** the module's CURRENT interface, the truth the assets must match. */
+    required_variables: string[];
+    variable_names: string[];
+    assets: ModuleTestAsset[];
+    drift: ModuleTestDrift[];
+}
+/**
+ * The TOP-LEVEL attribute names assigned (`name = …`) directly in an HCL block
+ * body — nested-block / object-field keys are excluded by collapsing `{…}` spans
+ * first. Pure. Used for both a `module` block's arguments and a `variables {}`
+ * block's entries. `==`/`>=`/`!=` etc. are excluded via the `=(?!=)` guard and
+ * by requiring the name to start a line.
+ */
+export declare function topLevelAttributeNames(body: string): string[];
+/**
+ * Variables an example sets on the module(s) whose `source` satisfies
+ * `sourceMatches` — the union of the matching `module` blocks' top-level
+ * arguments (minus meta-args like `source`/`version`/`count`). Pure. Returns []
+ * when no module block in the HCL targets the module.
+ */
+export declare function parseExampleModuleVariables(hcl: string, sourceMatches: (source: string) => boolean): string[];
+/**
+ * Variables a Terraform-native test (`*.tftest.hcl`) sets — the union of every
+ * `variables { … }` block's top-level entries (the top-level block plus any
+ * inside `run "…" { … }`). When the test lives in the module's own dir it tests
+ * the module in place, so these are the module's variables. Pure.
+ */
+export declare function parseNativeTestVariables(hcl: string): string[];
+/**
+ * Variable keys a Go Terratest sets — the `"<key>":` entries inside a
+ * `Vars: map[string]interface{}{ … }` (or `map[string]any{ … }`) literal.
+ * Best-effort (Go isn't parsed structurally); advisory only. Pure.
+ */
+export declare function parseGoTestVariables(go: string): string[];
+/**
+ * Drift between what an asset passes and the module's CURRENT interface:
+ * `missing_required` (required vars the asset never sets) and `unknown_set`
+ * (vars the asset sets that the module no longer declares). Pure.
+ */
+export declare function computeInterfaceDrift(input: {
+    setVariables: string[];
+    requiredVariables: string[];
+    variableNames: string[];
+}): {
+    missing_required: string[];
+    unknown_set: string[];
+};
+/**
+ * Find a module's existing test/example assets in the conventional locations and
+ * record which of the module's variables each one passes. Reads only the module's
+ * own `examples/`/`tests/`/`test/` dirs and the repo-root `examples/` (no
+ * full-tree walk). `moduleDir` is repo-relative POSIX. Side-effecting (reads fs).
+ */
+export declare function discoverModuleTestAssets(cwd: string, moduleDir: string): ModuleTestAsset[];
+/**
+ * Build the module's test/example consistency report: its current interface, the
+ * discovered assets, and the per-asset drift against that interface. Side-effecting
+ * (reads fs). The agent reads `drift` to know which assets to update after a fix.
+ */
+export declare function analyzeModuleTests(cwd: string, moduleDir: string): ModuleTestReport;
+export declare const TerraformModuleTestsParams: import("arktype/internal/variants/object.ts").ObjectType<{
+    module_dir: string;
+}, {}>;
+export declare function TerraformModuleTestsTool(ctx: LocalToolContext): import("fastmcp").Tool<any, import("@standard-schema/spec").StandardSchemaV1<{
+    module_dir: string;
+}, {
+    module_dir: string;
+}>> & {
+    mutates?: boolean;
+};