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

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

@@ -0,0 +1,190 @@
+export function routeExplanationSummary(plan, routes) {
+  const missingEvidence = uniqueStrings(routes.flatMap((route) => route.missingEvidence));
+  const blockers = uniqueStrings(routes.flatMap((route) => route.blockers));
+  const review = uniqueStrings(routes.flatMap((route) => route.review));
+  const readiness = aggregateReadiness(routes.map((route) => route.semanticMerge.readiness));
+  const routeScores = routes.map((route) => route.semanticMerge.score).filter((score) => Number.isFinite(score));
+  return {
+    kind: 'frontier.workbench.routeExplanation',
+    version: 1,
+    planId: plan.id,
+    summary: {
+      routes: routes.length,
+      targetAdapterRoutes: plan.summary.targetAdapterRoutes,
+      missingEvidence: missingEvidence.length,
+      blockers: blockers.length,
+      reviewReasons: review.length,
+      autoMergeClaims: plan.summary.autoMergeClaims,
+      semanticEquivalenceClaims: plan.summary.semanticEquivalenceClaims
+    },
+    semanticMerge: {
+      readiness,
+      ready: readiness === 'ready' && missingEvidence.length === 0 && blockers.length === 0,
+      admissionAction: aggregateAdmissionAction(routes.map((route) => route.semanticMerge.admissionAction)),
+      score: routeScores.length ? Math.min(...routeScores) : 0,
+      risk: aggregateRisk(routes.map((route) => route.semanticMerge.risk)),
+      missingEvidence,
+      missingEvidenceDetails: missingEvidence.map(evidenceGapDetail),
+      blockers,
+      review,
+      autoMergeClaim: false,
+      semanticEquivalenceClaim: false
+    },
+    routes
+  };
+}
+
+export function explainRoute(route, context) {
+  const missingEvidence = routeMissingEvidence(route, context.projection);
+  const semanticReadiness = routeSemanticMergeReadiness(route, missingEvidence);
+  const semanticAdmissionAction = routeSemanticAdmissionAction(route, semanticReadiness, missingEvidence);
+  return {
+    id: route?.id ?? `conversion_${context.sourceLanguage}_to_${context.target}`,
+    sourceLanguage: route?.sourceLanguage ?? context.sourceLanguage,
+    target: route?.target ?? context.target,
+    mode: route?.mode ?? 'blocked',
+    routeAction: route?.routeAction ?? 'blocked',
+    readiness: route?.readiness ?? 'blocked',
+    priority: route?.priority ?? 'blocker',
+    adapter: route?.adapter,
+    adapterKind: route?.adapterKind,
+    targetPath: context.projection?.targetPath,
+    missingEvidence,
+    missingEvidenceDetails: missingEvidence.map(evidenceGapDetail),
+    blockers: route?.blockers ?? ['No conversion route was planned.'],
+    review: route?.review ?? [],
+    evidence: {
+      imports: route?.evidence?.imports ?? 0,
+      importReadiness: route?.evidence?.importReadiness,
+      symbols: route?.evidence?.symbols ?? 0,
+      sourceMapMappings: route?.evidence?.sourceMapMappings ?? 0,
+      parserRows: route?.evidence?.parserRows ?? 0,
+      mergeReadyParsers: route?.evidence?.mergeReadyParsers ?? 0,
+      targetSupported: route?.evidence?.targetSupported === true,
+      targetAdapter: route?.evidence?.targetAdapter ?? route?.adapter,
+      projectionEvidenceIds: (context.projection?.evidence ?? []).map((record) => record.id).filter(Boolean)
+    },
+    semanticMerge: {
+      readiness: semanticReadiness,
+      score: route?.mergeScore?.value ?? 0,
+      risk: routeSemanticRisk(route, semanticReadiness),
+      admissionAction: semanticAdmissionAction,
+      penalties: uniqueStrings([
+        ...(route?.mergeScore?.penalties ?? []),
+        ...missingEvidence.map((key) => `Missing evidence: ${key}`)
+      ]).slice(0, 6),
+      autoMergeClaim: route?.autoMergeClaim === true,
+      semanticEquivalenceClaim: route?.semanticEquivalenceClaim === true
+    },
+    explanation: routeExplanationText(route, missingEvidence, semanticReadiness)
+  };
+}
+
+function routeMissingEvidence(route, projection) {
+  const missing = new Set(route?.missingEvidence ?? []);
+  if ((route?.evidence?.mergeReadyParsers ?? 0) === 0) missing.add('merge-ready-parser');
+  if (!hasProofEvidence(projection?.evidence ?? [])) missing.add('proof-or-replay-evidence');
+  if (!hasRuntimeAdapterEvidence(projection?.evidence ?? [])) missing.add('runtime-adapter-evidence');
+  return [...missing].sort();
+}
+
+function routeExplanationText(route, missingEvidence, semanticReadiness) {
+  if (!route) return 'No conversion route was planned for this target.';
+  const adapter = route.adapter ? ` through ${route.adapter}` : '';
+  const evidence = missingEvidence.length ? ` missing ${missingEvidence.join(', ')}` : ' with required evidence attached';
+  return `${route.sourceLanguage} -> ${route.target} uses ${route.mode}${adapter}; semantic merge readiness is ${semanticReadiness}${evidence}.`;
+}
+
+function evidenceGapDetail(key) {
+  const details = {
+    'merge-ready-parser': {
+      key,
+      label: 'Merge-ready parser evidence',
+      status: 'missing',
+      summary: 'Attach exact parser, source range, token/trivia, and feature coverage evidence before merge admission.'
+    },
+    'proof-or-replay-evidence': {
+      key,
+      label: 'Proof or replay evidence',
+      status: 'missing',
+      summary: 'Attach proof, oracle, replay, or behavior test evidence for the projected route.'
+    },
+    'runtime-adapter-evidence': {
+      key,
+      label: 'Runtime adapter evidence',
+      status: 'missing',
+      summary: 'Attach runtime adapter evidence for imports, effects, host APIs, package modules, and target runtime shims.'
+    },
+    'source-preservation-hash': {
+      key,
+      label: 'Source preservation hash',
+      status: 'missing',
+      summary: 'Attach exact source preservation evidence so source text can be traced to merge candidates.'
+    },
+    'target-adapter': {
+      key,
+      label: 'Target adapter',
+      status: 'missing',
+      summary: 'Add a source-to-target projection adapter for emitted target code.'
+    },
+    'target-adapter-evidence': {
+      key,
+      label: 'Target adapter evidence',
+      status: 'missing',
+      summary: 'Attach run evidence from the host-owned target projection adapter.'
+    }
+  };
+  return details[key] ?? { key, label: key, status: 'missing', summary: 'Attach route evidence before merge admission.' };
+}
+
+function hasProofEvidence(evidence) {
+  return evidence.some((record) => /proof|oracle|replay|behavior|test|verification/.test(String(record.kind ?? record.metadata?.kind ?? record.type ?? '')));
+}
+
+function hasRuntimeAdapterEvidence(evidence) {
+  return evidence.some((record) => {
+    const capabilities = record.metadata?.capabilities ?? [];
+    return record.metadata?.runtimeAdapterEvidence === true
+      || capabilities.includes('runtime-adapter')
+      || /runtime/.test(String(record.kind ?? record.metadata?.kind ?? record.type ?? ''));
+  });
+}
+
+function uniqueStrings(values) {
+  return [...new Set(values.filter((value) => typeof value === 'string' && value.length > 0))];
+}
+
+function aggregateReadiness(values) {
+  const rank = { ready: 0, 'ready-with-losses': 1, 'needs-review': 2, blocked: 3 };
+  return values.reduce((current, value) => (rank[value] ?? 3) > (rank[current] ?? 3) ? value : current, 'ready');
+}
+
+function routeSemanticMergeReadiness(route, missingEvidence) {
+  const base = route?.mergeScore?.readiness ?? route?.readiness ?? 'blocked';
+  if (!missingEvidence.length || base === 'blocked') return base;
+  return aggregateReadiness([base, 'needs-review']);
+}
+
+function routeSemanticAdmissionAction(route, readiness, missingEvidence) {
+  if ((route?.mergeScore?.action ?? route?.admissionAction) === 'reject' || readiness === 'blocked') return 'reject';
+  if (readiness === 'ready' && missingEvidence.length === 0) return route?.mergeScore?.action ?? 'admit';
+  return 'prioritize';
+}
+
+function routeSemanticRisk(route, readiness) {
+  if (readiness === 'blocked') return 'high';
+  if (readiness === 'needs-review') return 'medium';
+  return route?.mergeScore?.risk ?? 'low';
+}
+
+function aggregateAdmissionAction(values) {
+  if (values.includes('reject')) return 'reject';
+  if (values.includes('prioritize')) return 'prioritize';
+  return values[0] ?? 'prioritize';
+}
+
+function aggregateRisk(values) {
+  if (values.includes('high')) return 'high';
+  if (values.includes('medium')) return 'medium';
+  return values[0] ?? 'low';
+}

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

@@ -1,3 +1,5 @@
+import { workbenchRouteStyles } from './js-frontier-rust-workbench-route-styles.mjs';
+
 export function workbenchStyles() {
   return `
 :root {
@@ -223,44 +225,7 @@ textarea[readonly] {
   font-size: 11px;
   text-transform: uppercase;
 }
-.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;
-}
+${workbenchRouteStyles()}
 .segmented { display: flex; gap: 0; }
 .segmented button {
   width: 58px;

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

@@ -1,11 +1,6 @@
 #!/usr/bin/env node
 import http from 'node:http';
-import { compileNativeSource, createSemanticImportSidecar, importNativeSource, 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 { convertSource } from './js-frontier-rust-workbench-convert.mjs';
 import { renderWorkbenchHtml } from './js-frontier-rust-workbench-html.mjs';
 import { workbenchClientScript } from './js-frontier-rust-workbench-client.mjs';
 import { workbenchStyles } from './js-frontier-rust-workbench-styles.mjs';
@@ -35,6 +30,11 @@ if (args.smoke) {
   assert(result.frontier.universalAst.valid, 'expected valid universal AST summary');
   assert(result.projections.rust.output.includes('pub'), 'expected Rust projection');
   assert(result.projections.python.output.includes('def add_todo'), 'expected Python projection');
+  assert(result.routeExplanation.routes.length === 2, 'expected route explanation for both targets');
+  assert(result.routeExplanation.semanticMerge.readiness === 'blocked', 'expected blocked semantic merge readiness');
+  assert(result.routeExplanation.semanticMerge.missingEvidence.includes('proof-or-replay-evidence'), 'expected missing proof evidence');
+  assert(result.routeExplanation.semanticMerge.missingEvidence.includes('merge-ready-parser'), 'expected missing parser evidence');
+  assert(result.routeExplanation.semanticMerge.missingEvidence.includes('runtime-adapter-evidence'), 'expected missing runtime adapter evidence');
   const html = renderWorkbenchHtml({
     sourceLanguage: 'typescript',
     sources: { typescript: sampleSource },
@@ -48,8 +48,11 @@ if (args.smoke) {
   assert(html.includes('id="rustOutput"'), 'expected Rust output pane');
   assert(html.includes('id="pythonOutput"'), 'expected Python output pane');
   assert(client.includes("addEventListener('submit'"), 'expected submit-based conversion listener');
+  assert(client.includes('Route Explanation'), 'expected route explanation rendering');
   assert(styles.includes('grid-template-columns: minmax(260px, 0.9fr) minmax(320px, 1.1fr) minmax(280px, 1fr) minmax(280px, 1fr);'), 'expected four-pane desktop scaffold');
   assert(styles.includes('overflow: auto'), 'expected scrollable pane bodies');
+  assert(styles.includes('.workspace {'), 'expected fixed workspace section');
+  assert(styles.includes('.routeCard'), 'expected route explanation styles');
   console.log(JSON.stringify({
     ok: true,
     summary: result.summary,
@@ -57,10 +60,22 @@ if (args.smoke) {
       rust: { ok: result.projections.rust.ok, readiness: result.projections.rust.readiness },
       python: { ok: result.projections.python.ok, readiness: result.projections.python.readiness }
     },
+    routeExplanation: {
+      semanticMerge: result.routeExplanation.semanticMerge,
+      routes: result.routeExplanation.routes.map((route) => ({
+        target: route.target,
+        mode: route.mode,
+        routeAction: route.routeAction,
+        readiness: route.readiness,
+        admissionAction: route.semanticMerge.admissionAction,
+        missingEvidence: route.missingEvidence
+      }))
+    },
     layout: {
       submitBased: true,
       panes: ['typescript', 'frontier', 'rust', 'python'],
-      independentScrollRegions: 4
+      independentScrollRegions: 4,
+      fixedSections: ['topbar', 'statusStrip', 'workspace']
     }
   }, null, 2));
 } else {
@@ -100,127 +115,6 @@ async function routeRequest(request, response) {
   }
 }
 
-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 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('/')),
-    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
-  };
-}
-
-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';
-}
-
 function sendJson(response, status, value) {
   return send(response, status, JSON.stringify(value), 'application/json; charset=utf-8');
 }

package/package.json

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