@shapeshift-labs/frontier-lang-compiler 0.2.103 → 0.2.104

package/dist/js-ts-semantic-conflict-sidecar-normalize.js

@@ -0,0 +1,203 @@
+import { uniqueStrings } from './native-import-utils.js';
+import { array, compactRecord, firstString, keysForAffected, keysForChange, normalizeChangeKind, numberOrUndefined, numberValue, strings } from './js-ts-semantic-conflict-sidecar-utils.js';
+
+export function normalizedChanges(input, context) {
+  return [
+    ...array(input.changes),
+    ...array(input.operations),
+    ...array(input.edits),
+    ...array(input.left?.changes).map((change) => ({ ...change, side: change.side ?? 'left' })),
+    ...array(input.left?.operations).map((change) => ({ ...change, side: change.side ?? 'left' })),
+    ...array(input.right?.changes).map((change) => ({ ...change, side: change.side ?? 'right' })),
+    ...array(input.right?.operations).map((change) => ({ ...change, side: change.side ?? 'right' }))
+  ].map((change, index) => normalizeChange(change, context, `change_${index + 1}`));
+}
+
+export function normalizeChange(change, context, fallbackId) {
+  const anchor = change.anchor ?? {};
+  const insertion = change.insertion ?? {};
+  const spans = change.spans ?? {};
+  const sourcePath = firstString(
+    change.sourcePath,
+    change.originalSourcePath,
+    change.targetSourcePath,
+    anchor.sourcePath,
+    insertion.sourcePath,
+    insertion.insertedSourcePath,
+    context.sourcePath
+  );
+  const span = normalizeSpan(
+    change.sourceSpan
+      ?? change.span
+      ?? change.range
+      ?? spans.head
+      ?? spans.worker
+      ?? spans.base
+      ?? anchor.sourceSpan
+      ?? insertion.insertedSourceSpan
+      ?? insertion.baseSpan
+      ?? insertion.headSpan,
+    sourcePath
+  );
+  const key = firstString(
+    change.conflictKey,
+    change.regionKey,
+    change.key,
+    change.semanticKey,
+    change.anchorKey,
+    anchor.conflictKey,
+    anchor.key,
+    anchor.regionId,
+    insertion.anchorKey
+  );
+  const listKey = firstString(change.listKey, change.orderedListKey, change.containerKey, change.parentKey, change.orderingKey);
+  return {
+    raw: change,
+    id: firstString(change.id, change.operationId, fallbackId),
+    side: firstString(change.side, change.author, change.branch, change.source, fallbackId),
+    changeKind: normalizeChangeKind(change.changeKind ?? change.kind ?? change.editKind ?? change.op),
+    sourcePath,
+    span,
+    key,
+    regionKey: firstString(change.regionKey, anchor.regionId, key),
+    conflictKey: firstString(change.conflictKey, anchor.conflictKey, key),
+    symbolId: firstString(change.symbolId, anchor.symbolId, insertion.insertedSymbolId),
+    symbolName: firstString(change.symbolName, anchor.symbolName, insertion.insertedSymbolName),
+    symbolKind: firstString(change.symbolKind, anchor.symbolKind, insertion.insertedSymbolKind),
+    memberName: firstString(change.memberName, change.name, change.symbolName, insertion.insertedSymbolName),
+    exportName: firstString(change.exportName, change.exportedName),
+    containerKey: firstString(change.containerKey, change.parentKey, anchor.regionId),
+    listKey,
+    orderedListKey: firstString(change.orderedListKey, listKey),
+    index: firstString(change.index, change.position, change.orderIndex),
+    position: firstString(change.position, change.index),
+    orderKey: firstString(change.orderKey, change.order, change.sortKey),
+    beforeKey: firstString(change.beforeKey, change.before, change.previousKey),
+    afterKey: firstString(change.afterKey, change.after, change.nextKey),
+    anchorKey: firstString(change.anchorKey, insertion.anchorKey, anchor.key),
+    sourceHash: firstString(change.sourceHash, change.currentSourceHash, change.targetHash),
+    reasonCodes: uniqueStrings([...strings(change.reasonCode), ...strings(change.reasonCodes)])
+  };
+}
+
+export function normalizeDeclaration(entry, index, context) {
+  const change = normalizeChange(entry, context, `declaration_${index + 1}`);
+  const name = firstString(entry.name, entry.memberName, entry.exportName, entry.symbolName, change.memberName, change.exportName, change.symbolName);
+  const exported = entry.exported === true || entry.isExport === true || Boolean(entry.exportName) || /export/i.test(String(entry.kind ?? entry.symbolKind ?? ''));
+  const member = entry.member === true || entry.isMember === true || Boolean(entry.memberName || entry.containerKey || entry.parentKey) || /member|method|field|property/i.test(String(entry.kind ?? entry.symbolKind ?? ''));
+  return {
+    ...change,
+    name,
+    exported,
+    member,
+    containerKey: firstString(entry.containerKey, entry.parentKey, entry.classKey, entry.ownerKey, change.containerKey),
+    key: firstString(entry.key, entry.semanticKey, change.key, name)
+  };
+}
+
+export function sameChangeRegion(left, right) {
+  if (left.id === right.id) return false;
+  if (left.side && right.side && left.side === right.side) return false;
+  const leftKeys = keysForChange(left);
+  const rightKeys = keysForChange(right);
+  if (leftKeys.some((key) => rightKeys.includes(key))) return true;
+  return spansOverlap(left.span, right.span);
+}
+
+export function spansOverlap(left, right) {
+  if (!left || !right) return false;
+  if (left.sourcePath && right.sourcePath && left.sourcePath !== right.sourcePath) return false;
+  const leftStart = numberValue(left.startOffset, left.start);
+  const leftEnd = numberValue(left.endOffset, left.end);
+  const rightStart = numberValue(right.startOffset, right.start);
+  const rightEnd = numberValue(right.endOffset, right.end);
+  if (Number.isFinite(leftStart) && Number.isFinite(leftEnd) && Number.isFinite(rightStart) && Number.isFinite(rightEnd)) {
+    return leftStart < rightEnd && rightStart < leftEnd;
+  }
+  const leftStartLine = numberValue(left.startLine, left.line);
+  const leftEndLine = numberValue(left.endLine, leftStartLine);
+  const rightStartLine = numberValue(right.startLine, right.line);
+  const rightEndLine = numberValue(right.endLine, rightStartLine);
+  if (Number.isFinite(leftStartLine) && Number.isFinite(leftEndLine) && Number.isFinite(rightStartLine) && Number.isFinite(rightEndLine)) {
+    return leftStartLine <= rightEndLine && rightStartLine <= leftEndLine;
+  }
+  return false;
+}
+
+export function affectedFromEntries(entries, context) {
+  return normalizeAffected({
+    sourcePath: uniqueStrings(entries.map((entry) => entry.sourcePath)),
+    sourceSpan: entries.map((entry) => entry.span ?? entry.sourceSpan).filter(Boolean),
+    key: entries.flatMap((entry) => keysForAffected(entry)),
+    symbolId: entries.map((entry) => entry.symbolId),
+    symbolName: entries.map((entry) => entry.symbolName ?? entry.name),
+    memberKey: entries.map((entry) => entry.memberName ? `${entry.containerKey ?? entry.sourcePath ?? context.sourcePath ?? 'member'}#${entry.memberName}` : undefined),
+    exportName: entries.map((entry) => entry.exportName ?? (entry.exported ? entry.name : undefined)),
+    orderedListKey: entries.map((entry) => entry.listKey ?? entry.orderedListKey),
+    sourceHash: entries.map((entry) => entry.sourceHash)
+  }, context);
+}
+
+export function normalizeAffected(value, context) {
+  const sourcePaths = uniqueStrings([
+    context.sourcePath,
+    ...strings(value.sourcePath),
+    ...strings(value.sourcePaths),
+    ...array(value.spans).map((span) => span?.sourcePath),
+    ...array(value.sourceSpan).map((span) => span?.sourcePath)
+  ]);
+  const spans = uniqueSpans([
+    ...array(value.sourceSpan),
+    ...array(value.span),
+    ...array(value.spans)
+  ].map((span) => normalizeSpan(span, sourcePaths[0])).filter(Boolean));
+  const keys = uniqueStrings([
+    ...strings(value.key),
+    ...strings(value.keys),
+    ...strings(value.conflictKey),
+    ...strings(value.conflictKeys),
+    ...strings(value.regionKey),
+    ...strings(value.regionKeys),
+    ...strings(value.semanticKey),
+    ...strings(value.anchorKey)
+  ]);
+  return {
+    sourcePaths,
+    spans,
+    keys,
+    regionKeys: uniqueStrings([...strings(value.regionKey), ...strings(value.regionKeys)]),
+    symbolIds: uniqueStrings([...strings(value.symbolId), ...strings(value.symbolIds)]),
+    symbolNames: uniqueStrings([...strings(value.symbolName), ...strings(value.symbolNames)]),
+    memberKeys: uniqueStrings([...strings(value.memberKey), ...strings(value.memberKeys)]),
+    exportNames: uniqueStrings([...strings(value.exportName), ...strings(value.exportNames)]),
+    orderedListKeys: uniqueStrings([...strings(value.orderedListKey), ...strings(value.orderedListKeys), ...strings(value.listKey)]),
+    sourceHashes: uniqueStrings([...strings(value.sourceHash), ...strings(value.sourceHashes)])
+  };
+}
+
+export function normalizeSpan(span, sourcePath) {
+  if (!span || typeof span !== 'object') return undefined;
+  return compactRecord({
+    sourcePath: span.sourcePath ?? span.path ?? sourcePath,
+    start: numberOrUndefined(span.start),
+    end: numberOrUndefined(span.end),
+    startOffset: numberOrUndefined(span.startOffset ?? span.offset),
+    endOffset: numberOrUndefined(span.endOffset),
+    startLine: numberOrUndefined(span.startLine ?? span.line),
+    startColumn: numberOrUndefined(span.startColumn ?? span.column),
+    endLine: numberOrUndefined(span.endLine ?? span.line),
+    endColumn: numberOrUndefined(span.endColumn)
+  });
+}
+
+export function uniqueSpans(spans) {
+  const seen = new Set();
+  const result = [];
+  for (const span of spans) {
+    const key = JSON.stringify(span);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    result.push(span);
+  }
+  return result;
+}

package/dist/js-ts-semantic-conflict-sidecar-utils.js

@@ -0,0 +1,190 @@
+import { uniqueStrings } from './native-import-utils.js';
+import { deleteChangeKinds, modifyChangeKinds, riskRank, severityRank } from './js-ts-semantic-conflict-sidecar-constants.js';
+
+export function changePairs(changes) {
+  const pairs = [];
+  for (let leftIndex = 0; leftIndex < changes.length; leftIndex += 1) {
+    for (let rightIndex = leftIndex + 1; rightIndex < changes.length; rightIndex += 1) {
+      pairs.push([changes[leftIndex], changes[rightIndex]]);
+    }
+  }
+  return pairs;
+}
+
+export function duplicateGroups(entries, keyFn) {
+  const groups = new Map();
+  for (const entry of entries) {
+    const key = keyFn(entry);
+    if (!key || /^(\|)+$/.test(key)) continue;
+    groups.set(key, [...(groups.get(key) ?? []), entry]);
+  }
+  return [...groups.values()].filter((group) => group.length > 1);
+}
+
+export function dedupeSidecars(records) {
+  const seen = new Set();
+  const result = [];
+  for (const record of records) {
+    const key = `${record.class}:${record.id}:${record.reasonCodes.join('|')}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    result.push(record);
+  }
+  return result.sort(compareSidecars);
+}
+
+function compareSidecars(left, right) {
+  return (riskRank[right.risk] ?? 2) - (riskRank[left.risk] ?? 2)
+    || (severityRank[right.severity] ?? 2) - (severityRank[left.severity] ?? 2)
+    || String(left.class).localeCompare(String(right.class))
+    || String(left.id).localeCompare(String(right.id));
+}
+
+export function mergeContext(input, options) {
+  return {
+    language: options.language ?? input.language ?? input.sourceLanguage ?? 'typescript',
+    sourcePath: options.sourcePath ?? input.sourcePath ?? input.path,
+    readiness: options.readiness ?? input.readiness,
+    expectedSourceHash: firstString(
+      options.expectedSourceHash,
+      input.expectedSourceHash,
+      input.expectedHash,
+      input.sourceHashAssertions?.expectedSourceHash,
+      input.sourceHashes?.expectedSourceHash
+    ),
+    currentSourceHash: firstString(
+      options.currentSourceHash,
+      input.currentSourceHash,
+      input.actualSourceHash,
+      input.sourceHashAssertions?.currentSourceHash,
+      input.sourceHashes?.currentSourceHash
+    )
+  };
+}
+
+export function keysForChange(change) {
+  return uniqueStrings([
+    change.key,
+    change.conflictKey,
+    change.regionKey,
+    change.semanticKey,
+    change.anchorKey
+  ]);
+}
+
+export function keysForAffected(entry) {
+  return uniqueStrings([
+    entry.key,
+    entry.conflictKey,
+    entry.regionKey,
+    entry.semanticKey,
+    entry.anchorKey,
+    entry.containerKey,
+    entry.id
+  ]);
+}
+
+export function lossText(entry) {
+  return [
+    entry?.kind,
+    entry?.code,
+    entry?.reasonCode,
+    ...(entry?.reasonCodes ?? []),
+    entry?.message,
+    entry?.summary,
+    entry?.category,
+    entry?.lossClass
+  ].filter(Boolean).join(' ');
+}
+
+export function lossReasonCodes(entry) {
+  return uniqueStrings([
+    ...strings(entry?.reasonCode),
+    ...strings(entry?.reasonCodes),
+    entry?.code,
+    entry?.kind
+  ]);
+}
+
+export function classesFromRecords(records) {
+  return records.map((record) => record.class);
+}
+
+export function summarySuggestedOutcome(records, readiness) {
+  if (!records.length) return 'auto-merge-safe';
+  const outcomes = uniqueStrings(records.map((record) => record.suggestedOutcome));
+  if (readiness === 'blocked') return outcomes.includes('rerun-parser-and-ledger-before-merge')
+    ? 'rerun-parser-and-ledger-before-merge'
+    : 'manual-merge-required';
+  return outcomes[0] ?? 'human-review';
+}
+
+export function highestSeverity(records) {
+  const value = Math.max(0, ...records.map((record) => severityRank[record.severity] ?? 2));
+  return Object.keys(severityRank).find((severity) => severityRank[severity] === value) ?? 'info';
+}
+
+export function highestRisk(records) {
+  const value = Math.max(0, ...records.map((record) => riskRank[record.risk] ?? 2));
+  return Object.keys(riskRank).find((risk) => riskRank[risk] === value) ?? 'low';
+}
+
+export function normalizeSeverity(value) {
+  const severity = String(value ?? '').toLowerCase();
+  return Object.prototype.hasOwnProperty.call(severityRank, severity) ? severity : undefined;
+}
+
+export function normalizeRisk(value) {
+  const risk = String(value ?? '').toLowerCase();
+  return Object.prototype.hasOwnProperty.call(riskRank, risk) ? risk : undefined;
+}
+
+export function normalizeChangeKind(value) {
+  const text = String(value ?? 'modify').toLowerCase();
+  if (text === 'removed') return 'delete';
+  if (text === 'added') return 'insert';
+  if (text === 'updated') return 'modify';
+  return text;
+}
+
+export function isDeleteChange(change) {
+  return deleteChangeKinds.test(change.changeKind);
+}
+
+export function isModifyChange(change) {
+  return modifyChangeKinds.test(change.changeKind);
+}
+
+export function isInsertChange(change) {
+  return /^(?:insert|add|create)$/i.test(change.changeKind);
+}
+
+export function numberValue(...values) {
+  for (const value of values) {
+    const number = Number(value);
+    if (Number.isFinite(number)) return number;
+  }
+  return undefined;
+}
+
+export function numberOrUndefined(value) {
+  const number = Number(value);
+  return Number.isFinite(number) ? number : undefined;
+}
+
+export function array(value) {
+  if (value === undefined || value === null) return [];
+  return Array.isArray(value) ? value : [value];
+}
+
+export function strings(value) {
+  return array(value).flatMap((entry) => Array.isArray(entry) ? strings(entry) : [String(entry ?? '')]).filter(Boolean);
+}
+
+export function firstString(...values) {
+  return values.map((value) => value === undefined || value === null ? '' : String(value)).find(Boolean);
+}
+
+export function compactRecord(value) {
+  return Object.fromEntries(Object.entries(value ?? {}).filter(([, entry]) => entry !== undefined && entry !== ''));
+}

package/dist/js-ts-semantic-conflict-sidecars.js

@@ -0,0 +1,81 @@
+import { countBy, idFragment, maxSemanticMergeReadiness, normalizeSemanticMergeReadiness, uniqueStrings } from './native-import-utils.js';
+import { JsTsSemanticConflictSidecarClasses } from './js-ts-semantic-conflict-sidecar-constants.js';
+import { deleteModifySidecars, duplicateDeclarationSidecars, explicitSidecars, orderedListSidecars, parserLedgerLossSidecars, sameRegionSidecars, staleSourceHashSidecars, unsupportedSyntaxSidecars } from './js-ts-semantic-conflict-sidecar-detectors.js';
+import { normalizedChanges } from './js-ts-semantic-conflict-sidecar-normalize.js';
+import { array, classesFromRecords, compactRecord, dedupeSidecars, highestRisk, highestSeverity, mergeContext, summarySuggestedOutcome } from './js-ts-semantic-conflict-sidecar-utils.js';
+
+export { JsTsSemanticConflictSidecarClasses } from './js-ts-semantic-conflict-sidecar-constants.js';
+
+export function createJsTsSemanticConflictSidecars(input = {}, options = {}) {
+  const context = mergeContext(input, options);
+  const changes = normalizedChanges(input, context);
+  const records = dedupeSidecars([
+    ...explicitSidecars(input, context),
+    ...sameRegionSidecars(changes, context),
+    ...deleteModifySidecars(changes, context),
+    ...duplicateDeclarationSidecars(input, changes, context),
+    ...orderedListSidecars(input, changes, context),
+    ...parserLedgerLossSidecars(input, context),
+    ...staleSourceHashSidecars(input, context),
+    ...unsupportedSyntaxSidecars(input, context)
+  ]);
+  const summary = summarizeJsTsSemanticConflictSidecars(records, context);
+  const id = options.id
+    ?? input.id
+    ?? `js_ts_semantic_conflict_sidecars_${idFragment(context.sourcePath ?? context.language ?? 'source')}`;
+  return {
+    kind: 'frontier.lang.jsTsSemanticMergeConflictSidecars',
+    version: 1,
+    schema: 'frontier.lang.jsTsSemanticMergeConflictSidecars.v1',
+    id,
+    language: context.language,
+    sourcePath: context.sourcePath,
+    expectedSourceHash: context.expectedSourceHash,
+    currentSourceHash: context.currentSourceHash,
+    conflicts: records,
+    sidecars: records,
+    summary,
+    admission: {
+      status: records.length ? summary.readiness : 'ready',
+      reviewRequired: records.length > 0,
+      autoMergeSafe: records.length === 0,
+      suggestedOutcome: summary.suggestedOutcome,
+      reasonCodes: summary.reasonCodes
+    },
+    metadata: compactRecord({
+      conflictSidecarSource: 'js-ts-semantic-merge',
+      ...options.metadata,
+      ...input.metadata
+    })
+  };
+}
+
+export function summarizeJsTsSemanticConflictSidecars(records = [], context = {}) {
+  const list = array(records).filter(Boolean);
+  const classes = uniqueStrings(list.map((record) => record.class));
+  const reasonCodes = uniqueStrings(list.flatMap((record) => record.reasonCodes ?? []));
+  const affectedSourcePaths = uniqueStrings([
+    context.sourcePath,
+    ...list.flatMap((record) => record.affected?.sourcePaths ?? [])
+  ]);
+  const affectedKeys = uniqueStrings(list.flatMap((record) => record.affected?.keys ?? []));
+  const readiness = list.reduce(
+    (current, record) => maxSemanticMergeReadiness(current, record.readiness ?? 'needs-review'),
+    normalizeSemanticMergeReadiness(context.readiness) ?? 'ready'
+  );
+  return {
+    schema: 'frontier.lang.jsTsSemanticConflictSidecarSummary.v1',
+    total: list.length,
+    classes,
+    byClass: countBy(classesFromRecords(list)),
+    bySeverity: countBy(list.map((record) => record.severity ?? 'warning')),
+    byRisk: countBy(list.map((record) => record.risk ?? 'medium')),
+    highestSeverity: highestSeverity(list),
+    highestRisk: highestRisk(list),
+    readiness,
+    affectedSourcePaths,
+    affectedKeys,
+    reasonCodes,
+    suggestedOutcome: summarySuggestedOutcome(list, readiness)
+  };
+}

package/dist/js-ts-semantic-merge-contract-helpers.js

@@ -0,0 +1,128 @@
+import { idFragment, normalizeSemanticMergeReadiness, uniqueStrings } from './native-import-utils.js';
+import { JsTsSemanticMergeGateStatuses } from './js-ts-semantic-merge-contracts.js';
+import { hashSemanticValue } from '@shapeshift-labs/frontier-lang-kernel';
+
+export function normalizeConflictSides(sides = {}) {
+  return compactRecord({
+    base: normalizeConflictSide('base', sides.base),
+    left: normalizeConflictSide('left', sides.left),
+    right: normalizeConflictSide('right', sides.right)
+  });
+}
+
+function normalizeConflictSide(side, value) {
+  if (!value) return undefined;
+  return compactRecord({
+    side: firstString(value.side, side),
+    sourcePath: firstString(value.sourcePath),
+    sourceHash: firstString(value.sourceHash),
+    editIds: uniqueStrings(value.editIds),
+    regionIds: uniqueStrings(value.regionIds),
+    tokenIds: uniqueStrings(value.tokenIds),
+    summary: firstString(value.summary),
+    metadata: value.metadata
+  });
+}
+
+export function normalizeGateChecks(checks, fallbackStatus) {
+  return array(checks).filter(Boolean).map((check, index) => {
+    const status = normalizeGateStatus(check.status) ?? fallbackStatus;
+    const name = firstString(check.name, check.id, `check-${index + 1}`);
+    const reasonCodes = uniqueStrings([
+      ...strings(check.reasonCodes),
+      ...strings(check.reasons),
+      ...(status === 'passed' ? [] : [`js-ts-merge-check:${status}`])
+    ]);
+    const stablePayload = compactRecord({
+      name,
+      status,
+      readiness: normalizeSemanticMergeReadiness(check.readiness) ?? check.readiness,
+      reasonCodes,
+      evidenceIds: uniqueStrings(check.evidenceIds)
+    });
+    const hash = firstString(check.hash) || hashSemanticValue(stablePayload);
+    return compactRecord({
+      id: firstString(check.id) || `js_ts_merge_check_${idFragment(name)}_${idFragment(hash)}`,
+      name,
+      status,
+      readiness: stablePayload.readiness,
+      reasonCodes,
+      evidenceIds: stablePayload.evidenceIds,
+      hash,
+      metadata: check.metadata
+    });
+  });
+}
+
+export function readinessForRisk(risk) {
+  if (risk === 'high') return 'blocked';
+  if (risk === 'low') return 'ready-with-losses';
+  return 'needs-review';
+}
+
+export function readinessForGateStatus(status, checks, conflictExplanationIds) {
+  if (status === 'blocked' || status === 'failed') return 'blocked';
+  if (conflictExplanationIds.length > 0) return 'needs-review';
+  if (checks.some((check) => check.status === 'failed' || check.status === 'blocked')) return 'blocked';
+  if (status === 'warning' || checks.some((check) => check.status === 'warning')) return 'ready-with-losses';
+  if (status === 'passed') return 'ready';
+  return 'needs-review';
+}
+
+export function actionForConflict({ risk, readiness }) {
+  if (readiness === 'blocked' || risk === 'high') return 'block';
+  if (readiness === 'ready') return 'merge';
+  return 'manual-review';
+}
+
+export function actionForGate({ status, readiness, mergeable }) {
+  if (mergeable) return 'merge';
+  if (status === 'blocked' || status === 'failed' || readiness === 'blocked') return 'block';
+  if (status === 'skipped') return 'skip';
+  return 'review';
+}
+
+export function titleForConflictClass(conflictClass) {
+  return String(conflictClass).split(/[-_]+/g).filter(Boolean).map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join(' ');
+}
+
+export function normalizeRisk(value) {
+  const risk = String(value ?? '').toLowerCase();
+  return risk === 'low' || risk === 'medium' || risk === 'high' ? risk : undefined;
+}
+
+export function normalizeGateStatus(value) {
+  const status = String(value ?? '').toLowerCase();
+  return JsTsSemanticMergeGateStatuses.includes(status) ? status : undefined;
+}
+
+export function booleanValue(...values) {
+  for (const value of values) {
+    if (typeof value === 'boolean') return value;
+  }
+  return undefined;
+}
+
+export function numberValue(...values) {
+  for (const value of values) {
+    if (typeof value === 'number' && Number.isFinite(value)) return value;
+  }
+  return undefined;
+}
+
+export function array(value) {
+  if (value === undefined || value === null) return [];
+  return Array.isArray(value) ? value : [value];
+}
+
+export function strings(value) {
+  return array(value).map((entry) => entry === undefined || entry === null ? '' : String(entry)).filter(Boolean);
+}
+
+export function firstString(...values) {
+  return values.map((value) => value === undefined || value === null ? '' : String(value)).find(Boolean);
+}
+
+export function compactRecord(value) {
+  return Object.fromEntries(Object.entries(value ?? {}).filter(([, entry]) => entry !== undefined));
+}