Initial Commit

openspec/changes/audio-shipped-file-size-cleanup/specs/audio-metadata/spec.md

@@ -0,0 +1,70 @@
+<!-- markdownlint-disable MD024 -->
+
+# Capability Spec Delta: audio-metadata (audio-shipped-file-size-cleanup)
+
+**Package**: `@suaveplan/audio-metadata`
+**Status**: PROPOSED
+
+> Every requirement below carries a `**Verified by:**` line at authoring time. No exceptions.
+
+## MODIFIED Requirements
+
+### Requirement: id3v2 parser source modules respect the 300-line cap
+
+The ID3v2 parser implementation MUST be split such that no single `.ts` file under `src/parsers/id3v2/` exceeds the 300-line hard cap. The public function export `parseId3v2` SHALL remain available from `@suaveplan/audio-metadata` with its existing signature and observable behavior across every supported frame type (T... text frames, TXXX user-defined text, W... URL frames, APIC attached picture, UFID file identifier, COMM comments, USLT lyrics, GEOB general encapsulated object) and every supported text encoding (ISO-8859-1, UTF-16, UTF-16BE, UTF-8) with unsynchronisation reversal applied where the header flag is set.
+
+#### Scenario: every id3v2 source file is at or under the 300-line cap
+
+- **WHEN** `find packages/audio/audio-metadata/src/parsers/id3v2 -name "*.ts" ! -name "*.test.ts" | xargs awk 'END { if (NR > 300) print FILENAME, NR }'` is run
+- **THEN** the output is empty
+
+#### Scenario: id3v2 fixture parses are unchanged
+
+- **WHEN** `parseId3v2` is invoked on the existing fixture set used by `id3v2.test.ts`
+- **THEN** every parse result is deep-equal to the pre-split result
+
+**Verified by:** `src/parsers/id3v2/id3v2.test.ts::"every supported v2.4 fixture parses to the documented shape"` AND `tests/file-size.test.ts::"every id3v2 src file is under 300 lines"`
+
+---
+
+### Requirement: id3v2 test modules respect the 500-line cap
+
+The ID3v2 test suite MUST be split such that no single `*.test.ts` file under `src/parsers/id3v2/` exceeds the 500-line hard cap. The aggregate test count across the split files SHALL be greater than or equal to the pre-split count. The residual `id3v2.test.ts` SHALL hold end-to-end fixture-parse cases; per-frame-family and per-encoding cases SHALL move to sibling files named after the family they cover.
+
+#### Scenario: every id3v2 test file is at or under the 500-line cap
+
+- **WHEN** `find packages/audio/audio-metadata/src/parsers/id3v2 -name "*.test.ts" | xargs awk 'END { if (NR > 500) print FILENAME, NR }'` is run
+- **THEN** the output is empty
+
+**Verified by:** `tests/file-size.test.ts::"every id3v2 test file is under 500 lines"` AND `tests/exports.test.ts::"aggregate id3v2 test count is greater than or equal to pre-split"`
+
+---
+
+### Requirement: mp4-atom parser modules respect the size caps
+
+The MP4 atom parser implementation MUST be split such that no `.ts` source file under `src/parsers/mp4-atom/` exceeds the 300-line cap and no `.test.ts` file exceeds the 500-line cap. The public function export `parseMp4Atom` SHALL remain available from `@suaveplan/audio-metadata` with its existing signature and observable behavior across container atoms (`ftyp`, `moov`, `mvhd`, `mdat`, `ilst`) and iTunes metadata sub-atoms.
+
+#### Scenario: every mp4-atom source file is at or under the 300-line cap
+
+- **WHEN** `find packages/audio/audio-metadata/src/parsers/mp4-atom -name "*.ts" ! -name "*.test.ts" | xargs awk 'END { if (NR > 300) print FILENAME, NR }'` is run
+- **THEN** the output is empty
+
+#### Scenario: every mp4-atom test file is at or under the 500-line cap
+
+- **WHEN** `find packages/audio/audio-metadata/src/parsers/mp4-atom -name "*.test.ts" | xargs awk 'END { if (NR > 500) print FILENAME, NR }'` is run
+- **THEN** the output is empty
+
+**Verified by:** `tests/file-size.test.ts::"every mp4-atom src file is under 300 lines"` AND `tests/file-size.test.ts::"every mp4-atom test file is under 500 lines"`
+
+---
+
+### Requirement: ogg-vorbis test modules respect the 500-line cap
+
+The Ogg-Vorbis test suite MUST be split such that no `*.test.ts` file under `src/parsers/ogg-vorbis/` exceeds the 500-line hard cap. The aggregate test count across the split files SHALL be greater than or equal to the pre-split count. The source file is already within cap and is unchanged.
+
+#### Scenario: every ogg-vorbis test file is at or under the 500-line cap
+
+- **WHEN** `find packages/audio/audio-metadata/src/parsers/ogg-vorbis -name "*.test.ts" | xargs awk 'END { if (NR > 500) print FILENAME, NR }'` is run
+- **THEN** the output is empty
+
+**Verified by:** `tests/file-size.test.ts::"every ogg-vorbis test file is under 500 lines"`