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

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

@@ -0,0 +1,279 @@
+import { JsTsSafeMergeConflictCodes, JsTsSafeMergeGateIds } from './js-ts-safe-merge-constants.js';
+import { addConflict, arraysEqual, sameStatementText } from './js-ts-safe-merge-context.js';
+
+export function analyzeVariantLedger(base, variant, baseIndex, side, context) {
+  const projectedBaseKeys = [];
+  const addedEntries = [];
+  const importAdditions = new Map();
+  const baseKeys = new Set(baseIndex.orderedKeys);
+
+  for (const entry of variant.entries) {
+    const baseEntry = baseIndex.entriesByKey.get(entry.key);
+    if (!baseEntry) {
+      if (entry.kind === 'import') {
+        addConflict(context, {
+          code: JsTsSafeMergeConflictCodes.newImportDeclaration,
+          gateId: JsTsSafeMergeGateIds.independentImportSpecifiers,
+          side,
+          message: `${side} source adds a new import declaration; only specifier additions to existing imports are accepted.`,
+          details: { key: entry.key, statement: entry.text.trim() }
+        });
+      } else {
+        addedEntries.push(entry);
+      }
+      continue;
+    }
+    projectedBaseKeys.push(entry.key);
+    if (entry.kind !== baseEntry.kind) {
+      addConflict(context, {
+        code: JsTsSafeMergeConflictCodes.parserLedgerLoss,
+        gateId: JsTsSafeMergeGateIds.parseLedger,
+        side,
+        message: `${side} source changes a base ledger entry kind.`,
+        details: { key: entry.key, baseKind: baseEntry.kind, sideKind: entry.kind }
+      });
+      continue;
+    }
+    if (entry.kind === 'import') {
+      const additions = analyzeImportStatementChange(baseEntry, entry, side, context);
+      if (additions.length) importAdditions.set(entry.key, additions);
+    } else if (!sameStatementText(baseEntry.text, entry.text)) {
+      const typeAliasConflict = baseEntry.declarationInfo?.declarationKind === 'type'
+        || entry.declarationInfo?.declarationKind === 'type';
+      addConflict(context, {
+        code: typeAliasConflict ? JsTsSafeMergeConflictCodes.typeAliasConflict : JsTsSafeMergeConflictCodes.changedExistingDeclaration,
+        gateId: JsTsSafeMergeGateIds.stableExistingDeclarations,
+        side,
+        message: typeAliasConflict
+          ? `${side} source changes an existing type alias body.`
+          : `${side} source changes an existing top-level declaration or export body.`,
+        details: { key: entry.key, name: entry.names?.[0], declarationKind: entry.declarationInfo?.declarationKind }
+      });
+    }
+  }
+
+  if (!arraysEqual(projectedBaseKeys, baseIndex.orderedKeys)) {
+    const code = base.entries.some((entry) => entry.kind === 'import' && entry.importInfo.sideEffectOnly)
+      ? JsTsSafeMergeConflictCodes.sideEffectImportReorder
+      : JsTsSafeMergeConflictCodes.topLevelOrderChanged;
+    addConflict(context, {
+      code,
+      gateId: JsTsSafeMergeGateIds.preserveBaseOrder,
+      side,
+      message: `${side} source changes the order or presence of base top-level entries.`,
+      details: {
+        expected: baseIndex.orderedKeys,
+        actual: projectedBaseKeys
+      }
+    });
+  }
+
+  return {
+    side,
+    addedEntries,
+    importAdditions,
+    baseKeys
+  };
+}
+
+function analyzeImportStatementChange(baseEntry, variantEntry, side, context) {
+  const baseImport = baseEntry.importInfo;
+  const variantImport = variantEntry.importInfo;
+  if (!sameImportShape(baseImport, variantImport)) {
+    addConflict(context, {
+      code: baseImport.sideEffectOnly ? JsTsSafeMergeConflictCodes.sideEffectImportReorder : JsTsSafeMergeConflictCodes.importShapeChanged,
+      gateId: JsTsSafeMergeGateIds.independentImportSpecifiers,
+      side,
+      message: `${side} source changes an existing import shape instead of adding named specifiers.`,
+      details: { key: baseEntry.key }
+    });
+    return [];
+  }
+  if (baseImport.sideEffectOnly) {
+    if (!sameStatementText(baseEntry.text, variantEntry.text)) {
+      addConflict(context, {
+        code: JsTsSafeMergeConflictCodes.sideEffectImportReorder,
+        gateId: JsTsSafeMergeGateIds.preserveBaseOrder,
+        side,
+        message: `${side} source changes a side-effect import.`,
+        details: { key: baseEntry.key }
+      });
+    }
+    return [];
+  }
+
+  const baseSpecifiers = baseImport.specifiers;
+  const variantSpecifiers = variantImport.specifiers;
+  if (variantSpecifiers.length < baseSpecifiers.length) {
+    addConflict(context, {
+      code: JsTsSafeMergeConflictCodes.importSpecifierRemoved,
+      gateId: JsTsSafeMergeGateIds.independentImportSpecifiers,
+      side,
+      message: `${side} source removes import specifiers.`,
+      details: { key: baseEntry.key }
+    });
+    return [];
+  }
+  for (let index = 0; index < baseSpecifiers.length; index += 1) {
+    if (variantSpecifiers[index]?.canonical !== baseSpecifiers[index].canonical) {
+      addConflict(context, {
+        code: JsTsSafeMergeConflictCodes.importSpecifierReordered,
+        gateId: JsTsSafeMergeGateIds.independentImportSpecifiers,
+        side,
+        message: `${side} source reorders or changes existing import specifiers.`,
+        details: {
+          key: baseEntry.key,
+          expected: baseSpecifiers.map((specifier) => specifier.canonical),
+          actual: variantSpecifiers.map((specifier) => specifier.canonical)
+        }
+      });
+      return [];
+    }
+  }
+  const additions = variantSpecifiers.slice(baseSpecifiers.length);
+  if (additions.length === 0 && !sameStatementText(baseEntry.text, variantEntry.text)) {
+    addConflict(context, {
+      code: JsTsSafeMergeConflictCodes.importFormattingChanged,
+      gateId: JsTsSafeMergeGateIds.independentImportSpecifiers,
+      side,
+      message: `${side} source changes import formatting without a specifier addition.`,
+      details: { key: baseEntry.key }
+    });
+  }
+  return additions;
+}
+
+function sameImportShape(left, right) {
+  return left.moduleSpecifier === right.moduleSpecifier
+    && left.typeOnly === right.typeOnly
+    && left.sideEffectOnly === right.sideEffectOnly
+    && left.defaultLocalName === right.defaultLocalName
+    && left.namespaceLocalName === right.namespaceLocalName;
+}
+
+export function validateIndependentAdditions(base, workerPlan, headPlan, context) {
+  const declarationNames = new Set();
+  for (const entry of base.entries.filter((item) => item.kind !== 'import')) {
+    for (const name of entry.names ?? []) declarationNames.add(`${entry.kind}:${name}`);
+  }
+  validateAddedEntryNames(workerPlan, declarationNames, context);
+  validateAddedEntryNames(headPlan, declarationNames, context);
+  validateCrossSideAddedNames(workerPlan, headPlan, context);
+  validateCrossSideImportAdditions(workerPlan, headPlan, context);
+  validateMergedImportAndDeclarationNames(base, workerPlan, headPlan, context);
+}
+
+function validateAddedEntryNames(plan, baseNames, context) {
+  for (const entry of plan.addedEntries) {
+    if (entry.kind !== 'declaration' && entry.kind !== 'export') {
+      addConflict(context, {
+        code: JsTsSafeMergeConflictCodes.parserLedgerLoss,
+        gateId: JsTsSafeMergeGateIds.independentTopLevelDeclarations,
+        side: plan.side,
+        message: `${plan.side} source adds an unsupported top-level entry.`,
+        details: { kind: entry.kind, statement: entry.text.trim() }
+      });
+      continue;
+    }
+    for (const name of entry.names ?? []) {
+      const nameKey = `${entry.kind}:${name}`;
+      if (baseNames.has(nameKey)) {
+        addConflict(context, {
+          code: JsTsSafeMergeConflictCodes.duplicateName,
+          gateId: JsTsSafeMergeGateIds.uniqueNames,
+          side: plan.side,
+          message: `${plan.side} source adds a duplicate top-level name.`,
+          details: { name, kind: entry.kind }
+        });
+      }
+    }
+  }
+}
+
+function validateCrossSideAddedNames(workerPlan, headPlan, context) {
+  const headEntriesByName = new Map();
+  for (const entry of headPlan.addedEntries) {
+    for (const name of entry.names ?? []) headEntriesByName.set(`${entry.kind}:${name}`, entry);
+  }
+  for (const entry of workerPlan.addedEntries) {
+    for (const name of entry.names ?? []) {
+      const nameKey = `${entry.kind}:${name}`;
+      const headEntry = headEntriesByName.get(nameKey);
+      if (headEntry) {
+        const typeAliasConflict = entry.declarationInfo?.declarationKind === 'type'
+          || headEntry.declarationInfo?.declarationKind === 'type';
+        addConflict(context, {
+          code: typeAliasConflict ? JsTsSafeMergeConflictCodes.typeAliasConflict : JsTsSafeMergeConflictCodes.duplicateName,
+          gateId: JsTsSafeMergeGateIds.uniqueNames,
+          side: 'worker',
+          message: typeAliasConflict
+            ? 'Worker and head add conflicting type aliases.'
+            : 'Worker and head add the same top-level name.',
+          details: { name, kind: entry.kind, workerDeclarationKind: entry.declarationInfo?.declarationKind, headDeclarationKind: headEntry.declarationInfo?.declarationKind }
+        });
+      }
+    }
+  }
+}
+
+function validateCrossSideImportAdditions(workerPlan, headPlan, context) {
+  for (const [key, workerAdditions] of workerPlan.importAdditions) {
+    const headAdditions = headPlan.importAdditions.get(key) ?? [];
+    const headLocalNames = new Set(headAdditions.map((specifier) => specifier.localName));
+    const headImportedNames = new Set(headAdditions.map((specifier) => `${specifier.typeOnly ? 'type:' : 'value:'}${specifier.importedName}`));
+    for (const specifier of workerAdditions) {
+      if (headLocalNames.has(specifier.localName) || headImportedNames.has(`${specifier.typeOnly ? 'type:' : 'value:'}${specifier.importedName}`)) {
+        addConflict(context, {
+          code: JsTsSafeMergeConflictCodes.duplicateName,
+          gateId: JsTsSafeMergeGateIds.uniqueNames,
+          side: 'worker',
+          message: 'Worker and head add duplicate import specifiers.',
+          details: { key, specifier: specifier.canonical }
+        });
+      }
+    }
+  }
+}
+
+function validateMergedImportAndDeclarationNames(base, workerPlan, headPlan, context) {
+  const topLevelBindingNames = new Set();
+  for (const entry of base.entries.filter((item) => item.kind !== 'import')) {
+    for (const name of entry.names ?? []) topLevelBindingNames.add(name);
+  }
+  for (const plan of [workerPlan, headPlan]) {
+    for (const entry of plan.addedEntries.filter((item) => item.kind !== 'import')) {
+      for (const name of entry.names ?? []) topLevelBindingNames.add(name);
+    }
+  }
+  const importLocalNames = new Set();
+  for (const entry of base.entries.filter((item) => item.kind === 'import')) {
+    const additions = [
+      ...(workerPlan.importAdditions.get(entry.key) ?? []),
+      ...(headPlan.importAdditions.get(entry.key) ?? [])
+    ];
+    for (const specifier of [
+      ...(entry.importInfo.defaultLocalName ? [{ localName: entry.importInfo.defaultLocalName, canonical: `default:${entry.importInfo.defaultLocalName}` }] : []),
+      ...(entry.importInfo.namespaceLocalName ? [{ localName: entry.importInfo.namespaceLocalName, canonical: `namespace:${entry.importInfo.namespaceLocalName}` }] : []),
+      ...entry.importInfo.specifiers,
+      ...additions
+    ]) {
+      if (importLocalNames.has(specifier.localName)) {
+        addConflict(context, {
+          code: JsTsSafeMergeConflictCodes.duplicateName,
+          gateId: JsTsSafeMergeGateIds.uniqueNames,
+          message: 'Merged imports would contain duplicate local names.',
+          details: { localName: specifier.localName, specifier: specifier.canonical }
+        });
+      }
+      if (topLevelBindingNames.has(specifier.localName)) {
+        addConflict(context, {
+          code: JsTsSafeMergeConflictCodes.duplicateName,
+          gateId: JsTsSafeMergeGateIds.uniqueNames,
+          message: 'Merged imports would duplicate a top-level declaration name.',
+          details: { localName: specifier.localName, specifier: specifier.canonical }
+        });
+      }
+      importLocalNames.add(specifier.localName);
+    }
+  }
+}

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

@@ -0,0 +1,50 @@
+export const JsTsSafeMergeStatuses = Object.freeze({
+  merged: 'merged',
+  blocked: 'blocked'
+});
+
+export const JsTsSafeMergeGateIds = Object.freeze({
+  parseLedger: 'parse-ledger',
+  preserveBaseOrder: 'preserve-base-order',
+  stableExistingDeclarations: 'stable-existing-declarations',
+  independentImportSpecifiers: 'independent-import-specifiers',
+  independentTopLevelDeclarations: 'independent-top-level-declarations',
+  uniqueNames: 'unique-names',
+  resolvedInsertionAnchors: 'resolved-insertion-anchors'
+});
+
+export const JsTsSafeMergeConflictCodes = Object.freeze({
+  invalidInput: 'invalid-input',
+  parserLedgerLoss: 'parser-ledger-loss',
+  malformedSyntax: 'malformed-syntax',
+  sideEffectImportReorder: 'side-effect-import-reorder',
+  topLevelOrderChanged: 'top-level-order-changed',
+  changedExistingDeclaration: 'changed-existing-declaration',
+  typeAliasConflict: 'type-alias-conflict',
+  importShapeChanged: 'import-shape-changed',
+  importSpecifierRemoved: 'import-specifier-removed',
+  importSpecifierReordered: 'import-specifier-reordered',
+  importFormattingChanged: 'import-formatting-changed',
+  newImportDeclaration: 'new-import-declaration',
+  duplicateName: 'duplicate-name',
+  computedKey: 'computed-key',
+  unsupportedDecorator: 'unsupported-decorator-merge-anchor',
+  unsupportedOverload: 'unsupported-overload-merge-anchor',
+  staleSourceHash: 'stale-source-hash',
+  missingSourceLedgerSpan: 'missing-source-ledger-span',
+  ambiguousInsertionPoint: 'ambiguous-insertion-point',
+  insertionAnchorMissing: 'insertion-anchor-missing'
+});
+
+export const jsTsSafeMergeGateOrder = Object.freeze([
+  JsTsSafeMergeGateIds.parseLedger,
+  JsTsSafeMergeGateIds.preserveBaseOrder,
+  JsTsSafeMergeGateIds.stableExistingDeclarations,
+  JsTsSafeMergeGateIds.independentImportSpecifiers,
+  JsTsSafeMergeGateIds.independentTopLevelDeclarations,
+  JsTsSafeMergeGateIds.uniqueNames,
+  JsTsSafeMergeGateIds.resolvedInsertionAnchors
+]);
+
+const identifierPattern = '[A-Za-z_$][\\w$]*';
+export const identifierRegExp = new RegExp(`^${identifierPattern}$`);

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

@@ -0,0 +1,118 @@
+import { JsTsSafeMergeConflictCodes, JsTsSafeMergeGateIds, JsTsSafeMergeStatuses, jsTsSafeMergeGateOrder } from './js-ts-safe-merge-constants.js';
+
+export function createMergeContext(input) {
+  return {
+    id: String(input.id ?? 'js_ts_safe_merge'),
+    sourcePath: input.sourcePath,
+    language: input.language ?? 'typescript',
+    conflicts: [],
+    blockedGateIds: new Set(),
+    gateReasonCodes: new Map()
+  };
+}
+
+export function blockedResult(context, ledgers = {}) {
+  const reasonCodes = uniqueStrings(context.conflicts.map((conflict) => conflict.code));
+  return {
+    kind: 'frontier.lang.jsTsSafeMerge',
+    version: 1,
+    schema: 'frontier.lang.jsTsSafeMerge.v1',
+    id: context.id,
+    status: JsTsSafeMergeStatuses.blocked,
+    sourcePath: context.sourcePath,
+    language: context.language,
+    conflicts: context.conflicts,
+    gates: gatesFor(context),
+    admission: {
+      status: 'blocked',
+      action: 'human-review',
+      reviewRequired: true,
+      autoApplyCandidate: false,
+      autoMergeClaim: false,
+      semanticEquivalenceClaim: false,
+      reasonCodes
+    },
+    summary: {
+      importSpecifierAdditions: 0,
+      topLevelDeclarationAdditions: 0,
+      changedExistingDeclarations: context.conflicts.filter((conflict) => conflict.code === JsTsSafeMergeConflictCodes.changedExistingDeclaration).length,
+      conflicts: context.conflicts.length,
+      gatesPassed: gatesFor(context).filter((gate) => gate.status === 'passed').length
+    },
+    metadata: {
+      ledgers: compactRecord({
+        base: ledgerSummary(ledgers.base),
+        worker: ledgerSummary(ledgers.worker),
+        head: ledgerSummary(ledgers.head),
+        merged: ledgerSummary(ledgers.merged)
+      })
+    }
+  };
+}
+
+export function addConflict(context, conflict) {
+  const gateId = conflict.gateId ?? JsTsSafeMergeGateIds.parseLedger;
+  const record = {
+    code: conflict.code,
+    gateId,
+    message: conflict.message,
+    side: conflict.side,
+    sourcePath: context.sourcePath,
+    details: compactRecord(conflict.details)
+  };
+  context.conflicts.push(record);
+  context.blockedGateIds.add(gateId);
+  const gateReasonCodes = context.gateReasonCodes.get(gateId) ?? [];
+  gateReasonCodes.push(conflict.code);
+  context.gateReasonCodes.set(gateId, uniqueStrings(gateReasonCodes));
+}
+
+export function gatesFor(context) {
+  let blockedSeen = false;
+  return jsTsSafeMergeGateOrder.map((id) => {
+    const blocked = context.blockedGateIds.has(id);
+    const status = blocked ? 'blocked' : blockedSeen ? 'skipped' : 'passed';
+    if (blocked) blockedSeen = true;
+    return {
+      id,
+      status,
+      reasonCodes: context.gateReasonCodes.get(id) ?? []
+    };
+  });
+}
+
+export function sameStatementText(left, right) {
+  return normalizeLineEndings(String(left ?? '').trim(), '\n') === normalizeLineEndings(String(right ?? '').trim(), '\n');
+}
+
+export function normalizeLineEndings(text, lineEnding) {
+  return String(text ?? '').replace(/\r\n?/g, '\n').replace(/\n/g, lineEnding);
+}
+
+export function detectLineEnding(text) {
+  return String(text ?? '').includes('\r\n') ? '\r\n' : '\n';
+}
+
+export function arraysEqual(left, right) {
+  if (left.length !== right.length) return false;
+  return left.every((value, index) => value === right[index]);
+}
+
+export function uniqueStrings(values) {
+  return [...new Set((values ?? []).filter((value) => typeof value === 'string' && value.length > 0))];
+}
+
+export function compactRecord(record) {
+  return Object.fromEntries(Object.entries(record ?? {}).filter(([, value]) => value !== undefined));
+}
+
+export function ledgerSummary(ledger) {
+  if (!ledger) return undefined;
+  return {
+    label: ledger.label,
+    entries: ledger.entries.length,
+    imports: ledger.entries.filter((entry) => entry.kind === 'import').length,
+    declarations: ledger.entries.filter((entry) => entry.kind === 'declaration').length,
+    exports: ledger.entries.filter((entry) => entry.kind === 'export').length
+  };
+}

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

@@ -0,0 +1,92 @@
+import { JsTsSafeMergeConflictCodes, JsTsSafeMergeGateIds } from './js-ts-safe-merge-constants.js';
+import { addConflict } from './js-ts-safe-merge-context.js';
+
+export function validateLedgerUniqueness(ledger, context) {
+  const keyOwners = new Map();
+  for (const entry of ledger.entries) {
+    const existing = keyOwners.get(entry.key);
+    if (existing) {
+      addConflict(context, {
+        code: JsTsSafeMergeConflictCodes.duplicateName,
+        gateId: JsTsSafeMergeGateIds.uniqueNames,
+        side: ledger.label,
+        message: `${ledger.label} source has duplicate top-level ledger keys.`,
+        details: { key: entry.key, firstOffset: existing.start, secondOffset: entry.start }
+      });
+    } else {
+      keyOwners.set(entry.key, entry);
+    }
+  }
+
+  const nameOwners = new Map();
+  for (const entry of ledger.entries) {
+    for (const name of entry.names ?? []) {
+      const nameKey = `${entry.kind}:${name}`;
+      const existing = nameOwners.get(nameKey);
+      if (existing) {
+        addConflict(context, {
+          code: JsTsSafeMergeConflictCodes.duplicateName,
+          gateId: JsTsSafeMergeGateIds.uniqueNames,
+          side: ledger.label,
+          message: `${ledger.label} source has duplicate top-level names.`,
+          details: { name, firstOffset: existing.start, secondOffset: entry.start }
+        });
+      } else {
+        nameOwners.set(nameKey, entry);
+      }
+    }
+  }
+
+  for (const entry of ledger.entries.filter((item) => item.kind === 'import')) {
+    validateUniqueImportSpecifiers(entry, ledger.label, context);
+  }
+}
+
+function validateUniqueImportSpecifiers(entry, side, context) {
+  const localNames = new Map();
+  const specifiers = [
+    ...(entry.importInfo.defaultLocalName ? [{ localName: entry.importInfo.defaultLocalName, canonical: `default:${entry.importInfo.defaultLocalName}` }] : []),
+    ...(entry.importInfo.namespaceLocalName ? [{ localName: entry.importInfo.namespaceLocalName, canonical: `namespace:${entry.importInfo.namespaceLocalName}` }] : []),
+    ...entry.importInfo.specifiers
+  ];
+  for (const specifier of specifiers) {
+    const existing = localNames.get(specifier.localName);
+    if (existing) {
+      addConflict(context, {
+        code: JsTsSafeMergeConflictCodes.duplicateName,
+        gateId: JsTsSafeMergeGateIds.uniqueNames,
+        side,
+        message: `${side} source has duplicate import binding names.`,
+        details: { importKey: entry.key, localName: specifier.localName, first: existing.canonical, second: specifier.canonical }
+      });
+    } else {
+      localNames.set(specifier.localName, specifier);
+    }
+  }
+}
+
+export function indexBaseLedger(base, context) {
+  const entriesByKey = new Map();
+  for (const entry of base.entries) entriesByKey.set(entry.key, entry);
+  const names = new Set();
+  for (const entry of base.entries) {
+    for (const name of entry.names ?? []) {
+      const nameKey = `${entry.kind}:${name}`;
+      if (names.has(nameKey)) {
+        addConflict(context, {
+          code: JsTsSafeMergeConflictCodes.duplicateName,
+          gateId: JsTsSafeMergeGateIds.uniqueNames,
+          side: 'base',
+          message: 'Base source has duplicate declaration or export names.',
+          details: { name }
+        });
+      }
+      names.add(nameKey);
+    }
+  }
+  return {
+    entriesByKey,
+    orderedKeys: base.entries.map((entry) => entry.key),
+    names
+  };
+}

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

@@ -0,0 +1,85 @@
+import { JsTsSafeMergeConflictCodes, JsTsSafeMergeGateIds } from './js-ts-safe-merge-constants.js';
+import { addConflict } from './js-ts-safe-merge-context.js';
+import { classifyStatement, importSpecifierCanonical } from './js-ts-safe-merge-parse-declarations.js';
+import { findStatementEnd, skipTopLevelTrivia } from './js-ts-safe-merge-parse-statements.js';
+
+export function scanJsTsTopLevelLedger(sourceText, label, context) {
+  const entries = [];
+  let offset = 0;
+  while (offset < sourceText.length) {
+    const skipped = skipTopLevelTrivia(sourceText, offset);
+    if (skipped.error) {
+      addConflict(context, {
+        code: JsTsSafeMergeConflictCodes.parserLedgerLoss,
+        gateId: JsTsSafeMergeGateIds.parseLedger,
+        side: label,
+        message: `${label} source contains unterminated top-level trivia.`,
+        details: { offset, error: skipped.error }
+      });
+      return createLedger(label, sourceText, entries);
+    }
+    offset = skipped.offset;
+    if (offset >= sourceText.length) break;
+
+    if (sourceText[offset] === '@') {
+      addConflict(context, {
+        code: JsTsSafeMergeConflictCodes.unsupportedDecorator,
+        gateId: JsTsSafeMergeGateIds.parseLedger,
+        side: label,
+        message: `${label} source contains decorator syntax that is not safe for ledger merge anchors.`,
+        details: { offset, reasonCode: 'unsupported-js-ts-syntax', preview: sourceText.slice(offset, Math.min(sourceText.length, offset + 80)) }
+      });
+      return createLedger(label, sourceText, entries);
+    }
+
+    const end = findStatementEnd(sourceText, offset);
+    if (end.error) {
+      addConflict(context, {
+        code: JsTsSafeMergeConflictCodes.malformedSyntax,
+        gateId: JsTsSafeMergeGateIds.parseLedger,
+        side: label,
+        message: `${label} source contains a top-level statement the narrow ledger cannot bound.`,
+        details: { offset, error: end.error, preview: sourceText.slice(offset, Math.min(sourceText.length, offset + 80)) }
+      });
+      return createLedger(label, sourceText, entries);
+    }
+
+    const statementText = sourceText.slice(offset, end.offset);
+    const entry = classifyStatement(statementText, offset, end.offset);
+    if (entry?.unsupported) {
+      addConflict(context, {
+        code: entry.unsupported.code,
+        gateId: JsTsSafeMergeGateIds.parseLedger,
+        side: label,
+        message: `${label} source contains syntax that is not safe for automatic JS/TS ledger merge.`,
+        details: { offset, ...entry.unsupported.details, statement: statementText.trim().slice(0, 120) }
+      });
+      return createLedger(label, sourceText, entries);
+    }
+    if (!entry) {
+      addConflict(context, {
+        code: JsTsSafeMergeConflictCodes.parserLedgerLoss,
+        gateId: JsTsSafeMergeGateIds.parseLedger,
+        side: label,
+        message: `${label} source contains an unsupported top-level statement.`,
+        details: { offset, statement: statementText.trim().slice(0, 120) }
+      });
+      return createLedger(label, sourceText, entries);
+    }
+    entries.push(entry);
+    offset = end.offset;
+  }
+  return createLedger(label, sourceText, entries);
+}
+
+function createLedger(label, sourceText, entries) {
+  return {
+    label,
+    sourceText,
+    entries,
+    baseEntries: entries.filter((entry) => entry.kind === 'import' || entry.kind === 'declaration' || entry.kind === 'export')
+  };
+}
+
+export { importSpecifierCanonical } from './js-ts-safe-merge-parse-declarations.js';
+export { indexBaseLedger, validateLedgerUniqueness } from './js-ts-safe-merge-ledger-validation.js';