Initial Commit
This commit is contained in:
217
openspec/archive/2026-04-25-enterprise-compress-svg/proposal.md
Normal file
217
openspec/archive/2026-04-25-enterprise-compress-svg/proposal.md
Normal file
@@ -0,0 +1,217 @@
|
||||
# OpenSpec Change: enterprise-compress-svg
|
||||
|
||||
- **Change ID**: enterprise-compress-svg
|
||||
- **Package**: `@suaveplan/compress-svg`
|
||||
- **Category**: universal
|
||||
- **Target path**: `universal/compression/compress-svg`
|
||||
- **Status**: PROPOSED
|
||||
- **Date**: 2026-04-24
|
||||
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/compress-svg.md`
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
Deliver `@suaveplan/compress-svg` on the genesis branch from scratch at enterprise quality. The package provides SVG optimisation and minification: whitespace removal, redundant attribute stripping, path data precision reduction, element collapsing, ID mangling, viewBox normalisation, inline style to attribute conversion, and SVGO-compatible plugin pipeline. Pure TypeScript, runs in Bun/Node/browser, operates on SVG string input/output.
|
||||
|
||||
---
|
||||
|
||||
## 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 99.31% coverage.
|
||||
|
||||
---
|
||||
|
||||
## Available workspace deps on genesis
|
||||
|
||||
| Package | Role |
|
||||
|---|---|
|
||||
| `@suaveplan/error` (`workspace:^`) | Base class for `SvgCompressError`; `SVG_COMPRESS.*` codes |
|
||||
| `@suaveplan/types` (`workspace:^`) | `LoggerLike` |
|
||||
| `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 SvgCompressError extends SuaveplanError
|
||||
|
||||
interface SvgPlugin {
|
||||
name: string
|
||||
apply(node: SvgNode, options: SvgPluginOptions): SvgNode | null
|
||||
}
|
||||
|
||||
interface SvgNode {
|
||||
type: 'element' | 'text' | 'comment' | 'cdata' | 'doctype'
|
||||
name?: string
|
||||
attributes?: Record<string, string>
|
||||
children?: SvgNode[]
|
||||
value?: string
|
||||
}
|
||||
|
||||
interface CompressOptions {
|
||||
plugins?: SvgPlugin[] // default: standard plugin set
|
||||
floatPrecision?: number // decimal places for path coords; default: 3
|
||||
transformPrecision?: number // default: 5
|
||||
multipass?: boolean // default: true; run until stable
|
||||
removeComments?: boolean // default: true
|
||||
removeMetadata?: boolean // default: true
|
||||
removeDoctype?: boolean // default: true
|
||||
collapseGroups?: boolean // default: true
|
||||
mergeStyles?: boolean // default: true
|
||||
mangleIds?: boolean // default: false
|
||||
}
|
||||
|
||||
interface CompressResult {
|
||||
data: string // optimised SVG string
|
||||
originalSize: number // bytes
|
||||
compressedSize: number // bytes
|
||||
ratio: number // compressedSize / originalSize
|
||||
passCount: number // multipass iterations used
|
||||
}
|
||||
|
||||
function compressSvg(svg: string, options?: CompressOptions): CompressResult
|
||||
function parseSvg(svg: string): SvgNode
|
||||
function serializeSvg(node: SvgNode): string
|
||||
|
||||
// Built-in plugins (each independently importable)
|
||||
const removeComments: SvgPlugin
|
||||
const removeMetadata: SvgPlugin
|
||||
const removeDoctype: SvgPlugin
|
||||
const collapseGroups: SvgPlugin
|
||||
const cleanupAttrs: SvgPlugin
|
||||
const convertColors: SvgPlugin
|
||||
const convertPathData: SvgPlugin
|
||||
const convertTransforms: SvgPlugin
|
||||
const mergeStyles: SvgPlugin
|
||||
const inlineStyles: SvgPlugin
|
||||
const removeUnusedDefs: SvgPlugin
|
||||
const mangleIds: SvgPlugin
|
||||
```
|
||||
|
||||
### Presets
|
||||
|
||||
```ts
|
||||
const PRESET_DEFAULT: SvgPlugin[] // removeComments + metadata + doctype + collapseGroups + cleanupAttrs + convertPathData
|
||||
const PRESET_SAFE: SvgPlugin[] // PRESET_DEFAULT minus id-mangling and transform conversion
|
||||
const PRESET_AGGRESSIVE: SvgPlugin[] // all plugins enabled
|
||||
```
|
||||
|
||||
### Error codes
|
||||
|
||||
```ts
|
||||
type SvgCompressErrorCode =
|
||||
| 'SVG_COMPRESS_PARSE_FAILED'
|
||||
| 'SVG_COMPRESS_INVALID_SVG'
|
||||
| 'SVG_COMPRESS_PLUGIN_FAILED'
|
||||
|
||||
const SVG_COMPRESS_ERROR_METADATA: Readonly<Record<SvgCompressErrorCode, CodeMetadata>>
|
||||
function registerSvgCompressErrorCodes(): void
|
||||
```
|
||||
|
||||
### Zod schemas
|
||||
|
||||
```ts
|
||||
CompressOptionsSchema
|
||||
CompressResultSchema
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## New additions for genesis
|
||||
|
||||
1. **Streaming-safe parser** — lightweight push-parser (no DOMParser dependency) operating on string; SAX-like for large SVGs.
|
||||
2. **Plugin pipeline** — each plugin receives and returns an `SvgNode` tree; returning `null` removes the node. Plugins compose cleanly via standard array.
|
||||
3. **Multipass loop** — runs plugins until the serialised output reaches a stable size (or `multipass: false`).
|
||||
4. **OTel instrumentation** — span `svg.compress`, counter `svg_compress_total`, histogram `svg_compress_duration_ms` + `svg_compress_ratio`.
|
||||
5. **Property-based tests** — compression idempotency (compress twice = same output), `parseSvg` ↔ `serializeSvg` round-trip, ratio always ≤ 1 for any valid SVG.
|
||||
6. **Benchmark suite** — `compressSvg` on 10 kB SVG icon, 100 kB complex illustration, 1 MB map SVG.
|
||||
|
||||
---
|
||||
|
||||
## File layout
|
||||
|
||||
```text
|
||||
universal/compression/compress-svg/
|
||||
package.json
|
||||
tsconfig.json
|
||||
vitest.config.ts
|
||||
src/
|
||||
index.ts
|
||||
error-codes.ts
|
||||
constants/
|
||||
index.ts
|
||||
types/
|
||||
common.ts
|
||||
common.md
|
||||
core/
|
||||
compress-svg/
|
||||
compress-svg.ts
|
||||
compress-svg.md
|
||||
compress-svg.types.ts
|
||||
compress-svg.test.ts
|
||||
index.ts
|
||||
parser/
|
||||
svg-parser/
|
||||
svg-parser.ts
|
||||
svg-parser.md
|
||||
svg-parser.test.ts
|
||||
index.ts
|
||||
plugins/
|
||||
remove-comments/
|
||||
remove-comments.ts
|
||||
remove-comments.md
|
||||
remove-comments.test.ts
|
||||
index.ts
|
||||
remove-metadata/
|
||||
remove-metadata.ts
|
||||
remove-metadata.md
|
||||
remove-metadata.test.ts
|
||||
index.ts
|
||||
collapse-groups/
|
||||
collapse-groups.ts
|
||||
collapse-groups.md
|
||||
collapse-groups.test.ts
|
||||
index.ts
|
||||
cleanup-attrs/
|
||||
cleanup-attrs.ts
|
||||
cleanup-attrs.md
|
||||
cleanup-attrs.test.ts
|
||||
index.ts
|
||||
convert-path-data/
|
||||
convert-path-data.ts
|
||||
convert-path-data.md
|
||||
convert-path-data.test.ts
|
||||
index.ts
|
||||
convert-transforms/
|
||||
convert-transforms.ts
|
||||
convert-transforms.md
|
||||
convert-transforms.test.ts
|
||||
index.ts
|
||||
mangle-ids/
|
||||
mangle-ids.ts
|
||||
mangle-ids.md
|
||||
mangle-ids.test.ts
|
||||
index.ts
|
||||
presets/
|
||||
index.ts
|
||||
__benchmarks__/
|
||||
compress-svg.bench.ts
|
||||
tests/
|
||||
integration.test.ts
|
||||
property.test.ts
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Impact
|
||||
|
||||
**Downstream**: build pipeline tools, `@suaveplan/packer`, any SVG-heavy asset pipelines.
|
||||
**Breaking changes**: none — fresh build.
|
||||
**Prerequisites**: `@suaveplan/error`, `@suaveplan/types` published to Verdaccio.
|
||||
86
openspec/archive/2026-04-25-enterprise-compress-svg/tasks.md
Normal file
86
openspec/archive/2026-04-25-enterprise-compress-svg/tasks.md
Normal file
@@ -0,0 +1,86 @@
|
||||
# Tasks: enterprise-compress-svg
|
||||
|
||||
**Change ID**: enterprise-compress-svg
|
||||
**Package**: `@suaveplan/compress-svg`
|
||||
**Target path**: `universal/compression/compress-svg`
|
||||
**Prerequisite packages on Verdaccio**: `@suaveplan/error`, `@suaveplan/types`
|
||||
|
||||
---
|
||||
|
||||
## 1. Scaffold
|
||||
|
||||
- [x] Create directory `universal/compression/compress-svg/` with `src/`, `tests/`, `src/__benchmarks__/`, and all feature subdirectories per the layout in `proposal.md`.
|
||||
- [x] Write `package.json` at version `0.1.0` with `"type": "module"`, `"sideEffects": false`, full `exports` map, deps: `@suaveplan/error workspace:^`, `@suaveplan/types workspace:^`, `zod catalog:forms`, `@opentelemetry/api catalog:observability`.
|
||||
- [x] Write `tsconfig.json` extending `@suaveplan/typescript-config/library.json`.
|
||||
- [x] Write `vitest.config.ts` using `createTestConfig()` from `@suaveplan/testing/config`.
|
||||
- [x] Add `lint`, `typecheck`, `test`, `test:coverage`, `build`, `docs:check` scripts.
|
||||
|
||||
---
|
||||
|
||||
## 2. Types + errors
|
||||
|
||||
- [x] Write `src/types/common.ts` — `SvgNode`, `SvgPlugin`, `CompressOptions`, `CompressResult` interfaces.
|
||||
- [x] Write `src/types/common.md`.
|
||||
- [x] Write `src/error-codes.ts` — `SvgCompressErrorCode`, `SVG_COMPRESS_ERROR_METADATA`, `registerSvgCompressErrorCodes()`.
|
||||
- [x] Write Zod schemas: `CompressOptionsSchema`, `CompressResultSchema`.
|
||||
|
||||
---
|
||||
|
||||
## 3. Parser
|
||||
|
||||
- [x] Implement `parseSvg(svg: string): SvgNode` — push-based SAX-like parser; no DOMParser dependency; handles element, text, comment, cdata, doctype nodes; throws `SvgCompressError(SVG_COMPRESS_PARSE_FAILED)` on malformed input.
|
||||
- [x] Implement `serializeSvg(node: SvgNode): string` — compact serialiser.
|
||||
- [x] Write `svg-parser.test.ts` (≤500 lines): round-trip for various SVG structures, malformed input throws.
|
||||
- [x] Write `svg-parser.md`.
|
||||
|
||||
---
|
||||
|
||||
## 4. Plugins (one task each — each ≤300 lines)
|
||||
|
||||
- [x] `removeComments` — remove `type: 'comment'` nodes. Tests + md.
|
||||
- [x] `removeMetadata` — remove `<metadata>` elements. Tests + md.
|
||||
- [x] `removeDoctype` — remove `type: 'doctype'` nodes. Tests + md.
|
||||
- [x] `collapseGroups` — merge single-child `<g>` elements, hoisting attrs. Tests + md.
|
||||
- [x] `cleanupAttrs` — remove redundant/default attributes (e.g. `fill="black"` when it's the SVG default). Tests + md.
|
||||
- [x] `convertPathData` — reduce decimal precision in `d` attribute to `floatPrecision` places. Tests + md.
|
||||
- [x] `convertTransforms` — collapse and simplify `transform` attribute matrices. Tests + md.
|
||||
- [x] `mangleIds` — replace `id` values with short sequential identifiers. Tests + md.
|
||||
|
||||
---
|
||||
|
||||
## 5. Presets
|
||||
|
||||
- [x] Write `src/presets/index.ts` — `PRESET_DEFAULT`, `PRESET_SAFE`, `PRESET_AGGRESSIVE`.
|
||||
|
||||
---
|
||||
|
||||
## 6. Main compressSvg function
|
||||
|
||||
- [x] Implement `compressSvg(svg, options): CompressResult` — parse → apply plugin pipeline → multipass loop until stable → serialize → return result with ratio.
|
||||
- [x] Wire OTel: span `svg.compress`, counter `svg_compress_total`, histogram `svg_compress_duration_ms` + `svg_compress_ratio`.
|
||||
- [x] Write `compress-svg.test.ts` (≤500 lines): each preset, multipass, custom plugin, parse error.
|
||||
- [x] Write `compress-svg.md`.
|
||||
|
||||
---
|
||||
|
||||
## 7. Benchmarks
|
||||
|
||||
- [x] Write `src/__benchmarks__/compress-svg.bench.ts` — 10 kB SVG, 100 kB SVG, 1 MB SVG.
|
||||
|
||||
---
|
||||
|
||||
## 8. Tests
|
||||
|
||||
- [x] Write `tests/integration.test.ts` — PRESET_DEFAULT on real SVG files (inline fixtures).
|
||||
- [x] Write `tests/property.test.ts` (fast-check) — idempotency, parse↔serialize round-trip, ratio ≤ 1.
|
||||
|
||||
---
|
||||
|
||||
## 9. Docs + verify + publish
|
||||
|
||||
- [x] All co-located `.md` files (≥200 words each).
|
||||
- [x] Write `README.md` at package root.
|
||||
- [x] `bunx turbo lint typecheck test --filter=@suaveplan/compress-svg` — green.
|
||||
- [x] `bunx turbo test:coverage --filter=@suaveplan/compress-svg` — 100%.
|
||||
- [x] `bun scripts/publish.ts --package @suaveplan/compress-svg`.
|
||||
- [x] Archive to `openspec/archive/2026-04-24-enterprise-compress-svg/`.
|
||||
Reference in New Issue
Block a user