enginehall 2.0.0__py3-none-any.whl

pcba/rules/kicad_schematic.py

@@ -0,0 +1,621 @@
+"""KiCad schematic rules: KiCad's own ERC, the netlist cross-check, and electrical checks ERC
+does not make (or makes only when its settings are right).
+
+Each rule reads the connectivity the engine built from wire geometry. Where kicad-cli is
+installed, `kicad.netlist.parity` compares that connectivity with KiCad's own netlist, so a
+reader mistake shows up as a finding rather than as a quietly wrong check.
+"""
+
+from __future__ import annotations
+
+import re
+from collections import defaultdict
+from collections.abc import Iterator
+
+from pcba.model.design import Net
+from pcba.model.finding import Detector, Domain, Evidence, Finding, Location, Severity
+from pcba.model.pinmap import Project
+from pcba.requirements import voltage_from_name
+from pcba.rules.kicad_common import (
+    at_component,
+    at_label,
+    at_net,
+    at_pin,
+    classify,
+    is_ground_net,
+    is_supply_rail,
+    net_display,
+    other_nets,
+    parts,
+    pin_label,
+    pin_numbers,
+    requirements,
+    schematic,
+    sheet_of,
+)
+
+EXTERNAL_CONFIDENCE = 0.95
+# Library-table and footprint-filter messages describe the machine that ran kicad-cli more than
+# the design; they are kept, as information.
+_CONFIGURATION = {"lib_symbol_issues", "lib_symbol_mismatch", "footprint_link_issues", "footprint_filter",
+                  "lib_footprint_issues", "lib_footprint_mismatch"}
+_ERC_CONSEQUENCE = {
+    "power_pin_not_driven": "KiCad cannot see where this rail is supplied; either a source is missing or the "
+                            "rail enters through a part KiCad does not treat as a source.",
+    "pin_not_connected": "An unconnected pin is either a missing wire or an intentionally open pin without a "
+                         "no-connect flag; the two cannot be told apart in review.",
+    "pin_not_driven": "An input with no driver floats on the board.",
+    "label_dangling": "A label that touches nothing names no net; the connection it suggests does not exist.",
+    "pin_to_pin": "Two pin types that must not meet are connected (for example two outputs).",
+}
+DC_PATH_KINDS = ("resistor", "inductor", "ferrite", "fuse", "jumper", "net_tie")
+DC_PATH_MAX_OHM = 1.0
+DC_PATH_DEPTH = 3
+_I2C = re.compile(r"(?:^|[_/])(?:I2C\d*_?)?(SDA|SCL)\d*$", re.I)
+
+
+# --- KiCad ERC --------------------------------------------------------------------------------
+
+
+def _item_location(text: str) -> tuple[str | None, str | None]:
+    """(reference, pin) named in a kicad-cli item description, e.g. "Symbol U3 Pin 3 [A2, Input,
+    Line]", "Pad 6 [/TX] of U1 on F.Cu", "PTH pad 4 [GND] of J2", "Footprint C2", "Reference field
+    of R6"."""
+    match = re.search(r"Symbol (\S+) Pin (\S+)", text)
+    if match:
+        return match.group(1), match.group(2)
+    match = re.search(r"[Pp]ad (\S+) (?:\[[^\]]*\] )?of (\S+)", text)
+    if match:
+        return match.group(2), match.group(1)
+    match = re.search(r"(?:Symbol|Footprint) (\S+)", text) or re.search(r"\bof (\S+)", text)
+    return (match.group(1), None) if match else (None, None)
+
+
+def _severity(kicad: str, kind: str) -> Severity | None:
+    if kind in _CONFIGURATION:
+        return Severity.INFO
+    return {"error": Severity.ERROR, "warning": Severity.WARNING}.get(kicad)
+
+
+def erc_violation(project: Project) -> Iterator[Finding]:
+    """Every violation KiCad's ERC reports, at the sheet and symbol it names."""
+    sch = schematic(project)
+    run = (project.design.external.get("erc") or {}) if project.design else {}
+    if sch is None or not run.get("ran"):
+        return
+    report = run["report"]
+    for sheet in report.get("sheets", []):
+        file = sch.sheet_paths.get(sheet.get("path", "/"), sch.root_file)
+        for violation in sheet.get("violations", []):
+            kind = violation.get("type", "erc")
+            severity = _severity(violation.get("severity", ""), kind)
+            if severity is None:     # exclusions the designer accepted in KiCad
+                continue
+            items = violation.get("items", [])
+            first = items[0] if items else {}
+            pos = first.get("pos", {})
+            ref, pin = _item_location(first.get("description", ""))
+            location = Location(artifact=project.relative(file), sheet=sheet_of(sheet.get("path", "/")),
+                                component=ref, pin=pin,
+                                key=f"{kind}@{pos.get('x', 0):.2f},{pos.get('y', 0):.2f}")
+            evidence = tuple(
+                Evidence(kind="kicad_erc", value=f"{item.get('description', '')} at "
+                         f"({item.get('pos', {}).get('x', 0):.2f}, {item.get('pos', {}).get('y', 0):.2f}) mm",
+                         source=f"kicad-cli {run.get('version') or ''} sch erc".replace("  ", " "))
+                for item in items) or (Evidence(kind="kicad_erc", value=violation.get("description", kind)),)
+            configuration = kind in _CONFIGURATION
+            yield Finding(
+                rule_id="kicad.erc.violation",
+                title=f"ERC {kind}: {violation.get('description', '')}",
+                severity=severity,
+                domain=Domain.SCHEMATIC,
+                location=location,
+                evidence=evidence,
+                explanation=(f"KiCad's electrical rules check reports {kind!r}"
+                             + (" — this concerns the library setup of the machine that ran kicad-cli as much "
+                                "as the design." if configuration else ".")),
+                consequence=_ERC_CONSEQUENCE.get(kind, "An ERC violation left in a released schematic is either a "
+                                                       "defect or a decision nobody recorded."),
+                recommendation=("Fix it in the schematic, or exclude it in KiCad's ERC dialog with a comment so the "
+                                "decision is visible."),
+                detector=Detector.EXTERNAL,
+                confidence=EXTERNAL_CONFIDENCE,
+            )
+
+
+# --- netlist cross-check ----------------------------------------------------------------------
+
+
+def netlist_parity(project: Project) -> Iterator[Finding]:
+    """The engine's connectivity against KiCad's own exported netlist."""
+    sch = schematic(project)
+    run = (project.design.external.get("netlist") or {}) if project.design else {}
+    if sch is None or not run.get("ran"):
+        return
+    theirs: dict[tuple[str, str], str] = {}
+    for name, nodes in run["report"].items():
+        for ref, pin in nodes:
+            if not ref.startswith("#"):
+                theirs[(ref, pin)] = name
+    ours: dict[tuple[str, str], Net] = {}
+    for net in sch.nets:
+        for pin in net.parts:
+            ours[(pin.ref, pin.number)] = net
+    source = f"kicad-cli {run.get('version') or ''} sch export netlist".replace("  ", " ")
+    reported: set[str] = set()
+    for net in sch.nets:
+        names = sorted({theirs[(p.ref, p.number)] for p in net.parts if (p.ref, p.number) in theirs})
+        if len(names) > 1 and net.name not in reported:
+            reported.add(net.name)
+            yield _parity(project, net, f"the engine joins {len(names)} KiCad nets into {net_display(net)!r}",
+                          [f"KiCad keeps apart: {', '.join(names)}"], source)
+    by_their_net: dict[str, set[str]] = defaultdict(set)
+    for node, name in theirs.items():
+        if node in ours:
+            by_their_net[name].add(ours[node].name)
+    for name, our_names in sorted(by_their_net.items()):
+        if len(our_names) > 1:
+            net = next(n for n in sch.nets if n.name == sorted(our_names)[0])
+            if net.name in reported:
+                continue
+            reported.add(net.name)
+            yield _parity(project, net, f"the engine splits KiCad's net {name!r} into {len(our_names)} nets",
+                          [f"engine nets: {', '.join(sorted(our_names))}"], source)
+    missing = sorted(set(theirs) - set(ours))
+    by_ref: dict[str, list[str]] = defaultdict(list)
+    for ref, pin in missing:
+        by_ref[ref].append(pin)
+    for ref, pins in sorted(by_ref.items()):
+        component = sch.components.get(ref)
+        location = at_component(project, component, key="missing_pins") if component else Location(
+            artifact=project.relative(sch.root_file), component=ref, key="missing_pins")
+        yield Finding(
+            rule_id="kicad.netlist.parity",
+            title=f"KiCad's netlist has pins of {ref} the engine did not read",
+            severity=Severity.WARNING,
+            domain=Domain.SCHEMATIC,
+            location=location,
+            evidence=(Evidence(kind="kicad_netlist", value=f"{ref} pins {', '.join(sorted(pins))} in KiCad's netlist",
+                               source=source),),
+            explanation="The engine has no connectivity for these pins, so every rule below skips them.",
+            consequence="Checks on this part would silently cover less than the design contains.",
+            recommendation="Check that the symbol is embedded in the sheet's lib_symbols and annotated; report the "
+                           "case to EngineHall if it is.",
+            detector=Detector.EXTERNAL,
+            confidence=EXTERNAL_CONFIDENCE,
+        )
+
+
+def _parity(project: Project, net: Net, what: str, extra: list[str], source: str) -> Finding:
+    return Finding(
+        rule_id="kicad.netlist.parity",
+        title=f"Connectivity disagrees with KiCad: {what}",
+        severity=Severity.WARNING,
+        domain=Domain.SCHEMATIC,
+        location=at_net(project, net),
+        evidence=(Evidence(kind="engine_net", value=f"{net.name}: " + ", ".join(pin_label(p) for p in net.parts[:12]),
+                           source=project.relative(net.parts[0].sheet_file) if net.parts else None),
+                  *(Evidence(kind="kicad_netlist", value=text, source=source) for text in extra)),
+        explanation=("EngineHall builds nets from wire geometry; KiCad's netlist export disagrees for this net. "
+                     "Either the drawing relies on a connection rule the engine does not model (buses, for one), "
+                     "or a wire does something the drawing hides."),
+        consequence="Rules that read this net may report or miss problems that are not there.",
+        recommendation="Open the net in KiCad and check which pins it really joins; trust KiCad's netlist for the "
+                       "board.",
+        detector=Detector.EXTERNAL,
+        confidence=EXTERNAL_CONFIDENCE,
+    )
+
+
+# --- rails ------------------------------------------------------------------------------------
+
+
+def rail_without_source(project: Project) -> Iterator[Finding]:
+    """A net with power inputs but no power output, regulator output or PWR_FLAG."""
+    sch = schematic(project)
+    if sch is None:
+        return
+    for net in sch.nets:
+        inputs = [p for p in net.parts if p.type == "power_in"]
+        if not inputs or any(p.type == "power_out" for p in net.pins):
+            continue
+        yield Finding(
+            rule_id="kicad.power.rail_without_source",
+            title=f"Rail {net_display(net)!r} has power inputs but no source",
+            severity=Severity.ERROR,
+            domain=Domain.SCHEMATIC,
+            location=at_pin(project, inputs[0], key=net_display(net)),
+            evidence=(Evidence(kind="schematic_net", value=f"power inputs on {net_display(net)!r}: "
+                               + ", ".join(pin_label(p) for p in inputs[:10]),
+                               source=project.relative(inputs[0].sheet_file)),
+                      Evidence(kind="schematic_net", value="no power output pin and no PWR_FLAG on the net")),
+            explanation=("Every pin on this net that is typed as a power input waits for a power output: a regulator "
+                         "output, a power-output connector pin, or a PWR_FLAG where the rail enters the board."),
+            consequence=("Either the rail really has no source (a missing regulator or connection), or it enters "
+                         "through a passive pin and KiCad's ERC keeps reporting it, which hides the next real one."),
+            recommendation=("Find where the rail is supplied. If it enters through a connector, fuse or diode, place a "
+                            "PWR_FLAG there; if a regulator feeds it, type its output pin as power output."),
+        )
+
+
+def _dc_neighbours(project: Project, net: Net) -> list[tuple[Net, str]]:
+    """Nets one conductive part away: resistors of at most 1 ohm, inductors, ferrites, fuses, jumpers."""
+    from pcba.components import parse_value
+
+    sch = schematic(project)
+    out = []
+    for pin in net.parts:
+        component = sch.components.get(pin.ref)
+        if component is None or component.dnp or len(pin_numbers(component)) != 2:
+            continue
+        kind = classify(component)
+        if kind not in DC_PATH_KINDS:
+            continue
+        if kind == "resistor":
+            ohms = parse_value(component.value)
+            if ohms is None or ohms > DC_PATH_MAX_OHM:
+                continue
+        for far in other_nets(sch, component, pin.number):
+            out.append((far, component.ref))
+    return out
+
+
+def _capacitor_neighbours(project: Project, net: Net) -> list[tuple[Net, str]]:
+    sch = schematic(project)
+    out = []
+    for pin in net.parts:
+        component = sch.components.get(pin.ref)
+        if component is not None and classify(component) == "capacitor":
+            out.extend((far, component.ref) for far in other_nets(sch, component, pin.number))
+    return out
+
+
+def _blocking_resistors(project: Project, net: Net) -> list[tuple[str, str]]:
+    """Resistors on the net that lead to a rail but are too large to count as a supply path."""
+    from pcba.components import parse_value
+
+    sch = schematic(project)
+    out = []
+    for pin in net.parts:
+        component = sch.components.get(pin.ref)
+        if component is None or classify(component) != "resistor":
+            continue
+        ohms = parse_value(component.value)
+        if (ohms is None or ohms > DC_PATH_MAX_OHM) and any(
+                _is_rail(project, far) for far in other_nets(sch, component, pin.number)):
+            out.append((component.ref, component.value))
+    return out
+
+
+def _is_rail(project: Project, net: Net) -> bool:
+    return is_ground_net(net) or is_supply_rail(project, net)
+
+
+def _dc_rail(project: Project, net: Net) -> tuple[Net, list[str]] | None:
+    """The first named rail reachable through conductive parts, with the parts on the way."""
+    seen = {net.name}
+    frontier: list[tuple[Net, list[str]]] = [(net, [])]
+    for _depth in range(DC_PATH_DEPTH + 1):
+        following = []
+        for current, path in frontier:
+            if _is_rail(project, current):
+                return current, path
+            for far, via in _dc_neighbours(project, current):
+                if far.name not in seen:
+                    seen.add(far.name)
+                    following.append((far, path + [via]))
+        frontier = following
+    return None
+
+
+def pin_without_dc_path(project: Project) -> Iterator[Finding]:
+    """An IC power pin that reaches no named rail through a DC path."""
+    sch = schematic(project)
+    if sch is None:
+        return
+    for component in parts(project, "ic"):
+        if component.dnp:
+            continue
+        for pin in component.pins:
+            if pin.type != "power_in":
+                continue
+            net = sch.net_of(component.ref, pin.number)
+            if net is None or _dc_rail(project, net) is not None:
+                continue
+            via_cap = [(far, ref) for far, ref in _capacitor_neighbours(project, net) if is_supply_rail(project, far)]
+            if via_cap:
+                far, ref = via_cap[0]
+                detail = f"its net {net_display(net)!r} reaches {net_display(far)!r} only through capacitor {ref}"
+            elif len(net.parts) == 1 and not net.labels:
+                detail = "the pin is not connected at all"
+            else:
+                detail = f"its net {net_display(net)!r} reaches no power symbol, declared rail or power output"
+            blocked = _blocking_resistors(project, net)
+            yield Finding(
+                rule_id="kicad.power.pin_without_dc_path",
+                title=f"{component.ref} power pin {pin.number} ({pin.name or 'unnamed'}) reaches no rail",
+                severity=Severity.ERROR,
+                domain=Domain.SCHEMATIC,
+                location=at_pin(project, pin),
+                evidence=(Evidence(kind="schematic_net", value=detail, source=project.relative(pin.sheet_file)),
+                          *(Evidence(kind="schematic_net", value=f"{ref} ({value}) is not counted as a supply path "
+                                     f"(above {DC_PATH_MAX_OHM:g} ohm)") for ref, value in blocked),
+                          Evidence(kind="rule", value=f"DC path: wires, resistors up to {DC_PATH_MAX_OHM:g} ohm, "
+                                   f"inductors, ferrites, fuses, jumpers; at most {DC_PATH_DEPTH} parts")),
+                explanation=(f"{component.ref} pin {pin.number} is a power input. Following its net through "
+                             "conductive parts reaches no supply or ground rail."),
+                consequence="The pin is unpowered on the board (a capacitor passes no DC); the part does not work "
+                            "or back-powers through its I/O.",
+                recommendation="Connect the pin to its rail (a power symbol or the regulator output); a decoupling "
+                               "capacitor goes beside that connection, not instead of it.",
+            )
+
+
+def decoupling_missing(project: Project) -> Iterator[Finding]:
+    """An IC supply net without a capacitor to ground."""
+    sch = schematic(project)
+    if sch is None:
+        return
+    decoupled: set[str] = set()
+    for capacitor in parts(project, "capacitor"):
+        if capacitor.dnp or len(pin_numbers(capacitor)) != 2:
+            continue
+        nets = [sch.net_of(capacitor.ref, p.number) for p in capacitor.pins]
+        if any(is_ground_net(n) for n in nets):
+            decoupled.update(n.name for n in nets if n is not None and not is_ground_net(n))
+    for component in parts(project, "ic"):
+        if component.dnp:
+            continue
+        seen: set[str] = set()
+        for pin in sorted(component.pins, key=lambda p: p.number):
+            net = sch.net_of(component.ref, pin.number)
+            if pin.type != "power_in" or net is None or is_ground_net(net) or net.name in seen:
+                continue
+            seen.add(net.name)
+            if net.name in decoupled or (len(net.parts) == 1 and not net.labels):
+                continue
+            yield Finding(
+                rule_id="kicad.power.decoupling_missing",
+                title=f"{component.ref} supply {net_display(net)!r} has no decoupling capacitor",
+                severity=Severity.WARNING,
+                domain=Domain.SCHEMATIC,
+                location=at_pin(project, pin, key=net_display(net)),
+                evidence=(Evidence(kind="schematic_net", value=f"{component.ref}.{pin.number} ({pin.name}) on "
+                                   f"{net_display(net)!r}", source=project.relative(pin.sheet_file)),
+                          Evidence(kind="schematic_net",
+                                   value=f"no capacitor connects {net_display(net)!r} to a ground net anywhere in the "
+                                   "schematic")),
+                explanation=("Every IC supply pin needs a local capacitor to ground. This schematic has none on the "
+                             "net at all, so no placement on the board can provide it."),
+                consequence="Supply noise and transients reach the IC directly: resets, corrupted conversions, "
+                            "radiated emissions.",
+                recommendation=f"Add a capacitor (typically 100 nF per supply pin, plus bulk) from "
+                               f"{net_display(net)!r} to ground beside {component.ref}.",
+            )
+
+
+# --- parts and pins ---------------------------------------------------------------------------
+
+
+def shorted_part(project: Project) -> Iterator[Finding]:
+    """A two-pin part whose pins are both on one net."""
+    sch = schematic(project)
+    if sch is None:
+        return
+    for component in parts(project):
+        kind = classify(component)
+        numbers = sorted(pin_numbers(component))
+        if component.dnp or len(numbers) != 2 or kind in ("net_tie", "jumper", "test_point", "connector", "mechanical"):
+            continue
+        nets = [sch.net_of(component.ref, n) for n in numbers]
+        if nets[0] is None or nets[0] is not nets[1]:
+            continue
+        net = nets[0]
+        yield Finding(
+            rule_id="kicad.part.shorted",
+            title=f"{component.ref} ({component.value}) has both pins on {net_display(net)!r}",
+            severity=Severity.WARNING,
+            domain=Domain.SCHEMATIC,
+            location=at_component(project, component),
+            evidence=(Evidence(kind="schematic_net",
+                               value=f"{component.ref}.{numbers[0]} and {component.ref}.{numbers[1]} are both on "
+                               f"{net_display(net)!r}", source=project.relative(component.sheet_file)),),
+            explanation=("Both ends of a two-pin part connect to the same net, so the part does nothing. The usual "
+                         "cause is a wire drawn straight through the symbol, which ERC does not report."),
+            consequence="The circuit the part was meant to form (a filter, divider, series element) does not exist.",
+            recommendation="Redraw the wiring so each pin reaches its own net; for an intentional short use a net "
+                           "tie or mark the part DNP.",
+        )
+
+
+def input_floating(project: Project) -> Iterator[Finding]:
+    """An input pin connected to nothing and not marked no-connect."""
+    sch = schematic(project)
+    if sch is None:
+        return
+    for component in parts(project):
+        if component.dnp:
+            continue
+        for pin in component.pins:
+            if pin.type != "input" or pin.no_connect:
+                continue
+            net = sch.net_of(component.ref, pin.number)
+            if net is None or len(net.parts) > 1 or net.power:
+                continue
+            yield Finding(
+                rule_id="kicad.pin.input_floating",
+                title=f"Input {component.ref}.{pin.number} ({pin.name or 'unnamed'}) is not connected",
+                severity=Severity.ERROR,
+                domain=Domain.SCHEMATIC,
+                location=at_pin(project, pin),
+                evidence=(Evidence(kind="schematic_net", value=f"{pin_label(pin)} is the only pin on its net "
+                                   f"{net_display(net)!r}", source=project.relative(pin.sheet_file)),
+                          Evidence(kind="symbol", value=f"pin type {pin.type}; no no-connect flag")),
+                explanation="A CMOS input left open floats between the logic levels.",
+                consequence="Random toggling, extra supply current, and behaviour that changes with humidity or a "
+                            "finger near the board.",
+                recommendation="Tie the input to its inactive level (directly or through a resistor), or mark it "
+                               "with a no-connect flag if the datasheet allows it open.",
+            )
+
+
+def pull_up_missing(project: Project) -> Iterator[Finding]:
+    """An I2C or open-drain net with no resistor to a supply rail."""
+    sch = schematic(project)
+    if sch is None:
+        return
+    for net in sch.nets:
+        open_drain = [p for p in net.parts if p.type in ("open_collector", "open_emitter")]
+        i2c = bool(_I2C.search(net.label or ""))
+        if not (open_drain or i2c) or len(net.parts) == 0:
+            continue
+        has_pull_up = False
+        for pin in net.parts:
+            component = sch.components.get(pin.ref)
+            if component is None or component.dnp or classify(component) != "resistor":
+                continue
+            if any(is_supply_rail(project, far) for far in other_nets(sch, component, pin.number)):
+                has_pull_up = True
+                break
+        if has_pull_up:
+            continue
+        why = (f"open-drain pin {pin_label(open_drain[0])}" if open_drain
+               else f"the net name {net_display(net)!r} marks an I2C line")
+        yield Finding(
+            rule_id="kicad.net.pull_up_missing",
+            title=f"{net_display(net)!r} has no pull-up resistor",
+            severity=Severity.WARNING,
+            domain=Domain.SCHEMATIC,
+            location=at_net(project, net),
+            evidence=(Evidence(kind="schematic_net", value=f"{why}", source=project.relative(sch.root_file)),
+                      Evidence(kind="schematic_net", value="no resistor connects the net to a supply rail")),
+            explanation="Open-drain outputs and I2C lines only pull low; the high level comes from a pull-up.",
+            consequence="The line never goes high (or rises far too slowly); the bus does not work.",
+            recommendation=f"Add a pull-up from {net_display(net)!r} to the logic supply (for I2C typically "
+                           "2.2 to 10 kohm, sized for the bus capacitance and speed).",
+        )
+
+
+# --- labels and names -------------------------------------------------------------------------
+
+
+def global_label_single_sheet(project: Project) -> Iterator[Finding]:
+    """A global label whose text appears on one sheet only."""
+    sch = schematic(project)
+    if sch is None:
+        return
+    sheets: dict[str, set[str]] = defaultdict(set)
+    first: dict[str, object] = {}
+    for label in sch.labels:
+        if label.kind == "global":
+            sheets[label.text].add(label.sheet_path)
+            first.setdefault(label.text, label)
+    if len(sch.sheet_paths) < 2:
+        return
+    for text, used in sorted(sheets.items()):
+        if len(used) != 1:
+            continue
+        label = first[text]
+        yield Finding(
+            rule_id="kicad.label.global_single_sheet",
+            title=f"Global label {text!r} is used on one sheet only",
+            severity=Severity.INFO,
+            domain=Domain.SCHEMATIC,
+            location=at_label(project, label, key=f"global:{text}"),
+            evidence=(Evidence(kind="label", value=f"every global label {text!r} is on sheet {next(iter(used))}",
+                               source=project.relative(label.sheet_file)),),
+            explanation="A global label joins nets across the whole project; used on one sheet it does the job of "
+                        "a local label.",
+            consequence="Anyone looking for where the signal leaves the sheet finds nothing, and a later global "
+                        "label with the same text on another sheet joins it silently.",
+            recommendation="Use a local label, or connect the signal on the sheet where it is used.",
+        )
+
+
+def label_single_connection(project: Project) -> Iterator[Finding]:
+    """A label on a net that reaches at most one pin."""
+    sch = schematic(project)
+    if sch is None:
+        return
+    for net in sch.nets:
+        named = [label for label in net.labels if label.kind in ("local", "global", "hierarchical")]
+        if not named or len(net.parts) > 1 or net.no_connect or net.power:
+            continue
+        label = named[0]
+        reached = f"only {pin_label(net.parts[0])}" if net.parts else "no pin at all"
+        yield Finding(
+            rule_id="kicad.label.single_connection",
+            title=f"Label {label.text!r} connects {reached}",
+            severity=Severity.WARNING,
+            domain=Domain.SCHEMATIC,
+            location=at_label(project, label, key=net.name),
+            evidence=(Evidence(kind="label", value=f"net {net.name!r} has {len(net.parts)} part pin(s)",
+                               source=project.relative(label.sheet_file)),
+                      *(Evidence(kind="label", value=f"{lab.kind} label {lab.text!r} on sheet {lab.sheet_path}")
+                        for lab in named[:4])),
+            explanation="A label exists to join a net to other places. This one reaches at most one pin, so the "
+                        "other end is missing or spelled differently.",
+            consequence="An intended connection is open on the board.",
+            recommendation="Check the spelling and scope (local, global, hierarchical) of the label at both ends.",
+        )
+
+
+def net_name_hygiene(project: Project) -> Iterator[Finding]:
+    """Rail names reviewers and tools misread: VBUS without USB, supplies without a voltage."""
+    sch = schematic(project)
+    if sch is None:
+        return
+    has_usb = any("USB" in " ".join((c.lib_id, c.value, c.footprint)).upper() for c in parts(project))
+    declared = requirements(project).rails
+    for net in sch.nets:
+        name = net.label
+        if not name:
+            continue
+        bare = name.rsplit("/", 1)[-1]
+        problem = None
+        if "VBUS" in bare.upper() and not has_usb:
+            problem = (f"{bare!r} is named VBUS but the design has no USB connector",
+                       "Reviewers and tools read VBUS as the 5 V USB supply.",
+                       "Name the rail after its voltage and role (for example DCLINK or +24V); keep VBUS for USB.")
+        elif (net.power and not is_ground_net(net) and voltage_from_name(bare) is None and bare.upper() != "VBUS"
+              and name not in declared and net.name not in declared):
+            problem = (f"rail {bare!r} carries no voltage in its name",
+                       "Its voltage is nowhere in the design files, so supply-range and derating checks cannot "
+                       "use it.",
+                       f"Rename it with its voltage (+3V3, +24V) or declare it in pcba-requirements.toml "
+                       f"([rails.\"{bare}\"] voltage = ...).")
+        if problem is None:
+            continue
+        yield Finding(
+            rule_id="kicad.net.name_hygiene",
+            title=problem[0][0].upper() + problem[0][1:],
+            severity=Severity.INFO,
+            domain=Domain.SCHEMATIC,
+            location=at_net(project, net, key=net.name),
+            evidence=(Evidence(kind="schematic_net", value=f"net {net.name!r}",
+                               source=project.relative(net.parts[0].sheet_file) if net.parts else None),),
+            explanation=problem[1],
+            consequence="A name that misleads costs review time and lets a wrong voltage assumption through.",
+            recommendation=problem[2],
+        )
+
+
+RULES = (erc_violation, netlist_parity, rail_without_source, pin_without_dc_path, decoupling_missing, shorted_part,
+         input_floating, pull_up_missing, global_label_single_sheet, label_single_connection, net_name_hygiene)
+
+
+def _ics(project: Project) -> tuple[int, list[str]]:
+    return len([c for c in parts(project, "ic") if not c.dnp]), []
+
+
+def _two_pin(project: Project) -> tuple[int, list[str]]:
+    return len([c for c in parts(project) if len(pin_numbers(c)) == 2]), []
+
+
+SCOPE = {
+    "kicad.power.pin_without_dc_path": _ics,
+    "kicad.power.decoupling_missing": _ics,
+    "kicad.part.shorted": _two_pin,
+}
+
+__all__ = ["RULES", "SCOPE"]

pcba/rules/locate.py

@@ -0,0 +1,22 @@
+"""Where a finding points.
+
+Every artifact in a Location or an Evidence source is a project-relative POSIX path. The
+rules never build one by hand; they come through here so the contract holds in one place.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from pcba.model.finding import Location
+from pcba.model.pinmap import Pin, Project
+
+
+def at_pin(project: Project, pin: Pin) -> Location:
+    """The schematic pin a finding is about."""
+    return Location(
+        artifact=project.relative(pin.sheet),
+        sheet=Path(pin.sheet).name,
+        component=pin.component,
+        pin=pin.port_pin,
+    )