Initial Commit

openspec/specs/locale-data/spec.md

@@ -0,0 +1,53 @@
+# Spec: @suaveplan/locale-data
+
+**Package:** `@suaveplan/locale-data`  
+**Domain:** `universal/i18n/locale-data`  
+**Version:** `0.1.0`  
+**Status:** Published
+
+## Overview
+
+Static ISO 3166-1 country data (209 entries) and ISO 639-1 language data (130+ entries) with
+typed lookup functions, OTel instrumentation, and Zod schemas.
+
+## Requirements
+
+### Countries
+
+- `getCountry(code: string): CountryItem` — O(1) lookup; throws `LocaleDataError(COUNTRY.NOT_FOUND)` for unknown codes.
+- `getAllCountries(): Record<string, CountryItem>` — returns same reference each call.
+- `getCountriesByContinent(continent: string): CountryItem[]` — filters by 2-letter continent code.
+- `getCountriesByCurrency(currency: string): CountryItem[]` — splits comma-separated currency fields.
+- OTel counter: `locale_data.country.lookups` with `result: "found" | "not_found"`.
+
+### Languages
+
+- `getLanguages(): Record<string, LanguageItem>` — returns same reference each call.
+- `getLanguage(code: string): LanguageItem` — O(1) lookup; throws `LocaleDataError(LANGUAGE.NOT_FOUND)`.
+- `getRtlLanguages(): readonly string[]` — returns RTL language code list.
+- `isRtlLanguage(code: string): boolean` — BCP-47 aware; strips subtags before checking.
+- OTel counter: `locale_data.language.lookups` with `result: "found" | "not_found"`.
+
+### Errors
+
+- `LOCALE_DATA_CODES` — `defineCodes("LOCALE_DATA", ["COUNTRY.NOT_FOUND", "LANGUAGE.NOT_FOUND"])`.
+- `LocaleDataError extends SuaveplanError<LocaleDataCode>`.
+
+### Types / Schemas
+
+- `CountryItemSchema` (Zod) — 9 fields: name, native, phone, continent, capital, currency, languages[], emoji, emojiU.
+- `LanguageItemSchema` (Zod) — 2 fields: name, native.
+- `CountryCodeSchema` — `z.string().length(2).toUpperCase()`.
+- `LanguageCodeSchema` — `z.string().min(2).max(3).toLowerCase()`.
+
+## Data Coverage
+
+- **Countries:** 209 ISO 3166-1 alpha-2 entries, 7 continent codes.
+- **Languages:** 130+ ISO 639-1 entries, 15 RTL codes (`ar`, `az`, `ba`, `dv`, `fa`, `he`, `iu`, `ks`, `ku`, `ps`, `sd`, `sr`, `tg`, `ur`, `yi`).
+
+## Quality Gates
+
+- 100% Istanbul coverage (all 4 thresholds)
+- 100% docs coverage (6/6 implementation files)
+- Biome lint clean
+- TypeScript clean