suaveplan/openspec/archive/2026-05-09-i18n-icu-parser/tasks.md

Tasks — @suaveplan/i18n-icu-parser (ICU parser, interpolation, pluralization)

Reconciled retroactively after Wave 2 shipped under commit cd86db44. Package is built, tested, and validated; this pass folds the spec delta into openspec/specs/i18n-icu-parser/spec.md and archives the change folder. All **Verified by:** paths in the spec have been confirmed to exist in packages/i18n/i18n-icu-parser/src/.

1. Spec authoring

• 1.1 Cross-cutting design + AGENTS sections read
• 1.2 Source-mapping table populated
• 1.3 proposal.md authored
• 1.4 specs/i18n-icu-parser/spec.md delta drafted with 7 requirements
• 1.5 Every requirement carries a **Verified by:** line
• 1.6 openspec change validate i18n-icu-parser clean

2. Package scaffold

• 2.1 packages/i18n/i18n-icu-parser/src/{parser,interpolation,pluralization,observability}/ structure
• 2.2 package.json — @suaveplan/i18n-icu-parser@0.0.0, type: module, sideEffects: false, deps include @suaveplan/i18n-shared/@suaveplan/error/@suaveplan/types/@opentelemetry/api
• 2.3 tsconfig.lib.json extends shared library config
• 2.4 vite.config.ts + vitest.config.ts
• 2.5 README.md with Modules table

3. Implementation — parser

• 3.1 src/parser/message.ts — ICU MessageFormat AST parser (text / variable / plural / select / unclosed-brace rejection)
• 3.2 src/parser/message-render.ts — AST → string with FormatBridge dispatch
• 3.3 src/parser/format-bridge.ts — FormatBridge interface + noopFormatBridge fallback

4. Implementation — interpolation

• 4.1 src/interpolation/interpolation.ts — variable substitution with maxDepth, escape options
• 4.2 src/interpolation/escape-html.ts — 5-char HTML escape
• 4.3 src/interpolation/escape-regex.ts — regex meta-char escape

5. Implementation — pluralization

• 5.1 src/pluralization/pluralization.ts — CLDR plural rules across covered locales (English, Welsh, ...) with PLURAL_RULE_NOT_FOUND for unknown locales

6. Implementation — observability

• 6.1 src/observability/metrics.ts — OTel counters/histograms

7. Root barrel + subpath exports

• 7.1 src/index.ts — explicit named re-exports (no export *)
• 7.2 package.json exports map covers root + parser/interpolation/pluralization subpaths

8. Documentation

• 8.1 Sibling .md per implementation file
• 8.2 README links every .md

9. Tests (runner-neutral imports)

• 9.1 parser/message.test.ts — text/variable/plural/unclosed-brace
• 9.2 parser/message-render.test.ts — bridge dispatch + fallback
• 9.3 parser/format-bridge.test.ts — noop bridge
• 9.4 interpolation/interpolation.test.ts — substitution, depth, escape
• 9.5 interpolation/escape-html.test.ts + escape-regex.test.ts
• 9.6 pluralization/pluralization.test.ts — English + Welsh + unknown-locale throw
• 9.7 index.test.ts — every documented subpath resolves
• 9.8 observability/metrics.test.ts
• 9.9 Every it(...) carries { timeout: 5000 }
• 9.10 Runner-neutral imports — CLAUDE.md §11 grep clean

10. Pre-archive verification

• 10.1 Biome clean
• 10.2 bunx turbo lint typecheck test --filter=@suaveplan/i18n-icu-parser green at commit time
• 10.3 bunx turbo test:coverage --filter=@suaveplan/i18n-icu-parser 100/100/100/100 at commit time
• 10.4 Conformance script clean
• 10.5 Build green

11. Pre-archive 7-row checklist

• 11.1 Generics threaded — FormatBridge interface; AST nodes typed
• 11.2 Zod schemas — N/A (parser operates on string; no boundary)
• 11.3 Error codes — INTERPOLATION_ERROR, PLURAL_RULE_NOT_FOUND, NESTING_DEPTH_EXCEEDED consumed from i18n-shared
• 11.4 Strict-mode tested
• 11.5 OTel — counters + histograms
• 11.6 Lifecycle dedup — N/A (pure functions)
• 11.7 No retroactive tick — boxes ticked during reconciliation pass after honest audit

12. Archive

• 12.1 Spec delta folded into openspec/specs/i18n-icu-parser/spec.md (canonical, status ACTIVE, 7 requirements)
• 12.2 Folder moved to openspec/archive/2026-05-09-i18n-icu-parser/
• 12.3 MANIFEST.md already lists the package