@shapeshift-labs/frontier-lang-compiler 0.2.18 → 0.2.19

package/README.md

@@ -166,6 +166,32 @@ console.log(changeSet.mergeCandidate.readiness); // merge-admission classificati
 
 Use `diffNativeSourceImports` when the worker or runner already produced `importNativeSource` results. Body-only edits that the lightweight scanner cannot anchor to a symbol are still reported as file-level changed regions instead of being silently treated as safe.
 
+Compile native source imports through the same reader/IR/writer facade that swarms use for sidecar evidence. Same-language targets preserve exact source when hashes match; cross-language targets emit declaration stubs until a real adapter provides stronger evidence:
+
+```js
+import { compileNativeSource } from '@shapeshift-labs/frontier-lang-compiler';
+
+const compiledJs = compileNativeSource({
+  language: 'javascript',
+  sourcePath: 'src/runtime.js',
+  sourceText: 'export function step(frame) { return frame + 1; }\n'
+});
+
+console.log(compiledJs.outputMode); // "preserved-source"
+console.log(compiledJs.readiness.readiness); // scanner imports can still be "needs-review"
+
+const rustCandidate = compileNativeSource(compiledJs.importResult, {
+  target: 'rust',
+  emitOnBlocked: true
+});
+
+console.log(rustCandidate.outputMode); // "target-stubs"
+console.log(rustCandidate.targetCoverage.lossClass); // "missingAdapter" without a JS-to-Rust adapter
+console.log(rustCandidate.ok); // true only because emitOnBlocked requested code anyway
+```
+
+`compileNativeSource` returns the import result, projection, target loss matrix cell, combined losses, readiness, evidence, and output hash. Admission queues should treat `ok` as "code was emitted", not as merge approval; `readiness` and `targetCoverage` carry the merge signal.
+
 Project a native import back to source. Exact source is preserved when the import carries matching source-preservation evidence or when supplied text matches the import hash; otherwise the compiler emits declaration stubs with review-required loss evidence:
 
 ```js

package/bench/smoke.mjs

@@ -1,5 +1,6 @@
 import { performance } from 'node:perf_hooks';
 import {
+  compileNativeSource,
   compileFrontierSource,
   createEstreeNativeImporterAdapter,
   createNativeImportCoverageMatrix,
@@ -92,6 +93,15 @@ const nativeProjections = nativeImportResults.map((imported) => projectNativeImp
 const projectionDurationMs = performance.now() - projectionStart;
 const projectionBytes = nativeProjections.reduce((sum, projection) => sum + projection.sourceText.length, 0);
 
+const nativeCompileStart = performance.now();
+const nativeCompiles = nativeImportResults.map((imported, index) => compileNativeSource(imported, {
+  target: index % 2 === 0 ? 'javascript' : 'rust',
+  emitOnBlocked: true
+}));
+const nativeCompileDurationMs = performance.now() - nativeCompileStart;
+const nativeCompileBytes = nativeCompiles.reduce((sum, result) => sum + result.output.length, 0);
+const nativeCompileBlocked = nativeCompiles.filter((result) => result.readiness.readiness === 'blocked').length;
+
 console.log(JSON.stringify({
   compiles: 250,
   bytes,
@@ -118,5 +128,9 @@ console.log(JSON.stringify({
   sidecarDurationMs: Number(sidecarDurationMs.toFixed(2)),
   nativeProjections: nativeProjections.length,
   projectionBytes,
-  projectionDurationMs: Number(projectionDurationMs.toFixed(2))
+  projectionDurationMs: Number(projectionDurationMs.toFixed(2)),
+  nativeCompiles: nativeCompiles.length,
+  nativeCompileBytes,
+  nativeCompileBlocked,
+  nativeCompileDurationMs: Number(nativeCompileDurationMs.toFixed(2))
 }));

package/dist/index.d.ts

@@ -1221,6 +1221,43 @@ export interface NativeSourceProjectionResult {
   readonly metadata: Record<string, unknown>;
 }
 
+export type NativeSourceCompileOutputMode = NativeSourceProjectionMode | 'target-stubs';
+
+export interface CompileNativeSourceOptions extends ProjectNativeImportToSourceOptions {
+  readonly target?: FrontierCompileTarget | string;
+  readonly adapters?: readonly NativeImporterAdapter[];
+  readonly languages?: readonly NativeImportLanguageProfile[];
+  readonly generatedAt?: number;
+  readonly emitOnBlocked?: boolean;
+  readonly projectionId?: string;
+  readonly projectionEvidenceId?: string;
+  readonly compileEvidenceId?: string;
+  readonly evidence?: readonly EvidenceRecord[];
+  readonly losses?: readonly NativeAstLossRecord[];
+}
+
+export interface NativeSourceCompileResult {
+  readonly kind: 'frontier.lang.nativeSourceCompileResult';
+  readonly version: 1;
+  readonly id: string;
+  readonly ok: boolean;
+  readonly target: FrontierCompileTarget | string;
+  readonly language: FrontierSourceLanguage | string;
+  readonly sourcePath?: string;
+  readonly output: string;
+  readonly outputHash: string;
+  readonly outputMode: NativeSourceCompileOutputMode;
+  readonly importResult: NativeSourceImportResult;
+  readonly projection: NativeSourceProjectionResult;
+  readonly targetCoverage: ProjectionTargetCoverageEntry;
+  readonly projectionMatrix: ProjectionTargetLossMatrix;
+  readonly losses: readonly NativeAstLossRecord[];
+  readonly lossSummary: NativeImportLossSummary;
+  readonly readiness: NativeImportReadinessClassification;
+  readonly evidence: readonly EvidenceRecord[];
+  readonly metadata: Record<string, unknown>;
+}
+
 export type NativeImportRoundtripReadinessStatus =
   | 'exact'
   | 'preserved-source'
@@ -1286,6 +1323,7 @@ export declare const NativeImportLanguageProfiles: readonly NativeImportLanguage
 export declare function normalizeCompileTarget(target?: string): FrontierCompileTarget;
 export declare function compileFrontierSource(source: string, options?: FrontierCompileOptions): FrontierCompileResult;
 export declare function compileFrontierDocument(document: FrontierLangDocument, options?: FrontierCompileOptions): FrontierCompileResult;
+export declare function compileNativeSource(input: ImportNativeSourceOptions | NativeSourceImportResult, options?: CompileNativeSourceOptions): NativeSourceCompileResult;
 export declare function projectFrontierAst(document: FrontierLangDocument, target?: FrontierCompileOptions['target'], options?: FrontierCompileEmitOptions): FrontierTargetAst;
 export declare function renderTargetAst(ast: FrontierTargetAst, target?: FrontierCompileOptions['target']): string;
 export declare function renderTargetAstWithSourceMap(ast: FrontierTargetAst, target?: FrontierCompileOptions['target'], options?: FrontierCompileEmitOptions): FrontierTargetSourceMapResult;

package/dist/index.js

@@ -253,6 +253,116 @@ export function compileFrontierDocument(document, options = {}) {
   };
 }
 
+export function compileNativeSource(input, options = {}) {
+  const importResult = isNativeSourceImportResult(input) ? input : importNativeSource(input);
+  const sourceLanguage = nativeCompileSourceLanguage(importResult, input);
+  const target = nativeCompileTarget(input, importResult, options);
+  const sourceTarget = nativeLanguageCompileTarget(sourceLanguage);
+  const sameSourceTarget = sourceTarget === target;
+  const idPart = idFragment(options.id ?? importResult.id ?? importResult.sourcePath ?? sourceLanguage ?? target);
+  const id = options.id ?? `native_source_compile_${idPart}_${idFragment(target)}`;
+  const projection = projectNativeImportToSource(importResult, {
+    ...options,
+    id: options.projectionId ?? `${id}_projection`,
+    language: sameSourceTarget ? sourceLanguage : target,
+    preferPreservedSource: sameSourceTarget ? options.preferPreservedSource : false,
+    evidenceId: options.projectionEvidenceId ?? options.evidenceId,
+    metadata: {
+      sourceLanguage,
+      target,
+      nativeCompileResultId: id,
+      ...options.metadata
+    }
+  });
+  const projectionMatrix = createProjectionTargetLossMatrix({
+    imports: [importResult],
+    adapters: options.adapters,
+    languages: options.languages,
+    targets: [target],
+    generatedAt: options.generatedAt
+  });
+  const targetCoverage = nativeSourceCompileTargetCoverage(projectionMatrix, sourceLanguage, target);
+  const targetLosses = nativeSourceCompileTargetLosses({
+    importResult,
+    projection,
+    targetCoverage,
+    sourceLanguage,
+    target,
+    idPart
+  });
+  const outputMode = sameSourceTarget ? projection.mode : 'target-stubs';
+  const compileEvidence = nativeSourceCompileEvidence({
+    id: options.compileEvidenceId ?? `evidence_${idPart}_${idFragment(target)}_native_source_compile`,
+    importResult,
+    projection,
+    targetCoverage,
+    targetLosses,
+    sourceLanguage,
+    target,
+    outputMode
+  });
+  const evidence = uniqueByEvidenceId([
+    ...(importResult.evidence ?? []),
+    ...(projection.evidence ?? []),
+    compileEvidence,
+    ...(options.evidence ?? [])
+  ]);
+  const losses = uniqueByLossId([
+    ...(importResult.losses ?? []),
+    ...(projection.losses ?? []),
+    ...targetLosses,
+    ...(options.losses ?? [])
+  ]);
+  const lossSummary = summarizeNativeImportLosses(losses, {
+    evidence,
+    parser: importResult.nativeAst?.parser ?? importResult.nativeSource?.parser ?? options.parser,
+    scanKind: 'native-source-compile',
+    semanticStatus: importResult.metadata?.semanticStatus ?? options.semanticStatus
+  });
+  const readiness = classifyNativeImportReadiness(losses, {
+    evidence,
+    parser: importResult.nativeAst?.parser ?? importResult.nativeSource?.parser ?? options.parser,
+    scanKind: 'native-source-compile',
+    semanticStatus: importResult.metadata?.semanticStatus ?? options.semanticStatus
+  });
+  return {
+    kind: 'frontier.lang.nativeSourceCompileResult',
+    version: 1,
+    id,
+    ok: readiness.readiness !== 'blocked' || options.emitOnBlocked === true,
+    target,
+    language: sourceLanguage,
+    sourcePath: importResult.sourcePath ?? importResult.nativeSource?.sourcePath,
+    output: projection.sourceText,
+    outputHash: projection.outputHash,
+    outputMode,
+    importResult,
+    projection,
+    targetCoverage,
+    projectionMatrix,
+    losses,
+    lossSummary,
+    readiness,
+    evidence,
+    metadata: {
+      nativeImportId: importResult.id,
+      nativeSourceId: importResult.nativeSource?.id,
+      nativeAstId: importResult.nativeAst?.id ?? importResult.nativeSource?.ast?.id,
+      semanticIndexId: importResult.semanticIndex?.id ?? importResult.universalAst?.semanticIndex?.id,
+      universalAstId: importResult.universalAst?.id,
+      projectionId: projection.id,
+      projectionMode: projection.mode,
+      outputMode,
+      sourceTarget,
+      sameSourceTarget,
+      targetLossClass: targetCoverage.lossClass,
+      targetReadiness: targetCoverage.readiness,
+      targetSupported: targetCoverage.supported,
+      ...options.metadata
+    }
+  };
+}
+
 export function projectFrontierAst(document, target = 'typescript', options = {}) {
   const normalized = normalizeCompileTarget(target);
   const projector = projectors[normalized];
@@ -4075,6 +4185,159 @@ function nativeLanguageCompileTarget(language, aliases = []) {
   return undefined;
 }
 
+function isNativeSourceImportResult(input) {
+  return Boolean(input && typeof input === 'object' && input.kind === 'frontier.lang.importResult' && input.nativeSource && input.universalAst);
+}
+
+function nativeCompileSourceLanguage(importResult, input) {
+  return normalizeNativeLanguageId(
+    importResult.language
+      ?? importResult.nativeSource?.language
+      ?? importResult.nativeAst?.language
+      ?? importResult.nativeSource?.ast?.language
+      ?? input?.language
+  ) || String(importResult.language ?? input?.language ?? 'source');
+}
+
+function nativeCompileTarget(input, importResult, options) {
+  const targetInput = options.target
+    ?? compileTargetLanguage(input?.target)
+    ?? compileTargetLanguage(importResult.nativeSource?.target)
+    ?? nativeLanguageCompileTarget(nativeCompileSourceLanguage(importResult, input))
+    ?? 'typescript';
+  return normalizeProjectionMatrixTargets([targetInput])[0] ?? String(targetInput ?? 'typescript').toLowerCase();
+}
+
+function compileTargetLanguage(target) {
+  if (!target) return undefined;
+  if (typeof target === 'string') return target;
+  return target.language ?? target.emitLanguage ?? target.target ?? target.name;
+}
+
+function nativeSourceCompileTargetCoverage(matrix, language, target) {
+  const sourceLanguage = normalizeNativeLanguageId(language);
+  const entry = (matrix.languages ?? []).find((candidate) => {
+    const ids = [candidate.language, ...(candidate.aliases ?? [])].map(normalizeNativeLanguageId);
+    return ids.includes(sourceLanguage);
+  });
+  const coverage = entry?.targets?.find((candidate) => candidate.target === target);
+  if (coverage) return coverage;
+  return {
+    target,
+    lossClass: 'missingAdapter',
+    supported: false,
+    readiness: 'blocked',
+    lossKinds: ['targetProjectionLoss'],
+    categories: ['targetProjectionLoss'],
+    reason: `No native-to-${target} projection coverage is available for ${language}.`,
+    adapter: undefined,
+    notes: ['Inject a source-language parser and target projection adapter before treating this cross-language output as merge-ready.']
+  };
+}
+
+function nativeSourceCompileTargetLosses(input) {
+  const { importResult, projection, targetCoverage, sourceLanguage, target, idPart } = input;
+  if (!targetCoverage || targetCoverage.lossClass === 'exactSourceProjection') return [];
+  if (targetCoverage.lossClass === 'missingAdapter') {
+    return [nativeSourceCompileTargetLoss({
+      id: `loss_${idPart}_${idFragment(target)}_missing_projection_adapter`,
+      severity: 'error',
+      message: targetCoverage.reason,
+      importResult,
+      projection,
+      targetCoverage,
+      sourceLanguage,
+      target
+    })];
+  }
+  if (targetCoverage.lossClass === 'unsupportedTargetFeatures') {
+    return [nativeSourceCompileTargetLoss({
+      id: `loss_${idPart}_${idFragment(target)}_unsupported_target_features`,
+      severity: 'warning',
+      message: targetCoverage.reason,
+      importResult,
+      projection,
+      targetCoverage,
+      sourceLanguage,
+      target
+    })];
+  }
+  if (targetCoverage.lossClass === 'nativeSourceStubs') {
+    return [nativeSourceCompileTargetLoss({
+      id: `loss_${idPart}_${idFragment(target)}_target_stubs`,
+      severity: 'warning',
+      message: targetCoverage.reason,
+      importResult,
+      projection,
+      targetCoverage,
+      sourceLanguage,
+      target
+    })];
+  }
+  return [];
+}
+
+function nativeSourceCompileTargetLoss(input) {
+  const rootSpan = input.importResult.nativeAst?.nodes?.[input.importResult.nativeAst?.rootId]?.span
+    ?? input.importResult.nativeSource?.ast?.nodes?.[input.importResult.nativeSource?.ast?.rootId]?.span;
+  return {
+    id: input.id,
+    severity: input.severity,
+    phase: 'emit',
+    sourceFormat: input.sourceLanguage,
+    kind: 'targetProjectionLoss',
+    message: input.message,
+    span: rootSpan ?? {
+      sourceId: input.importResult.nativeSource?.sourceHash ?? input.importResult.sourceHash,
+      path: input.importResult.sourcePath ?? input.importResult.nativeSource?.sourcePath,
+      startLine: 1,
+      startColumn: 1
+    },
+    metadata: {
+      target: input.target,
+      sourceLanguage: input.sourceLanguage,
+      projectionId: input.projection.id,
+      projectionMode: input.projection.mode,
+      targetLossClass: input.targetCoverage.lossClass,
+      targetReadiness: input.targetCoverage.readiness,
+      targetSupported: input.targetCoverage.supported,
+      targetAdapter: input.targetCoverage.adapter,
+      targetLossKinds: input.targetCoverage.lossKinds,
+      lossCategory: 'targetProjectionLoss',
+      semanticMergeAdmission: semanticMergeAdmissionForSeverity(input.severity)
+    }
+  };
+}
+
+function nativeSourceCompileEvidence(input) {
+  const failed = input.targetLosses.some((loss) => loss.severity === 'error')
+    || input.projection.evidence?.some((record) => record.status === 'failed')
+    || input.targetCoverage.readiness === 'blocked';
+  return {
+    id: input.id,
+    kind: 'projection',
+    status: failed ? 'failed' : 'passed',
+    path: input.importResult.sourcePath ?? input.importResult.nativeSource?.sourcePath,
+    summary: failed
+      ? `Compiled ${input.sourceLanguage} native source to ${input.target} with blocked projection evidence.`
+      : `Compiled ${input.sourceLanguage} native source to ${input.target} as ${input.outputMode}.`,
+    metadata: {
+      importId: input.importResult.id,
+      projectionId: input.projection.id,
+      sourceLanguage: input.sourceLanguage,
+      target: input.target,
+      outputHash: input.projection.outputHash,
+      outputMode: input.outputMode,
+      projectionMode: input.projection.mode,
+      targetLossClass: input.targetCoverage.lossClass,
+      targetReadiness: input.targetCoverage.readiness,
+      targetSupported: input.targetCoverage.supported,
+      targetReason: input.targetCoverage.reason,
+      targetLossIds: input.targetLosses.map((loss) => loss.id)
+    }
+  };
+}
+
 function nativeProjectionTargetsForLanguage(language, aliases = []) {
   const target = nativeLanguageCompileTarget(language, aliases);
   return target ? [target] : [];

package/package.json

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