gitcad 0.7.7__py3-none-any.whl

gitcad/bench/corpus.py

@@ -0,0 +1,260 @@
+"""The kernel benchmark corpus — deterministic documents per operator
+class (ADR-0018 W0).
+
+Each entry builds a Document tagged with the operator classes it
+exercises. This corpus is simultaneously: the differential-test input
+(ref vs occt), the benchmark workload (timed per backend), and the
+future acceptance suite for kernel cutover. Torture entries encode the
+configurations that break kernels — tangencies, coincidences, slivers
+— where beating OCCT must become measurable.
+"""
+
+from __future__ import annotations
+
+from typing import Callable
+
+from gitcad.document import Document, Feature
+
+
+def plate_with_holes() -> Document:
+    d = Document()
+    base = d.add(Feature(op="box", params={"dx": 60, "dy": 40, "dz": 4}))
+    prev = base
+    for i in range(4):
+        prev = d.add(Feature(op="hole", params={
+            "x": 10 + 13 * i, "y": 20, "top_z": 4, "depth": 4,
+            "diameter": 5}, inputs=[prev]))
+    return d
+
+
+def quadric_boss() -> Document:
+    d = Document()
+    base = d.add(Feature(op="cylinder", params={"radius": 20, "height": 8}))
+    boss = d.add(Feature(op="cone", params={"r1": 10, "r2": 6, "height": 12}))
+    bm = d.add(Feature(op="move", params={"translate": [0, 0, 8]}, inputs=[boss]))
+    u = d.add(Feature(op="boolean", params={"kind": "union"}, inputs=[base, bm]))
+    s = d.add(Feature(op="sphere", params={"radius": 5}))
+    sm = d.add(Feature(op="move", params={"translate": [0, 0, 22]}, inputs=[s]))
+    d.add(Feature(op="boolean", params={"kind": "union"}, inputs=[u, sm]))
+    return d
+
+
+def revolve_profile() -> Document:
+    d = Document()
+    profile = {"start": [5, 0], "segments": [
+        {"kind": "line", "to": [15, 0]}, {"kind": "line", "to": [15, 4]},
+        {"kind": "line", "to": [8, 8]}, {"kind": "line", "to": [8, 20]},
+        {"kind": "line", "to": [5, 20]}, {"kind": "line", "to": [5, 0]}]}
+    d.add(Feature(op="revolve", params={"profile": profile, "angle_deg": 360.0}))
+    return d
+
+
+def extrude_L() -> Document:
+    d = Document()
+    profile = {"start": [0, 0], "segments": [
+        {"kind": "line", "to": [30, 0]}, {"kind": "line", "to": [30, 8]},
+        {"kind": "line", "to": [8, 8]}, {"kind": "line", "to": [8, 25]},
+        {"kind": "line", "to": [0, 25]}, {"kind": "line", "to": [0, 0]}]}
+    d.add(Feature(op="extrude", params={"profile": profile, "height": 12}))
+    return d
+
+
+def filleted_block() -> Document:
+    d = Document()
+    b = d.add(Feature(op="box", params={"dx": 30, "dy": 20, "dz": 10}))
+    d.add(Feature(op="fillet", params={"radius": 2.5}, inputs=[b]))
+    return d
+
+
+def chamfered_block() -> Document:
+    d = Document()
+    b = d.add(Feature(op="box", params={"dx": 30, "dy": 20, "dz": 10}))
+    d.add(Feature(op="chamfer", params={"distance": 2.0}, inputs=[b]))
+    return d
+
+
+def shelled_box() -> Document:
+    d = Document()
+    b = d.add(Feature(op="box", params={"dx": 40, "dy": 30, "dz": 20}))
+    d.add(Feature(op="shell", params={"faces": [], "thickness": 2.0},
+                  inputs=[b]))
+    return d
+
+
+def shelled_prism() -> Document:
+    # K4.1: closed hollow of a non-box prism — a right trapezoid with a
+    # 3-4-5 hypotenuse (Pythagorean edges → the exact inward inset).
+    # ref = exactly 541/6; OCCT's thick-solid offset agrees in float.
+    d = Document()
+    p = d.add(Feature(op="extrude", params={"profile": {
+        "start": [0, 0], "segments": [
+            {"kind": "line", "to": [8, 0]}, {"kind": "line", "to": [8, 3]},
+            {"kind": "line", "to": [4, 6]}, {"kind": "line", "to": [0, 6]},
+            {"kind": "line", "to": [0, 0]}]}, "height": 5}))
+    d.add(Feature(op="shell", params={"faces": [], "thickness": 0.5},
+                  inputs=[p]))
+    return d
+
+
+def drafted_block() -> Document:
+    d = Document()
+    b = d.add(Feature(op="box", params={"dx": 30, "dy": 30, "dz": 15}))
+    d.add(Feature(op="draft", params={"faces": [], "angle_deg": 3.0},
+                  inputs=[b]))
+    return d
+
+
+def spring() -> Document:
+    d = Document()
+    d.add(Feature(op="spring", params={"radius": 8, "pitch": 4, "turns": 6,
+                                       "wire_diameter": 1.5}))
+    return d
+
+
+def swept_channel() -> Document:
+    d = Document()
+    profile = {"start": [-2, -2], "segments": [
+        {"kind": "line", "to": [2, -2]}, {"kind": "line", "to": [2, 2]},
+        {"kind": "line", "to": [-2, 2]}, {"kind": "line", "to": [-2, -2]}]}
+    d.add(Feature(op="sweep", params={"profile": profile,
+                                      "path": [[0, 0, 0], [0, 0, 20],
+                                               [15, 0, 35], [40, 0, 35]]}))
+    return d
+
+
+def loft_transition() -> Document:
+    d = Document()
+    sq = {"start": [-10, -10], "segments": [
+        {"kind": "line", "to": [10, -10]}, {"kind": "line", "to": [10, 10]},
+        {"kind": "line", "to": [-10, 10]}, {"kind": "line", "to": [-10, -10]}]}
+    sm = {"start": [-4, -4], "segments": [
+        {"kind": "line", "to": [4, -4]}, {"kind": "line", "to": [4, 4]},
+        {"kind": "line", "to": [-4, 4]}, {"kind": "line", "to": [-4, -4]}]}
+    d.add(Feature(op="loft", params={"sections": [
+        {"profile": sq, "z": 0.0}, {"profile": sm, "z": 25.0}]}))
+    return d
+
+
+def sheetmetal_folded() -> Document:
+    from gitcad.sheetmetal import Flange, SheetMetal
+
+    sm = SheetMetal(name="bench-bracket", width=40, height=50, thickness=2,
+                    k_factor=0.44, bend_radius=2,
+                    flanges=[Flange(edge="n", length=20),
+                             Flange(edge="e", length=12, direction="down")])
+    return sm.to_document()
+
+
+# -- torture: the configurations that break kernels ---------------------------
+
+def torture_tangent_cylinders() -> Document:
+    d = Document()
+    a = d.add(Feature(op="cylinder", params={"radius": 10, "height": 10}))
+    b = d.add(Feature(op="cylinder", params={"radius": 10, "height": 10}))
+    bm = d.add(Feature(op="move", params={"translate": [20, 0, 0]}, inputs=[b]))
+    d.add(Feature(op="boolean", params={"kind": "union"}, inputs=[a, bm]))
+    return d
+
+
+def torture_coincident_faces() -> Document:
+    d = Document()
+    a = d.add(Feature(op="box", params={"dx": 20, "dy": 20, "dz": 10}))
+    b = d.add(Feature(op="box", params={"dx": 20, "dy": 20, "dz": 10}))
+    bm = d.add(Feature(op="move", params={"translate": [20, 0, 0]}, inputs=[b]))
+    d.add(Feature(op="boolean", params={"kind": "union"}, inputs=[a, bm]))
+    return d
+
+
+def torture_sliver_cut() -> Document:
+    d = Document()
+    a = d.add(Feature(op="box", params={"dx": 30, "dy": 30, "dz": 10}))
+    b = d.add(Feature(op="box", params={"dx": 30, "dy": 30, "dz": 10}))
+    bm = d.add(Feature(op="move", params={"translate": [29.999, 0, 0]},
+                       inputs=[b]))
+    d.add(Feature(op="boolean", params={"kind": "cut"}, inputs=[a, bm]))
+    return d
+
+
+def torture_tangent_sphere_plane() -> Document:
+    d = Document()
+    a = d.add(Feature(op="box", params={"dx": 30, "dy": 30, "dz": 10}))
+    s = d.add(Feature(op="sphere", params={"radius": 5}))
+    sm = d.add(Feature(op="move", params={"translate": [15, 15, 15]},
+                       inputs=[s]))
+    d.add(Feature(op="boolean", params={"kind": "union"}, inputs=[a, sm]))
+    return d
+
+
+def quadric_sphere_overlap() -> Document:
+    """Two GENUINELY OVERLAPPING spheres unioned — a non-coaxial quadric
+    boolean OCCT builds and ref does EXACTLY in ℚ[π] (cap/lens): r=5
+    spheres 6 apart -> union = 896/3 π. The K2.2 exact case (parallel-
+    cylinder overlap stays transcendental / refused)."""
+    d = Document()
+    a = d.add(Feature(op="sphere", params={"radius": 5}))
+    b = d.add(Feature(op="sphere", params={"radius": 5}))
+    bm = d.add(Feature(op="move", params={"translate": [6, 0, 0]}, inputs=[b]))
+    d.add(Feature(op="boolean", params={"kind": "union"}, inputs=[a, bm]))
+    return d
+
+
+def sweep_rightangle() -> Document:
+    """A square profile swept along a 90-degree-cornered axis-aligned path
+    — all segment lengths RATIONAL, so ref builds it in plain Q (no surd
+    field needed). Exact volume = area * (10+10+10) = 16*30 = 480."""
+    d = Document()
+    profile = {"start": [-2, -2], "segments": [
+        {"kind": "line", "to": [2, -2]}, {"kind": "line", "to": [2, 2]},
+        {"kind": "line", "to": [-2, 2]}, {"kind": "line", "to": [-2, -2]}]}
+    d.add(Feature(op="sweep", params={"profile": profile,
+                                      "path": [[0, 0, 0], [0, 0, 10],
+                                               [10, 0, 10], [10, 0, 20]]}))
+    return d
+
+
+def torture_menger_1() -> Document:
+    """The K1 acid test: Menger sponge level 1 — a 27mm cube minus three
+    orthogonal 9mm square rods through the center. Five chained booleans
+    with coincident internal faces everywhere; exact volume is KNOWN:
+    20/27 of the cube = 14580 mm^3. A kernel that smears tolerances gets
+    this wrong; an exact kernel gets it to the last bit."""
+    d = Document()
+    cube = d.add(Feature(op="box", params={"dx": 27, "dy": 27, "dz": 27}))
+    rz = d.add(Feature(op="box", params={"dx": 9, "dy": 9, "dz": 27}))
+    rzm = d.add(Feature(op="move", params={"translate": [9, 9, 0]}, inputs=[rz]))
+    rx = d.add(Feature(op="box", params={"dx": 27, "dy": 9, "dz": 9}))
+    rxm = d.add(Feature(op="move", params={"translate": [0, 9, 9]}, inputs=[rx]))
+    ry = d.add(Feature(op="box", params={"dx": 9, "dy": 27, "dz": 9}))
+    rym = d.add(Feature(op="move", params={"translate": [9, 0, 9]}, inputs=[ry]))
+    u1 = d.add(Feature(op="boolean", params={"kind": "union"}, inputs=[rzm, rxm]))
+    u2 = d.add(Feature(op="boolean", params={"kind": "union"}, inputs=[u1, rym]))
+    d.add(Feature(op="boolean", params={"kind": "cut"}, inputs=[cube, u2]))
+    return d
+
+
+CORPUS: list[tuple[str, tuple[str, ...], Callable[[], Document]]] = [
+    ("plate_with_holes", ("planar", "boolean", "hole"), plate_with_holes),
+    ("quadric_boss", ("quadric", "boolean"), quadric_boss),
+    ("revolve_profile", ("quadric", "revolve"), revolve_profile),
+    ("extrude_L", ("planar", "extrude"), extrude_L),
+    ("filleted_block", ("blend",), filleted_block),
+    ("chamfered_block", ("planar", "blend"), chamfered_block),
+    ("shelled_box", ("offset",), shelled_box),
+    ("shelled_prism", ("offset",), shelled_prism),
+    ("drafted_block", ("draft",), drafted_block),
+    ("spring", ("sweep", "freeform"), spring),
+    ("swept_channel", ("sweep",), swept_channel),
+    ("loft_transition", ("loft", "freeform"), loft_transition),
+    ("sheetmetal_folded", ("planar", "boolean"), sheetmetal_folded),
+    ("torture_tangent_cylinders", ("torture", "quadric", "boolean"),
+     torture_tangent_cylinders),
+    ("torture_coincident_faces", ("torture", "planar", "boolean"),
+     torture_coincident_faces),
+    ("torture_sliver_cut", ("torture", "planar", "boolean"),
+     torture_sliver_cut),
+    ("torture_tangent_sphere_plane", ("torture", "quadric", "boolean"),
+     torture_tangent_sphere_plane),
+    ("torture_menger_1", ("torture", "planar", "boolean"), torture_menger_1),
+    ("sweep_rightangle", ("sweep",), sweep_rightangle),
+    ("quadric_sphere_overlap", ("quadric", "boolean"), quadric_sphere_overlap),
+]

gitcad/bench/scorecard.py

@@ -0,0 +1,176 @@
+"""Kernel scorecard — the benchmark that makes improvement provable
+(ADR-0018 W0; owner requirement: "show we are actually improving").
+
+Runs the corpus on a named backend and emits a snapshot: per-model
+build result, wall time, volume/bbox/topology metrics, validation.
+With two backends, emits deltas. Snapshots are dated JSON committed
+under bench/; TREND.md regenerates from them so every improvement
+claim has a number in git history behind it.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from pathlib import Path
+from typing import Any
+
+from gitcad.bench.corpus import CORPUS
+
+_REL_TOL = 1e-9
+
+
+def _get_kernel(name: str):
+    if name == "occt":
+        from gitcad.kernel.occt import OcctKernel
+        return OcctKernel()
+    if name == "null":
+        from gitcad.kernel.null import NullKernel
+        return NullKernel()
+    if name == "ref":
+        from gitcad.kernel.ref import RefKernel
+        return RefKernel()
+    if name == "forge":
+        from gitcad.kernel.rustref import RustKernel
+        return RustKernel()
+    if name == "auto":
+        from gitcad.kernel.auto import AutoKernel
+        return AutoKernel()
+    raise ValueError(f"unknown backend {name!r} (occt|null|ref|forge|auto)")
+
+
+def run_backend(backend: str) -> dict[str, Any]:
+    """Build every corpus model on one backend; never raises — failures
+    are data (that is the point of a robustness benchmark)."""
+    kernel = _get_kernel(backend)
+    models: dict[str, Any] = {}
+    for name, classes, build in CORPUS:
+        entry: dict[str, Any] = {"classes": list(classes)}
+        t0 = time.perf_counter()
+        try:
+            doc = build()
+            result = doc.build(kernel)
+            shape = result.final(doc)
+            entry["ok"] = True
+            entry["seconds"] = round(time.perf_counter() - t0, 4)
+            try:
+                mp = kernel.mass_props(shape)
+                entry["volume"] = mp.get("volume")
+            except Exception as exc:                     # metric, not fatal
+                entry["volume_error"] = f"{type(exc).__name__}: {exc}"
+            try:
+                (x0, y0, z0), (x1, y1, z1) = kernel.bbox(shape)
+                entry["bbox"] = [round(v, 6) for v in
+                                 (x0, y0, z0, x1, y1, z1)]
+            except Exception:
+                pass
+            try:
+                entry["faces"] = len(kernel.entities(shape, "face"))
+                entry["edges"] = len(kernel.entities(shape, "edge"))
+            except Exception:
+                pass
+            try:
+                v = kernel.validate(shape)
+                entry["valid"] = bool(v.ok)
+            except Exception:
+                pass
+        except Exception as exc:
+            entry["ok"] = False
+            entry["seconds"] = round(time.perf_counter() - t0, 4)
+            entry["error"] = f"{type(exc).__name__}: {exc}"
+        models[name] = entry
+
+    by_class: dict[str, dict[str, int]] = {}
+    for name, entry in models.items():
+        for cls in entry["classes"]:
+            c = by_class.setdefault(cls, {"total": 0, "ok": 0, "valid": 0})
+            c["total"] += 1
+            c["ok"] += 1 if entry.get("ok") else 0
+            c["valid"] += 1 if entry.get("valid") else 0
+    return {"backend": backend, "models": models, "by_class": by_class,
+            "capability_pct": round(
+                100 * sum(1 for m in models.values() if m.get("ok"))
+                / len(models), 1)}
+
+
+def compare(a: dict[str, Any], b: dict[str, Any]) -> dict[str, Any]:
+    """Deltas of run b against oracle run a (volume rel-delta, topology
+    count diffs, disagreement list)."""
+    out: dict[str, Any] = {"oracle": a["backend"], "subject": b["backend"],
+                           "models": {}, "disagreements": []}
+    for name, ea in a["models"].items():
+        eb = b["models"].get(name, {})
+        row: dict[str, Any] = {"oracle_ok": ea.get("ok"),
+                               "subject_ok": eb.get("ok")}
+        va, vb = ea.get("volume"), eb.get("volume")
+        if isinstance(va, (int, float)) and isinstance(vb, (int, float)) and va:
+            row["volume_rel_delta"] = abs(vb - va) / abs(va)
+            if row["volume_rel_delta"] > 1e-6:
+                out["disagreements"].append(
+                    f"{name}: volume {va:.6g} vs {vb:.6g}")
+        if ea.get("ok") != eb.get("ok"):
+            out["disagreements"].append(
+                f"{name}: ok {ea.get('ok')} vs {eb.get('ok')}")
+        for k in ("faces", "edges"):
+            if k in ea and k in eb and ea[k] != eb[k]:
+                row[f"{k}_diff"] = (ea[k], eb[k])
+        out["models"][name] = row
+    return out
+
+
+def snapshot(backends: list[str], outdir: str = "bench", *,
+             stamp: str) -> dict[str, Any]:
+    """Run + persist one dated benchmark snapshot; regenerate TREND.md."""
+    runs = {b: run_backend(b) for b in backends}
+    payload: dict[str, Any] = {"stamp": stamp, "runs": runs}
+    if len(backends) == 2:
+        payload["compare"] = compare(runs[backends[0]], runs[backends[1]])
+    out = Path(outdir)
+    out.mkdir(parents=True, exist_ok=True)
+    path = out / f"{stamp}-{'-vs-'.join(backends)}.json"
+    path.write_text(json.dumps(payload, indent=2, sort_keys=True) + "\n",
+                    newline="\n")
+    _render_trend(out)
+    return payload
+
+
+def _render_trend(outdir: Path) -> None:
+    rows: list[str] = ["# Kernel benchmark trend", "",
+                       "Regenerated from bench/*.json — every improvement "
+                       "claim has a snapshot behind it.", "",
+                       "| snapshot | backend | capability % | torture ok | "
+                       "models ok | total s |",
+                       "|---|---|---|---|---|---|"]
+    for p in sorted(outdir.glob("*.json")):
+        data = json.loads(p.read_text())
+        for backend, run in sorted(data.get("runs", {}).items()):
+            models = run["models"]
+            torture = [m for m in models.values() if "torture" in m["classes"]]
+            rows.append(
+                f"| {data['stamp']} | {backend} | {run['capability_pct']} | "
+                f"{sum(1 for m in torture if m.get('ok'))}/{len(torture)} | "
+                f"{sum(1 for m in models.values() if m.get('ok'))}/{len(models)} | "
+                f"{round(sum(m.get('seconds', 0) for m in models.values()), 2)} |")
+    (outdir / "TREND.md").write_text("\n".join(rows) + "\n", newline="\n")
+
+
+def main() -> None:  # pragma: no cover - CLI entry
+    import argparse
+    from datetime import date
+
+    ap = argparse.ArgumentParser(description="kernel benchmark scorecard")
+    ap.add_argument("backends", nargs="+", help="occt | null | ref")
+    ap.add_argument("--outdir", default="bench")
+    ap.add_argument("--stamp", default=str(date.today()))
+    args = ap.parse_args()
+    payload = snapshot(args.backends, args.outdir, stamp=args.stamp)
+    for b, run in payload["runs"].items():
+        print(f"{b}: capability {run['capability_pct']}% "
+              f"({sum(1 for m in run['models'].values() if m.get('ok'))}"
+              f"/{len(run['models'])} models)")
+    for d in payload.get("compare", {}).get("disagreements", []):
+        print("DISAGREE:", d)
+
+
+if __name__ == "__main__":
+    main()

gitcad/bridge.py

@@ -0,0 +1,72 @@
+"""Cross-domain bridges (metapackage — the one place mech and ecad meet).
+
+:func:`board_to_model` — the dogfood's #2 friction finding: interference
+checking needed the board as real 3D geometry, previously hand-extruded.
+Now: outline (polygon, any shape) x thickness, mounting holes cut through —
+a mech Document derived from the ecad source, ready for assemblies,
+interference, STEP export, or the viewer.
+"""
+
+from __future__ import annotations
+
+from gitcad.document import Document, Feature
+from gitcad.ecad.board import Board
+from gitcad.sketch import Profile
+
+
+def component_envelope(comp, *, default_height: float = 2.0
+                       ) -> tuple[float, float, float] | None:
+    """(w, h, height) of a component's IDF-style envelope, rotation applied:
+    courtyard when declared, pads' extent + margin otherwise, None when the
+    footprint has neither."""
+    cy = comp.footprint.courtyard
+    if cy is not None:
+        cw, ch = cy
+    else:
+        pads = comp.footprint.pads
+        if not pads:
+            return None
+        cw = max(abs(p.x) + p.w / 2 for p in pads) * 2 + 0.4
+        ch = max(abs(p.y) + p.h / 2 for p in pads) * 2 + 0.4
+    if round(comp.rot) % 180 == 90:
+        cw, ch = ch, cw
+    return (cw, ch, comp.footprint.height or default_height)
+
+
+def board_to_model(board: Board, *, components: bool = True,
+                   default_height: float = 2.0) -> Document:
+    """The board as a 3D body: extruded outline with mounting holes cut,
+    plus IDF-style component envelopes — each part's courtyard extruded to
+    its footprint height (``default_height`` when unknown). That makes the
+    populated board a REAL mechanical envelope: enclosure interference
+    checks see the tall electrolytic, not a bare slab."""
+    pts = list(board.outline)
+    prof = Profile(tuple(pts[0]))
+    for x, y in pts[1:]:
+        prof.line_to(x, y)
+    prof.close()
+
+    doc = Document()
+    fid = doc.add(Feature(op="extrude", params={"profile": prof.to_params(),
+                                                "height": board.thickness}))
+    for mh in board.mounting_holes:
+        fid = doc.add(Feature(op="hole", params={
+            "x": mh.x, "y": mh.y, "top_z": board.thickness,
+            "diameter": mh.drill, "depth": board.thickness}, inputs=[fid]))
+    if components:
+        for comp in board.components:
+            env = component_envelope(comp, default_height=default_height)
+            if env is None:
+                continue
+            cw, ch, h = env
+            # top: sits on the board surface; bottom: hangs below z=0
+            base = board.thickness if comp.side == "top" else -h
+            body = Profile((comp.x - cw / 2, comp.y - ch / 2)) \
+                .line_to(comp.x + cw / 2, comp.y - ch / 2) \
+                .line_to(comp.x + cw / 2, comp.y + ch / 2) \
+                .line_to(comp.x - cw / 2, comp.y + ch / 2).close()
+            fid = doc.add(Feature(op="extrude", params={
+                "profile": body.to_params(), "height": h,
+                "plane": {"offset": base},
+                "mode": "add"}, inputs=[fid]))
+    return doc

gitcad/convert.py

@@ -0,0 +1,30 @@
+"""gitcad-convert — one-command onboarding from other CAD.
+
+Currently: multi-body FreeCAD .FCStd -> a full gitcad project (per-body
+.model + .part, content-addressed assets/, and a .gitcad product root
+instancing everything at as-modeled positions). From there the whole
+toolchain applies: viewer + explode, interference with clash budgets,
+review gates, release.
+"""
+
+from __future__ import annotations
+
+
+def main() -> None:  # pragma: no cover - CLI entrypoint
+    import argparse
+
+    from gitcad.importers.fcstd import fcstd_to_project
+    from gitcad.kernel import get_kernel
+
+    ap = argparse.ArgumentParser(
+        description="gitcad convert — foreign CAD file to a gitcad project")
+    ap.add_argument("file", help="an .FCStd file (more formats to come)")
+    ap.add_argument("-o", "--out", required=True, help="project directory")
+    ap.add_argument("--name", help="project name (default: file stem)")
+    args = ap.parse_args()
+    result = fcstd_to_project(args.file, args.out,
+                              get_kernel(require="occt"), name=args.name)
+    print(f"converted {result['project']}: {len(result['bodies'])} bodies")
+    for rel in result["written"]:
+        print(f"  {rel}")
+    print(f"open it: gitcad-view {args.out}/{result['root']}")

gitcad/explore.py

@@ -0,0 +1,99 @@
+"""gitcad-explore — the branch scoreboard (ADR-0016's exploration half).
+
+Spawn N design variants as branches, then judge them all by the same
+gates: the review check-delta against base (violations introduced/fixed)
+and, when the branch carries ``requirements.reqs``, the full executable
+requirements suite run in a throwaway worktree of that branch. Output is
+a table — the design-space comparison incumbent tools cannot make
+because their files cannot branch.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import tempfile
+from pathlib import Path
+
+from gitcad.review import review_range
+
+
+def _git(repo: str, *args: str) -> subprocess.CompletedProcess:
+    return subprocess.run(["git", "-C", repo, *args],
+                          capture_output=True, text=True)
+
+
+def _branches(repo: str, base: str) -> list[str]:
+    proc = _git(repo, "branch", "--format=%(refname:short)")
+    return [b.strip() for b in proc.stdout.splitlines()
+            if b.strip() and b.strip() != base]
+
+
+def _requirements_in(repo: str, branch: str) -> str | None:
+    proc = _git(repo, "show", f"{branch}:requirements.reqs")
+    return proc.stdout if proc.returncode == 0 else None
+
+
+def score_branches(repo: str, base: str,
+                   branches: list[str] | None = None) -> dict:
+    from gitcad.requirements import verify
+
+    rows = []
+    for branch in (branches or _branches(repo, base)):
+        row: dict = {"branch": branch}
+        review = review_range(repo, base, branch)
+        row["gate"] = "PASS" if review["gate_ok"] else "FAIL"
+        row["introduced"] = review["summary"]["introduced"]
+        row["fixed"] = review["summary"]["fixed"]
+        row["files_changed"] = review["summary"]["changed"]
+
+        reqs_text = _requirements_in(repo, branch)
+        if reqs_text is not None:
+            with tempfile.TemporaryDirectory() as td:
+                wt = str(Path(td) / "wt")
+                added = _git(repo, "worktree", "add", "--detach", wt, branch)
+                if added.returncode == 0:
+                    try:
+                        report = verify(reqs_text, wt)
+                        row["requirements"] = (
+                            f"{report['summary']['pass']}/"
+                            f"{len(report['requirements'])} pass")
+                        row["requirements_ok"] = report["ok"]
+                    finally:
+                        _git(repo, "worktree", "remove", "--force", wt)
+                else:
+                    row["requirements"] = "worktree failed"
+                    row["requirements_ok"] = False
+        else:
+            row["requirements"] = "—"
+            row["requirements_ok"] = None
+        rows.append(row)
+
+    # rank: gate pass first, then requirements ok, then most fixed, fewest introduced
+    rows.sort(key=lambda r: (r["gate"] != "PASS",
+                             r["requirements_ok"] is False,
+                             -r["fixed"], r["introduced"], r["branch"]))
+    return {"base": base, "rows": rows}
+
+
+def to_markdown(scoreboard: dict) -> str:
+    lines = [f"## branch scoreboard vs `{scoreboard['base']}`", "",
+             "| branch | gate | introduced | fixed | files | requirements |",
+             "|--------|------|-----------:|------:|------:|--------------|"]
+    for r in scoreboard["rows"]:
+        lines.append(f"| {r['branch']} | **{r['gate']}** | {r['introduced']} "
+                     f"| {r['fixed']} | {r['files_changed']} | {r['requirements']} |")
+    return "\n".join(lines) + "\n"
+
+
+def main() -> None:  # pragma: no cover - CLI entrypoint
+    import argparse
+
+    ap = argparse.ArgumentParser(
+        description="gitcad explore — judge N design branches by the same gates")
+    ap.add_argument("branches", nargs="*",
+                    help="branches to score (default: all except base)")
+    ap.add_argument("--repo", default=".")
+    ap.add_argument("--base", required=True)
+    args = ap.parse_args()
+    print(to_markdown(score_branches(args.repo, args.base,
+                                     args.branches or None)))