enginehall 2.0.0__py3-none-any.whl

pcba/adapters/altium_drive.py

@@ -0,0 +1,1160 @@
+"""Drive Altium Designer (and Altium Designer Develop) from an agent.
+
+Class C, like the CubeMX adapter: it operates a GUI application and can never run in CI or on
+the review path. Windows only, because Altium is.
+
+How a request runs
+------------------
+1. The packaged bridge library (`altium_bridge/bridge.pas`) is installed once per version
+   under `%LOCALAPPDATA%\\pcba\\altium-bridge\\<version>\\` and its SHA-256 is checked against
+   `altium_bridge/MANIFEST.json` before every request. A mismatch is reinstalled and reported,
+   never silently run.
+2. `altium_ops.render` turns typed operations into calls of bridge procedures with literal,
+   escaped arguments. The adapter writes `<library> + <generated body>` to the exchange folder
+   as `<id>.pas` and asks the running Altium to execute it with
+   `X2.EXE -RScriptingSystem:RunScriptFile(FileName=…|ProcName=Run)`. RunScriptFile reads the
+   file every time; a script *project* would run Altium's cached in-memory copy instead.
+3. The script writes `<id>.json` (via a temp file) and appends progress to `<id>.log`. A reply
+   whose id or bridge version differ is rejected.
+
+Failure handling, measured on Altium Designer Develop 26.10
+------------------------------------------------------------
+- Busy is not wedged. The first PCB document of a session blocks for ~35 s with no dialog;
+  progress lines tell the two apart, and recovery starts only when a modal dialog is present
+  or a hard ceiling passes.
+- A script error leaves the scripting engine paused in the debugger. Recovery: kill the hung
+  launcher processes, capture and close Altium's modal dialogs (they chain), dispatch
+  `X2.EXE -REditScript:Stop`, and prove it with a ping whose id must come back (~2 s).
+- Restarting Altium loses unsaved work, so the last rung runs only with `allow_restart`.
+
+The ceiling, stated plainly: this drives a desktop application in a logged-in session. It is a
+workstation tool, not a build step, and Altium's own checks (compile, DRC) remain the source of
+truth for Altium's documents.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+import subprocess
+import sys
+import time
+import uuid
+from dataclasses import dataclass, field
+from importlib import resources
+from typing import Any
+from pathlib import Path
+
+from pcba.adapters import altium_ops
+
+BRIDGE_PACKAGE = "pcba.adapters.altium_bridge"
+REGISTRY_ROOT = r"SOFTWARE\Altium\Builds"
+PING_TIMEOUT = 20.0
+DEFAULT_TIMEOUT = 120.0
+FIRST_PCB_GRACE = 90.0
+# Windows that disable the main window while Altium works and close by themselves, so they are no
+# Altium's exception box: an error inside Altium, not a question.
+ECO_ERROR_CLASSES = ("TShowException",)
+# prompt: Draftsman's "Updating Board Information" progress, shown while a drawing is published.
+# A real hang behind one still ends at the timeout.
+PROGRESS_TITLES = ("Draftsman",)
+# Request files Altium has not read yet must stay: a launcher that is still queued opens its
+# script later, and a deleted one raises "Cannot open file", one more modal per recovery round.
+# Leftovers are swept by age instead, when a session starts.
+EXCHANGE_KEEP_SECONDS = 24 * 3600
+DIALOG_IMAGE_KEEP_SECONDS = 7 * 24 * 3600
+MAX_ANSWERS = 20  # prompts one request may answer; a prompt that will not close must not loop forever
+ALTIUM_DOCUMENT_SUFFIXES = (".schdoc", ".pcbdoc", ".prjpcb", ".schlib", ".pcblib", ".outjob", ".bomdoc", ".pcbdwf",
+                            ".intlib", ".harness", ".prjpcbstructure")
+
+
+class DriveError(RuntimeError):
+    """A controlled failure while driving Altium. `code` is stable for agents."""
+
+    def __init__(self, code: str, message: str, detail: dict | None = None):
+        super().__init__(message)
+        self.code = code
+        self.detail = detail or {}
+
+    def to_dict(self) -> dict:
+        return {"code": self.code, "message": str(self), **({"detail": self.detail} if self.detail else {})}
+
+
+@dataclass(frozen=True, slots=True)
+class AltiumInstall:
+    exe: Path
+    version: str
+    product: str
+
+
+@dataclass(slots=True)
+class Reply:
+    ok: bool
+    items: list[dict]
+    error: str = ""
+    failed_op: int | None = None
+    failed_name: str = ""
+    seconds: float = 0.0
+    recovery: dict | None = None
+    log_tail: list[str] = field(default_factory=list)
+    answered: list[dict] = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        out = {"ok": self.ok, "seconds": round(self.seconds, 3), "items": self.items}
+        if not self.ok:
+            out.update(error=self.error, failed_op=self.failed_op, failed_name=self.failed_name)
+            out["log_tail"] = self.log_tail
+        if self.answered:
+            out["answered"] = self.answered
+        if self.recovery:
+            out["recovery"] = self.recovery
+        return out
+
+
+# --- locating Altium ---------------------------------------------------------------------
+
+
+SCREENSHOT_MIN_CONTENT = 0.01  # share of pixels that must differ from the background colour
+SCREENSHOT_FALLBACK = ("altium_outputs renders off-screen and works while the session is locked: "
+                       "outputs ['schematic_pdf'] for the sheets, ['pcb_3d'] for the board")
+# Situs can run for many minutes at only 0.15-0.25 of a core on a constrained board, and a short
+# dip below that is not the end: a save attempted then fails with "a command is currently active".
+AUTOROUTE_IDLE_CPU = 0.08     # CPU seconds per wall second, above Altium's own load, that count as busy
+AUTOROUTE_BASELINE_SECONDS = 3.0  # how long Altium's own load (view redraws) is sampled before routing
+AUTOROUTE_IDLE_SECONDS = 15   # consecutive idle seconds that mean Situs has finished
+AUTOROUTE_MIN_SECONDS = 4.0   # Situs never finishes faster than this, even on a tiny board
+
+
+def preflight() -> None:
+    if sys.platform != "win32":
+        raise DriveError(
+            "platform",
+            "Driving Altium is Windows-only, because Altium Designer is. Read schematics on any "
+            "platform with `enginehall altium netlist` or `enginehall altium pinmap` instead.",
+        )
+
+
+def _registry_installs() -> list[AltiumInstall]:  # pragma: no cover - Windows registry
+    import winreg
+
+    found = []
+    try:
+        root = winreg.OpenKey(winreg.HKEY_LOCAL_MACHINE, REGISTRY_ROOT)
+    except OSError:
+        return found
+    with root:
+        index = 0
+        while True:
+            try:
+                name = winreg.EnumKey(root, index)
+            except OSError:
+                break
+            index += 1
+            try:
+                with winreg.OpenKey(root, name) as key:
+                    folder = winreg.QueryValueEx(key, "ProgramsInstallPath")[0]
+                    version = str(winreg.QueryValueEx(key, "Version")[0])
+            except OSError:
+                continue
+            exe = Path(folder) / "X2.EXE"
+            if exe.is_file():
+                found.append(AltiumInstall(exe, version, name.split(" {")[0]))
+    return found
+
+
+def _version_key(version: str) -> tuple:
+    return tuple(int(p) if p.isdigit() else 0 for p in version.split("."))
+
+
+def find_altium(explicit: str | None = None) -> AltiumInstall:
+    """`explicit`, then `PCBA_ALTIUM_EXE`, then the newest registered build."""
+    for candidate in (explicit, os.environ.get("PCBA_ALTIUM_EXE")):
+        if candidate:
+            path = Path(candidate)
+            if not path.is_file():
+                raise DriveError("altium-not-found", f"X2.EXE not found at {path}")
+            return AltiumInstall(path, "unknown", "explicit")
+    installs = _registry_installs()
+    if not installs:
+        raise DriveError(
+            "altium-not-found",
+            f"No Altium build registered under HKLM\\{REGISTRY_ROOT}. Pass the path to X2.EXE "
+            "or set PCBA_ALTIUM_EXE.",
+        )
+    return max(installs, key=lambda i: _version_key(i.version))
+
+
+# --- bridge installation -------------------------------------------------------------------
+
+
+def packaged_bridge() -> tuple[str, dict]:
+    package = resources.files(BRIDGE_PACKAGE)
+    source = package.joinpath("bridge.pas").read_text(encoding="utf-8")
+    manifest = json.loads(package.joinpath("MANIFEST.json").read_text(encoding="utf-8"))
+    return source, manifest
+
+
+def sha256_text(text: str) -> str:
+    """SHA-256 of `text` as UTF-8 with its line endings normalised to LF, as MANIFEST.json
+    records it. A Windows checkout with `core.autocrlf` writes the bridge with CRLF; the hash
+    must not depend on that, nor on whether the caller read the file in text mode."""
+    normalised = text.replace("\r\n", "\n").replace("\r", "\n")
+    return hashlib.sha256(normalised.encode("utf-8")).hexdigest()
+
+
+def remanifest() -> dict:
+    """Developer tool: after editing bridge.pas, write MANIFEST.json for it (the version is read
+    from BRIDGE_VERSION in the file, so the two cannot drift). Every session refuses a bridge whose
+    hash differs from its manifest; this replaces the hand-run hash that each bridge edit needed."""
+    package = Path(str(resources.files(BRIDGE_PACKAGE)))
+    source = (package / "bridge.pas").read_text(encoding="utf-8")
+    found = re.search(r"BRIDGE_VERSION = '([^']+)'", source)
+    if not found:
+        raise DriveError("bridge-version", "bridge.pas declares no BRIDGE_VERSION")
+    manifest = {"version": found.group(1), "sha256": sha256_text(source), "file": "bridge.pas"}
+    (package / "MANIFEST.json").write_text(json.dumps(manifest, indent=2) + "\n", encoding="utf-8", newline="\n")
+    return manifest
+
+
+def default_home() -> Path:
+    base = os.environ.get("PCBA_ALTIUM_HOME") or os.environ.get("LOCALAPPDATA") or str(Path.home())
+    return Path(base) / "pcba" / "altium-bridge"
+
+
+def install_bridge(home: Path) -> dict:
+    """Install the packaged bridge for its version and verify it. Returns the install record."""
+    source, manifest = packaged_bridge()
+    actual = sha256_text(source)
+    if actual != manifest["sha256"]:
+        raise DriveError(
+            "bridge-hash",
+            "the packaged bridge does not match its manifest; reinstall enginehall",
+            {"expected": manifest["sha256"], "actual": actual},
+        )
+    folder = home / manifest["version"]
+    target = folder / "bridge.pas"
+    reinstalled = False
+    if not target.is_file() or sha256_text(target.read_text(encoding="utf-8")) != actual:
+        folder.mkdir(parents=True, exist_ok=True)
+        target.write_text(source, encoding="utf-8")
+        reinstalled = True
+    return {
+        "version": manifest["version"],
+        "sha256": actual,
+        "path": str(target),
+        "reinstalled": reinstalled,
+    }
+
+
+def load_installed(record: dict) -> str:
+    text = Path(record["path"]).read_text(encoding="utf-8")
+    if sha256_text(text) != record["sha256"]:
+        raise DriveError("bridge-hash", "the installed bridge changed on disk", record)
+    return text
+
+
+# --- single-instance lock ------------------------------------------------------------------
+
+
+def _pid_alive(pid: int) -> bool:
+    if pid <= 0:
+        return False
+    if sys.platform == "win32":  # pragma: no cover
+        import ctypes
+
+        handle = ctypes.windll.kernel32.OpenProcess(0x1000, False, pid)
+        if not handle:
+            return False
+        code = ctypes.c_ulong()
+        ctypes.windll.kernel32.GetExitCodeProcess(handle, ctypes.byref(code))
+        ctypes.windll.kernel32.CloseHandle(handle)
+        return code.value == 259  # STILL_ACTIVE
+    try:
+        os.kill(pid, 0)
+    except OSError:
+        return False
+    return True
+
+
+class Lock:
+    """One request at a time per Altium instance; Altium itself rejects a second script with a
+    blocking dialog. A lock left by a dead process is taken over and reported."""
+
+    def __init__(self, path: Path, wait: float = 30.0):
+        self.path = path
+        self.wait = wait
+        self.stale_taken = False
+
+    def __enter__(self):
+        deadline = time.monotonic() + self.wait
+        while True:
+            try:
+                fd = os.open(self.path, os.O_CREAT | os.O_EXCL | os.O_WRONLY)
+            except FileExistsError:
+                try:
+                    owner = json.loads(self.path.read_text(encoding="utf-8"))
+                except (OSError, ValueError):
+                    owner = {"pid": -1}
+                if not _pid_alive(int(owner.get("pid", -1))):
+                    self.path.unlink(missing_ok=True)
+                    self.stale_taken = True
+                    continue
+                if time.monotonic() > deadline:
+                    raise DriveError("busy", "another pcba session is driving Altium", owner)
+                time.sleep(0.2)
+                continue
+            with os.fdopen(fd, "w", encoding="utf-8") as handle:
+                json.dump({"pid": os.getpid(), "since": time.time()}, handle)
+            return self
+
+    def __exit__(self, *exc):
+        self.path.unlink(missing_ok=True)
+
+
+# --- the session ---------------------------------------------------------------------------
+
+
+class Session:
+    """Everything needed to run bridge requests against one Altium installation.
+
+    `launcher` and `win` are injectable so the protocol, the lock, timeouts and the recovery
+    ladder are testable without Altium (see tests/test_altium_drive.py).
+    """
+
+    def __init__(
+        self,
+        exe: str | None = None,
+        home: Path | None = None,
+        launcher=None,
+        win=None,
+        allow_restart: bool = False,
+        uia=None,
+    ):
+        self.home = Path(home) if home else default_home()
+        self.exchange = self.home / "exchange"
+        self.exchange.mkdir(parents=True, exist_ok=True)
+        self.allow_restart = allow_restart
+        self._exe = exe
+        self._install: AltiumInstall | None = None
+        self._launcher = launcher
+        self._win = win
+        self._uia = uia
+        self.bridge = install_bridge(self.home)
+        self.swept = sweep_exchange(self.exchange)
+
+    # -- environment -----------------------------------------------------------------------
+
+    @property
+    def install(self) -> AltiumInstall:
+        if self._install is None:
+            preflight()
+            self._install = find_altium(self._exe)
+        return self._install
+
+    @property
+    def win(self):
+        if self._win is None:
+            from pcba.adapters import altium_win32
+
+            self._win = altium_win32
+        return self._win
+
+    @property
+    def uia(self):
+        if self._uia is None:
+            from pcba.adapters import altium_uia
+
+            self._uia = altium_uia
+        return self._uia
+
+    def launch(self, process: str) -> subprocess.Popen:
+        if self._launcher is not None:
+            return self._launcher(process)
+        return subprocess.Popen(f'"{self.install.exe}" -R{process}')
+
+    def running(self) -> bool:
+        return bool(self.win.main_instances())
+
+    def status(self) -> dict:
+        info = {"bridge": self.bridge, "exchange": str(self.exchange)}
+        try:
+            install = self.install
+            info["altium"] = {"exe": str(install.exe), "version": install.version, "product": install.product}
+            info["running"] = self.running()
+        except DriveError as exc:
+            info["altium"] = exc.to_dict()
+            info["running"] = False
+        return info
+
+    # -- one request -----------------------------------------------------------------------
+
+    def run(self, ops: list[dict], timeout: float = DEFAULT_TIMEOUT, answers: list[dict] | None = None) -> Reply:
+        """Validate, render and execute operations in one Altium script.
+
+        `answers` are the prompts this request may answer (see `altium_ops.prompt_answers`, the
+        default); any other dialog is captured and cancelled, as before. File paths are sent in
+        Windows form (`altium_ops.normalise_paths`)."""
+        ops = altium_ops.normalise_paths(ops) if isinstance(ops, list) else ops
+        body = altium_ops.render(ops)
+        rules = altium_ops.prompt_answers(ops) if answers is None else answers
+        with Lock(self.exchange / "altium.lock"):
+            return self._run_locked(body, timeout, rules)
+
+    def _run_locked(self, body: str, timeout: float, rules: list[dict] | None = None) -> Reply:
+        rules = rules or []
+        answered: list[dict] = []
+        if self._dialog_present():
+            # Launching into a modal Altium only queues the request behind it (and Altium may
+            # say "another instance is running, but it is busy"). Answer what this request may
+            # answer; anything else belongs to someone else, so stop here and say what it is.
+            answered = self.answer_prompts(rules)
+            if self._dialog_present():
+                raise DriveError("busy-modal", "Altium shows a dialog this request may not answer; "
+                                 "read it, answer it, or run altium_recover",
+                                 {"dialogs": self.read_dialogs(), "answered": answered})
+        library = load_installed(self.bridge)
+        request_id = uuid.uuid4().hex[:12]
+        script = self.exchange / f"{request_id}.pas"
+        response = self.exchange / f"{request_id}.json"
+        log = self.exchange / f"{request_id}.log"
+        exchange_literal = altium_ops.pascal_string(str(self.exchange) + "\\")
+        script.write_text(
+            library
+            + "\n\n"
+            + body
+            + "\n\nprocedure Run;\nbegin\n"
+            + f"    Init({altium_ops.pascal_string(request_id)}, {exchange_literal});\n"
+            + "    try\n        Body;\n        Complete;\n    except\n"
+            + "        Finish('Altium raised an error: ' + ExceptionMessage);\n    end;\nend;\n",
+            encoding="utf-8",
+        )
+        started = time.monotonic()
+        if not self.running() and self._launcher is None:
+            if not self.allow_restart:
+                raise DriveError(
+                    "not-running",
+                    "Altium is not running. Start it, or allow pcba to start it.",
+                )
+        process = self.launch(f'ScriptingSystem:RunScriptFile(FileName="{script}"|ProcName="Run")')
+        reply = self._await(response, log, process, request_id, started, timeout, rules)
+        reply.answered = answered + reply.answered
+        for path in (script, log):
+            if reply.ok:
+                path.unlink(missing_ok=True)
+        response.unlink(missing_ok=True)
+        return reply
+
+    def _await(self, response, log, process, request_id, started, timeout, rules=None) -> Reply:
+        last_progress = started
+        last_size = -1
+        recovery = None
+        answered: list[dict] = []
+        while True:
+            if response.is_file():
+                try:
+                    data = json.loads(response.read_text(encoding="utf-8-sig"))
+                except ValueError:
+                    time.sleep(0.05)
+                    continue
+                reply = self._reply(data, request_id, started, log, recovery)
+                # A prompt after the reply is the request's business only if a rule covers it;
+                # either way the reply stands: the script did finish.
+                answered += self.answer_prompts(rules or [])
+                leftovers = self.close_dialogs()
+                if leftovers:
+                    reply.recovery = {"deferred_dialogs": leftovers}
+                reply.answered = answered
+                return reply
+            now = time.monotonic()
+            size = log.stat().st_size if log.is_file() else -1
+            if size != last_size:
+                last_size, last_progress = size, now
+            stuck_dialog = self._dialog_present()
+            if stuck_dialog and rules and len(answered) < MAX_ANSWERS:
+                done = self.answer_prompts(rules)
+                answered += done
+                if any(d["pressed"] for d in done):
+                    last_progress = time.monotonic()
+                    continue
+            if stuck_dialog:
+                # A prompt can appear just as the script finishes; give the reply a moment.
+                time.sleep(1.5)
+                if response.is_file():
+                    continue
+            idle = now - last_progress
+            if stuck_dialog or idle > timeout or now - started > timeout + FIRST_PCB_GRACE:
+                recovery = self.recover()
+                tail = log.read_text(encoding="utf-8", errors="replace").splitlines()[-8:] if log.is_file() else []
+                return Reply(
+                    ok=False,
+                    items=[],
+                    error="Altium stopped the script" if stuck_dialog else "Altium did not answer in time",
+                    seconds=now - started,
+                    recovery=recovery,
+                    log_tail=tail,
+                    answered=answered,
+                )
+            time.sleep(0.1)
+
+    # -- dialogs ---------------------------------------------------------------------------
+
+    def read_dialog(self, dialog) -> dict:
+        """What a dialog says, read through UI Automation (WPF, VCL and standard boxes alike),
+        with the Win32 text as a fallback. Painted VCL text stays unreadable: capture it."""
+        entry = {"class": dialog.cls[:40], "title": dialog.title}
+        try:
+            reading = self.uia.describe(dialog.hwnd).to_dict()
+            entry.update({k: v for k, v in reading.items() if k != "title" and v})
+        except OSError as exc:
+            entry["uia_error"] = str(exc)
+        win32_text = self.win.dialog_text(dialog.hwnd)
+        if win32_text and not entry.get("texts"):
+            entry["texts"] = win32_text.splitlines()
+        entry["text"] = "\n".join(entry.get("texts", []))
+        return entry
+
+    def _capture_dialog(self, dialog) -> str | None:
+        shots = self.exchange / "dialogs"
+        shots.mkdir(exist_ok=True)
+        shot = shots / f"{uuid.uuid4().hex[:8]}.png"
+        try:
+            self.win.capture(dialog.hwnd, shot)
+        except OSError:
+            return None
+        return str(shot)
+
+    def read_dialogs(self) -> list[dict]:
+        main = self.win.main_instances()
+        return [self.read_dialog(d) for d in self.win.dialogs(main)] if main else []
+
+    def answer_prompts(self, rules: list[dict]) -> list[dict]:
+        """Answer each present dialog that a rule covers, by its buttons' captions. Returns what was
+        answered. Dialogs no rule covers are left alone (the caller captures and cancels them)."""
+        main = self.win.main_instances()
+        if not main or not rules:
+            return []
+        answered = []
+        for dialog in self.win.dialogs(main):
+            if dialog.title in PROGRESS_TITLES:
+                continue
+            reading = self.read_dialog(dialog)
+            rule = matching_rule(rules, reading)
+            if rule is None:
+                continue
+            for box in rule.get("uncheck", []):
+                try:
+                    self.uia.set_checked(dialog.hwnd, box, False)
+                except OSError:
+                    pass  # no such box: nothing to clear
+            pressed: list[str] = []
+            closed = False
+            for step in rule["press"]:
+                choices = [step] if isinstance(step, str) else list(step)
+                done = None
+                for button in choices:
+                    try:
+                        if self.uia.press(dialog.hwnd, button):
+                            done = button
+                            break
+                    except OSError:
+                        # The dialog closed under us: an earlier press answered it (a "Save None"
+                        # that also confirms), or it was never there.
+                        closed = bool(pressed)
+                        break
+                if done is None:
+                    break
+                pressed.append(done)
+                time.sleep(0.4)
+            answered.append({"title": reading["title"], "texts": reading.get("texts", []), "pressed": pressed,
+                             "complete": closed or len(pressed) == len(rule["press"])})
+            time.sleep(0.4)
+        return answered
+
+    def close_dialogs(self) -> list[dict]:
+        """Read, capture and cancel any modal dialog of the main instance (WM_CLOSE = Cancel)."""
+        main = self.win.main_instances()
+        closed = []
+        if not main:
+            return closed
+        shots = self.exchange / "dialogs"
+        for _attempt in range(4):
+            found = [d for d in self.win.dialogs(main) if d.title not in PROGRESS_TITLES]
+            if not found:
+                break
+            for dialog in found:
+                entry = self.read_dialog(dialog)
+                shots.mkdir(exist_ok=True)
+                shot = shots / f"{uuid.uuid4().hex[:8]}.png"
+                try:
+                    self.win.capture(dialog.hwnd, shot)
+                    entry["image"] = str(shot)
+                except OSError as exc:  # the dialog is still closed and reported; only its picture is missing
+                    entry["image_error"] = str(exc)
+                self.win.close(dialog.hwnd)
+                closed.append(entry)
+            time.sleep(0.4)
+        return closed
+
+    def _dialog_present(self) -> bool:
+        main = self.win.main_instances()
+        return bool(main and [d for d in self.win.dialogs(main) if d.title not in PROGRESS_TITLES])
+
+    def _reply(self, data: dict, request_id: str, started: float, log: Path, recovery) -> Reply:
+        if data.get("id") != request_id:
+            raise DriveError("protocol", "reply id does not match the request", {"reply": data.get("id")})
+        if data.get("bridge") != self.bridge["version"]:
+            raise DriveError(
+                "bridge-version",
+                "Altium ran a different bridge version than the one installed",
+                {"reply": data.get("bridge"), "installed": self.bridge["version"]},
+            )
+        tail = []
+        if not data.get("ok") and log.is_file():
+            tail = log.read_text(encoding="utf-8", errors="replace").splitlines()[-8:]
+        return Reply(
+            ok=bool(data.get("ok")),
+            items=data.get("items", []),
+            error=data.get("error", ""),
+            failed_op=data.get("failed_op"),
+            failed_name=data.get("failed_name", ""),
+            seconds=time.monotonic() - started,
+            recovery=recovery,
+            log_tail=tail,
+        )
+
+    # -- recovery --------------------------------------------------------------------------
+
+    def recover(self, rounds: int = 4) -> dict:
+        """Clear a paused script engine without a person; prove it with a ping."""
+        record: dict = {"rounds": [], "verified": False}
+        shots = self.exchange / "dialogs"
+        shots.mkdir(exist_ok=True)
+        t0 = time.monotonic()
+        for _ in range(rounds):
+            step: dict = {"killed": [], "dialogs": []}
+            for pid in self.win.launchers():
+                if self.win.kill(pid):
+                    step["killed"].append(pid)
+            main = self.win.main_instances()
+            for _attempt in range(6):  # a parse error raises two dialogs in sequence
+                found = [d for d in self.win.dialogs(main) if d.title not in PROGRESS_TITLES] if main else []
+                if not found:
+                    break
+                for dialog in found:
+                    entry = self.read_dialog(dialog)
+                    shot = shots / f"{uuid.uuid4().hex[:8]}.png"
+                    try:
+                        self.win.capture(dialog.hwnd, shot)
+                        entry["image"] = str(shot)
+                    except OSError as exc:  # recovery goes on; only the dialog's picture is missing
+                        entry["image_error"] = str(exc)
+                    self.win.close(dialog.hwnd)
+                    step["dialogs"].append(entry)
+                time.sleep(0.4)
+            stopper = self.launch("EditScript:Stop")
+            try:
+                step["stop"] = stopper.wait(timeout=8)
+            except subprocess.TimeoutExpired:
+                step["stop"] = "hung"
+                stopper.kill()
+            record["rounds"].append(step)
+            if step["stop"] == 0 and self._ping():
+                record["verified"] = True
+                break
+        if not record["verified"]:
+            killed = any(step["killed"] for step in record["rounds"])
+            dialogs = any(step["dialogs"] for step in record["rounds"])
+            if killed and not dialogs:
+                # Altium's window answers but no script request reaches it: the launchers queue
+                # and hang. Seen after a long session; pinging again only adds hung launchers.
+                record["diagnosis"] = ("command-channel-stuck: Altium takes no script request and shows no "
+                                       "dialog; only a restart helps (altium_recover with allow_restart)")
+            elif dialogs:
+                record["diagnosis"] = ("dialogs-keep-coming: every round met a new dialog; read the captures "
+                                       "(a queued request may refer to a removed file)")
+        if not record["verified"] and self.allow_restart:
+            record["restart"] = self.restart()
+            record["verified"] = self._ping(timeout=PING_TIMEOUT * 3)
+            if record["verified"]:
+                record["restart"]["projects"] = self.open_projects()
+        record["seconds"] = round(time.monotonic() - t0, 3)
+        return record
+
+    def open_projects(self) -> list[str]:
+        """The projects Altium has open (it reopens its last project group after a restart)."""
+        try:
+            reply = self._run_locked(altium_ops.render([{"op": "project_state"}]), PING_TIMEOUT)
+        except DriveError:
+            return []
+        return [i["project"] for i in reply.items if i.get("kind") == "project"] if reply.ok else []
+
+    def _ping(self, timeout: float = PING_TIMEOUT, library: bool = False) -> bool:
+        """Prove the scripting engine answers. By default a tiny standalone script, so a broken
+        library cannot make a healthy engine look wedged."""
+        request_id = "ping" + uuid.uuid4().hex[:8]
+        script = self.exchange / f"{request_id}.pas"
+        response = self.exchange / f"{request_id}.json"
+        target = altium_ops.pascal_string(str(response))
+        if library:
+            init = (
+                f"    Init({altium_ops.pascal_string(request_id)}, "
+                f"{altium_ops.pascal_string(str(self.exchange) + chr(92))});"
+            )
+            text = "\n".join([load_installed(self.bridge), "", "procedure Run;", "begin", init,
+                              "    Finish('');", "end;", ""])
+        else:
+            payload = altium_ops.pascal_string('{"id":"' + request_id + '"}')
+            text = "\n".join([
+                "procedure Run;",
+                "var SL: TStringList;",
+                "begin",
+                "    SL := TStringList.Create;",
+                f"    SL.Text := {payload};",
+                f"    SL.SaveToFile({target});",
+                "    SL.Free;",
+                "end;",
+                "",
+            ])
+        script.write_text(text, encoding="utf-8")
+        self.launch(f'ScriptingSystem:RunScriptFile(FileName="{script}"|ProcName="Run")')
+        deadline = time.monotonic() + timeout
+        answered = False
+        try:
+            while time.monotonic() < deadline:
+                if response.is_file():
+                    try:
+                        answered = json.loads(response.read_text(encoding="utf-8-sig")).get("id") == request_id
+                        return answered
+                    except ValueError:
+                        pass  # the bridge is still writing the reply: read it again on the next round
+                if self._dialog_present():
+                    return False
+                time.sleep(0.1)
+            return False
+        finally:
+            # The script stays until Altium has run it: a queued launcher opens it later, and a
+            # missing file raises "Cannot open file", which looks like a new hang. The sweep at
+            # session start removes leftovers by age.
+            leftovers = (response, self.exchange / f"{request_id}.log") + ((script,) if answered else ())
+            for path in leftovers:
+                path.unlink(missing_ok=True)
+
+    def ping(self) -> dict:
+        t0 = time.monotonic()
+        with Lock(self.exchange / "altium.lock"):
+            engine = self._ping()
+            bridge = self._ping(library=True) if engine else False
+        return {"ok": engine and bridge, "engine": engine, "bridge": bridge,
+                "seconds": round(time.monotonic() - t0, 3)}
+
+    def restart(self) -> dict:
+        """Kill Altium and start it again. Loses unsaved work; callers must opt in."""
+        killed = []
+        for pid in list(self.win.main_instances()) + list(self.win.launchers()):
+            if self.win.kill(pid):
+                killed.append(pid)
+        time.sleep(1.0)
+        subprocess.Popen(f'"{self.install.exe}"')
+        deadline = time.monotonic() + 180
+        while time.monotonic() < deadline and not self.running():
+            time.sleep(1.0)
+        return {"killed": killed, "running": self.running()}
+
+    # -- dialog-driven Altium functions ------------------------------------------------------
+
+    def wait_dialog(self, form_class: str, timeout: float = 60.0):
+        """The first window of `form_class`, looked for at least once (a zero timeout is a single look)."""
+        deadline = time.monotonic() + timeout
+        while True:
+            main = self.win.main_instances()
+            for window in self.win.top_windows(main):
+                if window.cls == form_class:
+                    return window
+            if time.monotonic() >= deadline:
+                return None
+            time.sleep(0.2)
+
+    def wait_eco_form(self, timeout: float):
+        """Wait for the ECO form. Altium may first ask how to link unlinked components ("Component
+        Links"); closing that question lets it match by designator and go on to the ECO."""
+        deadline = time.monotonic() + timeout
+        while time.monotonic() < deadline:
+            form = self.wait_dialog("TChangeManagementForm", timeout=0.5)
+            if form is not None:
+                return form
+            for d in self.win.dialogs(self.win.main_instances()):
+                if d.title == "Component Links":
+                    self.win.close(d.hwnd)
+        return None
+
+    def update_pcb(self, project: str, pcb: str, timeout: float = 120.0, reopen: bool = True) -> dict:
+        """Run Altium's own ECO (Design > Import Changes) and report its log.
+
+        The ECO dialog is driven by message; the result is read from the ECO log Altium writes
+        under `Project Logs for <project>`, never inferred from the click.
+        """
+        project_dir = Path(project).parent
+        logs = project_dir / f"Project Logs for {Path(project).stem}"
+        before = {p: p.stat().st_mtime for p in logs.glob("*.LOG")} if logs.is_dir() else {}
+        reply = self.run([{"op": "project_open", "path": project}, {"op": "pcb_open", "path": pcb},
+                          {"op": "pcb_components"}, {"op": "doc_focus", "kind": "PCB", "path": pcb}])
+        if not reply.ok:
+            return {"ok": False, "stage": "open", **reply.to_dict()}
+        parts_before = _designators(reply.items)
+        interrupted: list[dict] = []
+        with Lock(self.exchange / "altium.lock"):
+            self.launch("WorkspaceManager:Compare(ObjectKind=Project|Action=UpdateMe)").wait(timeout=30)
+            form = self.wait_eco_form(timeout)
+            if form is None:
+                main = self.win.main_instances()
+                found = []
+                for d in self.win.dialogs(main):
+                    entry = {"class": d.cls, "title": d.title, "text": self.win.dialog_text(d.hwnd)}
+                    if d.cls in ECO_ERROR_CLASSES:
+                        entry["image"] = self._capture_dialog(d)  # the exception text is painted
+                    found.append(entry)
+                    self.win.close(d.hwnd)
+                stale = any(d["title"].startswith("Comparator Results (No Differences)") for d in found)
+                if stale and reopen:
+                    pass  # retried below, outside the lock
+                elif any(d["class"] in ECO_ERROR_CLASSES for d in found):
+                    # Measured: a rule whose scope Altium cannot parse (InNetClas(LED)) raises an
+                    # exception box as soon as the comparison starts, before any ECO form (#41).
+                    return {"ok": False, "stage": "eco-error", "dialogs": found,
+                            "note": "Altium raised an error before the ECO; most often a board rule whose scope it "
+                                    "cannot parse. Read pcb_rules (descriptor), fix or delete that rule, run the ECO "
+                                    "again"}
+                else:
+                    return {"ok": False, "stage": "eco-dialog", "dialogs": found,
+                            "note": "Altium raised no ECO dialog; usually nothing to change, "
+                                    "or the PCB is not in the project"}
+            else:
+                stale = False
+            if not stale:
+                self.win.click_button(form, "Execute Changes")
+                time.sleep(3.0)
+                # A change Altium cannot make (a rule whose scope it cannot parse, #41) raises a
+                # script-error dialog in the middle of the ECO; what ran before it stays applied.
+                # The ECO form itself is listed among the dialogs (measured); only another one is
+                # an interruption.
+                main = self.win.main_instances()
+                for _round in range(6):  # closing one error box can open the next
+                    others = [d for d in self.win.dialogs(main) if d.cls != "TChangeManagementForm"]
+                    if not others:
+                        break
+                    for d in others:
+                        interrupted.append({"class": d.cls, "title": d.title, "text": self.win.dialog_text(d.hwnd)})
+                        self.win.close(d.hwnd)
+                if self.wait_dialog("TChangeManagementForm", timeout=0) is not None:
+                    self.win.click_button(form, "Close")
+                deadline = time.monotonic() + 30
+                while time.monotonic() < deadline and self.wait_dialog("TChangeManagementForm", timeout=0.5):
+                    time.sleep(0.5)
+        if stale:
+            # "No Differences" from a project whose sheets were created in this session usually
+            # means Altium's in-memory project is stale; reopen it and compare once more.
+            self.run([{"op": "project_close", "path": project}, {"op": "project_open", "path": project}])
+            result = self.update_pcb(project, pcb, timeout, reopen=False)
+            result["reopened"] = True
+            return result
+        new_logs = []
+        if logs.is_dir():
+            new_logs = [p for p in logs.glob("*.LOG") if before.get(p) != p.stat().st_mtime]
+        lines = []
+        for path in sorted(new_logs):
+            lines += path.read_text(encoding="utf-8", errors="replace").splitlines()
+        result: dict[str, Any] = {"ok": bool(lines) and not interrupted, "log": [str(p) for p in new_logs],
+                                  "changes": lines}
+        after = self.run([{"op": "pcb_open", "path": pcb}, {"op": "pcb_components"}])
+        if after.ok:
+            parts_after = _designators(after.items)
+            result["components"] = {"before": len(parts_before), "after": len(parts_after),
+                                    "added": sorted(parts_after - parts_before),
+                                    "removed": sorted(parts_before - parts_after)}
+        if interrupted:
+            result["stage"] = "eco-interrupted"
+            result["interrupted_by"] = interrupted
+            result["note"] = ("a dialog interrupted the ECO; changes made before it stay on the board. "
+                              "`components` shows what the board holds now; fix the cause and run the ECO again")
+        return result
+
+    def run_drc(self, project: str, pcb: str, timeout: float = 300.0) -> dict:
+        """Run Altium's DRC from its own dialog and parse the text report it writes."""
+        outputs = Path(project).parent / f"Project Outputs for {Path(project).stem}"
+        report = outputs / f"Design Rule Check - {Path(pcb).stem}.drc"
+        before = report.stat().st_mtime if report.is_file() else None
+        reply = self.run([{"op": "project_open", "path": project}, {"op": "doc_focus", "kind": "PCB", "path": pcb}])
+        if not reply.ok:
+            return {"ok": False, "stage": "open", **reply.to_dict()}
+        with Lock(self.exchange / "altium.lock"):
+            self.launch("PCB:DesignRuleCheck").wait(timeout=30)
+            form = self.wait_dialog("TDesignRuleCheckForm", timeout=60)
+            if form is None:
+                return {"ok": False, "stage": "drc-dialog"}
+            self.win.click_button(form, "Run Design Rule Check...")
+            deadline = time.monotonic() + timeout
+            repoured = False
+            while time.monotonic() < deadline:
+                if report.is_file() and report.stat().st_mtime != before:
+                    time.sleep(0.5)
+                    break
+                # Altium warns that unpoured polygons make the result wrong; take its own
+                # recommendation instead of checking a stale board.
+                prompt = next((d for d in self.win.dialogs(self.win.main_instances())
+                               if d.title == "Design Rule Check"), None)
+                if prompt is not None and not repoured:
+                    self.win.click_button(prompt, "Repour Polygons and Run DRC")
+                    repoured = True
+                time.sleep(0.5)
+            else:
+                return {"ok": False, "stage": "drc-report", "report": str(report)}
+        parsed = parse_drc(report.read_text(encoding="utf-8", errors="replace"))
+        result = {"ok": parsed["violations"] is not None, "report": str(report), **parsed}
+        if parsed["violations"] is None:
+            result["error"] = "the DRC report has no violation count; it was not read"
+        if repoured:
+            result["repoured"] = True
+        return result
+
+    def autoroute(self, project: str, pcb: str, timeout: float = 600.0, ripup_violations: bool = False,
+                  lock_preroutes: bool = False) -> dict:
+        """Run Situs (Route > Auto Route > All) with its default strategy for the board (Default
+        Multi Layer Board on a board with inner layers). Situs follows the board's routing rules:
+        widths, via style, routing layers, corners, topology and priority.
+
+        `ripup_violations` and `lock_preroutes` set the two check boxes of the Situs dialog: rip
+        up whatever still violates a rule after routing (left unrouted, for DRC to report), and
+        lock every existing track first. Locked primitives (pcb_track/pcb_via with locked=true)
+        are always left alone. Completion is judged by Altium's CPU load falling back to what it
+        was before routing and the scripting engine answering again; DRC, not this call, proves
+        the result.
+        """
+        reply = self.run([{"op": "project_open", "path": project}, {"op": "doc_focus", "kind": "PCB", "path": pcb}])
+        if not reply.ok:
+            return {"ok": False, "stage": "open", **reply.to_dict()}
+        with Lock(self.exchange / "altium.lock"):
+            self.launch("PCB:AutoRoute(Mode=All)").wait(timeout=30)
+            form = self.wait_dialog("TSitusSetup", timeout=60)
+            if form is None:
+                return {"ok": False, "stage": "situs-dialog", "dialogs": self.close_dialogs()}
+            for caption, wanted in (("Rip-up Violations After Routing", ripup_violations),
+                                    ("Lock All Pre-routes", lock_preroutes)):
+                if not self.win.set_check(form, caption, wanted):
+                    self.win.click_button(form, "Cancel")
+                    return {"ok": False, "stage": "situs-options", "option": caption}
+            # Situs routes with the main window enabled and no dialog, so window state says
+            # nothing; it is CPU-bound, so "done" is Altium's CPU time falling back to the load it
+            # carried before routing (a PCB view that keeps redrawing never goes fully idle).
+            pid = next(iter(self.win.main_instances()), None)
+            base_cpu = self.win.cpu_seconds(pid) if pid else 0.0
+            time.sleep(AUTOROUTE_BASELINE_SECONDS)
+            last_cpu = self.win.cpu_seconds(pid) if pid else 0.0
+            baseline = max(0.0, last_cpu - base_cpu) / AUTOROUTE_BASELINE_SECONDS
+            self.win.click_button(form, "Route All")
+            started = time.monotonic()
+            quiet = 0
+            while time.monotonic() - started < timeout:
+                time.sleep(1.0)
+                cpu = self.win.cpu_seconds(pid) if pid else 0.0
+                busy = (self.wait_dialog("TSitusSetup", timeout=0) is not None or self._dialog_present()
+                        or cpu - last_cpu > baseline + AUTOROUTE_IDLE_CPU)
+                last_cpu = cpu
+                quiet = 0 if busy else quiet + 1
+                if quiet >= AUTOROUTE_IDLE_SECONDS and time.monotonic() - started >= AUTOROUTE_MIN_SECONDS:
+                    break
+            else:
+                return {"ok": False, "stage": "routing", "seconds": round(time.monotonic() - started, 1)}
+            seconds = round(time.monotonic() - started, 1)
+        if not self._ping(timeout=60):
+            return {"ok": False, "stage": "idle", "seconds": seconds}
+        return {"ok": True, "seconds": seconds, "ripup_violations": ripup_violations, "lock_preroutes": lock_preroutes}
+
+    def update_footprints(self, project: str, pcb: str, library: str, timeout: float = 120.0) -> dict:
+        """Altium's Update PCB With All Footprints, run from the footprint library: every placed
+        footprint that comes from `library` is replaced by the library's current version in place
+        (position, rotation, side and nets kept), then the board is saved. Pads, silkscreen and 3D
+        bodies follow the library; check the result with pcb_bodies and altium_drc."""
+        reply = self.run([{"op": "project_open", "path": project}, {"op": "doc_focus", "kind": "PCB", "path": pcb},
+                          {"op": "doc_focus", "kind": "PCBLIB", "path": library}])
+        if not reply.ok:
+            return {"ok": False, "stage": "open", **reply.to_dict()}
+        started = time.monotonic()
+        with Lock(self.exchange / "altium.lock"):
+            self.launch("PCB:UpdateFootprints(Mode=All)").wait(timeout=30)
+            form = self.wait_dialog("TComponentUpdateOptions", timeout=60)
+            if form is None:
+                return {"ok": False, "stage": "options-dialog", "dialogs": self.close_dialogs()}
+            self.win.click_button(form, "OK")
+            deadline = time.monotonic() + timeout
+            while time.monotonic() < deadline and self.wait_dialog("TComponentUpdateOptions", timeout=0):
+                time.sleep(0.5)
+            time.sleep(2.0)
+            if self._dialog_present():
+                return {"ok": False, "stage": "update", "dialogs": self.close_dialogs()}
+        if not self._ping(timeout=60):
+            return {"ok": False, "stage": "idle"}
+        saved = self.run([{"op": "pcb_open", "path": pcb}, {"op": "pcb_save"}])
+        if not saved.ok:
+            return {"ok": False, "stage": "save", **saved.to_dict()}
+        return {"ok": True, "seconds": round(time.monotonic() - started, 1)}
+
+    def screenshot(self, kind: str, path: str, out: Path) -> dict:
+        zoom = "Sch:Zoom" if kind.upper() == "SCH" else "PCB:Zoom"
+        locked = getattr(self.win, "session_locked", lambda: None)()
+        if locked:
+            # Checked first: a locked session draws nothing, and nothing is maximised or focused
+            # for a capture that cannot show anything.
+            return {"ok": False, "code": "session-locked", "error": "the Windows session that runs Altium is "
+                    "locked, so no view can be captured", "fallback": SCREENSHOT_FALLBACK}
+        for pid in self.win.main_instances():
+            hwnd = self.win.main_window(pid)
+            if hwnd:
+                self.win.maximize(hwnd)
+        reply = self.run([{"op": "doc_focus", "kind": kind, "path": path, "zoom": zoom}])
+        if not reply.ok:
+            return {"ok": False, **reply.to_dict()}
+        time.sleep(1.2)
+        main = self.win.main_instances()
+        view = self.win.find_view(next(iter(main)), Path(path).name) if main else None
+        if view is None:
+            return {"ok": False, "error": f"the view of {Path(path).name} is not the visible one; "
+                                         "refusing to capture another editor"}
+        out.parent.mkdir(parents=True, exist_ok=True)
+        shot = self.win.capture(view, out)
+        if shot.get("content", 1.0) < SCREENSHOT_MIN_CONTENT:
+            # Windows draws nothing while the session is locked or the GPU device is lost; an
+            # empty canvas is not evidence of anything, so it is neither reported nor kept as a
+            # screenshot (a blank PNG left at `out` read as one).
+            out.unlink(missing_ok=True)
+            shot = {k: v for k, v in shot.items() if k != "path"}
+            return {"ok": False, "code": "blank", **shot, "fallback": SCREENSHOT_FALLBACK,
+                    "error": "Altium's view came back blank: is the Windows session locked or minimised?"}
+        return {"ok": True, **shot}
+
+
+def sweep_exchange(exchange: Path, now: float | None = None) -> int:
+    """Remove request files older than a day and dialog captures older than a week. Returns how
+    many files were removed. Recent files stay: a queued launcher may still open its script."""
+    now = time.time() if now is None else now
+    removed = 0
+    for path in exchange.glob("*"):
+        if path.is_file() and path.suffix in (".pas", ".json", ".log", ".tmp") and \
+                now - path.stat().st_mtime > EXCHANGE_KEEP_SECONDS and path.name != "altium.lock":
+            path.unlink(missing_ok=True)
+            removed += 1
+    shots = exchange / "dialogs"
+    if shots.is_dir():
+        for path in shots.glob("*.png"):
+            if now - path.stat().st_mtime > DIALOG_IMAGE_KEEP_SECONDS:
+                path.unlink(missing_ok=True)
+                removed += 1
+    return removed
+
+
+def named_documents(reading: dict) -> list[str]:
+    """Altium document names or paths a dialog mentions (its texts and list items)."""
+    found = []
+    for text in reading.get("texts", []) + [i.get("name", "") for i in reading.get("items", [])]:
+        for token in str(text).replace('"', " ").split("\n"):
+            token = token.strip()
+            if token.lower().endswith(ALTIUM_DOCUMENT_SUFFIXES) and token not in found:
+                found.append(token)
+    return found
+
+
+def _in_folder(folder: str, name: str, exists) -> bool:
+    """Whether a bare document name exists in `folder` (Altium's Windows form) or below it."""
+    local = folder.replace("\\", os.sep)
+    if exists(os.path.join(local, name)):
+        return True
+    for _root, _dirs, files in os.walk(local):
+        if name in files:
+            return True
+    return False
+
+
+def matching_rule(rules: list[dict], reading: dict, exists=os.path.exists) -> dict | None:
+    """The first rule that covers a dialog: its title starts with the rule's title (captions
+    compared loosely), and every document the dialog names lies in the rule's folder (and is one
+    of the rule's `files`, when it lists them). A dialog that names no document is answered only
+    by a rule marked `documents: optional` (a confirmation of an answer already given). A dialog
+    about another project's document is never answered on this request's behalf."""
+    from pcba.adapters.altium_uia import caption
+
+    title = caption(reading.get("title", ""))
+    for rule in rules:
+        if not title.startswith(caption(rule["title"])):
+            continue
+        folder = rule.get("folder", "")
+        if "folder" in rule and not folder:
+            # The operation named no folder (a bare file name): no document can be shown to be in it.
+            if named_documents(reading) or rule.get("documents") != "optional":
+                continue
+        if folder:
+            documents = named_documents(reading)
+            if not documents and rule.get("documents") != "optional":
+                continue
+            allowed = [f.replace("/", "\\").lower() for f in rule.get("files", [])]
+            inside = True
+            for doc in documents:
+                norm = doc.replace("/", "\\")
+                if "\\" in norm:
+                    inside = inside and norm.lower().startswith(folder.lower().rstrip("\\") + "\\")
+                    if allowed:
+                        inside = inside and norm.lower() in allowed
+                else:
+                    inside = inside and _in_folder(folder, norm, exists)
+                    if allowed:
+                        inside = inside and norm.lower() in [a.rsplit("\\", 1)[-1] for a in allowed]
+            if not inside:
+                continue
+        return rule
+    return None
+
+
+def _designators(items: list[dict]) -> set[str]:
+    return {str(i["designator"]) for i in items if i.get("name") == "pcb_components" and i.get("designator")}
+
+
+def parse_drc(text: str) -> dict:
+    """Summarise Altium's `.drc` text report: violations per rule, waived, total."""
+    rules = []
+    current = None
+    total = None
+    waived = None
+    for raw in text.splitlines():
+        line = raw.strip()
+        if line.startswith("Processing Rule :"):
+            current = {"rule": line.split(":", 1)[1].strip(), "violations": 0, "details": []}
+            rules.append(current)
+        elif line.startswith("Rule Violations :") and current is not None:
+            current["violations"] = int(line.split(":", 1)[1].strip() or 0)
+        elif line.startswith("Violation between") and current is not None:
+            if len(current["details"]) < 50:
+                current["details"].append(line)
+        elif line.startswith("Violations Detected"):
+            total = int(line.split(":", 1)[1].strip() or 0)
+        elif line.startswith("Waived Violations"):
+            waived = int(line.split(":", 1)[1].strip() or 0)
+    # A report without its "Violations Detected" line and without a rule section was not read:
+    # that is no count, never zero.
+    if total is None and not rules:
+        violations = None
+    else:
+        violations = total if total is not None else sum(r["violations"] for r in rules)
+    return {
+        "violations": violations,
+        "waived": waived or 0,
+        "rules": [r for r in rules if r["violations"]],
+        "rules_checked": len(rules),
+    }
+
+
+def file_hashes(paths: list[Path]) -> list[dict]:
+    out = []
+    for path in paths:
+        digest = hashlib.sha256(path.read_bytes()).hexdigest()
+        out.append({"path": str(path), "bytes": path.stat().st_size, "sha256": digest})
+    return out