enginehall 2.0.0__py3-none-any.whl

pcba/report/text.py

@@ -0,0 +1,304 @@
+"""Human-readable output.
+
+The layout puts evidence directly under the claim, because the first thing an engineer does
+with a finding is disbelieve it. Making the proof immediate is the difference between a tool
+that gets adopted and one that gets muted.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+
+from pcba.model.finding import Detector, Finding, Severity
+
+_COLOR = {
+    Severity.ERROR: "\033[31m",
+    Severity.WARNING: "\033[33m",
+    Severity.INFO: "\033[36m",
+}
+_DIM = "\033[2m"
+_BOLD = "\033[1m"
+_RESET = "\033[0m"
+
+
+def _supports_color(stream=sys.stdout) -> bool:
+    if os.environ.get("NO_COLOR"):
+        return False
+    return bool(getattr(stream, "isatty", lambda: False)())
+
+
+def _markdown_table_cell(value: str) -> str:
+    """Keep arbitrary evidence on one Markdown table row."""
+    escaped = value.replace("\\", "\\\\").replace("|", "\\|")
+    return escaped.replace("\r\n", "<br>").replace("\r", "<br>").replace("\n", "<br>")
+
+
+def to_text(
+    findings: list[Finding],
+    coverage: dict | None = None,
+    baseline: dict | None = None,
+    changes: dict | None = None,
+) -> str:
+    color = _supports_color()
+
+    def paint(text: str, code: str) -> str:
+        return f"{code}{text}{_RESET}" if color else text
+
+    lines: list[str] = []
+    for f in findings:
+        head = paint(str(f.severity).ljust(7), _COLOR[f.severity])
+        lines.append(f"{head} {paint(f.rule_id, _BOLD)}  {f.title}")
+        lines.append(f"        {paint(f.location.describe(), _DIM)}")
+        for evidence in f.evidence:
+            source = f" [{evidence.source}]" if evidence.source else ""
+            lines.append(f"        {paint('·', _DIM)} {evidence.value}{paint(source, _DIM)}")
+        lines.append(f"        {f.explanation}")
+        lines.append(f"        {paint('→ ' + f.recommendation, _DIM)}")
+        # Never let a heuristic pass for a proof.
+        if f.detector is not Detector.DETERMINISTIC:
+            lines.append(
+                f"        {paint(f'({f.detector}, confidence {f.confidence:.0%})', _DIM)}"
+            )
+        lines.append("")
+
+    counts = {s: sum(1 for f in findings if f.severity is s) for s in Severity}
+    summary = ", ".join(
+        f"{counts[s]} {s}{'s' if counts[s] != 1 else ''}" for s in Severity if counts[s]
+    )
+    lines.append(summary or "no findings")
+    stats = (coverage or {}).get("statistics", {})
+    if stats.get("ioc_signals") is not None:
+        lines.append(
+            f"compared {stats['compared_signals']} of {stats['ioc_signals']} configured "
+            "peripheral signal placements"
+        )
+
+    if baseline:
+        lines.append(f"{baseline['suppressed']} findings suppressed by {baseline['path']}")
+        if baseline["stale"]:
+            lines.append(f"{len(baseline['stale'])} stale baseline entries")
+    if changes:
+        lines.append(
+            f"changed-only against {changes['base']}: {len(changes['files'])} files, "
+            f"{changes['omitted']} unchanged findings omitted"
+        )
+
+    if coverage and coverage.get("skipped"):
+        # "0 findings" from checks that never ran is the most dangerous output this tool
+        # could produce. Always say what did not run.
+        lines.append("")
+        lines.append(paint("Not checked:", _BOLD))
+        for skipped in coverage["skipped"]:
+            lines.append(f"  {paint('·', _DIM)} {skipped}")
+    ambiguous = (coverage or {}).get("statistics", {}).get("ambiguous_signals")
+    if ambiguous:
+        lines.append("")
+        lines.append(paint("Not compared (signal on several pins of one side):", _BOLD))
+        lines.append(f"  {paint('·', _DIM)} {', '.join(ambiguous)}")
+    uncompared = stats.get("uncompared_signals", [])
+    if uncompared:
+        lines.append("")
+        lines.append(paint("Configured signals not compared:", _BOLD))
+        for item in uncompared:
+            context = f"; schematic net {item['schematic_net']}" if item.get("schematic_net") else ""
+            lines.append(f"  {paint('·', _DIM)} {item['signal']} at {item['ioc_pin']} "
+                         f"({item['ioc_key']}): "
+                         f"{item['reason'].replace('_', ' ')}{context}")
+    if (coverage or {}).get("unmet"):
+        lines.append("")
+        lines.append(paint("Required checks without usable coverage:", _BOLD))
+        for rule in coverage["unmet"]:
+            lines.append(f"  {paint('·', _DIM)} {rule}")
+
+    tools = (coverage or {}).get("tools")
+    if tools:
+        lines.append("")
+        lines.append(paint("External tools:", _BOLD))
+        for name, run in tools.items():
+            lines.append(f"  {paint('·', _DIM)} {_tool_line(name, run)}")
+    simulations = (coverage or {}).get("simulations")
+    if simulations:
+        lines.append("")
+        lines.append(paint("Simulations:", _BOLD))
+        for sim in simulations:
+            lines.append(f"  {paint('·', _DIM)} {_simulation_line(sim)}")
+    statuses = (coverage or {}).get("rules")
+    if statuses:
+        lines.append("")
+        lines.append(paint(f"Rules ({_status_summary(statuses)}):", _BOLD))
+        width = max(len(entry["rule_id"]) for entry in statuses)
+        for entry in statuses:
+            if entry["status"] == "not_applicable":
+                continue
+            label = entry["status"].replace("_", " ")
+            lines.append(f"  {label:<12} {entry['rule_id']:<{width}}  {_status_detail(entry)}".rstrip())
+            for item in _unchecked(entry):
+                lines.append(f"  {'':<12} {'':<{width}}  {paint('not judged: ' + item, _DIM)}")
+
+    return "\n".join(lines)
+
+
+_STATUS_ORDER = ("failed", "info", "passed", "not_checked", "not_applicable")
+UNCHECKED_SHOWN = 5
+
+
+def _status_summary(statuses: list[dict]) -> str:
+    counts = {s: sum(1 for e in statuses if e["status"] == s) for s in _STATUS_ORDER}
+    parts = [f"{counts[s]} {s.replace('_', ' ')}" for s in _STATUS_ORDER if counts[s]]
+    return ", ".join(parts)
+
+
+def _status_detail(entry: dict) -> str:
+    if entry.get("findings"):
+        return f"{entry['findings']} finding{'s' if entry['findings'] != 1 else ''}"
+    return entry.get("reason", "")
+
+
+def _unchecked(entry: dict) -> list[str]:
+    items = entry.get("unchecked", [])
+    shown = items[:UNCHECKED_SHOWN]
+    if len(items) > UNCHECKED_SHOWN:
+        shown.append(f"and {len(items) - UNCHECKED_SHOWN} more")
+    return shown
+
+
+def _tool_line(name: str, run: dict) -> str:
+    label = {"erc": "ERC", "drc": "DRC", "netlist": "netlist export", "spice": "SPICE testbenches"}.get(name, name)
+    if run.get("ran"):
+        version = f" {run['version']}" if run.get("version") else ""
+        return f"{label}: ran with {run.get('tool', 'tool')}{version}"
+    return f"{label}: not run ({run.get('reason', 'no reason given')})"
+
+
+def _simulation_line(sim: dict) -> str:
+    low, high = sim.get("pass", [None, None])
+    if sim.get("status") == "not_run":
+        return f"not run  {sim['name']}: {sim.get('reason', '')}"
+    return (f"{sim['status']:<8} {sim['name']}: {sim.get('measure')} = {sim.get('value'):g} "
+            f"(pass {low:g} to {high:g})")
+
+
+def to_markdown(
+    findings: list[Finding],
+    coverage: dict | None = None,
+    baseline: dict | None = None,
+    changes: dict | None = None,
+) -> str:
+    lines = ["# EngineHall review", ""]
+    counts = {s: sum(1 for f in findings if f.severity is s) for s in Severity}
+    lines.append(
+        f"**{counts[Severity.ERROR]} errors, {counts[Severity.WARNING]} warnings, "
+        f"{counts[Severity.INFO]} info.**"
+    )
+    lines.append("")
+    if (coverage or {}).get("unmet"):
+        # Why an exit-2 run failed belongs at the top of a PR comment, not after the findings.
+        lines.append("## Required checks without usable coverage")
+        lines.append("")
+        for rule in coverage["unmet"]:
+            lines.append(f"- `{rule}`")
+        lines.append("")
+    stats = (coverage or {}).get("statistics", {})
+    if stats.get("ioc_signals") is not None:
+        lines.append(
+            f"Compared **{stats['compared_signals']} of {stats['ioc_signals']}** "
+            "configured peripheral signal placements."
+        )
+        lines.append("")
+
+    if baseline:
+        lines.append(
+            f"Baseline `{baseline['path']}` suppressed {baseline['suppressed']} findings; "
+            f"{len(baseline['stale'])} entries are stale."
+        )
+        lines.append("")
+    if changes:
+        lines.append(
+            f"Changed-only against `{changes['base']}`: {len(changes['files'])} files; "
+            f"{changes['omitted']} unchanged findings omitted."
+        )
+        lines.append("")
+
+    if not findings:
+        lines.append("No findings.")
+    for f in findings:
+        lines.append(f"## {f.severity.upper()} — {f.title}")
+        lines.append("")
+        lines.append(f"`{f.rule_id}` · {f.location.describe()}")
+        lines.append("")
+        if f.evidence:
+            lines.append("| Evidence | Value | Source |")
+            lines.append("| -------- | ----- | ------ |")
+            for e in f.evidence:
+                kind = _markdown_table_cell(e.kind)
+                value = _markdown_table_cell(e.value)
+                source = _markdown_table_cell(e.source or "—")
+                lines.append(f"| {kind} | {value} | {source} |")
+            lines.append("")
+        lines.append(f.explanation)
+        lines.append("")
+        lines.append(f"**Consequence.** {f.consequence}")
+        lines.append("")
+        lines.append(f"**Recommendation.** {f.recommendation}")
+        lines.append("")
+        if f.detector is not Detector.DETERMINISTIC:
+            lines.append(f"_Detected {f.detector}; confidence {f.confidence:.0%}._")
+            lines.append("")
+
+    if coverage and coverage.get("skipped"):
+        lines.append("## Not checked")
+        lines.append("")
+        for skipped in coverage["skipped"]:
+            lines.append(f"- {skipped}")
+        lines.append("")
+    ambiguous = (coverage or {}).get("statistics", {}).get("ambiguous_signals")
+    if ambiguous:
+        lines.append("## Not compared")
+        lines.append("")
+        lines.append("Each of these signals sits on several pins of one side: "
+                     + ", ".join(f"`{s}`" for s in ambiguous))
+        lines.append("")
+    uncompared = stats.get("uncompared_signals", [])
+    if uncompared:
+        lines.append("## Configured signals not compared")
+        lines.append("")
+        for item in uncompared:
+            context = f"; schematic net `{item['schematic_net']}`" if item.get("schematic_net") else ""
+            lines.append(f"- `{item['signal']}` at `{item['ioc_pin']}` "
+                         f"(`{item['ioc_key']}`): "
+                         f"{item['reason'].replace('_', ' ')}{context}")
+        lines.append("")
+
+    tools = (coverage or {}).get("tools")
+    if tools:
+        lines.append("## External tools")
+        lines.append("")
+        lines.extend(f"- {_markdown_table_cell(_tool_line(name, run))}" for name, run in tools.items())
+        lines.append("")
+    simulations = (coverage or {}).get("simulations")
+    if simulations:
+        lines.append("## Simulations")
+        lines.append("")
+        lines.extend(f"- {_markdown_table_cell(_simulation_line(sim))}" for sim in simulations)
+        lines.append("")
+    statuses = (coverage or {}).get("rules")
+    if statuses:
+        lines.append("## Rules")
+        lines.append("")
+        lines.append(f"{_status_summary(statuses)}.")
+        lines.append("")
+        lines.append("| Rule | Status | Detail |")
+        lines.append("| ---- | ------ | ------ |")
+        for entry in statuses:
+            if entry["status"] == "not_applicable":
+                continue
+            detail = _status_detail(entry)
+            unchecked = _unchecked(entry)
+            if unchecked:
+                detail = (detail + "; " if detail else "") + "not judged: " + "; ".join(unchecked)
+            lines.append(f"| `{entry['rule_id']}` | {entry['status'].replace('_', ' ')} | "
+                         f"{_markdown_table_cell(detail) or '—'} |")
+        lines.append("")
+
+    return "\n".join(lines)

pcba/requirements.py

@@ -0,0 +1,320 @@
+"""`pcba-requirements.toml`: what a project promises that its files cannot say by themselves.
+
+A schematic names a rail `+3V3`, but only the designer knows it is 3.3 V +-5 %, that the board is
+assembled on one side, which signal each connector pin must carry, and which SPICE testbenches
+prove a filter. The KiCad rules read those promises from this optional file next to the project
+(the review root first, then the KiCad project folder). Without it, rail voltages come from
+power-symbol names (`+3V3`, `+24V`) and are labelled as inferred, and the checks that need a
+promise are listed as not checked.
+
+    version = 1
+
+    [rails."+3V3"]            # exact net name (or the label without its sheet path)
+    voltage = 3.3
+    tolerance = 0.05          # or min = 3.135 / max = 3.465
+
+    [derating]                # maximum applied/rated ratio; defaults shown
+    ceramic = 0.5
+    electrolytic = 0.8
+    tantalum = 0.5
+    film = 0.7
+    resistor_power = 0.5
+
+    [board]
+    assembly = "single-sided" # or "double-sided"
+    smd_edge_clearance_mm = 5.0
+    test_points = "advisory"  # "required", "advisory" or "off"
+    test_point_exempt = ["GND"]
+
+    [[connectors]]
+    ref = "J1"
+    interface = "debug"
+    pins = { "1" = "+3V3", "2" = "SWDIO", "3" = "SWCLK", "4" = "GND", "5" = "NC" }
+
+    [[simulations]]
+    name = "sense divider"
+    netlist = "sim/divider.cir"   # ngspice deck; prints `name = value` lines
+    measure = "vout"
+    pass = [3.25, 3.35]
+    warn = [3.20, 3.40]
+    timeout_s = 30
+
+    [components]
+    databases = ["parts/components.json"]   # extra component data, same schema as the shipped file
+    assign = { U1 = "generic-mcu-3v3" }     # reference -> component id
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import math
+import re
+import tomllib
+from pathlib import Path
+from typing import Any
+
+FILE_NAME = "pcba-requirements.toml"
+
+DERATING_DEFAULTS = {
+    "ceramic": 0.5,          # MLCC (X7R, X5R, C0G ...): applied voltage at most half the rating
+    "electrolytic": 0.8,
+    "tantalum": 0.5,
+    "film": 0.7,
+    "polymer": 0.8,
+    "resistor_power": 0.5,
+}
+TEST_POINT_MODES = ("required", "advisory", "off")
+ASSEMBLY_MODES = ("single-sided", "double-sided")
+
+
+class RequirementsError(ValueError):
+    """The requirements file is malformed."""
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class Rail:
+    name: str
+    voltage: float
+    low: float
+    high: float
+    source: str              # "requirements" or "net name"
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class Connector:
+    ref: str
+    interface: str
+    pins: dict[str, str]
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class Testbench:
+    name: str
+    netlist: str
+    measure: str
+    passing: tuple[float, float]
+    warning: tuple[float, float] | None
+    timeout_s: float
+
+
+@dataclasses.dataclass(slots=True)
+class Requirements:
+    path: Path | None = None
+    rails: dict[str, Rail] = dataclasses.field(default_factory=dict)
+    derating: dict[str, float] = dataclasses.field(default_factory=lambda: dict(DERATING_DEFAULTS))
+    assembly: str | None = None
+    smd_edge_clearance_mm: float | None = None
+    test_points: str = "advisory"
+    test_point_exempt: tuple[str, ...] = ()
+    connectors: list[Connector] = dataclasses.field(default_factory=list)
+    simulations: list[Testbench] = dataclasses.field(default_factory=list)
+    databases: tuple[Path, ...] = ()
+    assign: dict[str, str] = dataclasses.field(default_factory=dict)
+
+    def rail(self, net_name: str | None, label: str | None = None) -> Rail | None:
+        """The voltage of a net: the requirements file first, then the net's name."""
+        for key in (net_name, label):
+            if key and key in self.rails:
+                return self.rails[key]
+        for key in (label, net_name):
+            if not key:
+                continue
+            bare = key.rsplit("/", 1)[-1]
+            if is_ground(bare):
+                return Rail(bare, 0.0, 0.0, 0.0, "net name")
+            voltage = voltage_from_name(bare)
+            if voltage is not None:
+                return Rail(bare, voltage, voltage, voltage, "net name")
+        return None
+
+
+_GROUND = re.compile(r"^(?:[ADPSC]?GND[A-Z0-9]*|GND[_-].*|.*[_-]GND|VSS[A-Z0-9]*|0V|EARTH|PE|CHASSIS)$", re.I)
+_VOLTAGE = re.compile(r"^[+-]?(\d+)(?:[.p](\d+))?V(\d+)?$", re.I)
+
+
+def is_ground(name: str | None) -> bool:
+    return bool(name and _GROUND.match(name.rsplit("/", 1)[-1]))
+
+
+def voltage_from_name(name: str | None) -> float | None:
+    """`+3V3` -> 3.3, `+24V_F` -> 24, `-12V` -> -12, `+1V8` -> 1.8, `3.3V` -> 3.3; else None.
+
+    Only a token that is a voltage by itself counts, as the first token or after the rail name
+    (`VCC_3V3`); `V15_SENSE` or `VBUS_DIV` are not rails and stay unknown.
+    """
+    if not name:
+        return None
+    bare = name.rsplit("/", 1)[-1]
+    tokens = re.split(r"[_\s]", bare)
+    for index, token in enumerate(tokens[:2]):
+        match = _VOLTAGE.match(token)
+        if not match or (index == 1 and not re.match(r"^[A-Z]+\d*$", tokens[0], re.I)):
+            continue
+        whole, decimals, after = match.group(1), match.group(2), match.group(3)
+        if decimals and after:
+            continue
+        value = float(f"{whole}.{decimals or after or 0}")
+        return -value if token.startswith("-") else value
+    return None
+
+
+def _number(table: dict, key: str, where: str, *, positive: bool = False) -> float | None:
+    value = table.get(key)
+    if value is None:
+        return None
+    if isinstance(value, bool) or not isinstance(value, (int, float)) or not math.isfinite(value):
+        raise RequirementsError(f"{where}.{key} must be a number")
+    if positive and value <= 0:
+        raise RequirementsError(f"{where}.{key} must be positive")
+    return float(value)
+
+
+def _unknown(table: dict, allowed: set[str], where: str) -> None:
+    extra = sorted(set(table) - allowed)
+    if extra:
+        raise RequirementsError(f"unknown fields in {where}: {', '.join(extra)}")
+
+
+def _range(value: Any, where: str) -> tuple[float, float]:
+    if (not isinstance(value, list) or len(value) != 2
+            or any(isinstance(v, bool) or not isinstance(v, (int, float)) for v in value) or value[0] > value[1]):
+        raise RequirementsError(f"{where} must be [low, high] with low <= high")
+    return float(value[0]), float(value[1])
+
+
+def find(*directories: Path | str) -> Path | None:
+    for directory in directories:
+        if directory is None:
+            continue
+        candidate = Path(directory) / FILE_NAME
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+def load(path: Path | str | None) -> Requirements:
+    """Parse a requirements file; `None` gives the defaults."""
+    if path is None:
+        return Requirements()
+    path = Path(path)
+    try:
+        payload = tomllib.loads(path.read_text(encoding="utf-8"))
+    except OSError as exc:
+        raise RequirementsError(f"cannot read {path}: {exc}") from exc
+    except (UnicodeDecodeError, tomllib.TOMLDecodeError) as exc:
+        raise RequirementsError(f"invalid {path.name}: {exc}") from exc
+    _unknown(payload, {"version", "rails", "derating", "board", "connectors", "simulations", "components"},
+             FILE_NAME)
+    if payload.get("version") != 1:
+        raise RequirementsError(f"{FILE_NAME} version must be 1")
+    out = Requirements(path=path.resolve())
+
+    rails = payload.get("rails", {})
+    if not isinstance(rails, dict):
+        raise RequirementsError("rails must be a table of [rails.NAME] tables")
+    for name, table in rails.items():
+        where = f"rails.{name}"
+        if not isinstance(table, dict):
+            raise RequirementsError(f"{where} must be a table")
+        _unknown(table, {"voltage", "tolerance", "min", "max"}, where)
+        voltage = _number(table, "voltage", where)
+        if voltage is None:
+            raise RequirementsError(f"{where}.voltage is required")
+        tolerance = _number(table, "tolerance", where) or 0.0
+        if not 0 <= tolerance < 1:
+            raise RequirementsError(f"{where}.tolerance is a fraction between 0 and 1")
+        low = _number(table, "min", where)
+        high = _number(table, "max", where)
+        spread = abs(voltage) * tolerance
+        low = voltage - spread if low is None else low
+        high = voltage + spread if high is None else high
+        if not low <= voltage <= high:
+            raise RequirementsError(f"{where}: min <= voltage <= max does not hold")
+        out.rails[name] = Rail(name, voltage, low, high, "requirements")
+
+    derating = payload.get("derating", {})
+    if not isinstance(derating, dict):
+        raise RequirementsError("derating must be a table")
+    _unknown(derating, set(DERATING_DEFAULTS), "derating")
+    for key in derating:
+        value = _number(derating, key, "derating", positive=True)
+        if value is None or value > 1:
+            raise RequirementsError(f"derating.{key} is a ratio between 0 and 1")
+        out.derating[key] = value
+
+    board = payload.get("board", {})
+    if not isinstance(board, dict):
+        raise RequirementsError("board must be a table")
+    _unknown(board, {"assembly", "smd_edge_clearance_mm", "test_points", "test_point_exempt"}, "board")
+    assembly = board.get("assembly")
+    if assembly is not None and assembly not in ASSEMBLY_MODES:
+        raise RequirementsError(f"board.assembly must be one of {', '.join(ASSEMBLY_MODES)}")
+    out.assembly = assembly
+    out.smd_edge_clearance_mm = _number(board, "smd_edge_clearance_mm", "board", positive=True)
+    mode = board.get("test_points", "advisory")
+    if mode not in TEST_POINT_MODES:
+        raise RequirementsError(f"board.test_points must be one of {', '.join(TEST_POINT_MODES)}")
+    out.test_points = mode
+    exempt = board.get("test_point_exempt", [])
+    if not isinstance(exempt, list) or any(not isinstance(v, str) for v in exempt):
+        raise RequirementsError("board.test_point_exempt must be a list of net names")
+    out.test_point_exempt = tuple(exempt)
+
+    connectors = payload.get("connectors", [])
+    if not isinstance(connectors, list):
+        raise RequirementsError("connectors must be an array of [[connectors]] tables")
+    for index, table in enumerate(connectors):
+        where = f"connectors[{index}]"
+        if not isinstance(table, dict):
+            raise RequirementsError(f"{where} must be a table")
+        _unknown(table, {"ref", "interface", "pins"}, where)
+        ref, pins = table.get("ref"), table.get("pins")
+        if not isinstance(ref, str) or not ref:
+            raise RequirementsError(f"{where}.ref is required")
+        if not isinstance(pins, dict) or not pins or any(not isinstance(v, str) for v in pins.values()):
+            raise RequirementsError(f"{where}.pins must map pin numbers to signal names")
+        out.connectors.append(Connector(ref, str(table.get("interface", "")), {str(k): v for k, v in pins.items()}))
+
+    simulations = payload.get("simulations", [])
+    if not isinstance(simulations, list):
+        raise RequirementsError("simulations must be an array of [[simulations]] tables")
+    for index, table in enumerate(simulations):
+        where = f"simulations[{index}]"
+        if not isinstance(table, dict):
+            raise RequirementsError(f"{where} must be a table")
+        _unknown(table, {"name", "netlist", "measure", "pass", "warn", "timeout_s"}, where)
+        for key in ("name", "netlist", "measure"):
+            if not isinstance(table.get(key), str) or not table[key]:
+                raise RequirementsError(f"{where}.{key} is required")
+        if not re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*", table["measure"]):
+            raise RequirementsError(f"{where}.measure must be a plain identifier")
+        passing = _range(table.get("pass"), f"{where}.pass")
+        warning = _range(table["warn"], f"{where}.warn") if "warn" in table else None
+        if warning and not (warning[0] <= passing[0] and passing[1] <= warning[1]):
+            raise RequirementsError(f"{where}.warn must contain the pass range")
+        timeout = _number(table, "timeout_s", where, positive=True) or 30.0
+        out.simulations.append(Testbench(table["name"], table["netlist"], table["measure"], passing, warning,
+                                         min(timeout, 600.0)))
+
+    components = payload.get("components", {})
+    if not isinstance(components, dict):
+        raise RequirementsError("components must be a table")
+    _unknown(components, {"databases", "assign"}, "components")
+    databases = components.get("databases", [])
+    if not isinstance(databases, list) or any(not isinstance(v, str) for v in databases):
+        raise RequirementsError("components.databases must be a list of paths")
+    root = path.parent.resolve()
+    resolved = []
+    for value in databases:
+        candidate = (root / value).resolve()
+        try:
+            candidate.relative_to(root)
+        except ValueError as exc:
+            raise RequirementsError(f"components.databases must stay inside the project: {value}") from exc
+        resolved.append(candidate)
+    out.databases = tuple(resolved)
+    assign = components.get("assign", {})
+    if not isinstance(assign, dict) or any(not isinstance(v, str) for v in assign.values()):
+        raise RequirementsError("components.assign must map references to component ids")
+    out.assign = dict(assign)
+    return out