@_linked/translation 0.2.2

package/src/key-version.ts

@@ -0,0 +1,206 @@
+import type { MessageFormat } from './core/messages.js';
+import { analyzeMessage } from './message-format.js';
+
+export interface TranslationKeyVersionContract {
+  sourceLanguage: string;
+  sourceText: string;
+  format: MessageFormat;
+  argumentSignature: string;
+  contractHash: string;
+  sourceHash: string;
+}
+
+export interface DerivedBackfillKeyVersion
+  extends TranslationKeyVersionContract {
+  versionId: string;
+}
+
+export interface TranslationKeyVersionLike {
+  sourceText: string;
+  format: MessageFormat;
+  argumentSignature: string;
+}
+
+export interface ExtractedTranslationKeyContract {
+  sourceText: string;
+  format: MessageFormat;
+}
+
+export interface KeyVersionDecision {
+  action: 'unchanged' | 'create-version' | 'retire';
+  reason:
+    | 'same-source-and-contract'
+    | 'source-changed'
+    | 'format-changed'
+    | 'argument-contract-changed'
+    | 'missing-from-source';
+}
+
+const bytesToHex = (bytes: Uint8Array): string =>
+  [...bytes].map((byte) => byte.toString(16).padStart(2, '0')).join('');
+
+const ULID_ALPHABET = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
+const BIGINT_FIVE = BigInt(5);
+const BIGINT_EIGHT = BigInt(8);
+const BIGINT_THIRTY_ONE = BigInt(31);
+let lastUlidTime = -1;
+let lastUlidRandom = new Uint8Array(10);
+
+function encodeUlidTime(timestamp: number): string {
+  let value = BigInt(timestamp);
+  let encoded = '';
+  for (let index = 0; index < 10; index++) {
+    encoded = ULID_ALPHABET[Number(value & BIGINT_THIRTY_ONE)] + encoded;
+    value >>= BIGINT_FIVE;
+  }
+  return encoded;
+}
+
+function encodeUlidRandom(bytes: Uint8Array): string {
+  let value = BigInt(0);
+  for (const byte of bytes) value = (value << BIGINT_EIGHT) | BigInt(byte);
+  let encoded = '';
+  for (let index = 0; index < 16; index++) {
+    encoded = ULID_ALPHABET[Number(value & BIGINT_THIRTY_ONE)] + encoded;
+    value >>= BIGINT_FIVE;
+  }
+  return encoded;
+}
+
+function incrementRandom(bytes: Uint8Array): Uint8Array {
+  const next = new Uint8Array(bytes);
+  for (let index = next.length - 1; index >= 0; index--) {
+    next[index] = (next[index] + 1) & 0xff;
+    if (next[index] !== 0) return next;
+  }
+  throw new Error('ULID random component overflowed within one millisecond.');
+}
+
+/** Monotonic ULID for newly authored key versions. */
+export function createMonotonicVersionId(
+  now = Date.now(),
+  randomBytes?: Uint8Array,
+): string {
+  if (!Number.isSafeInteger(now) || now < 0 || now > 0xffffffffffff) {
+    throw new Error('ULID timestamp is outside the supported 48-bit range.');
+  }
+  const timestamp = Math.max(now, lastUlidTime);
+  if (timestamp === lastUlidTime) {
+    lastUlidRandom = incrementRandom(lastUlidRandom);
+  } else {
+    const next = randomBytes ?? globalThis.crypto.getRandomValues(new Uint8Array(10));
+    if (next.length !== 10) {
+      throw new Error('ULID randomness must contain exactly 10 bytes.');
+    }
+    lastUlidTime = timestamp;
+    lastUlidRandom = new Uint8Array(next);
+  }
+  return `${encodeUlidTime(timestamp)}${encodeUlidRandom(lastUlidRandom)}`;
+}
+
+/** Portable SHA-256 used by both the browser-safe package and Node publishers. */
+export async function sha256Hex(value: string): Promise<string> {
+  const digest = await globalThis.crypto.subtle.digest(
+    'SHA-256',
+    new TextEncoder().encode(value),
+  );
+  return bytesToHex(new Uint8Array(digest));
+}
+
+export function canonicalLanguageTag(language: string): string {
+  const value = language.trim();
+  if (!value) throw new Error('sourceLanguage is required.');
+  try {
+    return Intl.getCanonicalLocales(value)[0] ?? value;
+  } catch {
+    throw new Error(`Invalid BCP-47 source language: ${language}`);
+  }
+}
+
+/**
+ * Stable runtime-argument contract. Object/argument ordering is canonical so
+ * extraction order and translator word order cannot change the hash.
+ */
+export function createArgumentSignature(
+  sourceText: string,
+  format: MessageFormat,
+): string {
+  const analysis = analyzeMessage(sourceText, format);
+  if (!analysis.valid) {
+    throw new Error(
+      `Cannot version invalid ${format.toUpperCase()} source text: ${analysis.error}`,
+    );
+  }
+  return JSON.stringify(
+    analysis.arguments.map(({ name, kinds }) => [name, [...kinds].sort()]),
+  );
+}
+
+export function classifyKeyVersion(
+  current: TranslationKeyVersionLike | undefined,
+  extracted: ExtractedTranslationKeyContract | undefined,
+): KeyVersionDecision {
+  if (!extracted) {
+    return { action: 'retire', reason: 'missing-from-source' };
+  }
+  if (!current) {
+    return { action: 'create-version', reason: 'source-changed' };
+  }
+  if (current.format !== extracted.format) {
+    return { action: 'create-version', reason: 'format-changed' };
+  }
+  const nextSignature = createArgumentSignature(
+    extracted.sourceText,
+    extracted.format,
+  );
+  if (current.argumentSignature !== nextSignature) {
+    return {
+      action: 'create-version',
+      reason: 'argument-contract-changed',
+    };
+  }
+  if (current.sourceText !== extracted.sourceText) {
+    return { action: 'create-version', reason: 'source-changed' };
+  }
+  return { action: 'unchanged', reason: 'same-source-and-contract' };
+}
+
+export async function deriveTranslationKeyVersionContract(input: {
+  sourceLanguage: string;
+  sourceText: string;
+  format: MessageFormat;
+}): Promise<TranslationKeyVersionContract> {
+  const sourceLanguage = canonicalLanguageTag(input.sourceLanguage);
+  const argumentSignature = createArgumentSignature(
+    input.sourceText,
+    input.format,
+  );
+  const [sourceHash, contractHash] = await Promise.all([
+    sha256Hex(JSON.stringify([sourceLanguage, input.sourceText])),
+    sha256Hex(JSON.stringify([input.format, argumentSignature])),
+  ]);
+  return {
+    sourceLanguage,
+    sourceText: input.sourceText,
+    format: input.format,
+    argumentSignature,
+    contractHash,
+    sourceHash,
+  };
+}
+
+/**
+ * Existing keys need a deterministic first version so a restarted migration
+ * cannot create a second node. Future authored versions use monotonic ULIDs.
+ */
+export async function deriveBackfillKeyVersion(input: {
+  sourceLanguage: string;
+  sourceText: string;
+  format: MessageFormat;
+}): Promise<DerivedBackfillKeyVersion> {
+  const contract = await deriveTranslationKeyVersionContract(input);
+  return {
+    ...contract,
+    versionId: `backfill-${contract.sourceHash.slice(0, 16)}-${contract.contractHash.slice(0, 16)}`,
+  };
+}

package/src/languages.ts

@@ -0,0 +1,102 @@
+/** Portable language metadata. Codes are open BCP-47 strings, never an enum. */
+export interface TranslationLanguageDefinition {
+  id: string;
+  code: string;
+  nativeName: string;
+  englishName: string;
+  direction: 'ltr' | 'rtl';
+  parent?: string;
+  fallback?: string;
+  enabled: boolean;
+  supported: boolean;
+}
+
+export function canonicalLocale(code: string): string {
+  return (
+    Intl.getCanonicalLocales(code.trim())[0] ||
+    (() => {
+      throw new Error('Language code is required.');
+    })()
+  );
+}
+
+export function localeDirection(code: string): 'ltr' | 'rtl' {
+  const locale = new Intl.Locale(canonicalLocale(code));
+  const info = (locale as any).getTextInfo?.() ?? (locale as any).textInfo;
+  if (info?.direction) return info.direction;
+  // Script fallback for engines without Intl.Locale text information. This is
+  // a script property, not a closed list of supported languages.
+  return /^(Adlm|Arab|Hebr|Nkoo|Rohg|Samr|Syrc|Thaa)$/.test(
+    locale.maximize().script ?? ''
+  )
+    ? 'rtl'
+    : 'ltr';
+}
+
+export function defineLanguage(
+  code: string,
+  input: Partial<TranslationLanguageDefinition> = {}
+): TranslationLanguageDefinition {
+  code = canonicalLocale(code);
+  const base = new Intl.Locale(code).language;
+  const name = (locale: string) =>
+    new Intl.DisplayNames([locale], { type: 'language' }).of(code) ?? code;
+  return {
+    id: input.id ?? `https://id.linked.cm/language/${code}`,
+    code,
+    nativeName: input.nativeName || name(code),
+    englishName: input.englishName || name('en'),
+    direction: input.direction ?? localeDirection(code),
+    ...(base !== code ? { parent: base } : {}),
+    ...input,
+    enabled: input.enabled ?? true,
+    supported: input.supported ?? true,
+  };
+}
+
+/** Ordered explicit fallback chain, ending at the source; safe against cycles. */
+export function languageFallbacks(
+  code: string,
+  source: string,
+  definitions: readonly TranslationLanguageDefinition[] = []
+): string[] {
+  const byCode = new Map(
+    definitions.map((language) => [language.code, language])
+  );
+  const chain: string[] = [];
+  let current: string | undefined = canonicalLocale(code);
+  while (current && !chain.includes(current) && current !== source) {
+    chain.push(current);
+    current = byCode.get(current)?.fallback;
+  }
+  if (!chain.includes(source)) chain.push(source);
+  return chain;
+}
+
+export function validateLanguageDefinitions(
+  definitions: readonly TranslationLanguageDefinition[]
+): void {
+  const byCode = new Map(
+    definitions.map((language) => [language.code, language])
+  );
+  if (byCode.size !== definitions.length)
+    throw new Error('Duplicate language resources.');
+  for (const language of definitions) {
+    if (canonicalLocale(language.code) !== language.code)
+      throw new Error('Use canonical BCP-47 codes.');
+    if (!['ltr', 'rtl'].includes(language.direction))
+      throw new Error('Language direction must be ltr or rtl.');
+    for (const relation of ['fallback', 'parent'] as const) {
+      const visited = new Set([language.code]);
+      let target = language[relation];
+      while (target) {
+        if (visited.has(target))
+          throw new Error(`Cyclic language ${relation}: ${language.code}`);
+        visited.add(target);
+        if (!byCode.has(target))
+          throw new Error(`Missing ${relation} language resource: ${target}`);
+        target = byCode.get(target)?.[relation];
+      }
+    }
+  }
+}

package/src/linked-discovery.ts

@@ -0,0 +1,385 @@
+import type { MessageFormat } from './core/messages.js';
+import type {
+  TranslationDeclaration,
+  TranslationDiscoverySource,
+} from './discovery.js';
+import {
+  defineShapeTranslationCatalog,
+  shapeCatalogTranslationDiscoverySource,
+  type ShapeTranslationCatalog,
+  type ShapeTranslationCatalogEntry,
+} from './shape-catalog.js';
+
+export type LinkedSemanticEntryType =
+  | 'label'
+  | 'help'
+  | 'validation'
+  | 'controlled-value'
+  | 'workflow-role'
+  | 'skos-concept';
+
+export interface LinkedSemanticCatalogEntry {
+  key: string;
+  sourceText: string;
+  ownerIri: string;
+  namespace?: string;
+  description?: string;
+  format?: MessageFormat;
+  shapeIri?: string;
+  propertyIri?: string;
+  targetClass?: string;
+  type?: LinkedSemanticEntryType;
+}
+
+export interface LinkedComponentTranslationCatalog {
+  componentIri: string;
+  targetClass?: string;
+  entries: Array<Omit<LinkedSemanticCatalogEntry, 'ownerIri'>>;
+}
+
+export interface LinkedContentTranslationCatalogEntry {
+  key: string;
+  sourceText: string;
+  nodeIri: string;
+  propertyIri: string;
+  description?: string;
+  format?: MessageFormat;
+}
+
+export interface LinkedPackageTranslationCatalog {
+  schemaVersion: 1;
+  packageName: string;
+  shapes: ShapeTranslationCatalog[];
+  components: LinkedComponentTranslationCatalog[];
+  labels: LinkedSemanticCatalogEntry[];
+  controlledValues: LinkedSemanticCatalogEntry[];
+  workflowRoles: LinkedSemanticCatalogEntry[];
+  skosConcepts: LinkedSemanticCatalogEntry[];
+  content: LinkedContentTranslationCatalogEntry[];
+}
+
+function record(value: unknown, label: string): Record<string, unknown> {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error(`${label} must be an object.`);
+  }
+  return value as Record<string, unknown>;
+}
+
+function requiredString(value: unknown, label: string): string {
+  if (typeof value !== 'string' || !value.trim()) {
+    throw new Error(`${label} is required.`);
+  }
+  return value.trim();
+}
+
+function optionalString(value: unknown, label: string): string | undefined {
+  if (value === undefined) return undefined;
+  if (typeof value !== 'string' || !value.trim()) {
+    throw new Error(`${label} must be a non-empty string when supplied.`);
+  }
+  return value.trim();
+}
+
+function format(value: unknown, label: string): MessageFormat | undefined {
+  if (value === undefined) return undefined;
+  if (value !== 'simple' && value !== 'icu') {
+    throw new Error(`${label} must be "simple" or "icu".`);
+  }
+  return value;
+}
+
+function array(value: unknown, label: string): unknown[] {
+  if (value === undefined) return [];
+  if (!Array.isArray(value)) throw new Error(`${label} must be an array.`);
+  return value;
+}
+
+function semanticEntry(
+  value: unknown,
+  label: string,
+  expectedType?: LinkedSemanticEntryType,
+): LinkedSemanticCatalogEntry {
+  const entry = record(value, label);
+  const type = (entry.type ?? expectedType) as LinkedSemanticEntryType | undefined;
+  if (
+    type !== undefined &&
+    type !== 'label' &&
+    type !== 'help' &&
+    type !== 'validation' &&
+    type !== 'controlled-value' &&
+    type !== 'workflow-role' &&
+    type !== 'skos-concept'
+  ) {
+    throw new Error(`${label}.type is invalid.`);
+  }
+  if (typeof entry.sourceText !== 'string') {
+    throw new Error(`${label}.sourceText must be a string.`);
+  }
+  return {
+    key: requiredString(entry.key, `${label}.key`),
+    sourceText: entry.sourceText,
+    ownerIri: requiredString(entry.ownerIri, `${label}.ownerIri`),
+    ...(optionalString(entry.namespace, `${label}.namespace`)
+      ? { namespace: entry.namespace as string }
+      : {}),
+    ...(optionalString(entry.description, `${label}.description`)
+      ? { description: entry.description as string }
+      : {}),
+    ...(format(entry.format, `${label}.format`)
+      ? { format: entry.format as MessageFormat }
+      : {}),
+    ...(optionalString(entry.shapeIri, `${label}.shapeIri`)
+      ? { shapeIri: entry.shapeIri as string }
+      : {}),
+    ...(optionalString(entry.propertyIri, `${label}.propertyIri`)
+      ? { propertyIri: entry.propertyIri as string }
+      : {}),
+    ...(optionalString(entry.targetClass, `${label}.targetClass`)
+      ? { targetClass: entry.targetClass as string }
+      : {}),
+    ...(type ? { type } : {}),
+  };
+}
+
+function component(
+  value: unknown,
+  index: number,
+): LinkedComponentTranslationCatalog {
+  const item = record(value, `components[${index}]`);
+  const componentIri = requiredString(
+    item.componentIri,
+    `components[${index}].componentIri`,
+  );
+  const entries = array(item.entries, `components[${index}].entries`).map(
+    (raw, entryIndex) => {
+      const parsed = semanticEntry(
+        {
+          ...record(raw, `components[${index}].entries[${entryIndex}]`),
+          ownerIri: componentIri,
+        },
+        `components[${index}].entries[${entryIndex}]`,
+      );
+      const { ownerIri: _ownerIri, ...entry } = parsed;
+      return entry;
+    },
+  );
+  return {
+    componentIri,
+    entries,
+    ...(optionalString(item.targetClass, `components[${index}].targetClass`)
+      ? { targetClass: item.targetClass as string }
+      : {}),
+  };
+}
+
+function contentEntry(
+  value: unknown,
+  index: number,
+): LinkedContentTranslationCatalogEntry {
+  const entry = record(value, `content[${index}]`);
+  if (typeof entry.sourceText !== 'string') {
+    throw new Error(`content[${index}].sourceText must be a string.`);
+  }
+  return {
+    key: requiredString(entry.key, `content[${index}].key`),
+    sourceText: entry.sourceText,
+    nodeIri: requiredString(entry.nodeIri, `content[${index}].nodeIri`),
+    propertyIri: requiredString(
+      entry.propertyIri,
+      `content[${index}].propertyIri`,
+    ),
+    ...(optionalString(entry.description, `content[${index}].description`)
+      ? { description: entry.description as string }
+      : {}),
+    ...(format(entry.format, `content[${index}].format`)
+      ? { format: entry.format as MessageFormat }
+      : {}),
+  };
+}
+
+function shapeCatalog(value: unknown, index: number): ShapeTranslationCatalog {
+  const shape = record(value, `shapes[${index}]`);
+  return defineShapeTranslationCatalog({
+    schemaVersion: shape.schemaVersion as 1,
+    packageName: requiredString(
+      shape.packageName,
+      `shapes[${index}].packageName`,
+    ),
+    shapeIri: requiredString(shape.shapeIri, `shapes[${index}].shapeIri`),
+    ...(optionalString(shape.targetClass, `shapes[${index}].targetClass`)
+      ? { targetClass: shape.targetClass as string }
+      : {}),
+    entries: array(shape.entries, `shapes[${index}].entries`) as ShapeTranslationCatalogEntry[],
+  });
+}
+
+function assertNoDuplicateIdentities(
+  catalog: LinkedPackageTranslationCatalog,
+): void {
+  const messages = new Set<string>();
+  const add = (key: string, namespace = '') => {
+    const identity = JSON.stringify([namespace, key]);
+    if (messages.has(identity)) {
+      throw new Error(`Duplicate linked translation key "${key}".`);
+    }
+    messages.add(identity);
+  };
+  for (const shape of catalog.shapes) {
+    for (const entry of shape.entries) add(entry.key, entry.namespace);
+  }
+  for (const component of catalog.components) {
+    for (const entry of component.entries) add(entry.key, entry.namespace);
+  }
+  for (const entries of [
+    catalog.labels,
+    catalog.controlledValues,
+    catalog.workflowRoles,
+    catalog.skosConcepts,
+  ]) {
+    for (const entry of entries) add(entry.key, entry.namespace);
+  }
+  const content = new Set<string>();
+  for (const entry of catalog.content) {
+    const identity = JSON.stringify([entry.nodeIri, entry.propertyIri]);
+    if (content.has(identity)) {
+      throw new Error(
+        `Duplicate linked content translation field "${entry.nodeIri}" / "${entry.propertyIri}".`,
+      );
+    }
+    content.add(identity);
+  }
+}
+
+/** Parse serialized JSON only; package JavaScript is never imported or run. */
+export function parseLinkedPackageTranslationCatalog(
+  input: string | Uint8Array,
+): LinkedPackageTranslationCatalog {
+  let value: unknown;
+  try {
+    value = JSON.parse(
+      typeof input === 'string' ? input : new TextDecoder().decode(input),
+    );
+  } catch {
+    throw new Error('Linked translation catalog must be valid JSON.');
+  }
+  const raw = record(value, 'catalog');
+  if (raw.schemaVersion !== 1) {
+    throw new Error('Linked translation catalog schemaVersion must be 1.');
+  }
+  const catalog: LinkedPackageTranslationCatalog = {
+    schemaVersion: 1,
+    packageName: requiredString(raw.packageName, 'catalog.packageName'),
+    shapes: array(raw.shapes, 'catalog.shapes').map(shapeCatalog),
+    components: array(raw.components, 'catalog.components').map(component),
+    labels: array(raw.labels, 'catalog.labels').map((entry, index) =>
+      semanticEntry(entry, `labels[${index}]`, 'label'),
+    ),
+    controlledValues: array(
+      raw.controlledValues,
+      'catalog.controlledValues',
+    ).map((entry, index) =>
+      semanticEntry(
+        entry,
+        `controlledValues[${index}]`,
+        'controlled-value',
+      ),
+    ),
+    workflowRoles: array(raw.workflowRoles, 'catalog.workflowRoles').map(
+      (entry, index) =>
+        semanticEntry(entry, `workflowRoles[${index}]`, 'workflow-role'),
+    ),
+    skosConcepts: array(raw.skosConcepts, 'catalog.skosConcepts').map(
+      (entry, index) =>
+        semanticEntry(entry, `skosConcepts[${index}]`, 'skos-concept'),
+    ),
+    content: array(raw.content, 'catalog.content').map(contentEntry),
+  };
+  for (const shape of catalog.shapes) {
+    if (shape.packageName !== catalog.packageName) {
+      throw new Error(
+        `Shape catalog package "${shape.packageName}" does not match "${catalog.packageName}".`,
+      );
+    }
+  }
+  assertNoDuplicateIdentities(catalog);
+  return catalog;
+}
+
+function semanticDeclaration(
+  packageName: string,
+  category: string,
+  entry: LinkedSemanticCatalogEntry,
+): TranslationDeclaration {
+  return {
+    schemaVersion: 1,
+    key: entry.key,
+    sourceText: entry.sourceText,
+    kind: 'semantic',
+    format: entry.format ?? 'simple',
+    ...(entry.namespace ? { namespace: entry.namespace } : {}),
+    ...(entry.description ? { description: entry.description } : {}),
+    provenance: {
+      source: 'linked',
+      sourceId: `${packageName}:${category}:${entry.ownerIri}`,
+      authoritative: true,
+      ownerIri: entry.ownerIri,
+      fromPackage: packageName,
+      ...(entry.shapeIri ? { shapeIri: entry.shapeIri } : {}),
+      ...(entry.propertyIri ? { propertyIri: entry.propertyIri } : {}),
+      ...(entry.targetClass ? { targetClass: entry.targetClass } : {}),
+    },
+  };
+}
+
+/** Discover safe serialized LINKED package metadata without code execution. */
+export function linkedPackageTranslationDiscoverySource(
+  input: string | Uint8Array,
+): TranslationDiscoverySource {
+  const catalog = parseLinkedPackageTranslationCatalog(input);
+  return {
+    name: `linked-package:${catalog.packageName}`,
+    async *discover(context) {
+      for (const shape of catalog.shapes) {
+        yield* shapeCatalogTranslationDiscoverySource(shape).discover(context);
+      }
+      for (const component of catalog.components) {
+        for (const entry of component.entries) {
+          yield semanticDeclaration(catalog.packageName, 'component', {
+            ...entry,
+            ownerIri: component.componentIri,
+            targetClass: entry.targetClass ?? component.targetClass,
+          });
+        }
+      }
+      for (const [category, entries] of [
+        ['label', catalog.labels],
+        ['controlled-value', catalog.controlledValues],
+        ['workflow-role', catalog.workflowRoles],
+        ['skos-concept', catalog.skosConcepts],
+      ] as const) {
+        for (const entry of entries) {
+          yield semanticDeclaration(catalog.packageName, category, entry);
+        }
+      }
+      for (const entry of catalog.content) {
+        yield {
+          schemaVersion: 1,
+          key: entry.key,
+          sourceText: entry.sourceText,
+          kind: 'content',
+          format: entry.format ?? 'simple',
+          ...(entry.description ? { description: entry.description } : {}),
+          provenance: {
+            source: 'linked',
+            sourceId: `${catalog.packageName}:content:${entry.nodeIri}:${entry.propertyIri}`,
+            authoritative: true,
+            ownerIri: entry.nodeIri,
+            nodeIri: entry.nodeIri,
+            propertyIri: entry.propertyIri,
+            fromPackage: catalog.packageName,
+          },
+        };
+      }
+    },
+  };
+}