@shapeshift-labs/frontier-lang-compiler 0.2.38 → 0.2.39

package/README.md

@@ -118,6 +118,7 @@ import {
   createNativeImportCoverageMatrix,
   createNativeParserAstFormatMatrix,
   createProjectionTargetLossMatrix,
+  createUniversalCapabilityMatrix,
   importNativeSource
 } from '@shapeshift-labs/frontier-lang-compiler';
 
@@ -142,6 +143,15 @@ const pythonProjection = projectionMatrix.languages.find((entry) => entry.langua
 console.log(pythonProjection.sourceProjection.exactSource.lossClass); // "exactSourceProjection"
 console.log(pythonProjection.sourceProjection.stubs.lossClass); // "nativeSourceStubs"
 console.log(pythonProjection.targets.find((entry) => entry.target === 'rust').lossClass); // "missingAdapter"
+
+const universalMatrix = createUniversalCapabilityMatrix({
+  imports: [imported],
+  requiredFeatures: ['syntax', 'semantic', 'sourcePreservation']
+});
+const pythonUniversal = universalMatrix.languages.find((entry) => entry.language === 'python');
+
+console.log(pythonUniversal.readiness); // combined import/parser/projection readiness
+console.log(pythonUniversal.blockers); // missing evidence/adapters that prevent merge admission
 ```
 
 The projection target matrix separates five runtime/API classes:
@@ -152,6 +162,8 @@ The projection target matrix separates five runtime/API classes:
 - `targetAdapterProjection`: a host-owned native-to-target adapter is present and produced target output with its own evidence/readiness.
 - `missingAdapter`: no native-to-target projection adapter is declared; preserve or stub the original source language instead, or inject host-owned parser/semantic adapter evidence.
 
+`createUniversalCapabilityMatrix` composes the import coverage, parser AST format, parser feature, and projection target matrices into a single language row per source language. It is the coordinator-facing view for universal-language work: it shows imports, symbols, source-map mappings, parser feature readiness, projection targets, missing adapters, unsupported target features, blockers, and review reasons without claiming lossless conversion where evidence is absent.
+
 Preserve exact native source text, token/trivia hashes, comments, whitespace, and source directives as evidence. This does not claim full semantic understanding; it keeps round-trip material available while exact parser adapters catch up:
 
 ```js

package/bench/smoke.mjs

@@ -12,6 +12,7 @@ import {
   createNativeParserAstFormatMatrix,
   createNativeParserFeatureMatrix,
   createProjectionTargetLossMatrix,
+  createUniversalCapabilityMatrix,
   createNativeSourcePreservation,
   createPythonAstNativeImporterAdapter,
   createRustSynNativeImporterAdapter,
@@ -140,6 +141,14 @@ const projectionMatrixStart = performance.now();
 const projectionLossMatrix = createProjectionTargetLossMatrix({ imports: nativeImportResults });
 const projectionMatrixDurationMs = performance.now() - projectionMatrixStart;
 
+const universalMatrixStart = performance.now();
+const universalCapabilityMatrix = createUniversalCapabilityMatrix({
+  imports: nativeImportResults,
+  adapters: [estreeAdapter, createPythonAstNativeImporterAdapter(), createRustSynNativeImporterAdapter(), createClangAstNativeImporterAdapter(), createGoAstNativeImporterAdapter(), createJavaAstNativeImporterAdapter(), kotlinPsiAdapter, createCSharpRoslynNativeImporterAdapter(), createSwiftSyntaxNativeImporterAdapter()],
+  requiredFeatures: ['syntax', 'semantic', 'sourcePreservation']
+});
+const universalMatrixDurationMs = performance.now() - universalMatrixStart;
+
 const preservationStart = performance.now();
 const preservationRecords = nativeImportResults.map((imported) => imported.metadata.sourcePreservation ?? createNativeSourcePreservation({
   language: imported.language,
@@ -304,6 +313,11 @@ console.log(JSON.stringify({
   projectionMatrixMissingAdapters: projectionLossMatrix.summary.missingAdapters,
   projectionMatrixUnsupportedTargetFeatures: projectionLossMatrix.summary.unsupportedTargetFeatures,
   projectionMatrixDurationMs: Number(projectionMatrixDurationMs.toFixed(2)),
+  universalMatrixLanguages: universalCapabilityMatrix.summary.languages,
+  universalMatrixImports: universalCapabilityMatrix.summary.imports,
+  universalMatrixBlockedLanguages: universalCapabilityMatrix.summary.blockedLanguages,
+  universalMatrixMissingAdapters: universalCapabilityMatrix.summary.missingAdapters,
+  universalMatrixDurationMs: Number(universalMatrixDurationMs.toFixed(2)),
   sourcePreservationRecords: preservationRecords.length,
   sourcePreservationTokens: preservationTokens,
   sourcePreservationDurationMs: Number(preservationDurationMs.toFixed(2)),

package/dist/index.d.ts

@@ -652,6 +652,101 @@ export interface ProjectionTargetLossMatrixOptions {
   readonly generatedAt?: number;
 }
 
+export interface UniversalCapabilityLanguageRow {
+  readonly language: FrontierSourceLanguage | string;
+  readonly aliases: readonly string[];
+  readonly extensions: readonly string[];
+  readonly readiness: SemanticMergeReadiness;
+  readonly imports: {
+    readonly total: number;
+    readonly readiness: SemanticMergeReadiness;
+    readonly symbols: number;
+    readonly sourceMaps: number;
+    readonly sourceMapMappings: number;
+    readonly losses: number;
+    readonly lossKinds: Readonly<Record<string, number>>;
+    readonly readinessReasons: readonly string[];
+  };
+  readonly parser: {
+    readonly readiness: SemanticMergeReadiness;
+    readonly rows: number;
+    readonly parsers: readonly string[];
+    readonly mergeReadyParsers: readonly string[];
+    readonly blockingFeatures: readonly NativeParserFeatureCategory[];
+    readonly reviewFeatures: readonly NativeParserFeatureCategory[];
+    readonly languageSummary?: NativeParserFeatureLanguageSummary;
+  };
+  readonly projection: {
+    readonly readiness: SemanticMergeReadiness;
+    readonly sourceProjection?: ProjectionTargetLanguageCoverage['sourceProjection'];
+    readonly targets: readonly ProjectionTargetCoverageEntry[];
+    readonly summary: ProjectionTargetLanguageCoverage['summary'];
+    readonly missingTargets: readonly (FrontierCompileTarget | string)[];
+    readonly unsupportedTargets: readonly (FrontierCompileTarget | string)[];
+  };
+  readonly evidence: {
+    readonly parserAdapters: number;
+    readonly adapterCoverageSummaries: number;
+    readonly adapterCoverageGaps: Readonly<Record<string, number>>;
+    readonly knownLossKinds: readonly NativeImportKnownLossKind[];
+    readonly sourceMapMappings: number;
+  };
+  readonly blockers: readonly string[];
+  readonly review: readonly string[];
+}
+
+export interface UniversalCapabilityMatrix {
+  readonly kind: 'frontier.lang.universalCapabilityMatrix';
+  readonly version: 1;
+  readonly generatedAt: number;
+  readonly languages: readonly UniversalCapabilityLanguageRow[];
+  readonly summary: {
+    readonly languages: number;
+    readonly imports: number;
+    readonly symbols: number;
+    readonly sourceMapMappings: number;
+    readonly losses: number;
+    readonly parserRows: number;
+    readonly parserMergeReady: number;
+    readonly targetEntries: number;
+    readonly missingAdapters: number;
+    readonly unsupportedTargetFeatures: number;
+    readonly exactSourceProjection: number;
+    readonly nativeSourceStubs: number;
+    readonly blockers: number;
+    readonly reviewReasons: number;
+    readonly readyLanguages: number;
+    readonly readyWithLossesLanguages: number;
+    readonly reviewLanguages: number;
+    readonly blockedLanguages: number;
+    readonly byReadiness: Readonly<Record<SemanticMergeReadiness, number>>;
+    readonly byImportReadiness: Readonly<Record<SemanticMergeReadiness, number>>;
+    readonly byParserReadiness: Readonly<Record<SemanticMergeReadiness, number>>;
+    readonly byProjectionReadiness: Readonly<Record<SemanticMergeReadiness, number>>;
+  };
+  readonly matrices: {
+    readonly importCoverage: NativeImportCoverageMatrix;
+    readonly parserFormats: NativeParserAstFormatMatrix;
+    readonly parserFeatures: NativeParserFeatureMatrix;
+    readonly projectionTargets: ProjectionTargetLossMatrix;
+  };
+  readonly metadata: {
+    readonly requiredFeatures: readonly NativeParserFeatureCategory[];
+    readonly minimumReadiness: SemanticMergeReadiness;
+    readonly compileTargets: readonly (FrontierCompileTarget | string)[];
+    readonly note: string;
+  };
+}
+
+export interface UniversalCapabilityMatrixOptions extends
+  NativeImportCoverageMatrixOptions,
+  NativeParserAstFormatMatrixOptions,
+  NativeParserFeatureMatrixOptions,
+  ProjectionTargetLossMatrixOptions {
+  readonly targetAdapters?: readonly NativeTargetProjectionAdapter[];
+  readonly targets?: readonly (FrontierCompileTarget | string)[];
+}
+
 export interface NativeImportContractSource {
   readonly id: string;
   readonly language?: FrontierSourceLanguage | string;
@@ -2253,6 +2348,7 @@ export declare function createNativeParserAstFormatMatrix(options?: NativeParser
 export declare function createNativeParserFeatureMatrix(options?: NativeParserFeatureMatrixOptions): NativeParserFeatureMatrix;
 export declare function queryNativeParserFeatureMatrix(matrixOrOptions?: NativeParserFeatureMatrix | NativeParserFeatureMatrixOptions, query?: NativeParserFeatureMatrixQuery): NativeParserFeatureMatrixQueryResult;
 export declare function createProjectionTargetLossMatrix(options?: ProjectionTargetLossMatrixOptions): ProjectionTargetLossMatrix;
+export declare function createUniversalCapabilityMatrix(options?: UniversalCapabilityMatrixOptions): UniversalCapabilityMatrix;
 export declare function createNativeSourcePreservation(options: CreateNativeSourcePreservationOptions): NativeSourcePreservation;
 export declare function createSemanticImportSidecar(importResult: NativeSourceImportResult | NativeProjectImportResult, options?: SemanticImportSidecarOptions): SemanticImportSidecar;
 export declare function createNativeImportResultContract(importResult: NativeSourceImportResult | NativeProjectImportResult, options?: NativeImportResultContractOptions): NativeImportResultContract;

package/dist/index.js

@@ -2488,6 +2488,62 @@ export function createProjectionTargetLossMatrix(input = {}) {
   };
 }
 
+export function createUniversalCapabilityMatrix(input = {}) {
+  const generatedAt = input.generatedAt ?? Date.now();
+  const imports = input.imports ?? [];
+  const adapters = input.adapters ?? [];
+  const targetAdapters = input.targetAdapters ?? [];
+  const languages = input.languages ?? NativeImportLanguageProfiles;
+  const targets = input.targets ?? FrontierCompileTargets;
+  const importCoverage = createNativeImportCoverageMatrix({ languages, imports, adapters, generatedAt });
+  const parserFormats = createNativeParserAstFormatMatrix({
+    formats: input.formats,
+    imports,
+    adapters,
+    generatedAt
+  });
+  const parserFeatures = createNativeParserFeatureMatrix({
+    languages,
+    imports,
+    adapters,
+    requiredFeatures: input.requiredFeatures,
+    minimumReadiness: input.minimumReadiness,
+    includeEmptyParsers: input.includeEmptyParsers,
+    generatedAt
+  });
+  const projectionTargets = createProjectionTargetLossMatrix({
+    languages,
+    imports,
+    adapters,
+    targetAdapters,
+    targets,
+    generatedAt
+  });
+  const rows = importCoverage.languages.map((entry) => universalCapabilityLanguageRow(entry, {
+    parserFeatures,
+    projectionTargets
+  }));
+  return {
+    kind: 'frontier.lang.universalCapabilityMatrix',
+    version: 1,
+    generatedAt,
+    languages: rows,
+    summary: universalCapabilityMatrixSummary(rows),
+    matrices: {
+      importCoverage,
+      parserFormats,
+      parserFeatures,
+      projectionTargets
+    },
+    metadata: {
+      requiredFeatures: parserFeatures.metadata.requiredFeatures,
+      minimumReadiness: parserFeatures.metadata.minimumReadiness,
+      compileTargets: projectionTargets.metadata.compileTargets,
+      note: 'Universal capability coverage composes import, parser, source-preservation, and projection evidence. It identifies gaps; it is not a proof that every language feature is losslessly portable.'
+    }
+  };
+}
+
 export function createNativeSourcePreservation(options) {
   if (!options || typeof options.sourceText !== 'string') {
     throw new Error('createNativeSourcePreservation requires sourceText');
@@ -7191,6 +7247,211 @@ function projectionTargetLossMatrixSummary(languages) {
   };
 }
 
+function universalCapabilityLanguageRow(importCoverage, context) {
+  const languageIds = universalLanguageIds(importCoverage);
+  const parserRows = (context.parserFeatures.parsers ?? []).filter((row) => universalLanguageIds(row).some((id) => languageIds.includes(id)));
+  const parserLanguage = (context.parserFeatures.languages ?? []).find((row) => universalLanguageIds(row).some((id) => languageIds.includes(id)));
+  const projection = (context.projectionTargets.languages ?? []).find((row) => universalLanguageIds(row).some((id) => languageIds.includes(id)));
+  const parserReadiness = parserRows.length
+    ? parserRows.reduce((current, row) => maxSemanticMergeReadiness(current, row.merge?.readiness ?? row.imports?.readiness ?? 'blocked'), 'ready')
+    : 'blocked';
+  const sourceProjectionReadiness = [projection?.sourceProjection?.exactSource, projection?.sourceProjection?.stubs]
+    .filter(Boolean)
+    .reduce((current, entry) => maxSemanticMergeReadiness(current, entry.readiness ?? 'blocked'), 'ready');
+  const targetReadiness = (projection?.targets ?? []).length
+    ? projection.targets.reduce((current, entry) => maxSemanticMergeReadiness(current, entry.readiness ?? 'blocked'), 'ready')
+    : 'blocked';
+  const projectionReadiness = maxSemanticMergeReadiness(sourceProjectionReadiness, targetReadiness);
+  const readiness = maxSemanticMergeReadiness(importCoverage.imports.readiness, maxSemanticMergeReadiness(parserReadiness, projectionReadiness));
+  const parserBlockingFeatures = uniqueStrings(parserRows.flatMap((row) => row.merge?.blockingFeatures ?? []));
+  const parserReviewFeatures = uniqueStrings(parserRows.flatMap((row) => row.merge?.reviewFeatures ?? []));
+  const missingTargets = (projection?.targets ?? []).filter((entry) => entry.lossClass === 'missingAdapter').map((entry) => entry.target);
+  const unsupportedTargets = (projection?.targets ?? []).filter((entry) => entry.lossClass === 'unsupportedTargetFeatures').map((entry) => entry.target);
+  const blockers = universalCapabilityBlockers({
+    importCoverage,
+    parserRows,
+    parserReadiness,
+    parserBlockingFeatures,
+    projection,
+    missingTargets,
+    readiness
+  });
+  const review = universalCapabilityReviewReasons({
+    importCoverage,
+    parserRows,
+    parserReviewFeatures,
+    unsupportedTargets,
+    readiness
+  });
+  return {
+    language: importCoverage.language,
+    aliases: importCoverage.aliases,
+    extensions: importCoverage.extensions,
+    readiness,
+    imports: {
+      total: importCoverage.imports.total,
+      readiness: importCoverage.imports.readiness,
+      symbols: importCoverage.imports.symbols,
+      sourceMaps: importCoverage.imports.sourceMaps,
+      sourceMapMappings: importCoverage.imports.sourceMapMappings,
+      losses: importCoverage.imports.losses,
+      lossKinds: importCoverage.imports.lossKinds,
+      readinessReasons: importCoverage.imports.readinessReasons
+    },
+    parser: {
+      readiness: parserReadiness,
+      rows: parserRows.length,
+      parsers: parserRows.map((row) => row.parser),
+      mergeReadyParsers: parserRows.filter((row) => row.merge?.mergeReady).map((row) => row.parser),
+      blockingFeatures: parserBlockingFeatures,
+      reviewFeatures: parserReviewFeatures,
+      languageSummary: parserLanguage
+    },
+    projection: {
+      readiness: projectionReadiness,
+      sourceProjection: projection?.sourceProjection,
+      targets: projection?.targets ?? [],
+      summary: projection?.summary ?? {
+        imports: 0,
+        parserAdapters: 0,
+        targetEntries: 0,
+        byLossClass: {},
+        exactSourceImports: 0,
+        stubDeclarationImports: 0
+      },
+      missingTargets,
+      unsupportedTargets
+    },
+    evidence: {
+      parserAdapters: importCoverage.parserAdapters.length,
+      adapterCoverageSummaries: importCoverage.adapterCoverage.total,
+      adapterCoverageGaps: importCoverage.adapterCoverage.gaps,
+      knownLossKinds: importCoverage.knownLossKinds,
+      sourceMapMappings: importCoverage.imports.sourceMapMappings
+    },
+    blockers,
+    review
+  };
+}
+
+function universalCapabilityBlockers(input) {
+  const blockers = [];
+  if ((input.importCoverage.imports.total ?? 0) === 0) {
+    blockers.push('No native import evidence observed for this language.');
+  }
+  if (!input.parserRows.length) {
+    blockers.push('No parser feature row matched this language.');
+  }
+  if (input.parserReadiness === 'blocked') {
+    blockers.push('Parser feature readiness is blocked.');
+  }
+  for (const feature of input.parserBlockingFeatures) {
+    blockers.push(`Required parser feature is not merge-ready: ${feature}.`);
+  }
+  if (!input.projection) {
+    blockers.push('No projection coverage row matched this language.');
+  }
+  for (const target of input.missingTargets) {
+    blockers.push(`Missing native-to-target projection adapter for ${target}.`);
+  }
+  if (input.readiness === 'blocked' && blockers.length === 0) {
+    blockers.push('Combined universal capability readiness is blocked.');
+  }
+  return uniqueStrings(blockers);
+}
+
+function universalCapabilityReviewReasons(input) {
+  const review = [];
+  if ((input.importCoverage.imports.losses ?? 0) > 0) {
+    review.push(`Native import evidence carries ${input.importCoverage.imports.losses} loss record(s).`);
+  }
+  for (const reason of input.importCoverage.imports.readinessReasons ?? []) {
+    review.push(reason);
+  }
+  for (const feature of input.parserReviewFeatures) {
+    review.push(`Parser feature needs review: ${feature}.`);
+  }
+  for (const target of input.unsupportedTargets) {
+    review.push(`Target projection has unsupported feature losses for ${target}.`);
+  }
+  if (input.readiness === 'needs-review') {
+    review.push('Combined universal capability readiness requires review.');
+  } else if (input.readiness === 'ready-with-losses') {
+    review.push('Combined universal capability readiness is ready with disclosed losses.');
+  }
+  return uniqueStrings(review);
+}
+
+function universalCapabilityMatrixSummary(rows) {
+  const byReadiness = {};
+  const byImportReadiness = {};
+  const byParserReadiness = {};
+  const byProjectionReadiness = {};
+  let imports = 0;
+  let symbols = 0;
+  let sourceMapMappings = 0;
+  let losses = 0;
+  let parserRows = 0;
+  let parserMergeReady = 0;
+  let targetEntries = 0;
+  let missingAdapters = 0;
+  let unsupportedTargetFeatures = 0;
+  let exactSourceProjection = 0;
+  let nativeSourceStubs = 0;
+  let blockers = 0;
+  let reviewReasons = 0;
+  for (const row of rows) {
+    byReadiness[row.readiness] = (byReadiness[row.readiness] ?? 0) + 1;
+    byImportReadiness[row.imports.readiness] = (byImportReadiness[row.imports.readiness] ?? 0) + 1;
+    byParserReadiness[row.parser.readiness] = (byParserReadiness[row.parser.readiness] ?? 0) + 1;
+    byProjectionReadiness[row.projection.readiness] = (byProjectionReadiness[row.projection.readiness] ?? 0) + 1;
+    imports += row.imports.total;
+    symbols += row.imports.symbols;
+    sourceMapMappings += row.imports.sourceMapMappings;
+    losses += row.imports.losses;
+    parserRows += row.parser.rows;
+    parserMergeReady += row.parser.mergeReadyParsers.length;
+    targetEntries += row.projection.targets.length;
+    missingAdapters += row.projection.missingTargets.length;
+    unsupportedTargetFeatures += row.projection.unsupportedTargets.length;
+    exactSourceProjection += row.projection.summary.byLossClass?.exactSourceProjection ?? 0;
+    nativeSourceStubs += row.projection.summary.byLossClass?.nativeSourceStubs ?? 0;
+    blockers += row.blockers.length;
+    reviewReasons += row.review.length;
+  }
+  return {
+    languages: rows.length,
+    imports,
+    symbols,
+    sourceMapMappings,
+    losses,
+    parserRows,
+    parserMergeReady,
+    targetEntries,
+    missingAdapters,
+    unsupportedTargetFeatures,
+    exactSourceProjection,
+    nativeSourceStubs,
+    blockers,
+    reviewReasons,
+    readyLanguages: rows.filter((row) => row.readiness === 'ready').length,
+    readyWithLossesLanguages: rows.filter((row) => row.readiness === 'ready-with-losses').length,
+    reviewLanguages: rows.filter((row) => row.readiness === 'needs-review').length,
+    blockedLanguages: rows.filter((row) => row.readiness === 'blocked').length,
+    byReadiness,
+    byImportReadiness,
+    byParserReadiness,
+    byProjectionReadiness
+  };
+}
+
+function universalLanguageIds(entry) {
+  return uniqueStrings([
+    entry?.language,
+    ...(entry?.aliases ?? [])
+  ].map(normalizeNativeLanguageId).filter(Boolean));
+}
+
 function countProjectionLossClasses(entries) {
   const counts = {};
   for (const entry of entries ?? []) {

package/package.json

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