@shapeshift-labs/frontier-lang-compiler 0.2.8 → 0.2.9

package/README.md

@@ -50,6 +50,73 @@ console.log(summary.categories);
 console.log(readiness.readiness);
 ```
 
+Ask the compiler what is actually covered before sending native imports into a merge queue:
+
+```js
+import {
+  createNativeImportCoverageMatrix,
+  importNativeSource
+} from '@shapeshift-labs/frontier-lang-compiler';
+
+const imported = importNativeSource({
+  language: 'python',
+  sourcePath: 'todo.py',
+  sourceText: 'def add_todo(title):\n    return title\n'
+});
+
+const matrix = createNativeImportCoverageMatrix({ imports: [imported] });
+const python = matrix.languages.find((entry) => entry.language === 'python');
+
+console.log(python.imports.readiness); // scanner imports are intentionally review-required
+console.log(python.parserAdapters); // host-owned exact parsers such as LibCST can be injected
+```
+
+Create a compact semantic sidecar for swarm merge admission. This is the artifact a coordinator can index instead of reading a worker directory by hand:
+
+```js
+import {
+  createSemanticImportSidecar,
+  importNativeSource
+} from '@shapeshift-labs/frontier-lang-compiler';
+
+const imported = importNativeSource({
+  language: 'typescript',
+  sourcePath: 'src/runtime.ts',
+  sourceText: `
+    export class Runtime {
+      step(frame: number) { return frame + 1; }
+    }
+  `
+});
+
+const sidecar = createSemanticImportSidecar(imported);
+
+console.log(sidecar.summary.emptySemanticIndex); // false when symbols were found
+console.log(sidecar.ownershipRegions[0].key); // source#src/runtime.ts#class#Runtime
+console.log(sidecar.patchHints[0].supportedOperations); // source-region patch operations
+```
+
+Project a native import back to source. Exact source is preserved only when the supplied text matches the import hash; otherwise the compiler emits declaration stubs with review-required loss evidence:
+
+```js
+import {
+  importNativeSource,
+  projectNativeImportToSource
+} from '@shapeshift-labs/frontier-lang-compiler';
+
+const sourceText = 'export function step(frame) { return frame + 1; }\n';
+const imported = importNativeSource({
+  language: 'javascript',
+  sourcePath: 'src/runtime.js',
+  sourceText
+});
+
+const projection = projectNativeImportToSource(imported, { sourceText });
+
+console.log(projection.mode); // "preserved-source"
+console.log(projection.readiness.readiness); // "ready"
+```
+
 Use injected parser adapters when a real language parser is available but should not become a compiler runtime dependency:
 
 ```js

package/bench/smoke.mjs

@@ -2,7 +2,10 @@ import { performance } from 'node:perf_hooks';
 import {
   compileFrontierSource,
   createEstreeNativeImporterAdapter,
+  createNativeImportCoverageMatrix,
+  createSemanticImportSidecar,
   importNativeSource,
+  projectNativeImportToSource,
   runNativeImporterAdapter
 } from '../dist/index.js';
 
@@ -32,6 +35,7 @@ const compileDurationMs = performance.now() - start;
 const importStart = performance.now();
 const estreeAdapter = createEstreeNativeImporterAdapter();
 let nativeSymbols = 0;
+const nativeImportResults = [];
 for (let index = 0; index < 150; index += 1) {
   const imported = index % 2 === 0
     ? importNativeSource({
@@ -55,14 +59,38 @@ for (let index = 0; index < 150; index += 1) {
       }
     });
   nativeSymbols += imported.semanticIndex?.symbols?.length ?? 0;
+  nativeImportResults.push(imported);
 }
 const importDurationMs = performance.now() - importStart;
 
+const matrixStart = performance.now();
+const coverageMatrix = createNativeImportCoverageMatrix({ imports: nativeImportResults });
+const matrixDurationMs = performance.now() - matrixStart;
+
+const sidecarStart = performance.now();
+const semanticSidecars = nativeImportResults.map((imported) => createSemanticImportSidecar(imported));
+const sidecarDurationMs = performance.now() - sidecarStart;
+const sidecarOwnershipRegions = semanticSidecars.reduce((sum, sidecar) => sum + sidecar.ownershipRegions.length, 0);
+
+const projectionStart = performance.now();
+const nativeProjections = nativeImportResults.map((imported) => projectNativeImportToSource(imported));
+const projectionDurationMs = performance.now() - projectionStart;
+const projectionBytes = nativeProjections.reduce((sum, projection) => sum + projection.sourceText.length, 0);
+
 console.log(JSON.stringify({
   compiles: 250,
   bytes,
   compileDurationMs: Number(compileDurationMs.toFixed(2)),
   nativeImports: 150,
   nativeSymbols,
-  nativeImportDurationMs: Number(importDurationMs.toFixed(2))
+  nativeImportDurationMs: Number(importDurationMs.toFixed(2)),
+  coverageMatrixLanguages: coverageMatrix.summary.languages,
+  coverageMatrixImports: coverageMatrix.summary.imports,
+  coverageMatrixDurationMs: Number(matrixDurationMs.toFixed(2)),
+  semanticSidecars: semanticSidecars.length,
+  sidecarOwnershipRegions,
+  sidecarDurationMs: Number(sidecarDurationMs.toFixed(2)),
+  nativeProjections: nativeProjections.length,
+  projectionBytes,
+  projectionDurationMs: Number(projectionDurationMs.toFixed(2))
 }));

package/dist/index.d.ts

@@ -135,6 +135,193 @@ export interface NativeImportReadinessClassification {
   readonly summary: NativeImportLossSummary;
 }
 
+export interface NativeImportLanguageProfile {
+  readonly language: FrontierSourceLanguage;
+  readonly aliases: readonly string[];
+  readonly extensions: readonly string[];
+  readonly supportsLightweightScan: boolean;
+  readonly parserAdapters: readonly string[];
+  readonly projectionTargets: readonly FrontierCompileTarget[];
+  readonly knownLossKinds: readonly NativeImportKnownLossKind[];
+  readonly defaultReadiness: SemanticMergeReadiness;
+  readonly notes: readonly string[];
+}
+
+export interface NativeImportCoverageLanguage {
+  readonly language: FrontierSourceLanguage;
+  readonly aliases: readonly string[];
+  readonly extensions: readonly string[];
+  readonly supportsLightweightScan: boolean;
+  readonly parserAdapters: readonly string[];
+  readonly projectionTargets: readonly FrontierCompileTarget[];
+  readonly knownLossKinds: readonly NativeImportKnownLossKind[];
+  readonly defaultReadiness: SemanticMergeReadiness;
+  readonly notes: readonly string[];
+  readonly imports: {
+    readonly total: number;
+    readonly parsers: readonly string[];
+    readonly readiness: SemanticMergeReadiness;
+    readonly readinessReasons: readonly string[];
+    readonly symbols: number;
+    readonly sourceMaps: number;
+    readonly sourceMapMappings: number;
+    readonly losses: number;
+    readonly lossKinds: Readonly<Record<string, number>>;
+    readonly lossCategories: readonly NativeImportTaxonomyKind[];
+  };
+}
+
+export interface NativeImportCoverageMatrix {
+  readonly kind: 'frontier.lang.nativeImportCoverageMatrix';
+  readonly version: 1;
+  readonly generatedAt: number;
+  readonly languages: readonly NativeImportCoverageLanguage[];
+  readonly summary: {
+    readonly languages: number;
+    readonly lightweightScanners: number;
+    readonly parserAdapterSlots: number;
+    readonly imports: number;
+    readonly symbols: number;
+    readonly sourceMaps: number;
+    readonly sourceMapMappings: number;
+    readonly losses: number;
+    readonly byReadiness: Readonly<Record<string, number>>;
+    readonly lossKinds: Readonly<Record<string, number>>;
+  };
+  readonly metadata: {
+    readonly compileTargets: readonly FrontierCompileTarget[];
+    readonly note: string;
+  };
+}
+
+export interface NativeImportCoverageMatrixOptions {
+  readonly languages?: readonly NativeImportLanguageProfile[];
+  readonly imports?: readonly NativeSourceImportResult[];
+  readonly adapters?: readonly NativeImporterAdapter[];
+  readonly generatedAt?: number;
+}
+
+export interface SemanticImportOwnershipRegion {
+  readonly id: string;
+  readonly key: string;
+  readonly granularity: 'symbol' | string;
+  readonly language?: FrontierSourceLanguage | string;
+  readonly sourcePath?: string;
+  readonly sourceHash?: string;
+  readonly symbolId?: string;
+  readonly symbolName?: string;
+  readonly symbolKind?: string;
+  readonly nativeAstNodeId?: string;
+  readonly sourceSpan?: SourceSpan;
+  readonly precision?: 'exact' | 'declaration' | 'line' | 'estimated' | 'unknown' | string;
+  readonly mergePolicy?: string;
+}
+
+export interface SemanticImportSidecarSymbol {
+  readonly id: string;
+  readonly name?: string;
+  readonly kind?: string;
+  readonly language?: FrontierSourceLanguage | string;
+  readonly nativeAstNodeId?: string;
+  readonly semanticOccurrenceId?: string;
+  readonly sourceMapMappingId?: string;
+  readonly sourceSpan?: SourceSpan;
+  readonly signatureHash?: string;
+  readonly ownershipRegionId: string;
+  readonly ownershipKey: string;
+  readonly readiness: SemanticMergeReadiness;
+}
+
+export interface SemanticImportPatchHint {
+  readonly id: string;
+  readonly kind: 'source-region-patch' | string;
+  readonly ownershipRegionId: string;
+  readonly ownershipKey: string;
+  readonly sourcePath?: string;
+  readonly sourceHash?: string;
+  readonly sourceSpan?: SourceSpan;
+  readonly readiness: SemanticMergeReadiness;
+  readonly precision?: string;
+  readonly supportedOperations: readonly string[];
+  readonly projection: {
+    readonly sourceLanguage?: FrontierSourceLanguage | string;
+    readonly targetPath?: string;
+    readonly requiresSourceMap: boolean;
+  };
+}
+
+export interface SemanticImportSidecarImportEntry {
+  readonly id: string;
+  readonly language?: FrontierSourceLanguage | string;
+  readonly sourcePath?: string;
+  readonly sourceHash?: string;
+  readonly parser?: string;
+  readonly nativeSourceId?: string;
+  readonly nativeAstId?: string;
+  readonly semanticIndexId?: string;
+  readonly universalAstId?: string;
+  readonly symbolCount: number;
+  readonly sourceMapCount: number;
+  readonly sourceMapMappingCount: number;
+  readonly readiness: SemanticMergeReadiness;
+  readonly emptySemanticIndex: boolean;
+}
+
+export interface SemanticImportSidecar {
+  readonly kind: 'frontier.lang.semanticImportSidecar';
+  readonly version: 1;
+  readonly id: string;
+  readonly generatedAt: number;
+  readonly language?: FrontierSourceLanguage | 'mixed' | string;
+  readonly projectRoot?: string;
+  readonly imports: readonly SemanticImportSidecarImportEntry[];
+  readonly symbols: readonly SemanticImportSidecarSymbol[];
+  readonly ownershipRegions: readonly SemanticImportOwnershipRegion[];
+  readonly sourceMaps: {
+    readonly total: number;
+    readonly mappings: number;
+    readonly ids: readonly string[];
+  };
+  readonly patchHints: readonly SemanticImportPatchHint[];
+  readonly mergeCandidates: readonly {
+    readonly id?: string;
+    readonly readiness?: SemanticMergeReadiness;
+    readonly reasons: readonly string[];
+    readonly risk?: string;
+    readonly operationCount: number;
+  }[];
+  readonly losses: {
+    readonly total: number;
+    readonly byKind: Readonly<Record<string, number>>;
+    readonly bySeverity: Readonly<Record<string, number>>;
+    readonly categories: readonly NativeImportTaxonomyKind[];
+    readonly blockingLossIds: readonly string[];
+    readonly reviewLossIds: readonly string[];
+  };
+  readonly evidence: {
+    readonly total: number;
+    readonly failed: readonly string[];
+    readonly ids: readonly string[];
+  };
+  readonly summary: {
+    readonly imports: number;
+    readonly symbols: number;
+    readonly ownershipRegions: number;
+    readonly sourceMapMappings: number;
+    readonly readiness: SemanticMergeReadiness;
+    readonly emptySemanticIndex: boolean;
+  };
+  readonly metadata?: Record<string, unknown>;
+}
+
+export interface SemanticImportSidecarOptions {
+  readonly id?: string;
+  readonly generatedAt?: number;
+  readonly regionPrefix?: string;
+  readonly targetPath?: string;
+  readonly metadata?: Record<string, unknown>;
+}
+
 export interface NativeImporterAdapterDiagnostic {
   readonly id?: string;
   readonly severity?: 'info' | 'warning' | 'error';
@@ -343,10 +530,62 @@ export interface NativeProjectImportResult {
   readonly metadata?: Record<string, unknown>;
 }
 
+export type NativeSourceProjectionMode = 'preserved-source' | 'native-source-stubs';
+
+export interface ProjectNativeImportToSourceOptions {
+  readonly id?: string;
+  readonly language?: FrontierSourceLanguage | string;
+  readonly sourcePath?: string;
+  readonly expectedSourceHash?: string;
+  readonly sourceText?: string;
+  readonly preservedSourceText?: string;
+  readonly exactSourceText?: string;
+  readonly sourceHash?: string;
+  readonly verifySourceHash?: boolean;
+  readonly preferPreservedSource?: boolean;
+  readonly stubBanner?: string | false;
+  readonly evidenceId?: string;
+  readonly parser?: string;
+  readonly semanticStatus?: string;
+  readonly nativeSource?: NativeSourceNode;
+  readonly nativeAst?: NativeAstRecord;
+  readonly semanticIndex?: SemanticIndexRecord;
+  readonly metadata?: Record<string, unknown>;
+}
+
+export interface NativeSourceProjectionDeclaration {
+  readonly name: string;
+  readonly kind: string;
+  readonly symbolId?: string;
+  readonly nativeAstNodeId?: string;
+  readonly sourceSpan?: SourceSpan;
+  readonly ownershipRegionId?: string;
+  readonly metadata?: Record<string, unknown>;
+}
+
+export interface NativeSourceProjectionResult {
+  readonly kind: 'frontier.lang.nativeSourceProjection';
+  readonly version: 1;
+  readonly id: string;
+  readonly language: FrontierSourceLanguage | string;
+  readonly sourcePath?: string;
+  readonly sourceHash?: string;
+  readonly mode: NativeSourceProjectionMode;
+  readonly sourceText: string;
+  readonly outputHash: string;
+  readonly declarations: readonly NativeSourceProjectionDeclaration[];
+  readonly losses: readonly NativeAstLossRecord[];
+  readonly lossSummary: NativeImportLossSummary;
+  readonly readiness: NativeImportReadinessClassification;
+  readonly evidence: readonly EvidenceRecord[];
+  readonly metadata: Record<string, unknown>;
+}
+
 export declare const FrontierCompileTargets: readonly FrontierCompileTarget[];
 export declare const NativeImportTaxonomyKinds: readonly NativeImportTaxonomyKind[];
 export declare const NativeImportLossKinds: readonly NativeImportKnownLossKind[];
 export declare const NativeImportReadinessBySeverity: Readonly<Record<NativeImportLossSummary['highestSeverity'], SemanticMergeReadiness>>;
+export declare const NativeImportLanguageProfiles: readonly NativeImportLanguageProfile[];
 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;
@@ -355,11 +594,14 @@ export declare function renderTargetAst(ast: FrontierTargetAst, target?: Frontie
 export declare function resolveCapabilityAdapters(document: FrontierLangDocument, target?: FrontierCompileOptions['target'], options?: { readonly platform?: string }): readonly CapabilityResolution[];
 export declare function summarizeNativeImportLosses(losses?: readonly NativeAstLossRecord[], options?: NativeImportLossSummaryOptions): NativeImportLossSummary;
 export declare function classifyNativeImportReadiness(losses?: readonly NativeAstLossRecord[], options?: NativeImportLossSummaryOptions): NativeImportReadinessClassification;
+export declare function createNativeImportCoverageMatrix(options?: NativeImportCoverageMatrixOptions): NativeImportCoverageMatrix;
+export declare function createSemanticImportSidecar(importResult: NativeSourceImportResult | NativeProjectImportResult, options?: SemanticImportSidecarOptions): SemanticImportSidecar;
 export declare function createEstreeNativeImporterAdapter(options?: JavaScriptNativeImporterAdapterOptions): NativeImporterAdapter;
 export declare function createBabelNativeImporterAdapter(options?: JavaScriptNativeImporterAdapterOptions): NativeImporterAdapter;
 export declare function createTypeScriptCompilerNativeImporterAdapter(options?: TypeScriptCompilerNativeImporterAdapterOptions): NativeImporterAdapter;
 export declare function createTreeSitterNativeImporterAdapter(options?: TreeSitterNativeImporterAdapterOptions): NativeImporterAdapter;
 export declare function runNativeImporterAdapter(adapter: NativeImporterAdapter, input: RunNativeImporterAdapterOptions): Promise<NativeImporterAdapterImportResult>;
+export declare function projectNativeImportToSource(importResult: NativeSourceImportResult | NativeProjectImportResult, options?: ProjectNativeImportToSourceOptions): NativeSourceProjectionResult;
 export declare function importNativeSource(input: ImportNativeSourceOptions): NativeSourceImportResult;
 export declare function importNativeProject(input: ImportNativeProjectOptions): Promise<NativeProjectImportResult>;
 export declare function createUniversalAstFromDocument(document: FrontierLangDocument, input?: {