traceforge-pcb 1.0.0__py3-none-any.whl

traceforge/features/package.py

@@ -0,0 +1,433 @@
+"""Release package: fabrication files, BOM, placement, a viewer and a measured manufacturability report.
+
+``measure`` reads the smallest real feature sizes off the board (track width, via and drill sizes,
+annular rings, copper to edge, track to track clearance, silkscreen text) and ``dfm_rows`` sets them
+against a fab profile with the margin left, so "DRC is clean" becomes "this board is inside the fab's
+published limits by this much". It is an offline check of the numbers a fab's own portal tests; the
+fab's review still has the last word. ``build_package`` writes the bundle with a SHA-256 manifest.
+"""
+
+from __future__ import annotations
+
+import csv
+import hashlib
+import json
+import shutil
+import zipfile
+from collections import defaultdict
+from pathlib import Path
+from typing import Any
+
+from traceforge.fab import FabProfile, get_fab
+from traceforge.kicad.cli import KicadCli, KicadCliError
+from traceforge.kicad.edgegeom import _seg_seg_dist
+from traceforge.kicad.outputs import write_jlc_cpl
+from traceforge.kicad.pcb import Board, read_board
+
+CELL = 2.0  # mm, spatial hash for the clearance scan
+WARN_MARGIN = 0.05  # mm: closer than this to a limit is a warning, not a pass
+
+
+def _ref_key(ref: str) -> tuple[str, int]:
+    prefix = ref.rstrip("0123456789")
+    digits = ref[len(prefix) :]
+    return (prefix, int(digits) if digits.isdigit() else 0)
+
+
+def _track_clearance(board: Board) -> tuple[float | None, tuple[str, str] | None]:
+    """Smallest copper gap between tracks of different nets on the same layer, mm."""
+    cells: dict[tuple[str, int, int], list[int]] = defaultdict(list)
+    tracks = board.tracks
+    for i, t in enumerate(tracks):
+        reach = t.width / 2
+        x0, x1 = sorted((t.x1, t.x2))
+        y0, y1 = sorted((t.y1, t.y2))
+        for cx in range(int((x0 - reach) // CELL), int((x1 + reach) // CELL) + 1):
+            for cy in range(int((y0 - reach) // CELL), int((y1 + reach) // CELL) + 1):
+                cells[(t.layer, cx, cy)].append(i)
+    best: float | None = None
+    where: tuple[str, str] | None = None
+    seen: set[tuple[int, int]] = set()
+    for members in cells.values():
+        for ai in range(len(members)):
+            for bi in range(ai + 1, len(members)):
+                i, j = members[ai], members[bi]
+                pair = (i, j) if i < j else (j, i)
+                if pair in seen:
+                    continue
+                seen.add(pair)
+                a, b = tracks[i], tracks[j]
+                if a.net == b.net:
+                    continue
+                gap = (
+                    _seg_seg_dist((a.x1, a.y1, a.x2, a.y2), (b.x1, b.y1, b.x2, b.y2))
+                    - (a.width + b.width) / 2
+                )
+                if best is None or gap < best:
+                    best, where = gap, (a.net, b.net)
+    return best, where
+
+
+def measure(board: Board) -> dict[str, Any]:
+    """The smallest feature sizes on the board (None where the board has none of that feature)."""
+    widths = [t.width for t in board.tracks]
+    via_dia = [v.size for v in board.vias]
+    drills = [v.drill for v in board.vias]
+    rings = [(v.size - v.drill) / 2 for v in board.vias if v.drill > 0]
+    for fp in board.footprints:
+        for pad in fp.pads:
+            if pad.drill > 0 and pad.kind == "thru_hole":
+                drills.append(pad.drill)
+                rings.append((min(pad.width, pad.height) - pad.drill) / 2)
+            elif pad.drill > 0:
+                drills.append(pad.drill)
+    edge = None
+    geom = board.edge_geometry
+    if geom is not None:
+        gaps = []
+        for t in board.tracks:
+            for x, y in ((t.x1, t.y1), (t.x2, t.y2)):
+                gaps.append(geom.distance(x, y) - t.width / 2)
+        for v in board.vias:
+            gaps.append(geom.distance(v.x, v.y) - v.size / 2)
+        edge = min(gaps) if gaps else None
+    clearance, clear_nets = _track_clearance(board)
+    silk = [h for layer, _text, h in board.texts if "Silk" in layer and h > 0]
+    for fp in board.footprints:
+        silk += [h for layer, _t, h in fp.texts if "Silk" in layer and h > 0]
+    top = sum(1 for f in board.footprints if f.layer == "F.Cu" and not f.reference.startswith("#"))
+    bottom = sum(
+        1 for f in board.footprints if f.layer == "B.Cu" and not f.reference.startswith("#")
+    )
+    fiducials = [
+        f.reference
+        for f in board.footprints
+        if "fiducial" in f.lib_id.lower() or f.reference.upper().startswith("FID")
+    ]
+    parts = [f for f in board.footprints if not f.reference.startswith("#")]
+    no_lcsc = sorted(
+        (
+            f.reference
+            for f in parts
+            if not (f.fields.get("LCSC") or f.fields.get("LCSC Part") or f.fields.get("lcsc"))
+            and not ({"exclude_from_bom", "board_only"} & set(f.attrs))
+        ),
+        key=_ref_key,
+    )
+    smd = sum(1 for f in parts for p in f.pads if p.kind == "smd")
+    return {
+        "copper_layers": len(board.copper_layers),
+        "thickness_mm": board.thickness,
+        "size_mm": [round(v, 2) for v in board.size_mm] if board.size_mm else None,
+        "min_track_width": min(widths) if widths else None,
+        "min_via_diameter": min(via_dia) if via_dia else None,
+        "min_drill": min(drills) if drills else None,
+        "min_annular_ring": min(rings) if rings else None,
+        "min_copper_to_edge": edge,
+        "min_track_clearance": clearance,
+        "min_track_clearance_nets": list(clear_nets) if clear_nets else None,
+        "min_silk_text_height": min(silk) if silk else None,
+        "parts_top": top,
+        "parts_bottom": bottom,
+        "fiducials": fiducials,
+        "parts_without_lcsc": no_lcsc,
+        "smd_pads": smd,
+        "dnp": sorted((f.reference for f in parts if f.dnp), key=_ref_key),
+    }
+
+
+def _limit_row(
+    rid: str,
+    label: str,
+    measured: float | None,
+    limit: float,
+    note: str = "",
+    lower_is_bad: bool = True,
+) -> dict[str, Any]:
+    if measured is None:
+        return {
+            "id": rid,
+            "label": label,
+            "measured": None,
+            "limit": limit,
+            "unit": "mm",
+            "status": "n/a",
+            "margin": None,
+            "note": "no such feature on this board",
+        }
+    margin = measured - limit if lower_is_bad else limit - measured
+    status = "fail" if margin < -1e-6 else ("warn" if margin < WARN_MARGIN else "pass")
+    return {
+        "id": rid,
+        "label": label,
+        "measured": round(measured, 4),
+        "limit": limit,
+        "unit": "mm",
+        "status": status,
+        "margin": round(margin, 4),
+        "note": note,
+    }
+
+
+def dfm_rows(m: dict[str, Any], fab: FabProfile) -> list[dict[str, Any]]:
+    """The measurements set against ``fab``: one row each with pass, warn (close) or fail."""
+    rows = [
+        _limit_row("dfm.track", "narrowest track", m["min_track_width"], fab.min_track),
+        _limit_row(
+            "dfm.clearance",
+            "track to track clearance (different nets)",
+            m["min_track_clearance"],
+            fab.min_clearance,
+            note=(
+                "nets " + " / ".join(m["min_track_clearance_nets"])
+                if m["min_track_clearance_nets"]
+                else "pads and zones are checked by KiCad DRC"
+            ),
+        ),
+        _limit_row("dfm.via", "smallest via diameter", m["min_via_diameter"], fab.min_via_diameter),
+        _limit_row("dfm.drill", "smallest drill", m["min_drill"], fab.min_drill),
+        _limit_row(
+            "dfm.ring", "smallest annular ring", m["min_annular_ring"], fab.min_annular_ring
+        ),
+        _limit_row(
+            "dfm.edge",
+            "copper to board edge",
+            m["min_copper_to_edge"],
+            fab.min_copper_edge,
+        ),
+        _limit_row(
+            "dfm.silk",
+            "smallest silkscreen text",
+            m["min_silk_text_height"],
+            fab.min_silk_text_height,
+        ),
+    ]
+    size = m["size_mm"]
+    if size:
+        big = max(fab.max_board_mm)
+        small = min(fab.max_board_mm)
+        over = max(size) > big or min(size) > small
+        rows.append(
+            {
+                "id": "dfm.size",
+                "label": "board size",
+                "measured": size,
+                "limit": list(fab.max_board_mm),
+                "unit": "mm",
+                "status": "fail" if over else "pass",
+                "margin": None,
+                "note": "",
+            }
+        )
+    top, bottom = m["parts_top"], m["parts_bottom"]
+    if m["smd_pads"]:
+        have = len(m["fiducials"])
+        rows.append(
+            {
+                "id": "asm.fiducials",
+                "label": "fiducials for pick and place",
+                "measured": have,
+                "limit": 2,
+                "unit": "count",
+                "status": "pass" if have >= 2 else "warn",
+                "margin": None,
+                "note": "" if have >= 2 else "assembly houses align on 2 or more fiducials",
+            }
+        )
+    rows.append(
+        {
+            "id": "asm.sides",
+            "label": "assembly sides",
+            "measured": {"top": top, "bottom": bottom},
+            "limit": None,
+            "unit": "parts",
+            "status": "warn" if top and bottom else "pass",
+            "margin": None,
+            "note": "parts on both sides: assembly is usually quoted per side"
+            if top and bottom
+            else "",
+        }
+    )
+    miss = m["parts_without_lcsc"]
+    rows.append(
+        {
+            "id": "asm.lcsc",
+            "label": "parts with a supplier part number",
+            "measured": len(miss),
+            "limit": 0,
+            "unit": "missing",
+            "status": "pass" if not miss else "warn",
+            "margin": None,
+            "note": ("missing: " + ", ".join(miss[:12]) + (" ..." if len(miss) > 12 else ""))
+            if miss
+            else "",
+        }
+    )
+    return rows
+
+
+def _bom_rows(board: Board) -> list[dict[str, str]]:
+    groups: dict[tuple[str, str, str], list[str]] = defaultdict(list)
+    for fp in board.footprints:
+        if (
+            fp.reference.startswith("#")
+            or ({"exclude_from_bom", "board_only"} & set(fp.attrs))
+            or fp.dnp
+        ):
+            continue
+        lcsc = fp.fields.get("LCSC") or fp.fields.get("LCSC Part") or fp.fields.get("lcsc") or ""
+        groups[(fp.value, fp.lib_id.split(":")[-1], lcsc)].append(fp.reference)
+    rows = []
+    for (value, footprint, lcsc), refs in sorted(
+        groups.items(), key=lambda kv: _ref_key(min(kv[1], key=_ref_key))
+    ):
+        refs.sort(key=_ref_key)
+        rows.append(
+            {
+                "Comment": value,
+                "Designator": ",".join(refs),
+                "Footprint": footprint,
+                "LCSC Part #": lcsc,
+                "Quantity": str(len(refs)),
+            }
+        )
+    return rows
+
+
+def _write_bom(board: Board, out: Path) -> Path:
+    rows = _bom_rows(board)
+    with out.open("w", newline="", encoding="utf-8") as handle:
+        writer = csv.DictWriter(
+            handle, ["Comment", "Designator", "Footprint", "LCSC Part #", "Quantity"]
+        )
+        writer.writeheader()
+        writer.writerows(rows)
+    return out
+
+
+def dfm_markdown(name: str, fab: FabProfile, rows: list[dict[str, Any]]) -> str:
+    icon = {"pass": "pass", "warn": "WARN", "fail": "FAIL", "n/a": "-"}
+    lines = [
+        f"# Manufacturability: {name} against {fab.name}",
+        "",
+        f"Profile: {fab.notes or fab.name}. Numbers are read off the board file; the fab's own review decides.",
+        "",
+        "| check | measured | limit | margin | result | note |",
+        "|---|---|---|---|---|---|",
+    ]
+    for r in rows:
+        meas = r["measured"] if r["measured"] is not None else "-"
+        limit = r["limit"] if r["limit"] is not None else "-"
+        margin = "" if r["margin"] is None else f"{r['margin']:+.3f}"
+        lines.append(
+            f"| {r['label']} | {meas} | {limit} | {margin} | {icon[r['status']]} | {r['note']} |"
+        )
+    fails = [r for r in rows if r["status"] == "fail"]
+    warns = [r for r in rows if r["status"] == "warn"]
+    lines += [
+        "",
+        f"{len(fails)} fail, {len(warns)} warn, {sum(r['status'] == 'pass' for r in rows)} pass.",
+        "",
+    ]
+    return "\n".join(lines)
+
+
+def _sha(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for block in iter(lambda: handle.read(1 << 20), b""):
+            digest.update(block)
+    return digest.hexdigest()
+
+
+_README = """{name} - fabrication package
+
+Made by traceforge {version} from {pcb} for {fab}.
+
+  gerbers/      copper, mask, silk, edge and drill files (KiCad export)
+  {name}-bom.csv   bill of materials in the column layout the assembly service takes
+  {name}-cpl.csv   component placement list (centre, side, rotation)
+  dfm_report.md    measured feature sizes against {fab}'s limits (also dfm_report.json)
+  viewer.html      open in a browser: layers, nets, BOM, no KiCad needed
+  MANIFEST.sha256  SHA-256 of every file here; check with: sha256sum -c MANIFEST.sha256
+
+Before ordering: read dfm_report.md, confirm the stackup and finish on the fab's order page, and let the
+fab's own review run. Rotation and origin conventions of the placement list follow the fab's documentation
+at the time of writing; check a first assembly order against its preview.
+"""
+
+
+def build_package(
+    pcb: str | Path,
+    out_dir: str | Path,
+    fab: str = "jlcpcb",
+    name: str | None = None,
+    make_zip: bool = True,
+    gerbers: bool = True,
+) -> dict[str, Any]:
+    """Write the release package; returns the report (files, checks, warnings)."""
+    from traceforge import __version__
+    from traceforge.features.viewer import write_viewer
+
+    pcb = Path(pcb)
+    profile = get_fab(fab)
+    board = read_board(pcb)
+    name = name or pcb.stem
+    out = Path(out_dir)
+    if out.exists():
+        shutil.rmtree(out)
+    out.mkdir(parents=True)
+    notes: list[str] = []
+    files: list[Path] = []
+
+    if gerbers:
+        cli = KicadCli()
+        if cli.available:
+            try:
+                files += cli.gerbers(pcb, out / "gerbers")
+            except KicadCliError as exc:
+                notes.append(f"gerbers not written: {exc}")
+        else:
+            notes.append("gerbers not written: kicad-cli is not installed")
+    files.append(_write_bom(board, out / f"{name}-bom.csv"))
+    files.append(write_jlc_cpl(pcb, out / f"{name}-cpl.csv"))
+
+    measured = measure(board)
+    rows = dfm_rows(measured, profile)
+    (out / "dfm_report.json").write_text(
+        json.dumps({"fab": profile.name, "measured": measured, "checks": rows}, indent=1),
+        encoding="utf-8",
+    )
+    (out / "dfm_report.md").write_text(dfm_markdown(name, profile, rows), encoding="utf-8")
+    files += [out / "dfm_report.json", out / "dfm_report.md"]
+    files.append(write_viewer(pcb, out / "viewer.html"))
+    (out / "README.txt").write_text(
+        _README.format(name=name, version=__version__, pcb=pcb.name, fab=profile.name),
+        encoding="utf-8",
+    )
+    files.append(out / "README.txt")
+
+    manifest = out / "MANIFEST.sha256"
+    entries = sorted(p for p in out.rglob("*") if p.is_file() and p != manifest)
+    manifest.write_text(
+        "".join(f"{_sha(p)}  {p.relative_to(out).as_posix()}\n" for p in entries), encoding="utf-8"
+    )
+    zip_path = None
+    if make_zip:
+        zip_path = out.parent / f"{name}-fab-package.zip"
+        with zipfile.ZipFile(zip_path, "w", zipfile.ZIP_DEFLATED) as archive:
+            for p in sorted(out.rglob("*")):
+                if p.is_file():
+                    archive.write(p, f"{name}/{p.relative_to(out).as_posix()}")
+    fails = [r["id"] for r in rows if r["status"] == "fail"]
+    return {
+        "package_dir": str(out),
+        "zip": str(zip_path) if zip_path else None,
+        "files": len(entries) + 1,
+        "fab": profile.name,
+        "checks": rows,
+        "failed": fails,
+        "warned": [r["id"] for r in rows if r["status"] == "warn"],
+        "notes": notes,
+        "ready": not fails and not any("not written" in n for n in notes),
+    }

traceforge/features/revdiff.py

@@ -0,0 +1,224 @@
+"""Compare two revisions of a board: parts, connectivity, stackup, routing and size.
+
+``diff_boards(old, new)`` returns plain data; ``to_markdown`` renders it for a pull request. Parts are
+matched by reference designator. A moved part is reported only when it moved by more than
+``move_tol`` mm or turned. Connectivity compares which nets each pad is on, so a swapped pin shows
+up even when no part changed.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from traceforge.kicad.pcb import Board, read_board
+
+
+def _pad_nets(board: Board) -> dict[str, str]:
+    return {
+        f"{fp.reference}.{pad.number}": pad.net
+        for fp in board.footprints
+        if not fp.reference.startswith("#")
+        for pad in fp.pads
+    }
+
+
+def _routing(board: Board) -> dict[str, Any]:
+    per_layer: dict[str, dict[str, float]] = {}
+    for t in board.tracks:
+        entry = per_layer.setdefault(t.layer, {"tracks": 0, "length_mm": 0.0})
+        entry["tracks"] += 1
+        entry["length_mm"] += t.length
+    widths = sorted({round(t.width, 3) for t in board.tracks})
+    vias = sorted({(round(v.size, 3), round(v.drill, 3)) for v in board.vias})
+    return {
+        "layers": {
+            k: {"tracks": v["tracks"], "length_mm": round(v["length_mm"], 2)}
+            for k, v in per_layer.items()
+        },
+        "track_widths_mm": widths,
+        "via_count": len(board.vias),
+        "via_sizes": [list(v) for v in vias],
+        "total_length_mm": round(sum(v["length_mm"] for v in per_layer.values()), 2),
+    }
+
+
+def diff_boards(old: Board, new: Board, move_tol: float = 0.05) -> dict[str, Any]:
+    """What changed from ``old`` to ``new``."""
+    a = {f.reference: f for f in old.footprints if not f.reference.startswith("#")}
+    b = {f.reference: f for f in new.footprints if not f.reference.startswith("#")}
+    added = sorted(set(b) - set(a))
+    removed = sorted(set(a) - set(b))
+    changed: list[dict[str, Any]] = []
+    for ref in sorted(set(a) & set(b)):
+        x, y = a[ref], b[ref]
+        what: dict[str, Any] = {}
+        if x.value != y.value:
+            what["value"] = [x.value, y.value]
+        if x.lib_id != y.lib_id:
+            what["footprint"] = [x.lib_id, y.lib_id]
+        if x.layer != y.layer:
+            what["side"] = [x.layer, y.layer]
+        if round((x.angle - y.angle) % 360, 3) not in (0.0, 360.0):
+            what["angle"] = [round(x.angle, 2), round(y.angle, 2)]
+        dist = ((x.x - y.x) ** 2 + (x.y - y.y) ** 2) ** 0.5
+        if dist > move_tol:
+            what["moved_mm"] = round(dist, 2)
+        if x.dnp != y.dnp:
+            what["dnp"] = [x.dnp, y.dnp]
+        if what:
+            changed.append({"ref": ref, **what})
+    pa, pb = _pad_nets(old), _pad_nets(new)
+    rewired = [
+        {"pad": pad, "from": pa[pad], "to": pb[pad]}
+        for pad in sorted(set(pa) & set(pb))
+        if pa[pad] != pb[pad]
+    ]
+    nets_old = {n for n in pa.values() if n}
+    nets_new = {n for n in pb.values() if n}
+    ra, rb = _routing(old), _routing(new)
+    stack: dict[str, Any] = {}
+    if old.copper_layers != new.copper_layers:
+        stack["copper_layers"] = [old.copper_layers, new.copper_layers]
+    if round(old.thickness, 3) != round(new.thickness, 3):
+        stack["thickness_mm"] = [old.thickness, new.thickness]
+    sa = [round(v, 2) for v in old.size_mm] if old.size_mm else None
+    sb = [round(v, 2) for v in new.size_mm] if new.size_mm else None
+    zones_old = sorted((z["net"], tuple(z["layers"])) for z in old.zones)
+    zones_new = sorted((z["net"], tuple(z["layers"])) for z in new.zones)
+    result = {
+        "parts": {
+            "old": len(a),
+            "new": len(b),
+            "added": [{"ref": r, "value": b[r].value, "footprint": b[r].lib_id} for r in added],
+            "removed": [{"ref": r, "value": a[r].value, "footprint": a[r].lib_id} for r in removed],
+            "changed": changed,
+        },
+        "nets": {
+            "added": sorted(nets_new - nets_old),
+            "removed": sorted(nets_old - nets_new),
+            "rewired_pads": rewired,
+        },
+        "stackup": stack,
+        "board_size_mm": [sa, sb] if sa != sb else None,
+        "zones": {
+            "added": [list(z) for z in sorted(set(zones_new) - set(zones_old))],
+            "removed": [list(z) for z in sorted(set(zones_old) - set(zones_new))],
+        },
+        "routing": {"old": ra, "new": rb},
+    }
+    result["summary"] = summarize(result)
+    return result
+
+
+def summarize(d: dict[str, Any]) -> dict[str, Any]:
+    p, n = d["parts"], d["nets"]
+    r_old, r_new = d["routing"]["old"], d["routing"]["new"]
+    return {
+        "parts_added": len(p["added"]),
+        "parts_removed": len(p["removed"]),
+        "parts_changed": len(p["changed"]),
+        "nets_added": len(n["added"]),
+        "nets_removed": len(n["removed"]),
+        "pads_rewired": len(n["rewired_pads"]),
+        "vias_delta": r_new["via_count"] - r_old["via_count"],
+        "track_length_delta_mm": round(r_new["total_length_mm"] - r_old["total_length_mm"], 2),
+        "stackup_changed": bool(d["stackup"]),
+        "board_size_changed": d["board_size_mm"] is not None,
+        "identical": not (
+            p["added"]
+            or p["removed"]
+            or p["changed"]
+            or n["added"]
+            or n["removed"]
+            or n["rewired_pads"]
+            or d["stackup"]
+            or d["board_size_mm"]
+            or d["zones"]["added"]
+            or d["zones"]["removed"]
+            or r_old != r_new
+        ),
+    }
+
+
+def diff_files(old: str | Path, new: str | Path, move_tol: float = 0.05) -> dict[str, Any]:
+    return diff_boards(read_board(Path(old)), read_board(Path(new)), move_tol)
+
+
+def _row(*cells: object) -> str:
+    return "| " + " | ".join(str(c) for c in cells) + " |"
+
+
+def to_markdown(d: dict[str, Any], old_name: str = "old", new_name: str = "new") -> str:
+    s = d["summary"]
+    lines = [f"# Board changes: {old_name} to {new_name}", ""]
+    if s["identical"]:
+        return "\n".join([*lines, "No differences found.", ""])
+    lines += [
+        f"{s['parts_added']} parts added, {s['parts_removed']} removed, {s['parts_changed']} changed; "
+        f"{s['nets_added']} nets added, {s['nets_removed']} removed, {s['pads_rewired']} pads rewired; "
+        f"{s['vias_delta']:+d} vias, {s['track_length_delta_mm']:+.1f} mm of track.",
+        "",
+    ]
+    p = d["parts"]
+    if p["added"] or p["removed"]:
+        lines += [
+            "## Parts added and removed",
+            "",
+            _row("", "ref", "value", "footprint"),
+            _row("---", "---", "---", "---"),
+        ]
+        lines += [_row("added", x["ref"], x["value"], x["footprint"]) for x in p["added"]]
+        lines += [_row("removed", x["ref"], x["value"], x["footprint"]) for x in p["removed"]]
+        lines.append("")
+    if p["changed"]:
+        lines += ["## Parts changed", "", _row("ref", "what"), _row("---", "---")]
+        for c in p["changed"]:
+            what = ", ".join(
+                f"{k}: {v[0]} -> {v[1]}" if isinstance(v, list) else f"{k} {v} mm"
+                for k, v in c.items()
+                if k != "ref"
+            )
+            lines.append(_row(c["ref"], what))
+        lines.append("")
+    n = d["nets"]
+    if n["added"] or n["removed"] or n["rewired_pads"]:
+        lines += ["## Connectivity", ""]
+        if n["added"]:
+            lines.append("Nets added: " + ", ".join(n["added"]))
+        if n["removed"]:
+            lines.append("Nets removed: " + ", ".join(n["removed"]))
+        if n["rewired_pads"]:
+            lines += ["", _row("pad", "was", "now"), _row("---", "---", "---")]
+            lines += [_row(x["pad"], x["from"] or "-", x["to"] or "-") for x in n["rewired_pads"]]
+        lines.append("")
+    if d["stackup"] or d["board_size_mm"]:
+        lines += ["## Board", ""]
+        if d["stackup"].get("copper_layers"):
+            a, b = d["stackup"]["copper_layers"]
+            lines.append(f"Copper layers: {len(a)} -> {len(b)}")
+        if d["stackup"].get("thickness_mm"):
+            a, b = d["stackup"]["thickness_mm"]
+            lines.append(f"Thickness: {a} mm -> {b} mm")
+        if d["board_size_mm"]:
+            a, b = d["board_size_mm"]
+            lines.append(f"Size: {a[0]} x {a[1]} mm -> {b[0]} x {b[1]} mm")
+        lines.append("")
+    z = d["zones"]
+    if z["added"] or z["removed"]:
+        lines += ["## Zones", ""]
+        lines += [f"- added: {net} on {', '.join(layers)}" for net, layers in z["added"]]
+        lines += [f"- removed: {net} on {', '.join(layers)}" for net, layers in z["removed"]]
+        lines.append("")
+    ro, rn = d["routing"]["old"], d["routing"]["new"]
+    if ro != rn:
+        lines += ["## Routing", "", _row("", "old", "new"), _row("---", "---", "---")]
+        lines.append(_row("vias", ro["via_count"], rn["via_count"]))
+        lines.append(_row("track length (mm)", ro["total_length_mm"], rn["total_length_mm"]))
+        for layer in sorted(set(ro["layers"]) | set(rn["layers"])):
+            lo = ro["layers"].get(layer, {"tracks": 0, "length_mm": 0})
+            ln = rn["layers"].get(layer, {"tracks": 0, "length_mm": 0})
+            lines.append(_row(f"{layer} length (mm)", lo["length_mm"], ln["length_mm"]))
+        lines.append(_row("track widths (mm)", ro["track_widths_mm"], rn["track_widths_mm"]))
+        lines.append("")
+    return "\n".join(lines).rstrip() + "\n"