Skip to content

hashgraph-online/awesome-codex-plugins / plugins/aklofas/kicad-happy/skills/kicad

Analyze KiCad projects and PDF schematics: schematics, PCB layouts, Gerbers, footprints, symbols, netlists, and design rules. Reviews designs for bugs, traces nets, cross-references schematic to PCB, extracts BOM data, checks DRC/ERC, DFM, power trees, and regulator circuits. Every finding carries a confidence label and evidence source with trust_summary rollup. Analyzes PDF schematics from dev boards, reference designs, eval kits, and datasheets. Supports KiCad 5–10. Use whenever the user mentions .kicad_sch, .kicad_pcb, .kicad_pro, PCB design review, schematic analysis, PDF schematics, reference designs, Gerber files, DRC/ERC, netlist issues, BOM extraction, signal tracing, power budget, DFM, or wants to understand, debug, compare, or review any hardware design. Also for "check my board", "review before fab", "what's wrong with my schematic", "is this ready to order", "check my power supply", "verify this circuit", OSHWA certification readiness, or any electronics/PCB design question.

FileKindSize
SKILL.mdskill md79.1 KB
references/config-reference.mdmarkdown19.1 KB
references/datasheet-verification.mdmarkdown16.5 KB
references/deep-review.mdmarkdown9.7 KB
references/design-intent.mdmarkdown5.6 KB
references/diff-analysis.mdmarkdown17.6 KB
references/file-formats.mdmarkdown15.1 KB
references/gerber-parsing.mdmarkdown33.5 KB
references/manual-gerber-parsing.mdmarkdown24.5 KB
references/manual-pcb-parsing.mdmarkdown17.2 KB
references/manual-schematic-parsing.mdmarkdown12.8 KB
references/net-tracing.mdmarkdown12.0 KB
references/oshwa-certification.mdmarkdown4.5 KB
references/output-schema.mdmarkdown33.4 KB
references/pcb-layout-analysis.mdmarkdown27.3 KB
references/pdf-schematic-extraction.mdmarkdown15.2 KB
references/report-generation.mdmarkdown56.3 KB
references/schematic-analysis.mdmarkdown63.9 KB
references/standards-compliance.mdmarkdown33.5 KB
references/supplementary-data-sources.mdmarkdown12.5 KB
references/what-if.mdmarkdown19.5 KB
review/README.mdmarkdown4.1 KB
review/fixtures/deep_review.example.jsonconfig1.2 KB
review/fixtures/design_context.example.jsonconfig388 B
review/fixtures/review_annotations.example.jsonconfig707 B
review/prompts/design_context.mdmarkdown4.9 KB
review/schemas/deep_review.schema.jsonconfig3.3 KB
review/schemas/design_context.schema.jsonconfig2.2 KB
review/schemas/review_annotations.schema.jsonconfig1.9 KB
review/scripts/_mini_jsonschema.pyscript6.6 KB
review/scripts/build_review_plan.pyscript2.3 KB
review/scripts/deep_review_gate.pyscript27.3 KB
review/scripts/merge_annotations.pyscript7.0 KB
review/scripts/validate_review.pyscript2.6 KB
scripts/.gitignoreother13 B
scripts/README.mdmarkdown23.4 KB
scripts/analysis_cache.pyscript42.1 KB
scripts/analyze_gerbers.pyscript90.9 KB
scripts/analyze_pcb.pyscript7.4 KB
scripts/analyze_schematic.pyscript6.7 KB
scripts/analyze_thermal.pyscript48.5 KB
scripts/analyzer_envelope.pyscript15.5 KB
scripts/capability_mode.pyscript10.2 KB
scripts/check_report_sections.pyscript10.6 KB
scripts/cross_analysis.pyscript69.4 KB
scripts/cross_verify.pyscript23.1 KB
scripts/design_intent.pyscript13.5 KB
scripts/detection_schema.pyscript26.0 KB
scripts/detector_helpers.pyscript15.2 KB
scripts/diff_analysis.pyscript23.5 KB
scripts/diff_engine.pyscript47.2 KB
scripts/domain_detectors.pyscript260.5 KB
scripts/envelopes/__init__.pyscript0 B
scripts/envelopes/cross_analysis.pyscript5.9 KB
scripts/envelopes/gerber.pyscript16.1 KB
scripts/envelopes/pcb.pyscript25.9 KB
scripts/envelopes/schematic.pyscript23.1 KB
scripts/envelopes/thermal.pyscript7.4 KB
scripts/export_issues.pyscript27.6 KB
scripts/fab_release_gate.pyscript29.8 KB
scripts/finding_schema.pyscript25.7 KB
scripts/gen_output_schema_md.pyscript9.2 KB
scripts/inputs_builder.pyscript4.0 KB
scripts/kicad_core/__init__.pyscript0 B
scripts/kicad_core/classify.pyscript32.5 KB
scripts/kicad_core/cli.pyscript4.2 KB
scripts/kicad_core/coords.pyscript2.0 KB
scripts/kicad_core/diagnostics.pyscript1.9 KB
scripts/kicad_core/executables.pyscript1.0 KB
scripts/kicad_core/fields.pyscript5.9 KB
scripts/kicad_core/fileio.pyscript5.4 KB
scripts/kicad_core/hotloop.pyscript3.1 KB
scripts/kicad_core/instances.pyscript5.7 KB
scripts/kicad_core/model.pyscript4.8 KB
scripts/kicad_core/netnames.pyscript19.1 KB
scripts/kicad_core/netquery.pyscript6.7 KB
scripts/kicad_core/pairing.pyscript1.9 KB
scripts/kicad_core/parts.pyscript28.9 KB
scripts/kicad_core/passives.pyscript10.0 KB
scripts/kicad_core/pdn.pyscript1011 B
scripts/kicad_core/project.pyscript43.2 KB
scripts/kicad_core/render.pyscript2.7 KB
scripts/kicad_core/sexp.pyscript12.6 KB
scripts/kicad_core/textvars.pyscript5.4 KB
scripts/kicad_core/token_cache.pyscript2.2 KB
scripts/kicad_core/values.pyscript14.1 KB
scripts/kicad_types.pyscript15.1 KB
scripts/lifecycle_audit.pyscript6.7 KB
scripts/lifecycle_engine.pyscript52.8 KB
scripts/lookup_detectors.pyscript29.9 KB
scripts/lookup_helpers.pyscript3.0 KB
scripts/methodology_gerbers.mdmarkdown23.1 KB
scripts/methodology_pcb.mdmarkdown22.2 KB
scripts/methodology_schematic.mdmarkdown43.1 KB
scripts/netlist_queries.pyscript4.2 KB
scripts/output_filters.pyscript16.8 KB
scripts/output_io.pyscript5.3 KB
scripts/pcb/__init__.pyscript0 B
scripts/pcb/assembly.pyscript58.3 KB
scripts/pcb/connectivity.pyscript27.7 KB
scripts/pcb/copper.pyscript61.0 KB
scripts/pcb/dfm.pyscript56.9 KB
scripts/pcb/geometry.pyscript59.5 KB
scripts/pcb/pipeline.pyscript30.3 KB
scripts/pcb/presentation.pyscript24.3 KB
scripts/pcb/reader.pyscript87.1 KB
scripts/pcb/routing.pyscript53.5 KB
scripts/project_config.pyscript23.1 KB
scripts/risk_summary.pyscript3.1 KB
scripts/run_id.pyscript1.7 KB
scripts/schema_codec.pyscript5.0 KB
scripts/schematic/__init__.pyscript0 B
scripts/schematic/audits.pyscript56.0 KB
scripts/schematic/bom_stats.pyscript6.1 KB
scripts/schematic/connectivity.pyscript62.9 KB
scripts/schematic/erc_pins.pyscript8.4 KB
scripts/schematic/hierarchy.pyscript21.5 KB
scripts/schematic/ic_analysis.pyscript21.4 KB
scripts/schematic/legacy_reader.pyscript49.4 KB
scripts/schematic/net_analysis.pyscript75.5 KB
scripts/schematic/pipeline.pyscript72.2 KB
scripts/schematic/presentation.pyscript20.9 KB
scripts/schematic/reader.pyscript64.7 KB
scripts/schematic/system_analyses.pyscript126.9 KB
scripts/signal_detectors.pyscript248.0 KB
scripts/summarize_findings.pyexecutablescript17.4 KB
scripts/validation_detectors.pyscript75.3 KB
scripts/what_if.pyscript68.4 KB

scripts/pcb/assembly.py

View on GitHub
"""PCB placement and assembly checks: decoupling placement, placement/courtyards,
tombstoning, switching loops, fiducials, test points, orientation, silkscreen overlaps, keepouts."""

import math
import re

from kicad_core.classify import is_touch_pad
from kicad_core.hotloop import polygon_loop_area
from kicad_core.netnames import IC_SIGNAL_PIN_TYPES, is_ground_name, is_power_net_name
from pcb.geometry import (_outline_shape_points, _refined_overlap_mm2, _signed_depth,
                          courtyards_collide, outline_edge_distance, outline_loops,
                          overlap_area_mm2, point_in_outline)


# Whole-name match: VIN+/VINA/VBAT_OK/VREF/VCOUT and op-amp "+" pins are signals.
_SUPPLY_PIN_NAME = re.compile(
    r"(?:VCC|VDD|VIN|AVDD|DVDD|PVDD|VDDA|VDDIO|VDDQ|VBAT)(?:_?\d+)?|V\+", re.I)

_ESD_TVS_PREFIXES = ("esd", "prtr", "usblc", "tpd", "pesd", "sp05",
                     "rclamp", "nup", "lesd", "ip4", "dt104")


def _min_power_pad_distance(ic_fp: dict, cap_fp: dict) -> float:
    """Minimum distance between IC power/ground pads and capacitor pads.

    Uses absolute pad coordinates for accurate distance on large packages
    where footprint center can be 3+ mm from the actual power pin.
    Falls back to footprint center distance if pad data is missing.
    """
    # EQ-101: d = √((x1-x2)² + (y1-y2)²) over all pad pairs; return minimum.
    # Source: Self-evident — 2D Euclidean distance.
    ic_pads = ic_fp.get("pads", [])
    cap_pads = cap_fp.get("pads", [])

    # Find IC pads on power or ground nets
    power_pads = []
    for pad in ic_pads:
        net = pad.get("net_name", "")
        if not net:
            continue
        nu = net.upper()
        is_pwr_gnd = (
            nu in ("GND", "VSS", "AGND", "DGND", "PGND", "VCC", "VDD",
                   "AVCC", "AVDD", "DVCC", "DVDD") or
            nu.startswith(("GND", "VSS", "VCC", "VDD", "+")) or
            nu.endswith(("GND", "VSS")) or
            "V" in nu and any(c.isdigit() for c in nu)
        )
        if is_pwr_gnd:
            power_pads.append(pad)

    if not power_pads or not cap_pads:
        # Fallback: footprint center distance
        dx = ic_fp["x"] - cap_fp["x"]
        dy = ic_fp["y"] - cap_fp["y"]
        return math.sqrt(dx * dx + dy * dy)

    # Minimum distance between any IC power pad and any cap pad
    min_dist = float("inf")
    for ip in power_pads:
        ix, iy = ip.get("abs_x"), ip.get("abs_y")
        if ix is None or iy is None:
            continue
        for cp in cap_pads:
            cx, cy = cp.get("abs_x"), cp.get("abs_y")
            if cx is None or cy is None:
                continue
            d = math.sqrt((ix - cx) ** 2 + (iy - cy) ** 2)
            if d < min_dist:
                min_dist = d
    return min_dist


def _ic_signal_nets(ic: dict, power_rails: set[str] | None,
                    pin_signals: frozenset[str]) -> set[str]:
    """The IC's nets that its own pad marks as a signal pin (KiCad 6+ pad pin types), less the
    power rails: the rail set, a rail name (bar the VPP/VM nets in *pin_signals*), or the IC's
    supply pin on the net (by pin type or a supply pin name). A cap on such a net is a load,
    filter or timing cap."""
    rails, signals = set(), set()
    for pad in ic.get("pads", []):
        n = pad.get("net_name")
        if not n:
            continue
        pin_type = str(pad.get("pintype", "")).split("+")[0]
        if ((n not in pin_signals and is_power_net_name(n, power_rails))
                or pin_type in ("power_in", "power_out")
                or _SUPPLY_PIN_NAME.fullmatch(str(pad.get("pinfunction", "")))):
            rails.add(n)
        elif pin_type in IC_SIGNAL_PIN_TYPES:
            signals.add(n)
    return signals - rails


def _nearby_decoupling_caps(ic: dict, caps: list[dict],
                            signals: set[str] | frozenset[str] = frozenset()
                            ) -> tuple[list[dict], list[str]]:
    """Caps within 10 mm that share a non-ground net with the IC, other than its *signals*.
    Returns (nearby sorted by distance, refs of <=10 mm caps rejected as
    ground-only)."""
    ic_nets = {p.get("net_name") for p in ic.get("pads", []) if p.get("net_name")}
    nearby, rejected = [], []
    for cap in caps:
        dist = _min_power_pad_distance(ic, cap)
        if dist > 10.0:
            continue
        cap_nets = {p.get("net_name") for p in cap.get("pads", []) if p.get("net_name")}
        shared = {n for n in (ic_nets & cap_nets) if n and not is_ground_name(n)}
        if not shared:
            rejected.append(cap["reference"])
            continue
        shared -= signals
        if not shared:
            continue
        nearby.append({"cap": cap["reference"], "value": cap.get("value", ""),
                       "distance_mm": round(dist, 2), "shared_nets": sorted(shared),
                       "same_side": cap["layer"] == ic["layer"]})
    nearby.sort(key=lambda n: (n["distance_mm"], n["cap"]))
    return nearby, sorted(rejected)


def analyze_decoupling_placement(footprints: list[dict], power_rails: set[str] | None = None,
                                 pin_signals: frozenset[str] = frozenset()) -> list[dict]:
    """For each IC, find nearby capacitors and report distances.

    Helps verify decoupling caps are placed close to IC power pins. A cap that shares only
    the IC's signal-pin nets (`_ic_signal_nets`) is not its decoupling; an ESD part's bypass
    cap counts on any shared non-ground net.
    """
    # EQ-048: d = √(Δx²+Δy²) (cap-to-IC distance)
    ics = [fp for fp in footprints
           if re.match(r'^(U|IC)\d', fp.get("reference", ""))
           and not any(fp.get("value", "").lower().startswith(p)
                       for p in _ESD_TVS_PREFIXES)]
    caps = [fp for fp in footprints if re.match(r'^C\d', fp.get("reference", ""))]

    if not caps:
        return []

    results = []
    for ic in ics:
        nearby, rejected = _nearby_decoupling_caps(
            ic, caps, _ic_signal_nets(ic, power_rails, pin_signals))
        if nearby:
            entry = {
                "ic": ic["reference"],
                "value": ic.get("value", ""),
                "layer": ic["layer"],
                "nearby_caps": nearby,
                "closest_cap_mm": nearby[0]["distance_mm"],
            }
            if rejected:
                entry["gnd_only_caps"] = rejected
            results.append(entry)

    # ESD protection ICs need bypass caps within 3mm for clamping
    esd_ics = [fp for fp in footprints
               if re.match(r'^(U|IC)\d', fp.get("reference", ""))
               and any(fp.get("value", "").lower().startswith(p)
                       for p in _ESD_TVS_PREFIXES)]
    for ic in esd_ics:
        nearby, rejected = _nearby_decoupling_caps(ic, caps)
        if nearby:
            entry = {
                "ic": ic["reference"],
                "value": ic.get("value", ""),
                "layer": ic["layer"],
                "category": "esd_bypass",
                "nearby_caps": nearby,
                "closest_cap_mm": nearby[0]["distance_mm"],
            }
            if rejected:
                entry["gnd_only_caps"] = rejected
            results.append(entry)

    return results


_RF_MODULE_KEYWORDS = (
    'ESP32', 'ESP8266', 'WROOM', 'WROVER', 'XIAO', 'nRF52', 'nRF53',
    'RN4871', 'RN4870', 'RAK', 'LoRa', 'SIM800', 'SIM7', 'EC25', 'SIM868',
    'BGM', 'BGT', 'BM71', 'HM-10', 'HC-05',
)


_RF_LIB_KEYWORDS = ('RF_Module', 'RF_WiFi', 'RF_Bluetooth', 'RF_GPS')


def _is_rf_module(fp: dict) -> bool:
    """Return True if the footprint looks like an RF/wireless module."""
    library = fp.get('library', '') or ''
    value = fp.get('value', '') or ''
    for kw in _RF_LIB_KEYWORDS:
        if kw in library:
            return True
    for kw in _RF_MODULE_KEYWORDS:
        if kw.lower() in value.lower() or kw.lower() in library.lower():
            return True
    return False


# Edge-mount footprint categories: by-design at the board edge — PM-002 edge
# clearance should demote to info (not warning/error) for these.
_EDGE_MOUNT_LIBRARY_KEYWORDS = (
    'SMA_Edge',                           # edge-launch SMA antenna connectors
    'USB_C_Receptacle',                   # vertical/board-edge USB-C
    'USB_Mini', 'USB_Micro',              # board-edge USB Mini/Micro
    'USB_A_Vertical', 'USB_B_Vertical',
    'MagJack',                            # RJ45 with integrated mag — by-edge
    'microSD', 'SD_Card',                 # microSD/SD card edge sockets
    'BarrelJack',                         # DC barrel jack at edge
    'Standoff', 'Mounting',               # mounting features near edge are intentional
    'TerminalBlock',                      # screw terminals at board edge
    'Phoenix_MSTB',                       # Phoenix MSTB/MSTBA/MSTBVA terminal-block family
    'JST_', 'Molex_PicoBlade',            # edge-launched JST/Molex wire-to-board
)


_EDGE_MOUNT_VALUE_KEYWORDS = (
    'EDGE', 'VERTICAL',                   # value-string hints
)


def _is_edge_mount_footprint(fp: dict) -> bool:
    """Return True if the footprint is designed to sit at the board edge
    (board-edge connector, edge-launch antenna, mounting hole, etc.).
    PM-002 demotes edge-clearance findings to info for these.
    """
    library = fp.get('library', '') or fp.get('footprint', '') or ''
    value = fp.get('value', '') or ''
    for kw in _EDGE_MOUNT_LIBRARY_KEYWORDS:
        if kw.lower() in library.lower():
            return True
    for kw in _EDGE_MOUNT_VALUE_KEYWORDS:
        if kw in value.upper():
            return True
    return False


def _clearance_points(fp: dict) -> list[tuple[float, float]]:
    """Courtyard polygon vertices, else courtyard bbox corners, else the anchor."""
    pts = [(p[0], p[1]) for poly in (fp.get("_courtyard_poly") or fp.get("courtyard_poly") or [])
           for p in poly]
    if not pts and fp.get("courtyard"):
        c = fp["courtyard"]
        pts = [(c["min_x"], c["min_y"]), (c["max_x"], c["min_y"]),
               (c["max_x"], c["max_y"]), (c["min_x"], c["max_y"])]
    return pts or [(fp["x"], fp["y"])]


def _edge_boxes(edges: list[dict]) -> list[tuple[tuple[float, float, float, float], dict]]:
    """(min_x, min_y, max_x, max_y) of each outline edge, 0.01 mm loose for tessellation."""
    out = []
    for e in edges:
        shape = _outline_shape_points(e)
        if shape is None:
            continue
        xs = [p[0] for p in shape[0]]
        ys = [p[1] for p in shape[0]]
        out.append(((min(xs) - 0.01, min(ys) - 0.01, max(xs) + 0.01, max(ys) + 0.01), e))
    return out


def _outline_clearance(fp: dict, loops: list, edges: list[dict],
                       edge_boxes: list) -> tuple[float, bool]:
    """(clearance, off_board) against the closed outline: the nearest edge distance when every
    point is on the board, else minus the farthest outside distance; off-board when no point and
    no pad is on it. Slots and cutouts are board edge (even-odd)."""
    pts = _clearance_points(fp)
    # an edge more than 1 mm from the points' box cannot decide a clearance under 1 mm
    x0 = min(p[0] for p in pts) - 1.0
    y0 = min(p[1] for p in pts) - 1.0
    x1 = max(p[0] for p in pts) + 1.0
    y1 = max(p[1] for p in pts) + 1.0
    near = [e for (ex0, ey0, ex1, ey1), e in edge_boxes
            if ex0 <= x1 and ex1 >= x0 and ey0 <= y1 and ey1 >= y0]
    inside_d: list[float] = []
    outside_d: list[float] = []
    for x, y in pts:
        d = outline_edge_distance(x, y, near)
        d = math.inf if d is None else d
        # a point on the edge (closer than the reported 0.01 mm) is on the board
        if d < 0.005 or point_in_outline(x, y, loops):
            inside_d.append(d)
        else:
            outside_d.append(outline_edge_distance(x, y, edges) or 0.0)
    if not outside_d:
        return min(inside_d), False
    # a part whose pads reach the board (a mid-mount part in a cutout) overhangs, it is not off it
    on_board = bool(inside_d) or any(
        point_in_outline(p["abs_x"], p["abs_y"], loops)
        or (outline_edge_distance(p["abs_x"], p["abs_y"], edges) or 0.0) < 0.005
        for p in fp.get("pads", []) if "abs_x" in p and "abs_y" in p)
    return -max(outside_d), not on_board


def _bbox_clearance(fp: dict, bx_min: float, by_min: float,
                    bx_max: float, by_max: float) -> tuple[float, bool]:
    """(clearance, off_board) against the outline's bounding box."""
    cx, cy = fp["x"], fp["y"]
    min_edge = min(cx - bx_min, bx_max - cx, cy - by_min, by_max - cy)
    fp_min_x = fp_max_x = cx
    fp_min_y = fp_max_y = cy
    if fp.get("courtyard"):
        cy_box = fp["courtyard"]
        fp_min_x, fp_max_x = cy_box["min_x"], cy_box["max_x"]
        fp_min_y, fp_max_y = cy_box["min_y"], cy_box["max_y"]
        min_edge = min(
            cy_box["min_x"] - bx_min,
            bx_max - cy_box["max_x"],
            cy_box["min_y"] - by_min,
            by_max - cy_box["max_y"],
        )
    # A bbox entirely outside the outline bbox isn't "near the edge" — it's off the board
    is_off_board = (fp_max_x < bx_min or fp_min_x > bx_max or
                    fp_max_y < by_min or fp_min_y > by_max)
    return min_edge, is_off_board


def _courtyard_sides(fp: dict) -> dict:
    """Courtyard layer -> {"box", "polys", "rounded"} of a footprint. A footprint without
    per-layer data has its merged courtyard on the side it is mounted on."""
    sides = fp.get("_courtyard_sides")
    if sides is not None:
        return sides
    box = fp.get("courtyard")
    if not box:
        return {}
    side = "B.CrtYd" if str(fp.get("layer", "")).startswith("B.") else "F.CrtYd"
    return {side: {"box": box, "polys": fp.get("_courtyard_poly") or fp.get("courtyard_poly"),
                   "rounded": fp.get("courtyard_poly")}}


def analyze_placement(footprints: list[dict], outline: dict, *,
                      check_overlaps: bool = True,
                      board_area_mm2: float | None = None) -> dict:
    """Component placement analysis — courtyard overlaps and edge clearance.

    Reports:
    - Courtyard overlaps: pairs of components whose courtyards on the same courtyard
      layer overlap (potential physical collision or assembly issue)
    - Edge clearance: components closest to board edges (flagged if <0.5mm)
    - Placement density per board side

    ``check_overlaps`` False skips the overlaps (the project ignores KiCad's
    ``courtyards_overlap`` check). ``board_area_mm2`` is the area the density is taken over (the
    summed board area of a file with several boards); None uses the outline's bounding box.
    """
    # Courtyard overlap detection. One entry per footprint and courtyard layer: KiCad tests
    # F.CrtYd against F.CrtYd and B.CrtYd against B.CrtYd, whichever side each part is
    # mounted on. A pair colliding on both layers is reported once.
    overlaps = []
    fp_with_cy = [(fp, sd["box"], sd["polys"], sd["rounded"], side) for fp in footprints
                  if check_overlaps
                  for side, sd in _courtyard_sides(fp).items()]
    reported: set = set()

    for i in range(len(fp_with_cy)):
        fp_a, cy_a, _raw_a, _polys_a, side_a = fp_with_cy[i]
        for j in range(i + 1, len(fp_with_cy)):
            fp_b, cy_b, _raw_b, _polys_b, side_b = fp_with_cy[j]
            if side_a != side_b or fp_a is fp_b or (id(fp_a), id(fp_b)) in reported:
                continue
            # AABB overlap check; KiCad shrinks each courtyard by 0.005 mm, so
            # courtyards that touch or overlap by less than 0.01 mm do not collide
            # (the 0.001 mm slack covers the bbox's rounding)
            ox = min(cy_a["max_x"], cy_b["max_x"]) - max(cy_a["min_x"], cy_b["min_x"])
            oy = min(cy_a["max_y"], cy_b["max_y"]) - max(cy_a["min_y"], cy_b["min_y"])
            if ox >= 0.009 and oy >= 0.009:
                overlap_mm2 = round(ox * oy, 3)
                # AABB is only a pre-filter — notched courtyards
                # (QFP cross shapes) fill their corners in bbox space. With
                # chained polygons on both parts, test the real shapes; the
                # area is measured on the unshrunk shapes.
                if not (_polys_a and _polys_b):
                    if ox < 0.01 - 1e-7 or oy < 0.01 - 1e-7:
                        continue
                else:
                    if not courtyards_collide(_raw_a or _polys_a, _raw_b or _polys_b):
                        continue
                    _refined = _refined_overlap_mm2(
                        _polys_a, _polys_b,
                        max(cy_a["min_x"], cy_b["min_x"]),
                        max(cy_a["min_y"], cy_b["min_y"]),
                        min(cy_a["max_x"], cy_b["max_x"]),
                        min(cy_a["max_y"], cy_b["max_y"]))
                    if _refined <= 0.0:
                        # a thin crossing fell between the samples
                        _refined = overlap_area_mm2(
                            _polys_a, _polys_b,
                            max(cy_a["min_x"], cy_b["min_x"]),
                            max(cy_a["min_y"], cy_b["min_y"]),
                            min(cy_a["max_x"], cy_b["max_x"]),
                            min(cy_a["max_y"], cy_b["max_y"]))
                    overlap_mm2 = round(_refined, 3)
                reported.add((id(fp_a), id(fp_b)))
                layer = "B.Cu" if side_a == "B.CrtYd" else "F.Cu"
                is_rf_overlap = _is_rf_module(fp_a) or _is_rf_module(fp_b)
                # RF module courtyards deliberately encode the antenna RF
                # keepout (e.g., ESP32-S3-WROOM-1 extends ~7mm past the body
                # to enforce the no-copper keepout).  Overlap with a neighbor
                # usually means the neighbor is inside the keepout, not a
                # physical body collision.  Demote to info with a hint.
                if is_rf_overlap:
                    severity = 'info'
                elif overlap_mm2 > 1.0:
                    severity = 'error'
                else:
                    severity = 'warning'
                rf_note = (' (courtyard includes RF keepout — verify neighbor '
                           'is outside the antenna keepout, not a body collision)'
                           if is_rf_overlap else '')
                overlaps.append({
                    "component_a": fp_a["reference"],
                    "component_b": fp_b["reference"],
                    "layer": layer,
                    "overlap_mm2": overlap_mm2,
                    "detector": "analyze_placement",
                    "rule_id": "PM-001",
                    "category": "placement",
                    "severity": severity,
                    "confidence": "deterministic",
                    "evidence_source": "topology",
                    "summary": f"Courtyard overlap between {fp_a['reference']} and {fp_b['reference']} ({overlap_mm2}mm\u00b2){rf_note}",
                    "description": f"Components {fp_a['reference']} and {fp_b['reference']} have overlapping courtyards on {layer} ({overlap_mm2}mm\u00b2 overlap area). Threshold: \u22651.0mm\u00b2 = error, else warning; RF-module overlaps demote to info (courtyard encodes RF keepout).",
                    "components": [fp_a["reference"], fp_b["reference"]],
                    "nets": [],
                    "pins": [],
                    "recommendation": f"Resolve courtyard overlap between {fp_a['reference']} and {fp_b['reference']} — move components apart or adjust courtyard geometry",
                    "report_context": {"section": "Placement", "impact": "assembly", "standard_ref": ""},
                })

    overlaps.sort(key=lambda o: o["overlap_mm2"], reverse=True)

    # Edge clearance — distance from the courtyard to the nearest board edge
    edge_close: list[dict] = []
    bbox = outline.get("bounding_box")
    edges = outline.get("edges") or []
    # an outline that does not close is measured as its bounding box, as KiCad does
    loops = outline_loops(edges)
    edge_boxes = _edge_boxes(edges) if loops else []
    if bbox:
        bx_min, by_min = bbox["min_x"], bbox["min_y"]
        bx_max, by_max = bbox["max_x"], bbox["max_y"]
        for fp in footprints:
            if not fp.get("reference"):
                continue
            if loops:
                min_edge, is_off_board = _outline_clearance(fp, loops, edges, edge_boxes)
            else:
                min_edge, is_off_board = _bbox_clearance(fp, bx_min, by_min, bx_max, by_max)

            if min_edge < 1.0:  # Flag components within 1mm of edge
                clearance = round(min_edge, 2)
                # Off-board is checked ahead of the RF/edge-mount
                # exemptions below (those are for by-design partial overhang).
                # RF module footprints deliberately put the courtyard past the
                # board edge to expose the antenna to free space (WROOM-1 etc.).
                # Edge-mount footprints (SMA_Edge, USB_C vertical, MagJack,
                # microSD, BarrelJack, mounting holes, etc.) belong at the
                # board edge by design. Both demote the edge-clearance finding
                # to info with a hint.
                is_rf = _is_rf_module(fp)
                is_edge_mount = _is_edge_mount_footprint(fp)
                if is_off_board:
                    severity = 'warning'
                    rf_suffix = ''
                elif is_rf:
                    severity = 'info'
                    rf_suffix = (' (RF module antenna at board edge — '
                                 'verify antenna clearance, not a body collision)')
                elif is_edge_mount:
                    severity = 'info'
                    rf_suffix = (' (edge-mount footprint — by-design at board edge)')
                elif clearance < 0.5:
                    severity = 'error'
                    rf_suffix = ''
                else:
                    severity = 'warning'
                    rf_suffix = ''
                _summary = f"{fp['reference']} is {clearance}mm from board edge{rf_suffix}"
                _description = (f"Component {fp['reference']} on {fp['layer']} is only "
                                f"{clearance}mm from the board edge, risking damage "
                                f"during depaneling or handling.")
                _recommendation = (f"Move {fp['reference']} further from board edge "
                                   f"(currently {clearance}mm, recommend >= 1.0mm)")
                if is_off_board:
                    # Fully outside the outline — distinct from an
                    # overhang, never rendered as a negative distance.
                    _summary = (f"{fp['reference']} placed off-board "
                                f"({abs(clearance):.1f} mm outside outline)")
                    _description = (f"Component {fp['reference']} on {fp['layer']} has "
                                    f"its footprint entirely outside the board outline "
                                    f"({abs(clearance):.1f}mm outside), not merely "
                                    f"overhanging the edge.")
                    _recommendation = (f"Move {fp['reference']} onto the board — its "
                                       f"footprint currently lies completely outside "
                                       f"the outline.")
                elif clearance < 0:
                    # Negative clearance means the courtyard
                    # overhangs the outline — "move further from edge" is
                    # nonsense there. Applies regardless of the RF/edge-mount
                    # exemption (those only demote severity, not the message).
                    _summary = (f"{fp['reference']} courtyard overhangs board "
                                f"edge by {abs(clearance)}mm")
                    _description = (f"Component {fp['reference']} on {fp['layer']} has "
                                    f"a courtyard extending {abs(clearance)}mm past the "
                                    f"board outline. If not intentional (castellated or "
                                    f"edge-mount part), it will collide with the edge.")
                    _recommendation = (f"Verify the overhang on {fp['reference']} is "
                                       f"intentional; if not, place it inside the outline.")
                edge_close.append({
                    "component": fp["reference"],
                    "layer": fp["layer"],
                    "edge_clearance_mm": clearance,
                    "detector": "analyze_placement",
                    "rule_id": "PM-002",
                    "category": "placement",
                    "severity": severity,
                    "confidence": "deterministic",
                    "evidence_source": "topology",
                    "summary": _summary,
                    "description": _description,
                    "components": [fp["reference"]],
                    "nets": [],
                    "pins": [],
                    "recommendation": _recommendation,
                    "report_context": {"section": "Placement", "impact": "manufacturability", "standard_ref": ""},
                })

    edge_close.sort(key=lambda e: e["edge_clearance_mm"])

    # Placement density
    board_area = board_area_mm2
    if board_area is None and bbox:
        board_area = bbox["width"] * bbox["height"]

    front_count = sum(1 for fp in footprints if fp["layer"] == "F.Cu")
    back_count = sum(1 for fp in footprints if fp["layer"] == "B.Cu")

    density: dict = {}
    if board_area and board_area > 0:
        density["board_area_cm2"] = round(board_area / 100.0, 2)
        if front_count:
            density["front_density_per_cm2"] = round(front_count / (board_area / 100.0), 1)
        if back_count:
            density["back_density_per_cm2"] = round(back_count / (board_area / 100.0), 1)

    result: dict = {"density": density}
    if overlaps:
        result["courtyard_overlaps"] = overlaps[:50]
        result["overlap_count"] = len(overlaps)
    if edge_close:
        result["edge_clearance_warnings"] = edge_close[:20]

    return result


def _extract_package_code(footprint_name: str) -> str:
    """Extract package size code from footprint library name.

    Recognizes patterns like:
    - "Capacitor_SMD:C_0402_1005Metric" -> "0402"
    - "Resistor_SMD:R_0201_0603Metric" -> "0201"
    - "Package_TO_SOT_SMD:SOT-23" -> ""
    """
    m = re.search(r'[_:](?:C|R|L)_(\d{4})_', footprint_name)
    if m:
        return m.group(1)
    # Also try bare pattern like "0402" or "0201" in the name
    m = re.search(r'(?:^|[_:])(\d{4})(?:_|$|Metric)', footprint_name)
    if m:
        code = m.group(1)
        if code in ("0201", "0402", "0603", "0805", "1206", "1210", "2512"):
            return code
    return ""


def analyze_tombstoning_risk(footprints: list[dict], tracks: dict,
                             vias: dict,
                             zones: list[dict] | None = None) -> list[dict]:
    """Tombstoning risk assessment for small passive components.

    Tombstoning occurs when thermal asymmetry during reflow causes one pad
    of a small passive to lift off. Common causes:
    - One pad connected to a ground pour (high thermal mass), other to a
      thin signal trace
    - Asymmetric track widths connected to each pad
    - Proximity to thermal vias or large copper areas on one side

    Focuses on 0201 and 0402 passives (highest risk due to small size).

    Returns a list of at-risk components with risk level and reason.
    """
    # EQ-056: d = √(Δx²+Δy²) (pad center asymmetry)
    # Identify small passive components
    small_passives = []
    for fp in footprints:
        if fp.get("dnp") or fp.get("board_only"):
            continue
        lib = fp.get("library", "")
        ref = fp.get("reference", "")
        # Must be a passive (C, R, L prefix)
        prefix = ""
        for c in ref:
            if c.isalpha():
                prefix += c
            else:
                break
        if prefix not in ("C", "R", "L"):
            continue

        pkg = _extract_package_code(lib)
        if pkg not in ("0201", "0402"):
            continue

        # Must have exactly 2 pads for tombstoning to apply
        pads = fp.get("pads", [])
        if len(pads) != 2:
            continue

        small_passives.append({
            "fp": fp,
            "package": pkg,
            "prefix": prefix,
        })

    if not small_passives:
        return []

    # Build net->zone mapping to identify ground pour connections
    zone_nets: set[int] = set()
    zone_net_layers: dict[int, set[str]] = {}
    if zones:
        for z in zones:
            zn = z.get("net", 0)
            if zn > 0:
                zone_nets.add(zn)
                for zl in z.get("layers", []):
                    zone_net_layers.setdefault(zn, set()).add(zl)

    # Build net->track width lookup from segments near each pad
    # For efficiency, build a lookup of track widths per net
    net_track_widths: dict[int, list[float]] = {}
    for seg in tracks.get("segments", []):
        net = seg["net"]
        if net > 0:
            net_track_widths.setdefault(net, []).append(seg["width"])
    for arc in tracks.get("arcs", []):
        net = arc["net"]
        if net > 0:
            net_track_widths.setdefault(net, []).append(arc["width"])

    # Analyze each small passive
    at_risk: list[dict] = []
    for sp in small_passives:
        fp = sp["fp"]
        pads = fp["pads"]
        pad_a = pads[0]
        pad_b = pads[1]

        net_a = pad_a.get("net_number", 0)
        net_b = pad_b.get("net_number", 0)
        net_name_a = pad_a.get("net_name", "")
        net_name_b = pad_b.get("net_name", "")

        risks: list[str] = []
        risk_level = "low"

        # Check 1: Ground pour asymmetry
        # If one pad is on a zone net and the other is not
        a_on_zone = net_a in zone_nets
        b_on_zone = net_b in zone_nets

        if a_on_zone != b_on_zone:
            # One pad has zone, the other doesn't — thermal asymmetry
            zone_pad = "pad 1" if a_on_zone else "pad 2"
            zone_net = net_name_a if a_on_zone else net_name_b
            risks.append(f"{zone_pad} connected to zone net ({zone_net}), "
                         f"other pad is signal-only — thermal asymmetry")
            risk_level = "high" if sp["package"] == "0201" else "medium"

        # Check 2: GND net on one pad, signal on other (common tombstone cause)
        a_is_gnd = is_ground_name(net_name_a)
        b_is_gnd = is_ground_name(net_name_b)
        if a_is_gnd != b_is_gnd:
            gnd_pad = "pad 1" if a_is_gnd else "pad 2"
            risks.append(f"{gnd_pad} is GND (likely ground pour), "
                         f"other pad is signal — thermal asymmetry risk")
            if risk_level == "low":
                risk_level = "medium"

        # Check 3: Track width asymmetry
        widths_a = net_track_widths.get(net_a, [])
        widths_b = net_track_widths.get(net_b, [])
        if widths_a and widths_b:
            avg_a = sum(widths_a) / len(widths_a)
            avg_b = sum(widths_b) / len(widths_b)
            if avg_a > 0 and avg_b > 0:
                ratio = max(avg_a, avg_b) / min(avg_a, avg_b)
                if ratio > 3.0:
                    risks.append(f"Track width asymmetry: pad 1 avg "
                                 f"{round(avg_a, 3)}mm vs pad 2 avg "
                                 f"{round(avg_b, 3)}mm (ratio {round(ratio, 1)}x)")
                    if risk_level == "low":
                        risk_level = "medium"

        # Check 4: Thermal via proximity (one pad near thermal vias)
        via_counts = [0, 0]
        for pad_idx, pad in enumerate([pad_a, pad_b]):
            px = pad.get("abs_x", fp["x"])
            py = pad.get("abs_y", fp["y"])
            for via in vias.get("vias", []):
                dx = via["x"] - px
                dy = via["y"] - py
                dist = math.sqrt(dx * dx + dy * dy)
                if dist < 1.0:  # Within 1mm
                    via_counts[pad_idx] += 1

        if via_counts[0] != via_counts[1] and max(via_counts) >= 2:
            more_pad = "pad 1" if via_counts[0] > via_counts[1] else "pad 2"
            risks.append(f"{more_pad} has {max(via_counts)} nearby vias vs "
                         f"{min(via_counts)} on other pad — thermal asymmetry")
            if risk_level == "low":
                risk_level = "medium"

        if risks:
            at_risk.append({
                "component": fp["reference"],
                "value": fp.get("value", ""),
                "package": sp["package"],
                "layer": fp.get("layer", "F.Cu"),
                "risk_level": risk_level,
                "pad_1_net": net_name_a,
                "pad_2_net": net_name_b,
                "reasons": risks,
                "detector": "analyze_tombstoning_risk",
                "rule_id": "TB-001",
                "category": "dfm",
                "severity": "warning" if risk_level == "high" else "info",
                "confidence": "deterministic",
                "evidence_source": "topology",
                "summary": f"{fp['reference']} ({sp['package']}) tombstoning risk: {risk_level}",
                "description": f"{fp['reference']} ({sp['package']}, {fp.get('value', '')}) has {risk_level} tombstoning risk due to thermal asymmetry between pads.",
                "components": [fp["reference"]],
                "nets": [],
                "pins": [],
                "recommendation": "; ".join(risks),
                "report_context": {"section": "DFM", "impact": "assembly", "standard_ref": ""},
            })

    # Sort by risk level (high first)
    risk_order = {"high": 0, "medium": 1, "low": 2}
    at_risk.sort(key=lambda r: (risk_order.get(r["risk_level"], 3),
                                r["component"]))
    return at_risk


def _nearest_pad(pads: list, to: tuple):
    return min(pads, key=lambda p: (p["abs_x"] - to[0]) ** 2 + (p["abs_y"] - to[1]) ** 2)


def _pad_loop(reg_fp: dict, ind_fp: dict, cap_fp: dict, ind_sw_pins: set):
    """The hot-loop pads in loop order, or None when they cannot be resolved.

    Input-cap supply pad -> regulator supply pad, regulator SW pad -> inductor
    SW pad, regulator ground pad -> input-cap ground pad. Pads are matched by
    net: the cap's ground-named net and its other net, both also on the
    regulator; the SW net is shared by the regulator and the inductor and is
    neither of those (when the inductor's other side also reaches the
    regulator, ``ind_sw_pins``, the inductor pins on the schematic SW net,
    decide). The cap's first pad on each net is used; where the regulator or
    the inductor has several pads on a net, the one nearest a loop neighbour
    is used (regulator supply nearest the cap supply pad, SW nearest the
    regulator supply pad, inductor SW nearest the regulator SW pad,
    regulator ground nearest the cap ground pad).
    """
    def placed(fp):
        return [p for p in fp.get("pads") or []
                if p.get("net_name") and "abs_x" in p and "abs_y" in p]

    reg_pads, ind_pads, cap_pads = placed(reg_fp), placed(ind_fp), placed(cap_fp)
    cap_nets = {p["net_name"] for p in cap_pads}
    gnd = [n for n in cap_nets if is_ground_name(n)]
    vin = [n for n in cap_nets if not is_ground_name(n)]
    if len(gnd) != 1 or len(vin) != 1:
        return None
    gnd, vin = gnd[0], vin[0]
    reg_nets = {p["net_name"] for p in reg_pads}
    if gnd not in reg_nets or vin not in reg_nets:
        return None
    sw = sorted(({p["net_name"] for p in ind_pads} & reg_nets) - {gnd, vin})
    if len(sw) > 1 and ind_sw_pins:
        sw = [n for n in sw if any(p["net_name"] == n and p.get("number") in ind_sw_pins
                                   for p in ind_pads)]
    if len(sw) != 1:
        return None
    sw = sw[0]

    def on(pads, net):
        return [p for p in pads if p["net_name"] == net]

    cap_vin = on(cap_pads, vin)[0]
    reg_vin = _nearest_pad(on(reg_pads, vin), (cap_vin["abs_x"], cap_vin["abs_y"]))
    reg_sw = _nearest_pad(on(reg_pads, sw), (reg_vin["abs_x"], reg_vin["abs_y"]))
    ind_sw = _nearest_pad(on(ind_pads, sw), (reg_sw["abs_x"], reg_sw["abs_y"]))
    cap_gnd = on(cap_pads, gnd)[0]
    reg_gnd = _nearest_pad(on(reg_pads, gnd), (cap_gnd["abs_x"], cap_gnd["abs_y"]))
    return [(cap_fp, cap_vin), (reg_fp, reg_vin), (reg_fp, reg_sw),
            (ind_fp, ind_sw), (reg_fp, reg_gnd), (cap_fp, cap_gnd)]


def _compute_switching_loop_areas(footprints: list, schematic_data: dict) -> list:
    """Hot-loop areas for switching regulators, from pad positions.

    The loop runs input-cap supply pad -> regulator supply pad, regulator SW
    pad -> inductor SW pad, regulator ground pad -> input-cap ground pad
    (method "pad"), through the input cap whose pads are nearest the
    regulator's supply and ground pads. The polygon can cross itself (see
    kicad_core.hotloop).
    Returns list of {regulator_ref, regulator_value,
    inductor_ref, cap_ref, method, area_mm2, loop_pads, vertices_mm};
    area_mm2 is None with estimate "pads_unresolved" when the pads cannot be
    matched by net, or "degenerate" when the area is under 1 mm² across a
    reach of 2 mm or more (the pads lie in a line, or the loop crosses itself
    and its lobes cancel).
    """
    regulators = [f for f in schematic_data.get('findings', [])
                  if f.get('detector') == 'detect_power_regulators']
    if not regulators:
        return []

    sch_nets = schematic_data.get('nets') or {}
    fp_by_ref = {}
    for fp in footprints:
        ref = fp.get('reference', '')
        if ref:
            fp_by_ref.setdefault(ref, fp)

    results = []
    for reg in regulators:
        topology = reg.get('topology', '').lower()
        if topology in ('ldo', 'linear', 'unknown', 'ic_with_internal_regulator',
                        'load_switch', 'charge_pump'):
            continue

        ref = reg.get('ref', reg.get('reference', ''))
        inductor_ref = reg.get('inductor')
        input_caps = reg.get('input_capacitors', [])

        if not inductor_ref or not input_caps:
            continue

        reg_fp, ind_fp = fp_by_ref.get(ref), fp_by_ref.get(inductor_ref)
        cap_refs = [c.get('ref', '') if isinstance(c, dict) else str(c) for c in input_caps]
        cap_fps = [fp_by_ref[c] for c in cap_refs if c in fp_by_ref]
        if not reg_fp or not ind_fp or not cap_fps:
            continue
        if any((fp.get('x') or 0, fp.get('y') or 0) == (0, 0) for fp in (reg_fp, ind_fp, cap_fps[0])):
            continue

        sw_pins = {p.get('pin_number') for p in sch_nets.get(reg.get('sw_net') or '', {}).get('pins', [])
                   if p.get('component') == inductor_ref}
        # The input cap nearest the regulator's supply and ground pads closes the loop.
        best = None
        for cap_fp in cap_fps:
            pads = _pad_loop(reg_fp, ind_fp, cap_fp, sw_pins)
            if pads is None:
                continue
            vertices = [(p["abs_x"], p["abs_y"]) for _, p in pads]
            reach = math.dist(vertices[0], vertices[1]) + math.dist(vertices[4], vertices[5])
            if best is None or reach < best[0]:
                best = (reach, cap_fp, pads, vertices)

        loop = {
            "regulator_ref": ref,
            "regulator_value": reg.get('value', ''),
            "inductor_ref": inductor_ref,
            "cap_ref": best[1]['reference'] if best else cap_fps[0]['reference'],
            "method": "pad",
        }
        if best is None:
            loop["area_mm2"] = None
            loop["estimate"] = "pads_unresolved"
            results.append(loop)
            continue
        _, _, pads, vertices = best
        area_mm2 = polygon_loop_area(vertices)
        loop["area_mm2"] = round(area_mm2, 1) if area_mm2 is not None else None
        loop["loop_pads"] = [f"{fp['reference']}.{p.get('number', '')}" for fp, p in pads]
        loop["vertices_mm"] = [list(v) for v in vertices]
        if area_mm2 is None:
            loop["estimate"] = "degenerate"
        results.append(loop)

    return results


def _finest_smd_pad_dim(footprints: list[dict], side: str) -> float | None:
    """Return the smallest SMD pad dimension (width or height) on the given side.

    Uses pad 'width' and 'height' fields as a proxy for pad pitch — fine-pitch
    parts (BGA, fine-pitch QFN) have smaller pads. Returns None when no SMD
    pads with size data are found.
    """
    min_dim: float | None = None
    for fp in footprints:
        layer = fp.get("layer", "F.Cu")
        fp_side = layer if layer in ("F.Cu", "B.Cu") else "F.Cu"
        if fp_side != side:
            continue
        for pad in fp.get("pads", []):
            if pad.get("type") != "smd":
                continue
            w = pad.get("width")
            h = pad.get("height")
            if w is None or h is None:
                continue
            dim = min(float(w), float(h))
            if dim > 0 and (min_dim is None or dim < min_dim):
                min_dim = dim
    return min_dim


def _fiducial_severity_from_pitch(min_pad_dim: float | None) -> tuple[str, str]:
    """Return (severity, pitch_note) based on smallest SMD pad dimension.

    Thresholds use pad size as a proxy for pitch:
      <= 0.3 mm pad dim  -> likely BGA / fine-pitch QFN  -> 'error'
      <= 0.5 mm pad dim  -> medium pitch (SOT-563 etc.)  -> 'warning'
      >  0.5 mm or None  -> coarse pitch                 -> 'info'
    """
    if min_pad_dim is None:
        return "info", " (pad pitch unknown — coarse assumed)"
    if min_pad_dim <= 0.3:
        return "error", f" (finest pad dim {min_pad_dim:.2f}mm — BGA/fine-pitch QFN present)"
    if min_pad_dim <= 0.5:
        return "warning", f" (finest pad dim {min_pad_dim:.2f}mm — medium-pitch part present)"
    return "info", f" (finest pad dim {min_pad_dim:.2f}mm — coarse pitch only)"


def _has_pad_property(fp: dict, prop: str) -> bool:
    return any(p.get("_property") == prop for p in fp.get("pads", []))


def _is_tp_reference(fp: dict) -> bool:
    """A TP reference that is not a capacitive touch pad."""
    ref = fp.get("reference", "")
    return ref.upper().startswith("TP") and not is_touch_pad(
        ref, fp.get("value"), fp.get("library", ""))


def _is_test_point(fp: dict) -> bool:
    return _is_tp_reference(fp) or _has_pad_property(fp, "pad_prop_testpoint")


def analyze_fiducials(footprints: list[dict]) -> dict:
    """FD-001: Check for assembly fiducial markers."""
    fiducials_by_side: dict[str, list[str]] = {"F.Cu": [], "B.Cu": []}
    smd_by_side: dict[str, int] = {"F.Cu": 0, "B.Cu": 0}

    for fp in footprints:
        ref = fp.get("reference", "")
        val = fp.get("value", "")
        if not isinstance(val, str):
            val = str(val)
        lib = (fp.get("library", "") + " " + val + " " + ref).lower()
        layer = fp.get("layer", "F.Cu")
        side = layer if layer in fiducials_by_side else "F.Cu"

        # Local fiducials (pad_prop_fiducial_loc) serve one part, not board alignment
        if (any(k in lib for k in ("fiducial", "fid_", "fiducial_"))
                or _has_pad_property(fp, "pad_prop_fiducial_glob")):
            fiducials_by_side[side].append(ref)

        # Count SMD components per side. A touch electrode footprint is copper, not a placed
        # part; only the footprint decides, since a connector valued "Touch" is still placed.
        pads = fp.get("pads", [])
        if any(p.get("type") == "smd" for p in pads) and not is_touch_pad(
                "", "", fp.get("library", "")):
            smd_by_side[side] = smd_by_side.get(side, 0) + 1

    findings: list[dict] = []
    for side, fids in fiducials_by_side.items():
        smd_count = smd_by_side.get(side, 0)
        if smd_count == 0:
            continue  # No SMD on this side, fiducials not required
        count = len(fids)
        if count >= 3:
            continue  # Adequate

        # Pitch-aware severity: use finest SMD pad dimension as pitch proxy
        min_pad_dim = _finest_smd_pad_dim(footprints, side)
        severity, pitch_note = _fiducial_severity_from_pitch(min_pad_dim)

        if count == 0:
            summary = f"No fiducials on {side} ({smd_count} SMD components){pitch_note}"
        else:
            summary = f"Only {count} fiducial(s) on {side} (need >= 3){pitch_note}"

        findings.append({
            "side": side,
            "fiducial_count": count,
            "fiducial_refs": fids,
            "smd_component_count": smd_count,
            "finest_smd_pad_dim_mm": min_pad_dim,
            "detector": "analyze_fiducials",
            "rule_id": "FD-001",
            "category": "assembly",
            "severity": severity,
            "confidence": "deterministic",
            "evidence_source": "topology",
            "summary": summary,
            "description": f"{side} has {count} fiducial(s) but {smd_count} SMD components. Assembly machines need >= 3 fiducials for accurate placement.",
            "components": fids,
            "nets": [],
            "pins": [],
            "recommendation": "Add fiducial markers for pick-and-place alignment (3 per side with SMD).",
            "report_context": {"section": "Assembly", "impact": "Pick-and-place alignment", "standard_ref": "IPC-7351"},
        })

    return {"findings": findings}


def analyze_test_point_coverage(footprints: list[dict], net_names: dict) -> dict:
    """TE-001: Check test point coverage across nets."""
    tp_nets: set[str] = set()
    for fp in footprints:
        if not _is_test_point(fp):
            continue
        # A TP footprint tests every pad; elsewhere only the pads marked as test points
        tp_ref = _is_tp_reference(fp)
        for pad in fp.get("pads", []):
            if not tp_ref and pad.get("_property") != "pad_prop_testpoint":
                continue
            net = pad.get("net_name", "")
            if net:
                tp_nets.add(net)

    # Count signal nets (exclude power/ground)
    all_signal_nets = set()
    for net_id, name in net_names.items():
        if not name:
            continue
        n = name.upper()
        is_pg = n in ("GND", "VSS", "VDD", "VCC") or n.startswith(("+", "GND"))
        if not is_pg:
            all_signal_nets.add(name)

    total = len(all_signal_nets)
    covered = len(tp_nets & all_signal_nets)
    pct = (covered / total * 100) if total > 0 else 100

    if pct >= 95:
        severity = "info"
    elif pct >= 50:
        severity = "info"
    else:
        severity = "warning"

    finding = {
        "total_signal_nets": total,
        "nets_with_test_points": covered,
        "coverage_pct": round(pct, 1),
        "test_point_count": len([fp for fp in footprints if _is_test_point(fp)]),
        "detector": "analyze_test_point_coverage",
        "rule_id": "TE-001",
        "category": "testability",
        "severity": severity,
        "confidence": "deterministic",
        "evidence_source": "topology",
        "summary": f"Test point coverage: {covered}/{total} nets ({pct:.0f}%)",
        "description": f"{covered} of {total} signal nets have test points ({pct:.0f}% coverage).",
        "components": [],
        "nets": [],
        "pins": [],
        "recommendation": "Add test points to improve ICT/flying probe coverage." if pct < 95 else "",
        "report_context": {"section": "Testability", "impact": "ICT accessibility", "standard_ref": ""},
    }

    return finding


def analyze_orientation_consistency(footprints: list[dict]) -> list[dict]:
    """OR-001: Check passive component orientation consistency per board side."""
    from collections import Counter

    findings: list[dict] = []
    passives_by_side: dict[str, list[tuple[str, float]]] = {}

    for fp in footprints:
        ref = fp.get("reference", "")
        # Only check passives (R, C, L with 2 pads)
        if not ref or ref[0] not in ("R", "C", "L"):
            continue
        pads = fp.get("pads", [])
        if len(pads) != 2:
            continue
        layer = fp.get("layer", "F.Cu")
        angle = fp.get("angle", 0) or 0
        # Normalize angle to 0-179 range (0 and 180 are same orientation)
        norm_angle = round(angle) % 180
        passives_by_side.setdefault(layer, []).append((ref, norm_angle))

    for side, components in passives_by_side.items():
        if len(components) < 5:
            continue  # Too few to judge consistency

        angles = Counter(a for _, a in components)
        majority_angle, majority_count = angles.most_common(1)[0]
        deviators = [(ref, a) for ref, a in components if a != majority_angle]

        if not deviators:
            continue

        deviation_pct = len(deviators) / len(components) * 100
        if deviation_pct < 10:
            continue  # Minor inconsistency, not worth flagging

        findings.append({
            "side": side,
            "total_passives": len(components),
            "majority_angle": majority_angle,
            "majority_count": majority_count,
            "deviator_count": len(deviators),
            "deviator_refs": [ref for ref, _ in deviators[:20]],
            "detector": "analyze_orientation_consistency",
            "rule_id": "OR-001",
            "category": "assembly",
            "severity": "info",
            "confidence": "heuristic",
            "evidence_source": "topology",
            "summary": f"Orientation: {len(deviators)} passives on {side} deviate from {majority_angle} deg majority",
            "description": f"{len(deviators)} of {len(components)} passives on {side} are not at the majority {majority_angle} deg orientation.",
            "components": [ref for ref, _ in deviators[:20]],
            "nets": [],
            "pins": [],
            "recommendation": "Align passive component orientations for consistent pick-and-place.",
            "report_context": {"section": "Assembly", "impact": "Pick-and-place efficiency", "standard_ref": ""},
        })

    return findings


def analyze_silkscreen_pad_overlaps(footprints: list[dict], board_texts: list[dict]) -> list[dict]:
    """SK-001: Check for silkscreen text overlapping exposed pads."""
    findings: list[dict] = []

    # Collect all exposed pad bboxes (SMD pads on front/back)
    pad_bboxes: list[tuple[str, str, float, float, float, float]] = []
    for fp in footprints:
        ref = fp.get("reference", "")
        for pad in fp.get("pads", []):
            if pad.get("type") != "smd":
                continue
            px = pad.get("abs_x")
            py = pad.get("abs_y")
            if px is None or py is None:
                continue
            hw = pad.get("width", 0) / 2
            hh = pad.get("height", 0) / 2
            if hw <= 0 or hh <= 0:
                continue
            layers = pad.get("layers", [])
            for layer in layers:
                if ".Cu" in layer:
                    silk_layer = "F.SilkS" if "F." in layer else "B.SilkS"
                    pad_bboxes.append((ref, silk_layer, px - hw, py - hh, px + hw, py + hh))

    if not pad_bboxes:
        return findings

    # Check board-level silkscreen texts against pad bboxes
    flagged_refs: set[str] = set()
    for text_entry in board_texts:
        tx = text_entry.get("x")
        ty = text_entry.get("y")
        tlayer = text_entry.get("layer", "")
        if tx is None or ty is None:
            continue
        if "SilkS" not in tlayer and "Silkscreen" not in tlayer:
            continue
        for ref, silk_layer, x1, y1, x2, y2 in pad_bboxes:
            if ref in flagged_refs:
                continue
            if silk_layer.startswith(tlayer[0]):  # Same side (F/B)
                if x1 <= tx <= x2 and y1 <= ty <= y2:
                    flagged_refs.add(ref)
                    findings.append({
                        "component": ref,
                        "silk_layer": tlayer,
                        "detector": "analyze_silkscreen_pad_overlaps",
                        "rule_id": "SK-001",
                        "category": "dfm",
                        "severity": "warning",
                        "confidence": "heuristic",
                        "evidence_source": "topology",
                        "summary": f"Silkscreen overlaps pad on {ref} ({tlayer})",
                        "description": f"Silkscreen text on {tlayer} overlaps an exposed SMD pad on {ref}.",
                        "components": [ref],
                        "nets": [],
                        "pins": [],
                        "recommendation": f"Move silkscreen text away from exposed pads on {ref}.",
                        "report_context": {"section": "DFM", "impact": "Solder paste/solder joint interference", "standard_ref": ""},
                    })

    return findings


def _prohibits(restrictions: dict, key: str) -> bool:
    # KiCad rule areas carry "allowed" or "not_allowed" per item type.
    return restrictions.get(key) == "not_allowed"


def _area_copper_layers(layers: list[str]) -> bool:
    """True when a rule area covers a copper layer (*.Cu, F&B.Cu or a named copper layer)."""
    return any(layer.endswith(".Cu") for layer in layers)


def _area_courtyard_layers(layers: list[str]) -> list[str]:
    """Courtyard layers a rule area judges footprints on: F.CrtYd when it covers F.Cu, B.CrtYd
    when it covers B.Cu (F&B.Cu and *.Cu cover both). KiCad reports no footprint under an
    inner-layer-only or a non-copper area."""
    front = any(layer in ("F.Cu", "F&B.Cu", "*.Cu") for layer in layers)
    back = any(layer in ("B.Cu", "F&B.Cu", "*.Cu") for layer in layers)
    return (["F.CrtYd"] if front else []) + (["B.CrtYd"] if back else [])


def _courtyard_meets_area(fp: dict, crtyd_layers: list[str], bbox: list, polys: list) -> bool:
    """True when the footprint's courtyard on one of ``crtyd_layers`` overlaps the area.
    A footprint without a courtyard there, or with one that cannot be read, is not judged,
    as in KiCad."""
    kx1, ky1, kx2, ky2 = bbox[0], bbox[1], bbox[2], bbox[3]
    sides = _courtyard_sides(fp)
    for layer in crtyd_layers:
        side = sides.get(layer)
        if not side or not side.get("polys"):
            continue
        box = side["box"]
        if box["min_x"] > kx2 or box["max_x"] < kx1 or box["min_y"] > ky2 or box["max_y"] < ky1:
            continue
        # shrinks both shapes by 0.005 mm; KiCad shrinks the area by only 0.0005 mm, a
        # 0.0045 mm difference below anything measured
        if courtyards_collide(polys, side["polys"]):
            return True
    return False


# KiCad shrinks a rule area by its DRC epsilon before the keepout test, so touching is legal
_AREA_EPSILON_MM = 0.0005


def _via_meets_area(vx: float, vy: float, radius: float, polys: list) -> bool:
    """True when a via's copper disc (radius = half its size) overlaps the area."""
    return _signed_depth(vx, vy, polys) > _AREA_EPSILON_MM - radius


def analyze_keepout_violations(footprints: list[dict], vias: dict,
                                keepout_zones: list[dict]) -> list[dict]:
    """KO-001: Check for components or through vias inside keepout zones.

    As KiCad does, the test uses the area outline (cut-outs left out): a through via is inside
    when its copper disc overlaps the area, a footprint when its courtyard on the side the
    area covers does.
    A rule area's "vias" restriction prohibits through vias only (KiCad's DRC_DISALLOW_VIAS);
    a through via spans every copper layer, so it meets any area on a copper layer.
    """
    findings: list[dict] = []
    if not keepout_zones:
        return findings

    via_list = vias.get("vias", [])

    for kz in keepout_zones:
        bbox = kz.get("bounding_box")
        polys = kz.get("_outline_polys")
        if not bbox or len(bbox) < 4 or not polys:
            continue
        kx1, ky1, kx2, ky2 = bbox[0], bbox[1], bbox[2], bbox[3]
        restrictions = kz.get("restrictions", {})
        kz_name = kz.get("name", "unnamed")
        kz_label = kz_name or "unnamed"
        kz_layers = kz.get("layers", [])

        # Check footprints
        crtyd_layers = _area_courtyard_layers(kz_layers)
        if _prohibits(restrictions, "footprints") and crtyd_layers:
            for fp in footprints:
                ref = fp.get("reference", "")
                if _courtyard_meets_area(fp, crtyd_layers, bbox, polys):
                    findings.append({
                        "component": ref,
                        "keepout_name": kz_name,
                        "keepout_layers": kz_layers,
                        "detector": "analyze_keepout_violations",
                        "rule_id": "KO-001",
                        "category": "placement",
                        "severity": "error",
                        "confidence": "heuristic",
                        "evidence_source": "topology",
                        "summary": f"Keepout violation: {ref} inside keepout zone{' ' + kz_name if kz_name != 'unnamed' else ''}",
                        "description": f"Component {ref} courtyard overlaps keepout zone {kz_label}.",
                        "components": [ref],
                        "nets": [],
                        "pins": [],
                        "recommendation": f"Move {ref} outside the keepout zone.",
                        "report_context": {"section": "Placement", "impact": "Design rule violation", "standard_ref": ""},
                    })

        # Check vias
        if _prohibits(restrictions, "vias") and _area_copper_layers(kz_layers):
            for via in via_list:
                if via.get("type", "through") != "through":
                    continue
                vx = via.get("x")
                vy = via.get("y")
                if vx is None or vy is None:
                    continue
                radius = (via.get("size") or 0) / 2.0
                if (kx1 - radius <= vx <= kx2 + radius and ky1 - radius <= vy <= ky2 + radius
                        and _via_meets_area(vx, vy, radius, polys)):
                    findings.append({
                        "via_x": round(vx, 2),
                        "via_y": round(vy, 2),
                        "keepout_name": kz_name,
                        "detector": "analyze_keepout_violations",
                        "rule_id": "KO-001",
                        "category": "placement",
                        "severity": "error",
                        "confidence": "heuristic",
                        "evidence_source": "topology",
                        "summary": f"Keepout violation: via at ({round(vx, 1)}, {round(vy, 1)}) inside keepout{' ' + kz_name if kz_name != 'unnamed' else ''}",
                        "description": f"Via at ({round(vx, 2)}, {round(vy, 2)}) is inside keepout zone {kz_label}.",
                        "components": [],
                        "nets": [],
                        "pins": [],
                        "recommendation": "Move via outside the keepout zone.",
                        "report_context": {"section": "Placement", "impact": "Design rule violation", "standard_ref": ""},
                    })

    return findings[:50]
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 321kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 321kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 321kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 197kUpdated Claude CodeCodexVerifiedInstall