@contractspec/lib.contracts-spec 2.0.0

package/dist/translations/registry.d.ts

@@ -0,0 +1,172 @@
+/**
+ * Translation registry for managing translation specs.
+ *
+ * Provides registration, lookup, and resolution of translation specs
+ * with support for locale fallback chains.
+ *
+ * @module translations/registry
+ *
+ * @example
+ * ```typescript
+ * import { TranslationRegistry } from '@contractspec/lib.contracts-spec';
+ *
+ * const registry = new TranslationRegistry();
+ *
+ * // Register translations
+ * registry.register(englishMessages);
+ * registry.register(frenchMessages);
+ *
+ * // Get a translation spec
+ * const spec = registry.get('auth.messages', '1.0.0', 'en');
+ *
+ * // Get a specific message
+ * const message = registry.getMessage('auth.messages', 'login.success', 'en');
+ *
+ * // Get with fallback
+ * const messageWithFallback = registry.getWithFallback(
+ *   'auth.messages',
+ *   'login.success',
+ *   'de', // German
+ *   'en'  // Fallback to English
+ * );
+ * ```
+ */
+import type { TranslationSpec, TranslationMessage, Locale, MessageKey } from './spec';
+export interface TranslationLookupResult {
+    spec: TranslationSpec;
+    message: TranslationMessage;
+    locale: Locale;
+    fromFallback: boolean;
+}
+export interface TranslationRegistryStats {
+    totalSpecs: number;
+    locales: Locale[];
+    domains: string[];
+    totalMessages: number;
+}
+/**
+ * Registry for translation specs with locale-aware lookup.
+ */
+export declare class TranslationRegistry {
+    private readonly specs;
+    private readonly latestByLocale;
+    private readonly locales;
+    private readonly domains;
+    constructor(items?: TranslationSpec[]);
+    /**
+     * Register a translation spec.
+     *
+     * @param spec - Translation spec to register
+     */
+    register(spec: TranslationSpec): void;
+    /**
+     * Get a translation spec by key, version, and locale.
+     *
+     * @param key - Translation spec key
+     * @param version - Version string
+     * @param locale - Locale code
+     * @returns Translation spec or undefined
+     */
+    get(key: string, version: string, locale: Locale): TranslationSpec | undefined;
+    /**
+     * Get the latest version of a translation spec for a locale.
+     *
+     * @param key - Translation spec key
+     * @param locale - Locale code
+     * @returns Translation spec or undefined
+     */
+    getLatest(key: string, locale: Locale): TranslationSpec | undefined;
+    /**
+     * Get a specific message from a translation spec.
+     *
+     * @param specKey - Translation spec key
+     * @param messageKey - Message key within the spec
+     * @param locale - Locale code
+     * @param version - Optional version (uses latest if not specified)
+     * @returns Translation message or undefined
+     */
+    getMessage(specKey: string, messageKey: MessageKey, locale: Locale, version?: string): TranslationMessage | undefined;
+    /**
+     * Get a message value with fallback chain support.
+     *
+     * @param specKey - Translation spec key
+     * @param messageKey - Message key within the spec
+     * @param locale - Primary locale
+     * @param fallbackLocale - Fallback locale (optional, uses spec's fallback if not provided)
+     * @param version - Optional version (uses latest if not specified)
+     * @returns Translation lookup result or undefined
+     */
+    getWithFallback(specKey: string, messageKey: MessageKey, locale: Locale, fallbackLocale?: Locale, version?: string): TranslationLookupResult | undefined;
+    /**
+     * Get a message value string with fallback.
+     *
+     * Convenience method that returns just the string value or a fallback.
+     *
+     * @param specKey - Translation spec key
+     * @param messageKey - Message key
+     * @param locale - Primary locale
+     * @param fallback - String to return if message not found (default: messageKey)
+     * @returns Message value or fallback
+     */
+    getValue(specKey: string, messageKey: MessageKey, locale: Locale, fallback?: string): string;
+    /**
+     * List all locales available for a spec key.
+     *
+     * @param specKey - Translation spec key
+     * @returns Array of available locales
+     */
+    listLocales(specKey: string): Locale[];
+    /**
+     * List all translation specs.
+     *
+     * @returns Array of all registered translation specs
+     */
+    list(): TranslationSpec[];
+    /**
+     * List translation specs by locale.
+     *
+     * @param locale - Locale to filter by
+     * @returns Array of translation specs for the locale
+     */
+    listByLocale(locale: Locale): TranslationSpec[];
+    /**
+     * List translation specs by domain.
+     *
+     * @param domain - Domain to filter by
+     * @returns Array of translation specs for the domain
+     */
+    listByDomain(domain: string): TranslationSpec[];
+    /**
+     * Check if a translation spec exists.
+     *
+     * @param key - Translation spec key
+     * @param locale - Locale code
+     * @param version - Optional version
+     * @returns True if spec exists
+     */
+    has(key: string, locale: Locale, version?: string): boolean;
+    /**
+     * Get all registered locales.
+     *
+     * @returns Set of all registered locales
+     */
+    getLocales(): ReadonlySet<Locale>;
+    /**
+     * Get all registered domains.
+     *
+     * @returns Set of all registered domains
+     */
+    getDomains(): ReadonlySet<string>;
+    /**
+     * Get registry statistics.
+     *
+     * @returns Registry statistics
+     */
+    getStats(): TranslationRegistryStats;
+    /**
+     * Clear all registered specs.
+     */
+    clear(): void;
+    private makeKey;
+    private isNewerVersion;
+}

package/dist/translations/registry.js

@@ -0,0 +1,170 @@
+// @bun
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __moduleCache = /* @__PURE__ */ new WeakMap;
+var __toCommonJS = (from) => {
+  var entry = __moduleCache.get(from), desc;
+  if (entry)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function")
+    __getOwnPropNames(from).map((key) => !__hasOwnProp.call(entry, key) && __defProp(entry, key, {
+      get: () => from[key],
+      enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+    }));
+  __moduleCache.set(from, entry);
+  return entry;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+var __require = import.meta.require;
+
+// src/translations/registry.ts
+class TranslationRegistry {
+  specs = new Map;
+  latestByLocale = new Map;
+  locales = new Set;
+  domains = new Set;
+  constructor(items) {
+    if (items) {
+      for (const spec of items) {
+        this.register(spec);
+      }
+    }
+  }
+  register(spec) {
+    const fullKey = this.makeKey(spec.meta.key, spec.meta.version, spec.locale);
+    this.specs.set(fullKey, spec);
+    const localeKey = `${spec.meta.key}:${spec.locale}`;
+    const existing = this.latestByLocale.get(localeKey);
+    if (!existing || this.isNewerVersion(spec.meta.version, existing.meta.version)) {
+      this.latestByLocale.set(localeKey, spec);
+    }
+    this.locales.add(spec.locale);
+    this.domains.add(spec.meta.domain);
+  }
+  get(key, version, locale) {
+    return this.specs.get(this.makeKey(key, version, locale));
+  }
+  getLatest(key, locale) {
+    return this.latestByLocale.get(`${key}:${locale}`);
+  }
+  getMessage(specKey, messageKey, locale, version) {
+    const spec = version ? this.get(specKey, version, locale) : this.getLatest(specKey, locale);
+    if (!spec)
+      return;
+    return spec.messages[messageKey];
+  }
+  getWithFallback(specKey, messageKey, locale, fallbackLocale, version) {
+    const spec = version ? this.get(specKey, version, locale) : this.getLatest(specKey, locale);
+    if (spec) {
+      const message = spec.messages[messageKey];
+      if (message) {
+        return { spec, message, locale, fromFallback: false };
+      }
+      fallbackLocale = fallbackLocale ?? spec.fallback;
+    }
+    if (fallbackLocale && fallbackLocale !== locale) {
+      const fallbackSpec = version ? this.get(specKey, version, fallbackLocale) : this.getLatest(specKey, fallbackLocale);
+      if (fallbackSpec) {
+        const message = fallbackSpec.messages[messageKey];
+        if (message) {
+          return {
+            spec: fallbackSpec,
+            message,
+            locale: fallbackLocale,
+            fromFallback: true
+          };
+        }
+      }
+    }
+    return;
+  }
+  getValue(specKey, messageKey, locale, fallback) {
+    const result = this.getWithFallback(specKey, messageKey, locale);
+    return result?.message.value ?? fallback ?? messageKey;
+  }
+  listLocales(specKey) {
+    const locales = [];
+    for (const [key, spec] of this.specs.entries()) {
+      if (key.startsWith(`${specKey}:`)) {
+        if (!locales.includes(spec.locale)) {
+          locales.push(spec.locale);
+        }
+      }
+    }
+    return locales;
+  }
+  list() {
+    return [...this.specs.values()];
+  }
+  listByLocale(locale) {
+    return [...this.specs.values()].filter((s) => s.locale === locale);
+  }
+  listByDomain(domain) {
+    return [...this.specs.values()].filter((s) => s.meta.domain === domain);
+  }
+  has(key, locale, version) {
+    if (version) {
+      return this.specs.has(this.makeKey(key, version, locale));
+    }
+    return this.latestByLocale.has(`${key}:${locale}`);
+  }
+  getLocales() {
+    return this.locales;
+  }
+  getDomains() {
+    return this.domains;
+  }
+  getStats() {
+    let totalMessages = 0;
+    for (const spec of this.specs.values()) {
+      totalMessages += Object.keys(spec.messages).length;
+    }
+    return {
+      totalSpecs: this.specs.size,
+      locales: [...this.locales],
+      domains: [...this.domains],
+      totalMessages
+    };
+  }
+  clear() {
+    this.specs.clear();
+    this.latestByLocale.clear();
+    this.locales.clear();
+    this.domains.clear();
+  }
+  makeKey(key, version, locale) {
+    return `${key}:${version}:${locale}`;
+  }
+  isNewerVersion(a, b) {
+    const parseVersion = (v) => {
+      const parts = v.split(".").map(Number);
+      return {
+        major: parts[0] ?? 0,
+        minor: parts[1] ?? 0,
+        patch: parts[2] ?? 0
+      };
+    };
+    const va = parseVersion(a);
+    const vb = parseVersion(b);
+    if (va.major !== vb.major)
+      return va.major > vb.major;
+    if (va.minor !== vb.minor)
+      return va.minor > vb.minor;
+    return va.patch > vb.patch;
+  }
+}
+export {
+  TranslationRegistry
+};

package/dist/translations/registry.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/translations/spec.d.ts

@@ -0,0 +1,153 @@
+/**
+ * Translation specification types for i18n contract system.
+ *
+ * Provides comprehensive types for defining translatable content
+ * with support for pluralization, ICU message format hints,
+ * locale fallback, and context-aware translations.
+ *
+ * @module translations/spec
+ *
+ * @example
+ * ```typescript
+ * import { defineTranslation, TranslationSpec } from '@contractspec/lib.contracts-spec';
+ *
+ * const messages = defineTranslation({
+ *   meta: {
+ *     key: 'payments.messages',
+ *     version: '1.0.0',
+ *     domain: 'payments',
+ *     owners: [{ team: 'payments' }],
+ *   },
+ *   locale: 'en',
+ *   fallback: 'en',
+ *   messages: {
+ *     'payment.success': {
+ *       value: 'Payment of {amount, number, currency} completed successfully',
+ *       description: 'Shown after successful payment',
+ *       placeholders: [{ name: 'amount', type: 'number', format: 'currency' }],
+ *     },
+ *   },
+ * });
+ * ```
+ */
+import type { Owner, Stability, Tag } from '../ownership';
+/** ISO 639-1 locale code (e.g., 'en', 'fr', 'de'). */
+export type Locale = string;
+/** Message key identifier. */
+export type MessageKey = string;
+export type PlaceholderType = 'string' | 'number' | 'date' | 'time' | 'datetime' | 'currency' | 'percent' | 'plural' | 'select' | 'selectordinal';
+export interface PlaceholderDef {
+    /** Placeholder name (without braces). */
+    name: string;
+    /** Type of the placeholder value. */
+    type: PlaceholderType;
+    /** Format specifier (e.g., 'short', 'long', 'currency'). */
+    format?: string;
+    /** Description for translators. */
+    description?: string;
+    /** Example value for context. */
+    example?: string;
+}
+/**
+ * CLDR plural categories.
+ * @see https://cldr.unicode.org/index/cldr-spec/plural-rules
+ */
+export type PluralCategory = 'zero' | 'one' | 'two' | 'few' | 'many' | 'other';
+export interface PluralRule {
+    category: PluralCategory;
+    value: string;
+}
+export interface PluralRuleSet {
+    /** Name of the plural variable. */
+    variable: string;
+    /** Rules for each plural category. */
+    rules: PluralRule[];
+}
+export type VariantType = 'gender' | 'formality' | 'context';
+export interface MessageVariant {
+    /** Type of variant (gender, formality, context). */
+    type: VariantType;
+    /** Variant key (e.g., 'male', 'female', 'formal', 'informal'). */
+    key: string;
+    /** Variant value (the translated message for this variant). */
+    value: string;
+}
+export interface TranslationMessage {
+    /** The translated value (may use ICU message format). */
+    value: string;
+    /** Description for translators explaining context and usage. */
+    description?: string;
+    /** Usage context to help translators understand where this appears. */
+    context?: string;
+    /** Placeholder definitions for dynamic values. */
+    placeholders?: PlaceholderDef[];
+    /** Variants for gender, formality, or other contextual differences. */
+    variants?: MessageVariant[];
+    /** Maximum character length (hint for UI constraints). */
+    maxLength?: number;
+    /** Tags for categorization and filtering. */
+    tags?: string[];
+}
+export type TranslationMessages = Record<MessageKey, TranslationMessage>;
+export interface TranslationMeta {
+    /** Unique key for this translation spec. */
+    key: string;
+    /** Semantic version (e.g., "1.0.0"). */
+    version: string;
+    /** Business domain this translation belongs to. */
+    domain: string;
+    /** Description of the translation bundle. */
+    description?: string;
+    /** Owners responsible for this translation spec. */
+    owners: Owner[];
+    /** Stability marker. */
+    stability?: Stability;
+    /** Tags for categorization. */
+    tags?: Tag[];
+}
+export interface TranslationSpec {
+    /** Metadata about this translation spec. */
+    meta: TranslationMeta;
+    /** Primary locale for this translation spec. */
+    locale: Locale;
+    /** Fallback locale when a message is missing. */
+    fallback?: Locale;
+    /** Translation messages keyed by message key. */
+    messages: TranslationMessages;
+    /** Plural rules for the locale. */
+    pluralRules?: PluralRuleSet[];
+    /** Tags for categorization. */
+    tags?: string[];
+}
+export interface TranslationRef {
+    key: string;
+    version: string;
+    locale?: Locale;
+}
+/**
+ * Helper to define a Translation spec.
+ *
+ * @param spec - Translation specification
+ * @returns The same spec with type inference
+ *
+ * @example
+ * ```typescript
+ * const messages = defineTranslation({
+ *   meta: {
+ *     key: 'auth.messages',
+ *     version: '1.0.0',
+ *     domain: 'auth',
+ *     owners: [{ team: 'platform' }],
+ *   },
+ *   locale: 'en',
+ *   messages: {
+ *     'login.success': {
+ *       value: 'Welcome back, {name}!',
+ *       description: 'Shown after successful login',
+ *       placeholders: [{ name: 'name', type: 'string' }],
+ *     },
+ *   },
+ * });
+ * ```
+ */
+export declare const defineTranslation: (spec: TranslationSpec) => TranslationSpec;

package/dist/translations/spec.js

@@ -0,0 +1,36 @@
+// @bun
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __moduleCache = /* @__PURE__ */ new WeakMap;
+var __toCommonJS = (from) => {
+  var entry = __moduleCache.get(from), desc;
+  if (entry)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function")
+    __getOwnPropNames(from).map((key) => !__hasOwnProp.call(entry, key) && __defProp(entry, key, {
+      get: () => from[key],
+      enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+    }));
+  __moduleCache.set(from, entry);
+  return entry;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+var __require = import.meta.require;
+
+// src/translations/spec.ts
+var defineTranslation = (spec) => spec;
+export {
+  defineTranslation
+};

package/dist/translations/spec.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/translations/tenant.d.ts

@@ -0,0 +1,11 @@
+import type { Locale, TranslationEntry } from './catalog';
+export interface TenantTranslationOverride {
+    tenantId: string;
+    appId: string;
+    blueprintName: string;
+    blueprintVersion: number;
+    entries: TranslationEntry[];
+    defaultLocale?: Locale;
+    enabledLocales?: Locale[];
+    updatedAt?: string;
+}

package/dist/translations/tenant.js

@@ -0,0 +1 @@
+// @bun

package/dist/translations/validation.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Translation validation utilities.
+ *
+ * Provides functions to validate translation specs, check for
+ * missing translations, and validate ICU message format.
+ *
+ * @module translations/validation
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   validateTranslationSpec,
+ *   findMissingTranslations,
+ *   validateICUFormat
+ * } from '@contractspec/lib.contracts-spec';
+ *
+ * // Validate a translation spec
+ * const result = validateTranslationSpec(myTranslation);
+ *
+ * // Find missing translations between locales
+ * const missing = findMissingTranslations(englishSpec, frenchSpec);
+ *
+ * // Validate ICU message format
+ * const icuResult = validateICUFormat('{count, plural, one {item} other {items}}');
+ * ```
+ */
+import type { TranslationSpec, TranslationMessage, MessageKey, Locale } from './spec';
+import type { TranslationRegistry } from './registry';
+export type TranslationValidationLevel = 'error' | 'warning' | 'info';
+export interface TranslationValidationIssue {
+    level: TranslationValidationLevel;
+    message: string;
+    path?: string;
+    context?: Record<string, unknown>;
+}
+export interface TranslationValidationResult {
+    valid: boolean;
+    issues: TranslationValidationIssue[];
+}
+export interface ICUValidationResult {
+    valid: boolean;
+    error?: string;
+    placeholders: string[];
+    plurals: string[];
+    selects: string[];
+}
+export interface MissingTranslation {
+    messageKey: MessageKey;
+    sourceLocale: Locale;
+    targetLocale: Locale;
+    sourceMessage: TranslationMessage;
+}
+/**
+ * Validate a translation spec for internal consistency.
+ *
+ * @param spec - Translation spec to validate
+ * @returns Validation result with any issues found
+ */
+export declare function validateTranslationSpec(spec: TranslationSpec): TranslationValidationResult;
+/**
+ * Validate ICU message format syntax.
+ *
+ * This is a simplified validator that checks for balanced braces
+ * and extracts placeholders, plurals, and selects.
+ *
+ * @param message - Message string to validate
+ * @returns Validation result with extracted components
+ */
+export declare function validateICUFormat(message: string): ICUValidationResult;
+/**
+ * Find messages that exist in source but not in target.
+ *
+ * @param sourceSpec - Source translation spec (usually base locale like 'en')
+ * @param targetSpec - Target translation spec to check
+ * @returns Array of missing translations
+ */
+export declare function findMissingTranslations(sourceSpec: TranslationSpec, targetSpec: TranslationSpec): MissingTranslation[];
+/**
+ * Find all missing translations across a registry.
+ *
+ * Compares each locale against a base locale to find missing keys.
+ *
+ * @param registry - Translation registry
+ * @param specKey - Translation spec key to check
+ * @param baseLocale - Base locale to compare against
+ * @returns Map of locale to missing translations
+ */
+export declare function findAllMissingTranslations(registry: TranslationRegistry, specKey: string, baseLocale: Locale): Map<Locale, MissingTranslation[]>;
+/**
+ * Validate all translation specs in a registry.
+ *
+ * @param registry - Translation registry to validate
+ * @returns Validation result
+ */
+export declare function validateTranslationRegistry(registry: TranslationRegistry): TranslationValidationResult;
+export declare class TranslationValidationError extends Error {
+    readonly issues: TranslationValidationIssue[];
+    constructor(message: string, issues: TranslationValidationIssue[]);
+}
+/**
+ * Assert that a translation spec is valid, throwing if not.
+ *
+ * @param spec - Translation spec to validate
+ * @throws {TranslationValidationError} If validation fails
+ */
+export declare function assertTranslationSpecValid(spec: TranslationSpec): void;