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

package/README.md

@@ -38,6 +38,56 @@ console.log(imported.nativeSource.ast.rootId);
 console.log(imported.patch.operations.length);
 ```
 
+Native imports include source maps, semantic merge candidates, and a loss summary for admission queues and dashboards. Informational losses produce `ready-with-losses`, warning losses produce `needs-review`, and error losses or failed import evidence produce `blocked`:
+
+```js
+import { classifyNativeImportReadiness, summarizeNativeImportLosses } from '@shapeshift-labs/frontier-lang-compiler';
+
+const summary = summarizeNativeImportLosses(imported.losses, { evidence: imported.evidence });
+const readiness = classifyNativeImportReadiness(imported.losses, { evidence: imported.evidence });
+
+console.log(summary.categories);
+console.log(readiness.readiness);
+```
+
+Use injected parser adapters when a real language parser is available but should not become a compiler runtime dependency:
+
+```js
+import {
+  createBabelNativeImporterAdapter,
+  importNativeProject,
+  runNativeImporterAdapter
+} from '@shapeshift-labs/frontier-lang-compiler';
+
+const babelAdapter = createBabelNativeImporterAdapter({
+  parserModule: await import('@babel/parser')
+});
+
+const imported = await runNativeImporterAdapter(babelAdapter, {
+  sourcePath: 'src/todo.ts',
+  sourceText
+});
+
+const project = await importNativeProject({
+  projectRoot: 'src',
+  adapters: [babelAdapter],
+  sources: [
+    { language: 'typescript', adapter: babelAdapter.id, sourcePath: 'src/todo.ts', sourceText },
+    { language: 'python', sourcePath: 'tools/todo.py', sourceText: pythonSource }
+  ]
+});
+
+console.log(imported.universalAst.sourceMaps.length);
+console.log(project.semanticIndex.symbols.length);
+```
+
+The built-in adapter factories are dependency-light wrappers for caller-owned parsers or ASTs:
+
+- `createEstreeNativeImporterAdapter`
+- `createBabelNativeImporterAdapter`
+- `createTypeScriptCompilerNativeImporterAdapter`
+- `createTreeSitterNativeImporterAdapter`
+
 ## Related Packages
 
 The published Frontier package family is generated from one shared package catalog so READMEs stay in sync across packages:

package/bench/smoke.mjs

@@ -1,5 +1,10 @@
 import { performance } from 'node:perf_hooks';
-import { compileFrontierSource } from '../dist/index.js';
+import {
+  compileFrontierSource,
+  createEstreeNativeImporterAdapter,
+  importNativeSource,
+  runNativeImporterAdapter
+} from '../dist/index.js';
 
 const source = `
 module Bench @id("mod_bench")
@@ -22,4 +27,42 @@ let bytes = 0;
 for (let index = 0; index < 250; index += 1) {
   bytes += compileFrontierSource(source, { target: targets[index % targets.length] }).output.length;
 }
-console.log(JSON.stringify({ compiles: 250, bytes, durationMs: Number((performance.now() - start).toFixed(2)) }));
+const compileDurationMs = performance.now() - start;
+
+const importStart = performance.now();
+const estreeAdapter = createEstreeNativeImporterAdapter();
+let nativeSymbols = 0;
+for (let index = 0; index < 150; index += 1) {
+  const imported = index % 2 === 0
+    ? importNativeSource({
+      language: 'javascript',
+      sourcePath: `src/bench-${index}.js`,
+      sourceText: `export function bench${index}() { return ${index}; }\n`
+    })
+    : await runNativeImporterAdapter(estreeAdapter, {
+      sourcePath: `src/bench-${index}.js`,
+      sourceText: `export function bench${index}() { return ${index}; }\n`,
+      adapterOptions: {
+        ast: {
+          type: 'Program',
+          loc: { start: { line: 1, column: 0 }, end: { line: 1, column: 42 } },
+          body: [{
+            type: 'FunctionDeclaration',
+            id: { type: 'Identifier', name: `bench${index}` },
+            loc: { start: { line: 1, column: 0 }, end: { line: 1, column: 42 } }
+          }]
+        }
+      }
+    });
+  nativeSymbols += imported.semanticIndex?.symbols?.length ?? 0;
+}
+const importDurationMs = performance.now() - importStart;
+
+console.log(JSON.stringify({
+  compiles: 250,
+  bytes,
+  compileDurationMs: Number(compileDurationMs.toFixed(2)),
+  nativeImports: 150,
+  nativeSymbols,
+  nativeImportDurationMs: Number(importDurationMs.toFixed(2))
+}));

package/dist/index.d.ts

@@ -11,9 +11,13 @@ import type {
   NativeAstNode,
   NativeAstRecord,
   NativeSourceNode,
+  SemanticMergeCandidateRecord,
+  SemanticMergeReadiness,
   SemanticIndexRecord,
   SemanticNode,
   SemanticPatchBundle,
+  SourceMapMappingRecord,
+  SourceMapRecord,
   SourceSpan
 } from '@shapeshift-labs/frontier-lang-kernel';
 import type { Diagnostic } from '@shapeshift-labs/frontier-lang-checker';
@@ -69,6 +73,68 @@ export interface CapabilityResolution {
   readonly reason?: string;
 }
 
+export type NativeImportTaxonomyKind =
+  | 'exactAstImport'
+  | 'declarationsOnly'
+  | 'opaqueBodies'
+  | 'macroExpansion'
+  | 'preprocessor'
+  | 'metaprogramming'
+  | 'generatedCode'
+  | 'sourcePreservation'
+  | 'parserDiagnostics'
+  | 'unsupportedSyntax'
+  | 'partialSemanticIndex'
+  | 'sourceMapApproximation'
+  | string;
+
+export type NativeImportKnownLossKind =
+  | 'declarationOnlyCoverage'
+  | 'opaqueNative'
+  | 'macroExpansion'
+  | 'preprocessor'
+  | 'metaprogramming'
+  | 'generatedCode'
+  | 'sourcePreservation'
+  | 'parserDiagnostic'
+  | 'unsupportedSyntax'
+  | 'partialSemanticIndex'
+  | 'sourceMapApproximation'
+  | string;
+
+export interface NativeImportLossSummaryOptions {
+  readonly exactAst?: boolean;
+  readonly evidence?: readonly EvidenceRecord[];
+  readonly parser?: string;
+  readonly scanKind?: string;
+  readonly semanticStatus?: string;
+}
+
+export interface NativeImportLossSummary {
+  readonly total: number;
+  readonly hasLosses: boolean;
+  readonly exactAst: boolean;
+  readonly highestSeverity: 'none' | NativeAstLossRecord['severity'];
+  readonly semanticMergeReadiness: SemanticMergeReadiness;
+  readonly readinessReasons: readonly string[];
+  readonly categories: readonly NativeImportTaxonomyKind[];
+  readonly bySeverity: Readonly<Record<NativeAstLossRecord['severity'], number>>;
+  readonly byKind: Readonly<Record<string, number>>;
+  readonly blockingLossIds: readonly string[];
+  readonly reviewLossIds: readonly string[];
+  readonly informationalLossIds: readonly string[];
+  readonly failedEvidenceIds: readonly string[];
+  readonly parser?: string;
+  readonly scanKind?: string;
+  readonly semanticStatus?: string;
+}
+
+export interface NativeImportReadinessClassification {
+  readonly readiness: SemanticMergeReadiness;
+  readonly reasons: readonly string[];
+  readonly summary: NativeImportLossSummary;
+}
+
 export interface NativeImporterAdapterDiagnostic {
   readonly id?: string;
   readonly severity?: 'info' | 'warning' | 'error';
@@ -104,7 +170,7 @@ export interface ImportNativeSourceOptions {
   readonly nodes?: Readonly<Record<string, NativeAstNode>>;
   readonly semanticNodes?: readonly SemanticNode[];
   readonly frontierNodeIds?: readonly string[];
-  readonly mappings?: readonly unknown[];
+  readonly mappings?: readonly SourceMapMappingRecord[];
   readonly semanticStatus?: 'native-only' | 'mapped' | 'partial' | string;
   readonly losses?: readonly NativeAstLossRecord[];
   readonly evidence?: readonly EvidenceRecord[];
@@ -113,7 +179,11 @@ export interface ImportNativeSourceOptions {
   readonly patchId?: string;
   readonly author?: string;
   readonly target?: CompileTarget;
+  readonly targetPath?: string;
+  readonly targetHash?: string;
   readonly semanticIndex?: SemanticIndexRecord;
+  readonly sourceMapId?: string;
+  readonly sourceMaps?: readonly SourceMapRecord[];
   readonly universalAstId?: string;
   readonly universalAstMetadata?: Record<string, unknown>;
   readonly metadata?: Record<string, unknown>;
@@ -153,6 +223,56 @@ export interface NativeImporterAdapter {
   readonly parse: (input: NativeImporterAdapterParseInput) => NativeImporterAdapterParseResult | Promise<NativeImporterAdapterParseResult>;
 }
 
+export interface JavaScriptNativeImporterAdapterOptions {
+  readonly id?: string;
+  readonly language?: FrontierSourceLanguage;
+  readonly parser?: string;
+  readonly version?: string;
+  readonly capabilities?: readonly string[];
+  readonly supportedExtensions?: readonly string[];
+  readonly diagnostics?: readonly NativeImporterAdapterDiagnostic[];
+  readonly ast?: unknown;
+  readonly parse?: (sourceText: string, options: Record<string, unknown>) => unknown;
+  readonly parserModule?: { readonly parse: (sourceText: string, options: Record<string, unknown>) => unknown };
+  readonly babelParser?: { readonly parse: (sourceText: string, options: Record<string, unknown>) => unknown };
+  readonly parserOptions?: Record<string, unknown> | ((input: NativeImporterAdapterParseInput) => Record<string, unknown>);
+  readonly maxNodes?: number;
+}
+
+export interface TypeScriptCompilerNativeImporterAdapterOptions {
+  readonly id?: string;
+  readonly language?: FrontierSourceLanguage;
+  readonly parser?: string;
+  readonly version?: string;
+  readonly capabilities?: readonly string[];
+  readonly supportedExtensions?: readonly string[];
+  readonly diagnostics?: readonly NativeImporterAdapterDiagnostic[];
+  readonly typescript?: unknown;
+  readonly ts?: unknown;
+  readonly sourceFile?: unknown;
+  readonly createSourceFile?: (input: NativeImporterAdapterParseInput, typescript?: unknown) => unknown;
+  readonly scriptTarget?: unknown;
+  readonly scriptKind?: unknown;
+  readonly maxNodes?: number;
+  readonly includeTokens?: boolean;
+}
+
+export interface TreeSitterNativeImporterAdapterOptions {
+  readonly id?: string;
+  readonly language?: FrontierSourceLanguage;
+  readonly parser?: string | { readonly parse?: (sourceText: string) => unknown };
+  readonly parserName?: string;
+  readonly version?: string;
+  readonly capabilities?: readonly string[];
+  readonly supportedExtensions?: readonly string[];
+  readonly diagnostics?: readonly NativeImporterAdapterDiagnostic[];
+  readonly parserInstance?: { readonly parse: (sourceText: string) => unknown };
+  readonly treeSitterParser?: { readonly parse: (sourceText: string) => unknown };
+  readonly parse?: (input: NativeImporterAdapterParseInput) => unknown;
+  readonly tree?: unknown;
+  readonly maxNodes?: number;
+}
+
 export interface NativeImporterAdapterSummary {
   readonly id: string;
   readonly language: FrontierSourceLanguage;
@@ -177,18 +297,75 @@ export type NativeImporterAdapterImportResult = NativeSourceImportResult & {
   readonly diagnostics: readonly NativeImporterAdapterDiagnostic[];
 };
 
+export interface NativeProjectSourceInput extends ImportNativeSourceOptions {
+  readonly adapter?: NativeImporterAdapter | string;
+  readonly adapterOptions?: Record<string, unknown>;
+  readonly adapterMetadata?: Record<string, unknown>;
+}
+
+export interface ImportNativeProjectOptions {
+  readonly id?: string;
+  readonly name?: string;
+  readonly language?: FrontierSourceLanguage | 'mixed';
+  readonly projectRoot?: string;
+  readonly documentId?: string;
+  readonly documentName?: string;
+  readonly documentMetadata?: Record<string, unknown>;
+  readonly universalAstId?: string;
+  readonly universalAstMetadata?: Record<string, unknown>;
+  readonly semanticIndexId?: string;
+  readonly patchId?: string;
+  readonly author?: string;
+  readonly metadata?: Record<string, unknown>;
+  readonly adapterOptions?: Record<string, unknown>;
+  readonly adapterMetadata?: Record<string, unknown>;
+  readonly adapters?: readonly NativeImporterAdapter[];
+  readonly adapterResolver?: (source: NativeProjectSourceInput, adapters: readonly NativeImporterAdapter[]) => NativeImporterAdapter | undefined;
+  readonly sources: readonly NativeProjectSourceInput[];
+}
+
+export interface NativeProjectImportResult {
+  readonly kind: 'frontier.lang.projectImportResult';
+  readonly version: 1;
+  readonly id: string;
+  readonly language: FrontierSourceLanguage | 'mixed';
+  readonly projectRoot?: string;
+  readonly imports: readonly NativeSourceImportResult[];
+  readonly document: FrontierLangDocument;
+  readonly patch: SemanticPatchBundle;
+  readonly nativeSources: readonly NativeSourceNode[];
+  readonly semanticIndex?: SemanticIndexRecord;
+  readonly universalAst: FrontierUniversalAstEnvelope;
+  readonly sourceMaps: readonly SourceMapRecord[];
+  readonly losses: readonly NativeAstLossRecord[];
+  readonly evidence: readonly EvidenceRecord[];
+  readonly mergeCandidates: readonly SemanticMergeCandidateRecord[];
+  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 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 projectFrontierAst(document: FrontierLangDocument, target?: FrontierCompileOptions['target'], options?: FrontierCompileEmitOptions): FrontierTargetAst;
 export declare function renderTargetAst(ast: FrontierTargetAst, target?: FrontierCompileOptions['target']): string;
 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 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 importNativeSource(input: ImportNativeSourceOptions): NativeSourceImportResult;
+export declare function importNativeProject(input: ImportNativeProjectOptions): Promise<NativeProjectImportResult>;
 export declare function createUniversalAstFromDocument(document: FrontierLangDocument, input?: {
   readonly id?: string;
   readonly semanticIndex?: SemanticIndexRecord;
+  readonly sourceMaps?: readonly SourceMapRecord[];
   readonly evidence?: readonly EvidenceRecord[];
   readonly metadata?: Record<string, unknown>;
 }): FrontierUniversalAstEnvelope;