traceforge-pcb 1.0.0__py3-none-any.whl

traceforge/features/sarif.py

@@ -0,0 +1,145 @@
+"""Findings as SARIF 2.1.0, the format code-scanning and review bots read.
+
+Feeds: the result of ``traceforge check`` (built-in findings plus KiCad ERC and DRC violations), the
+JSON of ``traceforge validate`` (one entry per finding of each check), or a plain list of finding
+dicts. A finding has no line number (boards are not text lines), so each result carries the file it is
+about plus logical locations for the parts and nets it names.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from pathlib import Path
+from typing import Any
+
+SARIF_SCHEMA = "https://json.schemastore.org/sarif-2.1.0.json"
+LEVELS = {"P0": "error", "P1": "warning", "P2": "note", "P3": "note"}
+KICAD_LEVELS = {"error": "error", "warning": "warning", "exclusion": "none"}
+
+
+def _norm_builtin(f: dict, source: str) -> dict[str, Any]:
+    return {
+        "rule": f.get("check") or f.get("id") or "traceforge.finding",
+        "level": LEVELS.get(str(f.get("severity")), "warning"),
+        "severity": f.get("severity", ""),
+        "message": f.get("message", ""),
+        "evidence": f.get("evidence", ""),
+        "action": f.get("action", ""),
+        "standard": f.get("rule", ""),
+        "refs": list(f.get("refs") or []),
+        "nets": list(f.get("nets") or []),
+        "source": source,
+    }
+
+
+def normalize(data: dict | list) -> list[dict[str, Any]]:
+    """Any of the supported inputs as one flat list of finding records."""
+    if isinstance(data, list):
+        return [_norm_builtin(f, f.get("source", "")) for f in data if isinstance(f, dict)]
+    out: list[dict[str, Any]] = []
+    if "results" in data and isinstance(data["results"], list):  # validate report
+        for r in data["results"]:
+            for f in r.get("findings") or []:
+                out.append(
+                    _norm_builtin({**f, "check": f.get("id") or r.get("id")}, r.get("stage", ""))
+                )
+        return out
+    for section, body in data.items():
+        if not isinstance(body, dict):
+            continue
+        for f in (body.get("builtin") or {}).get("findings") or []:
+            out.append(_norm_builtin(f, section))
+        for key in ("kicad_erc", "kicad_drc"):
+            kicad = body.get(key)
+            if not isinstance(kicad, dict):
+                continue
+            tool = key.removeprefix("kicad_")
+            for v in kicad.get("violations") or []:
+                if v.get("excluded"):
+                    continue
+                out.append(
+                    {
+                        "rule": f"kicad.{tool}.{v.get('type', 'violation')}",
+                        "level": KICAD_LEVELS.get(str(v.get("severity")), "warning"),
+                        "severity": str(v.get("severity", "")),
+                        "message": v.get("description", ""),
+                        "evidence": "; ".join(str(i) for i in v.get("items") or []),
+                        "action": "",
+                        "standard": "",
+                        "refs": [],
+                        "nets": [],
+                        "source": f"{section}.{tool}",
+                    }
+                )
+    return out
+
+
+def _uri(source: str, files: dict[str, str]) -> str | None:
+    head = source.split(".")[0]
+    if head in ("erc", "layout", "schematic", "sch"):
+        return files.get("schematic")
+    if head in ("drc", "pcb"):
+        return files.get("pcb")
+    return files.get("pcb") or files.get("schematic")
+
+
+def to_sarif(
+    data: dict | list,
+    files: dict[str, str | Path] | None = None,
+    version: str = "",
+) -> dict[str, Any]:
+    """The SARIF log. ``files`` maps ``schematic`` and ``pcb`` to repository-relative paths."""
+    paths = {k: Path(v).as_posix() for k, v in (files or {}).items() if v}
+    records = normalize(data)
+    rules: dict[str, dict[str, Any]] = {}
+    results = []
+    for r in records:
+        rid = r["rule"]
+        if rid not in rules:
+            rule: dict[str, Any] = {
+                "id": rid,
+                "shortDescription": {"text": rid},
+                "defaultConfiguration": {"level": r["level"]},
+            }
+            if r["standard"]:
+                rule["fullDescription"] = {"text": r["standard"]}
+            rules[rid] = rule
+        text = r["message"]
+        if r["evidence"]:
+            text += f"\nEvidence: {r['evidence']}"
+        if r["action"]:
+            text += f"\nFix: {r['action']}"
+        location: dict[str, Any] = {}
+        uri = _uri(r["source"], paths)
+        if uri:
+            location["physicalLocation"] = {"artifactLocation": {"uri": uri}}
+        logical = [{"name": n, "kind": "member"} for n in r["refs"]] + [
+            {"name": n, "kind": "variable"} for n in r["nets"]
+        ]
+        if logical:
+            location["logicalLocations"] = logical
+        fingerprint = hashlib.sha256(
+            "|".join([rid, r["message"], ",".join(r["refs"]), ",".join(r["nets"])]).encode()
+        ).hexdigest()[:32]
+        results.append(
+            {
+                "ruleId": rid,
+                "level": r["level"],
+                "message": {"text": text},
+                "locations": [location] if location else [],
+                "partialFingerprints": {"traceforge/v1": fingerprint},
+                "properties": {"severity": r["severity"], "source": r["source"]},
+            }
+        )
+    driver: dict[str, Any] = {
+        "name": "traceforge",
+        "informationUri": "https://github.com/ashutosh-rath02/traceforge",
+        "rules": list(rules.values()),
+    }
+    if version:
+        driver["version"] = version
+    return {
+        "$schema": SARIF_SCHEMA,
+        "version": "2.1.0",
+        "runs": [{"tool": {"driver": driver}, "results": results}],
+    }

traceforge/features/viewer.py

@@ -0,0 +1,265 @@
+"""One self-contained HTML file to inspect a board without KiCad: layers, nets, BOM and findings.
+
+The page has no external requests: the board is embedded as JSON and drawn on a canvas. Pan with the
+mouse, zoom with the wheel, click a pad, track or via to select its net, click a BOM row or a finding to
+highlight its parts. ``traceforge view`` writes it; the findings are optional.
+"""
+
+from __future__ import annotations
+
+import json
+from collections import defaultdict
+from pathlib import Path
+from typing import Any
+
+from traceforge.kicad.pcb import Board, read_board
+
+COLORS = {
+    "F.Cu": "#c83434",
+    "B.Cu": "#4d7fc4",
+    "In1.Cu": "#c2c200",
+    "In2.Cu": "#c27d00",
+    "In3.Cu": "#00c2c2",
+    "In4.Cu": "#9a4dc4",
+    "In5.Cu": "#4dc47f",
+    "In6.Cu": "#c24d9a",
+}
+
+
+def _num(value: float) -> float:
+    return round(float(value), 3)
+
+
+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 board_data(board: Board, findings: list[dict] | None = None) -> dict[str, Any]:
+    """The board as plain JSON-able data for the page."""
+    outline = list(board.edge_segments or [])
+    if not outline and board.outline:
+        x0, y0, x1, y1 = board.outline
+        outline = [(x0, y0, x1, y0), (x1, y0, x1, y1), (x1, y1, x0, y1), (x0, y1, x0, y0)]
+    tracks: dict[str, list[list[Any]]] = defaultdict(list)
+    length: dict[str, float] = defaultdict(float)
+    for t in board.tracks:
+        if t.mid is not None:
+            mid = t.mid
+            pieces = [(t.x1, t.y1, mid[0], mid[1]), (mid[0], mid[1], t.x2, t.y2)]
+        else:
+            pieces = [(t.x1, t.y1, t.x2, t.y2)]
+        for a, b, c, d in pieces:
+            tracks[t.layer].append([_num(a), _num(b), _num(c), _num(d), _num(t.width), t.net])
+        length[t.net] += t.length
+    vias_per_net: dict[str, int] = defaultdict(int)
+    for v in board.vias:
+        vias_per_net[v.net] += 1
+    pads_per_net: dict[str, int] = defaultdict(int)
+    pads = []
+    parts = []
+    bom: dict[tuple[str, str], list[str]] = defaultdict(list)
+    for fp in board.footprints:
+        if fp.reference.startswith("#"):
+            continue
+        parts.append(
+            {
+                "ref": fp.reference,
+                "value": fp.value,
+                "lib": fp.lib_id,
+                "x": _num(fp.x),
+                "y": _num(fp.y),
+                "angle": _num(fp.angle),
+                "layer": fp.layer,
+                "dnp": fp.dnp,
+                "court": [_num(c) for c in fp.courtyard] if fp.courtyard else None,
+            }
+        )
+        if not ({"exclude_from_bom", "board_only"} & set(fp.attrs)):
+            bom[(fp.value, fp.lib_id.split(":")[-1])].append(fp.reference)
+        for pad in fp.pads:
+            pads_per_net[pad.net] += 1
+            pads.append(
+                [
+                    _num(pad.x),
+                    _num(pad.y),
+                    _num(pad.width),
+                    _num(pad.height),
+                    pad.shape,
+                    pad.layers,
+                    pad.net,
+                    fp.reference,
+                    pad.number,
+                    _num(pad.drill),
+                ]
+            )
+    nets = sorted(
+        {n for n in [*length, *vias_per_net, *pads_per_net] if n},
+        key=lambda n: (n.startswith("unconnected"), n),
+    )
+    bom_rows = [
+        {"value": v, "footprint": f, "qty": len(refs), "refs": sorted(refs, key=_ref_key)}
+        for (v, f), refs in sorted(bom.items(), key=lambda kv: _ref_key(kv[1][0]))
+    ]
+    size = board.size_mm
+    return {
+        "name": board.path.stem,
+        "layers": board.copper_layers,
+        "colors": {n: COLORS.get(n, "#888888") for n in board.copper_layers},
+        "outline": [[_num(v) for v in seg] for seg in outline],
+        "tracks": tracks,
+        "vias": [[_num(v.x), _num(v.y), _num(v.size), _num(v.drill), v.net] for v in board.vias],
+        "pads": pads,
+        "parts": parts,
+        "bom": bom_rows,
+        "nets": [
+            {
+                "name": n,
+                "length": round(length.get(n, 0.0), 2),
+                "vias": vias_per_net.get(n, 0),
+                "pads": pads_per_net.get(n, 0),
+            }
+            for n in nets
+        ],
+        "zones": [
+            {"net": z["net"], "layers": z["layers"], "filled": z["filled"]} for z in board.zones
+        ],
+        "size": [round(size[0], 2), round(size[1], 2)] if size else None,
+        "findings": findings or [],
+        "checked": findings is not None,
+    }
+
+
+def findings_from_checks(data: dict | list) -> list[dict]:
+    """Flatten the ``traceforge check`` result (or a list of finding dicts) into one list."""
+    if isinstance(data, list):
+        return [dict(f) for f in data]
+    out: list[dict] = []
+    for section, body in data.items():
+        if not isinstance(body, dict):
+            continue
+        found = (body.get("builtin") or {}).get("findings") or body.get("findings") or []
+        for f in found:
+            if isinstance(f, dict):
+                out.append({**f, "source": section})
+    return out
+
+
+def _escape(text: str) -> str:
+    return text.replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;")
+
+
+def render_html(data: dict[str, Any]) -> str:
+    payload = json.dumps(data, separators=(",", ":")).replace("</", "<\\/")
+    return _PAGE.replace("__TITLE__", _escape(data["name"])).replace("__DATA__", payload)
+
+
+def write_viewer(
+    pcb: str | Path, out: str | Path, findings: list[dict] | dict | None = None
+) -> Path:
+    """Write the viewer for ``pcb`` to ``out`` and return the path."""
+    board = read_board(Path(pcb))
+    data = board_data(board, findings_from_checks(findings) if findings is not None else None)
+    out = Path(out)
+    out.parent.mkdir(parents=True, exist_ok=True)
+    out.write_text(render_html(data), encoding="utf-8")
+    return out
+
+
+_PAGE = """<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>__TITLE__ - board viewer</title>
+<style>
+:root{--bg:#10141a;--panel:#171d26;--ink:#dbe2ea;--mute:#8b97a6;--line:#2a3340;--acc:#5aa9ff}
+@media (prefers-color-scheme: light){:root{--bg:#eef1f5;--panel:#fff;--ink:#1d2733;--mute:#5d6b7a;--line:#d5dbe3;--acc:#1668c9}}
+*{box-sizing:border-box}body{margin:0;height:100vh;display:flex;background:var(--bg);color:var(--ink);font:13px system-ui,sans-serif}
+#view{flex:1;position:relative;min-width:0}canvas{width:100%;height:100%;display:block;cursor:grab}
+#side{width:340px;max-width:45vw;background:var(--panel);border-left:1px solid var(--line);display:flex;flex-direction:column}
+#bar{padding:8px 10px;border-bottom:1px solid var(--line);display:flex;gap:10px;flex-wrap:wrap;align-items:center}
+#bar label{display:inline-flex;align-items:center;gap:4px;cursor:pointer}
+.sw{width:10px;height:10px;border-radius:2px;display:inline-block}
+#tabs{display:flex;border-bottom:1px solid var(--line)}#tabs button{flex:1;padding:8px;border:0;background:none;color:var(--mute);cursor:pointer;font:inherit}
+#tabs button.on{color:var(--ink);border-bottom:2px solid var(--acc)}
+#list{flex:1;overflow:auto}#q{margin:8px;width:calc(100% - 16px);padding:6px;border:1px solid var(--line);background:var(--bg);color:var(--ink);border-radius:4px}
+.row{padding:6px 10px;border-bottom:1px solid var(--line);cursor:pointer}.row:hover,.row.on{background:rgba(90,169,255,.14)}
+.row small{color:var(--mute);display:block}.sev{font-weight:600}.P0{color:#e5484d}.P1{color:#f08c00}.P2{color:#c9a400}.P3{color:var(--mute)}
+#info{position:absolute;left:10px;bottom:10px;background:var(--panel);border:1px solid var(--line);padding:6px 10px;border-radius:6px;max-width:60%}
+@media (max-width:700px){body{flex-direction:column}#side{width:100%;max-width:none;height:45vh}}
+</style></head><body>
+<div id="view"><canvas id="c"></canvas><div id="info">Click a pad, track or via. Wheel zooms, drag pans.</div></div>
+<div id="side"><div id="bar"></div>
+<div id="tabs"><button data-t="bom" class="on">BOM</button><button data-t="nets">Nets</button><button data-t="find">Findings</button></div>
+<input id="q" placeholder="filter"><div id="list"></div></div>
+<script id="data" type="application/json">__DATA__</script>
+<script>
+const D=JSON.parse(document.getElementById('data').textContent);
+const cv=document.getElementById('c'),ctx=cv.getContext('2d');
+const vis={};D.layers.forEach(l=>vis[l]=true);vis.pads=true;vis.vias=true;vis.silk=true;
+let flip=false,sel={net:null,refs:new Set()},tab='bom',view={s:1,x:0,y:0};
+const xs=D.outline.flatMap(s=>[s[0],s[2]]),ys=D.outline.flatMap(s=>[s[1],s[3]]);
+const bb=D.outline.length?[Math.min(...xs),Math.min(...ys),Math.max(...xs),Math.max(...ys)]:[0,0,100,80];
+function fit(){const r=cv.getBoundingClientRect(),k=window.devicePixelRatio||1;cv.width=r.width*k;cv.height=r.height*k;
+ const w=bb[2]-bb[0]||1,h=bb[3]-bb[1]||1;view.s=Math.min(cv.width/(w*1.1),cv.height/(h*1.1));
+ view.x=(cv.width-w*view.s)/2-bb[0]*view.s;view.y=(cv.height-h*view.s)/2-bb[1]*view.s;draw()}
+const P=(x,y)=>[(flip?(bb[0]+bb[2]-x):x)*view.s+view.x,y*view.s+view.y];
+const W=(mm)=>Math.max(1,mm*view.s);
+const dim=()=>sel.net||sel.refs.size;
+function net(n){return sel.net&&n===sel.net}
+function line(a,b,c,d,w,col){const p=P(a,b),q=P(c,d);ctx.strokeStyle=col;ctx.lineWidth=W(w);ctx.lineCap='round';ctx.beginPath();ctx.moveTo(p[0],p[1]);ctx.lineTo(q[0],q[1]);ctx.stroke()}
+function draw(){ctx.clearRect(0,0,cv.width,cv.height);
+ ctx.globalAlpha=1;D.outline.forEach(s=>line(s[0],s[1],s[2],s[3],.15,'#d8c84a'));
+ const order=[...D.layers].reverse();if(flip)order.reverse();
+ order.forEach(l=>{if(!vis[l])return;const col=D.colors[l];(D.tracks[l]||[]).forEach(t=>{
+  ctx.globalAlpha=dim()&&!net(t[5])?.25:1;line(t[0],t[1],t[2],t[3],t[4],net(t[5])?'#fff':col)})});
+ ctx.globalAlpha=1;
+ if(vis.pads)D.pads.forEach(p=>{const top=p[5].some(n=>n==='F.Cu'||n==='*.Cu'||n==='F&B.Cu'),bot=p[5].some(n=>n==='B.Cu'||n==='*.Cu'||n==='F&B.Cu');
+  if(!((top&&vis['F.Cu'])||(bot&&vis['B.Cu'])||p[9]>0))return;
+  const hot=net(p[6])||sel.refs.has(p[7]);ctx.globalAlpha=dim()&&!hot?.3:1;
+  ctx.fillStyle=hot?'#fff':(top?D.colors['F.Cu']:D.colors['B.Cu'])||'#c83434';
+  const c=P(p[0],p[1]),w=W(p[2]),h=W(p[3]);ctx.beginPath();
+  if(p[4]==='circle'||p[4]==='oval'){ctx.ellipse(c[0],c[1],w/2,h/2,0,0,7);}else{ctx.rect(c[0]-w/2,c[1]-h/2,w,h)}
+  ctx.fill();if(p[9]>0){ctx.fillStyle='#10141a';ctx.beginPath();ctx.arc(c[0],c[1],W(p[9])/2,0,7);ctx.fill()}});
+ ctx.globalAlpha=1;
+ if(vis.vias)D.vias.forEach(v=>{const c=P(v[0],v[1]);ctx.globalAlpha=dim()&&!net(v[4])?.3:1;ctx.fillStyle=net(v[4])?'#fff':'#9aa5b1';
+  ctx.beginPath();ctx.arc(c[0],c[1],W(v[2])/2,0,7);ctx.fill();ctx.fillStyle='#10141a';ctx.beginPath();ctx.arc(c[0],c[1],W(v[3])/2,0,7);ctx.fill()});
+ ctx.globalAlpha=1;
+ D.parts.forEach(p=>{if(!sel.refs.has(p.ref)||!p.court)return;const a=P(p.court[0],p.court[1]),b=P(p.court[2],p.court[3]);
+  ctx.strokeStyle='#5aa9ff';ctx.lineWidth=2;ctx.strokeRect(Math.min(a[0],b[0]),Math.min(a[1],b[1]),Math.abs(b[0]-a[0]),Math.abs(b[1]-a[1]))});
+ if(vis.silk&&view.s>6)D.parts.forEach(p=>{const c=P(p.x,p.y);ctx.fillStyle='#e6e6e6';ctx.font=Math.max(8,view.s*.9)+'px sans-serif';ctx.textAlign='center';ctx.fillText(p.ref,c[0],c[1])})}
+function toMM(ev){const r=cv.getBoundingClientRect(),k=cv.width/r.width;const px=(ev.clientX-r.left)*k,py=(ev.clientY-r.top)*k;
+ let x=(px-view.x)/view.s;if(flip)x=bb[0]+bb[2]-x;return[x,(py-view.y)/view.s]}
+function pick(ev){const[x,y]=toMM(ev);const tol=6/view.s;
+ for(const p of D.pads){if(Math.abs(p[0]-x)<=p[2]/2+tol/3&&Math.abs(p[1]-y)<=p[3]/2+tol/3)return{net:p[6],ref:p[7],what:'pad '+p[7]+'.'+p[8]}}
+ for(const v of D.vias){if(Math.hypot(v[0]-x,v[1]-y)<=v[2]/2+tol/3)return{net:v[4],what:'via'}}
+ for(const l of D.layers){if(!vis[l])continue;for(const t of D.tracks[l]||[]){const dx=t[2]-t[0],dy=t[3]-t[1],L=dx*dx+dy*dy||1e-9;
+  let u=((x-t[0])*dx+(y-t[1])*dy)/L;u=Math.max(0,Math.min(1,u));if(Math.hypot(t[0]+u*dx-x,t[1]+u*dy-y)<=t[4]/2+tol/3)return{net:t[5],what:'track on '+l}}}return null}
+function setSel(net,refs,text){sel.net=net||null;sel.refs=new Set(refs||[]);document.getElementById('info').textContent=text||'Click a pad, track or via.';draw();list()}
+let drag=null,moved=false;
+cv.onmousedown=e=>{drag=[e.clientX,e.clientY,view.x,view.y];moved=false;cv.style.cursor='grabbing'};
+window.onmouseup=e=>{cv.style.cursor='grab';if(drag&&!moved){const h=pick(e);if(h){const n=D.nets.find(n=>n.name===h.net);
+  setSel(h.net,h.ref?[h.ref]:[],h.what+' - net '+(h.net||'(none)')+(n?' - '+n.length+' mm, '+n.vias+' vias, '+n.pads+' pads':''))}else setSel(null,[],'')}drag=null};
+window.onmousemove=e=>{if(!drag)return;const k=cv.width/cv.getBoundingClientRect().width;
+ if(Math.abs(e.clientX-drag[0])+Math.abs(e.clientY-drag[1])>3)moved=true;view.x=drag[2]+(e.clientX-drag[0])*k;view.y=drag[3]+(e.clientY-drag[1])*k;draw()};
+cv.onwheel=e=>{e.preventDefault();const r=cv.getBoundingClientRect(),k=cv.width/r.width,px=(e.clientX-r.left)*k,py=(e.clientY-r.top)*k,f=e.deltaY<0?1.15:1/1.15;
+ view.x=px-(px-view.x)*f;view.y=py-(py-view.y)*f;view.s*=f;draw()};
+window.onresize=fit;
+const bar=document.getElementById('bar');
+function chk(name,key,col){const l=document.createElement('label');const i=document.createElement('input');i.type='checkbox';i.checked=true;
+ i.onchange=()=>{vis[key]=i.checked;draw()};const s=document.createElement('span');s.className='sw';s.style.background=col||'#999';
+ l.append(i,s,document.createTextNode(name));bar.append(l)}
+D.layers.forEach(l=>chk(l,l,D.colors[l]));chk('pads','pads');chk('vias','vias');chk('labels','silk');
+const fb=document.createElement('button');fb.textContent='flip';fb.onclick=()=>{flip=!flip;draw()};bar.append(fb);
+document.querySelectorAll('#tabs button').forEach(b=>b.onclick=()=>{tab=b.dataset.t;document.querySelectorAll('#tabs button').forEach(x=>x.classList.toggle('on',x===b));list()});
+document.getElementById('q').oninput=()=>list();
+function list(){const q=document.getElementById('q').value.toLowerCase(),el=document.getElementById('list');el.textContent='';
+ const add=(title,sub,on,fn,cls)=>{const d=document.createElement('div');d.className='row'+(on?' on':'');const t=document.createElement('div');
+  t.textContent=title;if(cls)t.className=cls;d.append(t);if(sub){const s=document.createElement('small');s.textContent=sub;d.append(s)}d.onclick=fn;el.append(d)};
+ if(tab==='bom')D.bom.filter(r=>(r.value+r.footprint+r.refs.join(' ')).toLowerCase().includes(q)).forEach(r=>add(r.qty+' x '+(r.value||'(no value)'),r.footprint+' - '+r.refs.join(', '),r.refs.some(x=>sel.refs.has(x)),()=>setSel(null,r.refs,r.refs.join(', '))));
+ if(tab==='nets')D.nets.filter(n=>n.name.toLowerCase().includes(q)).forEach(n=>add(n.name,n.length+' mm, '+n.vias+' vias, '+n.pads+' pads',sel.net===n.name,()=>setSel(n.name,[],'net '+n.name)));
+ if(tab==='find'){if(!D.findings.length){add(D.checked?'No findings':'Checks were not run','Run: traceforge view --check',false,()=>{})}
+  D.findings.filter(f=>JSON.stringify(f).toLowerCase().includes(q)).forEach(f=>add((f.severity||'')+' '+(f.message||f.check||''),(f.check||'')+(f.action?' - '+f.action:''),false,
+   ()=>setSel((f.nets||[])[0],f.refs||[],f.message||''),'sev '+(f.severity||'')))}}
+fit();list();
+</script></body></html>
+"""

traceforge/firmware/__init__.py

@@ -0,0 +1,3 @@
+"""Firmware that matches the hardware: pin maps, scaffolds, driver snippets, toolchains."""
+
+from __future__ import annotations

traceforge/firmware/cli.py

@@ -0,0 +1,174 @@
+"""``traceforge firmware pins|scaffold|driver|build|tools``."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from rich.console import Console
+
+from traceforge.firmware.drivers import generate_driver, supported_parts
+from traceforge.firmware.netlist import NetlistError, load_netlist
+from traceforge.firmware.pinmap import HEADER_FILES, build_pinmap, render_header
+from traceforge.firmware.scaffold import TARGETS, ScaffoldError, scaffold
+from traceforge.firmware.toolchain import (
+    INSTALL_GUIDANCE,
+    compile_project,
+    detect_tools,
+    flash_command,
+    flash_project,
+    size_project,
+)
+
+console = Console(highlight=False)
+err = Console(stderr=True, highlight=False)
+
+
+def add_firmware_parser(sub: argparse._SubParsersAction) -> None:
+    fw = sub.add_parser("firmware", help="pin map, scaffolds, drivers and builds for the board")
+    fsub = fw.add_subparsers(dest="firmware_command", required=True)
+
+    def design_args(p: argparse.ArgumentParser) -> None:
+        p.add_argument("design", help="design spec (.yaml), .kicad_sch or KiCad .net")
+        p.add_argument("--ref", help="MCU reference (auto-detected)")
+        p.add_argument("--mcu", help="attiny85 | esp32s3 | stm32f103 (auto-detected)")
+
+    pins = fsub.add_parser("pins", help="map netlist signals to MCU pins; write pin headers")
+    design_args(pins)
+    pins.add_argument("--style", choices=list(HEADER_FILES), help="header to write or print")
+    pins.add_argument("--out", help="write the header into this folder (default: print)")
+    pins.add_argument("--json", action="store_true")
+
+    sc = fsub.add_parser("scaffold", help="write a firmware project")
+    design_args(sc)
+    sc.add_argument("--target", choices=list(TARGETS))
+    sc.add_argument("--out", default="firmware")
+    sc.add_argument("--name")
+    sc.add_argument("--driver", action="append", default=[], help="part to include (repeatable)")
+    sc.add_argument("--overwrite", action="store_true")
+
+    dr = fsub.add_parser("driver", help="generate a driver for a common I2C/SPI part")
+    dr.add_argument("part", nargs="?", help=", ".join(supported_parts()))
+    dr.add_argument("--address", type=lambda v: int(v, 0), help="7-bit address override")
+    dr.add_argument("--out", help="write the files here (default: print)")
+
+    b = fsub.add_parser("build", help="compile, size or flash a firmware project")
+    b.add_argument("project", nargs="?", default=".")
+    b.add_argument("--size", action="store_true", help="report flash/RAM use only")
+    b.add_argument("--flash", action="store_true", help="flash after building")
+    b.add_argument("--port", help="serial port for flashing")
+    b.add_argument("-y", "--yes", action="store_true", help="approve flashing without asking")
+    b.add_argument("--json", action="store_true")
+
+    fsub.add_parser("tools", help="which firmware tools are installed, with install guidance")
+
+
+def run_firmware(args: argparse.Namespace) -> int:
+    try:
+        return _COMMANDS[args.firmware_command](args)
+    except (NetlistError, ScaffoldError, KeyError, ValueError) as exc:
+        err.print(f"[red]error:[/] {exc.args[0] if isinstance(exc, KeyError) else exc}")
+        return 1
+
+
+def _pins(args: argparse.Namespace) -> int:
+    pm = build_pinmap(load_netlist(args.design), args.ref, args.mcu)
+    if args.json:
+        print(json.dumps(pm.as_dict(), indent=1))
+        return 0
+    if args.style:
+        text = render_header(pm, args.style, args.design)
+        if args.out:
+            path = Path(args.out) / HEADER_FILES[args.style]
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_text(text, encoding="utf-8")
+            console.print(f"wrote {path}")
+        else:
+            sys.stdout.write(text)
+        return 0
+    console.print(f"{pm.mcu.name} ({pm.ref})   pin data: {pm.mcu.source}")
+    for a in pm.assignments:
+        console.print(f"  {a.net:<14} {a.pin_name:<5} pin {a.pin:<4} {a.function:<9} {a.direction}")
+    for w in pm.warnings:
+        console.print(f"[yellow]warning:[/] {w}")
+    return 0
+
+
+def _scaffold(args: argparse.Namespace) -> int:
+    pm = build_pinmap(load_netlist(args.design), args.ref, args.mcu)
+    files = scaffold(pm, args.out, args.target, args.name, args.driver, args.design, args.overwrite)
+    for f in files:
+        console.print(f"wrote {f}")
+    for w in pm.warnings:
+        console.print(f"[yellow]warning:[/] {w}")
+    return 0
+
+
+def _driver(args: argparse.Namespace) -> int:
+    if not args.part:
+        console.print("\n".join(supported_parts()))
+        return 0
+    files = generate_driver(args.part, args.address)
+    if args.out:
+        out = Path(args.out)
+        out.mkdir(parents=True, exist_ok=True)
+        for name, text in files.items():
+            (out / name).write_text(text, encoding="utf-8")
+            console.print(f"wrote {out / name}")
+        return 0
+    for name, text in files.items():
+        sys.stdout.write(f"/* ===== {name} ===== */\n{text}\n")
+    return 0
+
+
+def _build(args: argparse.Namespace) -> int:
+    result = size_project(args.project) if args.size else compile_project(args.project)
+    if args.json:
+        print(json.dumps(result.as_dict(), indent=1))
+    else:
+        console.print(f"{result.tool}: {' '.join(result.command)}")
+        for d in result.errors:
+            console.print(f"[red]{d.severity}[/] {d.file}:{d.line}: {d.message}")
+        if result.note:
+            console.print(result.note)
+        if result.size:
+            console.print("size: " + ", ".join(f"{k}={v}" for k, v in result.size.items()))
+        console.print("[green]ok[/]" if result.ok else "[red]failed[/]")
+        if not result.ok and not result.errors and result.output:
+            console.print(result.output[-1500:], markup=False)
+    if not result.ok:
+        return 1
+    if args.flash:
+        cmd = flash_command(args.project, args.port)
+        console.print("flash command: " + " ".join(cmd))
+        if not args.yes:
+            answer = input("run it now? [y/N] ").strip().lower() if sys.stdin.isatty() else ""
+            if answer != "y":
+                console.print("not flashed (pass -y to approve)")
+                return 0
+        flashed = flash_project(args.project, args.port, approved=True)
+        console.print(
+            flashed.note or ("flashed" if flashed.ok else flashed.output[-1500:]), markup=False
+        )
+        return 0 if flashed.ok else 1
+    return 0
+
+
+def _tools(args: argparse.Namespace) -> int:
+    for t in detect_tools():
+        if t.found:
+            console.print(f"[green]found[/]   {t.name:<18} {t.path}  {t.version}")
+        else:
+            console.print(f"[yellow]missing[/] {t.name:<18} {INSTALL_GUIDANCE[t.name]}")
+    return 0
+
+
+_COMMANDS = {
+    "pins": _pins,
+    "scaffold": _scaffold,
+    "driver": _driver,
+    "build": _build,
+    "tools": _tools,
+}