@contractspec/lib.contracts 0.0.0-canary-20260119225944 → 0.0.0-canary-20260202053150

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 };

package/dist/translations/validation.js

@@ -0,0 +1,328 @@
+//#region src/translations/validation.ts
+/**
+* Validate a translation spec for internal consistency.
+*
+* @param spec - Translation spec to validate
+* @returns Validation result with any issues found
+*/
+function validateTranslationSpec(spec) {
+	const issues = [];
+	validateMeta(spec, issues);
+	validateLocale(spec, issues);
+	validateMessages(spec, issues);
+	validatePluralRules(spec, issues);
+	return {
+		valid: issues.filter((i) => i.level === "error").length === 0,
+		issues
+	};
+}
+function validateMeta(spec, issues) {
+	const { meta } = spec;
+	if (!meta.key?.trim()) issues.push({
+		level: "error",
+		message: "Translation spec must have a non-empty key",
+		path: "meta.key"
+	});
+	if (!meta.version?.trim()) issues.push({
+		level: "error",
+		message: "Translation spec must have a non-empty version",
+		path: "meta.version"
+	});
+	if (!meta.domain?.trim()) issues.push({
+		level: "error",
+		message: "Translation spec must have a non-empty domain",
+		path: "meta.domain"
+	});
+	if (!meta.owners?.length) issues.push({
+		level: "warning",
+		message: "Translation spec should specify owners",
+		path: "meta.owners"
+	});
+}
+function validateLocale(spec, issues) {
+	if (!spec.locale?.trim()) issues.push({
+		level: "error",
+		message: "Translation spec must specify a locale",
+		path: "locale"
+	});
+	else if (!isValidLocaleFormat(spec.locale)) issues.push({
+		level: "warning",
+		message: `Locale "${spec.locale}" may not be a valid ISO 639-1 code`,
+		path: "locale"
+	});
+	if (spec.fallback && !isValidLocaleFormat(spec.fallback)) issues.push({
+		level: "warning",
+		message: `Fallback locale "${spec.fallback}" may not be a valid ISO 639-1 code`,
+		path: "fallback"
+	});
+	if (spec.fallback === spec.locale) issues.push({
+		level: "warning",
+		message: "Fallback locale is the same as primary locale",
+		path: "fallback"
+	});
+}
+function validateMessages(spec, issues) {
+	const { messages } = spec;
+	if (!messages || Object.keys(messages).length === 0) {
+		issues.push({
+			level: "warning",
+			message: "Translation spec has no messages",
+			path: "messages"
+		});
+		return;
+	}
+	for (const [key, message] of Object.entries(messages)) {
+		const path = `messages.${key}`;
+		if (!message.value?.trim()) issues.push({
+			level: "error",
+			message: `Message "${key}" has an empty value`,
+			path: `${path}.value`
+		});
+		const valueParams = extractPlaceholders(message.value);
+		const declaredPlaceholders = message.placeholders ?? [];
+		for (const placeholder of declaredPlaceholders) if (!valueParams.includes(placeholder.name)) issues.push({
+			level: "warning",
+			message: `Placeholder "${placeholder.name}" is defined but not used in message "${key}"`,
+			path: `${path}.placeholders`
+		});
+		if (message.placeholders !== void 0) {
+			for (const param of valueParams) if (!declaredPlaceholders.find((p) => p.name === param)) issues.push({
+				level: "info",
+				message: `Placeholder "{${param}}" used in message "${key}" but not declared`,
+				path: `${path}.placeholders`
+			});
+		}
+		const icuResult = validateICUFormat(message.value);
+		if (!icuResult.valid) issues.push({
+			level: "error",
+			message: `Message "${key}" has invalid ICU format: ${icuResult.error}`,
+			path: `${path}.value`
+		});
+		if (message.variants?.length) {
+			const seenVariants = /* @__PURE__ */ new Set();
+			for (const variant of message.variants) {
+				const variantKey = `${variant.type}:${variant.key}`;
+				if (seenVariants.has(variantKey)) issues.push({
+					level: "warning",
+					message: `Duplicate variant "${variantKey}" in message "${key}"`,
+					path: `${path}.variants`
+				});
+				seenVariants.add(variantKey);
+				if (!variant.value?.trim()) issues.push({
+					level: "error",
+					message: `Variant "${variantKey}" has an empty value in message "${key}"`,
+					path: `${path}.variants`
+				});
+			}
+		}
+		if (message.maxLength !== void 0) {
+			if (message.maxLength <= 0) issues.push({
+				level: "error",
+				message: `Message "${key}" has invalid maxLength (must be positive)`,
+				path: `${path}.maxLength`
+			});
+			else if (message.value.length > message.maxLength) issues.push({
+				level: "warning",
+				message: `Message "${key}" value exceeds maxLength (${message.value.length} > ${message.maxLength})`,
+				path: `${path}.value`
+			});
+		}
+	}
+}
+function validatePluralRules(spec, issues) {
+	if (!spec.pluralRules?.length) return;
+	for (let i = 0; i < spec.pluralRules.length; i++) {
+		const rule = spec.pluralRules[i];
+		if (!rule) continue;
+		const path = `pluralRules[${i}]`;
+		if (!rule.variable?.trim()) issues.push({
+			level: "error",
+			message: "Plural rule must specify a variable name",
+			path: `${path}.variable`
+		});
+		if (!rule.rules?.length) issues.push({
+			level: "error",
+			message: "Plural rule must have at least one category",
+			path: `${path}.rules`
+		});
+		else if (!rule.rules.some((r) => r.category === "other")) issues.push({
+			level: "error",
+			message: `Plural rule "${rule.variable}" must have an "other" category`,
+			path: `${path}.rules`
+		});
+	}
+}
+/**
+* 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
+*/
+function validateICUFormat(message) {
+	const placeholders = [];
+	const plurals = [];
+	const selects = [];
+	let braceDepth = 0;
+	let currentPlaceholder = "";
+	let inPlaceholder = false;
+	try {
+		for (let i = 0; i < message.length; i++) {
+			const char = message[i];
+			const prevChar = i > 0 ? message[i - 1] : "";
+			if (char === "'" && i + 1 < message.length) {
+				const nextChar = message[i + 1];
+				if (nextChar === "{" || nextChar === "}") {
+					i++;
+					continue;
+				}
+			}
+			if (char === "{") {
+				if (prevChar !== "'") {
+					braceDepth++;
+					if (braceDepth === 1) {
+						inPlaceholder = true;
+						currentPlaceholder = "";
+					}
+				}
+			} else if (char === "}") {
+				if (prevChar !== "'") {
+					braceDepth--;
+					if (braceDepth === 0 && inPlaceholder) {
+						processPlaceholder(currentPlaceholder.trim(), placeholders, plurals, selects);
+						inPlaceholder = false;
+					}
+					if (braceDepth < 0) return {
+						valid: false,
+						error: "Unbalanced closing brace",
+						placeholders: [],
+						plurals: [],
+						selects: []
+					};
+				}
+			} else if (inPlaceholder) currentPlaceholder += char;
+		}
+		if (braceDepth !== 0) return {
+			valid: false,
+			error: "Unbalanced opening brace",
+			placeholders: [],
+			plurals: [],
+			selects: []
+		};
+		return {
+			valid: true,
+			placeholders,
+			plurals,
+			selects
+		};
+	} catch (error) {
+		return {
+			valid: false,
+			error: error instanceof Error ? error.message : "Unknown error",
+			placeholders: [],
+			plurals: [],
+			selects: []
+		};
+	}
+}
+function processPlaceholder(placeholder, placeholders, plurals, selects) {
+	const parts = placeholder.split(",").map((p) => p.trim());
+	const name = parts[0];
+	const type = parts[1]?.toLowerCase();
+	if (name && !placeholders.includes(name)) placeholders.push(name);
+	if (type === "plural" || type === "selectordinal") {
+		if (name && !plurals.includes(name)) plurals.push(name);
+	} else if (type === "select") {
+		if (name && !selects.includes(name)) selects.push(name);
+	}
+}
+/**
+* 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
+*/
+function findMissingTranslations(sourceSpec, targetSpec) {
+	const missing = [];
+	for (const [key, message] of Object.entries(sourceSpec.messages)) if (!targetSpec.messages[key]) missing.push({
+		messageKey: key,
+		sourceLocale: sourceSpec.locale,
+		targetLocale: targetSpec.locale,
+		sourceMessage: message
+	});
+	return missing;
+}
+/**
+* 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
+*/
+function findAllMissingTranslations(registry, specKey, baseLocale) {
+	const result = /* @__PURE__ */ new Map();
+	const baseSpec = registry.getLatest(specKey, baseLocale);
+	if (!baseSpec) return result;
+	const locales = registry.listLocales(specKey);
+	for (const locale of locales) {
+		if (locale === baseLocale) continue;
+		const targetSpec = registry.getLatest(specKey, locale);
+		if (targetSpec) {
+			const missing = findMissingTranslations(baseSpec, targetSpec);
+			if (missing.length > 0) result.set(locale, missing);
+		}
+	}
+	return result;
+}
+/**
+* Validate all translation specs in a registry.
+*
+* @param registry - Translation registry to validate
+* @returns Validation result
+*/
+function validateTranslationRegistry(registry) {
+	const issues = [];
+	for (const spec of registry.list()) {
+		const specResult = validateTranslationSpec(spec);
+		issues.push(...specResult.issues.map((i) => ({
+			...i,
+			path: `${spec.meta.key}.v${spec.meta.version}:${spec.locale}${i.path ? `.${i.path}` : ""}`
+		})));
+	}
+	return {
+		valid: issues.filter((i) => i.level === "error").length === 0,
+		issues
+	};
+}
+var TranslationValidationError = class extends Error {
+	constructor(message, issues) {
+		super(message);
+		this.issues = issues;
+		this.name = "TranslationValidationError";
+	}
+};
+/**
+* Assert that a translation spec is valid, throwing if not.
+*
+* @param spec - Translation spec to validate
+* @throws {TranslationValidationError} If validation fails
+*/
+function assertTranslationSpecValid(spec) {
+	const result = validateTranslationSpec(spec);
+	if (!result.valid) throw new TranslationValidationError(`Translation ${spec.meta.key}.v${spec.meta.version}:${spec.locale} is invalid`, result.issues);
+}
+function isValidLocaleFormat(locale) {
+	return /^[a-z]{2}(-[A-Z]{2})?$/.test(locale);
+}
+function extractPlaceholders(value) {
+	return validateICUFormat(value).placeholders;
+}
+
+//#endregion
+export { TranslationValidationError, assertTranslationSpecValid, findAllMissingTranslations, findMissingTranslations, validateICUFormat, validateTranslationRegistry, validateTranslationSpec };