traceforge-pcb 1.0.0__py3-none-any.whl

traceforge/bench/design.py

@@ -0,0 +1,439 @@
+"""A neutral view of a finished KiCad project: components, nets and board geometry.
+
+Everything here comes from KiCad's own files: the netlist that ``kicad-cli sch
+export netlist`` writes, and the ``.kicad_pcb`` board. Nothing depends on how the
+project was made, so any agent's output is read the same way.
+"""
+
+from __future__ import annotations
+
+import math
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from traceforge import sexpr
+from traceforge.kicad.pcb import pin_function
+
+GROUND_RE = re.compile(r"^(GND|GNDD|GNDA|DGND|AGND|PGND|GNDPWR|VSS|0V|GROUND)$", re.I)
+_LCSC_FIELD = re.compile(r"^(lcsc|jlc|jlcpcb)([ _#-]*(part|pn|code|no\.?|number|#))*$", re.I)
+_MPN_FIELD = re.compile(
+    r"^(mpn|mfr[ _.]*(part|pn|no\.?|number)?|manufacturer[ _]*part.*|part[ _]?number)$", re.I
+)
+
+
+@dataclass
+class Pin:
+    ref: str
+    pin: str
+    function: str = ""
+
+
+@dataclass
+class Component:
+    ref: str
+    value: str = ""
+    footprint: str = ""
+    lib: str = ""  # lib:part
+    description: str = ""
+    fields: dict[str, str] = field(default_factory=dict)
+    exclude_from_bom: bool = False
+
+    @property
+    def kind(self) -> str:
+        """Reference prefix: R, C, U, J, ... (``#PWR`` style refs give '#')."""
+        match = re.match(r"[A-Za-z#]+", self.ref)
+        return match.group(0).upper() if match else ""
+
+    def field_like(self, pattern: re.Pattern[str]) -> str:
+        for key, val in self.fields.items():
+            if pattern.match(key.strip()) and val.strip():
+                return val.strip()
+        return ""
+
+    @property
+    def lcsc(self) -> str:
+        return self.field_like(_LCSC_FIELD)
+
+    @property
+    def mpn(self) -> str:
+        return self.field_like(_MPN_FIELD)
+
+    def text(self) -> str:
+        """Everything that names the part, for selector matching."""
+        bits = [self.value, self.lib, self.lib.split(":")[-1], self.mpn, self.description]
+        return " | ".join(b for b in bits if b)
+
+
+@dataclass
+class Netlist:
+    components: dict[str, Component] = field(default_factory=dict)
+    nets: dict[str, list[Pin]] = field(default_factory=dict)
+    source: str = ""  # schematic | pcb
+
+    def net_of(self, ref: str, pin: str) -> str | None:
+        for name, pins in self.nets.items():
+            if any(p.ref == ref and p.pin == pin for p in pins):
+                return name
+        return None
+
+    def pins_of(self, ref: str) -> list[tuple[Pin, str]]:
+        return [(p, name) for name, pins in self.nets.items() for p in pins if p.ref == ref]
+
+    def node_sets(
+        self, ignore_refs: set[str] = frozenset()
+    ) -> dict[str, frozenset[tuple[str, str]]]:
+        out = {}
+        for name, pins in self.nets.items():
+            nodes = frozenset((p.ref, p.pin) for p in pins if p.ref not in ignore_refs)
+            if len(nodes) >= 2:
+                out[name] = nodes
+        return out
+
+
+def clean_net(name: str) -> str:
+    return name[1:] if name.startswith("/") and name.count("/") == 1 else name
+
+
+def is_ground(name: str) -> bool:
+    return bool(GROUND_RE.match(clean_net(name).lstrip("+")))
+
+
+def parse_kicad_netlist(text: str) -> Netlist:
+    """Parse a ``kicadsexpr`` netlist (``kicad-cli sch export netlist``)."""
+    root = sexpr.parse(text)
+    out = Netlist(source="schematic")
+    comps = sexpr.find(root, "components") or []
+    for comp in sexpr.find_all(comps, "comp"):
+        ref = str(sexpr.value(comp, "ref", ""))
+        lib = sexpr.find(comp, "libsource")
+        fields: dict[str, str] = {}
+        for fnode in sexpr.find_all(sexpr.find(comp, "fields") or [], "field"):
+            key = str(sexpr.value(fnode, "name", ""))
+            vals = [c for c in fnode[1:] if isinstance(c, str)]
+            fields[key] = str(vals[-1]) if vals else ""
+        props = {
+            str(sexpr.value(p, "name", "")): str(sexpr.value(p, "value", ""))
+            for p in sexpr.find_all(comp, "property")
+        }
+        for key, val in props.items():
+            if not key.startswith("ki_") and key not in {"Sheetname", "Sheetfile"}:
+                fields.setdefault(key, val)
+        out.components[ref] = Component(
+            ref=ref,
+            value=str(sexpr.value(comp, "value", "")),
+            footprint=str(sexpr.value(comp, "footprint", "")),
+            lib=f"{sexpr.value(lib, 'lib', '')}:{sexpr.value(lib, 'part', '')}" if lib else "",
+            description=str(
+                sexpr.value(comp, "description", "") or props.get("ki_description", "")
+            ),
+            fields=fields,
+            exclude_from_bom="exclude_from_bom" in props or "dnp" in props,
+        )
+    # Pin names per library part, for nodes that carry no "pinfunction" (newer KiCad
+    # versions do not always write it): (lib, part) -> {pin number: name}.
+    lib_pins: dict[tuple[str, str], dict[str, str]] = {}
+    for libpart in sexpr.find_all(sexpr.find(root, "libparts") or [], "libpart"):
+        key = (str(sexpr.value(libpart, "lib", "")), str(sexpr.value(libpart, "part", "")))
+        lib_pins[key] = {
+            str(sexpr.value(pin, "num", "")): str(sexpr.value(pin, "name", ""))
+            for pin in sexpr.find_all(sexpr.find(libpart, "pins") or [], "pin")
+        }
+    comp_lib = {}
+    for comp in sexpr.find_all(comps, "comp"):
+        lib = sexpr.find(comp, "libsource")
+        if lib:
+            comp_lib[str(sexpr.value(comp, "ref", ""))] = (
+                str(sexpr.value(lib, "lib", "")),
+                str(sexpr.value(lib, "part", "")),
+            )
+
+    def function(node) -> str:
+        ref, pin = str(sexpr.value(node, "ref", "")), str(sexpr.value(node, "pin", ""))
+        name = pin_function(sexpr.value(node, "pinfunction", ""), pin)
+        if name:
+            return name
+        found = lib_pins.get(comp_lib.get(ref, ("", "")), {}).get(pin, "")
+        return "" if found in {"~", pin} else found
+
+    nets = sexpr.find(root, "nets") or []
+    for net in sexpr.find_all(nets, "net"):
+        name = clean_net(str(sexpr.value(net, "name", "")))
+        out.nets[name] = [
+            Pin(str(sexpr.value(n, "ref", "")), str(sexpr.value(n, "pin", "")), function(n))
+            for n in sexpr.find_all(net, "node")
+        ]
+    return out
+
+
+# ----------------------------------------------------------------------- board
+
+
+@dataclass
+class Pad:
+    number: str
+    x: float
+    y: float
+    w: float
+    h: float
+    net: str = ""
+    function: str = ""
+    kind: str = ""
+
+
+@dataclass
+class Footprint:
+    ref: str
+    lib: str
+    value: str
+    x: float
+    y: float
+    rot: float
+    layer: str
+    pads: list[Pad] = field(default_factory=list)
+    points: list[tuple[float, float]] = field(default_factory=list)  # graphics, absolute
+    ref_visible: bool = True
+    fields: dict[str, str] = field(default_factory=dict)
+
+
+@dataclass
+class Board:
+    path: Path
+    copper_layers: list[str] = field(default_factory=list)
+    outline: tuple[float, float, float, float] | None = None  # x0, y0, x1, y1
+    footprints: list[Footprint] = field(default_factory=list)
+    track_length: dict[str, float] = field(default_factory=dict)
+    vias: int = 0
+    zones: list[str] = field(default_factory=list)
+
+    @property
+    def size(self) -> tuple[float, float] | None:
+        if not self.outline:
+            return None
+        x0, y0, x1, y1 = self.outline
+        return round(x1 - x0, 3), round(y1 - y0, 3)
+
+    def netlist(self) -> Netlist:
+        """The board's own netlist (pads grouped by net), for parity and fallback."""
+        out = Netlist(source="pcb")
+        for fp in self.footprints:
+            if fp.ref and not fp.ref.startswith("#"):
+                out.components.setdefault(
+                    fp.ref,
+                    Component(fp.ref, fp.value, fp.lib, fields=dict(fp.fields)),
+                )
+            for pad in fp.pads:
+                if pad.net and not pad.net.startswith("unconnected-"):
+                    pins = out.nets.setdefault(clean_net(pad.net), [])
+                    if not any(p.ref == fp.ref and p.pin == pad.number for p in pins):
+                        pins.append(Pin(fp.ref, pad.number, pad.function))
+        return out
+
+    def total_connections(self) -> int:
+        return sum(max(0, len(p) - 1) for p in self.netlist().nets.values())
+
+
+def _rotate(x: float, y: float, deg: float) -> tuple[float, float]:
+    # KiCad: positive angles are counter-clockwise on screen, with y pointing down.
+    a = math.radians(deg)
+    return x * math.cos(a) + y * math.sin(a), -x * math.sin(a) + y * math.cos(a)
+
+
+def _xy(node, key: str = "at") -> tuple[float, float, float]:
+    at = sexpr.find(node, key)
+    if not at:
+        return 0.0, 0.0, 0.0
+    vals = [sexpr.num(v) for v in at[1:4] if not isinstance(v, list)]
+    vals += [0.0] * (3 - len(vals))
+    return vals[0], vals[1], vals[2]
+
+
+def _layer(node) -> str:
+    return str(sexpr.value(node, "layer", ""))
+
+
+def _hidden(node) -> bool:
+    if any(isinstance(c, str) and c == "hide" for c in node):
+        return True
+    hide = sexpr.find(node, "hide")
+    if hide is not None and (len(hide) < 2 or str(hide[1]) == "yes"):
+        return True
+    effects = sexpr.find(node, "effects")
+    return bool(effects and (_hidden(effects) if effects is not node else False))
+
+
+def _graphic_points(node) -> list[tuple[float, float]]:
+    pts = []
+    for key in ("start", "end", "mid", "center"):
+        sub = sexpr.find(node, key)
+        if sub:
+            pts.append((sexpr.num(sub[1]), sexpr.num(sub[2])))
+    poly = sexpr.find(node, "pts")
+    if poly:
+        pts += [(sexpr.num(p[1]), sexpr.num(p[2])) for p in sexpr.find_all(poly, "xy")]
+    if sexpr.name(node) in {"gr_circle", "fp_circle"} and len(pts) >= 2:
+        (cx, cy), (ex, ey) = pts[0], pts[1]
+        r = math.hypot(ex - cx, ey - cy)
+        pts = [(cx - r, cy - r), (cx + r, cy + r)]
+    return pts
+
+
+def load_board(path: Path) -> Board:
+    root = sexpr.parse(path.read_text(encoding="utf-8"))
+    board = Board(path=path)
+    layers = sexpr.find(root, "layers") or []
+    for layer in layers[1:]:
+        if isinstance(layer, list) and len(layer) >= 3 and str(layer[1]).endswith(".Cu"):
+            board.copper_layers.append(str(layer[1]))
+    edge: list[tuple[float, float]] = []
+    for item in root[1:]:
+        head = sexpr.name(item)
+        if head and head.startswith("gr_") and _layer(item) == "Edge.Cuts":
+            edge += _graphic_points(item)
+    nets_by_id = {str(n[1]): str(n[2]) for n in sexpr.find_all(root, "net") if len(n) >= 3}
+    for fp_node in sexpr.find_all(root, "footprint") + sexpr.find_all(root, "module"):
+        fx, fy, frot = _xy(fp_node)
+        ref, value, ref_visible = "", "", False
+        fields: dict[str, str] = {}
+        for text in sexpr.find_all(fp_node, "fp_text"):
+            if len(text) >= 3 and text[1] in {"reference", "value"}:
+                if text[1] == "reference":
+                    ref = str(text[2])
+                    ref_visible = "Silk" in _layer(text) and not _hidden(text)
+                else:
+                    value = str(text[2])
+        for prop in sexpr.find_all(fp_node, "property"):
+            if len(prop) < 3:
+                continue
+            key, val = str(prop[1]), str(prop[2])
+            if key == "Reference":
+                ref = val
+                ref_visible = "Silk" in _layer(prop) and not _hidden(prop)
+            elif key == "Value":
+                value = val
+            else:
+                fields[key] = val
+        fp = Footprint(
+            ref=ref,
+            lib=str(fp_node[1]) if len(fp_node) > 1 else "",
+            value=value,
+            x=fx,
+            y=fy,
+            rot=frot,
+            layer=_layer(fp_node),
+            ref_visible=ref_visible,
+            fields=fields,
+        )
+        for pad in sexpr.find_all(fp_node, "pad"):
+            px, py, _ = _xy(pad)
+            dx, dy = _rotate(px, py, frot)
+            size = sexpr.find(pad, "size") or [None, 0, 0]
+            net = sexpr.find(pad, "net")
+            net_name = ""
+            if net and len(net) >= 3:
+                net_name = str(net[2])
+            elif net and len(net) == 2:
+                net_name = nets_by_id.get(str(net[1]), str(net[1]))
+            fp.pads.append(
+                Pad(
+                    number=str(pad[1]) if len(pad) > 1 else "",
+                    x=fx + dx,
+                    y=fy + dy,
+                    w=sexpr.num(size[1]),
+                    h=sexpr.num(size[2]),
+                    net=net_name,
+                    function=pin_function(sexpr.value(pad, "pinfunction", ""), str(pad[1])),
+                    kind=str(pad[2]) if len(pad) > 2 else "",
+                )
+            )
+        for item in fp_node:
+            head = sexpr.name(item)
+            if head and head.startswith("fp_") and head != "fp_text":
+                for x, y in _graphic_points(item):
+                    dx, dy = _rotate(x, y, frot)
+                    fp.points.append((fx + dx, fy + dy))
+                if _layer(item) == "Edge.Cuts":
+                    edge += [
+                        (fx + _rotate(x, y, frot)[0], fy + _rotate(x, y, frot)[1])
+                        for x, y in _graphic_points(item)
+                    ]
+        board.footprints.append(fp)
+    if edge:
+        xs, ys = [p[0] for p in edge], [p[1] for p in edge]
+        board.outline = (min(xs), min(ys), max(xs), max(ys))
+    for seg in sexpr.find_all(root, "segment") + sexpr.find_all(root, "arc"):
+        start, end = sexpr.find(seg, "start"), sexpr.find(seg, "end")
+        net = sexpr.find(seg, "net")
+        if not (start and end and net and len(net) >= 2):
+            continue
+        name = clean_net(nets_by_id.get(str(net[1]), str(net[1])))
+        length = math.hypot(
+            sexpr.num(end[1]) - sexpr.num(start[1]), sexpr.num(end[2]) - sexpr.num(start[2])
+        )
+        board.track_length[name] = board.track_length.get(name, 0.0) + length
+    board.vias = len(sexpr.find_all(root, "via"))
+    for zone in sexpr.find_all(root, "zone"):
+        board.zones.append(clean_net(str(sexpr.value(zone, "net_name", ""))))
+    return board
+
+
+def footprint_extent(fp: Footprint) -> tuple[float, float, float, float]:
+    xs = [p.x - p.w / 2 for p in fp.pads] + [p.x + p.w / 2 for p in fp.pads]
+    ys = [p.y - p.h / 2 for p in fp.pads] + [p.y + p.h / 2 for p in fp.pads]
+    xs += [p[0] for p in fp.points]
+    ys += [p[1] for p in fp.points]
+    if not xs:
+        return fp.x, fp.y, fp.x, fp.y
+    return min(xs), min(ys), max(xs), max(ys)
+
+
+def edge_distance(board: Board, fp: Footprint) -> float | None:
+    """How far the footprint's nearest extent is from the board outline (<= 0: overhangs)."""
+    if not board.outline:
+        return None
+    x0, y0, x1, y1 = board.outline
+    fx0, fy0, fx1, fy1 = footprint_extent(fp)
+    return round(min(fx0 - x0, fy0 - y0, x1 - fx1, y1 - fy1), 3)
+
+
+# ------------------------------------------------------------------ discovery
+
+_SKIP_DIRS = {"backups", "outputs", "preview", ".git", ".traceforge", "gerbers", "libraries"}
+
+
+def find_project(root: Path) -> tuple[Path | None, Path | None]:
+    """The main (schematic, board) pair in a workspace.
+
+    Prefers a board with a schematic of the same name, then the largest board,
+    then the shallowest path; ignores backup and output folders.
+    """
+    boards = [
+        p
+        for p in root.rglob("*.kicad_pcb")
+        if not any(
+            part in _SKIP_DIRS or part.endswith("-backups")
+            for part in p.relative_to(root).parts[:-1]
+        )
+    ]
+    schematics = [
+        p
+        for p in root.rglob("*.kicad_sch")
+        if not any(
+            part in _SKIP_DIRS or part.endswith("-backups")
+            for part in p.relative_to(root).parts[:-1]
+        )
+    ]
+    if not boards:
+        roots = [s for s in schematics if s.with_suffix(".kicad_pro").exists()] or schematics
+        roots.sort(key=lambda p: (len(p.parts), -p.stat().st_size))
+        return (roots[0] if roots else None), None
+    boards.sort(
+        key=lambda p: (
+            not p.with_suffix(".kicad_sch").exists(),
+            -p.stat().st_size,
+            len(p.parts),
+        )
+    )
+    board = boards[0]
+    sch = board.with_suffix(".kicad_sch")
+    return (sch if sch.exists() else None), board

traceforge/bench/kicad.py

@@ -0,0 +1,99 @@
+"""KiCad runs for scoring: netlist export and DRC with refilled zones.
+
+DRC always runs on a scratch copy, so scoring never modifies an agent's output.
+Zones are refilled first: kicad-cli 10+ does it with ``--refill-zones``; older
+versions refill through KiCad's own Python module (``pcbnew``) when it is
+installed, which is also how KiCad 7 runs DRC at all.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+from pathlib import Path
+
+from traceforge.bench.design import Netlist, parse_kicad_netlist
+from traceforge.kicad.cli import (
+    CheckReport,
+    KicadCli,
+    KicadCliError,
+    find_kicad_python,
+    parse_text_drc,
+)
+
+_REFILL_DRC = """
+import sys, pcbnew
+board = pcbnew.LoadBoard(sys.argv[1])
+zones = board.Zones()
+if len(zones):
+    pcbnew.ZONE_FILLER(board).Fill(zones)
+    board.Save(sys.argv[1])
+if len(sys.argv) > 2:
+    ok = pcbnew.WriteDRCReport(board, sys.argv[2], pcbnew.EDA_UNITS_MILLIMETRES, True)
+    sys.exit(0 if ok else 3)
+"""
+
+
+def export_netlist(cli: KicadCli, schematic: Path, out_dir: Path) -> Netlist:
+    out_dir.mkdir(parents=True, exist_ok=True)
+    output = out_dir / f"{schematic.stem}.net"
+    output.unlink(missing_ok=True)
+    completed = cli.run(
+        ["sch", "export", "netlist", "--format", "kicadsexpr", "-o", str(output), str(schematic)]
+    )
+    if not output.exists():
+        raise KicadCliError(
+            f"netlist export failed: {(completed.stderr or completed.stdout)[-800:]}"
+        )
+    return parse_kicad_netlist(output.read_text(encoding="utf-8"))
+
+
+def _copy_board(board: Path, out_dir: Path) -> Path:
+    dest = out_dir / "drc_copy"
+    shutil.rmtree(dest, ignore_errors=True)
+    dest.mkdir(parents=True)
+    for suffix in (".kicad_pcb", ".kicad_pro", ".kicad_dru", ".kicad_prl"):
+        src = board.with_suffix(suffix)
+        if src.exists():
+            shutil.copy2(src, dest / src.name)
+    return dest / board.name
+
+
+def _pcbnew(python: str, *args: str) -> subprocess.CompletedProcess[str]:
+    env = {**os.environ, "QT_QPA_PLATFORM": "offscreen"}
+    return subprocess.run(  # noqa: S603
+        [python, "-c", _REFILL_DRC, *args],
+        capture_output=True,
+        text=True,
+        timeout=900,
+        env=env,
+        check=False,
+    )
+
+
+def run_drc(cli: KicadCli, board: Path, out_dir: Path) -> tuple[CheckReport, dict]:
+    """DRC on a copy of ``board`` with zones refilled. Returns (report, how it ran)."""
+    copy = _copy_board(board, out_dir)
+    version = cli.version()
+    info = {"kicad": ".".join(map(str, version)), "zones_refilled": False, "engine": "kicad-cli"}
+    python = find_kicad_python() if version < (10, 0, 0) else None
+    if version < (8, 0, 0):
+        if python is None:
+            raise KicadCliError(
+                "DRC on KiCad 7 needs KiCad's Python module (set TRACEFORGE_KICAD_PYTHON)"
+            )
+        report_path = out_dir / f"{board.stem}-drc.txt"
+        report_path.unlink(missing_ok=True)
+        done = _pcbnew(python, str(copy.resolve()), str(report_path.resolve()))
+        if not report_path.exists():
+            raise KicadCliError(f"pcbnew DRC failed: {(done.stderr or done.stdout)[-1500:]}")
+        info.update(engine="pcbnew", zones_refilled=True)
+        return parse_text_drc(report_path), info
+    if python is not None:
+        done = _pcbnew(python, str(copy.resolve()))
+        info["zones_refilled"] = done.returncode == 0
+    else:
+        info["zones_refilled"] = version >= (10, 0, 0)
+    report = cli.drc(copy, out_dir, schematic_parity=False)
+    return report, info

traceforge/bench/partscheck.py

@@ -0,0 +1,159 @@
+"""Check the BOM's LCSC part numbers against the live catalogue.
+
+Every fact is tagged with where it came from: ``design`` (the project's own
+fields) or ``catalogue`` (what JLCPCB/LCSC answered, with the provider names).
+Only stable facts are scored (the code exists, its package fits the footprint,
+its value matches); stock and price are recorded but never scored, so a re-run
+next month gives the same number.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from traceforge.bench.checks import parse_value
+from traceforge.bench.design import Component, Netlist
+
+_NOT_ORDERABLE = re.compile(r"^(H|MH|TP|FID|LOGO|G|NT|JP\d*SJ|REF)$", re.I)
+_UNIT = {"R": "Ω", "C": "F", "L": "H"}
+_CAT_VALUE = re.compile(r"(\d+(?:\.\d+)?)\s*([pnuµμmkKM]?)\s*(Ω|ohm|F|H)\b", re.I)
+
+
+def bom_components(netlist: Netlist) -> list[Component]:
+    out = []
+    for ref, comp in sorted(netlist.components.items()):
+        if ref.startswith("#") or comp.exclude_from_bom or not comp.footprint:
+            continue
+        if _NOT_ORDERABLE.match(comp.kind) or re.search(
+            r"MountingHole|Fiducial|TestPoint", comp.footprint, re.I
+        ):
+            continue
+        out.append(comp)
+    return out
+
+
+def _catalogue_values(part, unit: str) -> list[float]:
+    text = " ".join([part.description, *part.attributes.values()])
+    out = []
+    for num, prefix, u in _CAT_VALUE.findall(text):
+        u = "Ω" if u.lower() in {"ohm", "ω"} else u.upper()
+        if u == unit:
+            value = parse_value(f"{num}{prefix}")
+            if value is not None:
+                out.append(value)
+    return out
+
+
+def _package_problems(comp: Component, part) -> list[str]:
+    try:
+        from traceforge.parts import packages
+
+        cat = packages.parse_catalog_package(
+            part.package, description=part.description, attributes=part.attributes
+        )
+        fp = packages.parse_footprint(comp.footprint)
+        mismatches = packages.compare(cat, fp, compare_pins=False)
+        return [f"{m.aspect}: {m.detail}" for m in mismatches if m.severity == "P0"]
+    except Exception:  # package parsing is best effort; never fail scoring on it
+        return []
+
+
+def check_component(comp: Component, report) -> dict[str, Any]:
+    entry: dict[str, Any] = {
+        "ref": comp.ref,
+        "design": {
+            "lcsc": comp.lcsc,
+            "value": comp.value,
+            "footprint": comp.footprint,
+            "mpn": comp.mpn,
+        },
+        "catalogue": None,
+        "checks": [],
+        "status": "no_code",
+        "score": 0.0,
+    }
+    if not comp.lcsc:
+        return entry
+    if report is None or (not report.answered):
+        entry["status"] = "unverified"
+        entry["score"] = None
+        entry["lookup"] = report.describe() if report is not None else "not looked up"
+        return entry
+    part = report.part
+    entry["lookup"] = report.describe()
+    if part is None:
+        entry["status"] = "not_found"
+        return entry
+    entry["catalogue"] = {
+        "lcsc": part.lcsc,
+        "mpn": part.mpn,
+        "manufacturer": part.manufacturer,
+        "package": part.package,
+        "description": part.description,
+        "library_type": part.library_type,
+        "stock": part.stock,
+        "lifecycle": part.lifecycle,
+        "sources": list(part.sources),
+        "stale": part.stale,
+    }
+    problems = _package_problems(comp, part)
+    for problem in problems:
+        entry["checks"].append(
+            {"check": "package", "ok": False, "source": "catalogue", "detail": problem}
+        )
+    unit = _UNIT.get(comp.kind)
+    want = parse_value(comp.value) if unit else None
+    if unit and want:
+        values = _catalogue_values(part, unit)
+        if values:
+            ok = any(abs(v - want) <= 0.02 * want for v in values)
+            entry["checks"].append(
+                {
+                    "check": "value",
+                    "ok": ok,
+                    "source": "catalogue",
+                    "detail": f"design {comp.value}, catalogue {', '.join(f'{v:g}' for v in values[:3])}",
+                }
+            )
+    if comp.mpn and part.mpn:
+        from traceforge.parts.providers.base import same_device
+
+        ok = same_device(comp.mpn, part.mpn)
+        entry["checks"].append(
+            {
+                "check": "mpn",
+                "ok": ok,
+                "source": "catalogue",
+                "detail": f"design {comp.mpn}, catalogue {part.mpn}",
+            }
+        )
+    bad = [c for c in entry["checks"] if not c["ok"]]
+    entry["status"] = "mismatch" if bad else "verified"
+    entry["score"] = 0.5 if bad else 1.0
+    return entry
+
+
+def verify_parts(netlist: Netlist, catalog=None, offline: bool = False) -> dict[str, Any]:
+    comps = bom_components(netlist)
+    codes = sorted({c.lcsc.strip().upper() for c in comps if c.lcsc})
+    reports: dict[str, Any] = {}
+    if codes and not offline:
+        if catalog is None:
+            from traceforge.parts import default_catalog
+
+            catalog = default_catalog()
+        reports = {code: catalog.lookup_report(code) for code in codes}
+    entries = [
+        check_component(c, reports.get(c.lcsc.strip().upper()) if c.lcsc else None) for c in comps
+    ]
+    scored = [] if offline else [e["score"] for e in entries if e["score"] is not None]
+    counts: dict[str, int] = {}
+    for e in entries:
+        counts[e["status"]] = counts.get(e["status"], 0) + 1
+    return {
+        "score": (sum(scored) / len(scored)) if scored else None,
+        "lines": len(entries),
+        "counts": counts,
+        "parts": entries,
+    }