@shapeshift-labs/frontier-lang-compiler 0.2.77 → 0.2.78

package/README.md

@@ -422,6 +422,22 @@ console.log(targetChange.metadata.semanticEquivalenceClaim); // false
 
 Bidirectional target-change records are merge-admission evidence, not transpiler proof. They keep target diffs, source anchor matches, optional lineage resolutions, source patch-bundle records, semantic history records, evidence IDs, readiness, and reason codes. They always keep `autoMergeClaim: false` and `semanticEquivalenceClaim: false`; unmatched or deleted anchors block the source-port route, while matched and ambiguous anchors still require human or verifier review.
 
+When the target source came from a Frontier/native projection, pass the generated-output `sourceMaps` back into `createBidirectionalTargetChangeRecord`. The record will match target changed regions by generated span or generated name, emit `sourceMapLinks`, include `sourceMapBackedMatches` in the summary/evidence, and carry source-map mapping IDs into the source patch bundle index:
+
+```js
+const sourceMapBacked = createBidirectionalTargetChangeRecord({
+  source,
+  targetLanguage: 'rust',
+  targetPath: 'src/counter.rs',
+  baseTarget,
+  editedTarget,
+  sourceMaps: [projection.sourceMap]
+});
+
+console.log(sourceMapBacked.summary.sourceMapBackedMatches);
+console.log(sourceMapBacked.sourcePatchBundle.index.sourceMapMappingIds);
+```
+
 Store worker outputs as compact semantic history records when a coordinator needs to compare distributed changes without merging whole files:
 
 ```js

package/bench/smoke.mjs

@@ -116,6 +116,7 @@ console.log(JSON.stringify({
   semanticLineageInferenceDurationMs: Number(sourceChangeMetrics.semanticLineageInferenceDurationMs.toFixed(2)),
   bidirectionalTargetChanges: sourceChangeMetrics.bidirectionalTargetChanges,
   bidirectionalTargetChangeMatches: sourceChangeMetrics.bidirectionalTargetChangeMatches,
+  bidirectionalTargetChangeSourceMapBacked: sourceChangeMetrics.bidirectionalTargetChangeSourceMapBacked,
   bidirectionalTargetChangeBlocked: sourceChangeMetrics.bidirectionalTargetChangeBlocked,
   bidirectionalTargetChangeDurationMs: Number(sourceChangeMetrics.bidirectionalTargetChangeDurationMs.toFixed(2)),
   externalSemanticImports: sourceChangeMetrics.externalSemanticImports,

package/bench/source-change-suite.mjs

@@ -112,6 +112,8 @@ function measureBidirectionalTargetChanges() {
     sourcePath: 'src/bidirectional-source.ts',
     sourceText: 'export function advance(frame: number): number { return frame + 1; }\n'
   });
+  const sourceSymbol = source.semanticIndex.symbols.find((symbol) => symbol.name === 'advance');
+  const sourceMapping = source.sourceMaps[0].mappings.find((mapping) => mapping.semanticSymbolId === sourceSymbol.id);
   const lineage = [createSemanticLineageEvent({
     eventKind: 'moved',
     from: { key: 'source#src/bidirectional-source.ts#body#advance', symbolName: 'advance' },
@@ -134,18 +136,45 @@ function measureBidirectionalTargetChanges() {
         sourcePath: `src/bidirectional-${index}.rs`,
         sourceText: `pub fn advance(frame: i32, delta: i32) -> i32 { frame + delta + ${index} }\n`
       },
-      sourceAnchorMappings: [{ targetSymbolName: 'advance', sourceSymbolName: 'advance' }],
+      ...(index % 2 === 0
+        ? { sourceMaps: [rustSourceMap(source, sourceSymbol, sourceMapping, index)] }
+        : { sourceAnchorMappings: [{ targetSymbolName: 'advance', sourceSymbolName: 'advance' }] }),
       lineage: index % 4 === 0 ? lineage : []
     }));
   }
   return {
     bidirectionalTargetChanges: records.length,
     bidirectionalTargetChangeMatches: records.reduce((sum, record) => sum + record.summary.sourceAnchorMatches, 0),
+    bidirectionalTargetChangeSourceMapBacked: records.reduce((sum, record) => sum + record.summary.sourceMapBackedMatches, 0),
     bidirectionalTargetChangeBlocked: records.filter((record) => record.readiness === 'blocked').length,
     bidirectionalTargetChangeDurationMs: performance.now() - start
   };
 }
 
+function rustSourceMap(source, sourceSymbol, sourceMapping, index) {
+  const targetPath = `src/bidirectional-${index}.rs`;
+  return {
+    kind: 'frontier.lang.sourceMap',
+    version: 1,
+    id: `bench_source_map_bidirectional_${index}`,
+    sourcePath: source.sourcePath,
+    sourceHash: source.nativeSource.sourceHash,
+    target: 'rust',
+    targetPath,
+    mappings: [{
+      id: `bench_map_advance_${index}`,
+      semanticSymbolId: sourceSymbol.id,
+      nativeAstNodeId: sourceSymbol.nativeAstNodeId,
+      sourceSpan: sourceMapping.sourceSpan,
+      generatedSpan: { path: targetPath, target: 'rust', targetPath, startLine: 1, startColumn: 1, endLine: 1, endColumn: 80, generatedName: 'advance' },
+      target: 'rust',
+      generatedName: 'advance',
+      precision: 'declaration',
+      preservation: 'declaration'
+    }]
+  };
+}
+
 function measureExternalSemanticImports() {
   const externalSemanticStart = performance.now();
   const externalSemanticImports = [];

package/dist/declarations/bidirectional-target-change.d.ts

@@ -2,6 +2,8 @@ import type {
   EvidenceRecord,
   FrontierSourceLanguage,
   SemanticMergeReadiness,
+  SourceMapMappingRecord,
+  SourceMapRecord,
   SourceSpan
 } from '@shapeshift-labs/frontier-lang-kernel';
 import type { ImportNativeSourceOptions, NativeSourceImportResult } from './import-adapter-core.js';
@@ -27,6 +29,26 @@ export interface BidirectionalTargetChangeSourceAnchorMapping {
   readonly sourceSymbolId?: string;
 }
 
+export interface BidirectionalTargetChangeSourceMapLink {
+  readonly id: string;
+  readonly sourceMapId?: string;
+  readonly sourceMapMappingId?: string;
+  readonly sourcePath?: string;
+  readonly sourceHash?: string;
+  readonly targetPath?: string;
+  readonly targetHash?: string;
+  readonly semanticSymbolId?: string;
+  readonly semanticOccurrenceId?: string;
+  readonly semanticNodeId?: string;
+  readonly nativeSourceId?: string;
+  readonly nativeAstNodeId?: string;
+  readonly precision?: string;
+  readonly sourceSpan?: SourceSpan;
+  readonly generatedSpan?: SourceMapMappingRecord['generatedSpan'];
+  readonly regionKey?: string;
+  readonly regionKind?: string;
+}
+
 export interface BidirectionalTargetChangeAnchor {
   readonly id?: string;
   readonly key?: string;
@@ -47,6 +69,7 @@ export interface BidirectionalTargetChangeSourceAnchorMatch {
   readonly targetRegion: Partial<NativeSourceChangeRegion>;
   readonly sourceAnchors: readonly BidirectionalTargetChangeAnchor[];
   readonly lineageResolutions: readonly SemanticLineageResolution[];
+  readonly sourceMapLinks: readonly BidirectionalTargetChangeSourceMapLink[];
   readonly status: BidirectionalTargetChangeAnchorStatus;
   readonly confidence?: number;
   readonly reasonCodes: readonly string[];
@@ -77,6 +100,11 @@ export interface CreateBidirectionalTargetChangeRecordOptions {
   readonly after?: NativeSourceImportResult | ImportNativeSourceOptions;
   readonly sourceAnchorMappings?: readonly BidirectionalTargetChangeSourceAnchorMapping[];
   readonly anchorMappings?: readonly BidirectionalTargetChangeSourceAnchorMapping[];
+  readonly sourceMaps?: readonly SourceMapRecord[];
+  readonly projectionSourceMaps?: readonly SourceMapRecord[];
+  readonly targetSourceMaps?: readonly SourceMapRecord[];
+  readonly targetProjectionSourceMaps?: readonly SourceMapRecord[];
+  readonly targetCompileResult?: { readonly sourceMaps?: readonly SourceMapRecord[]; readonly sourceMap?: SourceMapRecord };
   readonly lineage?: readonly SemanticLineageEvent[];
   readonly lineageEvents?: readonly SemanticLineageEvent[];
   readonly lineageMap?: unknown;
@@ -114,6 +142,7 @@ export interface BidirectionalTargetChangeRecord {
     readonly unmatchedTargetRegions: number;
     readonly deletedSourceAnchors: number;
     readonly sourceChangedRegions: number;
+    readonly sourceMapBackedMatches: number;
   };
   readonly metadata: {
     readonly autoMergeClaim: false;

package/dist/internal/index-impl/bidirectionalTargetChangeRecordInternals.js

@@ -8,13 +8,14 @@ import { resolveSemanticLineage } from './semanticLineageResolutionRecords.js';
 
 export function matchTargetRegion(context) {
   const explicit = explicitMappingForRegion(context.region, context.mappings);
-  const candidateAnchors = explicit
-    ? sourceAnchorsForMapping(explicit, context.sourceAnchors)
-    : sourceAnchorsByName(context.region, context.sourceAnchors);
+  const mapped = explicit ? { anchors: sourceAnchorsForMapping(explicit, context.sourceAnchors), links: [] }
+    : sourceMapAnchorsForRegion(context.region, context.sourceMaps, context.sourceAnchors);
+  const candidateAnchors = mapped.anchors.length ? mapped.anchors : sourceAnchorsByName(context.region, context.sourceAnchors);
   const resolvedAnchors = candidateAnchors.flatMap((anchor) => resolveAnchor(anchor, context.lineage));
   const status = matchStatus(candidateAnchors, resolvedAnchors);
   const reasonCodes = uniqueStrings([
-    explicit ? 'explicit-anchor-mapping' : 'inferred-by-symbol-name',
+    explicit ? 'explicit-anchor-mapping' : mapped.links.length ? 'source-map-generated-anchor' : 'inferred-by-symbol-name',
+    mapped.links.length ? 'mapped-by-generated-source-map' : undefined,
     status === 'unmatched' ? 'source-anchor-not-found' : undefined,
     status === 'ambiguous' ? 'source-anchor-ambiguous' : undefined,
     status === 'deleted' ? 'source-anchor-deleted' : undefined,
@@ -27,8 +28,9 @@ export function matchTargetRegion(context) {
     targetRegion: compactRegion(context.region),
     sourceAnchors: resolvedAnchors.map((entry) => entry.anchor),
     lineageResolutions: uniqueRecordsById(resolvedAnchors.map((entry) => entry.resolution).filter(Boolean)),
+    sourceMapLinks: mapped.links,
     status,
-    confidence: status === 'matched' && explicit ? 0.8 : status === 'matched' ? 0.58 : undefined,
+    confidence: status === 'matched' && explicit ? 0.8 : status === 'matched' && mapped.links.length ? 0.72 : status === 'matched' ? 0.58 : undefined,
     reasonCodes,
     reviewRequired: true,
     autoMergeClaim: false,
@@ -37,6 +39,7 @@ export function matchTargetRegion(context) {
       context.region.conflictKey,
       context.region.key,
       ...resolvedAnchors.map((entry) => entry.anchor?.key),
+      ...mapped.links.map((link) => link.sourceMapMappingId && `source-map:${link.sourceMapMappingId}`),
       status === 'unmatched' ? `target:${context.region.sourcePath ?? context.region.language ?? 'unknown'}` : undefined
     ])
   };
@@ -65,6 +68,7 @@ export function sourceRegionsForMatch(match, readiness) {
     symbolId: anchor?.symbolId,
     symbolName: anchor?.symbolName,
     sourceSpan: anchor?.sourceSpan,
+    sourceMapLinks: match.sourceMapLinks,
     admission: {
       readiness,
       action: 'review-port-from-target-change',
@@ -75,6 +79,7 @@ export function sourceRegionsForMatch(match, readiness) {
       bidirectionalTargetChange: {
         matchId: match.id,
         targetRegion: match.targetRegion,
+        sourceMapLinkIds: match.sourceMapLinks.map((link) => link.id),
         lineageResolutionIds: match.lineageResolutions.map((resolution) => resolution.id),
         reviewRequired: true,
         autoMergeClaim: false,
@@ -97,6 +102,8 @@ export function createBidirectionalEvidence(context) {
       targetChangeSetId: context.targetChangeSet.id,
       targetPatchId: context.targetChangeSet.patch?.id,
       sourceAnchorMatchIds: context.sourceAnchorMatches.map((match) => match.id),
+      sourceMapBackedMatches: context.sourceAnchorMatches.filter((match) => match.sourceMapLinks.length > 0).length,
+      sourceMapLinkIds: context.sourceAnchorMatches.flatMap((match) => match.sourceMapLinks.map((link) => link.id)),
       readiness: context.readiness,
       reasons: context.reasons,
       autoMergeClaim: false,
@@ -105,6 +112,77 @@ export function createBidirectionalEvidence(context) {
   };
 }
 
+function sourceMapAnchorsForRegion(region, sourceMaps, sourceAnchors) {
+  const links = [];
+  const anchors = [];
+  for (const sourceMap of sourceMaps ?? []) {
+    for (const mapping of sourceMap?.mappings ?? []) {
+      if (!mappingMatchesTargetRegion(mapping, sourceMap, region)) continue;
+      const link = sourceMapLinkForMapping(sourceMap, mapping);
+      links.push(link);
+      anchors.push(...anchorsForSourceMapMapping(mapping, link, sourceAnchors));
+    }
+  }
+  return { anchors: uniqueRecordsById(anchors), links: uniqueRecordsById(links) };
+}
+
+function anchorsForSourceMapMapping(mapping, link, sourceAnchors) {
+  const matches = sourceAnchors.filter((anchor) =>
+    (mapping.semanticSymbolId && anchor.symbolId === mapping.semanticSymbolId)
+    || (mapping.semanticNodeId && anchor.id === mapping.semanticNodeId)
+    || (mapping.nativeAstNodeId && anchor.metadata?.nativeAstNodeId === mapping.nativeAstNodeId)
+    || (mapping.ownershipRegionKey && anchor.key === mapping.ownershipRegionKey)
+  );
+  if (matches.length) return matches;
+  return [compactRecord({
+    id: mapping.semanticSymbolId ?? mapping.semanticNodeId ?? mapping.nativeAstNodeId ?? link.id,
+    key: mapping.ownershipRegionKey ?? mapping.semanticSymbolId ?? mapping.semanticNodeId ?? link.id,
+    kind: mapping.ownershipRegionKind ?? 'source-map',
+    language: link.sourceSpan?.language,
+    sourcePath: link.sourcePath,
+    sourceHash: link.sourceHash,
+    symbolId: mapping.semanticSymbolId,
+    symbolName: mapping.generatedName ?? mapping.generatedSpan?.generatedName,
+    sourceSpan: mapping.sourceSpan,
+    metadata: { sourceMapId: link.sourceMapId, sourceMapMappingId: link.sourceMapMappingId }
+  })];
+}
+
+function mappingMatchesTargetRegion(mapping, sourceMap, region) {
+  if (!targetPathMatches(mapping, sourceMap, region)) return false;
+  if (mapping.generatedName && namesForRegion(region).includes(mapping.generatedName)) return true;
+  if (mapping.generatedSpan?.generatedName && namesForRegion(region).includes(mapping.generatedSpan.generatedName)) return true;
+  return spansOverlap(mapping.generatedSpan, region.sourceSpan);
+}
+
+function targetPathMatches(mapping, sourceMap, region) {
+  const targetPaths = uniqueStrings([mapping.generatedSpan?.targetPath, mapping.generatedSpan?.path, sourceMap?.targetPath]);
+  const regionPath = region.sourcePath ?? region.sourceSpan?.path;
+  return !regionPath || targetPaths.length === 0 || targetPaths.includes(regionPath);
+}
+
+function sourceMapLinkForMapping(sourceMap, mapping) {
+  return compactRecord({
+    id: `source_map_link_${idFragment(sourceMap?.id ?? 'map')}_${idFragment(mapping.id ?? mapping.semanticSymbolId ?? 'mapping')}`,
+    sourceMapId: sourceMap?.id,
+    sourceMapMappingId: mapping.id,
+    sourcePath: mapping.sourceSpan?.path ?? sourceMap?.sourcePath,
+    sourceHash: mapping.sourceSpan?.sourceId ?? sourceMap?.sourceHash,
+    targetPath: mapping.generatedSpan?.targetPath ?? sourceMap?.targetPath,
+    targetHash: mapping.generatedSpan?.targetHash ?? sourceMap?.targetHash,
+    semanticSymbolId: mapping.semanticSymbolId,
+    semanticOccurrenceId: mapping.semanticOccurrenceId,
+    semanticNodeId: mapping.semanticNodeId,
+    nativeSourceId: mapping.nativeSourceId,
+    nativeAstNodeId: mapping.nativeAstNodeId,
+    precision: mapping.precision,
+    sourceSpan: mapping.sourceSpan,
+    generatedSpan: mapping.generatedSpan,
+    regionKey: mapping.ownershipRegionKey,
+    regionKind: mapping.ownershipRegionKind
+  });
+}
+
 export function anchorsFromSourceSidecar(sidecar, source) {
   return uniqueRecordsById((sidecar.ownershipRegions ?? []).map((region) => compactRecord({
     id: region.id,
@@ -148,11 +226,15 @@ function sourceAnchorsForMapping(mapping, sourceAnchors) {
 }
 
 function sourceAnchorsByName(region, sourceAnchors) {
-  const names = uniqueStrings([region.symbolName, region.name, region.metadata?.changedRegionProjection?.region?.symbolName]);
+  const names = namesForRegion(region);
   if (names.length === 0) return [];
   return sourceAnchors.filter((anchor) => names.includes(anchor.symbolName));
 }
 
+function namesForRegion(region) {
+  return uniqueStrings([region.symbolName, region.name, region.metadata?.changedRegionProjection?.region?.symbolName]);
+}
+
 function resolveAnchor(anchor, lineage) {
   if (!anchor) return [];
   const resolution = array(lineage).length ? resolveSemanticLineage(lineage, { anchorKey: anchor.key }) : undefined;
@@ -189,6 +271,23 @@ function compactRegion(region) {
   });
 }
 
+function spansOverlap(left, right) {
+  if (!left || !right) return false;
+  if (!sourcePathsCompatible(left, right)) return false;
+  const leftStart = Number(left.startLine ?? 0);
+  const leftEnd = Number(left.endLine ?? left.startLine ?? 0);
+  const rightStart = Number(right.startLine ?? 0);
+  const rightEnd = Number(right.endLine ?? right.startLine ?? 0);
+  if (!leftStart || !rightStart) return false;
+  return leftStart <= rightEnd && rightStart <= leftEnd;
+}
+
+function sourcePathsCompatible(left, right) {
+  const leftPath = left.targetPath ?? left.path;
+  const rightPath = right.targetPath ?? right.path;
+  return !leftPath || !rightPath || leftPath === rightPath;
+}
+
 function array(value) {
   return value === undefined || value === null ? [] : Array.isArray(value) ? value : [value];
 }

package/dist/internal/index-impl/createBidirectionalTargetChangeRecord.js

@@ -1,5 +1,6 @@
 import {
   idFragment,
+  uniqueRecordsById,
   uniqueStrings
 } from '../../native-import-utils.js';
 import { createSemanticImportSidecar } from './createSemanticImportSidecar.js';
@@ -45,6 +46,14 @@ export function createBidirectionalTargetChangeRecord(input = {}, options = {})
   }) : undefined;
   const sourceAnchors = sourceSidecar ? anchorsFromSourceSidecar(sourceSidecar, source) : [];
   const mappings = array(input.sourceAnchorMappings ?? input.anchorMappings);
+  const sourceMaps = uniqueRecordsById([
+    ...array(input.sourceMaps),
+    ...array(input.projectionSourceMaps),
+    ...array(input.targetSourceMaps),
+    ...array(input.targetProjectionSourceMaps),
+    ...array(input.targetCompileResult?.sourceMaps),
+    input.targetCompileResult?.sourceMap
+  ]);
   const lineage = input.lineage ?? input.lineageEvents ?? input.lineageMap ?? [];
   const sourceAnchorMatches = targetChangeSet.changedRegions.map((region, index) => matchTargetRegion({
     id,
@@ -53,6 +62,7 @@ export function createBidirectionalTargetChangeRecord(input = {}, options = {})
     source,
     sourceAnchors,
     mappings,
+    sourceMaps,
     lineage
   }));
   const readiness = classifyBidirectionalReadiness(targetChangeSet, source, sourceAnchorMatches);
@@ -86,7 +96,8 @@ export function createBidirectionalTargetChangeRecord(input = {}, options = {})
       projectionOnly: true,
       targetChangeSetId: targetChangeSet.id,
       targetPatchId: targetChangeSet.patch?.id,
-      targetMergeCandidateId: targetChangeSet.mergeCandidate?.id
+      targetMergeCandidateId: targetChangeSet.mergeCandidate?.id,
+      sourceMapBackprojection: summarizeSourceMapBackprojection(sourceAnchorMatches)
     }
   }, {
     id: input.sourcePatchBundleId ?? `semantic_patch_bundle_${idFragment(id)}_source_port`,
@@ -127,6 +138,7 @@ export function createBidirectionalTargetChangeRecord(input = {}, options = {})
       bidirectionalTargetChangeId: id,
       sourcePatchBundleId: sourcePatchBundle.id,
       targetChangeSetId: targetChangeSet.id,
+      sourceMapBackprojection: summarizeSourceMapBackprojection(sourceAnchorMatches),
       autoMergeClaim: false,
       semanticEquivalenceClaim: false
     }
@@ -153,7 +165,8 @@ export function createBidirectionalTargetChangeRecord(input = {}, options = {})
       ambiguousMatches: sourceAnchorMatches.filter((match) => match.status === 'ambiguous').length,
       unmatchedTargetRegions: sourceAnchorMatches.filter((match) => match.status === 'unmatched').length,
       deletedSourceAnchors: sourceAnchorMatches.filter((match) => match.status === 'deleted').length,
-      sourceChangedRegions: sourceChangedRegions.length
+      sourceChangedRegions: sourceChangedRegions.length,
+      sourceMapBackedMatches: sourceAnchorMatches.filter((match) => match.sourceMapLinks.length > 0).length
     },
     metadata: {
       autoMergeClaim: false,
@@ -164,6 +177,16 @@ export function createBidirectionalTargetChangeRecord(input = {}, options = {})
   };
 }
 
+function summarizeSourceMapBackprojection(matches) {
+  const links = matches.flatMap((match) => match.sourceMapLinks ?? []);
+  return {
+    sourceMapBackedMatches: matches.filter((match) => (match.sourceMapLinks ?? []).length > 0).length,
+    sourceMapLinks: links.length,
+    sourceMapIds: uniqueStrings(links.map((link) => link.sourceMapId)),
+    sourceMapMappingIds: uniqueStrings(links.map((link) => link.sourceMapMappingId))
+  };
+}
+
 function array(value) {
   return value === undefined || value === null ? [] : Array.isArray(value) ? value : [value];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shapeshift-labs/frontier-lang-compiler",
-  "version": "0.2.77",
+  "version": "0.2.78",
   "description": "Compiler facade for Frontier Lang source documents and language projection adapters.",
   "type": "module",
   "main": "./dist/index.js",