@shapeshift-labs/frontier-lang-compiler 0.2.66 → 0.2.68

package/dist/universal-runtime-route-records.js

@@ -0,0 +1,162 @@
+import {
+  idFragment,
+  uniqueStrings
+} from './native-import-utils.js';
+
+export function runtimeRoute(sourceHost, targetHost, input) {
+  const requiredCapabilities = requirementsForRoute(input.requirements, sourceHost, targetHost);
+  const requirementRows = requiredCapabilities.map((capability) => runtimeCapabilityRequirement(capability, sourceHost, targetHost, input));
+  const adapterRequirements = requirementRows.filter((row) => row.adapterRequired).map((row) => row.adapterRequirement);
+  const satisfiedCapabilities = requirementRows.filter((row) => !row.adapterRequired).map((row) => row.capability);
+  const missingCapabilities = requirementRows.filter((row) => row.targetSupport === 'unavailable').map((row) => row.capability);
+  const blockers = requirementRows.filter((row) => row.sourceSupport === 'unavailable')
+    .map((row) => `Source host ${sourceHost.id} does not declare required runtime capability ${row.capability}.`);
+  const review = adapterRequirements.map((requirement) => requirement.reason);
+  const id = `runtime_${idFragment(sourceHost.id)}_to_${idFragment(targetHost.id)}_${idFragment(targetHost.target)}`;
+  return {
+    id,
+    source: runtimeHostSummary(sourceHost),
+    target: runtimeHostSummary(targetHost),
+    requiredCapabilities,
+    satisfiedCapabilities,
+    adapterRequirements,
+    missingCapabilities,
+    readiness: blockers.length ? 'blocked' : adapterRequirements.length ? 'needs-review' : 'ready',
+    blockers,
+    review: uniqueStrings(review),
+    metadata: {
+      generatedAt: input.generatedAt,
+      note: 'Runtime adapter requirements describe host API obligations only; parser, syntax, and target-projection evidence remain separate.'
+    }
+  };
+}
+
+function requirementsForRoute(requirements, sourceHost, targetHost) {
+  return uniqueStrings((requirements ?? []).filter((requirement) => requirementApplies(requirement, sourceHost, targetHost))
+    .map((requirement) => requirement.capability));
+}
+
+function requirementApplies(requirement, sourceHost, targetHost) {
+  if (requirement.sourceHostId && requirement.sourceHostId !== sourceHost.id) return false;
+  if (requirement.targetHostId && requirement.targetHostId !== targetHost.id) return false;
+  if (requirement.sourceLanguage && !sourceHost.languageIds.includes(requirement.sourceLanguage)) return false;
+  if (requirement.sourceRuntime && requirement.sourceRuntime !== sourceHost.runtime && requirement.sourceRuntime !== sourceHost.id) return false;
+  if (requirement.target && requirement.target !== targetHost.target) return false;
+  if (requirement.targetRuntime && requirement.targetRuntime !== targetHost.runtime && requirement.targetRuntime !== targetHost.id) return false;
+  return Boolean(requirement.capability);
+}
+
+function runtimeCapabilityRequirement(capability, sourceHost, targetHost, input) {
+  const sourceCapability = sourceHost.capabilities[capability] ?? unavailableCapability(capability, sourceHost.id);
+  const targetCapability = targetHost.capabilities[capability] ?? unavailableCapability(capability, targetHost.id);
+  const compatible = runtimeCapabilityCompatible(sourceHost, targetHost, sourceCapability, targetCapability);
+  const reason = runtimeAdapterReason(capability, sourceHost, targetHost, sourceCapability, targetCapability);
+  return {
+    capability,
+    sourceSupport: sourceCapability.support,
+    targetSupport: targetCapability.support,
+    sourceBinding: sourceCapability.binding,
+    targetBinding: targetCapability.binding,
+    adapterRequired: !compatible,
+    adapterRequirement: compatible ? undefined : {
+      id: `runtime_adapter_${idFragment(sourceHost.id)}_${idFragment(targetHost.id)}_${idFragment(capability)}`,
+      capability,
+      adapterKind: runtimeAdapterKind(capability, sourceHost, targetHost),
+      sourceHost: sourceHost.id,
+      targetHost: targetHost.id,
+      sourceBinding: sourceCapability.binding,
+      targetBinding: targetCapability.binding,
+      required: true,
+      reason,
+      evidenceIds: uniqueStrings(input.requirements
+        .filter((requirement) => requirement.capability === capability && requirementApplies(requirement, sourceHost, targetHost))
+        .flatMap((requirement) => requirement.evidenceIds ?? []))
+    }
+  };
+}
+
+function runtimeCapabilityCompatible(sourceHost, targetHost, sourceCapability, targetCapability) {
+  if (sourceHost.id === targetHost.id) return true;
+  if (sourceCapability.support === 'unavailable' || targetCapability.support === 'unavailable') return false;
+  return sourceCapability.binding === targetCapability.binding;
+}
+
+function unavailableCapability(kind, hostId) {
+  return {
+    kind,
+    support: 'unavailable',
+    binding: `${hostId}.${kind}.unavailable`,
+    notes: []
+  };
+}
+
+function runtimeHostSummary(host) {
+  return {
+    id: host.id,
+    language: host.language,
+    aliases: host.aliases,
+    languageIds: host.languageIds,
+    runtime: host.runtime,
+    host: host.host,
+    target: host.target,
+    capabilities: host.capabilities
+  };
+}
+
+function runtimeAdapterKind(capability, sourceHost, targetHost) {
+  if (capability === 'fetch' && sourceHost.runtime === 'web' && targetHost.runtime === 'cli') return 'browser-fetch-to-cli-http-client';
+  if (capability === 'fetch' && sourceHost.runtime === 'cli' && targetHost.runtime === 'web') return 'cli-http-client-to-browser-fetch';
+  if (capability === 'timers') return `${sourceHost.runtime}-timers-to-${targetHost.runtime}-timers`;
+  if (capability === 'storage' && targetHost.runtime === 'cli') return 'browser-storage-to-cli-persistence';
+  if (capability === 'storage' && targetHost.runtime === 'web') return 'cli-storage-to-browser-storage';
+  if (capability === 'filesystem' && targetHost.runtime === 'web') return 'filesystem-to-browser-storage';
+  if (capability === 'filesystem') return `${sourceHost.runtime}-filesystem-to-${targetHost.runtime}-filesystem`;
+  if (capability === 'threading' && targetHost.runtime === 'web') return 'native-threading-to-web-workers';
+  if (capability === 'threading') return `${sourceHost.runtime}-threading-to-${targetHost.runtime}-threading`;
+  if (capability === 'dom' && targetHost.runtime === 'cli') return 'dom-to-headless-host';
+  if (capability === 'dom') return `${sourceHost.runtime}-dom-to-${targetHost.runtime}-dom`;
+  if (capability === 'async') return `${sourceHost.runtime}-async-to-${targetHost.runtime}-async`;
+  if (capability === 'ffi' && targetHost.runtime === 'web') return 'native-ffi-to-web-boundary';
+  if (capability === 'ffi') return `${sourceHost.runtime}-ffi-to-${targetHost.runtime}-ffi`;
+  return `${sourceHost.runtime}-${capability}-to-${targetHost.runtime}-${capability}`;
+}
+
+function runtimeAdapterReason(capability, sourceHost, targetHost, sourceCapability, targetCapability) {
+  if (targetCapability.support === 'unavailable') {
+    return `${sourceHost.id} requires ${capability}, but ${targetHost.id} does not provide a compatible host capability.`;
+  }
+  if (sourceCapability.support === 'unavailable') {
+    return `${sourceHost.id} declared ${capability}, but the source host profile marks it unavailable.`;
+  }
+  return `${sourceHost.id} uses ${sourceCapability.binding} for ${capability}; ${targetHost.id} exposes ${targetCapability.binding}, so a host adapter must preserve the runtime effect boundary.`;
+}
+
+export function runtimeCapabilityMatrixSummary(routes) {
+  const byReadiness = {};
+  const byCapability = {};
+  const byAdapterKind = {};
+  let adapterRequirements = 0;
+  let routesWithAdapters = 0;
+  let missingCapabilities = 0;
+  for (const route of routes) {
+    byReadiness[route.readiness] = (byReadiness[route.readiness] ?? 0) + 1;
+    if (route.adapterRequirements.length) routesWithAdapters += 1;
+    adapterRequirements += route.adapterRequirements.length;
+    missingCapabilities += route.missingCapabilities.length;
+    for (const capability of route.requiredCapabilities) {
+      byCapability[capability] = (byCapability[capability] ?? 0) + 1;
+    }
+    for (const requirement of route.adapterRequirements) {
+      byAdapterKind[requirement.adapterKind] = (byAdapterKind[requirement.adapterKind] ?? 0) + 1;
+    }
+  }
+  return {
+    routes: routes.length,
+    routesWithAdapters,
+    adapterRequirements,
+    missingCapabilities,
+    byReadiness,
+    byCapability,
+    byAdapterKind
+  };
+}

package/examples/js-frontier-rust-workbench-client.mjs

@@ -100,7 +100,17 @@ async function convertFromTypescript() {
       sourceHash: payload.result.sourceHash,
       symbolCount: payload.result.summary.symbols,
       readiness: payload.result.summary.readiness,
-      projections: Object.keys(projections)
+      projections: Object.keys(projections),
+      semanticMergeReadiness: payload.result.routeExplanation?.semanticMerge?.readiness,
+      missingEvidence: payload.result.routeExplanation?.semanticMerge?.missingEvidence ?? [],
+      routeExplanation: (payload.result.routeExplanation?.routes ?? []).map((route) => ({
+        target: route.target,
+        mode: route.mode,
+        routeAction: route.routeAction,
+        readiness: route.readiness,
+        admissionAction: route.semanticMerge?.admissionAction,
+        missingEvidence: route.missingEvidence
+      }))
     });
   } catch (error) {
     state.result = errorResult(error);
@@ -155,15 +165,21 @@ function projectionSummaryText(projection) {
 function graphHtml(result) {
   const summary = result.summary || {};
   const frontier = result.frontier || {};
+  const routeExplanation = result.routeExplanation || {};
+  const semanticMerge = routeExplanation.semanticMerge || {};
   const symbols = frontier.symbols || [];
   const relations = frontier.relations || [];
+  const missingEvidence = semanticMerge.missingEvidence || [];
   return [
     '<div class="chipRow">',
     chip(summary.readiness, readinessClass(summary.readiness)),
+    chip('merge ' + (semanticMerge.readiness || 'unknown'), readinessClass(semanticMerge.readiness)),
+    chip(String(missingEvidence.length) + ' missing evidence', missingEvidence.length ? 'review' : 'ready'),
     chip(String(summary.losses || 0) + ' losses', 'review'),
     chip(String(summary.patchHints || 0) + ' patch hints', 'ready'),
     chip(projectionTargets(result), 'review'),
     '</div>',
+    routeExplanationHtml(routeExplanation),
     '<div class="sectionTitle">Symbols</div>',
     '<div class="graphGrid">',
     ...symbols.map((symbol) => nodeCard(symbol)),
@@ -182,6 +198,47 @@ function projectionTargets(result) {
   return (result.sourceLanguage || '-') + ' -> ' + (targets.length ? targets.join('/') : '-');
 }
 
+function routeExplanationHtml(explanation) {
+  const routes = explanation.routes || [];
+  if (!routes.length) return '';
+  const semanticMerge = explanation.semanticMerge || {};
+  return [
+    '<div class="sectionTitle">Route Explanation</div>',
+    '<section class="routeSummary">',
+    '<strong>' + escapeHtml('Semantic merge: ' + (semanticMerge.readiness || 'unknown')) + '</strong>',
+    '<span>' + escapeHtml((semanticMerge.admissionAction || 'prioritize') + ' / score ' + String(semanticMerge.score ?? 0)) + '</span>',
+    '</section>',
+    '<div class="routeGrid">',
+    ...routes.map((route) => routeCard(route)),
+    '</div>'
+  ].join('');
+}
+
+function routeCard(route) {
+  const semanticMerge = route.semanticMerge || {};
+  const missing = route.missingEvidenceDetails || [];
+  return '<article class="routeCard">' +
+    '<div class="routeCardHeader">' +
+    '<strong>' + escapeHtml((route.sourceLanguage || '-') + ' -> ' + (route.target || '-')) + '</strong>' +
+    chip(semanticMerge.readiness || route.readiness, readinessClass(semanticMerge.readiness || route.readiness)) +
+    '</div>' +
+    '<p>' + escapeHtml(route.explanation || '') + '</p>' +
+    '<dl class="routeFacts">' +
+    factHtml('Mode', route.mode) +
+    factHtml('Action', route.routeAction) +
+    factHtml('Adapter', route.adapter || 'none') +
+    factHtml('Admission', semanticMerge.admissionAction || 'prioritize') +
+    '</dl>' +
+    '<div class="missingEvidenceList">' +
+    missing.map((gap) => '<span title="' + escapeHtml(gap.summary) + '">' + escapeHtml(gap.label) + '</span>').join('') +
+    '</div>' +
+    '</article>';
+}
+
+function factHtml(label, value) {
+  return '<div><dt>' + escapeHtml(label) + '</dt><dd>' + escapeHtml(value || '-') + '</dd></div>';
+}
+
 function nodeCard(symbol) {
   return '<article class="nodeCard" data-graph-node="' + escapeHtml(symbol.id || symbol.name) + '">' +
     '<strong>' + escapeHtml(symbol.name) + '</strong>' +

package/examples/js-frontier-rust-workbench-convert.mjs

@@ -0,0 +1,161 @@
+import {
+  compileNativeSource,
+  createSemanticImportSidecar,
+  createUniversalConversionPlan,
+  importNativeSource,
+  queryUniversalConversionPlan,
+  writeUniversalAstJson
+} from '../dist/index.js';
+import {
+  createTsToPythonWorkbenchAdapter,
+  createTsToRustWorkbenchAdapter
+} from './js-frontier-rust-workbench-adapters.mjs';
+import { conversionBounds } from './js-frontier-rust-workbench-bounds.mjs';
+import {
+  explainRoute,
+  routeExplanationSummary
+} from './js-frontier-rust-workbench-route.mjs';
+
+export function convertSource(source, options = {}) {
+  const sourceLanguage = normalizeSourceLanguage(options.sourceLanguage);
+  const targets = ['rust', 'python'];
+  const imported = importNativeSource({
+    language: sourceLanguage,
+    sourcePath: `workbench/input.${sourceExtension(sourceLanguage)}`,
+    sourceText: source
+  });
+  const targetAdapters = [createTsToRustWorkbenchAdapter(), createTsToPythonWorkbenchAdapter()];
+  const projections = Object.fromEntries(targets.map((target) => {
+    const projection = compileNativeSource(imported, {
+      target,
+      targetPath: `workbench/output.${targetExtension(target)}`,
+      targetAdapters,
+      emitOnBlocked: true
+    });
+    return [target, projectionSummary(projection, { sourceLanguage, target })];
+  }));
+  const conversionPlan = createUniversalConversionPlan({
+    generatedAt: 0,
+    imports: [imported],
+    targetAdapters,
+    targets
+  });
+  const routes = targets.map((target) => explainRoute(
+    queryUniversalConversionPlan(conversionPlan, { sourceLanguage, target }).bestRoute,
+    { projection: projections[target], sourceLanguage, target }
+  ));
+  const sidecar = createSemanticImportSidecar(imported, { generatedAt: 0, targetPath: projections.rust?.targetPath });
+  return {
+    sourceHash: imported.nativeSource.sourceHash,
+    sourceLanguage,
+    summary: {
+      readiness: sidecar.summary.readiness,
+      symbols: imported.semanticIndex.symbols.length,
+      sourceMapMappings: imported.sourceMaps[0]?.mappings.length ?? 0,
+      losses: imported.losses.length,
+      patchHints: sidecar.patchHints.length
+    },
+    frontier: {
+      universalAst: universalAstSummary(imported),
+      semanticIndexId: imported.semanticIndex.id,
+      sidecarId: sidecar.id,
+      symbols: imported.semanticIndex.symbols.map(symbolSummary),
+      relations: relationSummaries(imported),
+      losses: imported.losses.map(lossSummary),
+      patchHints: sidecar.patchHints.map((hint) => ({
+        id: hint.id,
+        readiness: hint.readiness,
+        operations: hint.supportedOperations,
+        ownershipKey: hint.ownershipKey
+      }))
+    },
+    bounds: conversionBounds(sourceLanguage, targets.join('/')),
+    routeExplanation: routeExplanationSummary(conversionPlan, routes),
+    projection: projections.rust,
+    projections
+  };
+}
+
+function projectionSummary(projection, { sourceLanguage, target }) {
+  return {
+    target,
+    targetLanguage: target,
+    sourceLanguage,
+    targetPath: projection.sourceMap?.targetPath,
+    mode: projection.outputMode,
+    readiness: projection.readiness.readiness,
+    ok: projection.ok,
+    output: projection.output,
+    sourceMapMappings: projection.sourceMap?.mappings.length ?? 0,
+    targetAdapter: projection.metadata?.targetProjectionAdapterId,
+    evidence: (projection.evidence ?? []).map(evidenceSummary)
+  };
+}
+
+function evidenceSummary(record) {
+  return {
+    id: record.id,
+    kind: record.kind,
+    status: record.status,
+    summary: record.summary,
+    adapterId: record.metadata?.adapterId
+  };
+}
+
+function universalAstSummary(imported) {
+  const summary = { valid: true, validationError: undefined };
+  let parsed = imported.universalAst;
+  try {
+    parsed = JSON.parse(writeUniversalAstJson(imported.universalAst));
+  } catch (error) {
+    summary.valid = false;
+    summary.validationError = String(error.message || error);
+  }
+  return {
+    ...summary,
+    kind: parsed.kind,
+    id: parsed.id,
+    nativeSources: parsed.nativeSources?.length ?? 0,
+    semanticSymbols: parsed.semanticIndex?.symbols?.length ?? 0,
+    sourceMaps: parsed.sourceMaps?.length ?? 0,
+    layers: Object.keys(parsed.layers ?? {})
+  };
+}
+
+function symbolSummary(symbol) {
+  return {
+    id: symbol.id,
+    name: symbol.name,
+    kind: symbol.kind,
+    language: symbol.language,
+    region: symbol.metadata?.ownershipRegionKind,
+    ownershipKey: symbol.metadata?.ownershipRegionKey
+  };
+}
+
+function relationSummaries(imported) {
+  const names = new Map(imported.semanticIndex.symbols.map((symbol) => [symbol.id, symbol.name]));
+  return imported.semanticIndex.relations.map((relation) => ({
+    id: relation.id,
+    predicate: relation.predicate,
+    label: `${names.get(relation.sourceId) ?? relation.sourceId} ${relation.predicate} ${names.get(relation.targetId) ?? relation.targetId}`
+  }));
+}
+
+function lossSummary(loss) {
+  return { id: loss.id, kind: loss.kind, severity: loss.severity, message: loss.message };
+}
+
+function normalizeSourceLanguage(language) {
+  return 'typescript';
+}
+
+function targetExtension(target) {
+  if (target === 'rust') return 'rs';
+  if (target === 'python') return 'py';
+  return 'txt';
+}
+
+function sourceExtension(language) {
+  return 'ts';
+}

package/examples/js-frontier-rust-workbench-route-styles.mjs

@@ -0,0 +1,126 @@
+export function workbenchRouteStyles() {
+  return `
+.routeSummary {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 10px;
+  border: 1px solid var(--line);
+  border-radius: 8px;
+  background: #12171a;
+  padding: 10px;
+}
+.routeSummary strong {
+  min-width: 0;
+  overflow-wrap: anywhere;
+  font-size: 13px;
+}
+.routeSummary span {
+  flex: 0 0 auto;
+  color: var(--muted);
+  font-family: var(--mono);
+  font-size: 11px;
+}
+.routeGrid {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(220px, 1fr));
+  gap: 8px;
+  margin-top: 8px;
+}
+.routeCard {
+  border: 1px solid var(--line);
+  border-radius: 8px;
+  background: #14191d;
+  padding: 10px;
+}
+.routeCardHeader {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 8px;
+}
+.routeCardHeader strong {
+  min-width: 0;
+  overflow-wrap: anywhere;
+  font-size: 13px;
+}
+.routeCard p {
+  margin: 8px 0;
+  color: var(--muted);
+  font-size: 12px;
+  line-height: 1.45;
+  overflow-wrap: anywhere;
+}
+.routeFacts {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 6px;
+  margin: 0 0 8px;
+}
+.routeFacts div {
+  min-width: 0;
+}
+.routeFacts dt {
+  color: var(--faint);
+  font-size: 10px;
+  text-transform: uppercase;
+}
+.routeFacts dd {
+  margin: 2px 0 0;
+  color: var(--text);
+  font-family: var(--mono);
+  font-size: 11px;
+  overflow-wrap: anywhere;
+}
+.missingEvidenceList {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 5px;
+}
+.missingEvidenceList span {
+  border: 1px solid rgba(231, 183, 95, .45);
+  border-radius: 999px;
+  padding: 3px 6px;
+  color: var(--amber);
+  font-size: 10px;
+}
+.edgeList {
+  display: grid;
+  gap: 6px;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+.edgeList li {
+  border-left: 2px solid var(--blue);
+  background: rgba(109, 180, 232, .08);
+  padding: 6px 8px;
+  color: var(--muted);
+  font-size: 12px;
+  overflow-wrap: anywhere;
+}
+.boundsGrid {
+  display: grid;
+  grid-template-columns: repeat(3, minmax(0, 1fr));
+  gap: 8px;
+}
+.boundCard {
+  border: 1px solid var(--line);
+  border-radius: 8px;
+  background: #12171a;
+  padding: 10px;
+}
+.boundCard strong {
+  display: block;
+  margin-bottom: 8px;
+  font-size: 12px;
+}
+.boundCard ul {
+  margin: 0;
+  padding-left: 16px;
+  color: var(--muted);
+  font-size: 11px;
+  line-height: 1.45;
+}
+`;
+}