Skip to content

Code health: consolidate duplicated contract/lint helpers (finite-real, vectors, _rounded, _index_evidence) #1932

Closed

Description

@pzfreo

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

Problem

The same small helpers are reimplemented across modules:

  • Finite-real validators:

    • blend_contract._number (:33)
    • oriented_slot_contract._real (:25)
    • linting/oriented_slot_coverage._real (:48)
    • recognition_frame._strict_real (:57)
    • section_recess_contract._section_numbers (:44)

    The first two are identical except for the error text.

  • Vector helpers:

    • _dot/_cross in oriented_slot_contract.py:61,65, profile_angles.py:31,35 and linting/angular.py:178,186
    • _vector in three modules
  • _rounded = round(float(v), 3): 16 copies across linting/*_coverage.py, plus plate_correspondence.py:12.

  • _index_evidence: the same 19-line body in 9 linting/*_coverage.py modules.

  • _state: a 50-line body shared by pad_coverage.py:250 and pocket_coverage.py:199.

  • Other same-named helpers: _point is redefined in 18 modules, _state in 12 and _parameter_ids in 11.

  • Exact-key-set and equality checks: written inline five times in recogniser_contract.py (:926, 945, 951, 986, 1197), and again in section_recess_contract.py:39, inspection_contract.py:189 and oriented_slot_contract.py:246,328.

The test suite has a clone budget. src has none.

Proposal

  • Create one leaf module, for example contract_values.py, holding finite_real, vector, unit, dot, cross, exact_keys, require_equal and rounded.
  • Create a linting/_coverage_common.py for _index_evidence, _state and _point.
  • Before unifying the error text, check which tests match on it.

Acceptance

  • Each genuinely equivalent behavior among the listed helpers has one implementation at its appropriate DAG rank. Same-named helpers with different input schemas, error contracts, precision, provenance or ownership may remain separate; document the distinction.
  • Roughly 150–300 lines are removed.
  • Optional: extend the clone-shape scan to src/linting/.

Progress

#1948, #1952 and #1969 consolidated coverage, finite-real, rounding and state helpers. #1978 shares identical profile/frame cross and strict-length compensated dot arithmetic while retaining the distinct oriented-slot sum-dot and stable private keyword signatures. Remaining exact-key/point candidates still need semantic review; similar but different helpers are deliberately separate.

#2091 is open and awaiting CI, then merge after the current dependent stack: three exact three-coordinate lint point formatters share linting/_coverage_common.point3. The slice removes 12 net lines; 186 focused tests, static checks, 14-input differential/error comparison, and a load-bearing mutation passed. Independent review found no P0–P3 issue. The other exact-key and point candidates remain open for semantic review.

#2095 is open and awaiting CI: record_schemas reuses the existing fail-closed _exact_dict_keys helper in the recogniser contract. Ten input/error cases matched exactly, 114 focused tests and static checks passed, and a targeted mutation failed the new preconditioned guard. Fresh independent review found no P0–P3 issue; further helper candidates remain open.

2026-09-30 helper candidate rejected

A local attempt to alias four evaluation point-key helpers to one shared function removed only three net source lines. Fresh independent review found a callable-signature regression: the established step_analysis helper imports accept family-named keyword arguments, whereas the alias accepts only record=. The candidate was kept local and excluded from the next aggregate. Further consolidation must preserve those signatures and offer a clearer reduction than this cross-family indirection.

A second local slot/channel _state consolidation preserved the existing call signatures but measured 12 net source lines added after wrappers and imports; it was reverted. The remaining near-duplicates need a larger coherent owner reduction to improve code health.

2026-09-30 next local helper slice

On top of unpublished 0f9534c9, isolated commit 614c2b8d in /private/tmp/dw1932-legible-locations removes the duplicate _legible_locations body from annotations/hole_locations.py and reexports the existing rank-1 _core owner. Net source change is 23 lines removed. Prechange bodies, signatures, threshold and five representative outputs matched; after change the core, off-axis, and hole facade paths resolve to the same callable and preserve scale= keyword calls. The actual plan-location pass already used the _core implementation. Focused import/behavior tests passed (24), drawing-level tests passed (55), Ruff/mypy and diff check passed, and a fresh independent review found no P0–P3 issue. This is local and not merged. The remaining similarly named helpers have different error, shape, or identity semantics; the broad single-definition/line-removal acceptance remains open pending safe consolidation evidence.

The helper slice was combined with the reviewed #1935 test fold as local f8be6b91. On that exact tip, scripts/pr-check --static and the 9,938-pass fast tier (96.03% coverage) exited 0; changed-line coverage against 0f9534c9 is 100% (1/1 coverable line). The 14 CAD plus three STEP drawing/lint/decision/trace corpus matches the frozen parent byte for byte. Quiet paired workloads show no reproducible regression. The combined follow-up has no PR/CI and remains unmerged; #1932 acceptance remains open for the remaining genuinely duplicated helpers.

2026-09-30 local edge-observer consolidation

A third dependent local unit at 636a34d4 (/private/tmp/dw1939-third-local, after unpublished f8be6b91) shares the chamfer and fillet evaluation observer's expected-view, physical leader-tip, and rendered-label helpers. The prior view/leader bodies were AST-identical across families; the extracted bodies match after making the drawing dependency explicit. This removes 110 net source lines in rank-7 evaluation while keeping the physical-tip oracle independent of production placement. The two evidence modules plus evaluation tests passed 97 cases; deliberate always-true tip substitution failed the named chamfer and fillet wrong-profile guards. The integrated tip passed static, a 9,938-pass fast tier, 96.02% total coverage, 93.7% changed-line coverage against f8be6b91, and byte-identical 14 CAD plus three STEP drawing/lint/decision/trace signatures. Fresh slice and aggregate reviews found no P0–P3 issue. This is local only: no PR/CI or merge; the remaining semantically distinct helper candidates keep #1932 open.

2026-09-30 acceptance audit on proposed aggregate

On locally prepared 99c59d07, the broad source-line reduction target has been exceeded by earlier merged work (#1948 alone was net -319 src/draftwright lines by git diff --numstat), and the proposed aggregate removes additional duplicate outcome, legible-location and edge-observer bodies. The literal “each listed helper has a single definition” criterion is not met: an exact source scan still finds six top-level _index_evidence definitions, two _dot, three _vector, two _rounded, and several family-specific _state/_parameter_ids functions. The remaining same-named definitions have different schemas, error contracts, precision, ownership or independent lint semantics; the largest exact residual bodies offer only about 11 net lines of safe removal. A generic adapter solely to reduce names would add indirection and risk ADR 1/3/5 boundaries. No new source edit followed this audit. A maintainer choice between literal one-definition acceptance and one definition per equivalent behavior has been requested asynchronously; no wording or issue state changes before that answer. #1932 remains open, and the prepared aggregate is still unpublished under the GitHub branch-write approval block.

2026-09-30 seven-family coverage-state consolidation prepared

Local commit 7552b9d2 (after the unpublished revision-3 bundle) replaces seven exact placed → structured-note → suppressed → dropped → unverifiable/missing branches with calls to the existing linting._coverage_common.state owner. It removes 65 net production lines and adds no wrapper or ADR text. Family-specific recognition correspondence and typed outcomes remain local. Independent slice review caught a P3 static-contract gap; a closed six-Literal helper return type resolved it, and final review found no P0–P3 issue. Exact-head static, 273 focused tests, the 9,938-pass full fast tier (96.02% total coverage), 100% changed-line coverage for this unit (15/15), 97% for the aggregate (295/303), and byte-identical 14 CAD plus three STEP drawing/lint/decision/trace signatures passed. Deliberately forcing the shared helper to return missing failed both named blind-slot placed-outcome tests. A fresh whole-bundle review found no P0–P3 integration issue. This work is local only: no PR, CI or merge under the continuing branch-write approval rejection. The literal one-definition criterion for other semantically distinct same-named helpers remains open pending the maintainer's scope choice.

Maintainer acceptance decision (2026-09-30)

The maintainer accepted one owner per equivalent behavior, rather than one definition per shared helper name. Do not add a generic adapter merely to eliminate a name collision when semantics differ. The source-deletion and parity criteria above still apply.

Activity

  1. added
    tech-debtInternal maintainability or refactoring work
    area:recognitionFeature recognition and geometry detection
    area:lintLint, critique, reconciliation, suggestions
    on Sep 28, 2026
  2. pzfreo commented on Sep 28, 2026

    @pzfreo
    OwnerAuthor

    Third helper slice merged in #1969 (9840fe1d). It consolidates 28 exact three-decimal lint roundings and the identical finite, positive, and point blind-slot validators into shared helpers. Distinct precision/carrier variants remain local. The full local fast suite had exactly main's 19 failures and 3 errors; focused strict-value tests passed, changed-line coverage reached 100%, independent review found no actionable issue, and all final CI jobs passed. #1932 remains open for the other helper families and its overall line-removal acceptance.

  3. pzfreo commented on Sep 30, 2026

    @pzfreo
    OwnerAuthor

    Completion on merged main b5ba5564 via #2107 (17 required CI successes, two expected skips; no ADR edit). The final slice shares exact blind-slot source/span and slot/channel/flat measurement-identity behavior through linting._coverage_common, preserving the established private import names and removing 23 net production lines (merged commit git show --numstat: +31/-54 under src/draftwright). Independent slice and combined reviews cleared P0–P3, with 357 focused tests on the first two slices, 61 focused tests on the final head, static and import-boundary gates, and exact-head CI passing.

    The earlier merged #1948 alone removed 319 net src/draftwright lines (+142/-461 by git show --numstat), exceeding this issue's approximate 150–300-line reduction target; this PR adds further deletion. The final semantic audit found the listed genuinely equivalent helper behavior consolidated. Remaining same-named helpers differ in schema, error text, precision, provenance, independent judge ownership or callable signature; a few trivial two-line equal expressions remain local because a shared adapter would add cross-family coupling for negligible deletion. This follows the maintainer's accepted one-owner-per-equivalent-behavior criterion. No drawing output or compiled-plan behavior changed. Closing #1932.

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:lintLint, critique, reconciliation, suggestionsarea:recognitionFeature recognition and geometry detectiontech-debtInternal maintainability or refactoring work

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions