@shapeshift-labs/frontier-lang-compiler 0.2.11 → 0.2.13

package/README.md

@@ -171,6 +171,9 @@ const project = await importNativeProject({
 console.log(imported.universalAst.sourceMaps.length);
 console.log(project.semanticIndex.symbols.length);
 console.log(imported.adapter.coverage.exactness);
+console.log(imported.adapter.coverage.capabilityEvidence.declared.exactness);
+console.log(imported.adapter.coverage.capabilityEvidence.observed.sourceRanges);
+console.log(imported.adapter.coverage.capabilityEvidence.gaps);
 console.log(imported.adapter.coverage.semanticCoverage.level);
 console.log(project.metadata.sourcePreservationSummary.total);
 ```
@@ -184,6 +187,8 @@ The built-in adapter factories are dependency-light wrappers for caller-owned pa
 
 Adapter summaries include a structured `coverage` record so merge queues can distinguish exact parser AST imports from declaration scans. The record declares exactness, parser token/trivia support, diagnostics support, source-range and generated-range support, and semantic coverage. Built-in wrappers normalize native AST/CST nodes and declaration-level semantic indexes; they do not claim resolved references, types, control flow, generated ranges, or token/trivia fidelity unless the host adapter supplies that evidence.
 
+Coverage records also keep declared, observed, and effective capability evidence separate. `coverage.capabilityEvidence.gaps` highlights missing exact AST, token/trivia, parser diagnostics, source range, generated range, reference, type, and control-flow evidence for the current adapter/import. `observedOnly` means the import produced evidence the adapter did not declare, while `declaredOnly` means the adapter declared support that this run did not exercise.
+
 ## 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

@@ -96,6 +96,10 @@ console.log(JSON.stringify({
   nativeImportDurationMs: Number(importDurationMs.toFixed(2)),
   coverageMatrixLanguages: coverageMatrix.summary.languages,
   coverageMatrixImports: coverageMatrix.summary.imports,
+  adapterCoverageSummaries: coverageMatrix.summary.adapterCoverage.total,
+  adapterCoverageSourceRanges: coverageMatrix.summary.adapterCoverage.effective.sourceRanges ?? 0,
+  adapterCoverageTokenGaps: coverageMatrix.summary.adapterCoverage.gaps.tokens ?? 0,
+  adapterCoverageReferenceGaps: coverageMatrix.summary.adapterCoverage.gaps.references ?? 0,
   coverageMatrixDurationMs: Number(matrixDurationMs.toFixed(2)),
   sourcePreservationRecords: preservationRecords.length,
   sourcePreservationTokens: preservationTokens,

package/dist/index.d.ts

@@ -118,6 +118,17 @@ export type NativeImportKnownLossKind =
   | 'targetProjectionLoss'
   | string;
 
+export type NativeImportRegionTaxonomyKind =
+  | 'symbol'
+  | 'declaration'
+  | 'import'
+  | 'body'
+  | 'call'
+  | 'type'
+  | 'effect'
+  | 'generatedOutput'
+  | string;
+
 export interface NativeImportLossSummaryOptions {
   readonly exactAst?: boolean;
   readonly evidence?: readonly EvidenceRecord[];
@@ -163,6 +174,28 @@ export interface NativeImportLanguageProfile {
   readonly notes: readonly string[];
 }
 
+export interface NativeImporterAdapterCoverageAggregate {
+  readonly total: number;
+  readonly declared: Readonly<Record<string, number>>;
+  readonly observed: Readonly<Record<string, number>>;
+  readonly effective: Readonly<Record<string, number>>;
+  readonly gaps: Readonly<Record<string, number>>;
+  readonly declaredOnly: Readonly<Record<string, number>>;
+  readonly observedOnly: Readonly<Record<string, number>>;
+  readonly summaries: readonly {
+    readonly adapterId?: string;
+    readonly language?: FrontierSourceLanguage | string;
+    readonly parser?: string;
+    readonly exactness?: NativeImporterAdapterExactness;
+    readonly declared: readonly string[];
+    readonly observed: readonly string[];
+    readonly effective: readonly string[];
+    readonly gaps: readonly string[];
+    readonly declaredOnly: readonly string[];
+    readonly observedOnly: readonly string[];
+  }[];
+}
+
 export interface NativeImportCoverageLanguage {
   readonly language: FrontierSourceLanguage;
   readonly aliases: readonly string[];
@@ -173,6 +206,7 @@ export interface NativeImportCoverageLanguage {
   readonly knownLossKinds: readonly NativeImportKnownLossKind[];
   readonly defaultReadiness: SemanticMergeReadiness;
   readonly notes: readonly string[];
+  readonly adapterCoverage: NativeImporterAdapterCoverageAggregate;
   readonly imports: {
     readonly total: number;
     readonly parsers: readonly string[];
@@ -203,6 +237,7 @@ export interface NativeImportCoverageMatrix {
     readonly losses: number;
     readonly byReadiness: Readonly<Record<string, number>>;
     readonly lossKinds: Readonly<Record<string, number>>;
+    readonly adapterCoverage: NativeImporterAdapterCoverageAggregate;
   };
   readonly metadata: {
     readonly compileTargets: readonly FrontierCompileTarget[];
@@ -217,6 +252,167 @@ export interface NativeImportCoverageMatrixOptions {
   readonly generatedAt?: number;
 }
 
+export interface NativeImportContractSource {
+  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 patchId?: string;
+  readonly sourceMapIds: readonly string[];
+  readonly sourceMapMappings: number;
+  readonly symbolCount: number;
+  readonly lossCount: number;
+  readonly evidenceCount: number;
+  readonly readiness?: SemanticMergeReadiness;
+}
+
+export interface NativeImportSourcePreservationRecordSummary {
+  readonly id?: string;
+  readonly language?: FrontierSourceLanguage | string;
+  readonly sourcePath?: string;
+  readonly sourceHash?: string;
+  readonly sourceBytes?: number;
+  readonly lineCount?: number;
+  readonly newline?: string;
+  readonly encoding?: string;
+  readonly exactSourceAvailable: boolean;
+  readonly tokens: number;
+  readonly trivia: number;
+  readonly directives: number;
+  readonly comments: number;
+  readonly whitespace: number;
+  readonly truncated: boolean;
+}
+
+export interface NativeImportSourcePreservationContract {
+  readonly total: number;
+  readonly ids: readonly string[];
+  readonly sourcePaths: readonly string[];
+  readonly sourceHashes: readonly string[];
+  readonly exactSourceAvailable: number;
+  readonly sourceBytes: number;
+  readonly lineCount: number;
+  readonly tokens: number;
+  readonly trivia: number;
+  readonly directives: number;
+  readonly comments: number;
+  readonly whitespace: number;
+  readonly truncated: boolean;
+  readonly records: readonly NativeImportSourcePreservationRecordSummary[];
+}
+
+export interface NativeImportAdapterCoverageRecordSummary {
+  readonly adapterId?: string;
+  readonly adapterVersion?: string;
+  readonly parser?: string;
+  readonly capabilities: readonly string[];
+  readonly supportedExtensions: readonly string[];
+  readonly exactness?: NativeImporterAdapterExactness;
+  readonly exactAst: boolean;
+  readonly tokens: boolean;
+  readonly trivia: boolean;
+  readonly diagnostics: boolean;
+  readonly sourceRanges: boolean;
+  readonly generatedRanges: boolean;
+  readonly semanticCoverage?: NativeImporterAdapterSemanticCoverage;
+  readonly observed?: NativeImporterAdapterCoverageObserved;
+  readonly notes: readonly string[];
+}
+
+export interface NativeImportAdapterCoverageContract {
+  readonly total: number;
+  readonly adapterIds: readonly string[];
+  readonly parsers: readonly string[];
+  readonly exactness: readonly string[];
+  readonly exactAst: number;
+  readonly tokens: number;
+  readonly trivia: number;
+  readonly diagnostics: number;
+  readonly sourceRanges: number;
+  readonly generatedRanges: number;
+  readonly semanticCoverageLevels: readonly string[];
+  readonly observed: NativeImporterAdapterCoverageObserved;
+  readonly records: readonly NativeImportAdapterCoverageRecordSummary[];
+}
+
+export interface NativeImportRegionSummary {
+  readonly total: number;
+  readonly ids: readonly string[];
+  readonly keys: readonly string[];
+  readonly sourcePaths: readonly string[];
+  readonly byKind: Readonly<Record<string, number>>;
+  readonly byGranularity: Readonly<Record<string, number>>;
+  readonly byPrecision: Readonly<Record<string, number>>;
+  readonly byLanguage: Readonly<Record<string, number>>;
+  readonly symbolIds: readonly string[];
+  readonly taxonomy: SemanticImportRegionTaxonomySummary;
+}
+
+export interface NativeImportSourceMapSummary {
+  readonly total: number;
+  readonly ids: readonly string[];
+  readonly mappingCount: number;
+  readonly sourcePaths: readonly string[];
+  readonly targetPaths: readonly string[];
+  readonly byPrecision: Readonly<Record<string, number>>;
+  readonly sourceRangeMappings: number;
+  readonly generatedRangeMappings: number;
+}
+
+export interface NativeImportReadinessContract {
+  readonly semanticMergeReadiness: SemanticMergeReadiness;
+  readonly severityReadiness: SemanticMergeReadiness;
+  readonly reasons: readonly string[];
+  readonly failedEvidenceIds: readonly string[];
+  readonly blockingLossIds: readonly string[];
+  readonly reviewLossIds: readonly string[];
+  readonly informationalLossIds: readonly string[];
+}
+
+export interface NativeImportResultContract {
+  readonly kind: 'frontier.lang.nativeImportResultContract';
+  readonly version: 1;
+  readonly importResultId?: string;
+  readonly language?: FrontierSourceLanguage | 'mixed' | string;
+  readonly sourcePath?: string;
+  readonly sourceHash?: string;
+  readonly sourceCount: number;
+  readonly sources: readonly NativeImportContractSource[];
+  readonly ids: {
+    readonly nativeSourceId?: string;
+    readonly nativeAstId?: string;
+    readonly semanticIndexId?: string;
+    readonly universalAstId?: string;
+    readonly patchId?: string;
+    readonly sourceMapIds: readonly string[];
+    readonly semanticSidecarIds: readonly string[];
+  };
+  readonly sourcePreservation: NativeImportSourcePreservationContract;
+  readonly adapterCoverage: NativeImportAdapterCoverageContract;
+  readonly lossSummary: NativeImportLossSummary;
+  readonly regions: NativeImportRegionSummary;
+  readonly sourceMaps: NativeImportSourceMapSummary;
+  readonly readiness: NativeImportReadinessContract;
+  readonly evidence: {
+    readonly total: number;
+    readonly failed: readonly string[];
+    readonly ids: readonly string[];
+  };
+  readonly metadata: Record<string, unknown>;
+}
+
+export interface NativeImportResultContractOptions extends SemanticImportSidecarOptions {
+  readonly lossSummary?: NativeImportLossSummary;
+  readonly semanticSidecarIds?: readonly string[] | string;
+  readonly sidecarIds?: readonly string[] | string;
+  readonly sidecarId?: string;
+}
+
 export type NativeSourceTokenKind =
   | 'identifier'
   | 'keyword'
@@ -296,8 +492,10 @@ export interface CreateNativeSourcePreservationOptions {
 export interface SemanticImportOwnershipRegion {
   readonly id: string;
   readonly key: string;
+  readonly regionKind?: NativeImportRegionTaxonomyKind;
   readonly granularity: 'symbol' | string;
   readonly language?: FrontierSourceLanguage | string;
+  readonly documentId?: string;
   readonly sourcePath?: string;
   readonly sourceHash?: string;
   readonly symbolId?: string;
@@ -307,6 +505,7 @@ export interface SemanticImportOwnershipRegion {
   readonly sourceSpan?: SourceSpan;
   readonly precision?: 'exact' | 'declaration' | 'line' | 'estimated' | 'unknown' | string;
   readonly mergePolicy?: string;
+  readonly metadata?: Record<string, unknown>;
 }
 
 export interface SemanticImportSidecarSymbol {
@@ -321,9 +520,18 @@ export interface SemanticImportSidecarSymbol {
   readonly signatureHash?: string;
   readonly ownershipRegionId: string;
   readonly ownershipKey: string;
+  readonly ownershipRegionKind?: NativeImportRegionTaxonomyKind;
   readonly readiness: SemanticMergeReadiness;
 }
 
+export interface SemanticImportRegionTaxonomySummary {
+  readonly kinds: readonly NativeImportRegionTaxonomyKind[];
+  readonly presentKinds: readonly NativeImportRegionTaxonomyKind[];
+  readonly byKind: Readonly<Record<string, number>>;
+  readonly keys: readonly string[];
+  readonly keysByKind: Readonly<Record<string, readonly string[]>>;
+}
+
 export interface SemanticImportPatchHint {
   readonly id: string;
   readonly kind: 'source-region-patch' | string;
@@ -357,6 +565,7 @@ export interface SemanticImportSidecarImportEntry {
   readonly sourceMapMappingCount: number;
   readonly readiness: SemanticMergeReadiness;
   readonly emptySemanticIndex: boolean;
+  readonly regionTaxonomy?: SemanticImportRegionTaxonomySummary;
 }
 
 export interface SemanticImportSidecar {
@@ -390,6 +599,7 @@ export interface SemanticImportSidecar {
     readonly blockingLossIds: readonly string[];
     readonly reviewLossIds: readonly string[];
   };
+  readonly regionTaxonomy: SemanticImportRegionTaxonomySummary;
   readonly evidence: {
     readonly total: number;
     readonly failed: readonly string[];
@@ -399,6 +609,7 @@ export interface SemanticImportSidecar {
     readonly imports: number;
     readonly symbols: number;
     readonly ownershipRegions: number;
+    readonly regionKinds: number;
     readonly sourceMapMappings: number;
     readonly readiness: SemanticMergeReadiness;
     readonly emptySemanticIndex: boolean;
@@ -431,14 +642,97 @@ export interface NativeImporterAdapterSemanticCoverage {
   readonly controlFlow: boolean;
 }
 
+export interface NativeImporterAdapterCoverageSnapshot {
+  readonly exactness: NativeImporterAdapterExactness;
+  readonly exactAst: boolean;
+  readonly tokens: boolean;
+  readonly trivia: boolean;
+  readonly diagnostics: boolean;
+  readonly sourceRanges: boolean;
+  readonly generatedRanges: boolean;
+  readonly semanticCoverage: NativeImporterAdapterSemanticCoverage;
+}
+
 export interface NativeImporterAdapterCoverageObserved {
+  readonly exactness?: NativeImporterAdapterExactness;
+  readonly exactAst?: boolean;
+  readonly tokens?: boolean;
+  readonly tokenCount?: number;
+  readonly trivia?: boolean;
+  readonly triviaCount?: number;
   readonly diagnostics: number;
+  readonly parserDiagnostics?: number;
+  readonly diagnosticErrors?: number;
+  readonly diagnosticWarnings?: number;
+  readonly diagnosticInfos?: number;
   readonly losses: number;
   readonly nativeAstNodes: number;
   readonly semanticSymbols: number;
+  readonly semanticReferences?: number;
+  readonly semanticTypes?: number;
+  readonly semanticControlFlow?: number;
+  readonly references?: boolean;
+  readonly types?: boolean;
+  readonly controlFlow?: boolean;
   readonly sourceMapMappings: number;
   readonly sourceRanges: boolean;
+  readonly sourceRangeNodes?: number;
+  readonly sourceRangeMappings?: number;
   readonly generatedRanges: boolean;
+  readonly generatedRangeMappings?: number;
+  readonly semanticCoverage?: NativeImporterAdapterSemanticCoverage;
+}
+
+export interface NativeImporterAdapterCoverageCapabilityRow {
+  readonly capability: string;
+  readonly declared: boolean;
+  readonly observed: boolean;
+  readonly effective: boolean;
+  readonly count: number;
+  readonly status: 'declared-and-observed' | 'declared-unobserved' | 'observed-undeclared' | 'absent';
+}
+
+export interface NativeImporterAdapterCoverageCapabilityEvidence {
+  readonly declared: NativeImporterAdapterCoverageSnapshot;
+  readonly observed: NativeImporterAdapterCoverageObserved;
+  readonly effective: NativeImporterAdapterCoverageSnapshot;
+  readonly capabilities: readonly NativeImporterAdapterCoverageCapabilityRow[];
+  readonly gaps: readonly string[];
+  readonly declaredOnly: readonly string[];
+  readonly observedOnly: readonly string[];
+  readonly parserDiagnostics: {
+    readonly declared: boolean;
+    readonly observed: boolean;
+    readonly count: number;
+    readonly errors: number;
+    readonly warnings: number;
+    readonly infos: number;
+  };
+  readonly sourceRanges: {
+    readonly declared: boolean;
+    readonly observed: boolean;
+    readonly nativeAstNodes: number;
+    readonly sourceRangeNodes: number;
+    readonly sourceMapMappings: number;
+    readonly sourceRangeMappings: number;
+    readonly generatedRangeMappings: number;
+  };
+  readonly tokensTrivia: {
+    readonly tokens: { readonly declared: boolean; readonly observed: boolean; readonly count: number };
+    readonly trivia: { readonly declared: boolean; readonly observed: boolean; readonly count: number };
+  };
+  readonly semantic: {
+    readonly level: {
+      readonly declared: string;
+      readonly observed: string;
+      readonly effective: string;
+    };
+    readonly declarations: NativeImporterAdapterCoverageCapabilityRow;
+    readonly symbols: NativeImporterAdapterCoverageCapabilityRow;
+    readonly references: NativeImporterAdapterCoverageCapabilityRow;
+    readonly types: NativeImporterAdapterCoverageCapabilityRow;
+    readonly controlFlow: NativeImporterAdapterCoverageCapabilityRow;
+  };
 }
 
 export interface NativeImporterAdapterCoverageSummary {
@@ -451,11 +745,13 @@ export interface NativeImporterAdapterCoverageSummary {
   readonly generatedRanges: boolean;
   readonly semanticCoverage: NativeImporterAdapterSemanticCoverage;
   readonly notes: readonly string[];
+  readonly declared?: NativeImporterAdapterCoverageSnapshot;
   readonly observed?: NativeImporterAdapterCoverageObserved;
+  readonly capabilityEvidence?: NativeImporterAdapterCoverageCapabilityEvidence;
 }
 
 export type NativeImporterAdapterCoverageInput =
-  Omit<Partial<NativeImporterAdapterCoverageSummary>, 'semanticCoverage' | 'observed'> & {
+  Omit<Partial<NativeImporterAdapterCoverageSummary>, 'semanticCoverage' | 'observed' | 'declared' | 'capabilityEvidence'> & {
     readonly semanticCoverage?: Partial<NativeImporterAdapterSemanticCoverage>;
     readonly observed?: Partial<NativeImporterAdapterCoverageObserved>;
   };
@@ -784,6 +1080,7 @@ export declare const FrontierCompileTargets: readonly FrontierCompileTarget[];
 export declare const NativeImportRoundtripReadinessStatuses: readonly NativeImportRoundtripReadinessStatus[];
 export declare const NativeImportTaxonomyKinds: readonly NativeImportTaxonomyKind[];
 export declare const NativeImportLossKinds: readonly NativeImportKnownLossKind[];
+export declare const NativeImportRegionTaxonomyKinds: readonly NativeImportRegionTaxonomyKind[];
 export declare const NativeImportReadinessBySeverity: Readonly<Record<NativeImportLossSummary['highestSeverity'], SemanticMergeReadiness>>;
 export declare const NativeImportLanguageProfiles: readonly NativeImportLanguageProfile[];
 export declare function normalizeCompileTarget(target?: string): FrontierCompileTarget;
@@ -798,6 +1095,7 @@ export declare function classifyNativeImportRoundtripReadiness(importResult: Nat
 export declare function createNativeImportCoverageMatrix(options?: NativeImportCoverageMatrixOptions): NativeImportCoverageMatrix;
 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;
 export declare function createEstreeNativeImporterAdapter(options?: JavaScriptNativeImporterAdapterOptions): NativeImporterAdapter;
 export declare function createBabelNativeImporterAdapter(options?: JavaScriptNativeImporterAdapterOptions): NativeImporterAdapter;
 export declare function createTypeScriptCompilerNativeImporterAdapter(options?: TypeScriptCompilerNativeImporterAdapterOptions): NativeImporterAdapter;