Skip to content

Code health: extract a placement-candidate type and decompose the >1,000-line functions #1930

Closed

Description

@pzfreo

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

Problem

Very long functions are doing the job of classes by using closures:

Function Lines Notes
detect.build_part_model (model/detect.py:1571) 1,365
leaders.place_feature_leader_jobs (annotations/leaders.py:1675) 1,318 14 inner defs; greedy alone is 407 lines
builder.build_drawing (builder.py:2429) 1,246 nesting depth 8, 16 inner defs
analysis._analyse (analysis.py:1069) 906
holes._place_queue (annotations/holes.py:2767) 735 17 params
_common.place_strip_candidates (annotations/_common.py:3540) 685 27 params

Package-wide, 222 functions are over 100 lines, 67 over 200 and 27 over 400. 147 functions take 8 or more parameters.

from_model.py has 154 nested defs. 36 of them capture loop state as five or more default arguments. For example, _retry(nm=nm, _v=_v, _s=_s, _zones=_zones, … _routed_build=_routed_build) at from_model.py:10085 captures 14. The same _build/_drop/_retry trio is redefined for each pass: 9 _build, 8 _drop and 5 _retry in from_model.py, plus holes.py:983, :2703 and :3208. That trio is a placement-candidate type that nobody has extracted.

Proposal

  • Introduce one typed placement-candidate protocol or dataclass (build / drop / retry) in annotations/_common.py, and move the passes onto it.
  • Break the mega-functions into named, testable steps, starting with place_feature_leader_jobs and build_drawing.

Progress

  • Type through-step placement candidate state (#1930) #1985 replaced the through-step leg placement closure trio with typed state. The number of closures in from_model.py capturing five or more default arguments fell from 29 to 26 on that slice; the module-wide and six-function limits remain open. Fresh review, exact live parity, changed-line coverage, and CI passed.

  • Decompose analysis pipeline into ordered stages #1997 decomposed analysis._analyse from 906 to 99 lines into ordered handoff stages. Fresh review, local/CI gates, script parity, and 14 live golden signatures passed; five named functions and the closure limit remain open.

  • Extract feature leader placement phases #2019 extracted primary candidate classification, bounded pair conflicts, and provisional refinement from leaders.place_feature_leader_jobs on main at abb7d600: 1,318 to 1,191 lines. Its nested greedy remains 407 lines. Fresh review, local/CI gates, 14 live drawing signatures, and three STEP drawing/lint/leader-trace signatures passed; the <200-line and closure targets remain open.

  • The atomic Extract greedy feature leader selection phases (#1930) #2027/Extract settled feature-leader fixed ink lowering owner #2036 leader stack lowered place_feature_leader_jobs from 1,191 to 975 lines and its nested greedy from 407 to 191, while leaders.py reached 2,758 lines. The moved fixed-ink owner remains rank 4. Fresh independent reviews, 14 drawing signatures, three pinned STEP drawing/lint/trace signatures, changed-line coverage, and protected-main CI passed. The <200-line place_feature_leader_jobs and closure limits remain open.

  • Extract hole queue obstacle evidence phase (#1930) #2093 is open against the current #2088 stack: the hole queue's page-space obstacle evidence is a typed phase, reducing _place_queue from 237 to 182 AST lines. Static and 202 focused tests passed; 14 CAD and three STEP build_drawing drawing/lint/decision/trace JSON snapshots match the parent exactly. Fresh independent review found no P0–P3 issue; CI and the other named function/closure exits remain open.

  • Extract typed height-ladder rung callbacks (#1930) #2096 is open against the current #2088 stack: the height-ladder rung build, footprint, and drop callbacks moved to a frozen typed candidate. Their captured-default counts fell from 11, 6, and 5 to zero; a named guard rejects reintroduction. Static/focused gates, exact 17 CAD/STEP signatures, detailed CAD/STEP lint/decision/trace parity, and fresh independent review passed. CI and the remaining closure/function exits remain open.

Acceptance

  • No closure captures five or more default arguments. Add a small AST guard for this, or add the rule to the review checklist.
  • The six named functions are each under 200 lines.
  • The golden corpus is unchanged.

Completion (2026-09-29)

PR #2103 merged at 12772511 after local full fast-tier, required current-head CI, exact 14 CAD + three STEP drawing/lint/decision/trace parity, and fresh independent review. On merged main, the six named functions measure 159, 168, 101, 99, 178, and 121 physical lines in the table order above. The new tests/test_source_shape.py guard passes and rejects a nested callback with five or more default captures; it also guards the 3,000-line module and 300-line function limits. No ADR text changed.

Activity

  1. added
    tech-debtInternal maintainability or refactoring work
    area:layoutLayout, placement, scale/page, strips, repack
    on Sep 28, 2026
  2. pzfreo commented on Sep 29, 2026

    @pzfreo
    OwnerAuthor

    Next closure slice: #2100 is open against the reviewed #2084 stack tip. Two five-default circular-channel location callbacks are now bound methods of one frozen typed geometry state. A fresh independent review found no P0–P3 findings; focused/static/mutation checks and exact 14 CAD + 3 STEP parity passed, plus two STEP seat fixtures that exercise m_seatloc_x0. Required GitHub CI is pending. The issue's remaining large-default closures and named-function acceptance stay open.

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:layoutLayout, placement, scale/page, strips, repacktech-debtInternal maintainability or refactoring work

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions