Skip to content

Epic: code health after the Aug–Sep growth (structure, smells, tests, performance) #1939

Closed
17 of 17 issues completed

Description

@pzfreo

Why

In the month to 2026-09-28, src grew from 62k to 118k lines and from 66 to 123 modules. That came from 685 commits, about 24 a day. src was 10.6k lines at the end of June.

The architecture at package level still holds, and it is machine-enforced: _LAYERS has no upward-import exemptions, and ADRs 1–5 are tied to guard tests. Inside modules, though, structure has decayed:

  • God modules: from_model.py is 10.2k lines and drawing.py 6k. Seven modules take 64% of src commits.
  • Very long functions: 27 functions are over 400 lines, and 147 take 8 or more parameters.
  • Closures used as classes: loop state is captured through default arguments instead of a proper type.
  • Duplicated helpers across the linting and contract modules.
  • Untyped side-channel state stored on helper-library objects.
  • Comments that record history instead of explaining the current code.
  • A module map in the docs that no longer matches the code.

This review was read-only and done at main @ 71b8c94. All figures come from AST, grep and git scripts; each sub-issue carries its own evidence.

Sub-issues (suggested order)

Structure: highest leverage

Smells

Structure and docs (maintainer decisions)

Tests

Performance. On simple parts about 90% of build time goes to OCC work on annotation, text and title-block geometry, not on HLR or recognition.

Build times measured on main: 4–6 s warm for trivial parts, about 39 s for grm03. -m smoke took about 100 s, where the docs say 30 s.

Exit-criteria coverage to track

At main @ a6ae6de, ten src modules exceed 3,000 lines. #1928 and #1929 explicitly target drawing.py and annotations/from_model.py. Other issues touch some of the remaining files, but do not commit to reducing their module size:

Ground rules

Agreed execution decisions (2026-09-28)

Suggested exit criteria

  • No src module over about 3k lines.
  • No function over about 300 lines.
  • No closure capturing five or more default arguments.
  • Rank 0 in _LAYERS means "imports nothing in the package".

Active run status (2026-09-29)

2026-09-30 closure decision

The maintainer chose to close this epic now. Its completed structural, smell, documentation, test and accepted performance slices are merged and recorded above. #1943 and #1945 are measured exceptions, detached from the epic and left open as separate performance follow-ups. Neither issue's original measured acceptance is claimed; the current-main profiling, rejected experiments and remaining technical constraints are logged on those issues. #1937 was separately deferred after the maintainer chose to keep successful drawing output unchanged. No ADR text changed for this closure, and no new optimization or CI run was introduced.

Activity

  1. added
    tech-debtInternal maintainability or refactoring work
    roadmapUmbrella, plan, or sequencing issue
    area:architecturePackage layering and architectural structure
    on Sep 28, 2026
  2. 17 remaining items

  3. pzfreo commented on Sep 29, 2026

    @pzfreo
    OwnerAuthor

    Runner-efficient integration update (2026-09-29): the 27 active per-PR Actions runs for this epic were canceled after the maintainer reported that the full stack matrix was taking shared runners from other projects. No other project runs were touched. main requires strict current-head ci-ok for each PR, and gh stack merge cannot reuse the tip result for lower PRs. Therefore reviewed slices are now collected in one integration PR, #2102, against main; the original small PRs remain review records. Draft performance #2085 is excluded.

    Before opening #2102, the integrated head feb38bc4 passed static checks and the full local fast tier (9,909 passed, 9 skipped, 15 xfailed in 7m07s). Exact 14 CAD + 3 STEP drawing/lint/summary/decision/trace JSON matched the prior refactor-stack tip byte for byte. A fresh independent integration review found no P0–P3 findings and reran 101 targeted checks. This PR now has the only active epic GitHub CI matrix. It will squash-merge after its required current-head ci-ok passes; the source PRs will then be closed as superseded. No open work is counted as merged yet.

  4. pzfreo commented on Sep 29, 2026

    @pzfreo
    OwnerAuthor

    Status (2026-09-29): aggregate #2102 merged at 502bbc46; its post-merge main CI run 36627991793 completed successfully. To keep PR CI to one head, the next 21 reviewed commits are in PR #2103, based on 502bbc46, with auto-merge configured only after required checks pass. Local scripts/pr-check --full on e5b390e5 passed 9,913 tests, 96.01% total coverage and 98% changed-line coverage; 14 CAD + 3 STEP drawing/lint/decision/trace records match merged main exactly. A Windows-only test encoding correction at bb8e28dd passed focused/static checks and fresh review; required current-head CI is running. It adds guards for the epic's 3,000-line module / 300-line function / five-default closure exits and the six #1930 <200 functions, folds one issue-named test module (149→148), and extracts polygonal prism jobs. #1930 and #1956 close on merge if CI passes. No ADR text changed.

    #1929 was reopened because its own ~2,500-line annotation-module acceptance is still unmet on main (four modules over that threshold). Separate #1931, #1932, #1937 and #1929 follow-on slices remain local and unmerged. The build123d #1943 patch remains local at the maintainer's request; #1945 remains draft pending its no-regression gate.

  5. pzfreo commented on Sep 29, 2026

    @pzfreo
    OwnerAuthor

    2026-09-30 status after merged #2103 (12772511): its required PR CI passed, and post-merge main CI has passed lint, view-selection, remaining-2, and CTC-04 slow lanes; only remaining-1 is still running with no failure reported. The prior main run took about 90 minutes on that lane, so no next PR CI has been started while it occupies a runner.

    The next single-gate aggregate is ready locally only at eba73503 against merged main: fresh integrated architecture review clear; independent lint review found no other source defect and confirmed #1945 remains partial. scripts/pr-check --full exited 0 (9,924 passed, 9 skipped, 15 xfailed; 96.02% total and 99% changed-line coverage). Exact 14 CAD + three STEP build_drawing drawing/lint/summary/decision/trace comparisons match main 17/17. All 39 annotation modules are ≤2,500 lines and the new size guard failed under a deliberate 2,507-line mutation. Alternating paired builds across GRM03, blind-hole STEP, explicit/compare Box, and holed-slot found no reproducible combined regression. This aggregate will close #1929 after its own current-head CI passes; #1931/#1932/#1935/#1937/#1945 remain open. The literal #1945 double-lint gap and sequenced follow-up are recorded on that issue.

    A separate later local batch already combines reviewed #1931 span, #1937 shared leader commit, and #1932 exact-index slices with static/focused checks and 17/17 parity; it is not published or counted as merged. The maintainer's build123d #1943 patch remains local and unpublished as requested. No ADR text changed.

  6. pzfreo commented on Sep 30, 2026

    @pzfreo
    OwnerAuthor

    2026-09-30 status: structural/code-health work in this epic is merged, including #2108 / #2106. The two remaining in-goal issues, #1943 and #1945, do not meet their original measured performance acceptance. Fresh current-main four-workload profiling and independent audits found no material, output-preserving bbox/deepcopy patch in Draftwright-owned paths; the retired upstream text-cache candidate and smaller cache experiments did not justify a change. Fresh counted-call review found that #1945's opaque post-build hook can return the same object whether it changed lint-relevant state or not; a complete lint-once guarantee needs mutation tracking or a hook contract, and the small table-only patch had no reliable useful timing gain. No additional patch or CI run was started.

    The maintainer has been asked whether to close #1939 with #1943 and #1945 explicitly left open as measured exceptions outside the epic, or keep the epic open until their targets are met. Until that decision, the epic stays open and neither performance acceptance is claimed.

  7. pzfreo commented on Sep 30, 2026

    @pzfreo
    OwnerAuthor

    Closed by maintainer decision after all 17 retained subissues completed. #1943 and #1945 remain open as separate measured performance follow-ups; their original acceptance is explicitly unmet, as logged in this issue and each follow-up. #1937 remains a separate deferred follow-up. No ADR or successful drawing behavior changed for this disposition.

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 structureroadmapUmbrella, plan, or sequencing issuetech-debtInternal maintainability or refactoring work

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions