@contractspec/lib.contracts 1.49.0 → 1.51.0

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

package/dist/types.d.ts

@@ -9,83 +9,209 @@ import { SpecVariantResolver } from "./experiments/spec-resolver.js";
 import { EventRegistry } from "./events.js";
 
 //#region src/types.d.ts
+
+/**
+ * Common runtime types for ContractSpec execution.
+ *
+ * Provides types for execution context, policy decisions, event emission,
+ * and handler context passed through the contracts runtime.
+ *
+ * @module types
+ */
 /**
- * Common runtime types: execution context, policy decision & event emission.
+ * Actor type representing the entity making a request.
+ *
+ * - `anonymous`: Unauthenticated request
+ * - `user`: Authenticated end-user
+ * - `admin`: Administrative/system user with elevated privileges
  */
 type Actor = 'anonymous' | 'user' | 'admin';
+/**
+ * Channel through which a request originates.
+ *
+ * - `web`: Browser/web application
+ * - `mobile`: Native mobile application
+ * - `job`: Background job/scheduled task
+ * - `agent`: AI agent or automated system
+ */
 type Channel = 'web' | 'mobile' | 'job' | 'agent';
+/**
+ * Discriminator for all ContractSpec specification types.
+ *
+ * Used to identify the kind of spec in registries and runtime operations.
+ */
 type ContractSpecType = 'app-config' | 'agent' | 'operation' | 'example' | 'event' | 'presentation' | 'capability' | 'integration' | 'data-view' | 'feature' | 'workflow' | 'policy' | 'theme' | 'telemetry' | 'experiment' | 'knowledge-space';
+/**
+ * Decision for a specific field access.
+ * Used for fine-grained field-level authorization.
+ */
 interface FieldLevelDecision {
+  /** The field path being evaluated. */
   field: string;
+  /** Whether access is allowed or denied. */
   effect: 'allow' | 'deny';
+  /** Human-readable reason for the decision. */
   reason?: string;
 }
+/**
+ * Result of a policy evaluation.
+ *
+ * Contains the access decision and any applicable constraints
+ * like rate limits, escalation requirements, or consent needs.
+ */
 interface PolicyDecision {
+  /** Overall access decision: allow or deny. */
   effect: 'allow' | 'deny';
+  /** Human-readable reason for the decision. */
   reason?: string;
+  /** Rate limit constraints to apply if allowed. */
   rateLimit?: Pick<RateLimitDefinition, 'rpm' | 'key' | 'windowSeconds' | 'burst'>;
+  /** Escalation requirement for manual review. */
   escalate?: 'human_review' | null;
+  /** Per-field access decisions. */
   fieldDecisions?: FieldLevelDecision[];
+  /** PII handling policy. */
   pii?: PolicySpec['pii'];
+  /** Consents required before proceeding. */
   requiredConsents?: ConsentDefinition[];
+  /** Which engine produced this decision. */
   evaluatedBy?: 'engine' | 'opa';
 }
+/**
+ * Input for policy evaluation.
+ * Contains context about the request being authorized.
+ */
 interface PolicyDeciderInput {
+  /** Service name (e.g., "sigil"). */
   service: string;
+  /** Command/operation name (e.g., "beginSignup"). */
   command: string;
+  /** Operation version. */
   version: string;
+  /** Actor type making the request. */
   actor: Actor;
+  /** Channel the request came from. */
   channel?: Channel;
+  /** Roles assigned to the actor. */
   roles?: string[];
+  /** Organization context if applicable. */
   organizationId?: string | null;
+  /** User context if authenticated. */
   userId?: string | null;
+  /** Active feature flags. */
   flags?: string[];
 }
+/**
+ * Function that evaluates policy rules and returns a decision.
+ */
 type PolicyDecider = (input: PolicyDeciderInput) => Promise<PolicyDecision>;
+/**
+ * Function that enforces rate limits.
+ *
+ * @param key - The rate limit key (e.g., user ID, IP)
+ * @param cost - Cost of this request (usually 1)
+ * @param rpm - Requests per minute limit
+ * @throws When rate limit is exceeded
+ */
 type RateLimiter = (key: string, cost: number, rpm: number) => Promise<void>;
+/**
+ * Function that resolves translation keys to localized strings.
+ */
 type TranslationResolver = (key: MessageKey, locale?: Locale) => Promise<string | null> | string | null;
-/** Outbox/bus event publisher (after validation & guarding) */
+/**
+ * Function that publishes events to the outbox/message bus.
+ * Called after validation and guard checks pass.
+ */
 type EventPublisher = (envelope: {
+  /** Event key (e.g., "user.created"). */
   key: string;
+  /** Event version. */
   version: string;
+  /** Validated event payload. */
   payload: unknown;
+  /** Trace ID for correlation. */
   traceId?: string;
 }) => Promise<void>;
+/**
+ * Execution context passed to operation handlers.
+ *
+ * Contains all contextual information and service hooks needed
+ * during operation execution, including auth context, policy evaluation,
+ * telemetry, event publishing, and resolved configurations.
+ *
+ * @example
+ * ```typescript
+ * async function loginHandler(input: LoginInput, ctx: HandlerCtx) {
+ *   // Check policy
+ *   const decision = await ctx.decide?.({
+ *     service: 'auth',
+ *     command: 'login',
+ *     version: '1.0.0',
+ *     actor: ctx.actor ?? 'anonymous',
+ *   });
+ *
+ *   // Track telemetry
+ *   ctx.telemetry?.track('login_attempt', { userId: ctx.userId });
+ *
+ *   // Publish event
+ *   await ctx.eventPublisher?.({
+ *     key: 'user.loggedIn',
+ *     version: '1.0.0',
+ *     payload: { userId: input.email },
+ *     traceId: ctx.traceId,
+ *   });
+ * }
+ * ```
+ */
 interface HandlerCtx {
+  /** Distributed trace identifier for request correlation. */
   traceId?: string;
+  /** Idempotency key for deduplication. */
   idemKey?: string;
+  /** Organization context for multi-tenant operations. */
   organizationId?: string | null;
+  /** Authenticated user ID. */
   userId?: string | null;
+  /** Actor type making the request. */
   actor?: Actor;
+  /** Channel the request originated from. */
   channel?: Channel;
+  /** Roles assigned to the authenticated user. */
   roles?: string[];
-  /** Policy engine hook (policy.yaml) */
+  /** Policy engine for authorization decisions. */
   decide?: PolicyDecider;
-  /** Rate limiter (e.g., Redis) */
+  /** Rate limiter service (e.g., Redis-backed). */
   rateLimit?: RateLimiter;
-  /** Telemetry tracker */
+  /** Telemetry tracker for metrics and events. */
   telemetry?: TelemetryTracker;
-  /** Event publisher (outbox+bus) */
+  /** Event publisher for domain events (outbox/bus). */
   eventPublisher?: EventPublisher;
-  /** Secret provider for secure credentials */
+  /** Secret provider for secure credential access. */
   secretProvider?: SecretProvider;
-  /** Internal pipe: filled by executor to enforce declared events */
+  /**
+   * Internal emit guard for enforcing declared event emissions.
+   * Populated by the executor runtime.
+   * @internal
+   */
   __emitGuard__?: (key: string, version: string, payload: unknown) => Promise<void>;
-  /** Resolved application configuration for the current execution context */
+  /** Resolved application configuration for this execution. */
   appConfig?: ResolvedAppConfig;
-  /** Resolved integration connections available to this execution */
+  /** Resolved integration connections available to this execution. */
   integrations?: ResolvedIntegration[];
-  /** Resolved knowledge spaces available to this execution */
+  /** Resolved knowledge spaces available to this execution. */
   knowledge?: ResolvedKnowledge[];
-  /** Resolved branding context */
+  /** Resolved branding context (logos, colors, etc.). */
   branding?: ResolvedBranding;
-  /** Translation context */
+  /** Translation context with config and resolver. */
   translation?: {
+    /** Resolved translation configuration. */
     config: ResolvedTranslation;
+    /** Function to resolve translation keys. */
     resolve?: TranslationResolver;
   };
-  /** Optional spec variant resolver for experiments */
+  /** Spec variant resolver for A/B testing and experiments. */
   specVariantResolver?: SpecVariantResolver;
+  /** Event registry for runtime event spec lookup. */
   eventSpecResolver?: EventRegistry;
 }
 //#endregion

package/dist/versioning/index.d.ts

@@ -1,3 +1,4 @@
+import { OptionalVersionedSpecRef, SpecKeyRef, VersionedSpecRef, createKeyRef, createOptionalRef, createVersionedRef, formatVersionedRefKey, isOptionalVersionedSpecRef, isSpecKeyRef, isVersionedSpecRef, parseVersionedRefKey } from "./refs.js";
 import { ChangeEntry, ChangeType, ChangelogDocBlock, ChangelogEntry, ChangelogJsonExport, ChangelogResult, SemanticVersion, VersionAnalysis, VersionAnalysisResult, VersionBumpType, isChangeType, isChangelogDocBlock, isVersionBumpType } from "./types.js";
 import { bumpVersion, compareVersions, determineBumpType, formatVersion, getBumpTypePriority, getMaxBumpType, isValidVersion, isVersionEqual, isVersionGreater, isVersionLess, parseVersion, parseVersionStrict, validateVersion } from "./utils.js";
-export { ChangeEntry, ChangeType, ChangelogDocBlock, ChangelogEntry, ChangelogJsonExport, ChangelogResult, SemanticVersion, VersionAnalysis, VersionAnalysisResult, VersionBumpType, bumpVersion, compareVersions, determineBumpType, formatVersion, getBumpTypePriority, getMaxBumpType, isChangeType, isChangelogDocBlock, isValidVersion, isVersionBumpType, isVersionEqual, isVersionGreater, isVersionLess, parseVersion, parseVersionStrict, validateVersion };
+export { ChangeEntry, ChangeType, ChangelogDocBlock, ChangelogEntry, ChangelogJsonExport, ChangelogResult, OptionalVersionedSpecRef, SemanticVersion, SpecKeyRef, VersionAnalysis, VersionAnalysisResult, VersionBumpType, VersionedSpecRef, bumpVersion, compareVersions, createKeyRef, createOptionalRef, createVersionedRef, determineBumpType, formatVersion, formatVersionedRefKey, getBumpTypePriority, getMaxBumpType, isChangeType, isChangelogDocBlock, isOptionalVersionedSpecRef, isSpecKeyRef, isValidVersion, isVersionBumpType, isVersionEqual, isVersionGreater, isVersionLess, isVersionedSpecRef, parseVersion, parseVersionStrict, parseVersionedRefKey, validateVersion };

package/dist/versioning/index.js

@@ -1,4 +1,5 @@
+import { createKeyRef, createOptionalRef, createVersionedRef, formatVersionedRefKey, isOptionalVersionedSpecRef, isSpecKeyRef, isVersionedSpecRef, parseVersionedRefKey } from "./refs.js";
 import { isChangeType, isChangelogDocBlock, isVersionBumpType } from "./types.js";
 import { bumpVersion, compareVersions, determineBumpType, formatVersion, getBumpTypePriority, getMaxBumpType, isValidVersion, isVersionEqual, isVersionGreater, isVersionLess, parseVersion, parseVersionStrict, validateVersion } from "./utils.js";
 
-export { bumpVersion, compareVersions, determineBumpType, formatVersion, getBumpTypePriority, getMaxBumpType, isChangeType, isChangelogDocBlock, isValidVersion, isVersionBumpType, isVersionEqual, isVersionGreater, isVersionLess, parseVersion, parseVersionStrict, validateVersion };
+export { bumpVersion, compareVersions, createKeyRef, createOptionalRef, createVersionedRef, determineBumpType, formatVersion, formatVersionedRefKey, getBumpTypePriority, getMaxBumpType, isChangeType, isChangelogDocBlock, isOptionalVersionedSpecRef, isSpecKeyRef, isValidVersion, isVersionBumpType, isVersionEqual, isVersionGreater, isVersionLess, isVersionedSpecRef, parseVersion, parseVersionStrict, parseVersionedRefKey, validateVersion };