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

package/dist/js-ts-safe-merge.js

@@ -0,0 +1,175 @@
+import { analyzeVariantLedger, validateIndependentAdditions } from './js-ts-safe-merge-analyze.js';
+import { addConflict, blockedResult, compactRecord, createMergeContext, gatesFor } from './js-ts-safe-merge-context.js';
+import {
+  JsTsSafeMergeConflictCodes,
+  JsTsSafeMergeGateIds,
+  JsTsSafeMergeStatuses,
+  jsTsSafeMergeGateOrder
+} from './js-ts-safe-merge-constants.js';
+import { indexBaseLedger, scanJsTsTopLevelLedger, validateLedgerUniqueness } from './js-ts-safe-merge-ledger.js';
+import { applySourceMergePlan, createSourceMergePlan } from './js-ts-safe-merge-plan.js';
+
+export { JsTsSafeMergeConflictCodes, JsTsSafeMergeGateIds, JsTsSafeMergeStatuses };
+
+export function safeMergeJsTsImportsAndDeclarations(input = {}) {
+  const context = createMergeContext(input);
+  const baseSourceText = input.baseSourceText;
+  const workerSourceText = input.workerSourceText;
+  const headSourceText = input.headSourceText;
+
+  if (typeof baseSourceText !== 'string' || typeof workerSourceText !== 'string' || typeof headSourceText !== 'string') {
+    addConflict(context, {
+      code: JsTsSafeMergeConflictCodes.invalidInput,
+      gateId: JsTsSafeMergeGateIds.parseLedger,
+      message: 'baseSourceText, workerSourceText, and headSourceText must be strings.',
+      details: {
+        baseSourceText: typeof baseSourceText,
+        workerSourceText: typeof workerSourceText,
+        headSourceText: typeof headSourceText
+      }
+    });
+    return blockedResult(context);
+  }
+
+  validateStaleSourceHashes(input, context);
+  validateSourceLedgerSpans(input, context);
+  if (context.conflicts.length) return blockedResult(context);
+
+  const base = scanJsTsTopLevelLedger(baseSourceText, 'base', context);
+  const worker = scanJsTsTopLevelLedger(workerSourceText, 'worker', context);
+  const head = scanJsTsTopLevelLedger(headSourceText, 'head', context);
+  if (context.conflicts.length) return blockedResult(context, { base, worker, head });
+
+  validateLedgerUniqueness(base, context);
+  validateLedgerUniqueness(worker, context);
+  validateLedgerUniqueness(head, context);
+  if (context.conflicts.length) return blockedResult(context, { base, worker, head });
+
+  const baseIndex = indexBaseLedger(base, context);
+  if (context.conflicts.length) return blockedResult(context, { base, worker, head });
+
+  const workerPlan = analyzeVariantLedger(base, worker, baseIndex, 'worker', context);
+  const headPlan = analyzeVariantLedger(base, head, baseIndex, 'head', context);
+  validateIndependentAdditions(base, workerPlan, headPlan, context);
+  if (context.conflicts.length) return blockedResult(context, { base, worker, head });
+
+  const mergePlan = createSourceMergePlan(base, worker, head, workerPlan, headPlan, context);
+  if (context.conflicts.length) return blockedResult(context, { base, worker, head });
+
+  const mergedSourceText = applySourceMergePlan(headSourceText, mergePlan);
+  const merged = scanJsTsTopLevelLedger(mergedSourceText, 'merged', context);
+  if (!context.conflicts.length) validateLedgerUniqueness(merged, context);
+  if (context.conflicts.length) return blockedResult(context, { base, worker, head, merged });
+
+  return {
+    kind: 'frontier.lang.jsTsSafeMerge',
+    version: 1,
+    schema: 'frontier.lang.jsTsSafeMerge.v1',
+    id: context.id,
+    status: JsTsSafeMergeStatuses.merged,
+    sourcePath: context.sourcePath,
+    language: context.language,
+    mergedSourceText,
+    outputSourceText: mergedSourceText,
+    conflicts: [],
+    gates: gatesFor(context),
+    admission: {
+      status: 'auto-merge-candidate',
+      action: 'apply',
+      reviewRequired: false,
+      autoApplyCandidate: true,
+      autoMergeClaim: false,
+      semanticEquivalenceClaim: false,
+      reasonCodes: []
+    },
+    summary: {
+      importSpecifierAdditions: mergePlan.importSpecifierAdditions,
+      topLevelDeclarationAdditions: mergePlan.topLevelDeclarationAdditions,
+      changedExistingDeclarations: 0,
+      conflicts: 0,
+      gatesPassed: jsTsSafeMergeGateOrder.length
+    },
+    metadata: compactRecord({
+      workerChangeSetId: input.workerChangeSetId,
+      headChangeSetId: input.headChangeSetId,
+      baseHash: input.baseHash,
+      workerHash: input.workerHash,
+      headHash: input.headHash,
+      expectedSourceHash: input.expectedSourceHash,
+      currentSourceHash: input.currentSourceHash
+    })
+  };
+}
+
+function validateStaleSourceHashes(input, context) {
+  for (const pair of [
+    ['expectedSourceHash', 'currentSourceHash', 'head'],
+    ['expectedHeadHash', 'headHash', 'head'],
+    ['expectedBaseHash', 'baseHash', 'base'],
+    ['expectedWorkerHash', 'workerHash', 'worker']
+  ]) {
+    const [expectedField, currentField, side] = pair;
+    const expected = input[expectedField];
+    const current = input[currentField];
+    if (typeof expected !== 'string' || typeof current !== 'string' || expected === current) continue;
+    addConflict(context, {
+      code: JsTsSafeMergeConflictCodes.staleSourceHash,
+      gateId: JsTsSafeMergeGateIds.parseLedger,
+      side,
+      message: `${side} source hash is stale for safe merge anchors.`,
+      details: { expectedField, currentField, expected, current }
+    });
+  }
+}
+
+function validateSourceLedgerSpans(input, context) {
+  if (!input.requireSourceLedgerSpans && !input.sourceLedgers && !input.sourceLedger) return;
+  for (const side of ['base', 'worker', 'head']) {
+    const ledger = sourceLedgerForSide(input, side);
+    if (!ledger) {
+      addConflict(context, {
+        code: JsTsSafeMergeConflictCodes.missingSourceLedgerSpan,
+        gateId: JsTsSafeMergeGateIds.parseLedger,
+        side,
+        message: `${side} source is missing source ledger span evidence.`,
+        details: { side, missing: 'source-ledger' }
+      });
+      continue;
+    }
+    const spans = Array.isArray(ledger.spans) ? ledger.spans : Array.isArray(ledger.entries) ? ledger.entries : [];
+    if (!spans.length) {
+      addConflict(context, {
+        code: JsTsSafeMergeConflictCodes.missingSourceLedgerSpan,
+        gateId: JsTsSafeMergeGateIds.parseLedger,
+        side,
+        message: `${side} source ledger does not include span entries.`,
+        details: { side, missing: 'spans' }
+      });
+      continue;
+    }
+    const missingIndex = spans.findIndex((entry) => !hasLedgerSpan(entry));
+    if (missingIndex >= 0) {
+      addConflict(context, {
+        code: JsTsSafeMergeConflictCodes.missingSourceLedgerSpan,
+        gateId: JsTsSafeMergeGateIds.parseLedger,
+        side,
+        message: `${side} source ledger contains an entry without a source span.`,
+        details: { side, index: missingIndex, id: spans[missingIndex]?.id, kind: spans[missingIndex]?.kind }
+      });
+    }
+  }
+}
+
+function sourceLedgerForSide(input, side) {
+  return input.sourceLedgers?.[side]
+    ?? input[`${side}SourceLedger`]
+    ?? (input.sourceLedgerSide === side ? input.sourceLedger : undefined);
+}
+
+function hasLedgerSpan(entry) {
+  const span = entry?.span ?? entry?.sourceSpan;
+  if (!span) return false;
+  const hasOffsets = Number.isFinite(span.start) && Number.isFinite(span.end);
+  const hasLines = Number.isFinite(span.startLine) && Number.isFinite(span.endLine);
+  return hasOffsets || hasLines;
+}

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

@@ -0,0 +1,77 @@
+export const JsTsSemanticConflictSidecarClasses = Object.freeze([
+  'same-region',
+  'delete-modify',
+  'duplicate-export',
+  'duplicate-member',
+  'ordered-list-conflict',
+  'parser-ledger-loss',
+  'stale-source-hash',
+  'unsupported-syntax'
+]);
+
+export const classDefaults = Object.freeze({
+  'same-region': {
+    severity: 'error',
+    risk: 'high',
+    readiness: 'blocked',
+    reasonCodes: ['same-region-concurrent-edit'],
+    suggestedOutcome: 'manual-merge-required'
+  },
+  'delete-modify': {
+    severity: 'error',
+    risk: 'high',
+    readiness: 'blocked',
+    reasonCodes: ['delete-modify-same-region'],
+    suggestedOutcome: 'choose-delete-or-port-modification'
+  },
+  'duplicate-export': {
+    severity: 'error',
+    risk: 'high',
+    readiness: 'blocked',
+    reasonCodes: ['duplicate-export-name'],
+    suggestedOutcome: 'rename-or-remove-duplicate-export'
+  },
+  'duplicate-member': {
+    severity: 'error',
+    risk: 'high',
+    readiness: 'blocked',
+    reasonCodes: ['duplicate-member-name'],
+    suggestedOutcome: 'rename-or-remove-duplicate-member'
+  },
+  'ordered-list-conflict': {
+    severity: 'warning',
+    risk: 'medium',
+    readiness: 'needs-review',
+    reasonCodes: ['ordered-list-concurrent-position'],
+    suggestedOutcome: 'preserve-intended-order-with-human-review'
+  },
+  'parser-ledger-loss': {
+    severity: 'error',
+    risk: 'high',
+    readiness: 'blocked',
+    reasonCodes: ['parser-or-ledger-loss'],
+    suggestedOutcome: 'rerun-parser-and-ledger-before-merge'
+  },
+  'stale-source-hash': {
+    severity: 'error',
+    risk: 'high',
+    readiness: 'blocked',
+    reasonCodes: ['stale-source-hash'],
+    suggestedOutcome: 'rerun-semantic-import-before-merge'
+  },
+  'unsupported-syntax': {
+    severity: 'error',
+    risk: 'high',
+    readiness: 'blocked',
+    reasonCodes: ['unsupported-js-ts-syntax'],
+    suggestedOutcome: 'fall-back-to-textual-review'
+  }
+});
+
+export const severityRank = Object.freeze({ info: 1, warning: 2, error: 3 });
+export const riskRank = Object.freeze({ low: 1, medium: 2, high: 3 });
+export const orderedChangeKinds = /^(?:insert|add|move|reorder|replace|modify|update)$/i;
+export const deleteChangeKinds = /^(?:delete|remove|removed|deleted)$/i;
+export const modifyChangeKinds = /^(?:modify|modified|replace|update|edit|move|reorder|insert|add)$/i;
+export const parserLedgerLossPattern = /(?:parser|parse|ledger|source[-_ ]?map|anchor|projection).*(?:loss|lost|missing|failed|error)|(?:loss|lost|missing).*(?:parser|ledger|source[-_ ]?map|anchor|projection)/i;
+export const unsupportedSyntaxPattern = /unsupported|unhandled|unknown syntax|syntax unsupported/i;

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

@@ -0,0 +1,195 @@
+import { idFragment, normalizeSemanticMergeReadiness, uniqueStrings } from './native-import-utils.js';
+import { classDefaults, JsTsSemanticConflictSidecarClasses, orderedChangeKinds, parserLedgerLossPattern, unsupportedSyntaxPattern } from './js-ts-semantic-conflict-sidecar-constants.js';
+import { affectedFromEntries, normalizeAffected, normalizeChange, normalizeDeclaration, sameChangeRegion } from './js-ts-semantic-conflict-sidecar-normalize.js';
+import { array, changePairs, compactRecord, duplicateGroups, firstString, isDeleteChange, isInsertChange, isModifyChange, lossReasonCodes, lossText, normalizeRisk, normalizeSeverity, strings } from './js-ts-semantic-conflict-sidecar-utils.js';
+
+export function explicitSidecars(input, context) {
+  return [
+    ...array(input.conflicts),
+    ...array(input.sidecars),
+    ...array(input.conflictSidecars)
+  ]
+    .filter((record) => JsTsSemanticConflictSidecarClasses.includes(record?.class))
+    .map((record) => conflictSidecar(record.class, record, context));
+}
+
+export function sameRegionSidecars(changes, context) {
+  const records = [];
+  for (const [left, right] of changePairs(changes)) {
+    if (!sameChangeRegion(left, right)) continue;
+    records.push(conflictSidecar('same-region', {
+      id: `js_ts_conflict_${idFragment(left.id)}_${idFragment(right.id)}_same_region`,
+      affected: affectedFromEntries([left, right], context),
+      reasonCodes: ['same-region-concurrent-edit', ...left.reasonCodes, ...right.reasonCodes],
+      metadata: { leftChangeId: left.id, rightChangeId: right.id, leftChangeKind: left.changeKind, rightChangeKind: right.changeKind }
+    }, context));
+  }
+  return records;
+}
+
+export function deleteModifySidecars(changes, context) {
+  const records = [];
+  for (const [left, right] of changePairs(changes)) {
+    if (!sameChangeRegion(left, right)) continue;
+    if (!(isDeleteChange(left) && isModifyChange(right)) && !(isDeleteChange(right) && isModifyChange(left))) continue;
+    const deleted = isDeleteChange(left) ? left : right;
+    const modified = deleted === left ? right : left;
+    records.push(conflictSidecar('delete-modify', {
+      id: `js_ts_conflict_${idFragment(deleted.id)}_${idFragment(modified.id)}_delete_modify`,
+      affected: affectedFromEntries([deleted, modified], context),
+      reasonCodes: ['delete-modify-same-region', ...deleted.reasonCodes, ...modified.reasonCodes],
+      metadata: { deletedChangeId: deleted.id, modifiedChangeId: modified.id, deletedChangeKind: deleted.changeKind, modifiedChangeKind: modified.changeKind }
+    }, context));
+  }
+  return records;
+}
+
+export function duplicateDeclarationSidecars(input, changes, context) {
+  const declarations = [
+    ...array(input.declarations),
+    ...array(input.exports).map((entry) => ({ ...entry, exported: true })),
+    ...array(input.members).map((entry) => ({ ...entry, member: true })),
+    ...array(input.symbols),
+    ...changes.filter((change) => isInsertChange(change) && (change.memberName || change.exportName || change.symbolName))
+  ].map((entry, index) => normalizeDeclaration(entry, index, context)).filter((entry) => entry.name);
+  return [
+    ...duplicateGroups(declarations.filter((entry) => entry.exported), (entry) => [entry.sourcePath, entry.name].join('|'))
+      .map((group) => duplicateRecord('duplicate-export', group, context)),
+    ...duplicateGroups(declarations.filter((entry) => entry.member || entry.containerKey), (entry) => [entry.sourcePath, entry.containerKey, entry.name].join('|'))
+      .map((group) => duplicateRecord('duplicate-member', group, context))
+  ];
+}
+
+export function orderedListSidecars(input, changes, context) {
+  const explicitLists = array(input.orderedLists).flatMap((list, listIndex) =>
+    array(list.changes ?? list.operations ?? list.edits).map((change, changeIndex) => normalizeChange({
+      ...change,
+      listKey: change.listKey ?? list.key ?? list.id,
+      orderedListKey: change.orderedListKey ?? list.key ?? list.id,
+      sourcePath: change.sourcePath ?? list.sourcePath,
+      sourceSpan: change.sourceSpan ?? list.sourceSpan,
+      id: change.id ?? `${list.id ?? list.key ?? 'ordered_list'}_${changeIndex}`,
+      side: change.side ?? change.author ?? `list_${listIndex}`
+    }, context, `ordered_list_${listIndex}_${changeIndex}`))
+  );
+  const orderedChanges = [...changes, ...explicitLists].filter((change) =>
+    change.listKey && orderedChangeKinds.test(change.changeKind)
+  );
+  const groups = duplicateGroups(orderedChanges, (change) => [
+    change.sourcePath,
+    change.listKey,
+    firstString(change.index, change.position, change.orderKey, change.beforeKey, change.afterKey, change.anchorKey)
+  ].join('|'));
+  return groups.map((group) => conflictSidecar('ordered-list-conflict', {
+    id: `js_ts_conflict_${idFragment(group[0].listKey)}_${idFragment(firstString(group[0].index, group[0].position, group[0].orderKey, 'position'))}_ordered_list`,
+    affected: affectedFromEntries(group, context),
+    reasonCodes: ['ordered-list-concurrent-position', ...group.flatMap((entry) => entry.reasonCodes)],
+    metadata: {
+      listKey: group[0].listKey,
+      position: firstString(group[0].index, group[0].position, group[0].orderKey, group[0].beforeKey, group[0].afterKey),
+      changeIds: group.map((entry) => entry.id)
+    }
+  }, context));
+}
+
+export function parserLedgerLossSidecars(input, context) {
+  const losses = [
+    ...array(input.parserLosses),
+    ...array(input.ledgerLosses),
+    ...array(input.losses),
+    ...array(input.diagnostics)
+  ].filter((entry) => parserLedgerLossPattern.test(lossText(entry)) || entry?.kind === 'parser-ledger-loss');
+  if (!losses.length) return [];
+  return [conflictSidecar('parser-ledger-loss', {
+    id: `js_ts_conflict_${idFragment(context.sourcePath ?? context.language ?? 'source')}_parser_ledger_loss`,
+    severity: losses.some((entry) => entry.severity === 'error' || entry.status === 'failed') ? 'error' : undefined,
+    affected: affectedFromEntries(losses, context),
+    reasonCodes: ['parser-or-ledger-loss', ...losses.flatMap(lossReasonCodes)],
+    metadata: { lossIds: uniqueStrings(losses.map((entry) => entry.id)), lossKinds: uniqueStrings(losses.map((entry) => entry.kind ?? entry.code)) }
+  }, context)];
+}
+
+export function staleSourceHashSidecars(input, context) {
+  if (!context.expectedSourceHash || !context.currentSourceHash) return [];
+  if (context.expectedSourceHash === context.currentSourceHash && input.staleSourceHash !== true) return [];
+  return [conflictSidecar('stale-source-hash', {
+    id: `js_ts_conflict_${idFragment(context.sourcePath ?? context.language ?? 'source')}_stale_source_hash`,
+    affected: affectedFromEntries([{ sourcePath: context.sourcePath, sourceHash: context.currentSourceHash, key: context.sourcePath }], context),
+    reasonCodes: ['stale-source-hash', 'expected-source-hash-mismatch'],
+    metadata: { expectedSourceHash: context.expectedSourceHash, currentSourceHash: context.currentSourceHash }
+  }, context)];
+}
+
+export function unsupportedSyntaxSidecars(input, context) {
+  const entries = [
+    ...array(input.unsupportedSyntax),
+    ...array(input.syntaxUnsupported),
+    ...array(input.syntaxLosses),
+    ...array(input.losses).filter((entry) => unsupportedSyntaxPattern.test(lossText(entry)))
+  ];
+  if (!entries.length) return [];
+  return entries.map((entry, index) => conflictSidecar('unsupported-syntax', {
+    id: entry.id ?? `js_ts_conflict_${idFragment(context.sourcePath ?? context.language ?? 'source')}_${index + 1}_unsupported_syntax`,
+    affected: affectedFromEntries([entry], context),
+    reasonCodes: ['unsupported-js-ts-syntax', ...lossReasonCodes(entry)],
+    metadata: compactRecord({
+      syntaxKind: entry.kind ?? entry.syntaxKind,
+      parser: entry.parser,
+      message: entry.message ?? entry.summary
+    })
+  }, context));
+}
+
+export function duplicateRecord(conflictClass, group, context) {
+  return conflictSidecar(conflictClass, {
+    id: `js_ts_conflict_${idFragment(group[0].sourcePath ?? context.sourcePath ?? 'source')}_${idFragment(group[0].containerKey ?? 'export')}_${idFragment(group[0].name)}_${conflictClass.replace(/-/g, '_')}`,
+    affected: affectedFromEntries(group, context),
+    reasonCodes: [conflictClass === 'duplicate-member' ? 'duplicate-member-name' : 'duplicate-export-name'],
+    metadata: {
+      duplicateName: group[0].name,
+      containerKey: group[0].containerKey,
+      declarationIds: group.map((entry) => entry.id)
+    }
+  }, context);
+}
+
+export function conflictSidecar(conflictClass, input, context) {
+  const defaults = classDefaults[conflictClass] ?? classDefaults['same-region'];
+  const affected = normalizeAffected(input.affected ?? input, context);
+  const reasonCodes = uniqueStrings([
+    ...defaults.reasonCodes,
+    ...strings(input.reasonCode),
+    ...strings(input.reasonCodes)
+  ]);
+  const severity = normalizeSeverity(input.severity) ?? defaults.severity;
+  const risk = normalizeRisk(input.risk) ?? defaults.risk;
+  const readiness = normalizeSemanticMergeReadiness(input.readiness) ?? defaults.readiness;
+  const suggestedOutcome = input.suggestedOutcome ?? input.outcome ?? defaults.suggestedOutcome;
+  const id = input.id ?? `js_ts_conflict_${idFragment(conflictClass)}_${idFragment([
+    ...affected.keys,
+    ...affected.sourcePaths,
+    ...reasonCodes
+  ].join('_'))}`;
+  return {
+    kind: 'frontier.lang.jsTsSemanticMergeConflictSidecar',
+    version: 1,
+    schema: 'frontier.lang.jsTsSemanticMergeConflictSidecar.v1',
+    id,
+    class: conflictClass,
+    severity,
+    risk,
+    readiness,
+    affected,
+    reasonCodes,
+    suggestedOutcome,
+    explanation: {
+      class: conflictClass,
+      severity,
+      risk,
+      affected,
+      reasonCodes,
+      suggestedOutcome
+    },
+    metadata: compactRecord(input.metadata)
+  };
+}

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