infraweaver 0.1.0

package/dist/mcp/terraform/evidence.d.ts

@@ -0,0 +1,343 @@
+import { TOOL_NAME } from "#app/brand";
+import { type AssessmentScorecard, type AssessWaiver } from "#app/mcp/assess";
+import { type CrosswalkReport } from "#app/mcp/crosswalk";
+import type { LocalToolContext } from "#app/mcp/localContext";
+import { type EidasSeal } from "#app/mcp/terraform/eidas";
+import { type IdleFloorReport } from "#app/mcp/terraform/idleFloor";
+import type { DriftEvidenceStatement } from "#app/mcp/terraform/planDrift";
+import { type ModuleProvenance } from "#app/mcp/terraform/refactor";
+import { type SignatureMetadata } from "#app/mcp/terraform/signing";
+import type { UpgradeEvidenceStatement } from "#app/mcp/terraform/transformPacks";
+import { type Concern } from "#app/mcp/terraform/types";
+import { type VerificationStatus, type VerificationSummary } from "#app/mcp/terraform/verification";
+/**
+ * Backend-free compliance evidence bundle (the WS4a wedge — an auditor-facing
+ * artifact the OSS action can emit with **zero cloud and no backend**, committed
+ * to a `compliance/` path). It packages the read-only assessment — posture,
+ * per-control statements with their five-status verdict ([[verification]]), the
+ * crosswalk index, and the scanner coverage — into one deterministic JSON file.
+ *
+ * SCHEMA / HONESTY: this is Infraweaver's OWN structured schema, NOT OSCAL. A
+ * strict OSCAL (or compliance-trestle / C2P) emitter is a deliberate follow-up,
+ * gated on a buyer who actually needs OSCAL — emitting OSCAL nobody consumes is
+ * cost without value. The bundle is INDICATIVE alignment guidance, never an audit
+ * verdict, and it never claims `pass` for an unfired control (absence of a
+ * finding is not proof). Pure builder + a thin file-writing tool.
+ */
+export declare const EVIDENCE_SCHEMA: "infraweaver-evidence/v0.8";
+export declare const DEFAULT_EVIDENCE_PATH = "compliance/infraweaver-evidence.json";
+export interface EvidenceControlStatement {
+    concern_id: string;
+    /** line-independent anchor (sha1(source|rule|file), see `concernKeyOf`) — the
+     * stable deep-link key into this bundle: a dashboard finding carries the same
+     * key, so its entry here is locatable even after a fix shifts line numbers.
+     * Absent when the backing concern wasn't supplied to the builder. */
+    concern_key?: string | undefined;
+    rule_id: string;
+    /** the five-status verdict for this statement (fail / not-code-verifiable). */
+    status: VerificationStatus;
+    severity?: string | undefined;
+    file?: string | undefined;
+    line?: number | null | undefined;
+    controls: {
+        framework: string;
+        control: string;
+        title: string;
+    }[];
+}
+/**
+ * A refactor's evidence statement — emitted only for a refactor run. Carries the
+ * verdict, the equivalence sub-results that BACK it (when a keys-free proof ran),
+ * the adopted-module provenance, and — per §8 — BOTH what it asserts and what it
+ * explicitly does NOT. A `proposed-unproven` verdict (a b.4 third-party adoption
+ * shipped without a plan) asserts nothing about runtime behaviour.
+ */
+export interface EvidenceRefactorStatement {
+    verdict: "equivalence-proven" | "equivalence-failed" | "proposed-unproven";
+    equivalence?: {
+        resource_set_preserved: boolean;
+        arguments_preserved: boolean;
+        moves_exhaustive: boolean;
+        moves_detected: number;
+        uncovered_moves: number;
+        validate_passed: boolean;
+        fmt_clean: boolean;
+    } | undefined;
+    /** every external module the config adopts, with its pinned version (provenance
+     * discipline — the analog to a SHA-pinned action). */
+    module_provenance: ModuleProvenance[];
+    /** true when the change is proposed but unproven — the unmissable b.4 marker. */
+    proposed_unproven: boolean;
+    asserts: string;
+    does_not_assert: string;
+}
+/**
+ * The §5.19 cost statement: the credential-free IDLE FLOOR — what this
+ * configuration bills at zero traffic — with the same asserts/does_not_assert
+ * honesty pair the refactor statement carries. Deliberately NOT a monthly total:
+ * usage-dependent lines are not derivable from Terraform, so the floor is the
+ * only cost figure this bundle is willing to sign.
+ */
+export interface EvidenceCostStatement {
+    /** Currency of every figure below (from the bundled price snapshot). */
+    currency: string;
+    /** Cloud region the list prices were captured for. */
+    region: string;
+    /** ISO date the bundled price snapshot was captured — makes staleness visible. */
+    priced_at: string;
+    /** Monthly cost that accrues at zero traffic. */
+    monthly_floor: number;
+    /** One entry per resource contributing to the floor. */
+    resources: {
+        address: string;
+        resource_type: string;
+        file: string;
+        line: number;
+        monthly_cost: number;
+    }[];
+    /** Catalogued resources left unpriced because their tier was not identifiable
+     *  — the signed floor is a lower bound by exactly these. */
+    unpriced: {
+        address: string;
+        resource_type: string;
+        file: string;
+        line: number;
+        reason: string;
+    }[];
+    asserts: string;
+    does_not_assert: string;
+}
+/**
+ * Build the suppression summary (pure). Unlike `cost` and `drift`, this block is
+ * **always present** — including with `count: 0`. An omitted section would be
+ * ambiguous ("nothing silenced" vs "this version didn't record it"), and the
+ * whole point is that a reader can tell a clean repo from a quiet one without
+ * having to trust that we'd have mentioned it.
+ */
+export declare function buildSuppressionSummary(waivers: ReadonlyArray<AssessWaiver>): EvidenceSuppressionSummary;
+/**
+ * Build the cost evidence statement (pure). Returns undefined when no cost
+ * analysis ran or nothing priced, so the bundle omits the section entirely
+ * rather than signing a zero that could be read as "this costs nothing".
+ */
+export declare function buildCostStatement(report: IdleFloorReport | undefined): EvidenceCostStatement | undefined;
+/** the equivalence sub-results buildRefactorStatement reads (the shape recorded
+ * in `scanSession.refactorEquivalence`). */
+export interface RefactorEquivalenceInput {
+    equivalent: boolean;
+    resource_set_equivalent: boolean;
+    arg_names_equivalent: boolean;
+    moves_exhaustive: boolean;
+    moves_detected: number;
+    validate_passed: boolean;
+    fmt_clean: boolean;
+    uncovered_moves: {
+        from: string;
+        to: string;
+    }[];
+}
+/**
+ * Build the refactor evidence statement (pure). Returns undefined when nothing
+ * refactor-related happened (no equivalence proof, not a proposed-unproven b.4,
+ * no external module) so the bundle omits the section entirely. Infraweaver asserts
+ * only what the inputs prove — a failed or absent proof asserts nothing.
+ */
+export declare function buildRefactorStatement(args: {
+    equivalence?: RefactorEquivalenceInput | undefined;
+    provenance: ModuleProvenance[];
+    proposedUnproven: boolean;
+}): EvidenceRefactorStatement | undefined;
+/**
+ * What this run did NOT judge, because a human had already accepted it.
+ *
+ * WHY THIS IS IN THE SIGNED BYTES. `posture` and `control_statements` describe
+ * the OPEN findings only — suppressed ones are excluded by design, because a
+ * waived finding genuinely is an accepted risk. But that means a repo with
+ * thirty active waivers produced a bundle byte-indistinguishable from a
+ * genuinely clean one, and the difference is exactly what an assessor is there
+ * to examine. The human-readable report has always listed waivers; the SIGNED
+ * artifact did not, which made the signature cover the flattering half of the
+ * story.
+ *
+ * Each entry is what was silenced, where it is, why (a reason is mandatory
+ * everywhere), by which mechanism, and until when.
+ *
+ * A note on `source`. It records the two things the suppression pipeline
+ * actually models: `inline` (a directive in the source file) and `policy` (the
+ * `.infraweaver.yml` block). A skip written for ANOTHER scanner
+ * (`# checkov:skip=…`) is honoured and lands under `inline`, with the pipeline's
+ * own `[via <tool> skip]` marker appended to its reason — so the distinction is
+ * visible in the entry without this block claiming a structured tally the
+ * concern model does not carry.
+ */
+export interface EvidenceSuppressionRecord {
+    rule_id: string;
+    severity: string;
+    file: string;
+    line?: number | null | undefined;
+    /** mandatory everywhere; carries the `[via <tool> skip]` marker when the
+     *  directive was another scanner's rather than ours. */
+    reason: string;
+    /** `inline` = a directive in the source file; `policy` = the `.infraweaver.yml` block. */
+    source: string;
+    /** ISO date the waiver lapses, or null for an open-ended one. */
+    expires: string | null;
+}
+export interface EvidenceSuppressionSummary {
+    /** how many findings this bundle's posture excludes. 0 ⇒ nothing silenced. */
+    count: number;
+    /** count by mechanism (`inline` / `policy`) — how the silencing was applied. */
+    by_source: Record<string, number>;
+    /** open-ended waivers — the ones with no review date. */
+    never_expire: number;
+    entries: EvidenceSuppressionRecord[];
+    asserts: string;
+    does_not_assert: string;
+}
+/**
+ * WHO produced this evidence (A.3). The bundle always named the engine; after
+ * the Trivy compromise that is not enough — a poisoned scanner produces
+ * poisoned findings under a clean engine version. This block records the whole
+ * acting chain: the model that drove the agent, the runtime, and the exact
+ * scanner builds the integrity gate observed (`toolchainIntegrity`) before
+ * executing them. Nothing here is fabricated: a tool that never ran this
+ * session is simply absent from `scanners`, and an unresolved model is null.
+ */
+export interface EvidenceProvenance {
+    /** resolved model specifier that drove the agent, or null (auto/unknown —
+     * e.g. a local `infraweaver mcp` session has no agent of its own). */
+    model: string | null;
+    /** the Node.js runtime the engine executed on (`process.version`). */
+    node: string;
+    /** exact scanner versions probed by the integrity gate before execution —
+     * only tools that actually ran this session appear. */
+    scanners: {
+        tool: string;
+        version: string | null;
+    }[];
+}
+export interface EvidenceBundle {
+    /** Infraweaver's own schema id — explicitly NOT OSCAL (see module note). */
+    schema: typeof EVIDENCE_SCHEMA;
+    /** caller-supplied ISO timestamp (kept out of the builder so it stays pure). */
+    generated_at: string;
+    tool: {
+        name: typeof TOOL_NAME;
+        version: string;
+    };
+    /** who produced this evidence — model + runtime + observed scanner builds. */
+    provenance: EvidenceProvenance;
+    subject: {
+        scanned_dir: string;
+        repo?: string | undefined;
+        ref?: string | undefined;
+        commit?: string | undefined;
+    };
+    posture: AssessmentScorecard["posture"];
+    summary: {
+        total: number;
+        by_severity: AssessmentScorecard["by_severity"];
+        verification: VerificationSummary["counts"];
+    };
+    /** one statement per mapped concern, each carrying its status + controls. */
+    control_statements: EvidenceControlStatement[];
+    /** which scanners code-verified vs which were inconclusive (coverage gaps). */
+    coverage: VerificationSummary["coverage"];
+    /** what the posture above EXCLUDES because a human accepted it. Always
+     * present (0 when nothing was silenced) so a clean repo and a quiet one are
+     * distinguishable from the signed bytes alone. */
+    suppressions: EvidenceSuppressionSummary;
+    crosswalk: {
+        version: string;
+        reviewed: string;
+        /** sha256 of the reviewed crosswalk tables that produced these verdicts —
+         *  binds the exact (integrity-gated) control mapping into the signed bundle. */
+        digest: string;
+        by_framework: CrosswalkReport["by_framework"];
+    };
+    /** the five-status legend, so the bundle is self-describing for an assessor. */
+    legend: Record<VerificationStatus, string>;
+    /** present only on a refactor run — the equivalence/proposed-unproven statement
+     * with the proof that backs it (omitted entirely otherwise). */
+    refactor?: EvidenceRefactorStatement | undefined;
+    /** present only when the credential-free cost analysis ran — the §5.19 idle
+     * floor (what this bills at zero traffic), never a monthly total. */
+    cost?: EvidenceCostStatement | undefined;
+    /** present only when detect_plan_drift ran — the TC-2.1 drift statement:
+     * signed, bounded proof of whether live infrastructure matched the committed
+     * configuration when the plan artifact was produced, with the `forgotten`
+     * blind-spot list and every coverage gap carried in the claim itself. */
+    drift?: DriftEvidenceStatement | undefined;
+    /** present only when a provider-major upgrade was detected (TC-2.2) — which
+     * boundary was crossed, the codified transforms found in this configuration,
+     * and the plan that proves (or fails to prove) the result. A `no-plan` verdict
+     * is recorded rather than omitted: an upgrade shipped without a plan is
+     * exactly the thing a reader must be able to see. */
+    upgrade?: UpgradeEvidenceStatement | undefined;
+    /** Ed25519 signing metadata (public key + fingerprint + the sibling `.sig`
+     * carrying the detached signature over this file's exact bytes), or an
+     * explicit null when no INFRAWEAVER_SIGNING_KEY is configured — never fake. */
+    signature: SignatureMetadata | null;
+    /** §5.16 always-present eIDAS assurance declaration: which electronic-seal
+     * tier the `signature` above actually reaches, and — the load-bearing half —
+     * which it does not. `signature` says HOW the bytes were signed; this says
+     * WHAT THAT IS WORTH legally, so a reader cannot over-read an Ed25519
+     * signature as a qualified seal. Present even when unsigned (`level: "none"`),
+     * because an omitted section is ambiguous. See [[eidas]]. */
+    seal: EidasSeal;
+    disclaimer: string;
+}
+export interface EvidenceSubject {
+    scanned_dir: string;
+    repo?: string | undefined;
+    ref?: string | undefined;
+    commit?: string | undefined;
+}
+/**
+ * Build the evidence bundle from an assessment's scorecard + crosswalk. Pure —
+ * `generatedAt` and the subject identifiers are passed in so the same inputs
+ * always produce the same bytes (and tests don't need a clock). Control
+ * statements come from the crosswalk entries (which already carry the
+ * verification status), enriched with the concern's severity/location when the
+ * scanned concerns are supplied (the crosswalk entry itself carries neither).
+ */
+export declare function buildEvidenceBundle(args: {
+    scorecard: AssessmentScorecard;
+    crosswalk: CrosswalkReport;
+    subject: EvidenceSubject;
+    generatedAt: string;
+    version?: string;
+    /** the scanned concerns backing the crosswalk entries — the source of each
+     * statement's severity/file/line enrichment. */
+    concerns?: Concern[];
+    refactor?: EvidenceRefactorStatement | undefined;
+    /** the §5.19 idle-floor statement; omitted when no cost analysis ran. */
+    cost?: EvidenceCostStatement | undefined;
+    /** the TC-2.1 drift statement; omitted when detect_plan_drift didn't run. */
+    drift?: DriftEvidenceStatement | undefined;
+    /** the TC-2.2 upgrade statement; omitted when no provider-major pack applied. */
+    upgrade?: UpgradeEvidenceStatement | undefined;
+    /** who produced this evidence (A.3). REQUIRED — an evidence bundle that
+     * doesn't name its actor is the gap this block exists to close. Callers pass
+     * real values (the builder stays pure; no ambient reads here). */
+    provenance: EvidenceProvenance;
+    /** signing metadata when a key is configured; omitted/null ⇒ explicit
+     * `"signature": null` (the honest-unsigned marker). */
+    signature?: SignatureMetadata | null;
+}): EvidenceBundle;
+export declare const TerraformEmitEvidenceParams: import("arktype/internal/variants/object.ts").ObjectType<{
+    output_path?: string;
+    severity_threshold?: "critical" | "high" | "info" | "low" | "medium";
+    proposed_unproven?: boolean;
+}, {}>;
+export declare function TerraformEmitEvidenceTool(ctx: LocalToolContext): import("fastmcp").Tool<any, import("@standard-schema/spec").StandardSchemaV1<{
+    output_path?: string;
+    severity_threshold?: "critical" | "high" | "info" | "low" | "medium";
+    proposed_unproven?: boolean;
+}, {
+    output_path?: string;
+    severity_threshold?: "critical" | "high" | "info" | "low" | "medium";
+    proposed_unproven?: boolean;
+}>> & {
+    mutates?: boolean;
+};

package/dist/mcp/terraform/findings.d.ts

@@ -0,0 +1,76 @@
+import { type Concern } from "#app/mcp/terraform/types";
+/**
+ * Map a reviewer `findings.json` body into Concern[]. Drops `human_only`
+ * findings (out of scope — not auto-remediable). Paths are normalized to
+ * repo-relative POSIX (same as the scanners) so ids and grouping stay portable.
+ */
+export declare function parseReviewerFindings(json: string, cwd?: string): Concern[];
+declare const SarifReport: import("arktype/internal/variants/object.ts").ObjectType<{
+    version?: string;
+    $schema?: string;
+    runs?: {
+        tool?: {
+            driver?: {
+                name?: string;
+                rules?: {
+                    id?: string;
+                    helpUri?: string;
+                    shortDescription?: {
+                        text?: string;
+                    };
+                }[];
+            };
+        };
+        results?: {
+            ruleId?: string;
+            level?: string;
+            message?: {
+                text?: string;
+            };
+            locations?: {
+                physicalLocation?: {
+                    artifactLocation?: {
+                        uri?: string;
+                    };
+                    region?: {
+                        startLine?: number;
+                    };
+                };
+            }[];
+            properties?: {
+                "security-severity"?: string;
+            };
+            suppressions?: {
+                kind: "external" | "inSource";
+                justification?: string;
+            }[];
+        }[];
+    }[];
+}, {}>;
+type SarifReport = typeof SarifReport.infer;
+/** true when a parsed JSON object looks like a SARIF report (the standard
+ * scanner-output format) rather than a terraform-reviewer findings.json. */
+export declare function isSarif(parsed: unknown): boolean;
+/**
+ * Parse a SARIF 2.1.0 report (the standard scanner-output format Trivy /
+ * Checkov / tflint all emit) into Concern[]. The driver name picks the source so
+ * a finding from a scanner Infraweaver re-runs reproduces the SAME content id
+ * (✗→✓ verifiable); other tools collapse to `reviewer`. Rule docs come from the
+ * matching `tool.driver.rules[].helpUri`. Non-Terraform files are dropped.
+ */
+export declare function parseSarifFindings(json: string, cwd?: string): Concern[];
+/** dispatch a findings file to the right parser: SARIF (standard scanner
+ * output) or a terraform-reviewer findings.json. */
+export declare function parseFindingsFile(json: string, cwd?: string): Concern[];
+/**
+ * Emit a set of concerns as a SARIF 2.1.0 report for GitHub code-scanning (the
+ * inverse of `parseSarifFindings` — close the loop so a Infraweaver scan can
+ * populate the repo's Security tab via `github/codeql-action/upload-sarif`). One
+ * `run` with the `infraweaver` driver, a deduped `rules` array (each rule's
+ * `helpUri` from `ruleDocUrl`), and one `result` per concern carrying its
+ * `level`, `security-severity`, message, and `file:line`. Pure + deterministic
+ * (rules sorted, stable partialFingerprints from the content id) so re-emitting
+ * an unchanged scan yields a byte-identical report.
+ */
+export declare function buildSarifReport(concerns: Concern[]): SarifReport;
+export {};

package/dist/mcp/terraform/fixMemory.d.ts

@@ -0,0 +1,81 @@
+import { type Concern } from "#app/mcp/terraform/types";
+export declare const FIX_MEMORY_FILENAME = ".infraweaver.fix-memory.json";
+/**
+ * A proven-fix pattern. Freshly CAPTURED patterns carry only the identity +
+ * guidance (no stats); LIBRARY entries (loaded from Cloud / a local file) also
+ * carry the reuse stats and the operator `disabled` flag. The finding-TYPE key
+ * (`finding_type`) is file-independent on purpose — the whole point is to reuse
+ * across files and repos.
+ */
+export interface ProvenFixPattern {
+    /** the finding-TYPE shape: `source|bareRule` (file-independent). The match key. */
+    finding_type: string;
+    /** producing scanner, when known (null for reviewer-loaded concerns). */
+    source: string | null;
+    /** cross-scanner canonical class (e.g. "aws-s3-encryption"), when recognised. */
+    canonical_class: string | null;
+    category: string;
+    /** human label — the namespaced rule id (e.g. "trivy:AVD-AWS-0088"). */
+    title: string;
+    /** the scanner's "what is wrong" message, trimmed + capped. */
+    description: string | null;
+    /** the remediation guidance that proved out (trivy Resolution / fmt hint / …). */
+    remediation_hint: string | null;
+    /** a representative BEFORE snippet from the repo the pattern was proven on —
+     *  a concrete example for the fixer to adapt, never a patch to apply verbatim. */
+    before_example: string | null;
+    /** how many times this type went `✗→✓` (across the fleet, from Cloud). */
+    times_proven?: number;
+    /** distinct repos it's been proven on. */
+    repos_count?: number;
+    /** ISO timestamp of the most recent proof. */
+    last_proven?: string;
+    /** operator retired this pattern in the dashboard — never offered to the fixer. */
+    disabled?: boolean;
+}
+/** The finding-TYPE identity: `source|bareRule`, file-independent (unlike
+ *  `concernKeyOf`, which folds in the file). Two instances of the same rule in
+ *  different files/repos share this key — the reuse unit. */
+export declare function findingTypeOf(c: Pick<Concern, "source" | "rule_id">): string;
+/** Build a fresh pattern from a concern that just proved out `✗→✓`. Pure. */
+export declare function captureProvenFix(c: Concern): ProvenFixPattern;
+/**
+ * De-duplicate a run's captures to one pattern per finding-type. When the same
+ * type is proven on several concerns this run, keep the FIRST that carries a
+ * before-example (a concrete example beats none), else the first seen — the
+ * order is otherwise stable so the wire is deterministic.
+ */
+export declare function dedupeCaptures(captures: ProvenFixPattern[]): ProvenFixPattern[];
+/**
+ * Match a loaded library against the CURRENT scan's concerns: return the patterns
+ * whose finding-type is present in this scan (deduped, `disabled` excluded),
+ * newest-proven first, capped. This is what the fixer is offered — a proven prior
+ * for the exact finding-types it's about to fix. Pure.
+ */
+export declare function matchPatternsForConcerns(library: ProvenFixPattern[], concerns: Pick<Concern, "source" | "rule_id">[], max?: number): ProvenFixPattern[];
+export interface FixMemoryFile {
+    version: 1;
+    /** ISO timestamp of the last write (informational). */
+    updated?: string;
+    patterns: ProvenFixPattern[];
+}
+/**
+ * Merge freshly-captured patterns into a local library, keyed by finding-type:
+ * bump `times_proven`, advance `last_proven`, and prefer a non-empty
+ * before-example/hint over an empty one. The local file is single-repo memory
+ * (the fleet count lives in Cloud), so `repos_count` stays 1 here. Pure.
+ */
+export declare function mergeFixMemory(existing: ProvenFixPattern[], captured: ProvenFixPattern[], provenAt: string): ProvenFixPattern[];
+export declare function serializeFixMemory(patterns: ProvenFixPattern[], updated: string): FixMemoryFile;
+/** Parse fix-memory JSON into a pattern list; tolerant of a malformed/old file (→ null). */
+export declare function parseFixMemory(raw: string): ProvenFixPattern[] | null;
+/** Structural guard for one untrusted pattern (from a file or the Cloud library). */
+export declare function isProvenFixPattern(value: unknown): value is ProvenFixPattern;
+/** Load `.infraweaver.fix-memory.json` under `cwd`; [] when absent/unreadable/malformed. */
+export declare function loadFixMemory(cwd: string | undefined): ProvenFixPattern[];
+/**
+ * Coerce an untrusted library payload (the Cloud run-context `provenFixes` blob)
+ * into typed patterns, keeping only structurally-valid, non-disabled entries.
+ * Pure — the wire boundary can't be typechecked across repos.
+ */
+export declare function coerceLibrary(raw: unknown): ProvenFixPattern[];

package/dist/mcp/terraform/governance.d.ts

@@ -0,0 +1,56 @@
+import { type Concern } from "#app/mcp/terraform/types";
+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;
+}
+/**
+ * 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 declare function findActionTriggers(hcl: string): ActionTriggerSite[];
+/** 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 declare function findActionDeclarations(hcl: string): {
+    address: string;
+    line: number;
+}[];
+export declare function actionTriggersToConcerns(sites: ActionTriggerSite[], file: string): Concern[];
+export declare function isStatefulResourceType(resourceType: string): boolean;
+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 declare function findDynamicDestroyProtection(hcl: string): DynamicDestroyProtectionSite[];
+export declare function dynamicDestroyProtectionToConcerns(sites: DynamicDestroyProtectionSite[], file: string): Concern[];
+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 declare function scanGovernanceFile(hcl: string, file: string): GovernanceScan;

package/dist/mcp/terraform/hcl.d.ts

@@ -0,0 +1,115 @@
+/**
+ * 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 declare function skipNonCode(s: string, i: number): {
+    end: number;
+    endsLine: boolean;
+} | 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 declare function matchBraceBody(hcl: string, open: number): {
+    text: string;
+    end: number;
+} | null;
+/** 1-based line number of `index` in `hcl`. */
+export declare function lineOf(hcl: string, index: number): number;
+/** 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 declare function parseBlocks(hcl: string, keywords: readonly string[]): HclBlock[];
+/** 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 declare function topLevelAssignments(body: string): HclAssignment[];
+/**
+ * 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 declare function stripTrailingComment(value: string): string;
+/** 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 declare function isStringLiteral(value: string): boolean;