Skip to content

Code health: shrink the Drawing god class (extract PDF text layer, lint orchestration, intent drain) #1928

Closed

Description

@pzfreo

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

Problem

drawing.py:655 Drawing is 5,316 lines, with 107 methods and 23 properties. It makes 98 imports inside functions (25 of them from annotations/*, and 32 separate from draftwright.model.compiled import lines). It is 1 of the 7 modules touched by 64% of all src commits in the last month (84 commits). Besides being the result object, it holds several whole subsystems:

  • The PDF text layer: _pdf_text_runs (drawing.py:5171) is 583 lines, nests 11 deep and has 12 inner functions.
  • Linting: _lint (drawing.py:4373) is about 500 lines, although linting/ is documented as the owner of lint (ADR 3). docs/architecture.md:74 says Drawing "delegates … coverage to lint", which no longer describes the code.
  • The intent drain: _drain_intents (drawing.py:3207) is 632 lines.
  • Reporting and export glue: there are also 23 compatibility properties (drawing.py:1291) and two legacy export() call shapes (drawing.py:5850).

Proposal

Move each subsystem into its own module at the correct DAG rank, and leave Drawing as a thin façade over BuildState:

  1. export_text_layer.py (or into export.py) for the PDF text runs.
  2. The _lint orchestration into linting/, so Drawing calls one entry point.
  3. The intent drain into intents.py, or a new intent_drain.py beside builder.

Do one extraction per PR, and keep behaviour byte-stable on the golden corpus.

Acceptance

  • drawing.py is under about 2k lines, with no method over 150 lines.
  • test_drawing_encapsulation still passes. _LAYERS, docs/architecture.md and the agent guide are updated in the same PR.

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

    First extraction slice merged in #1966: PDF semantic text assembly moved from Drawing into rank-2 pdf_text.py; drawing.py fell from 6,008 to 5,382 lines. Fresh independent review clear; 25 live text runs, extracted text, and reproducible PDF bytes matched; full local failures exactly matched main, changed coverage 94%, all CI green. Lint orchestration, intent drain, and the under-2,000-line acceptance remain open.

  3. pzfreo commented on Sep 28, 2026

    @pzfreo
    OwnerAuthor

    Second extraction merged in #1968 (212a1c21): Drawing._lint is a thin wrapper over rank-2 linting/orchestration.py, retaining plan compilation and explicit cache handoff. Ordered lint JSON matched six baseline drawings; independent final review found no actionable issue. The final local full run matched main's exact 19 failures and 3 errors, changed-line coverage was 99%, and all final CI jobs passed. The intent drain, the ~2,000-line Drawing target, and the 150-line method target remain open.

  4. pzfreo commented on Sep 28, 2026

    @pzfreo
    OwnerAuthor

    Third #1928 extraction merged in #1973 (7626dc96). The 632-line deferred intent drain is now in rank-5 intent_drain.py; Drawing._drain_intents is an 18-line delegate and finalize() keeps transaction snapshot/rollback/trace ownership. The new module has no reverse import into Drawing.

    Independent fresh review found no actionable issue and checked stage equivalence and intent identity. Full local preflight had 9,628 passes and exactly the unchanged main baseline's 19 failures + 3 errors, with 98.3% changed-line coverage. The PR tier was corrected to include existing deferred pattern/detail contracts; it reached 92.4% changed-line coverage in CI, and all required jobs passed. The Drawing size target remains open, and intent_drain.drain_intents remains over 300 lines under #1956.

  5. pzfreo commented on Sep 28, 2026

    @pzfreo
    OwnerAuthor

    #1998 merged as a7a50a1c after fresh independent P0–P3 review and all 17 CI checks. The drawing evidence/claim ledger moved to rank-2 drawing_evidence.py (419 lines); drawing.py fell from 4,238 to 3,885 lines. Main census: six modules still exceed 3,000 lines; 30 functions still exceed 300 lines. #1928 remains open for the remaining Drawing split. No ADR text or successful drawing behavior changed.

  6. pzfreo commented on Sep 29, 2026

    @pzfreo
    OwnerAuthor

    PR #2009 merged on main at 9c3cc033. It moved Drawing intent routing, export coordination, and state/table operations into focused owners; drawing.py fell from 3,885 to 2,994 lines. The same PR split build_once to 288 lines. Independent reviews, local gates, exact live drawing parity, and CI passed.

    #1928 remains open for its stricter target. Reviewed PR #2012 is prepared to bring drawing.py to 1,940 lines and its longest method to 149 lines, with exact parent/child drawing and ordered-lint parity; it awaits main-branch CI after rebasing onto #2009.

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