@shapeshift-labs/frontier-lang-compiler 0.2.41 → 0.2.42

package/dist/native-source-maps.js

@@ -0,0 +1,260 @@
+import { createSourceMapRecord, validateSourceMapRecord } from '@shapeshift-labs/frontier-lang-kernel';
+import {
+  commonGeneratedTargetPath,
+  idFragment,
+  normalizeSourcePreservationLevel,
+  reserveUniqueId,
+  uniqueRecordsById,
+  uniqueStrings
+} from './native-import-utils.js';
+
+function inferSourceMapMappings(input) {
+  const semanticIndex = input.semanticIndex;
+  const nativeAst = input.nativeAst;
+  const nativeSource = input.nativeSource;
+  const evidenceIds = [
+    ...(semanticIndex?.evidence ?? []).map((record) => record.id),
+    ...(input.evidence ?? []).map((record) => record.id)
+  ];
+  const symbolsById = new Map((semanticIndex?.symbols ?? []).map((symbol) => [symbol.id, symbol]));
+
+  if (semanticIndex?.occurrences?.length) {
+    return semanticIndex.occurrences
+      .filter((occurrence) => occurrence.nativeAstNodeId || occurrence.span)
+      .map((occurrence) => {
+        const symbol = symbolsById.get(occurrence.symbolId);
+        const nativeNode = occurrence.nativeAstNodeId ? nativeAst?.nodes?.[occurrence.nativeAstNodeId] : undefined;
+        return {
+          id: `map_${idFragment(occurrence.id)}`,
+          nativeSourceId: nativeSource?.id,
+          nativeAstNodeId: occurrence.nativeAstNodeId,
+          semanticSymbolId: occurrence.symbolId,
+          semanticOccurrenceId: occurrence.id,
+          semanticNodeId: occurrence.semanticNodeId ?? symbol?.semanticNodeId,
+          sourceSpan: occurrence.span ?? nativeNode?.span,
+          evidenceIds,
+          lossIds: lossIdsForNativeNode(input.losses ?? nativeAst?.losses ?? [], occurrence.nativeAstNodeId),
+          ownershipRegionId: symbol?.metadata?.ownershipRegionId,
+          ownershipRegionKey: symbol?.metadata?.ownershipRegionKey,
+          ownershipRegionKind: symbol?.metadata?.ownershipRegionKind,
+          precision: occurrence.span || nativeNode?.span ? 'declaration' : 'unknown'
+        };
+      });
+  }
+
+  return Object.values(nativeAst?.nodes ?? {})
+    .filter((node) => node.span)
+    .map((node) => ({
+      id: `map_${idFragment(node.id)}`,
+      nativeSourceId: nativeSource?.id,
+      nativeAstNodeId: node.id,
+      sourceSpan: node.span,
+      evidenceIds,
+      lossIds: lossIdsForNativeNode(input.losses ?? nativeAst?.losses ?? [], node.id),
+      precision: 'line'
+    }));
+}
+
+function normalizeSourceMapMappings(mappings, context) {
+  if (mappings === undefined || mappings === null) return [];
+  if (!Array.isArray(mappings)) {
+    throw new Error('Source-map mappings must be an array');
+  }
+  const semanticIndex = context.semanticIndex;
+  const nativeAst = context.nativeAst;
+  const nativeSource = context.nativeSource;
+  const symbolsById = new Map((semanticIndex?.symbols ?? []).map((symbol) => [symbol.id, symbol]));
+  const occurrencesById = new Map((semanticIndex?.occurrences ?? []).map((occurrence) => [occurrence.id, occurrence]));
+  const evidenceIds = uniqueStrings([
+    ...(semanticIndex?.evidence ?? []).map((record) => record.id),
+    ...(context.evidence ?? []).map((record) => record.id),
+    ...(context.sourceMapEvidence ?? []).map((record) => record.id)
+  ]);
+  const usedMappingIds = new Set();
+  return mappings
+    .map((mapping, index) => {
+      if (!mapping || typeof mapping !== 'object') {
+        throw new Error(`Source-map mapping ${index + 1} must be an object`);
+      }
+      const occurrence = mapping.semanticOccurrenceId ? occurrencesById.get(mapping.semanticOccurrenceId) : undefined;
+      const symbol = mapping.semanticSymbolId ? symbolsById.get(mapping.semanticSymbolId) : occurrence ? symbolsById.get(occurrence.symbolId) : undefined;
+      const nativeAstNodeId = mapping.nativeAstNodeId ?? occurrence?.nativeAstNodeId;
+      const nativeNode = nativeAstNodeId ? nativeAst?.nodes?.[nativeAstNodeId] : undefined;
+      const sourceSpan = mapping.sourceSpan ?? occurrence?.span ?? nativeNode?.span;
+      const target = mapping.target ?? mapping.generatedSpan?.target ?? context.target;
+      const generatedSpan = normalizeGeneratedSpan(mapping.generatedSpan, target, context.targetPath, context.targetHash);
+      const mappingLossIds = normalizeReferenceIds(mapping.lossIds, lossIdsForNativeNode(context.losses ?? nativeAst?.losses ?? [], nativeAstNodeId));
+      const precision = normalizeSourceMapPrecision(mapping.precision, sourceSpan, generatedSpan);
+      if (
+        !nativeAstNodeId &&
+        !mapping.semanticNodeId &&
+        !mapping.semanticSymbolId &&
+        !mapping.semanticOccurrenceId &&
+        !sourceSpan &&
+        !generatedSpan &&
+        !mapping.generatedName
+      ) {
+        throw new Error(`Source-map mapping ${index + 1} must reference a native AST node, semantic node, symbol, occurrence, source span, or generated span`);
+      }
+      const normalizedMapping = {
+        ...mapping,
+        nativeSourceId: mapping.nativeSourceId ?? nativeSource?.id,
+        nativeAstNodeId,
+        semanticSymbolId: mapping.semanticSymbolId ?? occurrence?.symbolId,
+        semanticOccurrenceId: mapping.semanticOccurrenceId ?? occurrence?.id,
+        semanticNodeId: mapping.semanticNodeId ?? occurrence?.semanticNodeId ?? symbol?.semanticNodeId,
+        sourceSpan,
+        generatedSpan,
+        target,
+        evidenceIds: normalizeReferenceIds(mapping.evidenceIds, evidenceIds),
+        lossIds: mappingLossIds,
+        ownershipRegionId: mapping.ownershipRegionId ?? symbol?.metadata?.ownershipRegionId,
+        ownershipRegionKey: mapping.ownershipRegionKey ?? symbol?.metadata?.ownershipRegionKey,
+        ownershipRegionKind: mapping.ownershipRegionKind ?? symbol?.metadata?.ownershipRegionKind,
+        precision,
+        preservation: normalizeSourcePreservationLevel(mapping.preservation, {
+          precision,
+          lossIds: mappingLossIds,
+          losses: context.losses ?? nativeAst?.losses ?? [],
+          sourcePreservation: context.sourcePreservation
+        })
+      };
+      return {
+        ...normalizedMapping,
+        id: reserveUniqueId(sourceMapMappingBaseId(normalizedMapping, index), usedMappingIds)
+      };
+    });
+}
+
+function lossIdsForNativeNode(losses, nativeAstNodeId) {
+  if (!nativeAstNodeId) return [];
+  return (losses ?? [])
+    .filter((loss) => loss.nodeId === nativeAstNodeId)
+    .map((loss) => loss.id);
+}
+
+function normalizeSourceMaps(sourceMaps, context) {
+  if (sourceMaps === undefined || sourceMaps === null) return [];
+  if (!Array.isArray(sourceMaps)) {
+    throw new Error('Native import sourceMaps must be an array');
+  }
+  const usedSourceMapIds = new Set();
+  return sourceMaps.map((sourceMap, index) => {
+    if (!sourceMap || typeof sourceMap !== 'object') {
+      throw new Error(`Native import source map ${index + 1} must be an object`);
+    }
+    const id = reserveUniqueId(String(sourceMap.id ?? `${context.defaultSourceMapId}_${index + 1}`), usedSourceMapIds);
+    const evidence = uniqueRecordsById([...(sourceMap.evidence ?? []), ...(context.evidence ?? [])]);
+    const target = sourceMap.target ?? context.target;
+    const targetPath = sourceMap.targetPath ?? context.targetPath;
+    const targetHash = sourceMap.targetHash ?? context.targetHash;
+    const mappings = normalizeSourceMapMappings(sourceMap.mappings ?? [], {
+      ...context,
+      target,
+      targetPath,
+      targetHash,
+      sourceMapEvidence: evidence
+    });
+    const normalized = createSourceMapRecord({
+      ...sourceMap,
+      id,
+      sourcePath: sourceMap.sourcePath ?? context.sourcePath,
+      sourceHash: sourceMap.sourceHash ?? context.sourceHash,
+      target,
+      targetPath: targetPath ?? commonGeneratedTargetPath(mappings),
+      targetHash,
+      semanticIndexId: sourceMap.semanticIndexId ?? context.semanticIndex?.id,
+      nativeAstId: sourceMap.nativeAstId ?? context.nativeAst?.id,
+      nativeSourceId: sourceMap.nativeSourceId ?? context.nativeSource?.id,
+      mappings,
+      evidence
+    });
+    const issues = validateSourceMapRecord(normalized, {
+      document: context.document,
+      nativeSources: context.nativeSources,
+      nativeAst: context.nativeAst,
+      semanticIndex: context.semanticIndex,
+      losses: context.losses,
+      evidence: context.evidence
+    });
+    if (issues.length) {
+      throw new Error(`Invalid Frontier native source map ${normalized.id}: ${issues.join('; ')}`);
+    }
+    return normalized;
+  });
+}
+
+function normalizeGeneratedSpan(generatedSpan, target, targetPath, targetHash) {
+  if (!generatedSpan) return generatedSpan;
+  return {
+    ...generatedSpan,
+    target: generatedSpan.target ?? target,
+    targetPath: generatedSpan.targetPath ?? target?.emitPath ?? targetPath,
+    targetHash: generatedSpan.targetHash ?? targetHash
+  };
+}
+
+function normalizeSourceMapPrecision(value, sourceSpan, generatedSpan) {
+  const explicit = value === undefined || value === null ? '' : String(value).trim();
+  if (explicit) {
+    const normalized = explicit.toLowerCase();
+    if (normalized === 'exact') {
+      return hasExactSpan(sourceSpan) && hasExactSpan(generatedSpan)
+        ? 'exact'
+        : inferSourceMapPrecisionFromSpans(sourceSpan, generatedSpan);
+    }
+    if (normalized === 'declaration' || normalized === 'line' || normalized === 'estimated' || normalized === 'unknown') return normalized;
+    if (normalized === 'estimate' || normalized === 'approx' || normalized === 'approximate' || normalized === 'approximated') return 'estimated';
+    return explicit;
+  }
+  return inferSourceMapPrecisionFromSpans(sourceSpan, generatedSpan);
+}
+
+function inferSourceMapPrecisionFromSpans(sourceSpan, generatedSpan) {
+  if (hasExactSpan(sourceSpan) && hasExactSpan(generatedSpan)) return 'exact';
+  if (sourceSpan?.startLine && generatedSpan?.startLine) return 'line';
+  if (sourceSpan?.startLine) return 'declaration';
+  if (generatedSpan?.startLine) return 'line';
+  return 'unknown';
+}
+
+function hasExactSpan(span) {
+  return Boolean(span && (
+    (typeof span.start === 'number' && typeof span.end === 'number') ||
+    (
+      typeof span.startLine === 'number' &&
+      typeof span.startColumn === 'number' &&
+      typeof span.endLine === 'number' &&
+      typeof span.endColumn === 'number'
+    )
+  ));
+}
+
+function normalizeReferenceIds(value, fallback = []) {
+  if (value === undefined || value === null) return uniqueStrings(fallback);
+  return uniqueStrings(Array.isArray(value) ? value : [value]);
+}
+
+function sourceMapMappingBaseId(mapping, index) {
+  const explicit = mapping.id === undefined || mapping.id === null ? '' : String(mapping.id).trim();
+  if (explicit) return explicit;
+  const span = mapping.sourceSpan ?? mapping.generatedSpan;
+  const spanPart = span
+    ? `${span.path ?? span.targetPath ?? span.sourceId ?? 'span'}_${span.start ?? span.startLine ?? ''}_${span.end ?? span.endLine ?? ''}`
+    : undefined;
+  return `map_${idFragment([
+    mapping.nativeAstNodeId,
+    mapping.semanticOccurrenceId,
+    mapping.semanticSymbolId,
+    mapping.semanticNodeId,
+    spanPart,
+    index + 1
+  ].filter(Boolean).join('_'))}`;
+}
+
+export {
+  inferSourceMapMappings,
+  lossIdsForNativeNode,
+  normalizeSourceMapMappings,
+  normalizeSourceMaps
+};

package/dist/native-source-preservation-scanner.js

@@ -0,0 +1,266 @@
+import { hashSemanticValue } from '@shapeshift-labs/frontier-lang-kernel';
+import { idFragment, normalizeNativeLanguageId } from './native-import-utils.js';
+import { sourceLines } from './native-region-scanner-core.js';
+
+function scanPreservedSourceTokens(sourceText, input) {
+  const tokens = [];
+  const trivia = [];
+  const includeTokens = input.includeTokens !== false;
+  const includeTrivia = input.includeTrivia !== false;
+  const maxTokens = Number.isFinite(input.maxTokens) ? Math.max(0, input.maxTokens) : 20000;
+  const maxTrivia = Number.isFinite(input.maxTrivia) ? Math.max(0, input.maxTrivia) : 20000;
+  let offset = 0;
+  let line = 1;
+  let column = 1;
+  let truncated = false;
+  const push = (target, kind, text, start) => {
+    if ((target === tokens && !includeTokens) || (target === trivia && !includeTrivia)) return;
+    const max = target === tokens ? maxTokens : maxTrivia;
+    if (target.length >= max) {
+      truncated = true;
+      return;
+    }
+    target.push(preservedSourceSegment({
+      index: target.length,
+      kind,
+      text,
+      start,
+      end: { offset, line, column },
+      sourceHash: input.sourceHash,
+      sourcePath: input.sourcePath
+    }));
+  };
+  while (offset < sourceText.length) {
+    const start = { offset, line, column };
+    const char = sourceText[offset];
+    const next = sourceText[offset + 1];
+    if (char === '\r' || char === '\n') {
+      const text = char === '\r' && next === '\n' ? '\r\n' : char;
+      offset += text.length;
+      line += 1;
+      column = 1;
+      push(trivia, 'newline', text, start);
+      continue;
+    }
+    if (char === ' ' || char === '\t' || char === '\v' || char === '\f') {
+      let text = '';
+      while (offset < sourceText.length && /[ \t\v\f]/.test(sourceText[offset])) {
+        text += sourceText[offset];
+        offset += 1;
+        column += 1;
+      }
+      push(trivia, 'whitespace', text, start);
+      continue;
+    }
+    if (char === '/' && next === '/') {
+      let text = '';
+      while (offset < sourceText.length && sourceText[offset] !== '\n' && sourceText[offset] !== '\r') {
+        text += sourceText[offset];
+        offset += 1;
+        column += 1;
+      }
+      push(trivia, 'comment', text, start);
+      continue;
+    }
+    if (char === '/' && next === '*') {
+      let text = '';
+      while (offset < sourceText.length) {
+        const current = sourceText[offset];
+        text += current;
+        offset += 1;
+        if (current === '\n') {
+          line += 1;
+          column = 1;
+        } else {
+          column += 1;
+        }
+        if (current === '*' && sourceText[offset] === '/') {
+          text += '/';
+          offset += 1;
+          column += 1;
+          break;
+        }
+      }
+      push(trivia, 'comment', text, start);
+      continue;
+    }
+    if (char === '#' && isHashCommentLanguage(input.language)) {
+      let text = '';
+      while (offset < sourceText.length && sourceText[offset] !== '\n' && sourceText[offset] !== '\r') {
+        text += sourceText[offset];
+        offset += 1;
+        column += 1;
+      }
+      push(trivia, preservedHashLineKind(text), text, start);
+      continue;
+    }
+    if (char === '"' || char === '\'' || char === '`') {
+      const quote = char;
+      let text = char;
+      offset += 1;
+      column += 1;
+      let escaped = false;
+      while (offset < sourceText.length) {
+        const current = sourceText[offset];
+        text += current;
+        offset += 1;
+        if (current === '\n') {
+          line += 1;
+          column = 1;
+        } else {
+          column += 1;
+        }
+        if (escaped) {
+          escaped = false;
+        } else if (current === '\\') {
+          escaped = true;
+        } else if (current === quote) {
+          break;
+        }
+      }
+      push(tokens, 'string', text, start);
+      continue;
+    }
+    if (/[0-9]/.test(char)) {
+      let text = '';
+      while (offset < sourceText.length && /[0-9a-fA-F_xXoObBeE.+-]/.test(sourceText[offset])) {
+        text += sourceText[offset];
+        offset += 1;
+        column += 1;
+      }
+      push(tokens, 'number', text, start);
+      continue;
+    }
+    if (isIdentifierStart(char)) {
+      let text = '';
+      while (offset < sourceText.length && isIdentifierPart(sourceText[offset])) {
+        text += sourceText[offset];
+        offset += 1;
+        column += 1;
+      }
+      push(tokens, preservedKeywordSet.has(text) ? 'keyword' : 'identifier', text, start);
+      continue;
+    }
+    let text = char;
+    if (/[=+\-*/%&|^!<>?:.]/.test(char)) {
+      while (offset + text.length < sourceText.length && /[=+\-*/%&|^!<>?:.]/.test(sourceText[offset + text.length])) text += sourceText[offset + text.length];
+      offset += text.length;
+      column += text.length;
+      push(tokens, 'operator', text, start);
+    } else {
+      offset += 1;
+      column += 1;
+      push(tokens, /[()[\]{};,]/.test(char) ? 'punctuation' : 'unknown', text, start);
+    }
+  }
+  return { tokens, trivia, truncated };
+}
+
+function scanPreservedSourceDirectives(sourceText, input) {
+  const directives = [];
+  const maxDirectives = Number.isFinite(input.maxDirectives) ? Math.max(0, input.maxDirectives) : 20000;
+  let truncated = false;
+  let offset = 0;
+  for (const { line, number } of sourceLines(sourceText)) {
+    const trimmed = line.trim();
+    const directiveKind = preservedDirectiveKind(trimmed, input.language);
+    if (directiveKind) {
+      if (directives.length >= maxDirectives) {
+        truncated = true;
+        offset += line.length + 1;
+        continue;
+      }
+      const startColumn = Math.max(1, line.indexOf(trimmed) + 1);
+      directives.push({
+        id: `directive_${idFragment(input.sourcePath ?? input.language)}_${directives.length + 1}`,
+        kind: directiveKind,
+        text: trimmed,
+        textHash: hashSemanticValue(trimmed),
+        span: {
+          sourceId: input.sourceHash,
+          path: input.sourcePath,
+          start: offset + startColumn - 1,
+          end: offset + startColumn - 1 + trimmed.length,
+          startLine: number,
+          startColumn,
+          endLine: number,
+          endColumn: startColumn + trimmed.length
+        },
+        metadata: { language: input.language }
+      });
+    }
+    offset += line.length + 1;
+  }
+  return { directives, truncated };
+}
+
+function preservedSourceSegment(input) {
+  const id = `${input.kind}_${input.index + 1}_${idFragment(input.start.offset)}`;
+  return {
+    id,
+    kind: input.kind,
+    text: input.text,
+    textHash: hashSemanticValue(input.text),
+    span: {
+      sourceId: input.sourceHash,
+      path: input.sourcePath,
+      start: input.start.offset,
+      end: input.end.offset,
+      startLine: input.start.line,
+      startColumn: input.start.column,
+      endLine: input.end.line,
+      endColumn: input.end.column
+    }
+  };
+}
+
+function preservedDirectiveKind(trimmed, language) {
+  if (!trimmed) return undefined;
+  if (/^#\s*(include|define|if|ifdef|ifndef|elif|else|endif|pragma)\b/.test(trimmed)) return 'preprocessor';
+  if (/^#!\s*/.test(trimmed)) return 'shebang';
+  if (/^['"]use strict['"];?$/.test(trimmed)) return 'runtime-directive';
+  if (/^(import|export|package|module|namespace|use|using|from|require)\b/.test(trimmed)) return 'module-directive';
+  if (normalizeNativeLanguageId(language) === 'python' && /^from\s+\S+\s+import\b/.test(trimmed)) return 'module-directive';
+  return undefined;
+}
+
+function preservedHashLineKind(text) {
+  return preservedDirectiveKind(String(text).trim(), 'c') ? 'directive' : 'comment';
+}
+
+function isHashCommentLanguage(language) {
+  return ['python', 'ruby', 'shell', 'bash', 'zsh', 'r', 'perl', 'yaml', 'toml'].includes(normalizeNativeLanguageId(language));
+}
+
+function detectNewlineStyle(sourceText) {
+  const crlf = (sourceText.match(/\r\n/g) ?? []).length;
+  const normalized = sourceText.replace(/\r\n/g, '');
+  const lf = (normalized.match(/\n/g) ?? []).length;
+  const cr = (normalized.match(/\r/g) ?? []).length;
+  const kinds = [crlf ? 'crlf' : undefined, lf ? 'lf' : undefined, cr ? 'cr' : undefined].filter(Boolean);
+  if (!kinds.length) return 'none';
+  if (kinds.length > 1 || cr) return 'mixed';
+  return kinds[0];
+}
+
+const preservedKeywordSet = new Set([
+  'abstract', 'as', 'async', 'await', 'break', 'case', 'catch', 'class', 'const', 'continue', 'def', 'defer',
+  'do', 'else', 'enum', 'export', 'extends', 'extern', 'false', 'final', 'fn', 'for', 'from', 'func', 'function',
+  'if', 'impl', 'import', 'in', 'interface', 'let', 'match', 'mod', 'module', 'mut', 'namespace', 'new', 'nil',
+  'none', 'null', 'package', 'private', 'protected', 'pub', 'public', 'return', 'self', 'static', 'struct',
+  'switch', 'this', 'throw', 'trait', 'true', 'try', 'type', 'use', 'using', 'var', 'while', 'yield'
+]);
+
+function isIdentifierStart(char) {
+  return /[A-Za-z_$]/.test(char ?? '');
+}
+
+function isIdentifierPart(char) {
+  return /[A-Za-z0-9_$]/.test(char ?? '');
+}
+
+export {
+  detectNewlineStyle,
+  scanPreservedSourceDirectives,
+  scanPreservedSourceTokens
+};

package/dist/native-source-preservation-types.d.ts

@@ -0,0 +1,77 @@
+import type { FrontierSourceLanguage, SourceSpan } from '@shapeshift-labs/frontier-lang-kernel';
+
+export type NativeSourceTokenKind =
+  | 'identifier'
+  | 'keyword'
+  | 'number'
+  | 'string'
+  | 'operator'
+  | 'punctuation'
+  | 'comment'
+  | 'whitespace'
+  | 'newline'
+  | 'directive'
+  | 'unknown'
+  | string;
+
+export interface NativeSourcePreservedToken {
+  readonly id: string;
+  readonly kind: NativeSourceTokenKind;
+  readonly text?: string;
+  readonly textHash: string;
+  readonly span: SourceSpan;
+  readonly metadata?: Record<string, unknown>;
+}
+
+export interface NativeSourcePreservedDirective {
+  readonly id: string;
+  readonly kind: string;
+  readonly text?: string;
+  readonly textHash: string;
+  readonly span: SourceSpan;
+  readonly metadata?: Record<string, unknown>;
+}
+
+export interface NativeSourcePreservation {
+  readonly kind: 'frontier.lang.nativeSourcePreservation';
+  readonly version: 1;
+  readonly id: string;
+  readonly language: FrontierSourceLanguage | string;
+  readonly sourcePath?: string;
+  readonly sourceHash: string;
+  readonly sourceBytes: number;
+  readonly lineCount: number;
+  readonly newline: 'lf' | 'crlf' | 'mixed' | 'none';
+  readonly encoding: string;
+  readonly sourceText?: string;
+  readonly tokens: readonly NativeSourcePreservedToken[];
+  readonly trivia: readonly NativeSourcePreservedToken[];
+  readonly directives: readonly NativeSourcePreservedDirective[];
+  readonly summary: {
+    readonly tokens: number;
+    readonly trivia: number;
+    readonly directives: number;
+    readonly comments: number;
+    readonly whitespace: number;
+    readonly exactSourceAvailable: boolean;
+    readonly truncated: boolean;
+  };
+  readonly metadata?: Record<string, unknown>;
+}
+
+export interface CreateNativeSourcePreservationOptions {
+  readonly id?: string;
+  readonly language?: FrontierSourceLanguage | string;
+  readonly sourcePath?: string;
+  readonly sourceHash?: string;
+  readonly sourceText: string;
+  readonly encoding?: string;
+  readonly includeSourceText?: boolean;
+  readonly includeTokens?: boolean;
+  readonly includeTrivia?: boolean;
+  readonly includeDirectives?: boolean;
+  readonly maxTokens?: number;
+  readonly maxTrivia?: number;
+  readonly maxDirectives?: number;
+  readonly metadata?: Record<string, unknown>;
+}