67 lines
2.3 KiB
Markdown
67 lines
2.3 KiB
Markdown
# utils-spec-conformance
|
|
|
|
- **Change ID**: utils-spec-conformance
|
|
- **Package**: `@suaveplan/utils`
|
|
- **Status**: PROPOSED
|
|
- **Type**: spec-conformance
|
|
- **Date**: 2026-04-26
|
|
|
|
## Why
|
|
|
|
The folded `openspec/specs/utils/spec.md` documented the public surface as
|
|
`### ./errors`, `### ./debug`, `### ./object`, … module sections with bullet
|
|
lists of function signatures. The conformance parser only sees `###
|
|
Requirement: <name>` or `### CAP-NN —` headings, so the audit reported "0
|
|
requirements parsed". The implementation already satisfies every clause;
|
|
this change makes them machine-checkable and pins each scenario to existing
|
|
tests.
|
|
|
|
## What changes
|
|
|
|
- Rewrite `openspec/specs/utils/spec.md` from `./<module>` section headings
|
|
to ten `### Requirement: <name>` blocks, one per module:
|
|
- debug logger with bounded dedup buffer
|
|
- object utilities (type guards, deepMerge, pick/omit, flattenObject,
|
|
getNestedValue, deepClone)
|
|
- platform detection with injectable adapter
|
|
- IEEE 754 float packing and range constants
|
|
- pseudorandom array selection
|
|
- provider-aware email normalization
|
|
- sound-sprite parsing and variation selection
|
|
- string utilities (id generation, link extraction)
|
|
- hex string validation
|
|
- byte-size enforcement and parsing
|
|
|
|
- Add `**Verified by:**` lines under every requirement naming concrete
|
|
`it(...)` titles in the corresponding `*.test.ts` files (10 test files,
|
|
169 cases pre-dating this change).
|
|
- No source changes; no public-surface changes.
|
|
|
|
## Out of scope
|
|
|
|
- New behaviour. Heading rewrite + verification annotation only.
|
|
- `errors` is not a separate requirement block — error semantics are
|
|
asserted via the codes raised in each module's requirement (object
|
|
prototype-pollution, random empty/oob, validation size/parse, platform
|
|
unavailable, sound no-variations).
|
|
- Source mapping table — `@suaveplan/utils` is genesis-original.
|
|
|
|
## Verification approach
|
|
|
|
Every requirement is pinned to existing `it(...)` titles in:
|
|
|
|
- `src/debug/debug.test.ts`
|
|
- `src/object/object.test.ts`
|
|
- `src/platform/platform.test.ts`
|
|
- `src/number/number.test.ts`
|
|
- `src/random/pseudo.test.ts`
|
|
- `src/email/email.test.ts`
|
|
- `src/sound/sound.test.ts`
|
|
- `src/string/string.test.ts`
|
|
- `src/validate/validate.test.ts`
|
|
- `src/validation/size.test.ts`
|
|
|
|
## Migration impact
|
|
|
|
None — additive metadata only. Public surface unchanged.
|