gitcad 0.7.7__py3-none-any.whl

gitcad/render.py

@@ -0,0 +1,177 @@
+"""gitcad-render — PNG/SVG artifacts from any design file.
+
+The real-world deliverable set includes IMAGES (board renders, schematic
+sheets, assembly views for the styling review). SVG is native everywhere
+here; PNG rasterization borrows a local Chrome/Edge in headless mode —
+found automatically, and its absence is a loud, actionable error, never
+a silent downgrade.
+
+- schematic -> sheet-fidelity SVG (imported) or auto-layout SVG
+- board -> board SVG
+- model / assembly / pcba -> 3D via the viewer + headless browser
+  (#x= deep link renders exploded states)
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+import time
+from pathlib import Path
+
+from gitcad.errors import GitcadError
+
+
+def find_browser() -> str | None:
+    for name in ("chrome", "google-chrome", "chromium", "chromium-browser",
+                 "msedge"):
+        exe = shutil.which(name)
+        if exe:
+            return exe
+    for cand in (
+        Path("C:/Program Files/Google/Chrome/Application/chrome.exe"),
+        Path("C:/Program Files (x86)/Google/Chrome/Application/chrome.exe"),
+        Path("C:/Program Files (x86)/Microsoft/Edge/Application/msedge.exe"),
+        Path("C:/Program Files/Microsoft/Edge/Application/msedge.exe"),
+    ):
+        if cand.is_file():
+            return str(cand)
+    return None
+
+
+def _svg_for(path: Path) -> str:
+    if path.suffix == ".kicad_sch":
+        # imported sheets render EXACTLY as drawn (fidelity renderer)
+        from gitcad.ecad.schsvg import sheet_to_svg
+        from gitcad.importers.kicad_sch import import_kicad_sch
+
+        sch, _report = import_kicad_sch(str(path))
+        return sheet_to_svg(sch)
+    text = path.read_text(encoding="utf-8")
+    from gitcad.viewer.server import detect_kind
+
+    kind = detect_kind(text)
+    if kind == "schematic":
+        from gitcad.ecad import Schematic, schematic_to_svg
+
+        return schematic_to_svg(Schematic.loads(text))
+    if kind == "board":
+        from gitcad.ecad import Board
+        from gitcad.viewer.boardsvg import board_to_svg
+
+        return board_to_svg(Board.loads(text))
+    if kind == "pcba":
+        from gitcad.ecad import Board
+        from gitcad.pcba import pcba_sources
+        from gitcad.viewer.boardsvg import board_to_svg
+
+        src = pcba_sources(text, str(path.parent))
+        return board_to_svg(Board.loads(src["board"].read_text(encoding="utf-8")))
+    raise GitcadError(f"no direct SVG projection for kind {kind!r} — "
+                      "use PNG output (3D render via the viewer)")
+
+
+def _png_from_svg(svg: str, out: Path, browser: str, width: int, height: int) -> None:
+    import tempfile
+
+    with tempfile.TemporaryDirectory() as td:
+        f = Path(td) / "r.svg"
+        f.write_text(svg, encoding="utf-8")
+        _shoot(browser, f.as_uri(), out, width, height)
+
+
+def _shoot(browser: str, url: str, out: Path, width: int, height: int) -> None:
+    proc = subprocess.run(
+        [browser, "--headless", "--disable-gpu",
+         f"--screenshot={out}", f"--window-size={width},{height}",
+         "--virtual-time-budget=10000", url],
+        capture_output=True, timeout=120)
+    if not out.is_file():
+        raise GitcadError(
+            f"browser rasterization produced no file "
+            f"(exit {proc.returncode}): {proc.stderr.decode(errors='replace')[:200]}")
+
+
+def render(file: str, out: str, *, width: int = 1400, height: int = 900,
+           explode: float = 0.0, three: bool = False) -> str:
+    """Render a design file to ``out`` (.svg or .png). ``three`` forces a 3D
+    render for boards (the '3d iso' deliverable — board extruded through the
+    bridge). Returns the path."""
+    src = Path(file)
+    dst = Path(out)
+    if src.suffix == ".kicad_sch":
+        kind = "schematic"
+        text = None
+    else:
+        text = src.read_text(encoding="utf-8")
+        from gitcad.viewer.server import detect_kind
+
+        kind = detect_kind(text)
+
+    if dst.suffix.lower() == ".svg":
+        dst.write_text(_svg_for(src), encoding="utf-8")
+        return str(dst)
+    if dst.suffix.lower() != ".png":
+        raise GitcadError(f"unknown output format {dst.suffix!r} (want .svg or .png)")
+
+    browser = find_browser()
+    if browser is None:
+        raise GitcadError(
+            "PNG rendering needs a local Chrome/Edge (headless screenshot) — "
+            "none found; install one or render .svg instead")
+
+    if kind == "board" and three:
+        # the 3D board deliverable: extrude through the bridge, serve, shoot
+        import tempfile
+
+        from gitcad.bridge import board_to_model
+        from gitcad.ecad import Board
+
+        doc = board_to_model(Board.loads(text))
+        with tempfile.TemporaryDirectory() as td:
+            model = Path(td) / "board3d.model"
+            model.write_text(doc.dumps(), encoding="utf-8")
+            return _serve_and_shoot(model, dst, browser, width, height, explode)
+
+    if kind in ("schematic", "board"):
+        _png_from_svg(_svg_for(src), dst, browser, width, height)
+        return str(dst)
+
+    # 3D kinds: serve the viewer briefly, screenshot it
+    return _serve_and_shoot(src, dst, browser, width, height, explode)
+
+
+def _serve_and_shoot(src: Path, dst: Path, browser: str,
+                     width: int, height: int, explode: float) -> str:
+    import threading
+
+    from gitcad.viewer.server import serve
+
+    httpd = serve(str(src), port=0)
+    port = httpd.server_address[1]
+    threading.Thread(target=httpd.serve_forever, daemon=True).start()
+    try:
+        time.sleep(0.3)
+        frag = f"#x={explode}" if explode else ""
+        _shoot(browser, f"http://127.0.0.1:{port}/{frag}", dst, width, height)
+    finally:
+        httpd.shutdown()
+    return str(dst)
+
+
+def main() -> None:  # pragma: no cover - CLI entrypoint
+    import argparse
+
+    ap = argparse.ArgumentParser(
+        description="gitcad render — PNG/SVG images from any design file")
+    ap.add_argument("file")
+    ap.add_argument("-o", "--out", required=True, help="output .png or .svg")
+    ap.add_argument("--width", type=int, default=1400)
+    ap.add_argument("--height", type=int, default=900)
+    ap.add_argument("--explode", type=float, default=0.0,
+                    help="exploded-view amount 0..1 (3D kinds)")
+    ap.add_argument("--three", action="store_true",
+                    help="render a board in 3D (extruded) instead of top view")
+    args = ap.parse_args()
+    print(render(args.file, args.out, width=args.width, height=args.height,
+                 explode=args.explode, three=args.three))

gitcad/requirements.py

@@ -0,0 +1,204 @@
+"""Requirements as code — the traceability matrix that actually executes.
+
+A requirements document is canonical text binding named requirements to
+machine checks over the design: mass and volume limits, bbox envelopes,
+ERC/envelope/DRC cleanliness, rail utilization. ``verify`` runs every one
+and reports measured-vs-limit per requirement — pass/fail history rides in
+git next to the design that satisfies it, and a requirement nobody wired
+to a check is visibly ``unchecked``, never silently green.
+
+Aerospace/medical teams pay fortunes for traceability spreadsheets that
+are lies by the second week. This is ~200 lines because the checks
+already exist; requirements are just names bound to them.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from gitcad.canonical import canonical_json
+from gitcad.errors import GitcadError
+
+SCHEMA = "gitcad/requirements@1"
+
+
+def load_requirements(text: str) -> list[dict]:
+    doc = json.loads(text)
+    if doc.get("schema") != SCHEMA:
+        raise GitcadError(f"unsupported requirements schema {doc.get('schema')!r}")
+    reqs = doc.get("requirements", [])
+    seen = set()
+    for r in reqs:
+        if "id" not in r or "text" not in r:
+            raise GitcadError("every requirement needs id and text")
+        if r["id"] in seen:
+            raise GitcadError(f"duplicate requirement id {r['id']!r}")
+        seen.add(r["id"])
+    return reqs
+
+
+def _load_target(root: Path, target: str):
+    """'model:file.json' / 'schematic:file.json' / 'board:file.json'."""
+    kind, _, rel = target.partition(":")
+    path = root / rel
+    if not path.is_file():
+        raise GitcadError(f"target file not found: {rel}")
+    text = path.read_text(encoding="utf-8")
+    if kind == "model":
+        from gitcad.document import Document
+
+        return Document.loads(text)
+    if kind == "schematic":
+        from gitcad.ecad import Schematic
+
+        return Schematic.loads(text)
+    if kind == "board":
+        from gitcad.ecad import Board
+
+        return Board.loads(text)
+    raise GitcadError(f"unknown target kind {kind!r} (want model|schematic|board)")
+
+
+def _run_check(check: dict, root: Path) -> dict:
+    """One requirement's check. Returns {ok, measured, limit, detail?}."""
+    kind = check.get("kind")
+    if kind in ("mass_max_g", "volume_max_mm3", "bbox_max_mm"):
+        from gitcad.kernel import get_kernel
+
+        kernel = get_kernel()
+        doc = _load_target(root, check["target"])
+        shape = doc.build(kernel).final(doc)
+        if kind == "bbox_max_mm":
+            lo, hi = kernel.bbox(shape)
+            dims = [round(hi[i] - lo[i], 6) for i in range(3)]
+            limit = list(check["limit"])
+            return {"ok": all(d <= lim + 1e-9 for d, lim in zip(dims, limit)),
+                    "measured": dims, "limit": limit,
+                    "geometry_verified": not kernel.name.startswith("null")}
+        vol = kernel.measure(shape).get("volume")
+        if vol is None:
+            return {"ok": False, "measured": None, "limit": check["limit"],
+                    "detail": "volume unavailable on this kernel"}
+        if kind == "volume_max_mm3":
+            return {"ok": vol <= check["limit"] + 1e-9,
+                    "measured": round(vol, 3), "limit": check["limit"],
+                    "geometry_verified": not kernel.name.startswith("null")}
+        mass = vol * check.get("density_g_cm3", 1.0) / 1000.0
+        return {"ok": mass <= check["limit"] + 1e-9,
+                "measured": round(mass, 3), "limit": check["limit"],
+                "geometry_verified": not kernel.name.startswith("null")}
+
+    if kind == "interference_clear":
+        # the cross-domain fit check: every instance of an assembly —
+        # mech models AND board-backed PCBAs (populated envelopes) —
+        # pairwise boolean-intersected within a clash budget
+        from gitcad.kernel import get_kernel
+        from gitcad.part.interference import check_interference
+        from gitcad.viewer.server import resolve_assembly_shapes
+
+        kernel = get_kernel()
+        target = check["target"]
+        kind2, _, rel = target.partition(":")
+        if kind2 != "assembly":
+            raise GitcadError("interference_clear target must be 'assembly:<file>'")
+        path = root / rel
+        if not path.is_file():
+            raise GitcadError(f"target file not found: {rel}")
+        resolved = resolve_assembly_shapes(path, kernel)
+        instances = {n: (s, t, r) for n, (s, t, r, _p) in resolved.items()}
+        tol = float(check.get("tol_mm3", 0.0))
+        rep = check_interference(kernel, instances, tol_mm3=tol or None)
+        worst = max(rep.checks["overlaps_mm3"].values(), default=0.0)
+        return {"ok": rep.ok, "measured": worst, "limit": tol,
+                "detail": rep.checks["overlaps_mm3"] or "no overlaps",
+                "geometry_verified": not kernel.name.startswith("null")}
+
+    if kind == "erc_clean":
+        sch = _load_target(root, check["target"])
+        r = sch.erc()
+        return {"ok": r.ok, "measured": len(r.violations), "limit": 0,
+                "detail": r.violations[:10]}
+    if kind == "envelope_clean":
+        from gitcad.ecad import check_envelopes
+
+        r = check_envelopes(_load_target(root, check["target"]))
+        return {"ok": r.ok, "measured": len(r.violations), "limit": 0,
+                "detail": r.violations[:10],
+                "coverage_pins": r.checks["pins_with_specs"]}
+    if kind == "rail_utilization_max":
+        from gitcad.ecad import power_budget
+
+        budget = power_budget(_load_target(root, check["target"]))
+        rail = budget.get(check["net"])
+        if rail is None or rail.get("utilization") is None:
+            return {"ok": False, "measured": None, "limit": check["limit"],
+                    "detail": f"rail {check['net']!r} has no spec'd source/loads"}
+        return {"ok": rail["utilization"] <= check["limit"] + 1e-9,
+                "measured": rail["utilization"], "limit": check["limit"]}
+    if kind == "drc_clean":
+        from gitcad.ecad.drc import run_drc
+
+        r = run_drc(_load_target(root, check["target"]))
+        return {"ok": r.ok, "measured": len(r.violations), "limit": 0,
+                "detail": r.violations[:10]}
+    raise GitcadError(f"unknown check kind {kind!r}")
+
+
+def verify(requirements_text: str, root: str) -> dict:
+    rootp = Path(root)
+    results = []
+    ok = True
+    for req in load_requirements(requirements_text):
+        entry = {"id": req["id"], "text": req["text"]}
+        check = req.get("check")
+        if not check:
+            # a requirement without a check is VISIBLE debt, not silent green
+            entry.update({"status": "unchecked"})
+            ok = False
+        else:
+            try:
+                r = _run_check(check, rootp)
+                entry.update({"status": "pass" if r.pop("ok") else "fail", **r})
+                if entry["status"] == "fail":
+                    ok = False
+            except Exception as exc:
+                entry.update({"status": "error",
+                              "detail": f"{type(exc).__name__}: {exc}"})
+                ok = False
+        results.append(entry)
+    counts = {s: sum(1 for r in results if r["status"] == s)
+              for s in ("pass", "fail", "error", "unchecked")}
+    return {"ok": ok, "requirements": results, "summary": counts}
+
+
+def to_markdown(report: dict) -> str:
+    s = report["summary"]
+    lines = [f"## requirements — {'ALL PASS' if report['ok'] else 'NOT MET'}",
+             f"{s['pass']} pass · {s['fail']} fail · {s['error']} error · "
+             f"{s['unchecked']} unchecked", "",
+             "| id | requirement | status | measured | limit |",
+             "|----|-------------|--------|----------|-------|"]
+    for r in report["requirements"]:
+        lines.append(f"| {r['id']} | {r['text']} | **{r['status']}** | "
+                     f"{r.get('measured', '—')} | {r.get('limit', '—')} |")
+    return "\n".join(lines) + "\n"
+
+
+def new_requirements_doc(requirements: list[dict]) -> str:
+    return canonical_json({"schema": SCHEMA, "requirements": requirements},
+                          indent=2) + "\n"
+
+
+def main() -> None:  # pragma: no cover - CLI entrypoint
+    import argparse
+    import sys
+
+    ap = argparse.ArgumentParser(
+        description="gitcad requirements — the traceability matrix that executes")
+    ap.add_argument("file", help="requirements.json")
+    ap.add_argument("--root", default=".", help="design tree targets resolve against")
+    args = ap.parse_args()
+    report = verify(Path(args.file).read_text(encoding="utf-8"), args.root)
+    print(to_markdown(report))
+    sys.exit(0 if report["ok"] else 1)

gitcad/review.py

@@ -0,0 +1,230 @@
+"""PR review packaging — what a gitcad pull request shows a reviewer.
+
+``review_range`` compares every changed design document between two git
+refs and produces, per file: the semantic diff (feature/component-level,
+volume delta), the CHECK DELTA (violations introduced or fixed — ERC,
+envelopes, board validation, DRC), and before/after renders. The rollup's
+``gate_ok`` is the merge gate: any NEW violation fails it. A regression
+that was already red on base doesn't block (it isn't this PR's fault) but
+still shows.
+
+Binary CAD formats can't do any of this; canonical text + headless checks
+make it a ~300-line module. Emit markdown for a PR comment via
+``to_markdown``, or a self-contained HTML page via ``to_html``.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+from gitcad.release import _kind, semantic_diff
+
+
+def _git_show(repo: Path, ref: str, relpath: str) -> str | None:
+    proc = subprocess.run(["git", "-C", str(repo), "show", f"{ref}:{relpath}"],
+                          capture_output=True, text=True)
+    return proc.stdout if proc.returncode == 0 else None
+
+
+# Design-document extensions: the json-free names are canonical (directory
+# legibility); .json variants stay accepted forever — kind detection is by
+# CONTENT (the schema field), extensions only scope the scan.
+DESIGN_EXTENSIONS = (".json", ".gitcad", ".model", ".sch", ".board", ".part",
+                     ".pcba", ".reqs")
+
+
+def _changed_files(repo: Path, base: str, head: str) -> list[str]:
+    proc = subprocess.run(
+        ["git", "-C", str(repo), "diff", "--name-only", f"{base}...{head}"],
+        capture_output=True, text=True, check=True)
+    return [ln.strip().replace("\\", "/") for ln in proc.stdout.splitlines()
+            if ln.strip().endswith(DESIGN_EXTENSIONS)
+            and not ln.strip().endswith(".kicad_sch")]
+
+
+def _checks(kind: str, text: str) -> list[str]:
+    """The check suite for one document kind — violation strings."""
+    try:
+        if kind == "schematic":
+            from gitcad.ecad import Schematic, check_envelopes
+
+            sch = Schematic.loads(text)
+            return sch.erc().violations + check_envelopes(sch).violations
+        if kind == "board":
+            from gitcad.ecad import Board
+            from gitcad.ecad.drc import run_drc
+
+            board = Board.loads(text)
+            return board.validate().violations + run_drc(board).violations
+        if kind == "document":
+            from gitcad.document import Document
+            from gitcad.kernel import get_kernel
+
+            doc = Document.loads(text)
+            kernel = get_kernel()
+            result = doc.build(kernel)
+            report = kernel.validate(result.final(doc)) if len(doc) else None
+            return list(report.violations) if report and not report.ok else []
+        return []   # part manifests: interface-semver rides in the diff
+    except Exception as exc:
+        return [f"check-error:{type(exc).__name__}:{exc}"]
+
+
+def _render(kind: str, text: str) -> str | None:
+    """A reviewable SVG for one revision of a document, or None."""
+    try:
+        if kind == "schematic":
+            from gitcad.ecad import Schematic, schematic_to_svg
+
+            return schematic_to_svg(Schematic.loads(text))
+        if kind == "board":
+            from gitcad.ecad import Board
+            from gitcad.viewer.boardsvg import board_to_svg
+
+            return board_to_svg(Board.loads(text))
+        if kind == "document":
+            from gitcad.document import Document
+            from gitcad.drawing.sheet import make_drawing
+            from gitcad.kernel import get_kernel
+
+            kernel = get_kernel()
+            if kernel.name.startswith("null"):
+                return None   # no fake geometry renders
+            doc = Document.loads(text)
+            return make_drawing(doc.build(kernel).final(doc), kernel,
+                                title="review", sheet="A4").to_svg()
+    except Exception:
+        return None
+    return None
+
+
+def review_range(repo: str, base: str, head: str = "HEAD") -> dict:
+    root = Path(repo)
+    files = []
+    gate_ok = True
+    for rel in _changed_files(root, base, head):
+        old = _git_show(root, base, rel)
+        new = _git_show(root, head, rel)
+        if new is None and old is None:
+            continue
+        kind = _kind(new if new is not None else old)
+        if kind not in ("document", "board", "schematic", "part"):
+            continue
+        entry: dict = {"file": rel, "kind": kind,
+                       "status": ("added" if old is None else
+                                  "removed" if new is None else "modified")}
+        if old is not None and new is not None:
+            entry["diff"] = semantic_diff(old, new)
+        old_v = _checks(kind, old) if old is not None else []
+        new_v = _checks(kind, new) if new is not None else []
+        # sibling waivers file at HEAD applies to the gate (reviewable text —
+        # a PR that adds a waiver shows exactly what it silences and why)
+        wtext = _git_show(root, head, rel + ".waivers")
+        if wtext is not None:
+            from gitcad.waivers import load_waivers, waive
+
+            try:
+                ws = load_waivers(wtext)
+                new_v, waived, unused = waive(new_v, ws)
+                entry["waived"] = waived
+                new_v += [f"waiver-unused:{m}" for m in unused]
+            except Exception as exc:
+                new_v.append(f"waiver-error:{type(exc).__name__}:{exc}")
+        entry["violations_introduced"] = sorted(set(new_v) - set(old_v))
+        entry["violations_fixed"] = sorted(set(old_v) - set(new_v))
+        entry["violations_preexisting"] = sorted(set(new_v) & set(old_v))
+        if entry["violations_introduced"]:
+            gate_ok = False
+        entry["render_old"] = _render(kind, old) if old is not None else None
+        entry["render_new"] = _render(kind, new) if new is not None else None
+        files.append(entry)
+    return {"base": base, "head": head, "files": files, "gate_ok": gate_ok,
+            "summary": {
+                "changed": len(files),
+                "introduced": sum(len(f["violations_introduced"]) for f in files),
+                "fixed": sum(len(f["violations_fixed"]) for f in files)}}
+
+
+def to_markdown(report: dict) -> str:
+    s = report["summary"]
+    gate = "PASS" if report["gate_ok"] else "FAIL"
+    lines = [f"## gitcad review — {report['base']}...{report['head']}",
+             f"**gate: {gate}** · {s['changed']} design file(s) changed · "
+             f"{s['introduced']} violation(s) introduced · {s['fixed']} fixed", ""]
+    for f in report["files"]:
+        lines.append(f"### `{f['file']}` ({f['kind']}, {f['status']})")
+        d = f.get("diff", {})
+        for key in ("features_added", "features_removed", "features_changed",
+                    "components_added", "components_removed"):
+            if d.get(key):
+                items = [x["id"] if isinstance(x, dict) else x for x in d[key]]
+                lines.append(f"- {key.replace('_', ' ')}: {', '.join(map(str, items))}")
+        if "volume_mm3" in d and "delta" in d.get("volume_mm3", {}):
+            v = d["volume_mm3"]
+            lines.append(f"- volume: {v['old']} → {v['new']} mm³ (Δ {v['delta']:+})")
+        if d.get("required_bump"):
+            lines.append(f"- interface-semver: **{d['required_bump']}** bump required "
+                         f"({'; '.join(d.get('reasons', []))})")
+        for label, key in (("**introduced**", "violations_introduced"),
+                           ("fixed", "violations_fixed")):
+            for v in f[key]:
+                lines.append(f"- {label}: `{v}`")
+        if f["violations_preexisting"]:
+            lines.append(f"- pre-existing (not this PR): {len(f['violations_preexisting'])}")
+        lines.append("")
+    return "\n".join(lines)
+
+
+def to_html(report: dict) -> str:
+    cards = []
+    for f in report["files"]:
+        panes = ""
+        if f["render_old"] or f["render_new"]:
+            for title, svg in (("base", f["render_old"]), ("head", f["render_new"])):
+                inner = svg if svg else '<p class="none">(no render)</p>'
+                panes += f'<div class="pane"><h4>{title}</h4>{inner}</div>'
+            panes = f'<div class="sxs">{panes}</div>'
+        vio = "".join(f'<li class="bad">{v}</li>' for v in f["violations_introduced"])
+        vio += "".join(f'<li class="good">fixed: {v}</li>' for v in f["violations_fixed"])
+        cards.append(f'<section><h3>{f["file"]} <small>({f["kind"]}, {f["status"]})'
+                     f'</small></h3><ul>{vio}</ul>{panes}</section>')
+    gate = "PASS" if report["gate_ok"] else "FAIL"
+    color = "#3fb950" if report["gate_ok"] else "#f85149"
+    return (
+        "<!DOCTYPE html><html><head><meta charset='utf-8'>"
+        "<title>gitcad review</title><style>"
+        "body{font:14px ui-monospace,Consolas,monospace;margin:2rem;background:#0d1117;color:#c9d1d9}"
+        "section{margin-bottom:2rem;border:1px solid #21262d;border-radius:6px;padding:1rem}"
+        ".sxs{display:flex;gap:12px;flex-wrap:wrap}"
+        ".pane{flex:1;min-width:320px;background:#fff;border-radius:4px;padding:8px}"
+        ".pane h4{color:#57606a;margin:0 0 6px}.pane svg{max-width:100%;height:auto}"
+        ".bad{color:#f85149}.good{color:#3fb950}.none{color:#8b949e}"
+        "small{color:#8b949e}</style></head><body>"
+        f"<h1>gitcad review <span style='color:{color}'>{gate}</span></h1>"
+        f"<p>{report['base']}...{report['head']} · "
+        f"{report['summary']['changed']} file(s) · "
+        f"{report['summary']['introduced']} introduced · "
+        f"{report['summary']['fixed']} fixed</p>"
+        + "".join(cards) + "</body></html>")
+
+
+def main() -> None:  # pragma: no cover - CLI entrypoint
+    import argparse
+    import sys
+
+    ap = argparse.ArgumentParser(
+        description="gitcad review — semantic + check + visual diff between git refs")
+    ap.add_argument("--repo", default=".")
+    ap.add_argument("--base", required=True)
+    ap.add_argument("--head", default="HEAD")
+    ap.add_argument("--md", help="write a Markdown report (PR comment) here")
+    ap.add_argument("--html", help="write a self-contained HTML report here")
+    args = ap.parse_args()
+    report = review_range(args.repo, args.base, args.head)
+    if args.md:
+        Path(args.md).write_text(to_markdown(report), encoding="utf-8")
+    if args.html:
+        Path(args.html).write_text(to_html(report), encoding="utf-8")
+    print(to_markdown(report))
+    sys.exit(0 if report["gate_ok"] else 1)

gitcad/viewer/__init__.py

@@ -0,0 +1,19 @@
+"""The web viewer — a local, dependency-free window into models and boards.
+
+``gitcad-view model.gitcad.json`` serves a single-page viewer at localhost:
+3D models render in a ~200-line WebGL2 client (no three.js, no CDN — the
+page is self-contained, matching the project's zero-dependency ethos); boards
+render as server-generated SVG. The page polls for file changes and reloads
+live, which makes it simultaneously:
+
+- the human's window while an agent works, and
+- the agent's eyes (drive the file, screenshot the viewer).
+
+Server: Python stdlib only. The Renderer seam gets a real backend the day we
+need offscreen PNGs; the tessellation source is already kernel-side.
+"""
+
+from gitcad.viewer.boardsvg import board_to_svg
+from gitcad.viewer.server import main, mesh_payload
+
+__all__ = ["board_to_svg", "mesh_payload", "main"]