Initial Commit

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

@@ -0,0 +1,77 @@
+# OpenSpec Change: audio-shipped-file-size-cleanup
+
+- **Change ID**: audio-shipped-file-size-cleanup
+- **Packages**: `@suaveplan/audio-timeline`, `@suaveplan/audio-transport`, `@suaveplan/audio-metadata`
+- **Category**: maintenance (refactor — no behavior change)
+- **Status**: PROPOSED
+- **Date**: 2026-05-15
+- **Design**: `./design.md`
+- **Spec deltas**: `./specs/audio-timeline/spec.md`, `./specs/audio-transport/spec.md`, `./specs/audio-metadata/spec.md`
+
+---
+
+## Why
+
+A post-ship audit of the three universal audio packages flagged source and test files exceeding `CLAUDE.md` Rule §3 / `openspec/AGENTS.md` §3 (300-line hard cap on source, 500-line cap on tests):
+
+| Package | File | Lines | Cap | Over |
+|---|---|---|---|---|
+| audio-timeline | `src/engine/engine.ts` | 548 | 300 | +248 |
+| audio-timeline | `src/engine/engine.test.ts` | 819 | 500 | +319 |
+| audio-transport | `src/transport/transport.ts` | 419 | 300 | +119 |
+| audio-metadata | `src/parsers/id3v2/id3v2.ts` | 536 | 300 | +236 |
+| audio-metadata | `src/parsers/id3v2/id3v2.test.ts` | 1340 | 500 | +840 |
+| audio-metadata | `src/parsers/mp4-atom/mp4-atom.ts` | 351 | 300 | +51 |
+| audio-metadata | `src/parsers/mp4-atom/mp4-atom.test.ts` | 670 | 500 | +170 |
+| audio-metadata | `src/parsers/ogg-vorbis/ogg-vorbis.test.ts` | 803 | 500 | +303 |
+
+The 1340-line `id3v2.test.ts` (more than 2.6× the cap) is the most egregious. All eight files passed their own gates because the size budget is currently enforced by manual audit rather than a CI check.
+
+In parallel, the audit found a §7 / Rule 11 violation that was already migrated as a separate change (audio-timeline test files importing directly from `vitest` — the `bench` import was wrong-framework too and is now migrated to mitata). That work is out of scope for this proposal.
+
+## What changes
+
+- REFACTOR: Split each oversized source file at natural responsibility boundaries while preserving the **exact public API surface** (every existing `export` keeps its name, signature, and semantics).
+- REFACTOR: Split each oversized test file into co-located sibling `*.test.ts` modules, one per cohesive behavior cluster (e.g. `id3v2/frames.test.ts`, `id3v2/text-encoding.test.ts`, `id3v2/extended-header.test.ts`).
+- ADDED: Per-package barrel updates if new sub-modules are created — explicit named re-exports only (§6a).
+- ADDED: Sibling `.md` docs for any new implementation files; the original file's `.md` stays as the surface-level overview.
+- NO BEHAVIOR CHANGE. Test counts must not decrease. Coverage must remain 100/100/100/100.
+
+## Out of scope
+
+- API redesigns or new features.
+- The runner-import migration (already done in audio-timeline).
+- File-size cleanups in other packages (handled separately if needed).
+- Introducing a new CI gate for the 300/500 caps — recommended as a follow-up.
+
+## Source mapping
+
+This is a pure-genesis maintenance change; no upstream reference. The size caps come from `CLAUDE.md` (§Quality) and `openspec/AGENTS.md` §3.
+
+## Impact
+
+**Breaking changes**: none. Public API surface, package exports, and `package.json` `exports` entries are preserved verbatim. Internal sub-module paths may shift, but they were never part of the public contract.
+
+### Affected dependents
+
+The three packages are universal-tier and currently have **no published consumers** on genesis (`bunx turbo ls --filter=...@suaveplan/audio-timeline` / `audio-transport` / `audio-metadata` returns empty). Future consumers (`audio-engine-browser`, `audio-engine-server`, react-audio*) consume the public surface, which this change does not touch.
+
+- No dependents (verified by `bunx turbo ls --filter=...@suaveplan/audio-timeline`).
+- No dependents (verified by `bunx turbo ls --filter=...@suaveplan/audio-transport`).
+- No dependents (verified by `bunx turbo ls --filter=...@suaveplan/audio-metadata`).
+
+## Verification approach
+
+For each touched package:
+
+1. `bunx turbo lint typecheck test --filter=@suaveplan/<pkg>` — green.
+2. `bunx turbo test:coverage --filter=@suaveplan/<pkg>` — 100/100/100/100.
+3. `bunx turbo build --filter=@suaveplan/<pkg>` — green.
+4. `find packages/audio/<pkg>/src -name "*.ts" ! -name "*.test.ts" | xargs awk 'END { if (NR > 300) print FILENAME, NR " lines" }'` — empty.
+5. `find packages/audio/<pkg>/src packages/audio/<pkg>/tests -name "*.test.ts" | xargs awk 'END { if (NR > 500) print FILENAME, NR " lines" }'` — empty.
+6. Diff the public `exports` map in `package.json` before/after — identical.
+7. Diff `dist/` `.d.ts` files before/after — only path / source-map changes; no type-shape changes.
+
+## Follow-up
+
+Once this change archives, add a `scripts/lint/check-file-sizes.ts` CI gate so the caps are enforced automatically. That belongs in its own change — out of scope here.