enginehall 2.0.0__py3-none-any.whl

pcba/rules/schematic.py

@@ -0,0 +1,123 @@
+"""Single-domain schematic rules, resolved from geometry.
+
+Both detectors here already existed as working code; what they lacked was a finding schema
+to report through.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from pathlib import Path
+
+from pcba.model.finding import Detector, Domain, Evidence, Finding, Location, Severity
+from pcba.model.pinmap import Project
+from pcba.parsers.altium.pinmap import mislabelled, suspected_opens
+from pcba.rules.locate import at_pin
+
+
+def mislabelled_net(project: Project) -> Iterator[Finding]:
+    """A net label whose pin prefix disagrees with the pin it actually attaches to.
+
+    Only runs where the design demonstrably uses the pin-prefix convention — asserting it on
+    a project that never adopted it would flag every net on the board.
+    """
+    if not project.schematic:
+        return
+
+    by_name = project.schematic.by_pin_name()
+    for actual, claim, net in mislabelled(project.schematic):
+        pin = by_name.get(actual)
+        location = (
+            at_pin(project, pin)
+            if pin
+            else Location(artifact=project.relative(project.schematic.source), pin=actual)
+        )
+        yield Finding(
+            rule_id="schematic.net.mislabelled",
+            title=f"Net {net!r} is on {actual}, but its label claims {claim}",
+            severity=Severity.ERROR,
+            domain=Domain.SCHEMATIC,
+            location=location,
+            evidence=(
+                Evidence(
+                    kind="geometry",
+                    value=f"wire geometry attaches net {net!r} to {actual}",
+                    source=location.artifact,
+                ),
+                Evidence(kind="label", value=f"the label's prefix claims {claim}"),
+            ),
+            explanation=(
+                f"This design prefixes net labels with the pin they belong to. Connectivity "
+                f"resolved from wire geometry puts {net!r} on {actual}, but the label says "
+                f"{claim}. Geometry wins; the label is wrong."
+            ),
+            consequence=(
+                "Anyone reading the schematic — or any tool scanning label text rather than "
+                "geometry — builds a wrong pin map from this and does not find out until the "
+                "interface fails on hardware."
+            ),
+            recommendation=(
+                f"Rename the label to match {actual}, or move the wire if {claim} was intended."
+            ),
+        )
+
+
+def open_circuit(project: Project) -> Iterator[Finding]:
+    """A part that visually abuts an MCU pin without electrically touching it.
+
+    Heuristic, and labelled as such: it is a tuned distance threshold, not a proof. The two
+    constraints that keep it from crying wolf are axis-alignment (a diagonal neighbour is a
+    different grid point, not a slip) and requiring the pin to have resolved to no net at all.
+    """
+    if not project.schematic:
+        return
+
+    opens = suspected_opens(project.schematic)
+    for slip in opens:
+        sheet = project.relative(slip["sheet"])
+        yield Finding(
+            rule_id="schematic.net.open_circuit",
+            title=f"{slip['mcu_pin']} looks connected but is not",
+            severity=Severity.ERROR,
+            domain=Domain.SCHEMATIC,
+            location=Location(artifact=sheet, sheet=Path(sheet).name, pin=slip["mcu_pin"]),
+            evidence=(
+                Evidence(
+                    kind="geometry",
+                    value=(
+                        f"a pin lands {slip['gap']} units from {slip['mcu_pin']} "
+                        f"(package pin {slip['package_pin']}) without touching it"
+                    ),
+                    source=sheet,
+                ),
+                Evidence(
+                    kind="geometry",
+                    value=(
+                        f"{project.schematic.exact_landings} other pin"
+                        f"{'' if project.schematic.exact_landings == 1 else 's'} on this "
+                        f"design land{'s' if project.schematic.exact_landings == 1 else ''} "
+                        "exactly on an MCU pin"
+                    ),
+                ),
+                Evidence(
+                    kind="net", value=f"{slip['mcu_pin']} resolves to no net at all"
+                ),
+            ),
+            explanation=(
+                f"A part's pin sits {slip['gap']} units away from {slip['mcu_pin']} along one "
+                f"axis and does not connect to it. {slip['mcu_pin']} resolves to no net."
+            ),
+            consequence=(
+                "The parts visually abut the pin, so a rendered PDF looks correct and a "
+                "design review passes it. The net is open on the fabricated board."
+            ),
+            recommendation=(
+                f"Open the sheet at {slip['mcu_pin']} and check the connection. If it is "
+                "intentional, the pin should carry an explicit no-connect marker."
+            ),
+            detector=Detector.HEURISTIC,
+            confidence=0.85,
+        )
+
+
+RULES = (mislabelled_net, open_circuit)

pcba/rules/signals.py

@@ -0,0 +1,149 @@
+"""Normalizing signal names across artifacts.
+
+The schematic and the `.ioc` name the same wire differently. The schematic is written by a
+human ("UART8_TxD"); the `.ioc` carries ST's own name ("UART8_TX"). Comparing them raw
+produces either a flood of false mismatches or a silent failure to compare at all.
+
+The rule this module follows: **normalize conservatively, and only compare signals both
+sides actually name.** A missed finding is a disappointment; a false one gets the tool
+switched off.
+"""
+
+from __future__ import annotations
+
+import re
+
+# Peripheral families whose pin assignment is worth cross-checking. A net called
+# "SENSOR_ENABLE" is a GPIO and means nothing to the .ioc's Signal field, so it is skipped
+# rather than guessed at.
+_FAMILIES = (
+    "SPI|FDCAN|CAN|SDMMC|I2C|I2S|I3C|UART|USART|LPUART|QUADSPI|OCTOSPI|XSPIM|XSPI|ETH|USB|OTG|"
+    "ADC|DAC|FMC|TIM|LPTIM|SAI|SDIO|RCC|RTC|SWPMI|MDIOS|DCMIPP|DCMI|LTDC"
+)
+_PERIPHERAL = re.compile(rf"^({_FAMILIES})\d*(_|$)")
+
+# The first token of a peripheral signal, split into family and instance ("USART3" ->
+# USART, 3; "ETH" -> ETH, ""). Longer names first, so DCMIPP is not read as DCMI + "PP".
+_INSTANCE = re.compile(
+    rf"^({'|'.join(sorted(_FAMILIES.split('|'), key=len, reverse=True))})(\d*)$"
+)
+
+# Names a human and ST use for the same block. A schematic says UART1 where ST says USART1,
+# USB_DP where ST says USB1_OTG_HS_DP, OCTOSPI where a newer part says XSPI. LPUART1 is a
+# different peripheral from USART1, and the XSPIM port manager is not an XSPI instance, so
+# neither is folded.
+_FAMILY_ALIAS = {
+    "USART": "UART",
+    "OTG": "USB",
+    "QUADSPI": "XSPI", "OCTOSPI": "XSPI",
+}
+
+# Roles a signal name identifies. Two signals of one block that name different roles are
+# different wires (SDA on SCL, TX on RX, SCK on MOSI); an unrecognised last token (TXD0,
+# CH1N) is left alone rather than guessed at.
+_ROLE = re.compile(
+    r"^(SDA|SCL|TX|RX|MISO|MOSI|SCK|NSS|DP|DM|ID|CTS|RTS|DE|CK|CMD|MDC|MDIO|D\d{1,2}|IO\d{1,2})$"
+)
+_ROLE_SPELLING = {"DN": "DM", "TXD": "TX", "RXD": "RX", "CS": "NSS", "CLK": "CK", "SCLK": "SCK"}
+
+# Net labels in some designs are prefixed with the pin they belong to ("PA5_SPI1_SCK").
+# Ports run A..K, and on the STM32N6 also N..Q.
+_PIN_PREFIX = re.compile(r"^P[A-KN-Q]\d{1,2}(_C)?_")
+
+# Role aliases. Deliberately exact-match only, no digits.
+#
+# The temptation is to fold TXD -> TX globally. That breaks ETH_MII_TXD0, which is a real
+# ST signal name where the D and the digit are load-bearing. So aliasing applies only when
+# the role token is exactly TXD/RXD, never when a digit follows.
+_ROLE_ALIAS = {
+    "TXD": "TX",
+    "RXD": "RX",
+    "TXO": "TX",
+    "RXI": "RX",
+    "SCLK": "SCK",
+    "MISO": "MISO",
+    "MOSI": "MOSI",
+    "CLK": "CK",
+}
+
+
+def strip_pin_prefix(net: str) -> str:
+    """'PA5_SPI1_SCK' -> 'SPI1_SCK'. Leaves an unprefixed net untouched.
+
+    Strips whatever prefix is present, not the pin we believe we are on — a mislabeled net
+    must still yield its signal so the cross-domain rule can catch the disagreement.
+    """
+    return _PIN_PREFIX.sub("", net or "", count=1)
+
+
+def is_peripheral_signal(name: str) -> bool:
+    """Is this a peripheral signal (worth comparing) or just a GPIO net name?"""
+    return bool(_PERIPHERAL.match((name or "").upper()))
+
+
+def normalize(name: str | None) -> str | None:
+    """Canonical form of a peripheral signal name, or None if it isn't one.
+
+    'PE1_UART8_TxD' -> 'UART8_TX'
+    'ETH_MII_TXD0'  -> 'ETH_MII_TXD0'   (digit-suffixed role: left alone)
+    'SENSOR_ENABLE' -> None             (not a peripheral signal)
+    """
+    if not name:
+        return None
+    # Uppercase BEFORE stripping: the prefix pattern is uppercase-only, so a lowercase net
+    # name would keep its prefix, fail the peripheral test, and return None. That reads as
+    # "not a peripheral signal" and silently skips the comparison rather than erroring.
+    bare = strip_pin_prefix(name.strip().upper())
+    if not is_peripheral_signal(bare):
+        return None
+    tokens = bare.split("_")
+    if len(tokens) >= 2:
+        tokens[-1] = _ROLE_ALIAS.get(tokens[-1], tokens[-1])
+    return "_".join(tokens)
+
+
+def peripheral_instance(signal: str | None) -> tuple[str, str] | None:
+    """('UART', '1') for 'USART1_TX', ('ETH', '') for 'ETH_MDC'; None for a GPIO net.
+
+    The family is folded through the aliases above, so USART and UART compare equal.
+    """
+    name = normalize(signal)
+    if not name:
+        return None
+    match = _INSTANCE.match(name.split("_")[0])
+    if not match:
+        return None
+    family, instance = match.groups()
+    return _FAMILY_ALIAS.get(family, family), instance
+
+
+def _role(name: str) -> str | None:
+    role = name.split("_")[-1]
+    role = _ROLE_SPELLING.get(role, role)
+    return role if _ROLE.match(role) else None
+
+
+def same_block(net: str | None, signal: str | None) -> bool:
+    """Do both name the same peripheral instance, as far as each names one?
+
+    An instance on only one side (I2C_SDA against I2C1_SDA) is no disagreement.
+    """
+    left, right = peripheral_instance(net), peripheral_instance(signal)
+    if not left or not right or left[0] != right[0]:
+        return False
+    return not (left[1] and right[1] and left[1] != right[1])
+
+
+def compatible(net: str | None, signal: str | None) -> bool:
+    """Can a net with this name be the wire for that ST signal?
+
+    Lenient where people legitimately differ — a net names the family without its instance
+    (I2C_SDA for I2C1_SDA, ETH_MDC for ETH1_MDC), or the human spelling of the block (UART1
+    for USART1, USB_DN for USB1_OTG_HS_DM). Strict only where a difference is a real wiring
+    error: another instance (SPI2 on an SPI1 pin), another peripheral, or another role of the
+    same block (SDA on SCL, TX on RX, SCK on MOSI).
+    """
+    if not same_block(net, signal):
+        return False
+    a, b = _role(normalize(net) or ""), _role(normalize(signal) or "")
+    return not (a and b and a != b)

pcba/rules/spice.py

@@ -0,0 +1,59 @@
+"""Declared SPICE testbenches: a failed or marginal measurement is a finding.
+
+The testbenches run while the project is loaded (`pcba/simulation.py`), so their outcome is in
+`design.external["spice"]` before any rule runs; this rule only reports. A testbench that did not
+run (no ngspice, a refused deck, no value printed) is listed as not checked with its reason.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+
+from pcba.model.finding import Detector, Domain, Evidence, Finding, Location, Severity
+from pcba.model.pinmap import Project
+
+
+def _results(project: Project) -> list[dict]:
+    run = (project.design.external.get("spice") or {}) if project.design else {}
+    return run.get("results", []) if run.get("ran") else []
+
+
+def testbench(project: Project) -> Iterator[Finding]:
+    """A declared testbench whose measured value is outside its pass range."""
+    for result in _results(project):
+        status = result.get("status")
+        if status not in ("fail", "warn"):
+            continue
+        low, high = result["pass"]
+        yield Finding(
+            rule_id="simulation.spice.testbench",
+            title=f"Testbench {result['name']!r}: {result['measure']} = {result['value']:g}, "
+                  f"pass range {low:g} to {high:g}",
+            severity=Severity.ERROR if status == "fail" else Severity.WARNING,
+            domain=Domain.SCHEMATIC,
+            location=Location(artifact=project.relative(result["netlist"]), key=result["name"]),
+            evidence=(Evidence(kind="simulation", value=f"ngspice printed {result['measure']} = {result['value']:g}",
+                               source=project.relative(result["netlist"])),
+                      Evidence(kind="requirement", value=f"pass {low:g} to {high:g}"
+                               + (f", warn {result['warn'][0]:g} to {result['warn'][1]:g}" if result.get("warn")
+                                  else ""), source="pcba-requirements.toml")),
+            explanation=f"The project declares this testbench and its limits; the simulated value is "
+                        f"{'outside the warn range' if status == 'fail' else 'inside the warn range only'}.",
+            consequence="The circuit the testbench models does not meet the value the design relies on.",
+            recommendation="Check the component values against the testbench (and the testbench against the "
+                           "schematic); change the circuit or the declared limits deliberately.",
+            detector=Detector.EXTERNAL,
+            confidence=0.95,
+        )
+
+
+def _scope(project: Project) -> tuple[int, list[str]]:
+    run = (project.design.external.get("spice") or {}) if project.design else {}
+    results = run.get("results", [])
+    checked = sum(r.get("status") in ("pass", "warn", "fail") for r in results)
+    unchecked = [f"{r['name']}: {r.get('reason', 'not run')}" for r in results if r.get("status") == "not_run"]
+    return checked, unchecked
+
+
+RULES = (testbench,)
+SCOPE = {"simulation.spice.testbench": _scope}

pcba/rules/stm32.py

@@ -0,0 +1,155 @@
+"""Single-domain STM32 rules, checked against ST's own MCU database.
+
+CubeMX ships a per-part XML listing every pin and every signal it can carry. It is the
+authority on what a pin can do — never answer that from memory, and never from the datasheet
+PDF either.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+
+from pcba.model.finding import Domain, Evidence, Finding, Severity
+from pcba.model.pinmap import Project, Resolution, is_power_pin
+from pcba.parsers.ioc import IocError, alternate_function_table, find_mcu_db, resolve_part_xml
+from pcba.rules.locate import at_pin
+from pcba.rules.signals import compatible, normalize, same_block, strip_pin_prefix
+
+
+def af_table(project: Project) -> dict[str, set[str]] | None:
+    """ST's pin -> signals table for this project's part, or None if we have no usable one.
+
+    An empty table is None, not {}: a table that answers nothing cannot support the rule,
+    and reporting it as present would make `coverage()` claim this check ran.
+    """
+    part = None
+    if project.mcu and project.mcu.part:
+        part = project.mcu.part
+    elif project.schematic:
+        part = project.schematic.part
+    if not part:
+        return None
+    try:
+        db = find_mcu_db()
+        mcu_name = project.mcu.raw.get("Mcu.Name") if project.mcu else None
+        return alternate_function_table(resolve_part_xml(db, part, mcu_name)) or None
+    except (IocError, OSError):
+        return None
+
+
+def alternate_function_impossible(project: Project) -> Iterator[Finding]:
+    """A schematic net names a peripheral the pin physically cannot carry.
+
+    The net name is only a hint, and several benign naming conventions look like mismatches —
+    FMC_D0_DA0 for ST's FMC_D0/FMC_DA0, ADC1_Ch2 for ADC1_INP2. So this reports only the case
+    it can prove: a pin that offers no signal of that peripheral instance *at all*, which is
+    unroutable silicon and always a defect.
+
+    A tuned check that cries wolf gets switched off, and then it protects nothing. Hence the
+    variant tolerance below, and hence every finding here is an ERROR — because by the time
+    one is emitted, it is certain.
+    """
+    if not project.schematic or project.part_conflict:
+        return
+    table = af_table(project)
+    if not table:
+        return
+
+    for pin in sorted(
+        project.schematic.pins.values(), key=lambda p: (p.port_pin, p.package_pin)
+    ):
+        if is_power_pin(pin.name) or not pin.net:
+            continue
+        if pin.resolution in (Resolution.NONE, Resolution.AMBIGUOUS):
+            continue
+        signals = table.get(pin.port_pin)
+        if not signals:
+            continue
+        # The .ioc puts a matching signal on this very pin, and ST's table confirms the pad
+        # carries it: the net merely spells it differently (I2C_SDA for I2C1_SDA, UART1_TX
+        # for USART1_TX). A hand-edited .ioc naming a signal the pad lacks proves nothing.
+        assigned = project.mcu.assignments.get(pin.port_pin) if project.mcu else None
+        if assigned and assigned.signal in signals and compatible(pin.net, assigned.signal):
+            continue
+        # ST's signal names are upper case; net names often are not. Upper-case before
+        # stripping, as `normalize` does, or `usart1_tx` on a USART1_TX pin reads as
+        # unroutable silicon. The original net stays in the evidence.
+        want = strip_pin_prefix(pin.net.strip().upper())
+        if not normalize(want):
+            continue  # a plain GPIO net; the AF table has nothing to say about it
+
+        # Accept ST's MII/RMII prefixes and its D0/DA0 split naming.
+        variants = {
+            want,
+            want.replace("ETH_", "ETH_MII_", 1),
+            want.split("_DA")[0],
+            want.rsplit("_", 1)[0],
+        }
+        if any(v in signals for v in variants):
+            continue
+
+        # The only defensible signal is: this pin offers NOTHING for that peripheral
+        # instance. Anything weaker is a false positive.
+        #
+        # Measured on a real 176-pin design: reporting "the pin offers ADC1 signals but not
+        # under this exact name" produced 3 findings, all wrong — the nets were simply named
+        # descriptively (PF11_ADC1_Ch2_ICP_Check against ST's ADC1_INP2). The pin is
+        # correct; only the human-readable suffix differs. Flagging those trains engineers
+        # to ignore the rule, which costs us the one finding that is real.
+        #
+        # Requiring the whole instance to be absent leaves exactly the unroutable case: a
+        # signal assigned to silicon that cannot produce it. That is never a naming quibble.
+        #
+        # "Instance" is read as loosely as people write it: a net that names only the family
+        # (I2C_SDA, ETH_MDC, USB_DP) matches any instance of it, and UART/USART, OTG/USB name
+        # the same block. Only a pin offering no signal of that block at all is reported.
+        instance = want.split("_")[0]
+        if any(same_block(want, s) for s in signals):
+            continue
+
+        offered = sorted(s for s in signals if s.startswith(instance[:4]))
+
+        yield Finding(
+            rule_id="stm32.pin.alternate_function_impossible",
+            title=f"{pin.port_pin} cannot carry {want}",
+            severity=Severity.ERROR,
+            domain=Domain.IOC,
+            location=at_pin(project, pin),
+            evidence=(
+                Evidence(
+                    kind="schematic_net",
+                    value=f"{pin.port_pin} carries net {pin.net!r}",
+                    source=project.relative(pin.sheet),
+                ),
+                Evidence(
+                    kind="mcu_database",
+                    value=f"{pin.port_pin} offers no {instance} signal at all",
+                    source="STM32CubeMX MCU database",
+                ),
+                Evidence(
+                    kind="mcu_database",
+                    value=(
+                        f"nearest signals on {pin.port_pin}: {', '.join(offered)}"
+                        if offered
+                        else f"{pin.port_pin} offers nothing resembling {instance}"
+                    ),
+                    source="STM32CubeMX MCU database",
+                ),
+            ),
+            explanation=(
+                f"The net on {pin.port_pin} names {want}. Checked against ST's own MCU "
+                f"database for {project.schematic.part}, {pin.port_pin} has no {instance} "
+                f"alternate function of any kind."
+            ),
+            consequence=(
+                "The signal cannot be routed to this pin in silicon. No firmware "
+                "configuration can make this work; the board needs an ECO before layout."
+            ),
+            recommendation=(
+                f"Move {want} to a pin that offers {instance}, or correct the net name if the "
+                "net is not actually that peripheral."
+            ),
+        )
+
+
+RULES = (alternate_function_impossible,)

pcba/simulation.py

@@ -0,0 +1,143 @@
+"""SPICE testbenches a project declares, run with ngspice in batch mode (stage 1).
+
+A project lists testbenches in `pcba-requirements.toml` (`[[simulations]]`): an ngspice deck,
+the name of one measured value it prints, a pass range and an optional wider warn range. The
+review runs each deck with `ngspice -b -n` and reads the value from a `name = value` line
+(what `.measure` and `print`/`echo` produce). Each testbench ends as pass, warn, fail or not run,
+and "not run" always says why: no ngspice, a refused deck, a timeout, no value printed.
+
+A deck is a program. A review must not run what a project hides in it, so before ngspice starts:
+
+- the deck and every file it includes (`.include`, `.lib`, `source`) must lie inside the project;
+- inside `.control` blocks, commands that reach outside the simulator are refused (`shell`,
+  `codemodel`, `load`, `osdi`, `pre_osdi`, `cd`, `write`, `wrdata`, `plot`, ...): a measurement
+  needs `run`, `meas`, `let`, `print` and `echo`, nothing that starts programs or writes files;
+- ngspice starts with `-n` (no `spinit` / `.spiceinit`), in an empty temporary directory, with a
+  timeout, and nothing it writes is kept.
+
+No model is ever downloaded: a deck that needs a vendor model ships it in the project.
+`PCBA_NGSPICE` names the executable, or switches simulation off with `off`.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+
+from pcba.requirements import Testbench
+
+ENVIRONMENT = "PCBA_NGSPICE"
+_OFF = {"off", "0", "none", "no", "false", ""}
+_REFUSED = re.compile(r"^\s*(shell|codemodel|load|osdi|pre_osdi|cd|setcs|edit|wrdata|write|wrs2p|hardcopy|"
+                      r"plot|gnuplot|sendcmd|rehash|rspice|aspice|jobs)\b", re.I | re.M)
+_CONTROL = re.compile(r"^\s*\.control\b(.*?)(?:^\s*\.endc\b|\Z)", re.I | re.M | re.S)
+_INCLUDE = re.compile(r"^\s*(?:\.include|\.inc|\.lib|source)\s+(?:\"([^\"]+)\"|'([^']+)'|(\S+))", re.I | re.M)
+_RESULT = r"^\s*{name}\s*=\s*([-+]?(?:\d+\.?\d*|\.\d+)(?:[eE][-+]?\d+)?)"
+
+
+def find() -> tuple[Path | None, str]:
+    configured = os.environ.get(ENVIRONMENT)
+    if configured is not None:
+        if configured.strip().lower() in _OFF:
+            return None, f"switched off by {ENVIRONMENT}"
+        path = Path(configured).expanduser()
+        if path.is_file():
+            return path, ENVIRONMENT
+        return None, f"{ENVIRONMENT} names {configured}, which does not exist"
+    for candidate in (shutil.which("ngspice"), "/opt/homebrew/bin/ngspice", "/usr/local/bin/ngspice",
+                      "/usr/bin/ngspice"):
+        if candidate and Path(candidate).is_file():
+            return Path(candidate), "PATH" if candidate == shutil.which("ngspice") else "default install location"
+    return None, "ngspice not found (install ngspice, or set PCBA_NGSPICE to its path)"
+
+
+def _inside(root: Path, candidate: Path) -> bool:
+    try:
+        candidate.resolve().relative_to(root.resolve())
+        return True
+    except ValueError:
+        return False
+
+
+def vet(deck: Path, project_root: Path, seen: set[Path] | None = None) -> str | None:
+    """Why a deck must not run, or None. Follows includes, all of which must stay in the project."""
+    seen = seen if seen is not None else set()
+    if deck.resolve() in seen:
+        return None
+    seen.add(deck.resolve())
+    if not _inside(project_root, deck):
+        return f"{deck.name} lies outside the project"
+    try:
+        text = deck.read_text(encoding="utf-8", errors="replace")
+    except OSError as exc:
+        return f"cannot read {deck.name}: {exc}"
+    refused = next((m for block in _CONTROL.findall(text) for m in [_REFUSED.search(block)] if m), None)
+    if refused:
+        return f"{deck.name} uses the control command {refused.group(1)!r}, which a review does not run"
+    for match in _INCLUDE.finditer(text):
+        target = next(g for g in match.groups() if g)
+        included = Path(target) if Path(target).is_absolute() else deck.parent / target
+        if not _inside(project_root, included):
+            return f"{deck.name} includes {target}, outside the project"
+        if not included.is_file():
+            return f"{deck.name} includes {target}, which does not exist"
+        reason = vet(included, project_root, seen)
+        if reason:
+            return reason
+    return None
+
+
+def run(testbench: Testbench, base: Path, project_root: Path, ngspice: Path) -> dict:
+    """One testbench: {"name", "netlist", "status": pass|warn|fail|not_run, "value"?, "reason"?}."""
+    deck = (base / testbench.netlist).resolve()
+    result = {"name": testbench.name, "netlist": str(deck), "measure": testbench.measure,
+              "pass": list(testbench.passing), "warn": list(testbench.warning) if testbench.warning else None}
+    if not deck.is_file():
+        return {**result, "status": "not_run", "reason": f"{testbench.netlist} not found"}
+    reason = vet(deck, project_root)
+    if reason:
+        return {**result, "status": "not_run", "reason": reason}
+    with tempfile.TemporaryDirectory(prefix="pcba-spice-") as tmp:
+        try:
+            done = subprocess.run([str(ngspice), "-b", "-n", str(deck)], cwd=tmp, capture_output=True, text=True,
+                                  errors="replace", timeout=testbench.timeout_s, check=False,
+                                  env={**os.environ, "SPICE_ASCIIRAWFILE": "1", "HOME": tmp})
+        except subprocess.TimeoutExpired:
+            return {**result, "status": "not_run", "reason": f"ngspice timed out after {testbench.timeout_s:g} s"}
+        except OSError as exc:
+            return {**result, "status": "not_run", "reason": f"ngspice could not start: {exc}"}
+    output = done.stdout + "\n" + done.stderr
+    match = None
+    for match in re.finditer(_RESULT.format(name=re.escape(testbench.measure)), output, re.I | re.M):
+        pass  # the last printed value wins
+    if match is None:
+        tail = [line for line in output.strip().splitlines() if "error" in line.lower()][-1:]
+        return {**result, "status": "not_run",
+                "reason": f"ngspice printed no value for {testbench.measure} (exit {done.returncode})"
+                + (f": {tail[0].strip()}" if tail else "")}
+    value = float(match.group(1))
+    low, high = testbench.passing
+    if low <= value <= high:
+        status = "pass"
+    elif testbench.warning and testbench.warning[0] <= value <= testbench.warning[1]:
+        status = "warn"
+    else:
+        status = "fail"
+    return {**result, "status": status, "value": value}
+
+
+def run_all(testbenches: list[Testbench], base: Path, project_root: Path) -> dict:
+    """Every declared testbench. {"ran": bool, "reason"?, "tool"?, "results": [...]}."""
+    if not testbenches:
+        return {"ran": False, "reason": "no [[simulations]] in pcba-requirements.toml", "results": []}
+    ngspice, how = find()
+    if ngspice is None:
+        return {"ran": False, "reason": how,
+                "results": [{"name": t.name, "netlist": t.netlist, "status": "not_run", "reason": how}
+                            for t in testbenches]}
+    results = [run(t, base, project_root, ngspice) for t in testbenches]
+    return {"ran": True, "tool": "ngspice", "path": str(ngspice), "found_by": how, "results": results}