enginehall 2.0.0__py3-none-any.whl

pcba/rules/kicad_board.py

@@ -0,0 +1,775 @@
+"""KiCad board rules: KiCad's own DRC and schematic parity, and the Newmatik house DFM checks.
+
+The house checks are the ones the Altium drive's `altium_dfm` makes on an Altium board, with the
+same values (`pcba/house.py`) and the same house ids in the title (NM-FID-001 ...): fiducials,
+track angles, vias in pads, same-net via spacing, 3D models, silkscreen past the outline, and the
+barcode field. Added for KiCad boards: SMD parts on the bottom of a single-sided board, SMD pads
+too close to the board edge, test-point coverage and courtyard overlaps. The board is read from
+the `.kicad_pcb` file; no fabrication output is parsed (that is gerbtrace's domain).
+"""
+
+from __future__ import annotations
+
+import itertools
+import math
+import os
+import re
+from collections.abc import Iterator
+from pathlib import Path
+
+from pcba import house
+from pcba.model.design import Board, Footprint, Pad
+from pcba.model.finding import Detector, Domain, Evidence, Finding, Location, Severity
+from pcba.model.pinmap import Project
+from pcba.rules.kicad_common import requirements
+from pcba.rules.kicad_schematic import EXTERNAL_CONFIDENCE, _item_location, _severity
+
+SILK = {"F.SilkS": "top", "B.SilkS": "bottom"}
+SMD_SIDES = {"top": "F.Cu", "bottom": "B.Cu"}
+
+
+def board(project: Project) -> Board | None:
+    return project.design.board if project.design else None
+
+
+def _at(project: Project, b: Board, *, component: str | None = None, pin: str | None = None,
+        key: str | None = None, line: int = 0) -> Location:
+    return Location(artifact=project.relative(b.path), component=component, pin=pin, key=key, line=line or None)
+
+
+def _house(key: str, value) -> Evidence:
+    status = house.fiducial_status(key) if key in house.FIDUCIALS else house.layout_status(key)
+    return Evidence(kind="house_rule", value=f"{key} = {value} ({status})", source=f"{house.HOUSE} v{house.VERSION}")
+
+
+def is_fiducial(fp: Footprint) -> bool:
+    return "FIDUCIAL" in fp.lib.upper() or fp.ref.upper().startswith("FID")
+
+
+def is_test_point(fp: Footprint) -> bool:
+    return "TESTPOINT" in fp.lib.upper().replace("_", "") or re.match(r"^TP\d", fp.ref.upper()) is not None
+
+
+def _smd_on(fp: Footprint, side: str) -> bool:
+    return any(p.kind == "smd" and SMD_SIDES[side] in p.layers for p in fp.pads)
+
+
+def _outline(b: Board):
+    segments = b.outline
+    return segments if len(segments) >= 3 else None
+
+
+def _pad_dict(pad: Pad) -> dict:
+    return {"x": pad.x, "y": pad.y, "w": pad.w, "h": pad.h, "shape": pad.shape, "rotation": pad.rotation}
+
+
+# --- KiCad DRC ----------------------------------------------------------------------------------
+
+
+def _drc_items(project: Project, keys: tuple[str, ...]) -> Iterator[dict]:
+    b = board(project)
+    run = (project.design.external.get("drc") or {}) if project.design else {}
+    if b is None or not run.get("ran"):
+        return
+    source = f"kicad-cli {run.get('version') or ''} pcb drc".replace("  ", " ")
+    for key in keys:
+        for violation in run["report"].get(key, []):
+            kind = violation.get("type", key)
+            severity = _severity(violation.get("severity", ""), kind)
+            if severity is not None:
+                yield {"board": b, "key": key, "kind": kind, "severity": severity, "violation": violation,
+                       "source": source}
+
+
+def _drc_finding(project: Project, item: dict, *, rule_id: str) -> Finding:
+    b, violation, kind = item["board"], item["violation"], item["kind"]
+    items = violation.get("items", [])
+    first = items[0] if items else {}
+    pos = first.get("pos", {})
+    ref, pin = _item_location(first.get("description", ""))
+    return Finding(
+        rule_id=rule_id,
+        title=f"DRC {kind}: {violation.get('description', '')}",
+        severity=item["severity"],
+        domain=Domain.BOARD,
+        location=_at(project, b, component=ref, pin=pin, key=f"{kind}@{pos.get('x', 0):.2f},{pos.get('y', 0):.2f}"),
+        evidence=tuple(Evidence(kind="kicad_drc", value=f"{entry.get('description', '')} at "
+                                f"({entry.get('pos', {}).get('x', 0):.2f}, {entry.get('pos', {}).get('y', 0):.2f}) mm",
+                                source=item["source"]) for entry in items)
+        or (Evidence(kind="kicad_drc", value=violation.get("description", kind), source=item["source"]),),
+        explanation=f"KiCad's design rules check reports {kind!r}.",
+        consequence=("A schematic and board that disagree build a different circuit than the one reviewed."
+                     if item["key"] == "schematic_parity" else
+                     "A DRC violation in a released board is either a manufacturing defect or a decision nobody "
+                     "recorded."),
+        recommendation="Fix it on the board (or update the board from the schematic), or exclude it in KiCad's DRC "
+                       "dialog with a comment.",
+        detector=Detector.EXTERNAL,
+        confidence=EXTERNAL_CONFIDENCE,
+    )
+
+
+def drc_violation(project: Project) -> Iterator[Finding]:
+    """Every violation and unconnected item KiCad's DRC reports."""
+    for item in _drc_items(project, ("violations", "unconnected_items")):
+        yield _drc_finding(project, item, rule_id="kicad.drc.violation")
+
+
+def drc_schematic_parity(project: Project) -> Iterator[Finding]:
+    """Where KiCad finds the board and the schematic out of step."""
+    for item in _drc_items(project, ("schematic_parity",)):
+        yield _drc_finding(project, item, rule_id="kicad.drc.schematic_parity")
+
+
+# --- fiducials ----------------------------------------------------------------------------------
+
+
+def _fid(project: Project, b: Board, code: str, severity: Severity, title: str, key: str, evidence: list[Evidence],
+         fp: Footprint | None = None) -> dict:
+    return dict(
+        title=f"[{code}] {title}",
+        severity=severity,
+        domain=Domain.BOARD,
+        location=_at(project, b, component=fp.ref if fp else None, key=f"{code}:{key}", line=fp.line if fp else 0),
+        evidence=tuple(evidence),
+        explanation=("Newmatik's placement machines align every SMD side on three global fiducials: 1.0 mm round "
+                     "copper, a 3.0 mm solder-mask opening, no paste, no net, away from the edge, spread out as a "
+                     "triangle."),
+        consequence="Without usable fiducials the side is placed against the board edge only; fine-pitch parts "
+                    "shift, and the line stops to teach marks by hand.",
+        recommendation="Place three Fiducial_1mm_Mask3mm footprints per SMD side, near three corners, at least "
+                       f"{house.FIDUCIALS['edge_min_mm']:g} mm from the edge.",
+    )
+
+
+def fiducials(project: Project) -> Iterator[Finding]:
+    """NM-FID-001..006: three house fiducials on every side that carries SMD parts."""
+    b = board(project)
+    if b is None:
+        return
+    policy = house.FIDUCIALS
+    outline = _outline(b)
+
+    def fid(*args) -> Finding:
+        return Finding(rule_id="kicad.dfm.fiducials", **_fid(project, b, *args))
+
+    for side in ("top", "bottom"):
+        smd = sorted(fp.ref for fp in b.footprints if fp.side == side and not is_fiducial(fp) and _smd_on(fp, side))
+        fids = [fp for fp in b.footprints if fp.side == side and is_fiducial(fp)]
+        if not smd:
+            continue
+        if len(fids) < policy["per_smd_side"]:
+            yield fid("NM-FID-001", Severity.ERROR,
+                      f"{side} carries {len(smd)} SMD part(s) but {len(fids)} fiducial(s)", side,
+                      [Evidence(kind="board", value=f"SMD parts on {side}: {', '.join(smd[:10])}"
+                                + (" ..." if len(smd) > 10 else ""), source=project.relative(b.path)),
+                       Evidence(kind="board",
+                                value=f"fiducials on {side}: {', '.join(f.ref for f in fids) or 'none'}"),
+                       _house("per_smd_side", policy["per_smd_side"])])
+        points = {}
+        for fp in sorted(fids, key=lambda f: f.ref):
+            points[fp.ref] = (fp.x, fp.y)
+            copper = [p for p in fp.pads if p.copper_layers]
+            if len(copper) != 1:
+                yield fid("NM-FID-002", Severity.ERROR, f"{fp.ref} has {len(copper)} pads; a fiducial "
+                          "has one", fp.ref, [Evidence(kind="board", value=f"{fp.ref} ({fp.lib})")], fp)
+                continue
+            pad = copper[0]
+            size = max(pad.w, pad.h)
+            if (pad.shape != "circle" or abs(pad.w - pad.h) > 1e-3
+                    or abs(size - policy["copper_mm"]) > policy["copper_tolerance_mm"]):
+                yield fid("NM-FID-002", Severity.ERROR,
+                          f"{fp.ref} copper is a {pad.w:g} x {pad.h:g} mm {pad.shape} pad; the house fiducial is a "
+                          f"{policy['copper_mm']:g} mm round pad", f"{fp.ref}:copper",
+                          [Evidence(kind="board", value=f"pad {pad.number}: {pad.shape} {pad.w:g} x {pad.h:g} mm",
+                                    source=project.relative(b.path)), _house("copper_mm", policy["copper_mm"])], fp)
+            if pad.drill or pad.kind != "smd":
+                yield fid("NM-FID-002", Severity.ERROR, f"{fp.ref} is drilled; a fiducial is a bare SMD "
+                          "pad", f"{fp.ref}:drill", [Evidence(kind="board", value=f"pad kind {pad.kind}")], fp)
+            if pad.net:
+                yield fid("NM-FID-004", Severity.ERROR, f"{fp.ref} is on net {pad.net}; a fiducial "
+                          "carries no net", f"{fp.ref}:net", [Evidence(kind="board", value=f"net {pad.net}")], fp)
+            opening = size + 2 * (pad.mask_margin or 0.0)
+            mask = any(layer.endswith(".Mask") for layer in pad.layers)
+            if not mask or abs(opening - policy["mask_opening_mm"]) > policy["mask_tolerance_mm"]:
+                yield fid("NM-FID-003", Severity.ERROR,
+                          f"{fp.ref} mask opening is {opening if mask else 0:.2f} mm; the house fiducial needs "
+                          f"{policy['mask_opening_mm']:g} mm", f"{fp.ref}:mask",
+                          [Evidence(kind="board", value=f"pad {size:g} mm, solder-mask margin "
+                                    f"{pad.mask_margin or 0:g} mm" + ("" if mask else ", no mask layer")),
+                           _house("mask_opening_mm", policy["mask_opening_mm"])], fp)
+            if any(layer.endswith(".Paste") for layer in pad.layers):
+                yield fid("NM-FID-004", Severity.ERROR, f"{fp.ref} would get solder paste; a fiducial "
+                          "has none", f"{fp.ref}:paste", [Evidence(kind="board", value="layers "
+                                                                   + " ".join(pad.layers))], fp)
+            if outline:
+                if not house.inside_segments(points[fp.ref], outline):
+                    yield fid("NM-FID-006", Severity.ERROR, f"{fp.ref} lies outside the board outline",
+                              f"{fp.ref}:outside", [Evidence(kind="board", value=f"at ({fp.x:g}, {fp.y:g}) mm")], fp)
+                else:
+                    distance = house.edge_distance_segments(points[fp.ref], outline)
+                    if distance < policy["edge_min_mm"]:
+                        yield fid("NM-FID-006", Severity.WARNING,
+                                  f"{fp.ref} is {distance:.2f} mm from the board edge; house target "
+                                  f"{policy['edge_min_mm']:g} mm", f"{fp.ref}:edge",
+                                  [Evidence(kind="board", value=f"centre at ({fp.x:g}, {fp.y:g}) mm"),
+                                   _house("edge_min_mm", policy["edge_min_mm"])], fp)
+        if len(points) >= 3:
+            pts = list(points.values())
+            best = max(min(house.angles(a, b2, c)) for a, b2, c in itertools.combinations(pts, 3))
+            if best < policy["min_angle_deg"]:
+                yield fid("NM-FID-005", Severity.ERROR,
+                          f"the {side} fiducials are nearly in a line (smallest angle {best:.1f} deg)", f"{side}:line",
+                          [Evidence(kind="board",
+                                    value=", ".join(f"{r} ({x:g}, {y:g})" for r, (x, y) in points.items())),
+                           _house("min_angle_deg", policy["min_angle_deg"])])
+            if outline:
+                xs = [p[0] for seg in outline for p in seg]
+                ys = [p[1] for seg in outline for p in seg]
+                sx = (max(p[0] for p in pts) - min(p[0] for p in pts)) / max(1e-9, max(xs) - min(xs))
+                sy = (max(p[1] for p in pts) - min(p[1] for p in pts)) / max(1e-9, max(ys) - min(ys))
+                if min(sx, sy) < policy["min_spread"]:
+                    yield fid("NM-FID-005", Severity.WARNING,
+                              f"the {side} fiducials span {sx:.0%} of the board width and {sy:.0%} of its depth",
+                              f"{side}:spread", [_house("min_spread", policy["min_spread"])])
+
+
+# --- routing ------------------------------------------------------------------------------------
+
+
+def track_angle(project: Project) -> Iterator[Finding]:
+    """NM-ROUTE-001: copper tracks at 0, 45, 90 or 135 degrees only."""
+    b = board(project)
+    if b is None:
+        return
+    step, tolerance = house.LAYOUT["track_angle_step_deg"], house.LAYOUT["track_angle_tolerance_deg"]
+    for track in b.tracks:
+        if track.arc or not track.layer.endswith(".Cu"):
+            continue
+        dx, dy = track.end[0] - track.start[0], track.end[1] - track.start[1]
+        if math.hypot(dx, dy) < 1e-4:
+            continue
+        angle = math.degrees(math.atan2(-dy, dx)) % 180
+        off = abs(angle - round(angle / step) * step)
+        if off <= tolerance:
+            continue
+        shown = angle if angle <= 90 else 180 - angle
+        yield Finding(
+            rule_id="kicad.dfm.track_angle",
+            title=f"[NM-ROUTE-001] Track on {track.layer} (net {track.net or 'none'}) runs {shown:.1f} deg off "
+                  "horizontal",
+            severity=Severity.ERROR,
+            domain=Domain.BOARD,
+            location=_at(project, b, key=f"{track.layer}@{track.start[0]:g},{track.start[1]:g}", line=track.line),
+            evidence=(Evidence(kind="board", value=f"segment ({track.start[0]:g}, {track.start[1]:g}) to "
+                               f"({track.end[0]:g}, {track.end[1]:g}) mm", source=project.relative(b.path)),
+                      _house("track_angle_step_deg", step)),
+            explanation="Newmatik house routing uses 0, 45 and 90 degree tracks.",
+            consequence="Free-angle tracks are harder to review and to keep at clearance; they usually mean an "
+                        "unfinished autorouted or dragged segment.",
+            recommendation="Re-route the segment at 0, 45 or 90 degrees.",
+        )
+
+
+def via_in_pad(project: Project) -> Iterator[Finding]:
+    """NM-VIA-001: no via in or touching a pad."""
+    b = board(project)
+    if b is None:
+        return
+    pads = [p for fp in b.footprints for p in fp.pads if p.copper_layers]
+    for via in b.vias:
+        radius = via.size / 2
+        for pad in pads:
+            if house.distance_to_pad(via.x, via.y, _pad_dict(pad)) > radius:
+                continue
+            yield Finding(
+                rule_id="kicad.dfm.via_in_pad",
+                title=f"[NM-VIA-001] Via of net {via.net or 'none'} touches pad {pad.ref}.{pad.number}",
+                severity=Severity.ERROR,
+                domain=Domain.BOARD,
+                location=_at(project, b, component=pad.ref, pin=pad.number, key=f"via@{via.x:g},{via.y:g}",
+                             line=via.line),
+                evidence=(Evidence(kind="board", value=f"via {via.size:g} mm at ({via.x:g}, {via.y:g}) mm, pad "
+                                   f"{pad.ref}.{pad.number} {pad.w:g} x {pad.h:g} mm at ({pad.x:g}, {pad.y:g}) mm",
+                                   source=project.relative(b.path)),),
+                explanation="House rule: no via in or touching a pad (untented, unfilled vias).",
+                consequence="Solder wicks into the via: starved joints, voids, tombstoned passives.",
+                recommendation="Move the via off the pad and connect it with a short track, or specify filled and "
+                               "capped vias for this board.",
+            )
+            break
+
+
+def via_spacing(project: Project) -> Iterator[Finding]:
+    """NM-VIA-002: two vias of one net closer than the house distance."""
+    b = board(project)
+    if b is None:
+        return
+    limit = house.LAYOUT["same_net_via_min_mm"]
+    for a, c in itertools.combinations(b.vias, 2):
+        if not a.net or a.net != c.net:
+            continue
+        gap = math.hypot(a.x - c.x, a.y - c.y)
+        if gap >= limit:
+            continue
+        yield Finding(
+            rule_id="kicad.dfm.via_spacing",
+            title=f"[NM-VIA-002] Two vias of net {a.net} are {gap:.2f} mm apart",
+            severity=Severity.WARNING,
+            domain=Domain.BOARD,
+            location=_at(project, b, key=f"{a.net}@{a.x:g},{a.y:g}", line=a.line),
+            evidence=(Evidence(kind="board", value=f"vias at ({a.x:g}, {a.y:g}) and ({c.x:g}, {c.y:g}) mm",
+                               source=project.relative(b.path)), _house("same_net_via_min_mm", limit)),
+            explanation="Same-net vias this close usually do the job of one.",
+            consequence="Extra drill hits and a weakened plane for no electrical gain.",
+            recommendation="Merge them, unless they carry current or stitch a plane on purpose.",
+        )
+
+
+# --- 3D models ----------------------------------------------------------------------------------
+
+
+def _model_roots(b: Board) -> dict[str, list[Path]]:
+    """Where `${VAR}` in a model path can point: the environment, else KiCad's install."""
+    installs = [Path("/Applications/KiCad/KiCad.app/Contents/SharedSupport/3dmodels"),
+                Path.home() / "Applications/KiCad/KiCad.app/Contents/SharedSupport/3dmodels",
+                Path("/usr/share/kicad/3dmodels"), Path("/usr/local/share/kicad/3dmodels")]
+    if os.name == "nt":
+        base = Path(os.environ.get("ProgramFiles", r"C:\Program Files")) / "KiCad"
+        installs += sorted(base.glob("*/share/kicad/3dmodels"), reverse=True)
+    return {"KIPRJMOD": [Path(b.path).parent], "_install": [p for p in installs if p.is_dir()]}
+
+
+def resolve_model(path: str, b: Board) -> tuple[Path | None, str | None]:
+    """(file, None) or (None, why it cannot be resolved)."""
+    roots = _model_roots(b)
+    unresolved = None
+
+    def substitute(match: re.Match) -> str:
+        nonlocal unresolved
+        name = match.group(1)
+        if name == "KIPRJMOD":
+            return str(roots["KIPRJMOD"][0])
+        if os.environ.get(name):
+            return os.environ[name]
+        if re.fullmatch(r"KICAD\d*_3DMODEL_DIR", name) and roots["_install"]:
+            return str(roots["_install"][0])
+        unresolved = name
+        return match.group(0)
+
+    text = re.sub(r"\$\{([^}]+)\}", substitute, path)
+    if unresolved:
+        return None, f"${{{unresolved}}} is not set"
+    candidate = Path(text)
+    if not candidate.is_absolute():
+        candidate = Path(b.path).parent / candidate
+    return candidate, None
+
+
+def _step_for(path: Path) -> Path | None:
+    if path.suffix.lower() in (".step", ".stp"):
+        return path if path.is_file() else None
+    for suffix in (".step", ".stp", ".STEP", ".STP"):
+        sibling = path.with_suffix(suffix)
+        if sibling.is_file():
+            return sibling
+    return None
+
+
+def _model_state(fp: Footprint, b: Board) -> tuple[str, str]:
+    """("ok"|"missing"|"none"|"unresolved", detail)."""
+    if not fp.models:
+        return "none", "no 3D model referenced"
+    reasons = []
+    for model in fp.models:
+        resolved, why = resolve_model(model, b)
+        if resolved is None:
+            reasons.append(("unresolved", f"{model}: {why}"))
+            continue
+        step = _step_for(resolved)
+        if step is not None:
+            return "ok", str(step)
+        if resolved.suffix.lower() in (".step", ".stp"):
+            reasons.append(("missing", f"{model} does not exist"))
+        elif resolved.is_file():
+            reasons.append(("missing", f"{model} is not a STEP model and has no STEP file beside it"))
+        else:
+            reasons.append(("missing", f"{model} does not exist"))
+    kinds = {kind for kind, _ in reasons}
+    return ("missing" if "missing" in kinds else "unresolved"), "; ".join(text for _k, text in reasons)
+
+
+def _needs_model(fp: Footprint) -> bool:
+    return not is_fiducial(fp) and "board_only" not in fp.attributes and bool(fp.pads)
+
+
+def model_missing(project: Project) -> Iterator[Finding]:
+    """NM-3D-001: every footprint has a STEP model, and the file exists."""
+    b = board(project)
+    if b is None:
+        return
+    for fp in b.footprints:
+        if not _needs_model(fp):
+            continue
+        state, detail = _model_state(fp, b)
+        if state in ("ok", "unresolved"):
+            continue
+        yield Finding(
+            rule_id="kicad.dfm.model_missing",
+            title=f"[NM-3D-001] {fp.ref} ({fp.lib}) has no usable STEP model",
+            severity=Severity.WARNING,
+            domain=Domain.BOARD,
+            location=_at(project, b, component=fp.ref, key="model", line=fp.line),
+            evidence=(Evidence(kind="board", value=detail, source=project.relative(b.path)),),
+            explanation="Newmatik builds the assembly model and the enclosure fit from each part's STEP model.",
+            consequence="The 3D export has a hole where this part is; height and collision checks miss it.",
+            recommendation="Reference the manufacturer's STEP model (or a recognised library's) with a "
+                           "${KIPRJMOD}-relative or library path, and keep the file with the project.",
+        )
+
+
+def _model_scope(project: Project) -> tuple[int, list[str]]:
+    b = board(project)
+    if b is None:
+        return 0, []
+    checked, unchecked = 0, []
+    for fp in b.footprints:
+        if not _needs_model(fp):
+            continue
+        state, detail = _model_state(fp, b)
+        if state == "unresolved":
+            unchecked.append(f"{fp.ref}: {detail}")
+        else:
+            checked += 1
+    return checked, unchecked
+
+
+# --- silkscreen and barcode ---------------------------------------------------------------------
+
+
+def _text_box(g) -> list[tuple[float, float]]:
+    """A conservative extent for silkscreen text: 0.6 x height per character, centred."""
+    (x, y), half_w, half_h = g.points[0], len(g.text) * g.size * 0.3, g.size / 2
+    return [(x - half_w, y - half_h), (x + half_w, y - half_h), (x + half_w, y + half_h), (x - half_w, y + half_h)]
+
+
+def silkscreen_outside(project: Project) -> Iterator[Finding]:
+    """NM-SILK-001: silkscreen beyond the board outline (hidden texts do not print)."""
+    b = board(project)
+    outline = _outline(b) if b else None
+    if b is None or outline is None:
+        return
+    tolerance = house.LAYOUT["silk_tolerance_mm"]
+    graphics = list(b.graphics) + [g for fp in b.footprints for g in fp.graphics]
+    for g in graphics:
+        side = SILK.get(g.layer)
+        if side is None or g.hidden or (g.kind == "text" and not g.text.strip()):
+            continue
+        points = _text_box(g) if g.kind == "text" else list(g.points)
+        worst = max((0.0 if house.inside_segments(p, outline) else house.edge_distance_segments(p, outline))
+                    for p in points)
+        if worst <= tolerance:
+            continue
+        what = f"text {g.text!r}" if g.kind == "text" else g.kind
+        owner = f" of {g.ref}" if g.ref else ""
+        estimated = g.kind == "text"
+        yield Finding(
+            rule_id="kicad.dfm.silkscreen_outside",
+            title=f"[NM-SILK-001] {side} silkscreen {what}{owner} reaches {worst:.2f} mm beyond the outline",
+            severity=Severity.ERROR,
+            domain=Domain.BOARD,
+            location=_at(project, b, component=g.ref, key=f"{g.layer}@{points[0][0]:.2f},{points[0][1]:.2f}",
+                         line=g.line),
+            evidence=(Evidence(kind="board", value=f"{g.layer} {g.kind} at ({points[0][0]:.2f}, {points[0][1]:.2f}) mm"
+                               + (" (text extent estimated from its height)" if estimated else ""),
+                               source=project.relative(b.path)), _house("silk_tolerance_mm", tolerance)),
+            explanation="Silkscreen outside the board outline is cut off by the fabricator.",
+            consequence="Part of a marking (a reference, a board name, a warning) is missing on the board.",
+            recommendation="Move or shrink the silkscreen so it stays on the board.",
+            detector=Detector.HEURISTIC if estimated else Detector.DETERMINISTIC,
+            confidence=0.8 if estimated else 1.0,
+        )
+
+
+def _silk_lines(b: Board, layer: str) -> list[tuple[tuple[float, float], tuple[float, float]]]:
+    lines = []
+    for g in b.graphics:
+        if g.layer != layer or g.kind == "text":
+            continue
+        points = list(g.points)
+        closed = g.kind in ("rect", "poly")
+        pairs = zip(points, points[1:] + points[:1]) if closed else zip(points, points[1:])
+        lines.extend(pairs)
+    return lines
+
+
+def barcode_field(project: Project) -> Iterator[Finding]:
+    """NM-BC-001: a square silkscreen field with "BC" for the serial label, 5 mm at least (7 mm preferred)."""
+    b = board(project)
+    if b is None:
+        return
+    best = None
+    for g in b.graphics:
+        if g.kind != "text" or g.layer not in SILK or g.hidden or g.text.strip().upper() != "BC":
+            continue
+        cx, cy = g.points[0]
+        lines = _silk_lines(b, g.layer)
+        horizontal = [(a, c) for a, c in lines if abs(a[1] - c[1]) < 1e-3 and min(a[0], c[0]) <= cx <= max(a[0], c[0])]
+        vertical = [(a, c) for a, c in lines if abs(a[0] - c[0]) < 1e-3 and min(a[1], c[1]) <= cy <= max(a[1], c[1])]
+        below = [a[1] for a, _c in horizontal if a[1] > cy]
+        above = [a[1] for a, _c in horizontal if a[1] < cy]
+        left = [a[0] for a, _c in vertical if a[0] < cx]
+        right = [a[0] for a, _c in vertical if a[0] > cx]
+        if below and above and left and right:
+            size = min(min(below) - max(above), min(right) - max(left))
+            if best is None or size > best[0]:
+                best = (size, SILK[g.layer], g)
+    layout = house.LAYOUT
+    if best is None:
+        yield Finding(
+            rule_id="kicad.dfm.barcode_field",
+            title="[NM-BC-001] No barcode field on the silkscreen",
+            severity=Severity.WARNING,
+            domain=Domain.BOARD,
+            location=_at(project, b, key="barcode"),
+            evidence=(Evidence(kind="board", value='no silkscreen "BC" text inside a square silkscreen frame',
+                               source=project.relative(b.path)),
+                      _house("barcode_preferred_mm", layout["barcode_preferred_mm"])),
+            explanation="Newmatik labels every board with a serial barcode in a marked field.",
+            consequence="The label goes wherever there is room, over vias or parts, or the board is not traceable.",
+            recommendation=f"Draw a {layout['barcode_preferred_mm']:g} x {layout['barcode_preferred_mm']:g} mm square "
+                           f"(at least {layout['barcode_min_mm']:g} mm) on the top silkscreen with \"BC\" inside.",
+        )
+    elif best[0] + 1e-3 < layout["barcode_min_mm"]:
+        yield Finding(
+            rule_id="kicad.dfm.barcode_field",
+            title=(f"[NM-BC-001] The barcode field is {best[0]:.1f} mm; the house minimum is "
+                   f"{layout['barcode_min_mm']:g} mm"),
+            severity=Severity.WARNING,
+            domain=Domain.BOARD,
+            location=_at(project, b, key="barcode", line=best[2].line),
+            evidence=(Evidence(kind="board", value=f"{best[1]} field {best[0]:.2f} mm",
+                               source=project.relative(b.path)),
+                      _house("barcode_min_mm", layout["barcode_min_mm"])),
+            explanation="The serial label needs the field's full size to be scanned reliably.",
+            consequence="The label overhangs the field or cannot be applied.",
+            recommendation=f"Enlarge the field to {layout['barcode_preferred_mm']:g} mm.",
+        )
+
+
+# --- assembly requirements ----------------------------------------------------------------------
+
+
+def bottom_side_smd(project: Project) -> Iterator[Finding]:
+    """A single-sided board (per the requirements file) with SMD parts on the bottom."""
+    b = board(project)
+    req = requirements(project)
+    if b is None or req.assembly != "single-sided":
+        return
+    for fp in b.footprints:
+        if fp.side != "bottom" or is_fiducial(fp) or not _smd_on(fp, "bottom"):
+            continue
+        yield Finding(
+            rule_id="kicad.dfm.bottom_side_smd",
+            title=f"{fp.ref} is an SMD part on the bottom of a single-sided board",
+            severity=Severity.ERROR,
+            domain=Domain.BOARD,
+            location=_at(project, b, component=fp.ref, key="bottom", line=fp.line),
+            evidence=(Evidence(kind="board", value=f"{fp.ref} ({fp.lib}) on {fp.layer}",
+                               source=project.relative(b.path)),
+                      Evidence(kind="requirement", value='board.assembly = "single-sided"',
+                               source=project.relative(req.path) if req.path else None)),
+            explanation="The requirements file declares single-sided assembly; this part needs a second SMD pass.",
+            consequence="A second reflow side (paste, placement, fiducials) for one part, or a part left off.",
+            recommendation="Move the part to the top, or change the assembly requirement on purpose.",
+        )
+
+
+def _pad_corners(pad: Pad) -> list[tuple[float, float]]:
+    a = math.radians(pad.rotation)
+    cos, sin = math.cos(a), math.sin(a)
+    out = []
+    for sx, sy in ((-1, -1), (1, -1), (1, 1), (-1, 1)):
+        dx, dy = sx * pad.w / 2, sy * pad.h / 2
+        out.append((pad.x + dx * cos + dy * sin, pad.y - dx * sin + dy * cos))
+    return out
+
+
+def smd_edge_clearance(project: Project) -> Iterator[Finding]:
+    """SMD copper at least the required distance from the board edge."""
+    b = board(project)
+    req = requirements(project)
+    outline = _outline(b) if b else None
+    if b is None or outline is None or req.smd_edge_clearance_mm is None:
+        return
+    limit = req.smd_edge_clearance_mm
+    for fp in b.footprints:
+        if is_fiducial(fp):
+            continue
+        worst = None
+        for pad in fp.pads:
+            if pad.kind != "smd":
+                continue
+            distance = min(house.edge_distance_segments(c, outline) for c in _pad_corners(pad))
+            if worst is None or distance < worst[0]:
+                worst = (distance, pad)
+        if worst is None or worst[0] >= limit:
+            continue
+        distance, pad = worst
+        yield Finding(
+            rule_id="kicad.dfm.smd_edge_clearance",
+            title=f"{fp.ref} pad {pad.number} is {distance:.2f} mm from the board edge (required {limit:g} mm)",
+            severity=Severity.ERROR,
+            domain=Domain.BOARD,
+            location=_at(project, b, component=fp.ref, pin=pad.number, key="edge", line=pad.line),
+            evidence=(Evidence(kind="board", value=f"pad {pad.ref}.{pad.number} at ({pad.x:g}, {pad.y:g}) mm, "
+                               f"{pad.w:g} x {pad.h:g} mm", source=project.relative(b.path)),
+                      Evidence(kind="requirement", value=f"board.smd_edge_clearance_mm = {limit:g}",
+                               source=project.relative(req.path) if req.path else None)),
+            explanation="SMD copper this close to the edge sits where the conveyor clamps the board and where "
+                        "depaneling stresses it.",
+            consequence="Parts cannot be placed or are cracked at depaneling.",
+            recommendation="Move the part inward, or add a breakaway rail to the panel.",
+        )
+
+
+def _test_point_nets(b: Board) -> set[str]:
+    return {p.net for fp in b.footprints if is_test_point(fp) for p in fp.pads if p.net}
+
+
+def _testable_nets(b: Board, exempt: tuple[str, ...]) -> list[str]:
+    counts: dict[str, int] = {}
+    for fp in b.footprints:
+        for pad in fp.pads:
+            if pad.net:
+                counts[pad.net] = counts.get(pad.net, 0) + 1
+    wanted = {e.upper() for e in exempt}
+    return sorted(n for n, c in counts.items()
+                  if c >= 2 and not n.startswith("unconnected-") and n.upper() not in wanted
+                  and n.rsplit("/", 1)[-1].upper() not in wanted)
+
+
+def test_point_coverage(project: Project) -> Iterator[Finding]:
+    """Nets with two or more pads and no test-point footprint on them."""
+    b = board(project)
+    req = requirements(project)
+    if b is None or req.test_points == "off":
+        return
+    covered = _test_point_nets(b)
+    nets = _testable_nets(b, req.test_point_exempt)
+    missing = [n for n in nets if n not in covered]
+    if not missing:
+        return
+    yield Finding(
+        rule_id="kicad.dfm.test_point_coverage",
+        title=f"{len(missing)} of {len(nets)} nets have no test point",
+        severity=Severity.WARNING if req.test_points == "required" else Severity.INFO,
+        domain=Domain.BOARD,
+        location=_at(project, b, key="test_points"),
+        evidence=(Evidence(kind="board", value="without test point: " + ", ".join(missing[:20])
+                           + (f" and {len(missing) - 20} more" if len(missing) > 20 else ""),
+                           source=project.relative(b.path)),
+                  Evidence(kind="requirement", value=f'board.test_points = "{req.test_points}"',
+                           source=project.relative(req.path) if req.path else "EngineHall default")),
+        explanation="A net is testable in a bed-of-nails fixture when a test-point footprint (TP*) sits on it.",
+        consequence="Faults on these nets are found only by functional test, or not at all.",
+        recommendation="Add test points to the nets the test plan probes; exempt the rest in "
+                       "pcba-requirements.toml (board.test_point_exempt).",
+    )
+
+
+# --- courtyards ---------------------------------------------------------------------------------
+
+
+def _hull(points: list[tuple[float, float]]) -> list[tuple[float, float]]:
+    pts = sorted(set((round(x, 6), round(y, 6)) for x, y in points))
+    if len(pts) <= 2:
+        return pts
+
+    def cross(o, a, c):
+        return (a[0] - o[0]) * (c[1] - o[1]) - (a[1] - o[1]) * (c[0] - o[0])
+
+    lower, upper = [], []
+    for p in pts:
+        while len(lower) >= 2 and cross(lower[-2], lower[-1], p) <= 0:
+            lower.pop()
+        lower.append(p)
+    for p in reversed(pts):
+        while len(upper) >= 2 and cross(upper[-2], upper[-1], p) <= 0:
+            upper.pop()
+        upper.append(p)
+    return lower[:-1] + upper[:-1]
+
+
+def _penetration(a: list, c: list) -> float:
+    """Separating-axis overlap depth of two convex polygons (<= 0 when they do not overlap)."""
+    depth = math.inf
+    for poly in (a, c):
+        for p, q in zip(poly, poly[1:] + poly[:1]):
+            nx, ny = q[1] - p[1], p[0] - q[0]
+            length = math.hypot(nx, ny)
+            if length == 0:
+                continue
+            nx, ny = nx / length, ny / length
+            pa = [x * nx + y * ny for x, y in a]
+            pc = [x * nx + y * ny for x, y in c]
+            depth = min(depth, min(max(pa), max(pc)) - max(min(pa), min(pc)))
+            if depth <= 0:
+                return depth
+    return depth
+
+
+def _courtyard(fp: Footprint) -> list[tuple[float, float]] | None:
+    layer = "F.CrtYd" if fp.side == "top" else "B.CrtYd"
+    points = [p for g in fp.graphics if g.layer == layer and g.kind != "text" for p in g.points]
+    hull = _hull(points)
+    return hull if len(hull) >= 3 else None
+
+
+def courtyard_overlap(project: Project) -> Iterator[Finding]:
+    """Two footprints on one side whose courtyards overlap (each courtyard as its convex hull)."""
+    b = board(project)
+    if b is None:
+        return
+    shapes = [(fp, _courtyard(fp)) for fp in b.footprints]
+    shapes = [(fp, hull) for fp, hull in shapes if hull]
+    for (a, ha), (c, hc) in itertools.combinations(sorted(shapes, key=lambda s: s[0].ref), 2):
+        if a.side != c.side:
+            continue
+        depth = _penetration(ha, hc)
+        if depth <= 0.01:
+            continue
+        yield Finding(
+            rule_id="kicad.dfm.courtyard_overlap",
+            title=f"Courtyards of {a.ref} and {c.ref} overlap by {depth:.2f} mm",
+            severity=Severity.WARNING,
+            domain=Domain.BOARD,
+            location=_at(project, b, component=a.ref, key=f"courtyard:{c.ref}", line=a.line),
+            evidence=(Evidence(kind="board", value=f"{a.ref} at ({a.x:g}, {a.y:g}) and {c.ref} at ({c.x:g}, {c.y:g}) "
+                               f"mm on the {a.side}", source=project.relative(b.path)),),
+            explanation="A courtyard is the keep-out a part needs for placement and rework; two may touch but not "
+                        "overlap.",
+            consequence="The placement nozzle or a rework tool collides with the neighbour; parts shift or are "
+                        "damaged.",
+            recommendation="Move the parts apart until the courtyards only touch.",
+        )
+
+
+def _courtyard_scope(project: Project) -> tuple[int, list[str]]:
+    b = board(project)
+    if b is None:
+        return 0, []
+    checked = [fp for fp in b.footprints if _courtyard(fp)]
+    unchecked = [f"{fp.ref}: no courtyard" for fp in b.footprints if not _courtyard(fp) and fp.pads
+                 and not is_fiducial(fp)]
+    return len(checked), unchecked
+
+
+RULES = (drc_violation, drc_schematic_parity, fiducials, track_angle, via_in_pad, via_spacing, model_missing,
+         silkscreen_outside, barcode_field, bottom_side_smd, smd_edge_clearance, test_point_coverage,
+         courtyard_overlap)
+
+SCOPE = {
+    "kicad.dfm.model_missing": _model_scope,
+    "kicad.dfm.courtyard_overlap": _courtyard_scope,
+}