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/copper.py

View on GitHub
"""PCB copper checks: via analysis, thermal vias and thermal-pad vias, copper presence,
via-in-pad, board-edge via clearance."""

import math
import re

from kicad_core.classify import is_touch_pad
from kicad_core.netnames import is_ground_name
from pcb.dfm import _degenerate_drills, _is_real_drill, _pad_drills
from pcb.geometry import (ZoneFills, _pad_on_layer, _pad_sample_points, _point_in_pad,
                          copper_connected, outline_edge_distance)


def _via_exposed_by_pad(via: dict, pad_layers: list | None) -> bool:
    """True when a pad's own mask opening uncovers a via inside it. KiCad plots the pad's
    aperture on every mask layer in the pad's layer set whatever the via's tenting; the
    via shows wherever it reaches that side."""
    return bool(_via_open_sides(via, pad_layers))


def _via_open_sides(via: dict, pad_layers: list | None) -> list[str]:
    """Outer sides ("F", "B") where the pad opens the mask and the via reaches the copper."""
    layers = set(pad_layers or ())
    reaches = via.get("layers") or ["F.Cu", "B.Cu"]
    return [side for side in ("F", "B")
            if f"{side}.Cu" in reaches and layers & {f"{side}.Mask", "*.Mask", "F&B.Mask"}]


def _copper_rank(layer: str) -> int | None:
    """Stack position of a canonical copper layer name (F.Cu, In1.Cu ... In30.Cu, B.Cu)."""
    if layer == "F.Cu":
        return 0
    if layer == "B.Cu":
        return 99
    if layer.startswith("In") and layer.endswith(".Cu") and layer[2:-3].isdigit():
        return int(layer[2:-3])
    return None


def _via_span(via: dict) -> tuple[int, int] | None:
    """(top, bottom) stack positions of the via; None when unknown (read as a through via)."""
    span = [_copper_rank(l) for l in (via.get("layers") or [])[:2]]
    if len(span) < 2 or None in span:
        return None
    return min(span), max(span)


def _vias_reaching(vias: list[dict], layer: str) -> set[int]:
    """ids of the vias whose copper reaches `layer`: their own span holds it, or they are
    stacked at the same point on a chain of same-net vias that does."""
    target = _copper_rank(layer)
    stacks: dict[tuple, list[dict]] = {}
    for v in vias:
        stacks.setdefault((round(v["x"], 3), round(v["y"], 3), v.get("net")), []).append(v)
    reach: set[int] = set()
    for stack in stacks.values():
        spans = {id(v): _via_span(v) for v in stack}
        if target is None or any(sp is None for sp in spans.values()):
            reach.update(spans)
            continue
        lo = hi = None
        grown = True
        joined: set[int] = set()
        while grown:
            grown = False
            for v in stack:
                top, bottom = spans[id(v)]
                if id(v) in joined:
                    continue
                if (lo is None and top <= target <= bottom) or (
                        lo is not None and top <= hi and bottom >= lo):
                    joined.add(id(v))
                    lo = top if lo is None else min(lo, top)
                    hi = bottom if hi is None else max(hi, bottom)
                    grown = True
        reach.update(joined)
    return reach


def _mask_opening_size(pad: dict, w: float, h: float) -> tuple[float, float] | None:
    """Size of the pad's mask opening: a negative solder_mask_margin shrinks it on every
    side (KiCad's PAD::GetSolderMaskExpansion), and None when nothing is left open."""
    margin = pad.get("solder_mask_margin") or 0
    if margin >= 0:
        return w, h
    ow, oh = w + 2 * margin, h + 2 * margin
    return (ow, oh) if ow > 0 and oh > 0 else None


def _find_thermal_pads(fp: dict) -> list[dict]:
    """Identify thermal/exposed pads on a footprint.

    Returns list of pad dicts that are likely thermal pads —
    large center pads on power/ground nets, typical of QFN/BGA packages.
    """
    pads = fp.get("pads", [])
    if len(pads) < 3:
        return []

    # Calculate SMD pad area statistics (skip paste-only pads)
    pad_areas: list[tuple[dict, float]] = []
    for p in pads:
        if p.get("type") != "smd":
            continue
        pad_layers = p.get("layers", [])
        if not any(l.endswith(".Cu") or l == "*.Cu" for l in pad_layers):
            continue
        w = p.get("width", p.get("size_x", 0))
        h = p.get("height", p.get("size_y", 0))
        area = w * h
        if area > 0:
            pad_areas.append((p, area))

    if not pad_areas:
        return []

    avg_area = sum(a for _, a in pad_areas) / len(pad_areas)
    all_areas_sorted = sorted(a for _, a in pad_areas)
    median_area = all_areas_sorted[len(all_areas_sorted) // 2]

    thermal = []
    for p, area in pad_areas:
        pad_num = str(p.get("number", ""))
        is_ep = pad_num in ("0", "EP", "")

        # DFN/QFN variants use highest-numbered pad as EP — detect by
        # area ratio (pad >= 3x the median signal pad area)
        if not is_ep and median_area > 0:
            other_areas = sorted(a for pad, a in pad_areas
                                 if str(pad.get("number", "")) != pad_num)
            if other_areas:
                median_signal = other_areas[len(other_areas) // 2]
                if median_signal > 0 and area >= median_signal * 3.0:
                    is_ep = True

        # Thermal pad: explicitly named EP/0 with area >= 2mm²,
        # or any pad with area > 6mm² (large enough to need thermal vias)
        if not ((is_ep and area >= 2.0) or area > 6.0):
            continue

        # Must be at least 2x the average pad area
        if avg_area > 0 and area < avg_area * 2.0:
            continue

        # Must have a net — structural/shield pads with no net are not thermal
        net_name = p.get("net_name", "")
        pad_net_num = p.get("net_number", -1)
        if not net_name or pad_net_num <= 0:
            continue

        # Must be on a ground or power net (thermal pads dissipate heat)
        net_upper = net_name.upper()
        is_power_or_gnd = (
            net_upper in ("GND", "VSS", "AGND", "DGND", "PGND", "VCC", "VDD",
                          "AVCC", "AVDD", "DVCC", "DVDD", "VBUS")
            or net_upper.startswith("+")
            or net_upper.startswith("V+")
            or "GND" in net_upper
            or "VCC" in net_upper
            or "VDD" in net_upper
        )
        if not is_power_or_gnd and not is_ep:
            continue

        thermal.append(p)

    return thermal


def analyze_thermal_vias(footprints: list[dict], vias: dict,
                         zones: list[dict]) -> dict:
    """Provide facts for thermal analysis — via stitching, thermal pads, via-in-pad.

    Reports:
    - Via density per zone (stitching vias for thermal/ground plane connectivity)
    - Exposed/thermal pad detection on QFN/BGA packages (pad connected to ground)
    - Via clusters near thermal pads (thermal via arrays)
    - Overall via distribution across layers
    """
    # EQ-055: density = count / area_cm² (thermal via density)
    zone_vias: dict[int, dict] = {}  # net_num -> via stats within zone
    # For each zone, count vias on the same net within the zone outline
    # (approximate: use bounding box of zone outline)
    zone_bounds: list[dict] = []
    for z in zones:
        zn = z.get("net", 0)
        if zn <= 0:
            continue
        # Use the outline_area as a proxy — if we had the actual outline
        # points we could do point-in-polygon, but for a first pass,
        # just count all vias on the same net
        zone_bounds.append({
            "net": zn,
            "net_name": z.get("net_name", ""),
            "layers": z.get("layers", []),
            "area_mm2": z.get("outline_area_mm2", 0),
            "filled_area_mm2": z.get("filled_area_mm2"),
        })

    # Count vias per net
    via_by_net: dict[int, list[dict]] = {}
    for via in vias.get("vias", []):
        net = via.get("net", 0)
        if net > 0:
            via_by_net.setdefault(net, []).append(via)

    # Aggregate zone polygons by net before computing stitching density
    net_zones: dict[int, dict] = {}
    for zb in zone_bounds:
        net = zb["net"]
        if net not in net_zones:
            net_zones[net] = {
                "net_name": zb["net_name"],
                "layers": set(),
                "total_area_mm2": 0,
            }
        net_zones[net]["layers"].update(zb["layers"])
        net_zones[net]["total_area_mm2"] += zb.get("area_mm2", 0)

    # Zone stitching analysis — one entry per net
    stitching = []
    for net, info in net_zones.items():
        net_vias = via_by_net.get(net, [])
        if not net_vias:
            continue
        area = info["total_area_mm2"]

        entry = {
            "net": info["net_name"],
            "zone_layers": sorted(info["layers"]),
            "zone_area_mm2": round(area, 1) if area else None,
            "via_count": len(net_vias),
        }
        if area > 0:
            entry["via_density_per_cm2"] = round(len(net_vias) / (area / 100.0), 1)

        # Check drill sizes
        drills = set()
        for v in net_vias:
            if v.get("drill"):
                drills.add(v["drill"])
        if drills:
            entry["drill_sizes_mm"] = sorted(drills)

        entry["detector"] = "analyze_thermal_vias"
        entry["rule_id"] = "TS-DET"
        entry["category"] = "thermal"
        entry["severity"] = "info"
        entry["confidence"] = "deterministic"
        entry["evidence_source"] = "topology"
        entry["summary"] = f"Zone stitching: {info['net_name']} {len(net_vias)} vias"
        entry["description"] = (
            f"Zone stitching on net {info['net_name']}: {len(net_vias)} vias "
            f"across layers {sorted(info['layers'])}."
        )
        entry["components"] = []
        entry["nets"] = [info["net_name"]]
        entry["pins"] = []
        entry["recommendation"] = ""
        entry["report_context"] = {
            "section": "Thermal",
            "impact": "Thermal/ground plane connectivity",
            "standard_ref": "",
        }
        stitching.append(entry)

    # Thermal pad detection — use shared helper for QFN/BGA/DFN packages
    thermal_pads = []
    for fp in footprints:
        ref = fp.get("reference", "")

        # Skip component types that don't have thermal pads
        ref_prefix = ""
        for c in ref:
            if c.isalpha():
                ref_prefix += c
            else:
                break
        if ref_prefix in ("BT", "TP", "J"):
            continue

        for pad in _find_thermal_pads(fp):
            pad_num = str(pad.get("number", ""))
            w = pad.get("width", 0)
            h = pad.get("height", 0)
            pad_area = w * h
            net_name = pad.get("net_name", "")

            ax = pad.get("abs_x", fp["x"])
            ay = pad.get("abs_y", fp["y"])

            # Count standalone vias near this thermal pad
            standalone_vias = 0
            for via in vias.get("vias", []):
                if via.get("net") == pad.get("net_number", -1):
                    dx = via["x"] - ax
                    dy = via["y"] - ay
                    if math.sqrt(dx * dx + dy * dy) < max(w, h) * 1.5:
                        standalone_vias += 1

            # Count thru_hole pads in the same footprint on the same
            # net — these are footprint-embedded thermal vias
            footprint_via_pads = 0
            pad_net = pad.get("net_number", -1)
            for other_pad in fp.get("pads", []):
                if other_pad is pad:
                    continue
                if (other_pad.get("type") == "thru_hole" and
                        other_pad.get("net_number", -2) == pad_net and
                        pad_net >= 0):
                    footprint_via_pads += 1

            nearby_vias = standalone_vias + footprint_via_pads
            thermal_pads.append({
                "component": ref,
                "pad": pad_num,
                "pad_size_mm": [round(w, 2), round(h, 2)],
                "pad_area_mm2": round(pad_area, 2),
                "net": net_name,
                "nearby_thermal_vias": nearby_vias,
                "standalone_vias": standalone_vias,
                "footprint_via_pads": footprint_via_pads,
                "layer": fp.get("layer", "F.Cu"),
                "detector": "analyze_thermal_vias",
                "rule_id": "TP-DET",
                "category": "thermal",
                "severity": "info",
                "confidence": "deterministic",
                "evidence_source": "topology",
                "summary": f"Thermal pad: {ref} pad {pad_num} {nearby_vias} nearby vias",
                "description": (
                    f"Thermal pad on {ref} pad {pad_num}: "
                    f"{nearby_vias} nearby vias ({standalone_vias} standalone, "
                    f"{footprint_via_pads} footprint)."
                ),
                "components": [ref],
                "nets": [net_name],
                "pins": [pad_num],
                "recommendation": "",
                "report_context": {
                    "section": "Thermal",
                    "impact": "Thermal dissipation",
                    "standard_ref": "",
                },
            })

    return {
        "zone_stitching": stitching,
        "thermal_pads": thermal_pads,
    }


def analyze_vias(vias: dict, footprints: list[dict],
                 net_names: dict[int, str]) -> dict:
    """Comprehensive via analysis — types, annular ring, via-in-pad, fanout, current.

    Reports:
    - Type breakdown: through-hole vs blind vs micro via counts and distributions
    - Annular ring: (pad_size - drill) / 2 per via, with min/max/distribution
    - Via-in-pad detection: vias located within footprint pad bounding boxes
    - Fanout pattern detection: clusters of vias near BGA/QFN pads
    - Current capacity facts: drill sizes mapped to IPC-2221 approximate ratings
    """
    # EQ-058: area = π(d/2)² (via annular ring)
    all_vias = vias.get("vias", [])
    if not all_vias:
        # A via-less board can still have footprint pad drills
        # (including degenerate ones, e.g. a
        # `(drill 0.00001)` pad) worth surfacing — don't drop them just
        # because there are no vias to analyze.
        novia_result: dict = {}
        pad_drills = _pad_drills(footprints)
        if pad_drills:
            novia_result["current_capacity"] = {"min_pad_drill_mm": min(pad_drills)}
        dd = _degenerate_drills(footprints, [])
        if dd:
            novia_result["degenerate_drills"] = dd
        return novia_result

    # --- Type breakdown ---
    type_counts: dict[str, int] = {"through": 0, "blind": 0, "buried": 0, "micro": 0}
    type_sizes: dict[str, dict[str, int]] = {
        "through": {}, "blind": {}, "buried": {}, "micro": {},
    }
    for v in all_vias:
        # extract_vias always emits `type` as one of through/blind/buried/micro.
        vtype = v["type"]
        if vtype not in type_counts:
            vtype = "through"
        type_counts[vtype] += 1
        key = f"{v['size']}/{v['drill']}"
        type_sizes[vtype][key] = type_sizes[vtype].get(key, 0) + 1

    type_breakdown = {}
    for vtype, count in type_counts.items():
        if count > 0:
            type_breakdown[vtype] = {
                "count": count,
                "size_distribution": type_sizes[vtype],
            }

    # --- Annular ring analysis ---
    rings: list[float] = []
    ring_dist: dict[float, int] = {}
    for v in all_vias:
        size = v.get("size", 0)
        drill = v.get("drill", 0)
        if size > 0 and drill > 0:
            ring = round((size - drill) / 2.0, 3)
            rings.append(ring)
            ring_dist[ring] = ring_dist.get(ring, 0) + 1

    annular_ring: dict = {}
    if rings:
        min_ring = min(rings)
        annular_ring = {
            "min_mm": min_ring,
            "max_mm": max(rings),
            "distribution": {str(k): cnt for k, cnt in sorted(ring_dist.items())},
        }
        # Count vias below common manufacturer minimums
        violations_0125 = sum(1 for r in rings if r < 0.125)
        violations_0100 = sum(1 for r in rings if r < 0.100)
        if violations_0125 > 0:
            annular_ring["below_0.125mm"] = violations_0125
        if violations_0100 > 0:
            annular_ring["below_0.100mm"] = violations_0100

    # --- Via-in-pad detection ---
    # Build spatial index of pads for efficient lookup
    via_in_pad: list[dict] = []
    # Collect all SMD pads with bounding boxes
    pad_boxes: list[dict] = []
    for fp in footprints:
        ref = fp.get("reference", "")
        fp_layer = fp.get("layer", "F.Cu")
        for pad in fp.get("pads", []):
            if pad.get("type") != "smd":
                continue
            ax = pad.get("abs_x")
            ay = pad.get("abs_y")
            pw = pad.get("width", 0)
            ph = pad.get("height", 0)
            if ax is None or ay is None or pw <= 0 or ph <= 0:
                continue
            pad_boxes.append({
                "ref": ref,
                "pad": pad.get("number", ""),
                "cx": ax, "cy": ay,
                "hw": pw / 2.0, "hh": ph / 2.0,
                "net": pad.get("net_number", -1),
                "layer": fp_layer,
                "shape": pad.get("shape", ""),
                "angle": pad.get("angle", 0) or 0,
            })

    for v in all_vias:
        vx, vy = v["x"], v["y"]
        v_net = v.get("net", 0)
        v_layers = v.get("layers", ["F.Cu", "B.Cu"])
        # Each via counted once. When several pads hold it (a rotated pin pad and the exposed
        # pad's rectangle), take the pad on the via's net, then a numbered pad, then the smallest.
        holders = [pb for pb in pad_boxes
                   if pb["layer"] in v_layers
                   and _point_in_pad(vx, vy, pb["cx"], pb["cy"], pb["hw"] * 2, pb["hh"] * 2,
                                     pb["shape"], pb["angle"])]
        if holders:
            pb = min(holders, key=lambda b: (b["net"] != v_net, b["pad"] == "", b["hw"] * b["hh"]))
            via_in_pad.append({
                "component": pb["ref"],
                "pad": pb["pad"],
                "via_x": round(vx, 3),
                "via_y": round(vy, 3),
                "via_drill": v.get("drill", 0),
                "same_net": v_net == pb["net"],
                "via_type": v["type"],
            })

    # --- Fanout pattern detection ---
    # BGA/QFN packages with many pads often have fanout vias —
    # clusters of vias immediately outside the component footprint
    fanout_patterns: list[dict] = []
    for fp in footprints:
        pad_count = fp.get("pad_count", 0)
        if pad_count < 16:
            continue  # Only check multi-pad packages
        ref = fp.get("reference", "")
        lib = fp.get("library", "").lower()

        # Determine if this is a BGA/QFN/QFP-like package
        is_area_array = any(kw in lib for kw in
                           ("bga", "qfn", "dfn", "qfp", "lga", "wlcsp",
                            "son", "vson", "tqfp", "lqfp"))
        if not is_area_array and pad_count < 40:
            continue

        # Get component bounding box from courtyard or pad extents
        crtyd = fp.get("courtyard")
        if crtyd:
            cx_min, cy_min = crtyd["min_x"], crtyd["min_y"]
            cx_max, cy_max = crtyd["max_x"], crtyd["max_y"]
        else:
            # Fall back to pad extents
            pxs = [p.get("abs_x", fp["x"]) for p in fp.get("pads", [])]
            pys = [p.get("abs_y", fp["y"]) for p in fp.get("pads", [])]
            if not pxs:
                continue
            margin = 0.5
            cx_min, cx_max = min(pxs) - margin, max(pxs) + margin
            cy_min, cy_max = min(pys) - margin, max(pys) + margin

        # Expand by 2mm to catch fanout vias just outside the component
        expand = 2.0
        fx_min = cx_min - expand
        fx_max = cx_max + expand
        fy_min = cy_min - expand
        fy_max = cy_max + expand

        # Count vias in the expanded zone but outside the courtyard
        fanout_vias = 0
        fanout_nets: set[int] = set()
        for v in all_vias:
            vx, vy = v["x"], v["y"]
            if fx_min <= vx <= fx_max and fy_min <= vy <= fy_max:
                # Outside courtyard (actual fanout) or inside (via-in-pad)
                fanout_vias += 1
                if v.get("net", 0) > 0:
                    fanout_nets.add(v["net"])

        if fanout_vias >= 4:
            fanout_patterns.append({
                "component": ref,
                "pad_count": pad_count,
                "fanout_vias": fanout_vias,
                "unique_nets": len(fanout_nets),
                "package": fp.get("library", ""),
            })

    fanout_patterns.sort(key=lambda e: e["fanout_vias"], reverse=True)

    # --- Current capacity facts ---
    # IPC-2221 approximate via current capacity (1oz copper, 10°C rise)
    # Based on plated barrel: I ≈ k * d * t where d=drill, t=plating thickness
    # Typical 1oz plating ~25µm. These are conservative approximations.
    drill_sizes: dict[float, int] = {}
    for v in all_vias:
        d = v.get("drill", 0)
        # Degenerate drills (file artefacts) are excluded from
        # every minimum/rating, not just the DFM and design-rule checks —
        # they're reported separately via `degenerate_drills` instead.
        if _is_real_drill(d):
            drill_sizes[d] = drill_sizes.get(d, 0) + 1

    current_facts: dict = {}
    if drill_sizes:
        min_drill = min(drill_sizes.keys())
        max_drill = max(drill_sizes.keys())
        current_facts = {
            "drill_size_distribution": {str(k): cnt for k, cnt
                                        in sorted(drill_sizes.items())},
            "min_drill_mm": min_drill,
            "max_drill_mm": max_drill,
            "total_vias": len(all_vias),
        }
        # Approximate current ratings for common drill sizes (25µm plating)
        ratings = []
        for d in sorted(drill_sizes.keys()):
            # Barrel cross-section = π * d * t (thin-wall cylinder)
            # Current ≈ cross_section_area * current_density
            # For 25µm plating: area_mm2 = π * d * 0.025
            area_mm2 = math.pi * d * 0.025
            # Approximate 1A per 0.003 mm² (conservative for 10°C rise)
            approx_amps = round(area_mm2 / 0.003, 1)
            ratings.append({
                "drill_mm": d,
                "count": drill_sizes[d],
                "plating_area_mm2": round(area_mm2, 4),
                "approx_current_A": approx_amps,
            })
        current_facts["ratings"] = ratings

    # Footprint-embedded thru_hole/np_thru_hole pad drills (e.g. a
    # thermal via pattern baked into a QFN footprint) aren't board vias, but
    # can be smaller than any of them — surface separately as a fact.
    pad_drills = _pad_drills(footprints)
    if pad_drills:
        current_facts["min_pad_drill_mm"] = min(pad_drills)

    # Sub-0.05mm pad/via drills are file artefacts, not real holes —
    # list them separately instead of silently dropping them.
    degenerate = _degenerate_drills(footprints, all_vias)

    result: dict = {
        "type_breakdown": type_breakdown,
        **({"degenerate_drills": degenerate} if degenerate else {}),
    }
    if annular_ring:
        result["annular_ring"] = annular_ring
    if via_in_pad:
        result["via_in_pad"] = via_in_pad
    if fanout_patterns:
        result["fanout_patterns"] = fanout_patterns
    if current_facts:
        result["current_capacity"] = current_facts

    return result


def analyze_thermal_pad_vias(footprints: list[dict], vias: dict,
                             zones: list[dict],
                             zone_fills: "ZoneFills") -> list[dict]:
    """Thermal pad via adequacy assessment for QFN/BGA/DFN packages.

    For packages with exposed/thermal pads (large center pads), checks:
    - Tier 1: vias on the pad's net (any net when the pad has none) inside the
      rotated 1.5x pad bounding box whose copper reaches the pad's layer (their
      own span, or a same-point stack of vias that does)
    - Tier 1b: footprint-embedded thru_hole pads on the pad's net
    - Tier 2: same-net vias outside the pad bbox but within an expanded
      search radius (max(w,h)*2.0 + 2.0 mm) whose copper continuity to
      the pad is verified via the copper_connected helper — catches
      fanout fillet, adjacent via cluster, and GND-flood-connected via
      patterns
    - Via density (vias per mm²)
    - Whether vias are tented (solder mask prevents solder wicking)
    - Recommendations based on pad size

    Adequacy is computed from the TOTAL verified thermal path
    (Tier 1 + Tier 1b + Tier 2), not just the in-bbox strict count.
    This eliminates the false-positive "no thermal vias" classification
    on designs that use fillet or flood connection patterns.

    When zone fill data is not available (zones weren't saved with
    Fill All Zones), the Tier 2 search falls through cleanly:
    copper_connected returns None for every candidate, so all
    nearby same-net vias land in `nearby_unverified_vias` and do
    not influence adequacy. In that case the function's behavior
    matches pre-Tier 2 semantics.

    Field relationships in each returned entry (important for
    consumers that read more than one count field):

    - `via_count` is the STRICT in-pad count only — preserved for
      backward compat with consumers that want the in-bbox breakdown.
      It counts `vias_in_pad + footprint_via_pads`, unchanged from
      the pre-Tier 2 meaning.
    - `effective_via_count` is the drill-weighted strict in-pad count,
      also preserved unchanged.
    - `total_verified_via_count` is `via_count + nearby_verified_vias`.
    - `total_effective_verified_vias` is the drill-weighted version
      including the nearby_verified contribution.
    - `adequacy` is derived from `total_effective_verified_vias`
      (drill-weighted total including Tier 2 contributions), NOT
      from `via_count` or `effective_via_count`.
    - `raw_adequacy` is derived from `total_verified_via_count`
      (raw count total including Tier 2 contributions).
    - A reader can see `via_count: 2` alongside
      `adequacy: "adequate"` when the extra contribution comes
      from fanout-fillet vias outside the strict pad bbox. That
      is intentional, not a bug — the `adequacy_source` field
      explains which tier drove the classification.
    - `adequacy_source` is ALWAYS present on every returned entry
      and takes one of four values: "in_pad" (Tier 1/1b only),
      "nearby_fillet" (Tier 2 only), "mixed" (both), or "none"
      (no vias at all). Consumers that check `adequacy` can rely
      on `adequacy_source` being present to explain the reasoning.

    Returns a list of per-component thermal pad assessments.
    """
    # EQ-054: effective = Σ(drill/0.3)² (drill-weighted via count)
    all_vias = vias.get("vias", [])
    reaching: dict[str, set[int]] = {}  # pad copper layer -> ids of the vias reaching it
    results: list[dict] = []

    for fp in footprints:
        if fp.get("dnp") or fp.get("board_only"):
            continue
        ref = fp.get("reference", "")
        if not ref:
            continue

        # Skip component types that don't have thermal pads
        ref_prefix = ""
        for c in ref:
            if c.isalpha():
                ref_prefix += c
            else:
                break
        if ref_prefix in ("BT", "TP", "J"):
            continue

        thermal_pads_found = _find_thermal_pads(fp)
        if not thermal_pads_found:
            continue

        pads = fp.get("pads", [])
        for pad in thermal_pads_found:
            pad_num = str(pad.get("number", ""))
            w = pad.get("width", 0)
            h = pad.get("height", 0)
            pad_area = w * h
            ax = pad.get("abs_x", fp["x"])
            ay = pad.get("abs_y", fp["y"])
            net_num = pad.get("net_number", -1)

            # Rotate the via-to-pad offset back into the pad's local frame
            # for the rectangular containment check. KiCad writes a pad's
            # (at x y angle) orientation as the ABSOLUTE board orientation
            # -- it already includes the footprint's own rotation, so the
            # footprint angle must NOT be added again (as in
            # CP-003's _pad_sample_points). This check must undo
            # (not repeat) the local->board placement rotation that pad
            # corners/vias are given elsewhere (board placement uses -angle,
            # e.g. _pad_sample_points), so total_rad is NOT negated here --
            # see _point_in_pad's transposed-matrix form of the same inverse
            # (VP-001) for the equivalent established precedent.
            total_angle = pad.get("angle", 0) or 0
            total_rad = math.radians(total_angle) if total_angle != 0 else 0.0
            cos_a = math.cos(total_rad) if total_angle != 0 else 1.0
            sin_a = math.sin(total_rad) if total_angle != 0 else 0.0

            half_w = w / 2.0
            half_h = h / 2.0
            vias_in_pad = 0
            effective_vias_in_pad = 0.0
            drill_sum = 0.0
            vias_tented = 0
            vias_untented = 0
            vias_exposed = 0

            pad_shape = pad.get("shape", "rect")
            opening = _mask_opening_size(pad, w, h)
            pad_copper = fp.get("layer", "F.Cu")
            if pad_copper not in reaching:
                reaching[pad_copper] = _vias_reaching(all_vias, pad_copper)
            for via in all_vias:
                # A via of another net inside the pad is a short, not thermal copper.
                if net_num > 0 and via.get("net", -1) != net_num:
                    continue
                # A blind or buried via whose stack stops short of the pad's copper is not under it.
                if id(via) not in reaching[pad_copper]:
                    continue
                vx, vy = via["x"], via["y"]
                # Transform via position into pad-local coordinates
                dx, dy = vx - ax, vy - ay
                if total_angle != 0:
                    dx, dy = dx * cos_a - dy * sin_a, dx * sin_a + dy * cos_a
                # Check if via is within the pad area (with margin for
                # manufacturing grid offsets and vias placed just outside
                # the pad boundary — matches thermal_analysis 1.5x radius)
                if (abs(dx) <= half_w * 1.5 and
                        abs(dy) <= half_h * 1.5):
                    vias_in_pad += 1
                    # Weight by drill cross-section relative to 0.3mm standard
                    drill = via.get("drill", 0.3)
                    drill_sum += drill
                    effective_vias_in_pad += (drill / 0.3) ** 2
                    # Solder reaches the via on the side the pad opens; tenting elsewhere
                    # does not cover it.
                    open_sides = _via_open_sides(via, pad.get("layers"))
                    tenting = via.get("tenting", [])
                    if open_sides:
                        tented = all(("front" if side == "F" else "back") in tenting
                                     for side in open_sides)
                    else:
                        tented = len(tenting) > 0
                    if tented:
                        vias_tented += 1
                    else:
                        vias_untented += 1
                    # Inside the pad's mask opening the opening decides, not tenting.
                    in_opening = bool(open_sides) and opening is not None and _point_in_pad(
                        vx, vy, ax, ay, opening[0], opening[1], pad_shape, total_angle)
                    if not tented or in_opening:
                        vias_exposed += 1

            # Count thru_hole pads in the same footprint on the same net
            # — these are footprint-embedded thermal vias (common in
            # QFN/BGA footprints like ESP32-S3-WROOM-1)
            footprint_via_pads = 0
            effective_fp_vias = 0.0
            fp_drill_sum = 0.0
            for other_pad in pads:
                if other_pad is pad:
                    continue
                if (other_pad.get("type") == "thru_hole" and
                        other_pad.get("net_number", -2) == net_num and
                        net_num >= 0):
                    footprint_via_pads += 1
                    fp_drill = other_pad.get("drill", 0.3)
                    if isinstance(fp_drill, dict):
                        fp_drill = fp_drill.get("diameter", 0.3)
                    fp_drill_sum += fp_drill
                    effective_fp_vias += (fp_drill / 0.3) ** 2

            # Tier 2: nearby same-net vias verified copper-connected to the
            # pad via the ZoneFills index. Catches fanout-fillet, adjacent
            # via cluster, and GND-flood-connected patterns that sit past
            # the 1.5x pad bbox.
            pad_net_name = pad.get("net_name", "")
            pad_layer = fp.get("layer", "F.Cu")
            nearby_search_radius = max(w, h) * 2.0 + 2.0
            nearby_verified_vias = 0
            nearby_unverified_vias = 0
            effective_nearby_verified = 0.0
            for via in all_vias:
                vx, vy = via["x"], via["y"]
                # Skip vias already counted in Tier 1 (inside the 1.5x bbox).
                # Repeat the rotation-aware rect test from the Tier 1 loop.
                dx_local, dy_local = vx - ax, vy - ay
                if total_angle != 0:
                    dx_local, dy_local = (
                        dx_local * cos_a - dy_local * sin_a,
                        dx_local * sin_a + dy_local * cos_a,
                    )
                if (abs(dx_local) <= half_w * 1.5 and
                        abs(dy_local) <= half_h * 1.5):
                    continue
                # Skip wrong net
                if via.get("net", -1) != net_num or net_num < 0:
                    continue
                # Skip beyond Tier 2 search radius (Euclidean from pad center).
                # Rotation is distance-preserving, so dx_local/dy_local give
                # the same squared distance as (vx-ax)/(vy-ay).
                if (dx_local * dx_local + dy_local * dy_local >
                        nearby_search_radius * nearby_search_radius):
                    continue
                # Verify copper continuity
                continuity = copper_connected(
                    (vx, vy), (ax, ay),
                    pad_net_name, pad_layer,
                    zone_fills, zones,
                )
                if continuity is True:
                    nearby_verified_vias += 1
                    drill = via.get("drill", 0.3)
                    effective_nearby_verified += (drill / 0.3) ** 2
                elif continuity is None:
                    nearby_unverified_vias += 1
                # continuity is False: via on same net but not copper-connected,
                # skip (not contributing to thermal path)

            # Totals combining all three tiers
            strict_via_count = vias_in_pad + footprint_via_pads
            total_verified_via_count = strict_via_count + nearby_verified_vias
            total_effective_verified_vias = (
                effective_vias_in_pad + effective_fp_vias +
                effective_nearby_verified)

            # Density is still computed from strict in-pad contribution only —
            # it's a pad-area metric, not a whole-thermal-path metric
            density = 0.0
            if pad_area > 0:
                density = (effective_vias_in_pad + effective_fp_vias) / pad_area

            # Recommendations based on pad area
            # Rule of thumb: ~1 via per 1-2mm² of thermal pad area
            # Small QFN (pad < 10mm²): minimum 5-9 vias
            # Medium QFN (10-25mm²): minimum 9-16 vias
            # Large QFN/BGA (>25mm²): scale by area
            if pad_area < 10:
                recommended_min = 5
                recommended_ideal = 9
            elif pad_area < 25:
                recommended_min = 9
                recommended_ideal = 16
            else:
                recommended_min = max(9, int(pad_area * 0.5))
                recommended_ideal = max(16, int(pad_area * 0.8))

            # Assess adequacy using drill-weighted effective count including
            # nearby-verified contributions
            if total_effective_verified_vias >= recommended_ideal:
                adequacy = "good"
            elif total_effective_verified_vias >= recommended_min:
                adequacy = "adequate"
            elif total_verified_via_count > 0:
                adequacy = "insufficient"
            else:
                adequacy = "none"

            # Raw adequacy based on actual verified via count (ignoring drill)
            if total_verified_via_count >= recommended_ideal:
                raw_adequacy = "good"
            elif total_verified_via_count >= recommended_min:
                raw_adequacy = "adequate"
            elif total_verified_via_count > 0:
                raw_adequacy = "insufficient"
            else:
                raw_adequacy = "none"

            # When physical count meets threshold but drill weighting doesn't,
            # the physical count lifts the grade to adequate — drill size is a secondary
            # concern (many manufacturer reference designs use 0.2mm vias in thermal pads),
            # but an effective count below the minimum is never "good"
            drill_penalized = (raw_adequacy in ("adequate", "good") and
                               adequacy in ("insufficient", "none") and
                               total_verified_via_count > 0)
            if drill_penalized:
                adequacy = "adequate"

            # Explain which tiers contributed to the adequacy classification
            # (always present, never None — consumers can rely on this field)
            if nearby_verified_vias > 0 and strict_via_count > 0:
                adequacy_source = "mixed"
            elif nearby_verified_vias > 0:
                adequacy_source = "nearby_fillet"
            elif strict_via_count > 0:
                adequacy_source = "in_pad"
            else:
                adequacy_source = "none"

            entry: dict = {
                "component": ref,
                "value": fp.get("value", ""),
                "library": fp.get("library", ""),
                "layer": fp.get("layer", "F.Cu"),
                "pad_number": pad_num,
                "pad_size_mm": [round(w, 2), round(h, 2)],
                "pad_area_mm2": round(pad_area, 2),
                "net": pad.get("net_name", ""),
                "via_count": strict_via_count,
                "effective_via_count": round(
                    effective_vias_in_pad + effective_fp_vias, 1),
                "standalone_vias": vias_in_pad,
                "footprint_via_pads": footprint_via_pads,
                "nearby_verified_vias": nearby_verified_vias,
                "nearby_unverified_vias": nearby_unverified_vias,
                "nearby_search_radius_mm": round(nearby_search_radius, 2),
                "total_verified_via_count": total_verified_via_count,
                "total_effective_verified_vias": round(
                    total_effective_verified_vias, 1),
                "adequacy_source": adequacy_source,
                "via_density_per_mm2": round(density, 3),
                "vias_tented": vias_tented,
                "vias_untented": vias_untented,
                "recommended_min_vias": recommended_min,
                "recommended_ideal_vias": recommended_ideal,
                "adequacy": adequacy,
                "raw_adequacy": raw_adequacy,
            }

            if vias_exposed > 0:
                entry["tenting_note"] = (
                    f"{vias_exposed} via(s) are open to solder (untented, or inside the "
                    f"pad's mask opening) — solder may wick through during reflow, "
                    f"creating voids under the thermal pad"
                )

            if drill_penalized and strict_via_count > 0:
                avg_drill = (drill_sum + fp_drill_sum) / strict_via_count
                strict_effective = effective_vias_in_pad + effective_fp_vias
                entry["small_via_note"] = (
                    f"{strict_via_count} vias present (avg drill "
                    f"{avg_drill:.2f}mm) but effective count "
                    f"({strict_effective:.1f}) is below threshold "
                    f"({recommended_min}) due to small drill size — "
                    f"design may follow manufacturer's recommended via pattern"
                )

            entry["detector"] = "analyze_thermal_pad_vias"
            entry["rule_id"] = "TV-001"
            entry["category"] = "thermal"
            entry["severity"] = "warning" if adequacy in ("none", "insufficient") else "info"
            entry["confidence"] = "deterministic"
            entry["evidence_source"] = "topology"
            entry["summary"] = f"Thermal vias: {ref} {adequacy} ({strict_via_count}/{recommended_min} min)"
            entry["description"] = (
                f"Thermal pad on {ref} pad {pad_num}: {adequacy} "
                f"({strict_via_count} vias, {recommended_min} recommended)."
            )
            entry["components"] = [ref]
            entry["nets"] = [pad.get("net_name", "")]
            entry["pins"] = []
            rec = []
            if adequacy in ("none", "insufficient"):
                rec.append(f"Add thermal vias under {ref} (need {recommended_min}, have {strict_via_count}).")
            if entry.get("tenting_note"):
                rec.append(entry["tenting_note"])
            entry["recommendation"] = " ".join(rec)
            entry["report_context"] = {
                "section": "Thermal",
                "impact": "Thermal dissipation",
                "standard_ref": "",
            }

            results.append(entry)

    # Sort: worst adequacy first
    adequacy_order = {"none": 0, "insufficient": 1, "adequate": 2, "good": 3}
    results.sort(key=lambda r: (adequacy_order.get(r["adequacy"], 4),
                                r["component"]))
    return results


# Generic-passive reference designators (C, R, L, FB + digits, optionally
# with a hierarchical sheet prefix like "U1/C5"). CP-002 skips these
# because on a 2-layer board with a GND pour every decoupling cap's VCC
# pad is "uncovered" — that's expected, not a finding. Components on real
# touch / antenna pads use TP-prefixed refs or non-passive libraries and
# are surfaced via CP-003.
_PASSIVE_REF_RE = re.compile(r"^([A-Za-z0-9_]+/)?(C|R|L|FB)\d+$")


def _nearest_zone_copper_distance(fp: dict, fp_layer: str, gnd_zones: list,
                                  zones: list, zone_fills) -> tuple:
    """Distance from a footprint's pad outline to the nearest same-layer GND
    copper.

    Prefers the filled polygon edge (actual copper shape, holes
    included) over the zone bbox, which would measure 0.0 mm for any footprint
    inside a GND pour. Falls back
    to a filled_bbox / outline_bbox approximation when polygon
    data is unavailable. Returns (distance, basis) where basis is
    'filled_polygon', 'filled_bbox', or 'outline_bbox'; (inf, None) when
    no candidate zone covers the footprint's layer.
    """
    if zone_fills is not None and getattr(zone_fills, "has_data", False):
        gnd_idxs = {i for i, z in enumerate(zones)
                   if z in gnd_zones and fp_layer in z.get("layers", [])}
        if gnd_idxs:
            best = min(zone_fills.min_edge_distance(px, py, fp_layer, gnd_idxs)
                       for px, py in _pad_sample_points(fp, fp_layer))
            if best < float("inf"):
                return best, "filled_polygon"

    fx, fy = fp.get("x", 0), fp.get("y", 0)
    min_dist = float('inf')
    basis = None
    for gz in gnd_zones:
        if fp_layer not in gz.get("layers", []):
            continue
        gz_basis = "filled_bbox" if gz.get("filled_bbox") else "outline_bbox"
        bbox = gz.get("filled_bbox") or gz.get("outline_bbox")
        if not bbox or len(bbox) != 4:
            continue
        bx_min, by_min, bx_max, by_max = bbox
        # EQ-102: d = √((px-zx)² + (py-zy)²) for point-to-zone-pour proximity.
        # Source: Self-evident — 2D Euclidean distance to the nearest
        #   axis-aligned bounding-box edge (dx/dy clamped to 0 when the
        #   point is inside the box on that axis).
        dx = max(bx_min - fx, 0, fx - bx_max)
        dy = max(by_min - fy, 0, fy - by_max)
        dist = math.sqrt(dx * dx + dy * dy)
        if dist < min_dist:
            min_dist = dist
            basis = gz_basis
    return min_dist, basis


def analyze_copper_presence(footprints: list[dict], zones: list[dict],
                            zone_fills: ZoneFills,
                            ref_layer_map: dict[str, str] | None = None) -> dict:
    """Check zone copper presence at component pad locations.

    Uses point-in-polygon tests against zone filled polygon data to determine
    actual copper presence. Rather than listing every component with the common
    pattern (e.g., GND pour under everything on a 2-layer board), this reports
    a compact summary plus detailed exceptions:

    - Summary: how many components have opposite-layer copper, grouped by net
    - Exceptions: components WITHOUT opposite-layer copper when most others
      have it (e.g., touch pads with clearance in the ground pour)
    - Foreign zones: components with same-layer copper from a zone they're not
      connected to

    Requires filled zone data — run Fill All Zones in KiCad before analysis.
    """
    if not zone_fills.has_data:
        return {
            "warning": "No filled polygon data — zones may not have been "
                       "filled. Run Edit → Fill All Zones (B) in KiCad and "
                       "re-save before analysis.",
        }

    # Classify every component by opposite-layer copper status.
    # Use the component center (first pad centroid) for the check.
    opp_covered: dict[str, set[str]] = {}  # ref -> set of opp zone net names
    opp_uncovered: list[str] = []  # refs with NO opposite-layer copper
    foreign_zone_details: list[dict] = []  # same-layer foreign zone hits

    for fp in footprints:
        ref = fp.get("reference", "")
        fp_layer = fp.get("layer", "F.Cu")
        if ref_layer_map:
            opposite_layer = ref_layer_map.get(fp_layer, "B.Cu" if fp_layer == "F.Cu" else "F.Cu")
        else:
            opposite_layer = "B.Cu" if fp_layer == "F.Cu" else "F.Cu"
        pads = fp.get("pads", [])
        if not pads:
            continue

        # Check opposite-layer copper at each pad location
        has_opp = False
        opp_nets: set[str] = set()
        foreign_pads: list[dict] = []

        for pad in pads:
            px = pad.get("abs_x", fp["x"])
            py = pad.get("abs_y", fp["y"])
            pad_net = pad.get("net_number", 0)

            opp_zones = zone_fills.zones_at_point(
                px, py, opposite_layer, zones)
            if opp_zones:
                has_opp = True
                for z in opp_zones:
                    nn = z.get("net_name", "")
                    if nn:
                        opp_nets.add(nn)

            # Same-layer foreign zone check, on the copper side the pad is on (an SMD pad
            # can sit on the other side of its footprint, e.g. a hot-swap socket)
            if _pad_on_layer(pad, fp_layer, fp_layer):
                pad_side = fp_layer
            else:
                flip = "B.Cu" if fp_layer == "F.Cu" else "F.Cu"
                pad_side = flip if _pad_on_layer(pad, flip, fp_layer) else None
            same_other = [
                z for z in zone_fills.zones_at_point(px, py, pad_side, zones)
                if z.get("net", 0) != pad_net and pad_net > 0
            ] if pad_side else []
            if same_other:
                foreign_pads.append({
                    "pad": str(pad.get("number", "")),
                    "position": [round(px, 3), round(py, 3)],
                    "foreign_zones": [z["net_name"] for z in same_other],
                })

        if has_opp:
            opp_covered[ref] = opp_nets
        else:
            opp_uncovered.append(ref)

        if foreign_pads:
            fz_nets = sorted({
                n for fp_pad in foreign_pads
                for n in fp_pad["foreign_zones"]
            })
            # Classify: is every foreign zone a ground rail AND does this
            # component have a pin on that ground? That's the "desired"
            # case (decoupling cap sitting over GND pour) and should
            # surface as info, not warning. Anything else stays a
            # warning — mixed rails, non-ground foreign zones, or
            # components that don't actually reference the foreign net.
            fz_all_ground = bool(fz_nets) and all(
                is_ground_name(n) for n in fz_nets
            )
            comp_pad_nets = {
                (p.get("net_name") or "").upper()
                for p in fp.get("pads", []) or []
                if p.get("net_name")
            }
            comp_has_gnd_pad = any(
                is_ground_name(n) for n in comp_pad_nets
            )
            if fz_all_ground and comp_has_gnd_pad:
                severity = "info"
                impact = ("Decoupling / bypass cap sitting over the GND pour — "
                          "expected layout, not a clearance violation.")
                rec = ("No action. Bypass caps are intentionally placed over "
                       "the ground return to minimise loop area.")
            else:
                severity = "warning"
                impact = "Electrical isolation"
                rec = "Verify zone clearance rules or add keepout."

            foreign_zone_details.append({
                "component": ref,
                "value": fp.get("value", ""),
                "layer": fp_layer,
                "pads": foreign_pads,
                "detector": "analyze_copper_presence",
                "rule_id": "CP-001",
                "category": "copper_integrity",
                "severity": severity,
                "confidence": "deterministic",
                "evidence_source": "geometry",
                "summary": f"Foreign zone under {ref}",
                "description": (
                    f"Component {ref} has same-layer copper from foreign "
                    f"zone(s): {', '.join(fz_nets)}."
                ),
                "components": [ref],
                "nets": fz_nets,
                "pins": [fp_pad["pad"] for fp_pad in foreign_pads],
                "recommendation": rec,
                "report_context": {
                    "section": "Copper Integrity",
                    "impact": impact,
                    "standard_ref": "",
                },
            })

    # Build compact summary
    # Group covered components by which nets they sit over
    net_groups: dict[str, list[str]] = {}  # "GND" -> [ref1, ref2, ...]
    for ref, nets in opp_covered.items():
        key = ", ".join(sorted(nets))
        net_groups.setdefault(key, []).append(ref)

    opp_summary: list[dict] = []
    for nets_str, refs in sorted(net_groups.items(),
                                 key=lambda x: -len(x[1])):
        opp_summary.append({
            "opposite_layer_nets": nets_str,
            "component_count": len(refs),
            "components": sorted(refs),
        })

    result: dict = {
        "opposite_layer_summary": opp_summary,
    }

    # The interesting signal: components WITHOUT opposite-layer copper.
    # Emit CP-002 findings only for non-passive references — on a
    # 2-layer board with a GND pour on the opposite side, every decoupling
    # cap's VCC pad would otherwise fire CP-002, drowning the info tier.
    # Actual touch-sensitive / RF components are still surfaced via CP-003.
    # The summary list (`no_opposite_layer_copper`) keeps everything so
    # consumers that want the raw uncovered set still have it.
    if opp_uncovered:
        result["no_opposite_layer_copper"] = sorted(opp_uncovered)
        cp_002_refs = [r for r in opp_uncovered if not _PASSIVE_REF_RE.match(r)]
        if cp_002_refs:
            result["no_opposite_layer_copper_findings"] = [{
                "component": _ref,
                "detector": "analyze_copper_presence",
                "rule_id": "CP-002",
                "category": "copper_integrity",
                "severity": "info",
                "confidence": "deterministic",
                "evidence_source": "geometry",
                "summary": f"No opposite-layer copper under {_ref}",
                "description": (
                    f"Component {_ref} has no copper zone on the opposite layer."
                ),
                "components": [_ref],
                "nets": [],
                "pins": [],
                "recommendation": "",
                "report_context": {
                    "section": "Copper Integrity",
                    "impact": "Return path / shielding",
                    "standard_ref": "",
                },
            } for _ref in sorted(cp_002_refs)]

    if foreign_zone_details:
        result["same_layer_foreign_zones"] = foreign_zone_details

    # Touch pad GND clearance measurement
    # For components in opp_uncovered that look like touch pads, compute
    # distance to nearest same-layer GND zone edge
    _gnd_keywords = ("gnd", "vss", "ground", "agnd", "dgnd", "pgnd")
    gnd_zones = [z for z in zones
                 if z.get("net_name", "").lower() in _gnd_keywords
                 or "gnd" in z.get("net_name", "").lower()]
    touch_clearances = []
    for fp in footprints:
        ref = fp.get("reference", "")
        if ref not in opp_uncovered:
            continue
        # A bare "TP" ref prefix is not evidence of a touch pad (it also matches TestPoint:*
        # library parts).
        if not is_touch_pad(ref, fp.get("value"), fp.get("library", "")):
            continue
        fp_layer = fp.get("layer", "F.Cu")
        min_dist, _basis = _nearest_zone_copper_distance(fp, fp_layer,
                                                         gnd_zones, zones,
                                                         zone_fills)
        if min_dist < float('inf'):
            _conf = "deterministic" if _basis == "filled_polygon" else "heuristic"
            _note = ("" if _basis == "filled_polygon" else
                     " (zone bbox basis — fill polygon data unavailable; "
                     "actual clearance may be larger)")
            _nets = sorted({p.get("net_name") for p in fp.get("pads", [])
                          if p.get("net_name") and not is_ground_name(p["net_name"])})
            touch_clearances.append({
                "ref": ref,
                "layer": fp_layer,
                "gnd_clearance_mm": round(min_dist, 2),
                "measurement_basis": _basis,
                "detector": "analyze_copper_presence",
                "rule_id": "CP-003",
                "category": "copper_integrity",
                "severity": "info",
                "confidence": _conf,
                "evidence_source": "geometry",
                "summary": f"Touch pad {ref} GND clearance {round(min_dist, 2)}mm",
                "description": (
                    f"Touch pad {ref} on {fp_layer}: {round(min_dist, 2)}mm "
                    f"clearance to nearest GND zone copper{_note}."
                ),
                "components": [ref],
                "nets": _nets,
                "pins": [],
                "recommendation": "",
                "report_context": {
                    "section": "Copper Integrity",
                    "impact": "Touch sensitivity",
                    "standard_ref": "",
                },
            })
    if touch_clearances:
        result["touch_pad_gnd_clearance"] = touch_clearances

    return result


def analyze_via_in_pad(footprints: list[dict], vias: dict,
                       thermal_pads: set[tuple[str, str]]) -> list[dict]:
    """VP-001: Detect vias inside SMD pads; warn when solder can reach them.

    ``thermal_pads`` holds the (reference, pad number) pairs TV-001 already reports; they and
    pads with the heatsink fabrication property are skipped."""
    findings: list[dict] = []
    via_list = vias.get("vias", [])
    if not via_list:
        return findings

    # Build SMD pad bboxes (excluding thermal pads already covered by TV-001)
    smd_pads: list[tuple[str, 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
            # A pad KiCad marks as a heatsink carries its vias on purpose.
            if ((ref, str(pad.get("number", ""))) in thermal_pads
                    or pad.get("_property") == "pad_prop_heatsink"):
                continue
            # Pads "disabled" by clearing all copper layers
            # (e.g. (layers "Dwgs.User")) can't have via-in-pad issues.
            _pad_layers = pad.get("layers") or []
            if _pad_layers and not any(l.endswith(".Cu") for l in _pad_layers):
                continue
            px = pad.get("abs_x")
            py = pad.get("abs_y")
            if px is None or py is None:
                continue
            pw = pad.get("width", 0)
            ph = pad.get("height", 0)
            if pw <= 0 or ph <= 0:
                continue
            pad_num = pad.get("number", "?")
            smd_pads.append((ref, pad_num, pad.get("net_name", ""),
                             px, py, pw, ph,
                             pad.get("shape", "rect"), pad.get("angle", 0), _pad_layers))

    for via in via_list:
        vx = via.get("x")
        vy = via.get("y")
        if vx is None or vy is None:
            continue
        for ref, pad_num, net, ppx, ppy, pw, ph, pshape, pangle, players in smd_pads:
            if _point_in_pad(vx, vy, ppx, ppy, pw, ph, pshape, pangle):
                tented = len(via.get("tenting", [])) > 0
                by_pad = _via_exposed_by_pad(via, players)
                if by_pad:
                    state, detail = "exposed by the pad's mask opening", (
                        "The pad's mask opening exposes it whatever its tenting — "
                        "solder may wick through.")
                elif tented:
                    state, detail = "tented", "Tented."
                else:
                    state, detail = "untented", "Not tented — solder may wick through."
                exposed = by_pad or not tented
                severity = "warning" if exposed else "info"
                findings.append({
                    "component": ref,
                    "pad": pad_num,
                    "via_x": round(vx, 2),
                    "via_y": round(vy, 2),
                    "tented": tented,
                    "detector": "analyze_via_in_pad",
                    "rule_id": "VP-001",
                    "category": "dfm",
                    "severity": severity,
                    "confidence": "heuristic",
                    "evidence_source": "topology",
                    "summary": f"Via in pad: {ref}:{pad_num} ({state})",
                    "description": f"Via at ({round(vx, 2)}, {round(vy, 2)}) inside SMD pad {ref}:{pad_num}. {detail}",
                    "components": [ref],
                    "nets": [net] if net else [],
                    "pins": [],
                    "recommendation": (f"Fill and cap via in {ref}:{pad_num}." if by_pad
                                       else "" if tented
                                       else f"Fill and cap via in {ref}:{pad_num} or tent with solder mask."),
                    "report_context": {"section": "DFM", "impact": "Solder wicking risk" if exposed else "", "standard_ref": ""},
                })
                break  # One finding per via

    return findings


def analyze_board_edge_via_clearance(vias: dict, board_outline: dict) -> list[dict]:
    """BV-001: Check vias close to board edges."""
    # EQ-103: d = min distance from the via centre to any Edge.Cuts edge (lines, rects,
    # arcs, circles, polygons, curves) -- see outline_edge_distance.
    findings: list[dict] = []
    via_list = vias.get("vias", [])
    edges = board_outline.get("edges", [])

    if not via_list or not edges:
        return findings

    threshold_mm = 0.5
    for via in via_list:
        vx = via.get("x")
        vy = via.get("y")
        if vx is None or vy is None:
            continue
        min_dist = outline_edge_distance(vx, vy, edges)
        if min_dist is None:
            return findings
        if min_dist < threshold_mm:
            findings.append({
                "via_x": round(vx, 2),
                "via_y": round(vy, 2),
                "edge_clearance_mm": round(min_dist, 3),
                "detector": "analyze_board_edge_via_clearance",
                "rule_id": "BV-001",
                "category": "dfm",
                "severity": "warning",
                "confidence": "deterministic",
                "evidence_source": "topology",
                "summary": f"Via at ({round(vx, 1)}, {round(vy, 1)}) is {round(min_dist, 2)}mm from board edge",
                "description": f"Via at ({round(vx, 2)}, {round(vy, 2)}) is only {round(min_dist, 3)}mm from the board edge. Minimum recommended is {threshold_mm}mm.",
                "components": [],
                "nets": [],
                "pins": [],
                "recommendation": f"Move via at least {threshold_mm}mm from board edge to prevent damage during depanelization.",
                "report_context": {"section": "DFM", "impact": "Via damage during routing/depanelization", "standard_ref": ""},
            })

    return findings[:50]  # Cap at 50 findings
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