Programmatic Pre-Fab Design Review: Netlist-to-PCB Audit, DRC & Gerber Verification

def run_prefab_audit(bom_rows: list[dict]) -> list[tuple[str, str, str]]:
    """Run five automated pre-fabrication checks against the active SKiDL circuit."""
    circuit = builtins.default_circuit
    by_ref = {p.ref: p for p in circuit.parts}
    results = []

    # 1. Op-Amp MPN & Thermal Dissipation Check
    opamps = [by_ref[r] for r in ("U1", "U2", "U3")]
    all_tl074h = all(
        u.value == "TL074H" and u.fields.get("LCSC") == "C2878713" for u in opamps
    )
    supply_span_v = 2 * (12.0 - 0.38)  # +/-11.62V post-Schottky rails = 23.24V span
    pkg_mw = 5.6 * supply_span_v  # 5.6mA typ Iq per quad TL074H
    results.append(
        (
            "PASS" if all_tl074h else "FAIL",
            "Op-Amp Phase-Inversion & Thermal Audit",
            (
                f"U1-U3 = TL074HIDR (C2878713 CMOS, no JFET phase inversion), "
                f"Pd = {pkg_mw:.1f} mW/pkg ({3 * pkg_mw:.1f} mW total)"
            ),
        )
    )

    # 2. Reverse-Polarity Diode & Bulk Capacitor Polarity Check
    d1, d2 = by_ref["D1"], by_ref["D2"]
    c1, c2 = by_ref["C1"], by_ref["C2"]
    pol_ok = (
        d1["A"].net.name == "+12V_RAW"
        and d1["K"].net.name == "+12V"
        and d2["K"].net.name == "-12V_RAW"
        and d2["A"].net.name == "-12V"
        and c1.p[1].net.name == "+12V"
        and c1.p[2].net.name == "GND"
        and c2.p[1].net.name == "GND"
        and c2.p[2].net.name == "-12V"
    )
    results.append(
        (
            "PASS" if pol_ok else "FAIL",
            "Bipolar Rail & Capacitor Polarity Audit",
            "D1/D2 1N5819WS (+/-11.6V rails, +/-10.4V swing) & C2.1(+)->GND, C2.2(-)->-12V verified",
        )
    )

#!/usr/bin/env python3
"""
Lesson 0008: Programmatic Pre-Fab Design Review, Netlist-to-PCB Audit & DRC Checks.

Builds the 3-channel Eurorack Buffered Multiple netlist and JLCPCB SMT BOM, then runs
five automated pre-fabrication engineering audits modeled on DESIGN_REVIEW.md:
  1. Op-Amp MPN & Phase-Inversion Audit (TL074H / C2878713 + thermal budget)
  2. Schottky Reverse-Polarity & Bulk Cap Polarity / Headroom Audit
  3. Critical Pin Connectivity Audit (catching U1:5 open-circuit & C3-C8 GND islands)
  4. NetClass Trace Width & Clearance Audit (0.50 mm Power vs. 0.25 mm Signal)
  5. JLCPCB SMT BOM vs. Manual THT Partition Audit
"""

import builtins
import csv
import os
from pathlib import Path

# Keep generated .erc, .log, .net, .csv, and _sklib.py files inside this lesson's app directory
os.chdir(Path(__file__).resolve().parent)

# Configure writable cache directories and KiCad 10 library paths BEFORE importing skidl
os.environ.setdefault("XDG_DATA_HOME", "/tmp/xdg_data")
os.environ.setdefault("MPLCONFIGDIR", "/tmp/mpl_config")
if os.path.isdir("/Applications/KiCad/KiCad.app/Contents/SharedSupport/symbols"):
    os.environ.setdefault(
        "KICAD10_SYMBOL_DIR",
        "/Applications/KiCad/KiCad.app/Contents/SharedSupport/symbols",
    )
    os.environ.setdefault(
        "KICAD_SYMBOL_DIR",
        "/Applications/KiCad/KiCad.app/Contents/SharedSupport/symbols",
    )
if os.path.isdir("/Applications/KiCad/KiCad.app/Contents/SharedSupport/footprints"):
    os.environ.setdefault(
        "KICAD10_FOOTPRINT_DIR",
        "/Applications/KiCad/KiCad.app/Contents/SharedSupport/footprints",
    )

from skidl import (
    ERC,
    POWER,
    TEMPLATE,
    Net,
    NetClass,
    Part,
    generate_netlist,
    subcircuit,
)

# Footprints & Verified JLCPCB / LCSC Catalog Numbers
FP_OPAMP_SOIC14 = "Package_SO:SOIC-14_3.9x8.7mm_P1.27mm"
FP_R_0603 = "Resistor_SMD:R_0603_1608Metric"
FP_C_0603 = "Capacitor_SMD:C_0603_1608Metric"
FP_C_ELEC = "Capacitor_THT:CP_Radial_D5.0mm_P2.00mm"
FP_DIODE_SOD323 = "Diode_SMD:D_SOD-323"
FP_JACK_EURORACK = (
    "Connector_Audio:Jack_3.5mm_QingPu_WQP-PJ398SM_Vertical_CircularHoles"
)
FP_PWR_HEADER_10P = "Connector_IDC:IDC-Header_2x05_P2.54mm_Vertical"

LCSC_C_100NF_0603 = "C14663"
LCSC_R_100K_0603 = "C25803"
LCSC_R_1K_0603 = "C21190"
LCSC_R_470R_0603 = "C23179"
LCSC_D_1N5819WS_SOD323 = "C191023"
LCSC_D_TVS_PESD12VL1BA_SOD323 = "C38558"
LCSC_U_TL074H_SOIC14 = "C2878713"


@subcircuit
def eurorack_power(vcc, vee, gnd):
    """10-pin Eurorack power input with Schottky reverse-polarity protection."""
    j_pwr = Part(
        "Connector_Generic",
        "Conn_02x05_Odd_Even",
        value="EURORACK_PWR_10PIN",
        footprint=FP_PWR_HEADER_10P,
        tag="j_pwr",
    )
    j_pwr.fields["JLCPCB_Class"] = "Manual THT (DNP for SMT)"

    vcc_raw = Net("+12V_RAW")
    vee_raw = Net("-12V_RAW")

    vee_raw += j_pwr[1, 2]
    gnd += j_pwr[3, 4, 5, 6, 7, 8]
    vcc_raw += j_pwr[9, 10]

    d_t = Part(
        "Device",
        "D_Schottky",
        dest=TEMPLATE,
        value="1N5819WS",
        footprint=FP_DIODE_SOD323,
    )
    d_t.fields["LCSC"] = LCSC_D_1N5819WS_SOD323
    d_t.fields["MPN"] = "1N5819WS"
    d_t.fields["JLCPCB_Class"] = "Basic"
    d_pos, d_neg = d_t(2, tag="d_prot")

    vcc_raw += d_pos["A"]
    vcc += d_pos["K"]
    vee_raw += d_neg["K"]
    vee += d_neg["A"]

    c_bulk_t = Part(
        "Device",
        "C_Polarized",
        dest=TEMPLATE,
        value="10uF",
        footprint=FP_C_ELEC,
    )
    c_bulk_t.fields["MPN"] = "ECEA1EKS100"
    c_bulk_t.fields["JLCPCB_Class"] = "Manual THT (DNP for SMT)"
    c_bulk_pos, c_bulk_neg = c_bulk_t(2, tag="c_bulk")

    vcc += c_bulk_pos[1]
    gnd += c_bulk_pos[2]
    gnd += c_bulk_neg[1]
    vee += c_bulk_neg[2]


@subcircuit
def buffered_channel_1to3(vcc, vee, gnd, norm_in, buffered_tap_out, ch_num=1):
    """Single 1-to-3 buffered multiple channel built around one quad TL074H op-amp."""
    r_t = Part("Device", "R", dest=TEMPLATE, footprint=FP_R_0603)
    c_t = Part("Device", "C", dest=TEMPLATE, footprint=FP_C_0603)
    c_t.fields["LCSC"] = LCSC_C_100NF_0603
    c_t.fields["MPN"] = "CC0603KRX7R9BB104"
    c_t.fields["JLCPCB_Class"] = "Basic"

    jack_t = Part(
        "Connector_Audio",
        "AudioJack2_SwitchT",
        dest=TEMPLATE,
        footprint=FP_JACK_EURORACK,
    )
    jack_t.fields["MPN"] = "WQP-PJ398SM"
    jack_t.fields["JLCPCB_Class"] = "Manual THT (DNP for SMT)"

    u = Part(
        "Amplifier_Operational",
        "TL074",
        value="TL074H",
        footprint=FP_OPAMP_SOIC14,
        tag=f"u_ch{ch_num}",
    )
    u.fields["LCSC"] = LCSC_U_TL074H_SOIC14
    u.fields["MPN"] = "TL074HIDR"
    u.fields["JLCPCB_Class"] = "Extended"

    vcc += u["V+"]
    vee += u["V-"]

    c_dec_pos, c_dec_neg = c_t(2, value="100nF", tag=f"c_dec_ch{ch_num}")
    vcc & c_dec_pos & gnd
    gnd & c_dec_neg & vee

    j_in = jack_t(value=f"IN_{ch_num}", tag=f"j_in_ch{ch_num}")
    in_jack = Net(f"CH{ch_num}_JACK_IN")
    in_sig = Net(f"CH{ch_num}_IN")

    gnd += j_in["S"]
    norm_in += j_in["TN"]
    in_jack += j_in["T"]

    d_tvs = Part(
        "Device",
        "D_TVS",
        value="PESD12VL1BA",
        footprint=FP_DIODE_SOD323,
        tag=f"d_tvs_ch{ch_num}",
    )
    d_tvs.fields["LCSC"] = LCSC_D_TVS_PESD12VL1BA_SOD323
    d_tvs.fields["MPN"] = "PESD12VL1BA,115"
    d_tvs.fields["JLCPCB_Class"] = "Extended"
    in_jack & d_tvs & gnd

    r_pd = r_t(value="100K", tag=f"r_pd_ch{ch_num}")
    r_pd.fields["LCSC"] = LCSC_R_100K_0603
    r_pd.fields["MPN"] = "0603WAF1003T5E"
    r_pd.fields["JLCPCB_Class"] = "Basic"
    in_jack & r_pd & gnd

    r_in = r_t(value="1K", tag=f"r_in_ch{ch_num}")
    r_in.fields["LCSC"] = LCSC_R_1K_0603
    r_in.fields["MPN"] = "0603WAF1001T5E"
    r_in.fields["JLCPCB_Class"] = "Basic"
    in_jack & r_in & in_sig

    in_sig += u.p[3]
    buffered_tap_out += u.p[1], u.p[2]

    output_stages = [("A", 5, 6, 7), ("B", 10, 9, 8), ("C", 12, 13, 14)]

    for suffix, pin_pos, pin_neg, pin_out in output_stages:
        op_out = Net(f"CH{ch_num}_OP_{suffix}")
        jack_tip = Net(f"CH{ch_num}_OUT_{suffix}")

        buffered_tap_out += u.p[pin_pos]
        op_out += u.p[pin_out], u.p[pin_neg]

        r_out = r_t(value="470R", tag=f"r_out_ch{ch_num}_{suffix}")
        r_out.fields["LCSC"] = LCSC_R_470R_0603
        r_out.fields["MPN"] = "0603WAF4700T5E"
        r_out.fields["JLCPCB_Class"] = "Basic"
        op_out & r_out & jack_tip

        j_out = jack_t(value=f"OUT_{ch_num}{suffix}", tag=f"j_out_ch{ch_num}_{suffix}")
        jack_tip += j_out["T"]
        gnd += j_out["S"]
        j_out["TN"] += builtins.NC


def generate_jlcpcb_bom(file_: Path, include_tht: bool = False) -> list[dict]:
    """Export grouped JLCPCB SMT BOM CSV and return the exported row list."""
    groups = {}
    for part in builtins.default_circuit.parts:
        lcsc = part.fields.get("LCSC", "")
        jlc_class = part.fields.get("JLCPCB_Class", "")
        if not lcsc:
            continue
        if not include_tht and "THT" in jlc_class:
            continue

        comment = part.value_to_str()
        footprint = getattr(part, "footprint", "").split(":")[-1]
        key = (comment, footprint, lcsc)
        groups.setdefault(key, []).append(part.ref)

    rows = []
    with open(file_, "w", newline="", encoding="utf-8") as csvfile:
        writer = csv.writer(csvfile)
        writer.writerow(["Comment", "Designator", "Footprint", "LCSC Part #"])
        for (comment, footprint, lcsc), refs in groups.items():
            writer.writerow([comment, ", ".join(refs), footprint, lcsc])
            rows.append(
                {
                    "comment": comment,
                    "refs": refs,
                    "footprint": footprint,
                    "lcsc": lcsc,
                }
            )
    return rows


def run_prefab_audit(bom_rows: list[dict]) -> list[tuple[str, str, str]]:
    """Run five automated pre-fabrication checks against the active SKiDL circuit."""
    circuit = builtins.default_circuit
    by_ref = {p.ref: p for p in circuit.parts}
    results = []

    # 1. Op-Amp MPN & Thermal Dissipation Check
    opamps = [by_ref[r] for r in ("U1", "U2", "U3")]
    all_tl074h = all(
        u.value == "TL074H" and u.fields.get("LCSC") == "C2878713" for u in opamps
    )
    supply_span_v = 2 * (12.0 - 0.38)  # +/-11.62V post-Schottky rails = 23.24V span
    pkg_mw = 5.6 * supply_span_v  # 5.6mA typ Iq per quad TL074H
    results.append(
        (
            "PASS" if all_tl074h else "FAIL",
            "Op-Amp Phase-Inversion & Thermal Audit",
            (
                f"U1-U3 = TL074HIDR (C2878713 CMOS, no JFET phase inversion), "
                f"Pd = {pkg_mw:.1f} mW/pkg ({3 * pkg_mw:.1f} mW total)"
            ),
        )
    )

    # 2. Reverse-Polarity Diode & Bulk Capacitor Polarity Check
    d1, d2 = by_ref["D1"], by_ref["D2"]
    c1, c2 = by_ref["C1"], by_ref["C2"]
    pol_ok = (
        d1["A"].net.name == "+12V_RAW"
        and d1["K"].net.name == "+12V"
        and d2["K"].net.name == "-12V_RAW"
        and d2["A"].net.name == "-12V"
        and c1.p[1].net.name == "+12V"
        and c1.p[2].net.name == "GND"
        and c2.p[1].net.name == "GND"
        and c2.p[2].net.name == "-12V"
    )
    results.append(
        (
            "PASS" if pol_ok else "FAIL",
            "Bipolar Rail & Capacitor Polarity Audit",
            "D1/D2 1N5819WS (+/-11.6V rails, +/-10.4V swing) & C2.1(+)->GND, C2.2(-)->-12V verified",
        )
    )

    # 3. Critical Pin Connectivity Check (catching U1:5 open-circuit & C3-C8 GND islands)
    follower_pins_ok = all(
        by_ref[f"U{ch}"].p[pin].net.name == f"CH{ch}_BUF"
        for ch in (1, 2, 3)
        for pin in (1, 2, 5, 10, 12)
    )
    dec_gnd_ok = all(
        "GND" in (by_ref[f"C{n}"].p[1].net.name, by_ref[f"C{n}"].p[2].net.name)
        for n in range(3, 9)
    )
    results.append(
        (
            "PASS" if (follower_pins_ok and dec_gnd_ok) else "FAIL",
            "Follower Input & Decoupling GND Audit",
            "All 15 follower pins (U1..U3 pins 1,2,5,10,12) & all 6 decoupling GND pads (C3..C8) wired",
        )
    )

    # 4. NetClass Trace Width & Clearance Check
    vcc_net = by_ref["U1"]["V+"].net
    ch1_net = by_ref["U1"].p[1].net
    nc_ok = "Power" in vcc_net.netclasses and "Signal" in ch1_net.netclasses
    results.append(
        (
            "PASS" if nc_ok else "FAIL",
            "KiCad NetClass Routing Rule Audit",
            "Power rails = 0.50 mm width / 0.25 mm clearance; Signal nets = 0.25 mm width / 0.20 mm clearance",
        )
    )

    # 5. JLCPCB SMT BOM Partition Check
    smt_count = sum(len(r["refs"]) for r in bom_rows)
    has_tht = any(
        ref.startswith("J") or ref in ("C1", "C2")
        for r in bom_rows
        for ref in r["refs"]
    )
    bom_ok = smt_count == 29 and len(bom_rows) == 7 and not has_tht
    results.append(
        (
            "PASS" if bom_ok else "FAIL",
            "JLCPCB Single-Sided SMT BOM Audit",
            f"{smt_count} SMD parts across {len(bom_rows)} grouped lines; 0 THT parts in SMT CSV",
        )
    )

    return results


def main():
    vcc = Net("+12V")
    vee = Net("-12V")
    gnd = Net("GND")
    for rail in (vcc, vee, gnd):
        rail.drive = POWER

    pwr_class = NetClass("Power", priority=1, trace_width=0.5, clearance=0.25)
    sig_class = NetClass("Signal", priority=2, trace_width=0.25, clearance=0.2)
    for rail in (vcc, vee, gnd):
        rail.netclasses = pwr_class

    ch1_buf = Net("CH1_BUF")
    ch2_buf = Net("CH2_BUF")
    ch3_buf = Net("CH3_BUF")
    for buf_net in (ch1_buf, ch2_buf, ch3_buf):
        buf_net.netclasses = sig_class

    eurorack_power(vcc, vee, gnd, tag="pwr")
    buffered_channel_1to3(vcc, vee, gnd, gnd, ch1_buf, ch_num=1, tag="ch1")
    buffered_channel_1to3(vcc, vee, gnd, ch1_buf, ch2_buf, ch_num=2, tag="ch2")
    buffered_channel_1to3(vcc, vee, gnd, ch2_buf, ch3_buf, ch_num=3, tag="ch3")

    ERC()

    generate_netlist(file_="buffered_multiple.net")
    bom_rows = generate_jlcpcb_bom(
        file_=Path("buffered_multiple_jlcpcb_bom.csv"), include_tht=False
    )

    checks = run_prefab_audit(bom_rows)
    print("=== Lesson 0008: Automated Pre-Fabrication Design Review ===")
    for status, title, detail in checks:
        print(f"  [{status}] {title:<38} : {detail}")

    passed = sum(1 for s, _, _ in checks if s == "PASS")
    print(f"\n  Verdict: {passed}/{len(checks)} Pre-Fab Checks Passed (READY FOR FAB)")


if __name__ == "__main__":
    main()

.venv/bin/python tutorial/apps/0008-prefab-design-review-and-drc/prefab_design_audit.py
ruff check --fix tutorial/apps/0008-prefab-design-review-and-drc/*.py
ruff format tutorial/apps/0008-prefab-design-review-and-drc/*.py

ERC INFO: No errors or warnings found while running ERC.

=== Lesson 0008: Automated Pre-Fabrication Design Review ===
  [PASS] Op-Amp Phase-Inversion & Thermal Audit : U1-U3 = TL074HIDR (C2878713 CMOS, no JFET phase inversion), Pd = 130.1 mW/pkg (390.4 mW total)
  [PASS] Bipolar Rail & Capacitor Polarity Audit : D1/D2 1N5819WS (+/-11.6V rails, +/-10.4V swing) & C2.1(+)->GND, C2.2(-)->-12V verified
  [PASS] Follower Input & Decoupling GND Audit  : All 15 follower pins (U1..U3 pins 1,2,5,10,12) & all 6 decoupling GND pads (C3..C8) wired
  [PASS] KiCad NetClass Routing Rule Audit      : Power rails = 0.50 mm width / 0.25 mm clearance; Signal nets = 0.25 mm width / 0.20 mm clearance
  [PASS] JLCPCB Single-Sided SMT BOM Audit      : 29 SMD parts across 7 grouped lines; 0 THT parts in SMT CSV

  Verdict: 5/5 Pre-Fab Checks Passed (READY FOR FAB)