Repository navigation
Description
Part of #1259.
Scope
After this PR, system-images.ts is a part of the Android driver (ADR 0063 §4). It owns no state, and does installed system images and the one a spec gets, component install, list and find (with sdkmanager, licences and the 2 GiB reserve), the image listing, tool versions, and the fit refusal message. AndroidDriver builds it in its constructor, passes it the options it needs, and delegates to it. Behaviour, messages, timeouts and files on disk do not change. removeComponent stays in the root: it uninstalls through this part and then destroys the image's seeds. componentFootprint stays a root field. hostAbiFor and AndroidLicenseNotAcceptedError stay exported from index.ts.
In short
About 427 lines of code move out of the 3,573-line driver into a file an agent reads whole. Nothing a user or a caller sees changes. A part is a file that owns its own state and takes its collaborators in an options object; it never imports index.ts.
flowchart LR
R["index.ts: AndroidDriver"] --> P["system-images.ts (new part)"]
R --> O[parts moved earlier]
P --> O
What a user would notice if this goes wrong: an install, a licence check or a removal behaves differently.
Technical spec
Facts
Commit 059a270. Line numbers are on that commit; earlier tasks of #1259 move code, so the implementer finds each name by search.
| # | Fact | Source |
|---|---|---|
| F1 | every name this task moves, at its line on 059a270 (the exact assignment of every name of the file, made from its syntax tree) | LICENSE_ACCEPT_ANSWERS at src/drivers/android/index.ts:132; ANDROID_SYSTEM_IMAGE_MIN_FREE_BYTES at src/drivers/android/index.ts:149; AndroidLicenseNotAcceptedError at src/drivers/android/index.ts:252; #noFittingImage at src/drivers/android/index.ts:1118; toolVersions at src/drivers/android/index.ts:2114; findComponent at src/drivers/android/index.ts:2244; installComponent at src/drivers/android/index.ts:2249; listComponents at src/drivers/android/index.ts:2276; #uninstall at src/drivers/android/index.ts:2313; #listedImages at src/drivers/android/index.ts:2342; #foreignAvdImageDirectories at src/drivers/android/index.ts:2372; #readIfPresent at src/drivers/android/index.ts:2395; #installedComponent at src/drivers/android/index.ts:2404; #imageReceipt at src/drivers/android/index.ts:2413; #installSystemImageOrThrow at src/drivers/android/index.ts:2431; #acceptLicenses at src/drivers/android/index.ts:2462; #sdkmanager at src/drivers/android/index.ts:2479; #installedImages at src/drivers/android/index.ts:2510; #matchingImage at src/drivers/android/index.ts:2545; #requireImage at src/drivers/android/index.ts:2563; AndroidImageTagMissingError at src/drivers/android/index.ts:3224; installedApiLevels at src/drivers/android/index.ts:3234; isVisibleEntry at src/drivers/android/index.ts:3256; compareApiLevels at src/drivers/android/index.ts:3268; systemImagePackage at src/drivers/android/index.ts:3275; systemImageVersion at src/drivers/android/index.ts:3279; packageRevision at src/drivers/android/index.ts:3283; relativeImageDirectory at src/drivers/android/index.ts:3309; readSourceProperties at src/drivers/android/index.ts:3415; sourcePropertyValue at src/drivers/android/index.ts:3426; systemImageTags at src/drivers/android/index.ts:3435; hasUnacceptedLicense at src/drivers/android/index.ts:3492 |
| F2 | a part in this folder takes an options object and is built by the driver | src/drivers/android/adb-registrar.ts:22-25, src/drivers/android/index.ts:675 |
| F3 | such a part has its own test file that builds it directly | src/drivers/android/adb-registrar.test.ts:9 |
| F4 | the folder's testing.ts is imported by index.test.ts, and the test file's shared helpers sit outside any describe |
src/drivers/android/index.test.ts:46, src/drivers/android/index.test.ts:5117-5410, src/drivers/android/index.test.ts:7306-8212 |
| F5 | Fallow fails CI on an import loop between files (circular-dependencies, default error) and on any dead-code finding |
node_modules/fallow/schema.json RulesConfig at pnpm-lock.yaml:2180; docs/internal/agent-rules/toolchain.md:51-53 |
| F6 | test-lint flags an added sibling import in a test unless a why: sits above the first describe |
.agents/scripts/test-lint.mjs:141-148 |
| F7 | the module manual is 141 lines, and manuals may have at most 150 | src/drivers/android/AGENTS.md:1-141, src/docs-manuals.test.ts:9 |
| F8 | the root tests that prove the root still reaches this part | src/drivers/android/index.test.ts:4922 "removes the image the receipt names with sdkmanager --uninstall" |
Modules touched
Searches: grep -rn of each F1 name under src/ (hits only in src/drivers/android/index.ts, src/drivers/android/index.test.ts and, for the exports index.ts keeps, their importers); ls src/drivers/android/system-images.ts (absent on 059a270).
flowchart LR
R["index.ts (changed)"] --> P["system-images.ts (new)"]
P --> E["earlier parts, data.ts"]
src/drivers/android/system-images.ts: new; the part. It imports onlydata.ts, files that exist on 059a270 and the parts of earlier tasks; anything else reaches it as an option or a callback.src/drivers/android/index.ts: builds the part, delegates, and loses the F1 names.src/drivers/android/index.test.ts: loses the tests named under Tests.src/drivers/android/system-images.test.ts: new; its tests.src/drivers/android/data.ts: takes a type two parts share, when this task moves one.src/drivers/android/testing.ts: takes any helper two test files now use.src/drivers/android/AGENTS.md: the one Files row for the parts (ADR 0063), which Android driver: adb-tools.ts, the leaf part for env, commands and device folders #1264 adds, gainssystem-images.tsand a few words; no new row (F7).src/source-hygiene.test.ts: the two Android entries of the shrink-only list take their new lengths; an entry whose file is now within its limit is removed.
Contract and event changes
none: the task moves code inside the Android driver; no file under src/contract/ and no event changes (search: git grep -n "drivers/android" src/contract gives 0 hits).
Other code on the same state
The state this part owns: no state. Searches: grep -n of each owned name in src/drivers/android/index.ts and under src/ outside the Android folder (0 hits outside). After this task the root and later tasks (#1273, #1271, #1272) reach that state only through this part's interface; none keeps a copy.
Failure modes
none: the task crosses no new boundary and writes no new state. Every call to adb, emulator, avdmanager or sdkmanager it moves keeps its arguments, environment and time limit (F1).
Rules in play
- ADR 0063 §1, "A part never calls the root": the part takes collaborators and callbacks in its options and imports no
index.ts(F5 fails a loop). - ADR 0063 §2, tests sit with the part: a test moves only when everything it asserts is made by this part; a test across parts stays in the root's tests. A part test file has one
why:above its firstdescribenaming "a part of a decomposed module" (F6). - ADR 0063 §3: a listed file that is now within its limit leaves the shrink-only list in this PR.
- Architecture rule 14, "nothing outside the directory imports a file inside it": only files in
src/drivers/android/import the part. - Architecture rule 17, "A comment starts with
why:": a moved comment that is not awhy:, or that no longer holds, is deleted. - Documentation rule 7 and
src/docs-manuals.test.ts: the manual stays within 150 lines (F7).
Tests
The seam is src/drivers/android/system-images.test.ts, a new file modelled on src/drivers/android/adb-registrar.test.ts. These 22 tests move there, each keeping its claim and cases, because everything each asserts is made by this part: src/drivers/android/index.test.ts:2412 "fails naming downloads.acceptAndroidLicenses when licenses are unaccepted and the flag is off…"; src/drivers/android/index.test.ts:2432 "recognizes the alternate 'licenses have not been accepted' sdkmanager phrasing, not just 'not …"; src/drivers/android/index.test.ts:2490 "still fails when the install is rejected again after accepting licenses"; src/drivers/android/index.test.ts:2518 "installs the google_apis image for the host ABI with no timeout of its own, and reports it ins…"; src/drivers/android/index.test.ts:2538 "reports already-installed when the image was there before sdkmanager ran"; src/drivers/android/index.test.ts:2553 "gives two installs of one package, with an uninstall between them, different receipts"; src/drivers/android/index.test.ts:2573 "fails when sdkmanager exits 0 but the image is still not installed"; src/drivers/android/index.test.ts:2588 "fails with sdkmanager's own output when the install is rejected outright"; src/drivers/android/index.test.ts:2604 "reports each percentage sdkmanager prints as progress, and nothing for a line without one"; src/drivers/android/index.test.ts:2630 "ends %s when the signal fires, and fails the install"; src/drivers/android/index.test.ts:2671 "finds the image an API level means with its receipt, and nothing for a level that is not insta…"; src/drivers/android/index.test.ts:4756 "lists two images of one API level as two entries with different variants, each with its direct…"; src/drivers/android/index.test.ts:4797 "counts an AVD in the user's AVD home that names the image as foreign, wherever its directory i…"; src/drivers/android/index.test.ts:4820 "counts every AVD in the user's AVD home that names the image, booted before or never (#241)…"; src/drivers/android/index.test.ts:4834 "finds an AVD beside a pointer file with an empty path, counts nothing for an AVD whose directo…"; src/drivers/android/index.test.ts:4852 "counts no foreign AVD when the user's AVD home is Simlock's own root, as in a daemon started f…"; src/drivers/android/index.test.ts:4866 "rejects when %s cannot be read, rather than count the AVDs there as using nothing"; src/drivers/android/index.test.ts:4882 "leaves sizeBytes out when the image directory cannot be read, and still lists the image"; src/drivers/android/index.test.ts:4895 "lists an image with the receipt installComponent returned for it, and starts no process to lis…"; src/drivers/android/index.test.ts:5494 "reports emulator, platform-tools, and command-line tools revisions from each package's source.…"; src/drivers/android/index.test.ts:5517 "names the legacy SDK tools package as tools when its sdkmanager is the one in use"; src/drivers/android/index.test.ts:5530 "omits a tool whose source.properties cannot be read". Every other test stays where it is; F8's tests stay in src/drivers/android/index.test.ts and keep proving the root reaches the part.
- The driver installs, lists and finds system images through
system-images.ts, with the same results and messages as before; cases: "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.
Done when
pnpm exec vitest run --project unit src/drivers/androidpasses, and its number of tests is the base's plus the tests this task adds.src/drivers/android/system-images.tsexists, and only files insrc/drivers/android/import it: dependency-cruiser'spast-indexrule (.dependency-cruiser.mjs:36-37), run bypnpm check, fails any import of it from outside the folder.src/drivers/android/index.tsdefines none of the F1 names, except eachDrivermethod (and otherAndroidDrivermember the core or the daemon calls), which stays and delegates; the root's field that holds the part takes a name that is not an F1 name; an F1 constant the root still uses is imported from the part.- In
src/source-hygiene.test.ts, each Android entry equals its file's new line count, or is gone when the file is within its limit. pnpm checkpasses.
Out of scope
- Any change of behaviour, message, timeout or file on disk.
- The parts of the other tasks of Split the source and test files too big for agents to read whole #1259.
- New tests for code moved unchanged that had none before: the
sdkmanager --uninstalltimeout, they\nrepeat count in#acceptLicenses,retry.hasUnacceptedLicenseandrequireImage's host-ABI tie-break stay as untested as on the base. Tests: no new test for these; the root test that proves which options the root hands the part stays, since ADR 0063 §2 makes the root's wiring its own claim (decided in delivery, pending the maintainer)
Depends on
Written by an agent.
Activity
fix(android): shrink-only lengths equal the files; the licence test t…
test(android): the driver passes its own device root to system-images…
chore(stack): merge task/1269 into task/1270 (#1270)
refactor(android): system-images.ts owns system images and components (…