78 lines
4.7 KiB
Markdown
78 lines
4.7 KiB
Markdown
# 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.
|