Initial Commit

openspec/archive/2026-04-19-enterprise-barcode/proposal.md

@@ -0,0 +1,59 @@
+# OpenSpec Change: enterprise-barcode
+
+- **Change ID**: enterprise-barcode
+- **Package**: `@suaveplan/barcode`
+- **Category**: universal
+- **Target path**: `universal/media/barcode`
+- **Status**: PROPOSED
+- **Date**: 2026-04-19
+- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/barcode.md`
+
+## Summary
+
+Greenfield rebuild of `@suaveplan/barcode` — dependency-free barcode generator and reader with support for Code 39, Code 93, Code 128, ITF, EAN-13, UPC-A, Data Matrix, PDF417. Pure-TS encoders/decoders; no native bindings. Ships a `BarcodeGenerator`, `readBarcode`, and `generateBatch`.
+
+## Current-state audit (genesis)
+
+Package does not exist yet — fresh build.
+
+## Dependencies
+
+- Workspace: `@suaveplan/error`, `@suaveplan/types`
+- External (via catalog): `zod`, `tslib`, `@opentelemetry/api`
+- Dev (via catalog): `vitest`, `@vitest/coverage-istanbul`, `fast-check`, `mitata`
+
+## Preserved public surface
+
+### Generator / reader
+
+- `BarcodeGenerator`, `calculateEan13CheckDigit`, `calculateUpcaCheckDigit`
+- `readBarcode`, `ReadResult`
+- `generateBatch`, `BatchItem`, `BatchItemResult`, `BatchOptions`, `BatchResult`
+
+### Formats
+
+- Code 93: `encodeCode93`, `validateCode93`
+- Data Matrix: `encodeDataMatrix`, `validateDataMatrix`, `DataMatrixOptions`, `DataMatrixResult`
+- ITF: `calculateItfCheckDigit`, `encodeItf`, `validateItf`
+- PDF417: `encodePdf417`, `validatePdf417`, `Pdf417Options`, `Pdf417Result`
+
+### Errors
+
+- `BarcodeError`, `BarcodeErrorCode`, `BarcodeErrorContext`, `BARCODE_ERROR_METADATA`, `registerBarcodeErrorCodes`
+- `checksumFailed`, `decodeFailed`, `encodeFailed`, `imageInvalid`, `invalidData`, `invalidFormat`, `unsupportedCharacter`
+
+### Types / constants
+
+`BarcodeFormat`, `BarcodeOptions`, `BarcodeResult`, `CODE39_CHARS`, `DEFAULT_BARCODE_OPTIONS`, `VALID_FORMATS`.
+
+## New genesis additions
+
+- Extend code registry with `BARCODE.BATCH_PARTIAL` for partial batch failures.
+- Zod schemas for every option type.
+- OTel counter `barcode.encode.total{format, outcome}`, `barcode.decode.total{format, outcome}`; histograms for durations.
+- Property tests: `readBarcode(BarcodeGenerator.generate(x)) === x` for every format on valid payloads.
+
+## Impact
+
+- Adds one new package: `universal/media/barcode`
+- Adds one new spec capability: `barcode`

openspec/archive/2026-04-19-enterprise-barcode/specs/barcode/spec.md

@@ -0,0 +1,41 @@
+# Capability Spec: barcode
+
+**Package**: `@suaveplan/barcode`
+**Version**: 0.0.0 (genesis)
+**Status**: ADDED
+
+---
+
+## ADDED Requirements
+
+### BC-01 — Supported formats
+
+The package MUST implement encoders (and where image decoding applies, decoders) for Code 39, Code 93, Code 128, ITF, EAN-13, UPC-A, Data Matrix, PDF417. `VALID_FORMATS` MUST enumerate these.
+
+### BC-02 — Encoder contract
+
+`BarcodeGenerator.generate(data, options)` MUST validate the input characters for the chosen format, compute any required check digit (EAN-13, UPC-A, ITF via `calculateItfCheckDigit`), and return `BarcodeResult { bars, width, height, svg?, png? }`. Unsupported characters MUST throw `BARCODE.UNSUPPORTED_CHARACTER`.
+
+### BC-03 — Reader contract
+
+`readBarcode(image)` MUST accept `Uint8Array`, `ImageData`, `Blob`, or `File` and return `ReadResult { format, data, confidence }`. Decode failures MUST throw `BARCODE.DECODE_FAILED`.
+
+### BC-04 — Check-digit helpers
+
+`calculateEan13CheckDigit(digits)` and `calculateUpcaCheckDigit(digits)` MUST compute standard GTIN-13 / GTIN-12 mod-10 check digits. Round-trip tests MUST cover each.
+
+### BC-05 — Batch
+
+`generateBatch(items, options)` MUST return `BatchResult { succeeded, failed, total, items }`. Partial failure MUST NOT abort the batch; each failed item MUST carry its original error.
+
+### BC-06 — Data Matrix
+
+`encodeDataMatrix(data, options)` MUST choose the minimum square symbol size that fits the payload and emit the corresponding Reed-Solomon error-correction codewords.
+
+### BC-07 — PDF417
+
+`encodePdf417(data, options)` MUST accept `errorCorrectionLevel` 0–8 per the PDF417 specification. The encoder MUST emit valid start/stop patterns and row indicators.
+
+### BC-08 — Observability
+
+Each encode / decode MUST record `barcode.encode.total{format, outcome}` or `barcode.decode.total{format, outcome}` and the corresponding duration histogram.

openspec/archive/2026-04-19-enterprise-barcode/tasks.md

@@ -0,0 +1,40 @@
+# Tasks: enterprise-barcode
+
+## 1. Scaffold
+
+- [x] 1.1 `universal/media/barcode/`; 100/100/100/100; guard tests; CLAUDE/README/FOLDERS.
+
+## 2. Errors + schemas
+
+- [x] 2.1 `src/error-codes.ts` + `src/errors/barcode-errors.ts` — full error set.
+- [x] 2.2 Zod schemas.
+
+## 3. Formats
+
+- [x] 3.1 Code 39 + Code 93 + Code 128.
+- [x] 3.2 ITF (interleaved 2 of 5) + EAN-13 + UPC-A with check-digit helpers.
+- [x] 3.3 Data Matrix encoder (Reed-Solomon).
+- [x] 3.4 PDF417 encoder.
+- [x] 3.5 Co-located `.md` + unit + fuzz tests per format.
+
+## 4. Generator
+
+- [x] 4.1 `src/generator/barcode-generator.ts` — format dispatch + rendering to SVG/PNG.
+
+## 5. Reader
+
+- [x] 5.1 `src/reader/barcode-reader.ts` — `readBarcode` (image scan pipeline).
+
+## 6. Batch
+
+- [x] 6.1 `src/batch/batch-generator.ts` — `generateBatch` with partial-failure reporting.
+
+## 7. Docs / barrel / subpath exports / README
+
+## 8. Benchmarks
+
+- [x] 8.1 Encode / decode benchmarks per format.
+
+## 9. Ship gate
+
+- [x] 9.1 Verification sequence; fold + archive.