@shapeshift-labs/frontier-lang-compiler 0.2.21 → 0.2.23

package/README.md

@@ -50,6 +50,34 @@ console.log(imported.nativeSource.ast.rootId);
 console.log(imported.patch.operations.length);
 ```
 
+Import external code-intelligence payloads into Frontier semantic evidence when a project already has language tooling such as SCIP, LSIF, LSP, or SemanticDB:
+
+```js
+import { importExternalSemanticIndex } from '@shapeshift-labs/frontier-lang-compiler';
+
+const importedIndex = importExternalSemanticIndex({
+  format: 'scip',
+  language: 'typescript',
+  payload: {
+    metadata: { project_root: '/repo' },
+    documents: [{
+      relative_path: 'src/todo.ts',
+      occurrences: [{
+        symbol: 'scip-typescript npm todo 1.0.0 src/todo.ts/ addTodo().',
+        range: [0, 16, 23],
+        symbol_roles: 1
+      }]
+    }]
+  }
+});
+
+console.log(importedIndex.semanticIndex.symbols.length);
+console.log(importedIndex.summary.sourceMapMappings);
+console.log(importedIndex.readiness.readiness); // "ready-with-losses" or review-required
+```
+
+External semantic-index imports create Frontier `SemanticIndexRecord`, `SourceMapRecord`, evidence, losses, ownership facts, and a universal AST envelope. They are a bridge from existing language servers/indexers into semantic merge tooling; they do not claim full parser AST coverage, macro expansion, type checking, comments/trivia preservation, or lossless cross-language code generation by themselves.
+
 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
@@ -64,6 +92,25 @@ console.log(readiness.readiness);
 
 The loss taxonomy separates broad scanner limits from specific round-trip risks such as conditional compilation, reflection, overload/type-inference gaps, comments/trivia preservation, source-map approximation, parser diagnostics, and target projection loss. These records are evidence labels for merge admission; they are not claims that the lightweight scanner expanded macros, evaluated inactive branches, resolved overloads, or ran a type checker.
 
+High-risk native features also have explicit evidence policies. These policies are advisory in this package: they tell a swarm or admission queue what evidence is missing without silently changing the existing readiness classification.
+
+```js
+import {
+  getNativeImportFeatureEvidencePolicy,
+  summarizeNativeImportFeatureEvidence
+} from '@shapeshift-labs/frontier-lang-compiler';
+
+const policy = getNativeImportFeatureEvidencePolicy('preprocessor');
+console.log(policy.requiredEvidenceKeys); // ["preprocessedOutputHash", "definesHash"]
+
+const featureEvidence = summarizeNativeImportFeatureEvidence(imported.losses, {
+  evidence: imported.evidence
+});
+
+console.log(featureEvidence.highestRisk);
+console.log(featureEvidence.missingRequiredEvidence);
+```
+
 Ask the compiler what is actually covered before sending native imports into a merge queue:
 
 ```js

package/bench/smoke.mjs

@@ -7,9 +7,11 @@ import {
   createProjectionTargetLossMatrix,
   createNativeSourcePreservation,
   createSemanticImportSidecar,
+  importExternalSemanticIndex,
   importNativeSource,
   projectNativeImportToSource,
-  runNativeImporterAdapter
+  runNativeImporterAdapter,
+  summarizeNativeImportFeatureEvidence
 } from '../dist/index.js';
 
 const source = `
@@ -88,6 +90,13 @@ const semanticSidecars = nativeImportResults.map((imported) => createSemanticImp
 const sidecarDurationMs = performance.now() - sidecarStart;
 const sidecarOwnershipRegions = semanticSidecars.reduce((sum, sidecar) => sum + sidecar.ownershipRegions.length, 0);
 
+const featureEvidenceStart = performance.now();
+const featureEvidenceSummaries = nativeImportResults.map((imported) => summarizeNativeImportFeatureEvidence(imported.losses, {
+  evidence: imported.evidence
+}));
+const featureEvidenceDurationMs = performance.now() - featureEvidenceStart;
+const featureEvidencePolicyMatches = featureEvidenceSummaries.reduce((sum, summary) => sum + summary.total, 0);
+
 const projectionStart = performance.now();
 const nativeProjections = nativeImportResults.map((imported) => projectNativeImportToSource(imported));
 const projectionDurationMs = performance.now() - projectionStart;
@@ -126,6 +135,40 @@ const nativeTargetAdapterDurationMs = performance.now() - nativeTargetAdapterSta
 const nativeTargetAdapterBytes = nativeTargetAdapterCompiles.reduce((sum, result) => sum + result.output.length, 0);
 const nativeTargetAdapterSourceMaps = nativeTargetAdapterCompiles.reduce((sum, result) => sum + result.sourceMaps.length, 0);
 
+const externalSemanticStart = performance.now();
+const externalSemanticImports = [];
+for (let index = 0; index < 100; index += 1) {
+  externalSemanticImports.push(importExternalSemanticIndex({
+    format: index % 2 === 0 ? 'scip' : 'lsp',
+    language: index % 2 === 0 ? 'typescript' : 'python',
+    payload: index % 2 === 0
+      ? {
+        metadata: { project_root: '/bench' },
+        documents: [{
+          relative_path: `src/external-${index}.ts`,
+          language: 'typescript',
+          occurrences: [{
+            symbol: `scip-typescript npm bench 1.0.0 src/external-${index}.ts/ external${index}().`,
+            range: [0, 16, 24],
+            symbol_roles: 1
+          }]
+        }]
+      }
+      : {
+        uri: `file:///bench/src/external-${index}.py`,
+        languageId: 'python',
+        documentSymbols: [{
+          name: `external_${index}`,
+          kind: 12,
+          range: { start: { line: 0, character: 0 }, end: { line: 1, character: 0 } }
+        }]
+      }
+  }));
+}
+const externalSemanticDurationMs = performance.now() - externalSemanticStart;
+const externalSemanticSymbols = externalSemanticImports.reduce((sum, imported) => sum + imported.semanticIndex.symbols.length, 0);
+const externalSemanticMappings = externalSemanticImports.reduce((sum, imported) => sum + imported.summary.sourceMapMappings, 0);
+
 console.log(JSON.stringify({
   compiles: 250,
   bytes,
@@ -150,6 +193,8 @@ console.log(JSON.stringify({
   semanticSidecars: semanticSidecars.length,
   sidecarOwnershipRegions,
   sidecarDurationMs: Number(sidecarDurationMs.toFixed(2)),
+  featureEvidencePolicyMatches,
+  featureEvidenceDurationMs: Number(featureEvidenceDurationMs.toFixed(2)),
   nativeProjections: nativeProjections.length,
   projectionBytes,
   projectionDurationMs: Number(projectionDurationMs.toFixed(2)),
@@ -162,5 +207,9 @@ console.log(JSON.stringify({
   nativeTargetAdapterCompiles: nativeTargetAdapterCompiles.length,
   nativeTargetAdapterBytes,
   nativeTargetAdapterSourceMaps,
-  nativeTargetAdapterDurationMs: Number(nativeTargetAdapterDurationMs.toFixed(2))
+  nativeTargetAdapterDurationMs: Number(nativeTargetAdapterDurationMs.toFixed(2)),
+  externalSemanticImports: externalSemanticImports.length,
+  externalSemanticSymbols,
+  externalSemanticMappings,
+  externalSemanticDurationMs: Number(externalSemanticDurationMs.toFixed(2))
 }));

package/dist/index.d.ts

@@ -151,6 +151,49 @@ export interface NativeImportLossSummaryOptions {
   readonly semanticStatus?: string;
 }
 
+export type NativeImportFeatureEvidenceRisk = 'low' | 'medium' | 'high' | 'critical' | string;
+
+export interface NativeImportFeatureEvidencePolicy {
+  readonly kind: NativeImportKnownLossKind;
+  readonly category: NativeImportTaxonomyKind;
+  readonly risk: NativeImportFeatureEvidenceRisk;
+  readonly minimumReadiness: SemanticMergeReadiness;
+  readonly missingEvidenceReadiness: SemanticMergeReadiness;
+  readonly requiredEvidenceKeys: readonly string[];
+  readonly recommendedEvidenceKeys: readonly string[];
+  readonly notes: readonly string[];
+}
+
+export interface NativeImportFeatureEvidenceIssue {
+  readonly lossId: string;
+  readonly kind: NativeImportKnownLossKind;
+  readonly policyKind: NativeImportKnownLossKind;
+  readonly risk: NativeImportFeatureEvidenceRisk;
+  readonly category: NativeImportTaxonomyKind;
+  readonly readiness: SemanticMergeReadiness;
+  readonly missingRequiredEvidence: readonly string[];
+  readonly presentRequiredEvidence: readonly string[];
+  readonly presentRecommendedEvidence: readonly string[];
+  readonly evidenceIds: readonly string[];
+}
+
+export interface NativeImportFeatureEvidenceSummary {
+  readonly total: number;
+  readonly policyKinds: readonly NativeImportKnownLossKind[];
+  readonly byKind: Readonly<Record<string, number>>;
+  readonly byRisk: Readonly<Record<string, number>>;
+  readonly highestRisk: NativeImportFeatureEvidenceRisk;
+  readonly semanticMergeReadiness: SemanticMergeReadiness;
+  readonly missingRequiredEvidence: readonly {
+    readonly lossId: string;
+    readonly kind: NativeImportKnownLossKind;
+    readonly policyKind: NativeImportKnownLossKind;
+    readonly evidenceKey: string;
+  }[];
+  readonly issues: readonly NativeImportFeatureEvidenceIssue[];
+  readonly reasons: readonly string[];
+}
+
 export interface NativeImportLossSummary {
   readonly total: number;
   readonly hasLosses: boolean;
@@ -165,6 +208,7 @@ export interface NativeImportLossSummary {
   readonly reviewLossIds: readonly string[];
   readonly informationalLossIds: readonly string[];
   readonly failedEvidenceIds: readonly string[];
+  readonly featureEvidence: NativeImportFeatureEvidenceSummary;
   readonly parser?: string;
   readonly scanKind?: string;
   readonly semanticStatus?: string;
@@ -1023,6 +1067,63 @@ export type NativeSourceImportResult = LanguageImportResult & {
   readonly universalAst: FrontierUniversalAstEnvelope;
 };
 
+export type ExternalSemanticIndexFormat =
+  | 'frontier-semantic-index'
+  | 'scip'
+  | 'lsif'
+  | 'lsp'
+  | 'semanticdb'
+  | string;
+
+export interface ImportExternalSemanticIndexOptions {
+  readonly format?: ExternalSemanticIndexFormat;
+  readonly payload?: unknown;
+  readonly semanticIndex?: SemanticIndexRecord;
+  readonly id?: string;
+  readonly semanticIndexId?: string;
+  readonly universalAstId?: string;
+  readonly documentId?: string;
+  readonly documentName?: string;
+  readonly sourceMapId?: string;
+  readonly language?: FrontierSourceLanguage | string;
+  readonly sourcePath?: string;
+  readonly sourceHash?: string;
+  readonly projectRoot?: string;
+  readonly parser?: string;
+  readonly evidence?: readonly EvidenceRecord[];
+  readonly metadata?: Record<string, unknown>;
+  readonly universalAstMetadata?: Record<string, unknown>;
+}
+
+export interface ExternalSemanticIndexImportSummary {
+  readonly documents: number;
+  readonly symbols: number;
+  readonly occurrences: number;
+  readonly relations: number;
+  readonly facts: number;
+  readonly sourceMapMappings: number;
+  readonly losses: number;
+  readonly readiness: SemanticMergeReadiness;
+}
+
+export interface ExternalSemanticIndexImportResult {
+  readonly kind: 'frontier.lang.externalSemanticIndexImport';
+  readonly version: 1;
+  readonly id: string;
+  readonly format: ExternalSemanticIndexFormat;
+  readonly language?: FrontierSourceLanguage | string;
+  readonly sourcePath?: string;
+  readonly projectRoot?: string;
+  readonly semanticIndex: SemanticIndexRecord;
+  readonly universalAst: FrontierUniversalAstEnvelope;
+  readonly sourceMaps: readonly SourceMapRecord[];
+  readonly losses: readonly NativeAstLossRecord[];
+  readonly evidence: readonly EvidenceRecord[];
+  readonly readiness: NativeImportReadinessClassification;
+  readonly summary: ExternalSemanticIndexImportSummary;
+  readonly metadata: Record<string, unknown>;
+}
+
 export interface NativeImporterAdapterParseInput {
   readonly sourceText: string;
   readonly sourcePath?: string;
@@ -1428,7 +1529,9 @@ export declare const NativeImportLossKinds: readonly NativeImportKnownLossKind[]
 export declare const NativeImportRegionTaxonomyKinds: readonly NativeImportRegionTaxonomyKind[];
 export declare const ProjectionTargetLossClasses: readonly ProjectionTargetLossClass[];
 export declare const NativeImportReadinessBySeverity: Readonly<Record<NativeImportLossSummary['highestSeverity'], SemanticMergeReadiness>>;
+export declare const NativeImportFeatureEvidencePolicies: Readonly<Record<string, NativeImportFeatureEvidencePolicy>>;
 export declare const NativeImportLanguageProfiles: readonly NativeImportLanguageProfile[];
+export declare const ExternalSemanticIndexFormats: readonly ExternalSemanticIndexFormat[];
 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;
@@ -1438,6 +1541,8 @@ export declare function renderTargetAst(ast: FrontierTargetAst, target?: Frontie
 export declare function renderTargetAstWithSourceMap(ast: FrontierTargetAst, target?: FrontierCompileOptions['target'], options?: FrontierCompileEmitOptions): FrontierTargetSourceMapResult;
 export declare function emitForTargetWithSourceMap(document: FrontierLangDocument, target?: FrontierCompileOptions['target'], options?: FrontierCompileEmitOptions): FrontierTargetDocumentSourceMapResult;
 export declare function resolveCapabilityAdapters(document: FrontierLangDocument, target?: FrontierCompileOptions['target'], options?: { readonly platform?: string }): readonly CapabilityResolution[];
+export declare function getNativeImportFeatureEvidencePolicy(kind: NativeImportKnownLossKind | string): NativeImportFeatureEvidencePolicy | undefined;
+export declare function summarizeNativeImportFeatureEvidence(losses?: readonly NativeAstLossRecord[], options?: NativeImportLossSummaryOptions): NativeImportFeatureEvidenceSummary;
 export declare function summarizeNativeImportLosses(losses?: readonly NativeAstLossRecord[], options?: NativeImportLossSummaryOptions): NativeImportLossSummary;
 export declare function classifyNativeImportReadiness(losses?: readonly NativeAstLossRecord[], options?: NativeImportLossSummaryOptions): NativeImportReadinessClassification;
 export declare function classifyNativeImportRoundtripReadiness(importResult: NativeSourceImportResult | NativeProjectImportResult, options?: NativeImportRoundtripReadinessOptions): NativeImportRoundtripReadinessClassification;
@@ -1453,6 +1558,7 @@ export declare function createTreeSitterNativeImporterAdapter(options?: TreeSitt
 export declare function runNativeImporterAdapter(adapter: NativeImporterAdapter, input: RunNativeImporterAdapterOptions): Promise<NativeImporterAdapterImportResult>;
 export declare function runNativeTargetProjectionAdapter(adapter: NativeTargetProjectionAdapter, input: NativeTargetProjectionAdapterInput): NativeTargetProjectionResult;
 export declare function projectNativeImportToSource(importResult: NativeSourceImportResult | NativeProjectImportResult, options?: ProjectNativeImportToSourceOptions): NativeSourceProjectionResult;
+export declare function importExternalSemanticIndex(input: ImportExternalSemanticIndexOptions | SemanticIndexRecord): ExternalSemanticIndexImportResult;
 export declare function importNativeSource(input: ImportNativeSourceOptions): NativeSourceImportResult;
 export declare function diffNativeSources(input: DiffNativeSourcesOptions): NativeSourceChangeSet;
 export declare function diffNativeSourceImports(input: DiffNativeSourceImportsOptions): NativeSourceChangeSet;