@contractspec/lib.contracts 1.50.0 → 1.52.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/workflow/context.d.ts

@@ -0,0 +1,191 @@
+import { Step, WorkflowSpec } from "./spec.js";
+import { StepExecution, WorkflowState } from "./state.js";
+
+//#region src/workflow/context.d.ts
+
+/**
+ * Error thrown when a workflow operation fails.
+ */
+declare class WorkflowContextError extends Error {
+  readonly errorType: WorkflowContextErrorType;
+  readonly workflowId: string;
+  readonly details?: Record<string, unknown>;
+  constructor(type: WorkflowContextErrorType, workflowId: string, message: string, details?: Record<string, unknown>);
+}
+type WorkflowContextErrorType = 'invalid_transition' | 'workflow_completed' | 'workflow_failed' | 'step_not_found' | 'guard_rejected' | 'sla_violated';
+interface WorkflowTransitionResult {
+  success: boolean;
+  previousStep: string;
+  currentStep: string;
+  status: WorkflowState['status'];
+  error?: string;
+}
+interface AvailableTransition {
+  from: string;
+  to: string;
+  label?: string;
+  condition?: string;
+}
+interface SlaStatus {
+  key: string;
+  type: 'workflow' | 'step';
+  stepId?: string;
+  limitMs: number;
+  elapsedMs: number;
+  remainingMs: number;
+  violated: boolean;
+  percentUsed: number;
+}
+interface WorkflowEvent {
+  timestamp: Date;
+  type: 'step_started' | 'step_completed' | 'step_failed' | 'step_retried' | 'transition';
+  stepId?: string;
+  fromStep?: string;
+  toStep?: string;
+  input?: unknown;
+  output?: unknown;
+  error?: string;
+}
+/**
+ * Runtime context for interacting with a workflow instance.
+ *
+ * Provides a simplified interface over WorkflowRunner for common
+ * workflow operations like state access, transitions, and SLA tracking.
+ */
+interface WorkflowContext<TData = Record<string, unknown>> {
+  /** Unique workflow instance identifier. */
+  readonly workflowId: string;
+  /** Workflow spec key. */
+  readonly workflowKey: string;
+  /** Workflow spec version. */
+  readonly workflowVersion: string;
+  /** Current step identifier. */
+  readonly currentStep: string;
+  /** Current workflow status. */
+  readonly status: WorkflowState['status'];
+  /** Workflow data/state. */
+  readonly data: TData;
+  /** Execution history. */
+  readonly history: readonly StepExecution[];
+  /**
+   * Get the current workflow state.
+   * @returns Full workflow state object
+   */
+  getState(): WorkflowState;
+  /**
+   * Get a value from workflow data.
+   * @param key - Data key to retrieve
+   * @returns Value or undefined
+   */
+  getData<T = unknown>(key: string): T | undefined;
+  /**
+   * Check if workflow is in a terminal state.
+   * @returns True if completed, failed, or cancelled
+   */
+  isTerminal(): boolean;
+  /**
+   * Check if workflow is running.
+   * @returns True if status is 'running'
+   */
+  isRunning(): boolean;
+  /**
+   * Get the current step definition.
+   * @returns Step definition or undefined
+   */
+  getCurrentStepDef(): Step | undefined;
+  /**
+   * Get the retry count for a step.
+   * @param stepId - Step to check (defaults to current step)
+   * @returns Number of retry attempts
+   */
+  getRetryCount(stepId?: string): number;
+  /**
+   * Check if a transition to a target step is valid.
+   * @param toStepId - Target step identifier
+   * @returns True if transition is valid from current step
+   */
+  canTransition(toStepId: string): boolean;
+  /**
+   * Get all available transitions from current step.
+   * @returns Array of available transitions
+   */
+  getAvailableTransitions(): AvailableTransition[];
+  /**
+   * Check if the current step has any outgoing transitions.
+   * @returns True if there are outgoing transitions
+   */
+  hasNextStep(): boolean;
+  /**
+   * Get remaining time for an SLA constraint.
+   * @param slaKey - 'totalDuration' or step ID
+   * @returns Remaining milliseconds, or null if no SLA configured
+   */
+  getRemainingTime(slaKey: string): number | null;
+  /**
+   * Check if an SLA constraint has been violated.
+   * @param slaKey - 'totalDuration' or step ID
+   * @returns True if SLA has been violated
+   */
+  isSlaViolated(slaKey: string): boolean;
+  /**
+   * Get status of all SLA constraints.
+   * @returns Array of SLA statuses
+   */
+  getAllSlaStatuses(): SlaStatus[];
+  /**
+   * Check if compensation/rollback is available.
+   * @returns True if workflow has compensation strategy
+   */
+  hasCompensation(): boolean;
+  /**
+   * Get steps that have compensation handlers.
+   * @returns Array of step IDs with compensation
+   */
+  getCompensableSteps(): string[];
+  /**
+   * Convert execution history to workflow events.
+   * @returns Array of workflow events
+   */
+  getEvents(): WorkflowEvent[];
+}
+/**
+ * Creates a workflow context from state and spec.
+ *
+ * @param state - Current workflow state
+ * @param spec - Workflow specification
+ * @returns WorkflowContext for interacting with the workflow
+ *
+ * @example
+ * ```typescript
+ * const state = await runner.getState(workflowId);
+ * const spec = registry.get(state.workflowName, state.workflowVersion);
+ * const ctx = createWorkflowContext(state, spec);
+ *
+ * console.log('Current step:', ctx.currentStep);
+ * console.log('Available transitions:', ctx.getAvailableTransitions());
+ * ```
+ */
+declare function createWorkflowContext<TData = Record<string, unknown>>(state: WorkflowState, spec: WorkflowSpec): WorkflowContext<TData>;
+/**
+ * Calculate workflow progress as a percentage.
+ *
+ * @param ctx - Workflow context
+ * @returns Progress percentage (0-100)
+ */
+declare function calculateWorkflowProgress(ctx: WorkflowContext): number;
+/**
+ * Get the duration of a workflow in milliseconds.
+ *
+ * @param ctx - Workflow context
+ * @returns Duration in milliseconds
+ */
+declare function getWorkflowDuration(ctx: WorkflowContext): number;
+/**
+ * Get the average step duration in milliseconds.
+ *
+ * @param ctx - Workflow context
+ * @returns Average duration or 0 if no completed steps
+ */
+declare function getAverageStepDuration(ctx: WorkflowContext): number;
+//#endregion
+export { AvailableTransition, SlaStatus, WorkflowContext, WorkflowContextError, WorkflowContextErrorType, WorkflowEvent, WorkflowTransitionResult, calculateWorkflowProgress, createWorkflowContext, getAverageStepDuration, getWorkflowDuration };