Initial Commit
This commit is contained in:
172
openspec/changes/enterprise-font-decompress/proposal.md
Normal file
172
openspec/changes/enterprise-font-decompress/proposal.md
Normal file
@@ -0,0 +1,172 @@
|
||||
# OpenSpec Change: enterprise-font-decompress
|
||||
|
||||
- **Change ID**: enterprise-font-decompress
|
||||
- **Package**: `@suaveplan/font-decompress`
|
||||
- **Category**: universal
|
||||
- **Target path**: `universal/compression/font-decompress`
|
||||
- **Status**: PROPOSED
|
||||
- **Date**: 2026-04-24
|
||||
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/font-decompress.md`
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
Deliver `@suaveplan/font-decompress` on the genesis branch from scratch at enterprise quality. The package provides font decompression and extraction: WOFF2-to-TTF expansion, WOFF-to-TTF expansion, glyph enumeration, codepoint-to-glyph mapping extraction, and font metadata reading. Counterpart to `@suaveplan/font-compress`. Pure TypeScript; binary font operations delegate to an injectable `FontDecompressAdapter`.
|
||||
|
||||
---
|
||||
|
||||
## Current-state audit (genesis)
|
||||
|
||||
The package does not exist on genesis yet — this is a fresh build. No prior source, no test results, no coverage data. The main-branch package had 95%+ coverage.
|
||||
|
||||
---
|
||||
|
||||
## Available workspace deps on genesis
|
||||
|
||||
| Package | Role |
|
||||
|---|---|
|
||||
| `@suaveplan/error` (`workspace:^`) | Base class for `FontDecompressError`; `FONT_DECOMPRESS.*` codes |
|
||||
| `@suaveplan/types` (`workspace:^`) | `LoggerLike`, `Clock` |
|
||||
| `@suaveplan/mime` (`workspace:^`) | Font MIME-type detection |
|
||||
| `@suaveplan/font-compress` (`workspace:^`) | `FontFormat`, `FontMetadata` shared types |
|
||||
| `zod` (`catalog:forms`) | Zod schemas for all public option types |
|
||||
| `@opentelemetry/api` (`catalog:observability`) | Spans + counters |
|
||||
|
||||
Dev deps: `vitest`, `@vitest/coverage-istanbul`, `fast-check`, `mitata` (all `catalog:testing`).
|
||||
|
||||
---
|
||||
|
||||
## Public API
|
||||
|
||||
### Core types
|
||||
|
||||
```ts
|
||||
class FontDecompressError extends SuaveplanError
|
||||
|
||||
interface GlyphInfo {
|
||||
id: number
|
||||
unicode: number | null
|
||||
name: string | null
|
||||
}
|
||||
|
||||
interface CmapEntry {
|
||||
codepoint: number
|
||||
glyphId: number
|
||||
}
|
||||
|
||||
interface DecompressResult {
|
||||
data: Uint8Array
|
||||
format: FontFormat // re-exported from @suaveplan/font-compress
|
||||
mimeType: string
|
||||
originalSize: number
|
||||
decompressedSize: number
|
||||
}
|
||||
|
||||
interface FontDecompressAdapter {
|
||||
readonly supportedInputFormats: readonly FontFormat[]
|
||||
probe(data: Uint8Array): Promise<FontMetadata>
|
||||
decompress(data: Uint8Array): Promise<DecompressResult>
|
||||
enumerateGlyphs(data: Uint8Array): Promise<GlyphInfo[]>
|
||||
getCmapTable(data: Uint8Array): Promise<CmapEntry[]>
|
||||
}
|
||||
|
||||
interface FontDecompressorOptions {
|
||||
adapter: FontDecompressAdapter
|
||||
logger?: LoggerLike
|
||||
clock?: Clock
|
||||
}
|
||||
|
||||
class FontDecompressor {
|
||||
constructor(options: FontDecompressorOptions)
|
||||
probe(data: Uint8Array): Promise<FontMetadata>
|
||||
decompress(data: Uint8Array, signal?: AbortSignal): Promise<DecompressResult>
|
||||
enumerateGlyphs(data: Uint8Array, signal?: AbortSignal): Promise<GlyphInfo[]>
|
||||
getCmapTable(data: Uint8Array, signal?: AbortSignal): Promise<CmapEntry[]>
|
||||
}
|
||||
|
||||
function createFontDecompressor(options: FontDecompressorOptions): FontDecompressor
|
||||
```
|
||||
|
||||
### Error codes
|
||||
|
||||
```ts
|
||||
type FontDecompressErrorCode =
|
||||
| 'FONT_DECOMPRESS_UNSUPPORTED_FORMAT'
|
||||
| 'FONT_DECOMPRESS_PARSE_FAILED'
|
||||
| 'FONT_DECOMPRESS_DECODE_FAILED'
|
||||
| 'FONT_DECOMPRESS_INVALID_INPUT'
|
||||
|
||||
const FONT_DECOMPRESS_ERROR_METADATA: Readonly<Record<FontDecompressErrorCode, CodeMetadata>>
|
||||
function registerFontDecompressErrorCodes(): void
|
||||
```
|
||||
|
||||
### Zod schemas
|
||||
|
||||
```ts
|
||||
GlyphInfoSchema
|
||||
CmapEntrySchema
|
||||
DecompressResultSchema
|
||||
FontDecompressorOptionsSchema
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## New additions for genesis
|
||||
|
||||
1. **`FontDecompressAdapter` interface** — codec-agnostic; `NullFontDecompressAdapter` ships for unit tests.
|
||||
2. **`getCmapTable`** — extracts the Unicode cmap (platform 3, encoding 1) as an array of `CmapEntry` — useful for building glyph-to-character lookup tables without full font parse.
|
||||
3. **Shared types re-export** — `FontFormat`, `FontMetadata` re-used from `@suaveplan/font-compress`; no duplication.
|
||||
4. **`AbortSignal` propagation** — every async method; throws `FontDecompressError(FONT_DECOMPRESS_DECODE_FAILED)` on abort.
|
||||
5. **OTel instrumentation** — span `font.decompress`, counter `font_decompress_total`, histogram `font_decompress_duration_ms`.
|
||||
6. **Property-based tests** — decompressed size ≥ original size for WOFF/WOFF2, glyph count > 0 for non-empty font.
|
||||
7. **Benchmark suite** — decompress 50 kB WOFF2, enumerate glyphs from 200 kB TTF.
|
||||
|
||||
---
|
||||
|
||||
## File layout
|
||||
|
||||
```text
|
||||
universal/compression/font-decompress/
|
||||
package.json
|
||||
tsconfig.json
|
||||
vitest.config.ts
|
||||
src/
|
||||
index.ts
|
||||
error-codes.ts
|
||||
constants/
|
||||
index.ts
|
||||
types/
|
||||
common.ts
|
||||
common.md
|
||||
core/
|
||||
font-decompressor/
|
||||
font-decompressor.ts
|
||||
font-decompressor.md
|
||||
font-decompressor.types.ts
|
||||
font-decompressor.test.ts
|
||||
index.ts
|
||||
adapters/
|
||||
null-adapter/
|
||||
null-adapter.ts
|
||||
null-adapter.md
|
||||
null-adapter.test.ts
|
||||
index.ts
|
||||
utils/
|
||||
format-detect.ts
|
||||
format-detect.md
|
||||
format-detect.test.ts
|
||||
__benchmarks__/
|
||||
font-decompress.bench.ts
|
||||
tests/
|
||||
integration.test.ts
|
||||
property.test.ts
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Impact
|
||||
|
||||
**Downstream**: font inspection tools, `@suaveplan/react-font-decompress` React layer.
|
||||
**Breaking changes**: none — fresh build.
|
||||
**Prerequisites**: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/mime`, `@suaveplan/font-compress` published to Verdaccio.
|
||||
78
openspec/changes/enterprise-font-decompress/tasks.md
Normal file
78
openspec/changes/enterprise-font-decompress/tasks.md
Normal file
@@ -0,0 +1,78 @@
|
||||
# Tasks: enterprise-font-decompress
|
||||
|
||||
**Change ID**: enterprise-font-decompress
|
||||
**Package**: `@suaveplan/font-decompress`
|
||||
**Target path**: `universal/compression/font-decompress`
|
||||
**Prerequisite packages on Verdaccio**: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/mime`, `@suaveplan/font-compress`
|
||||
|
||||
---
|
||||
|
||||
## 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. Scaffold
|
||||
|
||||
- [ ] Create directory `universal/compression/font-decompress/` with `src/`, `tests/`, `src/__benchmarks__/`, and all feature subdirectories per the layout in `proposal.md`.
|
||||
- [ ] Write `package.json` at version `0.1.0` with `"type": "module"`, `"sideEffects": false`, full `exports` map, deps: `@suaveplan/error workspace:^`, `@suaveplan/types workspace:^`, `@suaveplan/mime workspace:^`, `@suaveplan/font-compress workspace:^`, `zod catalog:forms`, `@opentelemetry/api catalog:observability`.
|
||||
- [ ] Write `tsconfig.json` extending `@suaveplan/typescript-config/library.json`.
|
||||
- [ ] Write `vitest.config.ts` using `createTestConfig()` from `@suaveplan/testing/config`.
|
||||
- [ ] Add `lint`, `typecheck`, `test`, `test:coverage`, `build`, `docs:check` scripts.
|
||||
|
||||
---
|
||||
|
||||
## 2. Types + errors
|
||||
|
||||
- [ ] Write `src/types/common.ts` — `GlyphInfo`, `CmapEntry`, `DecompressResult`, `FontDecompressAdapter`, `FontDecompressorOptions`. Re-export `FontFormat`, `FontMetadata` from `@suaveplan/font-compress`.
|
||||
- [ ] Write `src/types/common.md`.
|
||||
- [ ] Write `src/error-codes.ts` — `FontDecompressErrorCode`, `FONT_DECOMPRESS_ERROR_METADATA`, `registerFontDecompressErrorCodes()`.
|
||||
- [ ] Write Zod schemas: `GlyphInfoSchema`, `CmapEntrySchema`, `DecompressResultSchema`, `FontDecompressorOptionsSchema`.
|
||||
|
||||
---
|
||||
|
||||
## 3. NullFontDecompressAdapter
|
||||
|
||||
- [ ] Implement `NullFontDecompressAdapter` — `probe` returns fixture metadata, `decompress` returns input bytes with a fixture result (decompressedSize = originalSize * 1.2), `enumerateGlyphs` returns N fixture glyphs, `getCmapTable` returns N fixture cmap entries.
|
||||
- [ ] Write `null-adapter.test.ts` and `null-adapter.md`.
|
||||
|
||||
---
|
||||
|
||||
## 4. Utils
|
||||
|
||||
- [ ] Implement `detectFontFormat` (re-use pattern from font-compress, delegates to `@suaveplan/mime`).
|
||||
- [ ] Write `format-detect.test.ts` and `format-detect.md`.
|
||||
|
||||
---
|
||||
|
||||
## 5. FontDecompressor
|
||||
|
||||
- [ ] Implement `FontDecompressor` — `probe`, `decompress`, `enumerateGlyphs`, `getCmapTable` delegate to adapter; wire `AbortSignal`.
|
||||
- [ ] Wire OTel: span `font.decompress`, counter `font_decompress_total`, histogram `font_decompress_duration_ms`.
|
||||
- [ ] Write `font-decompressor.test.ts` (≤500 lines): each method, abort, unsupported format throws.
|
||||
- [ ] Write `font-decompressor.md`.
|
||||
|
||||
---
|
||||
|
||||
## 6. Benchmarks
|
||||
|
||||
- [ ] Write `src/__benchmarks__/font-decompress.bench.ts` — decompress 50 kB WOFF2 (null adapter), enumerate glyphs 200 kB TTF.
|
||||
|
||||
---
|
||||
|
||||
## 7. Tests
|
||||
|
||||
- [ ] Write `tests/integration.test.ts`.
|
||||
- [ ] Write `tests/property.test.ts` (fast-check) — decompressed size ≥ original, glyph count > 0.
|
||||
|
||||
---
|
||||
|
||||
## 8. Docs + verify + publish
|
||||
|
||||
- [ ] All co-located `.md` files (≥200 words each).
|
||||
- [ ] Write `README.md` at package root.
|
||||
- [ ] `bunx turbo lint typecheck test --filter=@suaveplan/font-decompress` — green.
|
||||
- [ ] `bunx turbo test:coverage --filter=@suaveplan/font-decompress` — 100%.
|
||||
- [ ] `bun scripts/publish.ts --package @suaveplan/font-decompress`.
|
||||
- [ ] Archive to `openspec/archive/2026-04-24-enterprise-font-decompress/`.
|
||||
Reference in New Issue
Block a user