ecsodus 0.1.0__py3-none-any.whl

ecsodus/__init__.py

@@ -0,0 +1,6 @@
+"""ecsodus: safely migrate AWS Copilot CLI apps to Terraform-managed ECS.
+
+ecsodus is read-only: it inventories, reports and generates files. It never changes AWS.
+"""
+
+__version__ = "0.1.0"

ecsodus/cfn.py

@@ -0,0 +1,198 @@
+"""CloudFormation template parsing.
+
+Two views of a template are needed:
+
+* a *semantic* view (plain dicts, short-form tags such as ``!Ref`` normalised to the long form
+  ``{"Ref": ...}``), used for analysis and for verifying patches; and
+* *source positions* of each resource, used by the retain patcher to edit the original text
+  without re-serialising it (re-serialising YAML changes indentation and quoting, which would
+  break the "byte-stable apart from the patch" rule).
+"""
+
+from __future__ import annotations
+
+import io
+import json
+from dataclasses import dataclass
+from typing import Any
+
+from ruamel.yaml import YAML
+from ruamel.yaml.constructor import SafeConstructor
+from ruamel.yaml.nodes import MappingNode, ScalarNode, SequenceNode
+
+_SHORT_TAGS = {
+    "Ref": "Ref",
+    "Condition": "Condition",
+    "GetAtt": "Fn::GetAtt",
+}
+
+
+class TemplateError(ValueError):
+    """The template cannot be parsed or has a shape ecsodus refuses to handle."""
+
+
+def _construct_tagged(loader: Any, tag_suffix: str, node: Any) -> dict[str, Any]:
+    name = _SHORT_TAGS.get(tag_suffix, f"Fn::{tag_suffix}")
+    if isinstance(node, ScalarNode):
+        value: Any = loader.construct_scalar(node)
+        if tag_suffix == "GetAtt" and isinstance(value, str):
+            head, _, tail = value.partition(".")
+            value = [head, tail]
+    elif isinstance(node, SequenceNode):
+        value = loader.construct_sequence(node, deep=True)
+    elif isinstance(node, MappingNode):
+        value = loader.construct_mapping(node, deep=True)
+    else:  # pragma: no cover - ruamel only produces the three node kinds
+        raise TemplateError(f"unsupported node for !{tag_suffix}")
+    return {name: _plain(value)}
+
+
+def _plain(value: Any) -> Any:
+    """Convert ruamel containers to plain dict/list recursively."""
+    if isinstance(value, dict):
+        return {str(k): _plain(v) for k, v in value.items()}
+    if isinstance(value, list):
+        return [_plain(v) for v in value]
+    return value
+
+
+class _CfnConstructor(SafeConstructor):
+    """The semantic view's constructor.
+
+    ruamel registers constructors on the *class*. Registering on the shared SafeConstructor
+    leaked the ``!`` multi-constructor into the round-trip loader that :func:`yaml_positions`
+    uses, so after any :func:`load` a tagged mapping (``!GetAZs {Ref: AWS::Region}``) broke
+    retain patching. A private subclass keeps both registrations to this view.
+    """
+
+
+_CfnConstructor.add_multi_constructor("!", _construct_tagged)
+# CloudFormation treats unquoted dates as strings (AWSTemplateFormatVersion: 2010-09-09).
+_CfnConstructor.add_constructor("tag:yaml.org,2002:timestamp", SafeConstructor.construct_yaml_str)
+
+
+def _semantic_yaml() -> YAML:
+    y = YAML(typ="safe", pure=True)
+    y.Constructor = _CfnConstructor
+    return y
+
+
+def is_json(text: str) -> bool:
+    return text.lstrip().startswith("{")
+
+
+def load(text: str) -> dict[str, Any]:
+    """Parse a template (JSON or YAML) into plain dicts with long-form intrinsics."""
+    try:
+        data = json.loads(text) if is_json(text) else _semantic_yaml().load(io.StringIO(text))
+    except Exception as exc:  # noqa: BLE001 - surface any parser error uniformly
+        raise TemplateError(f"cannot parse template: {exc}") from exc
+    data = _plain(data)
+    if not isinstance(data, dict) or not isinstance(data.get("Resources"), dict):
+        raise TemplateError("template has no Resources mapping")
+    return data
+
+
+@dataclass(frozen=True)
+class ResourcePosition:
+    """Where one resource's mapping sits in the template source (0-based lines)."""
+
+    logical_id: str
+    key_line: int  # the "LogicalId:" line
+    body_line: int  # first line of the resource body
+    body_col: int  # indentation of the resource body keys
+    keys: dict[str, tuple[int, int]]  # attribute key -> (line, col)
+    flow_style: bool
+    template_url: tuple[int, int] | None = None  # Properties.TemplateURL key (line, col)
+    metadata: tuple[int, int, bool] | None = None  # Metadata body (line, col, is_block_map)
+
+
+def yaml_positions(text: str) -> dict[str, ResourcePosition]:
+    """Source positions of every resource in a block-style YAML template."""
+    y = YAML(typ="rt", pure=True)
+    try:
+        doc = y.load(io.StringIO(text))
+    except Exception as exc:  # noqa: BLE001
+        raise TemplateError(f"cannot parse template: {exc}") from exc
+    resources = doc.get("Resources") if hasattr(doc, "get") else None
+    if resources is None:
+        raise TemplateError("template has no Resources mapping")
+    out: dict[str, ResourcePosition] = {}
+    for lid, body in resources.items():
+        key_line, _ = resources.lc.key(lid)
+        if not hasattr(body, "lc"):
+            raise TemplateError(f"resource {lid} is not a mapping")
+        flow = body.fa.flow_style() if hasattr(body, "fa") else False
+        keys = {str(k): tuple(body.lc.key(k)) for k in body}
+        template_url = None
+        props = body.get("Properties")
+        if hasattr(props, "lc") and "TemplateURL" in props:
+            template_url = tuple(props.lc.key("TemplateURL"))
+        metadata = None
+        meta = body.get("Metadata")
+        if meta is not None:
+            is_block = hasattr(meta, "lc") and not (hasattr(meta, "fa") and meta.fa.flow_style())
+            if is_block and len(meta):
+                metadata = (meta.lc.line, meta.lc.col, True)
+            else:
+                metadata = (*keys["Metadata"], False)
+        out[str(lid)] = ResourcePosition(
+            logical_id=str(lid),
+            key_line=key_line,
+            body_line=body.lc.line,
+            body_col=body.lc.col,
+            keys=keys,  # type: ignore[arg-type]
+            flow_style=bool(flow),
+            template_url=template_url,  # type: ignore[arg-type]
+            metadata=metadata,  # type: ignore[arg-type]
+        )
+    return out
+
+
+def resources(template: dict[str, Any]) -> dict[str, dict[str, Any]]:
+    return template.get("Resources", {})
+
+
+def references(value: Any) -> set[str]:
+    """Logical IDs referenced by Ref / GetAtt / Sub / DependsOn inside ``value``."""
+    found: set[str] = set()
+
+    def walk(v: Any) -> None:
+        if isinstance(v, dict):
+            for k, inner in v.items():
+                if k == "Ref" and isinstance(inner, str):
+                    found.add(inner)
+                elif k == "Fn::GetAtt":
+                    if isinstance(inner, list) and inner and isinstance(inner[0], str):
+                        found.add(inner[0])
+                    elif isinstance(inner, str):
+                        found.add(inner.split(".", 1)[0])
+                elif k == "Fn::Sub":
+                    tpl = inner[0] if isinstance(inner, list) else inner
+                    if isinstance(tpl, str):
+                        found.update(_sub_vars(tpl))
+                    walk(inner)
+                    continue
+                walk(inner)
+        elif isinstance(v, list):
+            for inner in v:
+                walk(inner)
+
+    walk(value)
+    return found
+
+
+def _sub_vars(template: str) -> set[str]:
+    out: set[str] = set()
+    i = 0
+    while True:
+        start = template.find("${", i)
+        if start < 0:
+            return out
+        end = template.find("}", start)
+        if end < 0:
+            return out
+        name = template[start + 2 : end].strip()
+        if not name.startswith("!"):
+            out.add(name.split(".", 1)[0])
+        i = end + 1

ecsodus/check/changeset.py

@@ -0,0 +1,256 @@
+"""CloudFormation change-set acceptance rule for retain patches (PLAN §2.4, §13.2–3).
+
+Input: the JSON of ``aws cloudformation describe-change-set`` for the root change set and every
+nested change set (created with ``--include-nested-stacks``; describe each nested one by the
+``ChangeSetId`` shown on its ``AWS::CloudFormation::Stack`` resource change). Create change sets
+with ``--include-property-values`` so Metadata before/after values can be checked.
+
+Every resource change must be a policy-only ``Modify`` with ``Replacement: False``. Allowed
+detail targets:
+
+* ``Attribute`` DeletionPolicy / UpdateReplacePolicy;
+* ``Properties``/``TemplateURL`` with ``RequiresRecreation: Never`` on an
+  ``AWS::CloudFormation::Stack`` that ``generate`` patched (listed in the manifest);
+* ``Metadata`` whose only change is the ``ecsodus:retain`` key, when the Metadata fallback is on;
+* optionally, ``Dynamic`` ``ResourceAttribute`` entries caused by a patched nested stack's
+  outputs, only when explicitly allowed and that nested change set itself passes.
+
+An empty change set is not a pass: it means either the stack is already retained (verify with
+``ecsodus verify-retain`` and skip it) or CloudFormation treated the policy-only change as a no-op
+(use the Metadata fallback). The result distinguishes this case.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass, field
+from typing import Any
+
+from ecsodus.emit.retain_patch import METADATA_KEY, NESTED_STACK_TYPE
+
+POLICY_ATTRIBUTES = {"DeletionPolicy", "UpdateReplacePolicy"}
+NESTED_UNAVAILABLE_REASON = "Only executable from the root change set."
+NO_CHANGES_REASONS = ("didn't contain changes", "No updates are to be performed")
+
+PASS = "pass"
+FAIL = "fail"
+EMPTY = "empty"
+
+
+@dataclass
+class ChangeSetResult:
+    verdict: str
+    errors: list[str] = field(default_factory=list)
+    accepted: int = 0
+    change_sets: int = 0
+
+    @property
+    def ok(self) -> bool:
+        return self.verdict == PASS
+
+
+def _is_empty(cs: dict[str, Any]) -> bool:
+    if cs.get("Changes"):
+        return False
+    reason = cs.get("StatusReason") or ""
+    if cs.get("Status") == "FAILED":
+        return any(r in reason for r in NO_CHANGES_REASONS)
+    return cs.get("Status") == "CREATE_COMPLETE"
+
+
+def _metadata_only_ecsodus(detail: dict[str, Any]) -> bool:
+    target = detail.get("Target") or {}
+    before, after = target.get("BeforeValue"), target.get("AfterValue")
+    if after is None:
+        return False  # without --include-property-values the change cannot be verified
+    try:
+        b = json.loads(before) if before else {}
+        a = json.loads(after)
+    except (TypeError, ValueError):
+        return False
+    if not isinstance(a, dict) or not isinstance(b, dict):
+        return False
+    a = dict(a)
+    if a.pop(METADATA_KEY, None) not in ("true", True):
+        return False
+    b.pop(METADATA_KEY, None)
+    return a == b
+
+
+def check_change_sets(
+    change_sets: Iterable[dict[str, Any]],
+    patched_nested: Iterable[str] | Mapping[str, str] = (),
+    allow_metadata_key: bool = False,
+    allow_nested_dynamic: bool = False,
+) -> ChangeSetResult:
+    """Apply the acceptance rule to a root change set and all of its nested change sets.
+
+    ``patched_nested`` maps each patched nested-stack wrapper's logical ID to the S3 URL of its
+    patched child template (from the manifest); a plain list of IDs is accepted but then the
+    ``TemplateURL`` value cannot be verified and the rule fails closed.
+
+    Requirements beyond the per-change rule:
+
+    * every change set is ``CREATE_COMPLETE`` and executable (``ExecutionStatus: AVAILABLE``);
+      anything still in progress fails;
+    * every nested change set referenced by a stack-resource change is supplied, and every
+      supplied change set is the root or referenced by one;
+    * a ``TemplateURL`` change's new value (``describe-change-set --include-property-values``)
+      equals the manifest URL of the patched child.
+    """
+    sets = list(change_sets)
+    nested_urls: dict[str, str | None] = (
+        dict(patched_nested)
+        if isinstance(patched_nested, Mapping)
+        else dict.fromkeys(patched_nested)
+    )
+    result = ChangeSetResult(verdict=PASS, change_sets=len(sets))
+    if not sets:
+        return ChangeSetResult(verdict=FAIL, errors=["no change sets given"])
+    if len(sets) == 1 and _is_empty(sets[0]):
+        return ChangeSetResult(verdict=EMPTY, change_sets=1)
+
+    ids = {cs.get("ChangeSetId") for cs in sets if cs.get("ChangeSetId")}
+    roots = [cs for cs in sets if not cs.get("ParentChangeSetId")]
+    if len(roots) != 1:
+        result.errors.append(f"expected exactly one root change set, got {len(roots)}")
+    referenced: set[str] = set()
+    for cs in sets:
+        for change in cs.get("Changes") or []:
+            child = (change.get("ResourceChange") or {}).get("ChangeSetId")
+            if child:
+                referenced.add(child)
+    for child in sorted(referenced - ids):
+        result.errors.append(f"nested change set {child} was not supplied (describe it too)")
+    root_id = roots[0].get("ChangeSetId") if len(roots) == 1 else None
+    by_id = {cs.get("ChangeSetId"): cs for cs in sets}
+    for cs in sets:
+        cid = cs.get("ChangeSetId")
+        parent = cs.get("ParentChangeSetId")
+        if parent and cid not in referenced:
+            result.errors.append(f"change set {cid} is not referenced by the root")
+        if parent and (parent not in by_id or parent == cid):
+            result.errors.append(f"change set {cid} has parent {parent}, which was not supplied")
+        if cs.get("RootChangeSetId") and root_id and cs["RootChangeSetId"] != root_id:
+            result.errors.append(f"change set {cid} belongs to another root")
+    # Wrapper logical IDs whose child change set was actually supplied (for Dynamic entries),
+    # and each child's claimed parent and stack must match the change that references it.
+    supplied_children: set[str] = set()
+    for cs in sets:
+        for change in cs.get("Changes") or []:
+            rcx = change.get("ResourceChange") or {}
+            child_id = rcx.get("ChangeSetId")
+            if child_id not in ids:
+                continue
+            supplied_children.add(rcx.get("LogicalResourceId", ""))
+            child = by_id[child_id]
+            if child.get("ParentChangeSetId") != cs.get("ChangeSetId"):
+                result.errors.append(f"change set {child_id} does not name its referencing parent")
+            phys = rcx.get("PhysicalResourceId")
+            if phys and child.get("StackId") and child["StackId"] != phys:
+                result.errors.append(
+                    f"change set {child_id} is for stack {child['StackId']}, not {phys}"
+                )
+
+    for cs in sets:
+        name = cs.get("StackName") or cs.get("ChangeSetName") or "?"
+        status, execution = cs.get("Status"), cs.get("ExecutionStatus")
+        # Nested change sets are never executable on their own: AWS reports them
+        # UNAVAILABLE with this exact reason (observed in the AWS end-to-end run).
+        nested_ok = (
+            bool(cs.get("ParentChangeSetId"))
+            and execution == "UNAVAILABLE"
+            and cs.get("StatusReason") == NESTED_UNAVAILABLE_REASON
+        )
+        if status != "CREATE_COMPLETE" or (execution != "AVAILABLE" and not nested_ok):
+            result.errors.append(
+                f"{name}: change set is {status}/{execution}, not CREATE_COMPLETE/AVAILABLE"
+                + (f" ({cs.get('StatusReason')})" if cs.get("StatusReason") else "")
+            )
+            continue
+        for change in cs.get("Changes") or []:
+            if change.get("Type") not in (None, "Resource"):
+                result.errors.append(f"{name}: unexpected change type {change.get('Type')}")
+                continue
+            rc = change.get("ResourceChange") or {}
+            where = f"{name}/{rc.get('LogicalResourceId', '?')}"
+            problems = _check_resource_change(
+                rc, nested_urls, allow_metadata_key, allow_nested_dynamic, supplied_children
+            )
+            if problems:
+                result.errors.extend(f"{where}: {p}" for p in problems)
+            else:
+                result.accepted += 1
+    if result.errors:
+        result.verdict = FAIL
+    elif result.accepted == 0:
+        result.verdict = EMPTY
+    return result
+
+
+def _check_resource_change(
+    rc: dict[str, Any],
+    nested_ok: Mapping[str, str | None],
+    allow_metadata_key: bool,
+    allow_nested_dynamic: bool,
+    supplied_children: set[str] = frozenset(),  # type: ignore[assignment]
+) -> list[str]:
+    problems: list[str] = []
+    action = rc.get("Action")
+    if action != "Modify":
+        return [f"action {action} is not allowed (only policy-only Modify)"]
+    replacement = rc.get("Replacement")
+    if replacement != "False":
+        problems.append(f"Replacement is {replacement!r}, must be 'False'")
+    rtype = rc.get("ResourceType", "")
+    lid = rc.get("LogicalResourceId", "")
+    details = rc.get("Details") or []
+    if not details:
+        scope = set(rc.get("Scope") or [])
+        if not scope or scope - POLICY_ATTRIBUTES:
+            problems.append(f"Modify with no details and scope {sorted(scope)}")
+        return problems
+    for d in details:
+        target = d.get("Target") or {}
+        attr = target.get("Attribute")
+        evaluation = d.get("Evaluation", "Static")
+        if evaluation == "Dynamic":
+            causing = d.get("CausingEntity") or ""
+            if (
+                allow_nested_dynamic
+                and d.get("ChangeSource") == "ResourceAttribute"
+                and causing.split(".", 1)[0] in nested_ok
+                and causing.split(".", 1)[0] in supplied_children
+            ):
+                continue
+            problems.append(
+                f"dynamic change to {attr}/{target.get('Name')} (caused by {causing or '?'})"
+            )
+            continue
+        if attr in POLICY_ATTRIBUTES:
+            continue
+        if (
+            attr == "Properties"
+            and target.get("Name") == "TemplateURL"
+            and rtype == NESTED_STACK_TYPE
+            and lid in nested_ok
+        ):
+            if target.get("RequiresRecreation") != "Never":
+                problems.append(
+                    f"TemplateURL change has RequiresRecreation={target.get('RequiresRecreation')}"
+                )
+            expected = nested_ok.get(lid)
+            after = target.get("AfterValue")
+            if expected is None or after is None:
+                problems.append(
+                    "TemplateURL new value cannot be verified: describe the change set with "
+                    "--include-property-values and pass the manifest"
+                )
+            elif after.strip('"') != expected:
+                problems.append(f"TemplateURL points at {after!r}, not the patched child")
+            continue
+        if attr == "Metadata" and allow_metadata_key and _metadata_only_ecsodus(d):
+            continue
+        problems.append(f"change to {attr}/{target.get('Name') or '-'} is not policy-only")
+    return problems

ecsodus/check/plan.py

@@ -0,0 +1,162 @@
+"""Terraform plan and state gates (PLAN §2.6, §13.5-6).
+
+Input is ``terraform show -json <planfile>``. An import is marked by a non-null
+``change.importing`` (its ``id`` is the physical ID being adopted); the ``actions`` array only
+ever holds no-op / create / read / update / delete / forget, so imports must be detected through
+``importing`` (council note §13.6).
+
+Both phases require the plan to cover exactly the manifest's import set:
+
+* **import**: every managed change is a pure import (``importing`` set, actions ``["no-op"]``) of
+  the physical ID the manifest expects at that address; nothing else.
+* **steady**: every expected address is present as a plain no-op (so a targeted or empty plan
+  cannot pass), and nothing else changes.
+
+ecsodus generates no data sources, so any data source in the plan fails: a data source can read
+secret material into state (e.g. ``aws_secretsmanager_secret_version``).
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass, field
+from typing import Any
+
+IMPORT = "import"
+STEADY = "steady"
+AWS_PROVIDER = "registry.terraform.io/hashicorp/aws"
+
+
+def _identity_matches(import_id: str, before: Any) -> bool:
+    """Does the refreshed object carry the physical ID it was imported from?
+
+    Import IDs are either a plain ID/ARN/name or a composite of several (``cluster/service``,
+    ``ZONE_name_TYPE``); every component must appear among the object's attribute values.
+    Without ``before`` (not in state) there is nothing to prove, which is a failure.
+    """
+    if not isinstance(before, dict):
+        return False
+    text = json.dumps(before, sort_keys=True).lower()
+    if import_id.lower() in text:
+        return True
+    parts = [p for p in re.split(r"[/_:|,]", import_id.lower()) if len(p) > 2]
+    return bool(parts) and all(p in text for p in parts)
+
+
+@dataclass
+class CheckResult:
+    ok: bool
+    errors: list[str] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+    summary: dict[str, int] = field(default_factory=dict)
+
+
+def _changes(plan: dict[str, Any]) -> list[dict[str, Any]]:
+    if "resource_changes" not in plan and "format_version" not in plan:
+        raise ValueError("not a `terraform show -json` plan document")
+    return list(plan.get("resource_changes") or [])
+
+
+def check_plan(
+    plan: dict[str, Any],
+    expected_imports: Mapping[str, str] | Iterable[str],
+    phase: str,
+    forgotten: Iterable[str] = (),
+) -> CheckResult:
+    """Gate a plan for ``phase``. ``expected_imports`` maps address -> physical import ID.
+
+    ``forgotten`` lists addresses being handed off with a ``removed { destroy = false }`` block
+    (the imported task-definition revision): in the steady phase exactly those may show the
+    ``forget`` action, and they are no longer required to be present.
+    """
+    forgotten_set = {a for a in forgotten if a.split(".", 1)[0] == "aws_ecs_task_definition"}
+    res_pre = [a for a in forgotten if a not in forgotten_set]
+    forget_seen: set[str] = set()
+    if phase not in (IMPORT, STEADY):
+        raise ValueError(f"unknown phase {phase!r}")
+    expected: dict[str, str | None] = (
+        dict(expected_imports)
+        if isinstance(expected_imports, Mapping)
+        else dict.fromkeys(expected_imports)
+    )
+    res = CheckResult(ok=True)
+    for a in res_pre:
+        res.errors.append(f"{a}: only aws_ecs_task_definition addresses can be --forgotten")
+    counts: dict[str, int] = {}
+    importing_seen: set[str] = set()
+    noop_seen: set[str] = set()
+    if plan.get("errored"):
+        res.errors.append("the plan errored")
+    for rc in _changes(plan):
+        address = rc.get("address", "?")
+        change = rc.get("change") or {}
+        actions = list(change.get("actions") or [])
+        importing = change.get("importing")
+        mode = rc.get("mode", "managed")
+        key = "+".join(actions) + ("+import" if importing else "")
+        counts[key] = counts.get(key, 0) + 1
+        if mode == "data":
+            res.errors.append(f"{address}: data sources are not allowed (ecsodus generates none)")
+            continue
+        if actions == ["forget"] and phase == STEADY and address in forgotten_set:
+            forget_seen.add(address)
+            continue
+        provider = rc.get("provider_name", AWS_PROVIDER)
+        if provider != AWS_PROVIDER:
+            res.errors.append(f"{address}: provider {provider} is not {AWS_PROVIDER}")
+            continue
+        if rc.get("type") and rc["type"] != address.split(".", 1)[0].split("[", 1)[0]:
+            res.errors.append(f"{address}: resource type {rc['type']} does not match the address")
+            continue
+        if actions != ["no-op"]:
+            verb = "/".join(actions) or "?"
+            what = "pure imports and no-ops" if phase == IMPORT else "a zero-change plan"
+            res.errors.append(f"{address}: {verb} — the {phase} phase allows only {what}")
+            continue
+        if importing:
+            if phase == STEADY:
+                res.errors.append(f"{address}: still importing in the steady phase")
+                continue
+            importing_seen.add(address)
+            want = expected.get(address)
+            got = (importing or {}).get("id")
+            if address in expected and want is not None and got != want:
+                res.errors.append(f"{address}: imports {got!r}, but the manifest expects {want!r}")
+        else:
+            want = expected.get(address)
+            if phase == STEADY and want and not _identity_matches(want, change.get("before")):
+                res.errors.append(
+                    f"{address}: the resource in state does not carry the manifest's ID {want!r}"
+                )
+                continue
+            noop_seen.add(address)
+    if phase == IMPORT:
+        for address in sorted(set(expected) - importing_seen):
+            res.errors.append(f"{address}: expected import is missing from the plan")
+        for address in sorted(importing_seen - set(expected)):
+            res.errors.append(f"{address}: plan imports an address ecsodus did not generate")
+    else:
+        for address in sorted(forgotten_set - forget_seen):
+            res.errors.append(f"{address}: --forgotten but the plan does not forget it")
+        for address in sorted(set(expected) - noop_seen - forget_seen):
+            res.errors.append(
+                f"{address}: missing from the steady plan (targeted or incomplete plan?)"
+            )
+    for dd in plan.get("resource_drift") or []:
+        res.warnings.append(f"{dd.get('address', '?')}: drift detected during refresh")
+    res.summary = counts
+    res.ok = not res.errors
+    return res
+
+
+def check_state(state_addresses: Iterable[str], expected_imports: Iterable[str]) -> CheckResult:
+    """Every import-fated address must be in ``terraform state list`` output."""
+    present = {a.strip() for a in state_addresses if a.strip()}
+    wanted = set(expected_imports)
+    missing = sorted(wanted - present)
+    res = CheckResult(ok=not missing)
+    res.errors = [f"{a}: not in Terraform state" for a in missing]
+    res.summary = {"expected": len(wanted), "present": len(present)}
+    return res