Skip to content

Code health: introduce BuildOptions to collapse the 51-parameter build signature copied across six front doors #1927

Closed

Description

@pzfreo

Part of the code-health epic. Evidence pinned to main @ 71b8c94.

Problem

The same build options are spelled out as separate keyword parameters in six signatures, and there is no options object to share:

Signature Params Shared with build_drawing
builder.build_drawing (builder.py:2429) 51 —
builder._build_drawing_once (builder.py:1368) 51 47
builder.make_drawing (builder.py:3696) 36 36
Sheet.__init__ (sheet.py:1185) 36 32
sheet_emit.emit_sheet_script (sheet_emit.py:2376) 41 29
sheet_emit.generate_sheet_script (sheet_emit.py:2988) 35 30

So one new build option means editing about six signatures, their docstrings, and the forwarding between them. This is also where script/CLI parity bugs come from, because a parameter can be forwarded in one front door and missed in another.

Proposal

  • Add a frozen BuildOptions dataclass at the _core rank or below. It owns defaults and validation.
  • Internally, pass only BuildOptions.
  • Keep the public keyword signatures (they are the API), but have them build the dataclass once.
  • sheet_emit should serialise from BuildOptions and not keep its own list of parameters.

Acceptance

  • _build_drawing_once takes (source, options, …) and does not repeat the 47 shared parameters.
  • A test checks that every BuildOptions field is accepted by every public front door and round-trips through the emitted script. The test must fail if a field is added and not wired through.
  • Behaviour is unchanged: the golden corpus and script↔CLI parity tests stay green.

Architectural fit

ADR 1 (one engine, one front-door funnel). This needs no ADR change.

Activity

  1. added
    tech-debtInternal maintainability or refactoring work
    area:architecturePackage layering and architectural structure
    on Sep 28, 2026
  2. pzfreo commented on Sep 28, 2026

    @pzfreo
    OwnerAuthor

    Completed in #1967 (merged 007ecad0). Frozen rank-1 BuildOptions now owns shared build defaults and validation; _build_drawing_once takes the options object, while public signatures and script emission stay stable. A parity guard classifies every option across front doors. The fresh final reviewer found no actionable issue. The full local run had the 19 failures and 3 errors already present on main, plus one new test-only compatibility-import failure that was corrected and passed in focused recheck; changed-line coverage was 98%. All 17 applicable CI jobs passed on the final commit, and 14 live drawing signatures and two emitted scripts matched baseline.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:architecturePackage layering and architectural structuretech-debtInternal maintainability or refactoring work

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions