enginehall 2.0.0__py3-none-any.whl

pcba/parsers/altium/netlist.py

@@ -0,0 +1,302 @@
+"""Extract a full netlist from Altium schematic sheets, binary or ASCII.
+
+The pin map (`pinmap.py`) resolves one MCU's pins. This resolves every placed pin of every
+component into nets with the same sheet resolver (`_sheet.resolve`): the same format traps
+(the designator child record, the multi-part filter, the pin's electrical end,
+point-to-segment wire contact) and the same anchors and naming precedence. A node is
+`(component designator, pin designator)`, e.g. `("J1", "1")`.
+
+What connects (on one sheet, as in the pin map)
+-----------------------------------------------
+- Wires (RECORD=27), point-to-segment: a pin end, label anchor, junction or another wire's
+  vertex lying on a segment's interior joins it.
+- Junctions (RECORD=29) join every wire passing through them, so two crossing wires connect
+  only where a junction sits.
+- Pins whose electrical ends coincide connect directly, without a wire.
+- Net labels (RECORD=25), power ports (RECORD=17) and ports (RECORD=18) name the net their
+  anchor touches. A port touches at both ends: `Location`, and `Width` further along +X for
+  the horizontal styles 0-3 or along +Y for the vertical styles 4-7.
+
+Assumptions, stated because each one changes the answer
+-------------------------------------------------------
+- Flat project, global names. Net labels, power ports and ports are global: the same name
+  on two sheets is one net, as in Altium's "Global" net-identifier scope. Sheet symbols and
+  sheet entries are ignored, so a hierarchical design's sheet-local labels would be merged
+  by name. Identifier types have separate namespaces: a power port, label and port with
+  the same text join only when physically connected by sheet geometry.
+- Naming precedence when one net carries several names: power port, then net label, then
+  port; the lexicographically smallest name within that rank (`_sheet.precedence`, which
+  the pin map uses too). Every net with more than one name is listed in
+  `Netlist.conflicts`; one of those names is wrong or a deliberate tie.
+- An unnamed net is called `Net<Designator>_<Pin>` after its naturally lowest node, as
+  Altium does (`NetJ1_1`). Should that collide with a name on the sheets, `_1`, `_2`, ...
+  is appended.
+- A net with a single node is not a net. It goes to `Netlist.unconnected` with the name it
+  carries, if any, and never to `Netlist.nets`.
+- A pin needs both a component designator and a pad designator to be a node. One drawn
+  more than once (an unannotated `R?`, a duplicated designator, a part placed twice) is
+  listed in `Netlist.duplicates`; the netlist cannot tell those pads apart.
+- Distinct multi-node nets choosing the same output name are a controlled extraction
+  error: the name-keyed export cannot represent them without inventing names or losing pins.
+- Hidden power pins are not handled: their implicit `HiddenNetName` connection is not
+  applied, so such a pin is unconnected unless something touches its end. Part-zero pins
+  (`OwnerPartId` 0, negative or absent: shared by every part of a symbol) are placed with
+  every placed part, by the same multi-part filter the pin map uses. With several parts of
+  one symbol placed, such a pin is one pad drawn more than once and is listed in
+  `Netlist.duplicates`.
+- Not modelled: buses and bus entries, harnesses, off-sheet connectors, net ties, and
+  series parts (the pin map's resistor inference is naming, not connectivity).
+
+This is the engine's netlist; the extension's `netlist/builder.ts` is a heuristic for
+display (it snaps labels within a radius) and is not what rules are tested against.
+"""
+
+from __future__ import annotations
+
+import collections
+import dataclasses
+from pathlib import Path
+
+from pcba.model.pinmap import natural_key
+from pcba.parsers.altium import _sheet
+from pcba.parsers.altium.records import (
+    REC_IMPLEMENTATION,
+    REC_PARAMETER,
+    SchDocError,
+    load_any_records,
+    text_of,
+)
+
+Node = tuple[str, str]  # (component designator, pin designator)
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class Net:
+    name: str
+    nodes: tuple[Node, ...]  # natural order
+    generated: bool  # the name is the `Net<Designator>_<Pin>` fallback, not from the sheets
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class UnconnectedPin:
+    designator: str
+    pin: str
+    name: str  # the pin's own name, e.g. "PA5"
+    net: str | None  # a label, port or power-port name the lone pin carries, if any
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class NameConflict:
+    net: str  # the name chosen
+    names: tuple[str, ...]  # every name found on the net, sorted
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class Component:
+    designator: str
+    lib_ref: str
+    comment: str | None
+    footprint: str | None  # the current PCB implementation's model name
+    sheet: str  # file name of the first sheet it is drawn on
+
+
+@dataclasses.dataclass(slots=True)
+class Netlist:
+    source: str
+    sheets: list[str] = dataclasses.field(default_factory=list)
+    nets: dict[str, Net] = dataclasses.field(default_factory=dict)
+    unconnected: list[UnconnectedPin] = dataclasses.field(default_factory=list)
+    conflicts: list[NameConflict] = dataclasses.field(default_factory=list)
+    duplicates: list[Node] = dataclasses.field(default_factory=list)
+    components: dict[str, Component] = dataclasses.field(default_factory=dict)
+
+
+def extract_netlist(directory: Path | str) -> Netlist:
+    """Netlist of every `.SchDoc` directly in `directory` (not recursive), one flat project."""
+    directory = Path(directory)
+    sheets = sorted(directory.glob("*.SchDoc"))
+    if not sheets:
+        raise SchDocError(f"no .SchDoc under {directory}")
+    return _build(sheets, source=str(directory))
+
+
+def extract_sheet(path: Path | str) -> Netlist:
+    """Netlist of a single sheet, on its own."""
+    path = Path(path)
+    return _build([path], source=str(path))
+
+
+def to_dict(netlist: Netlist) -> dict:
+    """A JSON-ready shape; every list and mapping is in natural order."""
+    return {
+        "sheets": list(netlist.sheets),
+        "nets": {
+            name: [list(node) for node in net.nodes] for name, net in netlist.nets.items()
+        },
+        "unconnected": [
+            {"designator": u.designator, "pin": u.pin, "name": u.name, "net": u.net}
+            for u in netlist.unconnected
+        ],
+        "conflicts": [{"net": c.net, "names": list(c.names)} for c in netlist.conflicts],
+        "duplicates": [list(node) for node in netlist.duplicates],
+        "components": {
+            c.designator: {
+                "lib_ref": c.lib_ref,
+                "comment": c.comment,
+                "footprint": c.footprint,
+                "sheet": c.sheet,
+            }
+            for c in netlist.components.values()
+        },
+    }
+
+
+def _node_key(node: Node) -> tuple:
+    return (natural_key(node[0]), natural_key(node[1]), node)
+
+
+def _name_key(name: str) -> tuple:
+    return (natural_key(name), name)
+
+
+def _build(paths: list[Path], source: str) -> Netlist:
+    # A sheet-local cluster is ("sheet", i, root). A name joins every cluster it touches, on
+    # any sheet: the pin map joins by name within one sheet, this across all of them.
+    placements: list[tuple[Node, str, tuple]] = []
+    named: list[tuple[tuple, str, int]] = []
+    components: dict[str, Component] = {}
+    for index, path in enumerate(paths):
+        pins, names, comps = _read_sheet(path)
+        for node, pin_name, root in pins:
+            placements.append((node, pin_name, ("sheet", index, root)))
+        named += [(("sheet", index, root), name, rank) for root, name, rank in names]
+        for comp in comps:
+            components.setdefault(comp.designator, comp)
+    nets = _sheet.join_by_name(named)
+
+    members: dict = collections.defaultdict(list)
+    for node, pin_name, cluster in placements:
+        members[nets.uf.find(cluster)].append((node, pin_name))
+    names_on = nets.carried()
+
+    netlist = Netlist(source=source, sheets=[p.name for p in paths])
+    counts = collections.Counter(node for node, _, _ in placements)
+    netlist.duplicates = sorted((n for n, c in counts.items() if c > 1), key=_node_key)
+
+    anonymous: list[tuple[Node, ...]] = []
+    for root, found in members.items():
+        pin_names: dict[Node, str] = {}
+        for node, pin_name in found:
+            pin_names.setdefault(node, pin_name)
+        nodes = tuple(sorted(pin_names, key=_node_key))
+        carried = names_on.get(root, set())
+        chosen = nets.winner(root) if carried else None
+        if len(carried) > 1:
+            netlist.conflicts.append(NameConflict(chosen, tuple(sorted(carried))))
+        if len(nodes) == 1:
+            designator, pin = nodes[0]
+            netlist.unconnected.append(
+                UnconnectedPin(designator, pin, pin_names[nodes[0]], chosen)
+            )
+        elif chosen is not None:
+            if chosen in netlist.nets:
+                raise SchDocError(
+                    f"distinct nets choose the same output name {chosen!r}; "
+                    "resolve the naming ambiguity before exporting"
+                )
+            netlist.nets[chosen] = Net(chosen, nodes, generated=False)
+        else:
+            anonymous.append(nodes)
+
+    # Named nets first, so a generated name never displaces a name from the sheets.
+    for nodes in sorted(anonymous, key=lambda ns: _node_key(ns[0])):
+        name = base = f"Net{nodes[0][0]}_{nodes[0][1]}"
+        suffix = 0
+        while name in netlist.nets:
+            suffix += 1
+            name = f"{base}_{suffix}"
+        netlist.nets[name] = Net(name, nodes, generated=True)
+
+    netlist.nets = dict(sorted(netlist.nets.items(), key=lambda item: _name_key(item[0])))
+    netlist.unconnected.sort(key=lambda u: _node_key((u.designator, u.pin)))
+    netlist.conflicts.sort(key=lambda c: _name_key(c.net))
+    netlist.components = dict(
+        sorted(components.items(), key=lambda item: _name_key(item[0]))
+    )
+    return netlist
+
+
+def _read_sheet(
+    path: Path,
+) -> tuple[list[tuple[Node, str, tuple]], list[tuple[tuple, str, int]], list[Component]]:
+    """One sheet's (pin placements, names, components), clustered by local geometry."""
+    records = load_any_records(path)
+    sheet = _sheet.resolve(path, records)
+    placements = [
+        ((p["designator"], p["num"]), p["name"], sheet.root(p["hot"]))
+        for p in sheet.pins
+        if p["designator"] and p["num"]
+    ]
+    return placements, sheet.names, _components(path, records, sheet.components, sheet.designators)
+
+
+def _components(
+    path: Path,
+    records: list[dict[str, str]],
+    comps: dict[int, dict[str, str]],
+    designators: dict[int, str],
+) -> list[Component]:
+    params: dict[int, dict[str, str]] = collections.defaultdict(dict)
+    footprints: dict[int, str] = {}
+    for index, fields in enumerate(records):
+        kind = fields.get("RECORD")
+        if kind == REC_PARAMETER and fields.get("OwnerIndex"):
+            owner = int(fields["OwnerIndex"]) + 1
+            if owner in comps:
+                params[owner].setdefault(fields.get("Name", "").strip().lower(), text_of(fields))
+        elif (
+            kind == REC_IMPLEMENTATION
+            and fields.get("ModelType", "").upper() == "PCBLIB"
+            and fields.get("IsCurrent", "").upper() in ("T", "TRUE")
+        ):
+            owner = _owning_component(records, index, comps)
+            if owner is not None and fields.get("ModelName"):
+                footprints.setdefault(owner, fields["ModelName"].strip())
+
+    out = []
+    for ci, fields in comps.items():
+        designator = designators.get(ci)
+        if not designator:
+            continue
+        mine = params.get(ci, {})
+        comment = mine.get("comment") or (
+            fields.get("%UTF8%Comment") or fields.get("Comment", "")
+        ).strip()
+        if comment.startswith("="):  # "=Value": the comment shows another parameter
+            comment = mine.get(comment[1:].strip().lower(), comment)
+        out.append(
+            Component(
+                designator=designator,
+                lib_ref=fields.get("LibReference", ""),
+                comment=comment or None,
+                footprint=footprints.get(ci),
+                sheet=path.name,
+            )
+        )
+    return out
+
+
+def _owning_component(
+    records: list[dict[str, str]], index: int, comps: dict[int, dict[str, str]]
+) -> int | None:
+    """Walk OwnerIndex up from an implementation (45 -> 44 list -> 1 component)."""
+    for _ in range(4):
+        owner = records[index].get("OwnerIndex", "")
+        if not owner:
+            return None
+        index = int(owner) + 1
+        if index in comps:
+            return index
+        if not 0 <= index < len(records):
+            return None
+    return None

pcba/parsers/altium/pinmap.py

@@ -0,0 +1,336 @@
+"""Extract an MCU pin -> net map from binary Altium schematic sheets.
+
+The schematic is the authoritative source for pin assignment: the board gets built from it.
+Reading it directly means the pin map, the `.ioc` and the firmware can all be checked
+against one artifact instead of three hand-maintained ones.
+
+The one trap that matters most
+------------------------------
+A multi-part symbol's component record carries the pins of EVERY part, all at the same
+symbol-local coordinates. A 176-pin MCU is typically a 4-part symbol. Only pins whose
+`OwnerPartId` equals that instance's `CurrentPartId` are actually placed here, plus Altium's
+part zero (`OwnerPartId` 0, negative or absent), which every part shares. Without that
+filter, part 1's PA* pins and part 2's PE* pins land on identical coordinates and merge into
+one nonsense net — and nothing about the output looks wrong.
+"""
+
+from __future__ import annotations
+
+import collections
+import math
+import re
+from pathlib import Path
+
+from pcba.model.pinmap import Pin, Resolution, SchematicPinMap, is_power_pin, natural_key
+from pcba.parsers.altium import _sheet
+from pcba.parsers.altium.geometry import NEAR_MISS, key
+from pcba.parsers.altium.records import (
+    REC_COMPONENT,
+    REC_DESIGNATOR,
+    SchDocError,
+    contains_part,
+    load_records,
+    text_of,
+)
+
+
+# Resistor symbols by library reference: `Res1`/`Res2`/`Res3` and `Res Semi` from Altium's
+# Miscellaneous Devices, `RES`, `Resistor_0603`, `R_0603`, `R`. A capacitor, diode, or ferrite
+# is not a series element for net naming, so only these support a series inference.
+_RESISTOR = re.compile(r"(?:RES(?:ISTOR)?\d*|R)(?:[_ -].*)?", re.I)
+
+
+def _resolve_sheet(path: Path, part_hint: str, component: str | None = None) -> tuple[dict[str, Pin], dict]:
+    """Resolve one sheet. Returns (pins keyed by package pin, near-miss report).
+
+    Connectivity and naming come from `_sheet.resolve`, the resolver `enginehall altium netlist`
+    uses too: net labels, power ports and ports name a net (power port first, then label, then
+    port; the smallest text within a rank), junctions and port ends join it, and clusters on
+    this sheet that share a name are one net. Unlike the netlist, the pin map does not join
+    names across sheets: in a hierarchical design that would merge sheet-local nets.
+    """
+    sheet = _sheet.resolve(path, load_records(path))
+    mcu_components = {
+        ci for ci, fields in sheet.components.items()
+        if part_hint in fields.get("LibReference", "")
+        # "U1" lives in a child record, not on the component. See records.py.
+        and (component is None or sheet.designators.get(ci) == component)
+    }
+    pins = sheet.pins
+
+    hot_counts = collections.Counter(key(p["hot"]) for p in pins)
+    net_of_root = sheet.named()
+
+    # Only explicitly identified resistor symbols support a series inference.
+    # Other two-pin devices do not establish conductive connectivity.
+    by_component = collections.defaultdict(list)
+    for p in pins:
+        by_component[p["ci"]].append(p)
+    adjacency = collections.defaultdict(list)
+    for _ci, ps in by_component.items():
+        if len(ps) == 2 and _RESISTOR.fullmatch(ps[0]["lib"]):
+            a, b = sheet.root(ps[0]["hot"]), sheet.root(ps[1]["hot"])
+            adjacency[a].append(b)
+            adjacency[b].append(a)
+
+    out: dict[str, Pin] = {}
+    for p in pins:
+        if p["ci"] not in mcu_components or not p["num"]:
+            continue
+        root = sheet.root(p["hot"])
+        net, how = net_of_root.get(root), Resolution.DIRECT
+        if not net:
+            reachable = [net_of_root[n] for n in adjacency.get(root, []) if net_of_root.get(n)]
+            if len(reachable) == 1:
+                net, how = reachable[0], Resolution.SERIES_R
+            elif reachable:
+                net, how = "(" + " / ".join(reachable) + ")", Resolution.AMBIGUOUS
+            else:
+                net, how = None, Resolution.NONE
+        out[p["num"]] = Pin(
+            name=p["name"],
+            package_pin=p["num"],
+            net=net,
+            resolution=how,
+            sheet=str(path),
+            component=p["designator"] or None,
+            connected=(
+                key(p["hot"]) in sheet.wire_contacts
+                or hot_counts[key(p["hot"])] > 1
+                or root in net_of_root
+            ),
+        )
+
+    # Open-circuit detector: a non-MCU hot end that lands NEAR an MCU hot end without
+    # touching it is a placement slip. Two constraints keep this from crying wolf:
+    #   - Axis-aligned only. A diagonal neighbour at 10*sqrt(2) is a different grid point,
+    #     not a slip, so requiring dx==0 or dy==0 drops those.
+    #   - The caller intersects with resolution == NONE. A pin that still resolves to a net
+    #     is connected regardless of what else sits nearby.
+    mcu_hots = {key(p["hot"]): p for p in pins if p["ci"] in mcu_components}
+    other_hots = [p for p in pins if p["ci"] not in mcu_components]
+    exact = sum(1 for p in other_hots if key(p["hot"]) in mcu_hots)
+    near: dict[str, dict] = {}
+    for p in other_hots:
+        if key(p["hot"]) in mcu_hots:
+            continue
+        for (hx, hy), mp in mcu_hots.items():
+            dx, dy = p["hot"][0] - hx, p["hot"][1] - hy
+            if not mp["num"]:
+                continue
+            if (dx == 0 or dy == 0) and 0 < math.hypot(dx, dy) <= NEAR_MISS:
+                near.setdefault(
+                    mp["num"],
+                    {
+                        "mcu_pin": mp["name"],
+                        "package_pin": mp["num"],
+                        "gap": round(math.hypot(dx, dy), 2),
+                        "sheet": str(path),
+                    },
+                )
+    return out, {"exact": exact, "near": list(near.values())}
+
+
+def detect_part(directory: Path, hint: str = "STM32") -> str | None:
+    """Find the MCU's orderable part number by scanning component records.
+
+    Beats hardcoding a part per project, and beats asking the user for something the file
+    already knows.
+    """
+    for sheet in sorted(directory.glob("*.SchDoc")):
+        try:
+            records = load_records(sheet)
+        except SchDocError:
+            continue
+        for fields in records:
+            if fields.get("RECORD") != REC_COMPONENT:
+                continue
+            for field in ("SourceLibReference", "LibReference", "Comment", "%UTF8%Comment"):
+                value = fields.get(field, "")
+                if value.startswith(hint) and len(value) > len(hint):
+                    return value
+    return None
+
+
+def detect_parts(directory: Path, hint: str = "STM32") -> list[tuple[str, Path]]:
+    """Distinct MCU symbol references and their first sheets, for identity checks."""
+    found: dict[str, Path] = {}
+    for sheet in sorted(Path(directory).glob("*.SchDoc")):
+        try:
+            records = load_records(sheet)
+        except SchDocError:
+            continue
+        for fields in records:
+            if fields.get("RECORD") != REC_COMPONENT:
+                continue
+            value = fields.get("LibReference") or fields.get("SourceLibReference", "")
+            if value.startswith(hint) and len(value) > len(hint):
+                found.setdefault(value, sheet)
+    return list(found.items())
+
+
+def extract(
+    directory: Path,
+    part: str,
+    part_hint: str | None = None,
+    component: str | None = None,
+) -> SchematicPinMap:
+    """Build a pin map for `part` from every `.SchDoc` in `directory`.
+
+    `part_hint` selects which components count as "the MCU" by LibReference substring; it
+    defaults to the part's family prefix, which is what a symbol library normally uses.
+    """
+    directory = Path(directory)
+    sheets = sorted(directory.glob("*.SchDoc"))
+    if not sheets:
+        raise SchDocError(f"no .SchDoc under {directory}")
+
+    if not part_hint:
+        family = re.match(r"^([A-Za-z]+\d*)", part or "")
+        if not family:
+            raise SchDocError(f"cannot derive an MCU family from part {part!r}; pass --part")
+        part_hint = family.group(1)
+
+    # The MCU is drawn on only a couple of sheets; skip the rest rather than hardcoding names.
+    mcu_sheets = [s for s in sheets if contains_part(s, part)]
+
+    # Sheets exist but none draws the MCU: a renamed part, a moved directory, or a bad
+    # --dir. Falling through would produce an empty map and let a check pass having
+    # validated no pins at all.
+    if not mcu_sheets:
+        raise SchDocError(
+            f"none of the {len(sheets)} .SchDoc under {directory} contains {part}. "
+            "Wrong --part, wrong --schematic-dir, or the symbol was renamed."
+        )
+
+    instances: set[str] = set()
+    selected_sheets = []
+    for sheet in mcu_sheets:
+        records = load_records(sheet)
+        designators = {
+            int(f["OwnerIndex"]) + 1: text_of(f) for f in records
+            if f.get("RECORD") == REC_DESIGNATOR and f.get("OwnerIndex")
+        }
+        matched = False
+        for index, fields in enumerate(records):
+            if fields.get("RECORD") != REC_COMPONENT or part_hint not in fields.get("LibReference", ""):
+                continue
+            name = designators.get(index)
+            if component is not None and name != component:
+                continue
+            # An unannotated designator (`U?`) names no instance: two of them are two MCUs.
+            annotated = name and "?" not in name
+            instances.add(name if annotated else f"{name or 'unnamed'} ({sheet.name} record {index})")
+            matched = True
+        if matched:
+            selected_sheets.append(sheet)
+    if not instances:
+        raise SchDocError("selected MCU component was not found; check --schematic-component")
+    if len(instances) > 1:
+        raise SchDocError(
+            "several MCU instances found (" + ", ".join(sorted(instances))
+            + "); annotate the schematic or select one with --schematic-component"
+        )
+    pin_map = SchematicPinMap(part=part, source=str(directory))
+    for sheet in selected_sheets:
+        pins, slip = _resolve_sheet(sheet, part_hint, component)
+        for number, pin in pins.items():
+            previous = pin_map.pins.get(number)
+            if previous and (previous.name, previous.net, previous.resolution) != (pin.name, pin.net, pin.resolution):
+                raise SchDocError(f"conflicting MCU package pin {number} across sheets")
+            pin_map.pins[number] = pin
+        pin_map.near_misses += slip["near"]
+        pin_map.exact_landings += slip["exact"]
+    return pin_map
+
+
+def to_dict(pin_map: SchematicPinMap) -> dict:
+    """The JSON shape shared by `enginehall altium pinmap --format json` and the MCP tool.
+
+    One builder, because the two used to be separate literals that had already drifted. Pins are
+    keyed by pad, the one name that is unique: every VSS of a part shares its name, and keyed by
+    name an open supply pin vanished behind a connected one.
+    """
+    return {
+        "part": pin_map.part,
+        "source": pin_map.source,
+        "pins": {
+            p.package_pin: {
+                "package_pin": p.package_pin,
+                "port_pin": p.port_pin,
+                "name": p.name,
+                "net": p.net,
+                "resolution": str(p.resolution),
+                "sheet": Path(p.sheet).name,
+                "component": p.component,
+            }
+            for p in sorted(pin_map.pins.values(), key=lambda p: natural_key(p.package_pin))
+        },
+        "mislabelled": mislabelled(pin_map),
+        "suspected_open": suspected_opens(pin_map),
+        "exact_landings": pin_map.exact_landings,
+    }
+
+
+def suspected_opens(pin_map: SchematicPinMap) -> list[dict]:
+    """Near-misses that are actually open circuits.
+
+    A near-miss only means an open circuit if the pin also failed to resolve to any net.
+    Something sitting near a pin that IS connected is just an adjacent part.
+    """
+    return [
+        n
+        for n in pin_map.near_misses
+        if pin_map.pins.get(n["package_pin"])
+        and pin_map.pins[n["package_pin"]].resolution == Resolution.NONE
+    ]
+
+
+# --- Net-label naming convention -------------------------------------------------------
+#
+# Some designs prefix every net label with the pin it belongs to ("PA5_SPI1_SCK"). Where
+# that convention holds, a label whose prefix disagrees with the pin geometry places it on
+# is a real defect worth reporting.
+#
+# It is a *convention*, not a law, so it is detected rather than assumed. Asserting it on a
+# project that never adopted it would flag every net on the board.
+
+_PIN_PREFIX = re.compile(r"^(P[A-KN-Q]\d{1,2}(?:_C)?)_", re.IGNORECASE)
+
+
+def claimed_pin(net: str | None) -> str | None:
+    """Return the pin a net label claims to be on, if it claims one.
+
+    Case-insensitive, like signal normalization: `pa5_spi1_sck` claims PA5 as plainly as
+    `PA5_SPI1_SCK` does.
+    """
+    m = _PIN_PREFIX.match(net or "")
+    return m.group(1).upper() if m else None
+
+
+def uses_pin_prefix_convention(pin_map: SchematicPinMap, threshold: float = 0.5) -> bool:
+    """Does this design prefix net labels with the pin name?"""
+    nets = [
+        p.net for p in pin_map.pins.values() if p.net and not is_power_pin(p.name)
+    ]
+    if len(nets) < 8:  # too few to infer a convention from
+        return False
+    claimed = sum(1 for n in nets if claimed_pin(n))
+    return claimed / len(nets) >= threshold
+
+
+def mislabelled(pin_map: SchematicPinMap) -> list[tuple[str, str, str]]:
+    """(actual pin, pin the label claims, net text) for every disagreement.
+
+    Geometry wins; the label is wrong.
+    """
+    if not uses_pin_prefix_convention(pin_map):
+        return []
+    out = []
+    for pin in pin_map.pins.values():
+        if is_power_pin(pin.name):
+            continue
+        claim = claimed_pin(pin.net)
+        if claim and claim != pin.port_pin:
+            out.append((pin.port_pin, claim, pin.net))
+    return sorted(out)