draftwright 0.2.6__tar.gz → 0.2.7__tar.gz

{draftwright-0.2.6 → draftwright-0.2.7}/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## v0.2.7 — 2026-07-05
+
+**The three authoring modes (ADR 0011 Amendment 1).** Naming how you drive draftwright —
+*just do it* / *auto then tweak* / *generate an editable script* — and filling in the third:
+a declarative `Sheet`-DSL generator, and number-free authoring against the build123d objects
+you built.
+
+### Added
+
+- **`draftwright part.step --script --style sheet`** — generate an **editable declarative
+  `Sheet` script** from a detected part: one commentable line per feature (hole / diameter /
+  step / slot / pattern / envelope), views noted, the auto-section flagged. Comment a line out
+  to drop that feature; the script re-runs to the drawing. The existing `--script` (imperative
+  edit-verb reconstruction) stays the default (#461).
+- **Object-reading `.cbore(tool)` / `.spotface(tool)`** on a declared hole — read the
+  counterbore/spotface's ⌀ **and** depth off the tool object + part (depth measured from the
+  local open face, so a rib/wall elsewhere doesn't skew it). A `Sheet`-declared drawing can now
+  carry **zero magic numbers** and track the geometry parametrically (#462).
+- **`Sheet.of(feature)`** — a fluent handle onto an **existing / detection-seeded** feature (by
+  the build123d object, an index, or the `Feature` itself), so you can `.fit(...)` /
+  `.tolerance(...)` a feature from `Sheet.from_part()` without re-declaring it (#463).
+
+### Docs
+
+- **ADR 0011 Amendment 1** — the three authoring modes and the mode-3 generation surface;
+  records the decision to emit **honest detected numbers** for a detected part rather than
+  fabricate a build123d reconstruction that misrepresents the geometry (#464).
+
 ## v0.2.6 — 2026-07-05
 
 **ADR 0011 — the IR as a public input: declare features, don't only detect them.**

{draftwright-0.2.6 → draftwright-0.2.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: draftwright
-Version: 0.2.6
+Version: 0.2.7
 Summary: Automated technical-drawing generation for build123d
 Project-URL: Homepage, https://github.com/pzfreo/draftwright
 Project-URL: Repository, https://github.com/pzfreo/draftwright

{draftwright-0.2.6 → draftwright-0.2.7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "draftwright"
-version = "0.2.6"
+version = "0.2.7"
 description = "Automated technical-drawing generation for build123d"
 readme = "README.md"
 license = { file = "LICENSE" }

{draftwright-0.2.6 → draftwright-0.2.7}/src/draftwright/cli.py

@@ -105,6 +105,12 @@ def main(
     script: bool = typer.Option(
         False, "--script", help="Write an editable .py drawing script instead of SVG+DXF"
     ),
+    style: str = typer.Option(
+        "imperative",
+        "--style",
+        help="--script flavour: 'imperative' (edit-verb reconstruction) or "
+        "'sheet' (declarative Sheet DSL - one line per feature)",
+    ),
     pmi: PmiMode = typer.Option(
         PmiMode.off,
         help=(
@@ -136,6 +142,9 @@ def main(
     logging.basicConfig(level=logging.INFO if verbose else logging.WARNING, format="%(message)s")
 
     formats = _parse_formats(output_format)
+    if script and style not in ("imperative", "sheet"):
+        # validate before the ~5 s engine import so a typo fails fast
+        raise typer.BadParameter("--style must be 'imperative' or 'sheet'", param_hint="--style")
 
     # Import the engine lazily, only on the build path: it pulls in build123d/OCP
     # (~5 s of CAD-kernel import). Keeping it out of module scope means shell
@@ -144,17 +153,24 @@ def main(
     from draftwright.builder import build_drawing, generate_script
 
     if script:
-        py_path = generate_script(
-            step_file=step_file,
-            out=out,
-            title=title,
-            number=number,
-            tolerance=tolerance,
-            drawn_by=drawn_by,
-            pmi=pmi.value,
-            scale=scale,
-            page=page,
-        )
+        if style == "sheet":
+            from draftwright.sheet_emit import generate_sheet_script
+
+            py_path = generate_sheet_script(
+                step_file, out=out, title=title, number=number, pmi=pmi.value
+            )
+        else:
+            py_path = generate_script(
+                step_file=step_file,
+                out=out,
+                title=title,
+                number=number,
+                tolerance=tolerance,
+                drawn_by=drawn_by,
+                pmi=pmi.value,
+                scale=scale,
+                page=page,
+            )
         print(py_path)
         return
 

{draftwright-0.2.6 → draftwright-0.2.7}/src/draftwright/model/declare.py

@@ -128,6 +128,45 @@ def _read_cylinder(obj) -> tuple[str, float, Point]:
     return axis, dia, center
 
 
+def read_bore_step(part, tool, axis: str) -> tuple[float, float]:
+    """``(diameter, depth)`` of a counterbore / spotface *tool* cut into *part* (ADR 0011 #462).
+
+    ⌀ comes from the tool's cylindrical face (like :func:`_read_cylinder`); **depth** is measured
+    along the hole *axis* from the part's **open face at the hole** to the tool's inner (floor)
+    face — so both values track the geometry you built, restating no numbers.
+
+    The open face is found *locally*: the part is intersected with an axial prism over the tool's
+    cross-section, so a rib / wall / boss elsewhere on the part doesn't skew the reading (the
+    global bounding box would). The counterbore opens on whichever end of that local column the
+    tool sits nearer, even when the tool overhangs the part."""
+    from build123d import Box, Pos
+
+    axis = _norm_axis(axis)
+    dia = _read_cylinder(tool)[1]
+    i = "xyz".index(axis)
+    tb, pb = tool.bounding_box(), part.bounding_box()
+    t_lo, t_hi = [tb.min.X, tb.min.Y, tb.min.Z][i], [tb.max.X, tb.max.Y, tb.max.Z][i]
+
+    # A prism over the tool's cross-section, spanning the part along the axis; intersect it with
+    # the part to get the LOCAL material column under the tool (the open face is its axial edge).
+    size = [tb.size.X, tb.size.Y, tb.size.Z]
+    cen = [tb.center().X, tb.center().Y, tb.center().Z]
+    size[i] = [pb.size.X, pb.size.Y, pb.size.Z][i] * 3 or 1.0
+    cen[i] = [pb.center().X, pb.center().Y, pb.center().Z][i]
+    try:
+        column = part & (Pos(*cen) * Box(*size))
+        cb = column.bounding_box()
+        p_lo, p_hi = [cb.min.X, cb.min.Y, cb.min.Z][i], [cb.max.X, cb.max.Y, cb.max.Z][i]
+    except Exception:  # noqa: BLE001 — degenerate boolean; fall back to the global bbox
+        p_lo, p_hi = [pb.min.X, pb.min.Y, pb.min.Z][i], [pb.max.X, pb.max.Y, pb.max.Z][i]
+
+    if (t_lo + t_hi) / 2 >= (p_lo + p_hi) / 2:
+        depth = p_hi - t_lo  # floor at the tool bottom, open at the max face
+    else:
+        depth = t_hi - p_lo  # floor at the tool top, open at the min face
+    return (round(dia, 3), round(depth, 3))
+
+
 def _span(at: Point, axis: str, length: float) -> tuple[Point, Point]:
     """The two axial end-points of a segment of *length* centred at *at* along *axis*."""
     idx = "xyz".index(axis)

{draftwright-0.2.6 → draftwright-0.2.7}/src/draftwright/sheet_dsl.py

@@ -23,7 +23,9 @@ deliberately **not** stubbed here, so the surface only exposes what actually dra
 
 **Hybrid.** :meth:`Sheet.from_part` seeds the declared set from *detection*, so you
 can start from the detected model and override specific features (declaration is for
-where you know better than detection, not everywhere — ADR 0011 §3).
+where you know better than detection, not everywhere — ADR 0011 §3); :meth:`Sheet.of`
+returns a fluent handle onto one of those generated features (by object, index, or the
+feature itself) so you can ``.fit(...)`` / ``.tolerance(...)`` it without re-declaring (#463).
 """
 
 from __future__ import annotations
@@ -33,12 +35,15 @@ from dataclasses import replace
 from draftwright.analysis import _solids_body
 from draftwright.builder import _coerce_model, build_drawing, detect_part_model
 from draftwright.fits import fit_class
+from draftwright.model import Feature
 from draftwright.model import boss as _boss
 from draftwright.model import envelope as _envelope
 from draftwright.model import hole as _hole
 from draftwright.model import pattern as _pattern
 from draftwright.model import slot as _slot
 from draftwright.model import step as _step
+from draftwright.model.declare import _norm_axis, _read_cylinder, _require_positive
+from draftwright.model.declare import read_bore_step as _read_bore_step
 
 
 def _parse_scale(scale):
@@ -98,6 +103,34 @@ class _Hole:
         )
         return self
 
+    def cbore(
+        self, obj=None, *, diameter: float | None = None, depth: float | None = None
+    ) -> _Hole:
+        """A counterbore on this hole. ``.cbore(cbore_cyl)`` reads its ⌀ + depth off the
+        counterbore tool object (⌀ from the cylindrical face, depth from the part + tool along
+        the hole axis — no numbers restated), or pass explicit ``.cbore(diameter=…, depth=…)``.
+        An object supplies defaults; explicit kwargs override (#462)."""
+        return self._set(cbore=self._read_step("cbore", obj, diameter, depth))
+
+    def spotface(
+        self, obj=None, *, diameter: float | None = None, depth: float | None = None
+    ) -> _Hole:
+        """A spotface on this hole — same as :meth:`cbore` but a shallow facing (#462)."""
+        return self._set(spotface=self._read_step("spotface", obj, diameter, depth))
+
+    def _read_step(self, kind, obj, diameter, depth) -> tuple[float, float]:
+        if obj is not None:
+            rd, rdp = _read_bore_step(
+                self._sheet._part, obj, self._sheet._features[self._i].frame.axis
+            )
+            diameter = rd if diameter is None else diameter
+            depth = rdp if depth is None else depth
+        if diameter is None or depth is None:
+            raise ValueError(f"{kind} needs a tool object, or explicit diameter= and depth=")
+        # same positivity guard declare.hole() applies to cbore/spotface (#452/#462 review)
+        _require_positive(**{f"{kind} diameter": diameter, f"{kind} depth": depth})
+        return (diameter, depth)
+
     def _set(self, **kw) -> _Hole:
         self._sheet._features[self._i] = replace(self._sheet._features[self._i], **kw)
         return self
@@ -168,6 +201,57 @@ class Sheet:
         self._features.append(feature)
         return self
 
+    def of(self, ref) -> _Hole | _Dim:
+        """A decoratable handle onto an **existing** feature — the hybrid seam (#463).
+
+        *ref* is a feature index, a :class:`Feature` already in :attr:`features` (e.g. seeded by
+        :meth:`from_part`), or the build123d **object** you built (matched by ⌀ + in-plane
+        position). Returns the same fluent handle the declaration verbs do, so you can
+        ``.fit(...)`` / ``.tolerance(...)`` — and, for a hole, ``.cbore(...)`` — a feature you
+        did not declare from scratch. Raises if the object matches no feature or is ambiguous."""
+        i = self._index_of(ref)
+        kind = self._features[i].kind
+        if kind == "hole":
+            return _Hole(self, i)
+        if kind in ("boss", "step"):
+            return _Dim(self, i, "diameter" if kind == "boss" else "length")
+        raise ValueError(f"of(): no aspect handle for a {kind!r} feature (holes / bosses / steps)")
+
+    def _index_of(self, ref) -> int:
+        if isinstance(ref, bool):
+            raise TypeError("of(): ref must be an index, a Feature, or a build123d object")
+        if isinstance(ref, int):
+            n = len(self._features)
+            if not -n <= ref < n:
+                raise IndexError(f"of(): feature index {ref} out of range (have {n})")
+            return ref % n
+        if isinstance(ref, Feature):
+            for i, f in enumerate(self._features):
+                if f is ref:
+                    return i
+            raise ValueError("of(): that Feature is not in this sheet's features")
+        return self._match_object(ref)
+
+    def _match_object(self, obj) -> int:
+        """The index of the declared feature the build123d *obj* refers to, by axis + ⌀ + the
+        two in-plane coordinates (the axial position is where they legitimately differ)."""
+        axis, dia, center = _read_cylinder(obj)
+        axis = _norm_axis(axis)
+        perp = [k for k in range(3) if k != "xyz".index(axis)]
+        matches = [
+            i
+            for i, f in enumerate(self._features)
+            if getattr(f, "diameter", None) is not None
+            and _norm_axis(f.frame.axis) == axis  # same axis — a cross-hole must not match
+            and abs(f.diameter - dia) <= 0.2
+            and all(abs(f.frame.origin[k] - center[k]) <= 0.5 for k in perp)
+        ]
+        if not matches:
+            raise ValueError("of(): no declared feature matches that object (⌀ + position)")
+        if len(matches) > 1:
+            raise ValueError("of(): the object matches several features — pass an index instead")
+        return matches[0]
+
     def hole(self, obj=None, **kw) -> _Hole:
         """Declare a hole from the tool cylinder you subtracted (or explicit values).
         Returns a fluent handle: ``.through()`` (default) / ``.depth(d)``."""

draftwright-0.2.7/src/draftwright/sheet_emit.py

@@ -0,0 +1,191 @@
+"""sheet_emit — the declarative ``Sheet``-DSL emitter (ADR 0011 Amendment 1, #461).
+
+Mode 3 of the three authoring modes: *generate an editable beautiful-Python script*. Walk a
+**detected** :class:`PartModel` and print a :class:`~draftwright.Sheet` script — one commentable
+line per feature — that the user edits / comments-out / extends, then re-runs.
+
+**Detected input only writes numbers (the part-seam form, ADR 0011 Amdt 1 decision).** For a STEP
+file or a recovered solid the number *is* the ground truth, so a detected value is honest. We never
+fabricate a build123d part to chase a number-free layer — a synthesised solid silently drops what
+detection didn't model (chamfers, fillets, turned profiles) yet reads as authoritative. A caller who
+*has* the objects (mode 3b) wires their real part into the seam and swaps the number lines for
+``sheet.hole(obj)`` references — the emitter's numbers are a starting point, not a ceiling.
+
+Kinds with no declarative verb yet (``step_level``/``rotational``/``pmi``) are flagged inline as
+auto-dimensioned — never silently dropped. Fidelity: the script reproduces a lint-clean drawing of
+the same features (the auto-pass runs over the declared model), not a byte copy of the detected sheet.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from build123d import Shape
+
+from draftwright.builder import detect_part_model
+
+
+def _n(v) -> float | int:
+    """A tidy number: int when integral, else rounded to 3 dp."""
+    v = round(float(v), 3)
+    return int(v) if v == int(v) else v
+
+
+def _pt(p) -> str:
+    return "(" + ", ".join(str(_n(c)) for c in p) + ")"
+
+
+def _hole_line(f) -> str:
+    kw = [f"diameter={_n(f.diameter)}", f"at={_pt(f.frame.origin)}", f'axis="{f.frame.axis}"']
+    if f.count and f.count > 1:
+        kw.append(f"count={f.count}")
+        # A count-group carries its member positions; without them the render collapses to a
+        # single hole at the anchor (fidelity loss). Patterns recompute members from the
+        # arrangement, so only a plain count-group needs them spelled out.
+        if f.members:
+            kw.append("members=[" + ", ".join(_pt(m) for m in f.members) + "]")
+    if f.cbore:
+        kw.append(f"cbore=({_n(f.cbore[0])}, {_n(f.cbore[1])})")
+    if f.spotface:
+        kw.append(f"spotface=({_n(f.spotface[0])}, {_n(f.spotface[1])})")
+    line = f"sheet.hole({', '.join(kw)})"
+    if not f.through and f.depth is not None:
+        line += f".depth({_n(f.depth)})"
+    return line
+
+
+def _member_hole_str(m) -> str:
+    """The ``hole(...)`` template for a pattern member — carries its ⌀ AND its
+    counterbore / spotface / blind-depth so a counterbored bolt circle keeps those
+    callouts on re-run (declare.hole takes depth=/through=/cbore=/spotface= kwargs)."""
+    kw = [f"diameter={_n(m.diameter)}", f"at={_pt(m.frame.origin)}", f'axis="{m.frame.axis}"']
+    if m.cbore:
+        kw.append(f"cbore=({_n(m.cbore[0])}, {_n(m.cbore[1])})")
+    if m.spotface:
+        kw.append(f"spotface=({_n(m.spotface[0])}, {_n(m.spotface[1])})")
+    if not m.through and m.depth is not None:
+        kw.append(f"depth={_n(m.depth)}")
+        kw.append("through=False")
+    return f"hole({', '.join(kw)})"
+
+
+def _feature_line(f) -> str:
+    k = f.kind
+    if k == "envelope":
+        return f"sheet.envelope()   # {_n(f.width)} × {_n(f.height)} × {_n(f.depth)}"
+    if k == "hole":
+        return _hole_line(f)
+    if k == "boss":
+        return f'sheet.diameter(diameter={_n(f.diameter)}, at={_pt(f.frame.origin)}, axis="{f.frame.axis}")'
+    if k == "step":
+        return (
+            f"sheet.step(diameter={_n(f.diameter)}, length={_n(f.length)}, "
+            f'at={_pt(f.frame.origin)}, axis="{f.frame.axis}")'
+        )
+    if k == "slot":
+        lo, hi = _n(f.lo), _n(f.hi)
+        # Derive length from the EMITTED lo/hi so hi - lo == length exactly — declare.slot()
+        # rejects the recogniser's independently-rounded (lo, hi, length) with a 1e-6 tolerance.
+        length = _n(round(float(hi) - float(lo), 3))
+        return (
+            f"sheet.slot(width={_n(f.width)}, length={length}, "
+            f'long_axis="{f.long_axis}", width_axis="{f.width_axis}", '
+            f"lo={lo}, hi={hi}, w_center={_n(f.w_center)})"
+        )
+    if k == "pattern":
+        # Defining dims for the furniture (BCD centreline / pitch / grid dims) PLUS the exact
+        # member positions. The arrangement alone can't be recomputed faithfully — the
+        # detector records no bolt-circle START ANGLE (nor a linear direction reliably) — so
+        # spelling out members= is the only fidelity-safe form (declare uses them as-is).
+        parts = [f'kind="{f.pattern}"', f"count={f.count}"]
+        if f.pattern == "bolt_circle" and f.bcd:
+            parts.append(f"bcd={_n(f.bcd)}")
+        elif f.pattern == "linear" and f.pitch:
+            parts.append(f"pitch={_n(f.pitch)}")
+        elif f.pattern == "grid" and f.grid:
+            parts.append(f"grid=({_n(f.grid[0])}, {_n(f.grid[1])}), rows={f.rows}, cols={f.cols}")
+        if f.members:
+            parts.append("members=[" + ", ".join(_pt(p) for p in f.members) + "]")
+        return f"sheet.pattern({_member_hole_str(f.member)}, " + ", ".join(parts) + ")"
+    # kinds with no declarative verb yet — the auto-pass still dimensions them.
+    return f"# {k} @ {_pt(f.frame.origin)} — auto-dimensioned (no declarative verb yet)"
+
+
+def _needs_section(model) -> bool:
+    return any(
+        f.kind == "hole" and f.frame.axis == "z" and (f.cbore or f.spotface or not f.through)
+        for f in model.features
+    )
+
+
+_HEADER = '''"""Editable drawing — generated by draftwright (declarative Sheet DSL).
+
+Each line below declares one feature. Comment a line out to drop that feature; edit a
+value freely; chain .tolerance(lo, hi) / .fit("H7") onto any diameter. Then re-run this file.
+
+The values are DETECTED off the geometry (honest for a STEP / recovered solid). If you
+built the part yourself, wire your object into the `part = …` seam and swap a numbered
+line for a reference — e.g.  sheet.hole(my_bore)  — to read the size off the object.
+"""'''
+
+
+def emit_sheet_script(model, part_expr: str, stem: str, *, title: str, number: str) -> str:
+    """The generated declarative ``Sheet`` script text for a detected *model*.
+
+    *part_expr* is the Python that binds ``part`` (a STEP ``import_step`` or a ``part = …``
+    seam); *stem* is the output basename the script exports to."""
+    needs_hole = any(f.kind in ("hole", "pattern") for f in model.features)
+    lines = [
+        _HEADER,
+        "from draftwright import Sheet",
+        *(["from draftwright.model import hole"] if needs_hole else []),
+        "",
+        part_expr,
+        "",
+        f"sheet = Sheet(part, title={title!r}, number={number!r})",
+        "",
+        "# ── Features (each line is one declared feature) ──────────────────────────────",
+        *(_feature_line(f) for f in model.features),
+        "",
+        "# ── Views ─────────────────────────────────────────────────────────────────────",
+        "# front / plan / side / iso are always produced.",
+    ]
+    if _needs_section(model):
+        lines.append("# Section A–A auto-triggers from the counterbore/blind bore above.")
+    lines += ["", f"sheet.export({stem!r})"]
+    return "\n".join(lines) + "\n"
+
+
+def generate_sheet_script(
+    step_file: str | Shape,
+    out: str | None = None,
+    *,
+    title: str | None = None,
+    number: str = "DWG-001",
+    pmi: str = "off",
+) -> str:
+    """Write a declarative ``Sheet``-DSL script for *step_file* (a STEP path or a build123d
+    object). Returns the path to the generated ``.py``. The mode-3 declarative counterpart of
+    :func:`draftwright.builder.generate_script` (which emits the imperative reconstruction).
+
+    ``pmi`` is threaded to detection so AP242 PMI features surface (flagged inline)."""
+    is_shape = isinstance(step_file, Shape)
+    stem = out or ("drawing" if is_shape else Path(step_file).stem)
+    for _ext in (".py", ".svg", ".dxf"):
+        if stem.endswith(_ext):
+            stem = stem[: -len(_ext)]
+            break
+    title = title or (Path(stem).name.replace("_", " ").upper() if not is_shape else "DRAWING")
+
+    if is_shape:
+        part_expr = "part = ...   # ← wire in your build123d object (built above)"
+    else:
+        # absolute so the generated script runs from any working directory
+        abspath = str(Path(step_file).resolve())
+        part_expr = f"from build123d import import_step\npart = import_step({abspath!r})"
+
+    model = detect_part_model(step_file, pmi=pmi)
+    script = emit_sheet_script(model, part_expr, stem, title=title, number=number)
+    py_path = f"{stem}.py"
+    Path(py_path).write_text(script, encoding="utf-8")  # the script has box-drawing / × / ← glyphs
+    return py_path

draftwright-0.2.7/tests/test_object_aspects.py

@@ -0,0 +1,89 @@
+"""Object-reading aspect verbs — the number-free 3b layer (ADR 0011 #462).
+
+`.cbore(tool)` / `.spotface(tool)` read a counterbore/spotface's ⌀ + depth off the tool
+object and the part, so the drawing layer restates no numbers and tracks the geometry.
+"""
+
+import pytest
+from build123d import Box, Cylinder, Pos
+
+from draftwright import Sheet
+from draftwright.model.declare import read_bore_step
+
+
+class TestReadBoreStep:
+    def test_top_counterbore_reads_diameter_and_depth(self):
+        part = Box(100, 70, 24) - Pos(0, 0, 0) * Cylinder(9, 40) - Pos(0, 0, 8) * Cylinder(15, 20)
+        tool = Pos(0, 0, 8) * Cylinder(15, 20)  # ⌀30, overhangs the z=12 top → depth 14
+        assert read_bore_step(part, tool, "z") == pytest.approx((30.0, 14.0))
+
+    def test_depth_measured_from_the_near_face_both_orientations(self):
+        part = Box(40, 40, 20)  # z spans -10..10
+        top = Pos(0, 0, 6) * Cylinder(8, 12)  # sits high → opens at +z (10); floor at 0 → depth 10
+        bot = Pos(0, 0, -6) * Cylinder(
+            8, 12
+        )  # sits low → opens at -z (-10); floor at 0 → depth 10
+        assert read_bore_step(part, top, "z")[1] == pytest.approx(10.0)
+        assert read_bore_step(part, bot, "z")[1] == pytest.approx(10.0)
+
+    def test_diameter_tracks_the_tool_parametrically(self):
+        part = Box(60, 60, 20)
+        assert read_bore_step(part, Pos(0, 0, 6) * Cylinder(10, 12), "z")[0] == pytest.approx(20.0)
+        assert read_bore_step(part, Pos(0, 0, 6) * Cylinder(12, 12), "z")[0] == pytest.approx(24.0)
+
+    def test_depth_is_local_not_global_bbox(self):
+        # #462 review: a rib/wall elsewhere on the axis must NOT skew the depth — the open face
+        # is found from the LOCAL part column under the tool, not the whole part bounding box.
+        base = Pos(0, 0, 2.5) * Box(60, 30, 5)  # plate z 0..5
+        wall = Pos(-25, 0, 25) * Box(10, 30, 50)  # a wall rising to z 50, away from the hole
+        tool = Pos(0, 0, 3.5) * Cylinder(7.5, 3)  # counterbore z 2..5 → true depth 3
+        lbr = (base + wall) - Pos(0, 0, 0) * Cylinder(3, 10) - tool
+        assert read_bore_step(lbr, tool, "z") == pytest.approx((15.0, 3.0))  # not (15, 5)
+
+
+class TestCboreVerb:
+    def _plate(self):
+        plate = Box(100, 70, 24)
+        bore = Pos(0, 0, 0) * Cylinder(9, 40)
+        cbore = Pos(0, 0, 8) * Cylinder(15, 20)
+        return (plate - bore - cbore), bore, cbore
+
+    def test_number_free_counterbore_renders_lint_clean(self):
+        part, bore, cbore = self._plate()
+        s = Sheet(part, title="MP")
+        s.envelope()
+        s.hole(bore).cbore(cbore)  # ⌀ + depth read off the objects — no numbers
+        dwg = s.build()
+        assert s.features[1].cbore == pytest.approx((30.0, 14.0))
+        assert [i for i in dwg.lint() if i.severity in ("warning", "error")] == []
+
+    def test_explicit_kwargs_override_the_object_read(self):
+        part, bore, cbore = self._plate()
+        s = Sheet(part)
+        s.hole(bore).cbore(cbore, depth=6)  # keep the read ⌀, override the depth
+        assert s.features[0].cbore == pytest.approx((30.0, 6.0))
+
+    def test_explicit_values_without_an_object(self):
+        s = Sheet(Box(40, 40, 10))
+        s.hole(diameter=6, at=(0, 0, 0), axis="z").cbore(diameter=12, depth=4)
+        assert s.features[0].cbore == (12, 4)
+
+    def test_needs_object_or_explicit_values(self):
+        s = Sheet(Box(40, 40, 10))
+        with pytest.raises(ValueError):
+            s.hole(diameter=6, at=(0, 0, 0), axis="z").cbore()
+
+    def test_rejects_nonpositive_cbore(self):
+        # #462 review: match declare.hole()'s positivity guard — a bad explicit value fails loud
+        s = Sheet(Box(40, 40, 10))
+        with pytest.raises(ValueError):
+            s.hole(diameter=6, at=(0, 0, 0), axis="z").cbore(diameter=-5, depth=6)
+        with pytest.raises(ValueError):
+            s.hole(diameter=6, at=(0, 0, 0), axis="z").cbore(diameter=12, depth=0)
+
+    def test_spotface_reads_off_the_tool(self):
+        part = Box(60, 60, 20)
+        sf = Pos(0, 0, 8) * Cylinder(12, 6)  # ⌀24, opens at +z(10), floor at 5 → depth 5
+        s = Sheet(part - Pos(0, 0, 0) * Cylinder(4, 40) - sf)
+        s.hole(Pos(0, 0, 0) * Cylinder(4, 40)).spotface(sf)
+        assert s.features[0].spotface == pytest.approx((24.0, 5.0))

draftwright-0.2.7/tests/test_sheet_emit.py

@@ -0,0 +1,199 @@
+"""The declarative Sheet-DSL emitter (ADR 0011 Amendment 1, #461).
+
+Generates a `Sheet(...)` script from a detected part — one commentable line per feature.
+Detected input only writes numbers (the part-seam form); we never fabricate geometry.
+"""
+
+import ast
+import math
+import os
+
+from build123d import Box, Cylinder, Pos, export_step
+
+from draftwright.builder import detect_part_model
+from draftwright.sheet_emit import emit_sheet_script, generate_sheet_script
+
+
+def _plate():
+    return Box(80, 50, 8) - Pos(20, 10, 4) * Cylinder(4, 20) - Pos(-20, 10, 4) * Cylinder(4, 20)
+
+
+def _script_for(part, part_expr="part = PART", stem="drawing", **kw):
+    return emit_sheet_script(detect_part_model(part), part_expr, stem, title="T", number="N", **kw)
+
+
+class TestEmit:
+    def test_emits_one_declarative_line_per_feature(self):
+        src = _script_for(_plate())
+        assert "sheet = Sheet(part, title='T', number='N')" in src
+        assert "sheet.hole(diameter=8" in src  # the ⌀8 holes
+        assert "sheet.envelope()" in src
+        assert src.rstrip().endswith("sheet.export('drawing')")
+
+    def test_count_group_hole_carries_its_members(self):
+        # a count>1 hole MUST emit members= with every position — without them the render
+        # collapses to a single hole at the anchor (fidelity loss). The plate has two ⌀8 holes.
+        line = next(
+            ln
+            for ln in _script_for(_plate()).splitlines()
+            if ln.startswith("sheet.hole(diameter=8")
+        )
+        call = ast.parse(line, mode="eval").body  # the sheet.hole(...) Call node
+        kw = {k.arg: k.value for k in call.keywords}
+        assert ast.literal_eval(kw["count"]) == 2
+        assert len(kw["members"].elts) == 2  # both hole positions spelled out
+
+    def test_output_is_valid_python(self):
+        # the whole emitted script must parse — a generated script that doesn't is useless
+        ast.parse(_script_for(_plate()))
+
+    def test_counterbore_flags_the_auto_section(self):
+        part = Box(60, 60, 16) - Pos(0, 0, 0) * Cylinder(4, 30) - Pos(0, 0, 4) * Cylinder(8, 12)
+        src = _script_for(part)
+        assert "cbore=(" in src  # the counterbore rides the hole line
+        assert "Section A–A auto-triggers" in src
+
+    def test_blind_hole_gets_depth(self):
+        part = Box(40, 40, 20) - Pos(0, 0, 6) * Cylinder(4, 16)  # blind ⌀8
+        src = _script_for(part)
+        assert ".depth(" in src
+
+    def _bolt_circle(self, cbore=False):
+        part = Cylinder(40, 8)
+        for i in range(6):
+            a = i * math.pi / 3
+            c = Pos(25 * math.cos(a), 25 * math.sin(a), 0)
+            part -= c * Cylinder(3, 20)
+            if cbore:
+                part -= c * Pos(0, 0, 4) * Cylinder(5, 8)
+        return part
+
+    def test_pattern_emits_the_pattern_verb(self):
+        src = _script_for(self._bolt_circle())
+        assert "sheet.pattern(hole(" in src and 'kind="bolt_circle"' in src
+
+    def test_bolt_circle_spells_out_members(self):
+        # #461 review r2: the detector records no start ANGLE, so recomputing members at angle 0
+        # rotates the holes — the emitter must spell out the real member positions.
+        line = next(
+            ln
+            for ln in _script_for(self._bolt_circle()).splitlines()
+            if ln.startswith("sheet.pattern(")
+        )
+        assert "members=[" in line and line.count("(") >= 7  # member hole + 6 positions
+
+    def test_pattern_member_keeps_its_counterbore(self):
+        # #461 review r2: a counterbored bolt circle must keep the member's cbore on re-run
+        line = next(
+            ln
+            for ln in _script_for(self._bolt_circle(cbore=True)).splitlines()
+            if ln.startswith("sheet.pattern(")
+        )
+        assert "cbore=(" in line  # on the member hole(...) template
+
+    def test_non_declarable_kind_is_flagged_not_dropped(self):
+        # a counterbored plate carries a step_level (horizontal face levels) with no Sheet verb —
+        # it must surface as an inline comment, never silently vanish
+        part = Box(100, 70, 24) - Pos(0, 0, 0) * Cylinder(9, 40) - Pos(0, 0, 8) * Cylinder(15, 20)
+        src = _script_for(part)
+        assert any(
+            ln.startswith("#") and "no declarative verb yet" in ln for ln in src.splitlines()
+        )
+
+    def test_needs_hole_import_only_when_a_pattern_is_present(self):
+        # `hole` is only imported when a pattern line references it
+        assert "from draftwright.model import hole" not in _script_for(Box(20, 20, 5))
+
+    def test_slot_line_re_runs_without_the_length_invariant_error(self):
+        # #461 review: declare.slot() checks hi - lo == length to 1e-6; the emitter must derive
+        # length from the emitted lo/hi so the generated slot line doesn't raise on re-run.
+        from draftwright import Sheet
+
+        part = Box(60, 30, 12) - Pos(0, 0, 0) * Box(20.33, 8, 20)  # off-round → stresses rounding
+        line = next(ln for ln in _script_for(part).splitlines() if ln.startswith("sheet.slot("))
+        eval(line, {"sheet": Sheet(part)})  # declare.slot() must not raise
+
+    def test_linear_pattern_spells_out_members(self):
+        # #461 review: the arrangement can't be recomputed faithfully (no reliable direction/angle),
+        # so the emitter spells out the exact member positions for every pattern kind.
+        from draftwright.model import Frame, HoleFeature, PatternFeature
+        from draftwright.sheet_emit import _feature_line
+
+        member = HoleFeature(Frame((0, 0, 0), "z"), 4.0, depth=None, through=True)
+        pat = PatternFeature(
+            frame=Frame((0, 0, 0), "z"),
+            pattern="linear",
+            count=3,
+            member=member,
+            members=((0, -10, 0), (0, 0, 0), (0, 10, 0)),
+            pitch=10,
+            direction=(0, 1, 0),
+        )
+        line = _feature_line(pat)
+        assert "members=[(0, -10, 0), (0, 0, 0), (0, 10, 0)]" in line and "pitch=10" in line
+
+
+class TestGenerate:
+    def test_step_input_emits_a_self_contained_import_seam(self, tmp_path):
+        step = tmp_path / "plate.step"
+        export_step(_plate(), str(step))
+        py = generate_sheet_script(str(step), out=str(tmp_path / "gen"))
+        src = open(py, encoding="utf-8").read()
+        assert "import_step(" in src and "part = ..." not in src
+
+    def test_shape_input_leaves_a_part_seam(self, tmp_path):
+        py = generate_sheet_script(_plate(), out=str(tmp_path / "gen"))
+        src = open(py, encoding="utf-8").read()
+        assert "part = ..." in src and "import_step(" not in src
+
+    def test_generated_step_script_round_trips_to_a_drawing(self, tmp_path):
+        # the whole point: the generated script RUNS and produces a real drawing
+        step = tmp_path / "plate.step"
+        export_step(_plate(), str(step))
+        stem = tmp_path / "gen"
+        py = generate_sheet_script(str(step), out=str(stem))
+        exec(compile(open(py, encoding="utf-8").read(), py, "exec"), {})
+        assert (tmp_path / "gen.svg").exists()
+
+    def test_title_from_basename_not_the_out_path(self, tmp_path):
+        step = tmp_path / "widget.step"
+        export_step(Box(20, 20, 5), str(step))
+        py = generate_sheet_script(str(step), out=str(tmp_path / "gen"))
+        src = open(py, encoding="utf-8").read()
+        assert "title='GEN'" in src  # basename of out, upper — not the full path
+
+    def test_step_path_is_absolute_for_cwd_independence(self, tmp_path, monkeypatch):
+        export_step(_plate(), str(tmp_path / "plate.step"))
+        monkeypatch.chdir(tmp_path)
+        py = generate_sheet_script("plate.step", out="gen")  # relative input
+        # the emitted import_step path must be absolute so the script runs from any CWD
+        import_line = next(
+            ln for ln in open(py, encoding="utf-8").read().splitlines() if "import_step(" in ln
+        )
+        path = ast.literal_eval(import_line.split("import_step(", 1)[1].rsplit(")", 1)[0])
+        assert os.path.isabs(path)  # platform-agnostic (C:\… on Windows, /… on POSIX)
+
+
+class TestCli:
+    def test_style_sheet_routes_to_the_declarative_emitter(self, tmp_path):
+        from typer.testing import CliRunner
+
+        from draftwright.cli import app
+
+        step = tmp_path / "plate.step"
+        export_step(_plate(), str(step))
+        r = CliRunner().invoke(
+            app, [str(step), "--script", "--style", "sheet", "--out", str(tmp_path / "g")]
+        )
+        assert r.exit_code == 0, r.output
+        assert "sheet.hole(" in open(tmp_path / "g.py", encoding="utf-8").read()
+
+    def test_bad_style_is_rejected(self, tmp_path):
+        from typer.testing import CliRunner
+
+        from draftwright.cli import app
+
+        step = tmp_path / "plate.step"
+        export_step(_plate(), str(step))
+        r = CliRunner().invoke(app, [str(step), "--script", "--style", "bogus"])
+        assert r.exit_code != 0

draftwright-0.2.7/tests/test_sheet_of.py

@@ -0,0 +1,81 @@
+"""sheet.of(feature) — decorate a generated/existing feature (ADR 0011, #463).
+
+Where the from_part-generated feature list and the aspect layer (P2a/P2a.2) meet: a handle
+onto an existing feature so `.fit(...)` / `.tolerance(...)` reach a feature you didn't declare
+from scratch.
+"""
+
+import pytest
+from build123d import Box, Cylinder, Pos, Rot
+
+from draftwright import Sheet
+
+
+def _shaft():
+    return (Rot(0, 90, 0) * Cylinder(4, 20)) + (Pos(15, 0, 0) * Rot(0, 90, 0) * Cylinder(6, 10))
+
+
+class TestOf:
+    def test_of_object_decorates_a_generated_step(self):
+        # the headline: from_part generates the list; .of(object).fit() decorates one, end to end
+        s = Sheet.from_part(_shaft())
+        s.of(Pos(15, 0, 0) * Rot(0, 90, 0) * Cylinder(6, 10)).fit("g6")  # the ⌀12 collar
+        dwg = s.build()
+        dias = {n: dwg._named[n].label for n in dwg._named if n.startswith("m_dia")}
+        assert any(lbl == "ø12 g6" for lbl in dias.values()), dias
+
+    def test_of_index_returns_a_decoratable_handle(self):
+        s = Sheet.from_part(Box(80, 50, 8) - Pos(20, 10, 4) * Cylinder(4, 20))
+        i = next(i for i, f in enumerate(s.features) if f.kind == "hole")
+        s.of(i).fit("H7")  # records the fit on the hole's bore ⌀
+        assert (i, "diameter") in s._tolerances
+
+    def test_of_feature_identity(self):
+        s = Sheet.from_part(_shaft())
+        step = next(f for f in s.features if f.kind == "step")
+        s.of(step).tolerance(0.0, 0.1)  # by the Feature object itself
+        assert any(k[1] == "length" for k in s._tolerances)
+
+    def test_of_hole_handle_supports_cbore(self):
+        part = Box(100, 70, 24) - Pos(0, 0, 0) * Cylinder(9, 40) - Pos(0, 0, 8) * Cylinder(15, 20)
+        s = Sheet.from_part(part)
+        i = next(i for i, f in enumerate(s.features) if f.kind == "hole")
+        s.of(i).cbore(Pos(0, 0, 8) * Cylinder(15, 20))  # the hole handle carries .cbore
+        assert s.features[i].cbore == pytest.approx((30.0, 14.0))
+
+    def test_of_unmatched_object_raises(self):
+        s = Sheet.from_part(Box(80, 50, 8) - Pos(20, 10, 4) * Cylinder(4, 20))
+        with pytest.raises(ValueError):
+            s.of(Pos(0, 0, 0) * Cylinder(3, 10))  # ⌀6 at origin — no such feature
+
+    def test_of_matches_on_axis_not_just_in_plane(self):
+        # #463 review: a same-⌀ feature on a DIFFERENT axis (a cross-hole) sharing the in-plane
+        # coords must not match — the axis is part of the identity.
+        s = Sheet(Box(40, 40, 40))
+        s.hole(diameter=8, at=(0, 0, 0), axis="z")  # the intended target
+        s.diameter(diameter=8, at=(0, 0, 0), axis="x")  # same ⌀ + in-plane, different axis
+        h = s.of(Pos(0, 0, 0) * Cylinder(4, 20))  # a z-axis tool → only the z hole
+        assert s.features[h._i].frame.axis == "z"
+
+    def test_of_ambiguous_object_raises(self):
+        s = Sheet(Box(40, 40, 30))
+        s.hole(diameter=8, at=(0, 0, 5), axis="z")
+        s.hole(diameter=8, at=(0, 0, 20), axis="z")  # same ⌀ + in-plane (0,0)
+        with pytest.raises(ValueError):
+            s.of(Pos(0, 0, 10) * Cylinder(4, 10))  # matches both → ambiguous
+
+    def test_of_non_diameter_feature_raises(self):
+        s = Sheet(Box(30, 20, 5))
+        s.envelope()
+        with pytest.raises(ValueError):
+            s.of(0)  # an envelope has no ⌀ aspect handle
+
+    def test_of_out_of_range_index_raises(self):
+        s = Sheet.from_part(Box(30, 20, 5))
+        with pytest.raises(IndexError):
+            s.of(99)
+
+    def test_of_bool_rejected(self):
+        s = Sheet.from_part(Box(30, 20, 5))
+        with pytest.raises(TypeError):
+            s.of(True)