Files
2026-05-27 23:29:53 +01:00

6.0 KiB

Tasks — audio-shipped-file-size-cleanup

Every checkbox MUST reflect work actually done in this change. No behavior change is permitted.

0. Pre-flight (non-negotiable)

  • 0.1 Confirm clean working tree (git status reports nothing) and no in-flight worktrees with uncommitted work (git worktree list then git status in each)
  • 0.2 If any worktrees exist under .claude/worktrees/, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (git worktree remove) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
  • 0.3 Confirm the package set in MANIFEST.md matches find packages -maxdepth 3 -name package.json count. Drift here means a prior change archived without regenerating the manifest.

1. Pre-flight

  • 1.1 Capture baseline: bunx turbo lint typecheck test:coverage build --filter=@suaveplan/audio-timeline --filter=@suaveplan/audio-transport --filter=@suaveplan/audio-metadata — record green output.
  • 1.2 Snapshot dist/**/*.d.ts for the three packages to a temp dir for post-split comparison.
  • 1.3 Capture each package's package.json exports map for post-split comparison.

2. @suaveplan/audio-timeline — engine.ts split

  • 2.1 Extract src/engine/engine-tracks.ts + .md + .test.ts from engine.ts (track CRUD helpers).
  • 2.2 Extract src/engine/engine-clips.ts + .md + .test.ts (clip CRUD helpers).
  • 2.3 Extract src/engine/engine-mixer.ts + .md + .test.ts (mixer mutation helpers).
  • 2.4 Extract src/engine/engine-transport.ts + .md + .test.ts (transport helpers).
  • 2.5 Shrink engine.ts to delegating shell (≤300 lines); keep public class export at src/engine/index.ts unchanged.
  • 2.6 Shrink engine.test.ts to construction / adapter wiring / snapshot / undo-redo / event cases only (≤500 lines).
  • 2.7 Verify: bunx turbo lint typecheck test:coverage build --filter=@suaveplan/audio-timeline green; test count ≥ pre-split count.
  • 2.8 Diff dist/**/*.d.ts vs baseline — only path / source-map changes, no type-shape changes.

3. @suaveplan/audio-transport — transport.ts split

  • 3.1 Extract src/transport/transport-schedule.ts + .md (schedule/cancel/lookahead helpers).
  • 3.2 Extract src/transport/transport-tempo.ts + .md (BPM + tempo automation helpers).
  • 3.3 Shrink transport.ts to delegating shell (≤300 lines).
  • 3.4 Verify: bunx turbo lint typecheck test:coverage build --filter=@suaveplan/audio-transport green; test count unchanged.
  • 3.5 Diff dist/**/*.d.ts vs baseline — no type-shape changes.

4. @suaveplan/audio-metadata — id3v2.ts split (largest)

  • 4.1 Extract src/parsers/id3v2/id3v2-header.ts + .md + .test.ts (header / extended header parsing).
  • 4.2 Extract src/parsers/id3v2/id3v2-text-encoding.ts + .md + .test.ts (ISO-8859-1 / UTF-16 / UTF-16BE / UTF-8 decoders).
  • 4.3 Extract src/parsers/id3v2/id3v2-unsync.ts + .md + .test.ts (unsynchronisation reversal).
  • 4.4 Extract src/parsers/id3v2/id3v2-frames-text.ts + .md + .test.ts (T... / TXXX text frame decoders).
  • 4.5 Extract src/parsers/id3v2/id3v2-frames-binary.ts + .md + .test.ts (APIC / UFID / GEOB binary frame decoders).
  • 4.6 Extract src/parsers/id3v2/id3v2-frames-url.ts + .md + .test.ts (W... URL frame decoders).
  • 4.7 Shrink id3v2.ts to public parseId3v2() + frame-dispatch only (≤300 lines).
  • 4.8 Shrink id3v2.test.ts to end-to-end fixture parses only (≤500 lines).
  • 4.9 Verify: per-file split tests cover the same code paths; aggregate test count ≥ pre-split (1340-line file's tests redistributed, none deleted).

5. @suaveplan/audio-metadata — mp4-atom.ts + tests split

  • 5.1 Extract src/parsers/mp4-atom/mp4-atom-itunes.ts + .md + .test.ts (iTunes/ilst decoders).
  • 5.2 Shrink mp4-atom.ts to public parseMp4Atom() + container walker (≤300 lines).
  • 5.3 Shrink mp4-atom.test.ts to container + non-iTunes tests (≤500 lines).

6. @suaveplan/audio-metadata — ogg-vorbis.test.ts split

  • 6.1 Extract src/parsers/ogg-vorbis/ogg-vorbis-frames.test.ts (frame-level tests).
  • 6.2 Shrink ogg-vorbis.test.ts to page parsing + comment header tests (≤500 lines).

7. Per-package verification (post-split)

  • 7.1 bunx turbo lint typecheck test:coverage build --filter=@suaveplan/audio-timeline — 100/100/100/100.
  • 7.2 bunx turbo lint typecheck test:coverage build --filter=@suaveplan/audio-transport — 100/100/100/100.
  • 7.3 bunx turbo lint typecheck test:coverage build --filter=@suaveplan/audio-metadata — 100/100/100/100.
  • 7.4 File-size sweep: find packages/audio/audio-timeline/src packages/audio/audio-transport/src packages/audio/audio-metadata/src -name "*.ts" ! -name "*.test.ts" | xargs awk 'END { if (NR > 300) print FILENAME, NR " lines" }' — empty.
  • 7.5 Test-size sweep: same find ... -name "*.test.ts" ... with cap 500 — empty.
  • 7.6 Diff package.json exports maps vs baseline — identical for all three packages.
  • 7.7 Diff dist/**/*.d.ts vs baseline — only path/source-map changes.

8. Per-package docs refresh

  • 8.1 Update MANIFEST.md via bun scripts/folder-reorg/generate-manifest.ts (new sub-modules surfaced).
  • 8.2 No STATUS.md change — packages remain ✅ Completed.
  • 8.3 bunx markdownlint-cli2 --fix over touched files; re-stage; verify exit 0 without --fix.

9. Archive

  • 9.1 Fold specs/audio-timeline/spec.md, specs/audio-transport/spec.md, and specs/audio-metadata/spec.md into the canonical openspec/specs/<capability>/spec.md files.
  • 9.2 Move openspec/changes/audio-shipped-file-size-cleanup/ → openspec/archive/YYYY-MM-DD-audio-shipped-file-size-cleanup/.

10. Follow-up (separate change)

  • 10.1 Open a tooling-add-file-size-ci-gate change that adds scripts/lint/check-file-sizes.ts (run from bunx turbo lint) so the 300/500 caps are enforced automatically. Out of scope here.