Initial Commit

openspec/changes/audio-shipped-file-size-cleanup/tasks.md

@@ -0,0 +1,82 @@
+# 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.