@contractspec/lib.contracts 1.50.0 → 1.51.0

package/dist/tests/spec.d.ts

@@ -1,5 +1,5 @@
-import { OwnerShipMeta } from "../ownership.js";
 import { OptionalVersionedSpecRef } from "../versioning/refs.js";
+import { OwnerShipMeta } from "../ownership.js";
 
 //#region src/tests/spec.d.ts
 

package/dist/themes.d.ts

@@ -1,5 +1,5 @@
-import { OwnerShipMeta } from "./ownership.js";
 import { VersionedSpecRef } from "./versioning/refs.js";
+import { OwnerShipMeta } from "./ownership.js";
 import { SpecContractRegistry } from "./registry.js";
 
 //#region src/themes.d.ts

package/dist/translations/index.d.ts

@@ -0,0 +1,6 @@
+import { BlueprintTranslationCatalog, PlatformTranslationCatalog, TranslationCatalogMeta, TranslationEntry } from "./catalog.js";
+import { TenantTranslationOverride } from "./tenant.js";
+import { Locale, MessageKey, MessageVariant, PlaceholderDef, PlaceholderType, PluralCategory, PluralRule, PluralRuleSet, TranslationMessage, TranslationMessages, TranslationMeta, TranslationRef, TranslationSpec, VariantType, defineTranslation } from "./spec.js";
+import { TranslationLookupResult, TranslationRegistry, TranslationRegistryStats } from "./registry.js";
+import { ICUValidationResult, MissingTranslation, TranslationValidationError, TranslationValidationIssue, TranslationValidationLevel, TranslationValidationResult, assertTranslationSpecValid, findAllMissingTranslations, findMissingTranslations, validateICUFormat, validateTranslationRegistry, validateTranslationSpec } from "./validation.js";
+export { type BlueprintTranslationCatalog, ICUValidationResult, Locale, MessageKey, MessageVariant, MissingTranslation, PlaceholderDef, PlaceholderType, type PlatformTranslationCatalog, PluralCategory, PluralRule, PluralRuleSet, TenantTranslationOverride, type TranslationCatalogMeta, type TranslationEntry, TranslationLookupResult, TranslationMessage, TranslationMessages, TranslationMeta, TranslationRef, TranslationRegistry, TranslationRegistryStats, TranslationSpec, TranslationValidationError, TranslationValidationIssue, TranslationValidationLevel, TranslationValidationResult, VariantType, assertTranslationSpecValid, defineTranslation, findAllMissingTranslations, findMissingTranslations, validateICUFormat, validateTranslationRegistry, validateTranslationSpec };

package/dist/translations/index.js

@@ -0,0 +1,5 @@
+import { defineTranslation } from "./spec.js";
+import { TranslationRegistry } from "./registry.js";
+import { TranslationValidationError, assertTranslationSpecValid, findAllMissingTranslations, findMissingTranslations, validateICUFormat, validateTranslationRegistry, validateTranslationSpec } from "./validation.js";
+
+export { TranslationRegistry, TranslationValidationError, assertTranslationSpecValid, defineTranslation, findAllMissingTranslations, findMissingTranslations, validateICUFormat, validateTranslationRegistry, validateTranslationSpec };

package/dist/translations/registry.d.ts

@@ -0,0 +1,144 @@
+import { Locale, MessageKey, TranslationMessage, TranslationSpec } from "./spec.js";
+
+//#region src/translations/registry.d.ts
+
+interface TranslationLookupResult {
+  spec: TranslationSpec;
+  message: TranslationMessage;
+  locale: Locale;
+  fromFallback: boolean;
+}
+interface TranslationRegistryStats {
+  totalSpecs: number;
+  locales: Locale[];
+  domains: string[];
+  totalMessages: number;
+}
+/**
+ * Registry for translation specs with locale-aware lookup.
+ */
+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;
+}
+//#endregion
+export { TranslationLookupResult, TranslationRegistry, TranslationRegistryStats };

package/dist/translations/registry.js

@@ -0,0 +1,223 @@
+//#region src/translations/registry.ts
+/**
+* Registry for translation specs with locale-aware lookup.
+*/
+var TranslationRegistry = class {
+	specs = /* @__PURE__ */ new Map();
+	latestByLocale = /* @__PURE__ */ new Map();
+	locales = /* @__PURE__ */ new Set();
+	domains = /* @__PURE__ */ new Set();
+	constructor(items) {
+		if (items) for (const spec of items) this.register(spec);
+	}
+	/**
+	* Register a translation spec.
+	*
+	* @param spec - Translation spec to register
+	*/
+	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 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, version, locale) {
+		return this.specs.get(this.makeKey(key, version, locale));
+	}
+	/**
+	* 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, locale) {
+		return this.latestByLocale.get(`${key}:${locale}`);
+	}
+	/**
+	* 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, messageKey, locale, version) {
+		const spec = version ? this.get(specKey, version, locale) : this.getLatest(specKey, locale);
+		if (!spec) return void 0;
+		return spec.messages[messageKey];
+	}
+	/**
+	* 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, 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
+				};
+			}
+		}
+	}
+	/**
+	* 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, messageKey, locale, fallback) {
+		return this.getWithFallback(specKey, messageKey, locale)?.message.value ?? fallback ?? messageKey;
+	}
+	/**
+	* List all locales available for a spec key.
+	*
+	* @param specKey - Translation spec key
+	* @returns Array of available locales
+	*/
+	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 all translation specs.
+	*
+	* @returns Array of all registered translation specs
+	*/
+	list() {
+		return [...this.specs.values()];
+	}
+	/**
+	* List translation specs by locale.
+	*
+	* @param locale - Locale to filter by
+	* @returns Array of translation specs for the locale
+	*/
+	listByLocale(locale) {
+		return [...this.specs.values()].filter((s) => s.locale === locale);
+	}
+	/**
+	* List translation specs by domain.
+	*
+	* @param domain - Domain to filter by
+	* @returns Array of translation specs for the domain
+	*/
+	listByDomain(domain) {
+		return [...this.specs.values()].filter((s) => s.meta.domain === domain);
+	}
+	/**
+	* 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, locale, version) {
+		if (version) return this.specs.has(this.makeKey(key, version, locale));
+		return this.latestByLocale.has(`${key}:${locale}`);
+	}
+	/**
+	* Get all registered locales.
+	*
+	* @returns Set of all registered locales
+	*/
+	getLocales() {
+		return this.locales;
+	}
+	/**
+	* Get all registered domains.
+	*
+	* @returns Set of all registered domains
+	*/
+	getDomains() {
+		return this.domains;
+	}
+	/**
+	* Get registry statistics.
+	*
+	* @returns Registry statistics
+	*/
+	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 all registered specs.
+	*/
+	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;
+	}
+};
+
+//#endregion
+export { TranslationRegistry };

package/dist/translations/spec.d.ts

@@ -0,0 +1,126 @@
+import { Owner, Stability, Tag } from "../ownership.js";
+
+//#region src/translations/spec.d.ts
+
+/** ISO 639-1 locale code (e.g., 'en', 'fr', 'de'). */
+type Locale = string;
+/** Message key identifier. */
+type MessageKey = string;
+type PlaceholderType = 'string' | 'number' | 'date' | 'time' | 'datetime' | 'currency' | 'percent' | 'plural' | 'select' | 'selectordinal';
+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
+ */
+type PluralCategory = 'zero' | 'one' | 'two' | 'few' | 'many' | 'other';
+interface PluralRule {
+  category: PluralCategory;
+  value: string;
+}
+interface PluralRuleSet {
+  /** Name of the plural variable. */
+  variable: string;
+  /** Rules for each plural category. */
+  rules: PluralRule[];
+}
+type VariantType = 'gender' | 'formality' | 'context';
+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;
+}
+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[];
+}
+type TranslationMessages = Record<MessageKey, TranslationMessage>;
+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[];
+}
+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[];
+}
+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' }],
+ *     },
+ *   },
+ * });
+ * ```
+ */
+declare const defineTranslation: (spec: TranslationSpec) => TranslationSpec;
+//#endregion
+export { Locale, MessageKey, MessageVariant, PlaceholderDef, PlaceholderType, PluralCategory, PluralRule, PluralRuleSet, TranslationMessage, TranslationMessages, TranslationMeta, TranslationRef, TranslationSpec, VariantType, defineTranslation };

package/dist/translations/spec.js

@@ -0,0 +1,31 @@
+//#region src/translations/spec.ts
+/**
+* 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' }],
+*     },
+*   },
+* });
+* ```
+*/
+const defineTranslation = (spec) => spec;
+
+//#endregion
+export { defineTranslation };

package/dist/translations/validation.d.ts

@@ -0,0 +1,85 @@
+import { Locale, MessageKey, TranslationMessage, TranslationSpec } from "./spec.js";
+import { TranslationRegistry } from "./registry.js";
+
+//#region src/translations/validation.d.ts
+
+type TranslationValidationLevel = 'error' | 'warning' | 'info';
+interface TranslationValidationIssue {
+  level: TranslationValidationLevel;
+  message: string;
+  path?: string;
+  context?: Record<string, unknown>;
+}
+interface TranslationValidationResult {
+  valid: boolean;
+  issues: TranslationValidationIssue[];
+}
+interface ICUValidationResult {
+  valid: boolean;
+  error?: string;
+  placeholders: string[];
+  plurals: string[];
+  selects: string[];
+}
+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
+ */
+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
+ */
+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
+ */
+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
+ */
+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
+ */
+declare function validateTranslationRegistry(registry: TranslationRegistry): TranslationValidationResult;
+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
+ */
+declare function assertTranslationSpecValid(spec: TranslationSpec): void;
+//#endregion
+export { ICUValidationResult, MissingTranslation, TranslationValidationError, TranslationValidationIssue, TranslationValidationLevel, TranslationValidationResult, assertTranslationSpecValid, findAllMissingTranslations, findMissingTranslations, validateICUFormat, validateTranslationRegistry, validateTranslationSpec };