Skip to content

Split the source and test files too big for agents to read whole #1259

Closed
11 of 11 issues completed
Closed

Description

@V3RON

Request: #1251

Problem

A few source and test files are too big for a coding agent to read whole. Agents read them in many small sed -n ranges, each after a grep -n to find the spot. That costs tokens and turns, and an agent that sees one range at a time misses what sits next to it. In the last 10 agent sessions the worst file, src/drivers/android/index.ts, was read in 198 separate ranges.

On 059a270 22 files are over 1,400 lines (code) or 2,500 lines (tests). The worst is the Android driver: 3,573 lines, one class with 29 private fields, and an 8,442-line test file. It grew 500 lines in the week before this spec.

Who it is for

Every coding agent that builds, reviews or fixes a change in these modules: the implementer, the reviewers and bug triage.

Outcome

  • The Android driver is one composition root and ten parts that own their own state. An agent working on emulator boot reads emulator.ts and its tests, not the whole driver.
  • No file can pass 1,400 lines (code) or 2,500 (tests) without pnpm check failing. The 22 files already over may not grow, except by a visible edit to the size test's list, until their own feature splits them.
  • The Android driver behaves exactly as before.

How it works for the user

The user is an agent changing the Android driver.

flowchart LR
  A[Agent must change emulator boot] --> B[Reads the module manual's Files table]
  B --> C[Opens emulator.ts and emulator.test.ts whole]
  C --> D[Edits, runs pnpm check]
  D --> E{A file over its limit?}
  E -- no --> F[Done]
  E -- yes --> G[pnpm check fails naming the file, its lines and the limit]
  G --> H[Agent splits the file in the same change]
Loading

Before, an agent asked to change boot ran:

$ grep -n "#startEmulator\|#waitForReadiness" src/drivers/android/index.ts
$ sed -n 2880,2960p src/drivers/android/index.ts
$ sed -n 2750,2800p src/drivers/android/index.ts
... (many more ranges)

After:

$ cat src/drivers/android/emulator.ts        # about 280 lines

A file that grows past its limit fails the size test in pnpm check:

FAIL  src/source-hygiene.test.ts > tracked files > stay within their size limit
src/drivers/android/seeds.ts: 1412 lines; a code file may have at most 1400. Split it (ADR 0063).

Examples

The size test's verdict on a file. A file on the shrink-only list is one that was over its limit when the test landed.

File Lines Listed length Today After
src/core/lifecycle.ts (code) 1,400 not listed passes passes
a new code file 1,401 not listed passes fails: over 1,400
a test file x.test.ts 2,501 not listed passes fails: over 2,500
a helper test-x.ts or testing.ts 2,501 not listed passes fails: over 2,500 (counted as a test file)
src/daemon/main.ts 1,902 1,902 passes passes
src/daemon/main.ts grown 1,903 1,902 passes fails: grew past its listed length
src/daemon/main.ts grown, its listed length raised to 1,930 in the same PR 1,930 1,930 passes passes
src/daemon/main.ts shrunk 1,850 1,902 passes passes
a listed file split 1,200 1,902 passes fails: under the limit, remove it from the list
a listed file deleted none 1,902 passes fails: no such file, remove it from the list
vendor/…, website/… any not listed passes passes (not scanned)

What could go wrong

Words used

  • composition root: the one file that builds a module's parts and connects them, e.g. AndroidDriver in src/drivers/android/index.ts after this feature.
  • part: a file inside a module that owns its own state and exposes a small interface, taking its collaborators in an options object, e.g. console-ports.ts owning the port reservations.
  • leaf part: a part that calls no other part, e.g. adb-tools.ts.
  • shrink-only list: the size test's list of files that were over their limit when it landed, each with its length; a listed file may not grow past its listed length unless the same PR raises that length in the list, and it leaves the list once under its limit.
  • seed: a shut-down device Simlock keeps only to copy into new devices (ADR 0061).

Non-goals

  • Changing any behaviour of the Android driver, its messages, timeouts or files on disk.
  • Decomposing the iOS driver, daemon/main.ts, daemon/server.ts, the fleet coordinator, the lease acquisition coordinator or contract/schemas.ts. Each is a later feature from Split the source and test files too big for agents to read whole #1251, following ADR 0063.
  • Splitting the 9 test files over 2,500 lines whose code files are under 1,400 (e.g. src/cli/index.test.ts), or the 5 tests of the other listed code files. They stay on the shrink-only list for later features.
  • A Fallow rule for file length: Fallow 3.36.0 has none.

Completion conditions

  • src/drivers/android/index.ts is at most 1,400 lines and src/drivers/android/index.test.ts at most 2,500, and neither is on the shrink-only list.
  • Each of the ten parts of ADR 0063 §4 is a file in src/drivers/android/; a part whose behaviour its own tests can show has its own test file, and every test that crosses parts stays on the root.
  • pnpm check runs the size test, and its shrink-only list holds exactly the scanned files over their limit, and neither Android file.
  • src/drivers/android/AGENTS.md names every part in its Files table.
  • The whole Android test suite passes, with every test of 059a270 still present (moved or not) plus the two new ones (a pinned config hash, the per-device lock).

Open questions

none

Decisions

Shared values

Value or state Rule Written by Read by Source
Size limits 1,400 lines for a code file, 2,500 for a test file; lines as wc -l counts them #1263 every task ADR 0063 §3
Test file a name matching .test. or .spec., or a basename test-* or testing.ts; every other .ts, .tsx, .mts, .mjs, .js, .cjs file is code #1263 every task ADR 0063 §3; .dependency-cruiser.mjs:14
Scanned files tracked files under src/, ui/, e2e/, scripts/, .agents/scripts/ #1263 every task #1251's measure
Shrink-only list in src/source-hygiene.test.ts: path → length; every scanned file over its limit on the commit #1263 merges from, with its length there (22 files on 059a270); a PR raises a length only by editing that line #1263 writes; each part task lowers the Android lengths, and the task that brings a listed file within its limit removes its entry every task ADR 0063 §3
adb-tools.ts interface the scoped env, run-or-throw (DriverCrashError on a non-zero exit), a device's AVD folder and checked driver data, the adb devices scan, a bounded adb shell read, the emulator's version, the wait #1264 #1265–#1273 ADR 0063 §4; src/drivers/android/index.ts:1028, src/drivers/android/index.ts:3008
Shared types in data.ts DeviceState (moved by #1266) and SystemImage (moved by #1268) live in src/drivers/android/data.ts, beside AndroidDriverData #1266, #1268 every later task ADR 0063 §1 (a helper two parts need goes to a leaf)
The ownership answer ownership.ts runs every emu avd path query and returns its raw result: failed (with its error text) or a path, possibly blank; plus the folder comparison. Each caller keeps today's handling of each result #1265 #1266–#1273 ADR 0063 §4; src/drivers/android/index.ts:1850-1858, src/drivers/android/index.ts:2855-2868, src/drivers/android/index.ts:2050
ConsolePorts interface reserve and free a console port; one allocator per process runner, built by the root #1266 #1269, #1271, #1272 ADR 0063 §4
avd-config.ts interface config.ini merge, library profile, hardware properties, the config hash, marks write and read #1268 #1270, #1273, #1271, #1272 ADR 0063 §4
Emulator interface start (returns the process handle), wait until ready, shut down, wait for exit, log tail, stop an unowned emulator #1269 #1271, #1272 ADR 0063 §4
SystemImages interface installed images, matching image, install, find and list components, tool versions, the fit refusal message #1270 #1273, #1272 ADR 0063 §4
Catalog interface resolve a profile, the default avdmanager profile id, fitting API levels, listCatalog, resolveSpec #1273 #1272 ADR 0063 §4
DeviceTable interface get, set and delete a device's state; the per-device lock (also seed:<spec key>); listManaged; pre-root devices; reattach #1271 #1272 ADR 0063 §4
Verbs that span parts makeReady, shutdown, destroy, reclaim, estimate, removeComponent, advisories stay in the root and call the parts every part task every part task ADR 0063 §4
Android manual one Files row, Parts of AndroidDriver (ADR 0063), names every part; #1264 adds it, and each later part task adds its file to that row, so the manual stays within 150 lines #1264 adds; every later part task every part task src/drivers/android/AGENTS.md:1-141; src/docs-manuals.test.ts:9
Testing rule 6 text adds "a part of a decomposed module" as a reason for an internal-file test, and allows moving a test to the part in a behaviour-keeping change #1263 every task ADR 0063 §2

Behaviours

Behaviour (invoker, action, what it sees) Seam Cases Task
A contributor runs the size test with a file over its limit that is not listed, and it fails naming the file, its lines and the limit src/source-hygiene.test.ts code 1,400 passes, 1,401 fails; test 2,500 passes, 2,501 fails; test-x.ts and testing.ts count as tests #1263
A contributor runs the size test with a listed file, and it fails when the file grew past its listed length or no longer needs the entry src/source-hygiene.test.ts same length passes; shrunk passes; grew by one fails; under its limit fails; deleted fails #1263
The driver runs adb and emulator commands through adb-tools.ts, and the whole-driver tests see the same environment, failures and devices as before src/drivers/android/index.test.ts "boots concurrent devices on different even ports and skips ports adb shows taken"; "destroys a plain Android device after its ownership check" #1264
The driver asks ownership.ts what emu avd path answers, and the whole-driver tests see the same stops, refusals and listings as before src/drivers/android/index.test.ts "destroys a plain Android device after its ownership check"; "gates running state, processes and erasable marks on path proof" #1265
The driver reserves console ports through console-ports.ts, and the whole-driver tests see the same ports as before src/drivers/android/index.test.ts "boots concurrent devices on different even ports and skips ports adb shows taken"; "skips a console port when something listens on %s that its own adb server does not list" #1266
A caller passes adb arguments through passthrough-rules.ts, and is refused or served exactly as before src/drivers/android/passthrough-rules.test.ts "fills an emulator's serial into an adb command that names no device"; "refuses an emulator adb command that names another device, or that runs on another platform…"; "rejects a refusal with PassthroughRefusedError naming adb, never throwing it synchronously…"; "refuses kill-server, which would detach every leased emulator at once"; "refuses kill-server behind a global flag, not only in first position"; "refuses adb disconnect with or without an address, on the local CLI and through device.exec…"; and the other tests named in its task #1267
The driver writes config and marks through avd-config.ts, and gets the same files, marks and pinned config hash as before src/drivers/android/avd-config.test.ts, and src/drivers/android/index.test.ts "rewrites the mark on makeReady's early-return branch"; "captures the config hash after the library's keys are written"; a fixed config's hash equals its value on 059a270 (new) #1268
The driver boots and stops emulators through emulator.ts, and the whole-driver tests see the same launches, readiness and shutdowns as before src/drivers/android/index.test.ts "launches with the same arguments as before these options existed under the default config"; "starts the seed's boots and the copy's boot with -crash-report-mode never" #1269
The driver installs, lists and finds system images through system-images.ts, with the same results and messages as before src/drivers/android/system-images.test.ts "fails naming downloads.acceptAndroidLicenses when licenses are unaccepted and the flag is off…"; "recognizes the alternate 'licenses have not been accepted' sdkmanager phrasing, not just 'not …"; "still fails when the install is rejected again after accepting licenses"; "installs the google_apis image for the host ABI with no timeout of its own, and reports it ins…"; "reports already-installed when the image was there before sdkmanager ran"; "gives two installs of one package, with an uninstall between them, different receipts"; and the other tests named in its task #1270
The driver resolves specs and lists the catalog through catalog.ts, and gets the same profiles, fit verdicts and refusal messages as before src/drivers/android/catalog.test.ts "resolves the newest installed matching image"; "rejects a missing image naming its API level as the component, and starts no sdkmanager"; "fails a tag that is not installed for the API level as a runtime that cannot be downloaded, na…"; "gives a tagged request with no API level the newest API level that has an image of that tag…"; "fails a tag installed for no API level, with no API level named, naming the tag and no API lev…"; "lists resolvable models and installed API levels, defaulting to the newest"; and the other tests named in its task #1273
The driver lists devices and locks each one through device-table.ts, and sees the same devices, serials and order of calls as before src/drivers/android/device-table.test.ts "reports one running root AVD, one stopped root AVD and the running AVD's process"; "listManaged settles after the timeout when one serial's mark read never answers, reports that …"; "reads the erasable mark with head -c 4096, and a mark cut at that cap is read as no mark"; "listManaged passes a 30-second timeout to adb devices"; "treats an otherwise-stopped AVD as transitioning when an unattributable transitional serial is…"; "still resolves a stopped AVD as stopped when adb reports no serials at all"; and the other tests named in its task; a second call under one device's lock waits for the first, a call on another device does not (new) #1271
The driver makes seeds and copies through seeds.ts, with the same staleness, locking and cleanup as before src/drivers/android/seeds.test.ts "creates a tagged device from the host ABI's image when the tag is installed for two ABIs"; "creates a tagged device from a foreign ABI's image when that is the only image of the tag"; "fails provisioning a tagged spec whose image went missing after it resolved, offering no downl…"; "does not change the config hash when simlock.mark is present in config.ini"; "captures differing hardware properties in the config hash, proving they land before it is comp…"; "shadows a devices.xml profile with a built-in one of the same name and never applies propertie…"; and the other tests named in its task #1272
A test of the whole driver still passes through AndroidDriver after every part is moved, split between the wiring and the lifecycle test files; cases: the 99 tests that stay on the root, wiring and lifecycle src/drivers/android/index.test.ts, src/drivers/android/index-lifecycle.test.ts the 99 tests that stay on the root, wiring and lifecycle #1272

Tasks

flowchart LR
  T1[#1263 size test] --> T2[#1264 adb-tools] --> T3[#1265 ownership] --> T4[#1266 console-ports] --> T5[#1267 passthrough-rules] --> T6[#1268 avd-config] --> T7[#1269 emulator] --> T8[#1270 system-images] --> T11[#1273 catalog] --> T9[#1271 device-table] --> T10[#1272 seeds, root done]
Loading

Every part task changes src/drivers/android/index.ts and its test file, so they run one after the other.

Completion conditions → tasks: Android files under their limits and off the list → #1272. Ten parts → #1264–#1273. Size test with 20 listed files → #1263 (22 listed) and #1272 (two removed). Manual names every part → #1264 adds the parts row, each later part task adds its file to it. Whole Android suite passes → every task.

Open work in the same area:

Written by an agent.

Activity

  1. added
    feature:specSpec in progress, business and technical together.
    on Nov 4, 2026
  2. V3RON commented on Nov 4, 2026

    @V3RON
    ContributorAuthor

    Spec updated: all sections written; Android driver pilot (ADR 0063, PR #1262), size test #1263, ten part tasks #1264–#1273.

    Written by an agent.

  3. added
    feature:plannedSplit into tasks. Never picked up itself.
    and removed
    feature:specSpec in progress, business and technical together.
    on Nov 4, 2026
  4. github-actions commented on Nov 4, 2026

    @github-actions
    Contributor

    Closing: all 11 sub-issues are closed. The PR that closed the last one walks the completion conditions (delivery rule 9); reopen this if one does not hold on main. Flip its ADRs to Accepted if delivery has not.

  5. github-actions commented on Nov 4, 2026

    @github-actions
    Contributor

    Closing: all 11 sub-issues are closed. The PR that closed the last one walks the completion conditions (delivery rule 9); reopen this if one does not hold on main. Flip its ADRs to Accepted if delivery has not.

  6. V3RON commented on Nov 4, 2026

    @V3RON
    ContributorAuthor

    Delivery run

    Merged: #1262 (ADR 0063), #1274 (#1263), #1276 (#1264), #1277 (#1265), #1278 (#1266), #1279 (#1267), #1280 (#1268), #1281 (#1269), #1283 (#1270), #1284 (#1273), #1285 (#1271), #1286 (#1272)
    Parked: none
    Waiting: none
    Decided: #1270, #1273, #1271, #1272 — new tests for code moved unchanged that no test pinned on the base? → no; the root wiring tests stay (decision comments on #1283, #1284, #1285)
    Asleep: 7 min

    Written by an agent.

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

    feature:plannedSplit into tasks. Never picked up itself.

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions