@shapeshift-labs/frontier-lang-compiler 0.2.26 → 0.2.28

package/README.md

@@ -332,7 +332,9 @@ Use injected parser adapters when a real language parser is available but should
 ```js
 import {
   createBabelNativeImporterAdapter,
+  createClangAstNativeImporterAdapter,
   createPythonAstNativeImporterAdapter,
+  createRustSynNativeImporterAdapter,
   importNativeProject,
   runNativeImporterAdapter
 } from '@shapeshift-labs/frontier-lang-compiler';
@@ -343,6 +345,15 @@ const babelAdapter = createBabelNativeImporterAdapter({
 const pythonAstAdapter = createPythonAstNativeImporterAdapter({
   parserModule: hostPythonAstParser
 });
+const rustSynAdapter = createRustSynNativeImporterAdapter({
+  parserModule: hostRustSynParser,
+  rustEdition: '2021'
+});
+const clangAstAdapter = createClangAstNativeImporterAdapter({
+  parserModule: hostClangJsonParser,
+  cStandard: 'c11',
+  compileFlags: ['-std=c11']
+});
 
 const imported = await runNativeImporterAdapter(babelAdapter, {
   sourcePath: 'src/todo.ts',
@@ -351,10 +362,12 @@ const imported = await runNativeImporterAdapter(babelAdapter, {
 
 const project = await importNativeProject({
   projectRoot: 'src',
-  adapters: [babelAdapter, pythonAstAdapter],
+  adapters: [babelAdapter, pythonAstAdapter, rustSynAdapter, clangAstAdapter],
   sources: [
     { language: 'typescript', adapter: babelAdapter.id, sourcePath: 'src/todo.ts', sourceText },
-    { language: 'python', adapter: pythonAstAdapter.id, sourcePath: 'tools/todo.py', sourceText: pythonSource }
+    { language: 'python', adapter: pythonAstAdapter.id, sourcePath: 'tools/todo.py', sourceText: pythonSource },
+    { language: 'rust', adapter: rustSynAdapter.id, sourcePath: 'src/todo.rs', sourceText: rustSource },
+    { language: 'c', adapter: clangAstAdapter.id, sourcePath: 'native/todo.c', sourceText: cSource }
   ]
 });
 
@@ -374,6 +387,8 @@ The built-in adapter factories are dependency-light wrappers for caller-owned pa
 - `createBabelNativeImporterAdapter`
 - `createTypeScriptCompilerNativeImporterAdapter`
 - `createPythonAstNativeImporterAdapter`
+- `createRustSynNativeImporterAdapter`
+- `createClangAstNativeImporterAdapter`
 - `createTreeSitterNativeImporterAdapter`
 
 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.

package/bench/smoke.mjs

@@ -2,12 +2,14 @@ import { performance } from 'node:perf_hooks';
 import {
   compileNativeSource,
   compileFrontierSource,
+  createClangAstNativeImporterAdapter,
   createEstreeNativeImporterAdapter,
   createNativeImportCoverageMatrix,
   createNativeParserAstFormatMatrix,
   createProjectionTargetLossMatrix,
   createNativeSourcePreservation,
   createPythonAstNativeImporterAdapter,
+  createRustSynNativeImporterAdapter,
   createSemanticImportSidecar,
   diffNativeSources,
   importExternalSemanticIndex,
@@ -78,7 +80,7 @@ const matrixDurationMs = performance.now() - matrixStart;
 const parserFormatMatrixStart = performance.now();
 const parserFormatMatrix = createNativeParserAstFormatMatrix({
   imports: nativeImportResults,
-  adapters: [estreeAdapter, createPythonAstNativeImporterAdapter()]
+  adapters: [estreeAdapter, createPythonAstNativeImporterAdapter(), createRustSynNativeImporterAdapter(), createClangAstNativeImporterAdapter()]
 });
 const parserFormatMatrixDurationMs = performance.now() - parserFormatMatrixStart;
 

package/dist/index.d.ts

@@ -1388,6 +1388,53 @@ export interface PythonAstNativeImporterAdapterOptions {
   readonly maxNodes?: number;
 }
 
+export interface RustSynNativeImporterAdapterOptions {
+  readonly id?: string;
+  readonly language?: FrontierSourceLanguage;
+  readonly parser?: string;
+  readonly version?: string;
+  readonly capabilities?: readonly string[];
+  readonly coverage?: NativeImporterAdapterCoverageInput;
+  readonly supportedExtensions?: readonly string[];
+  readonly diagnostics?: readonly NativeImporterAdapterDiagnostic[];
+  readonly ast?: unknown;
+  readonly file?: unknown;
+  readonly sourceFile?: unknown;
+  readonly parse?: (sourceText: string, options: Record<string, unknown>) => unknown;
+  readonly parserModule?: { readonly parse: (sourceText: string, options: Record<string, unknown>) => unknown };
+  readonly rustSyn?: { readonly parse: (sourceText: string, options: Record<string, unknown>) => unknown };
+  readonly syn?: { readonly parse: (sourceText: string, options: Record<string, unknown>) => unknown };
+  readonly parserOptions?: Record<string, unknown>;
+  readonly rustEdition?: '2015' | '2018' | '2021' | '2024' | string;
+  readonly includeAttributes?: boolean;
+  readonly maxNodes?: number;
+}
+
+export interface ClangAstNativeImporterAdapterOptions {
+  readonly id?: string;
+  readonly language?: FrontierSourceLanguage;
+  readonly parser?: string;
+  readonly version?: string;
+  readonly capabilities?: readonly string[];
+  readonly coverage?: NativeImporterAdapterCoverageInput;
+  readonly supportedExtensions?: readonly string[];
+  readonly diagnostics?: readonly NativeImporterAdapterDiagnostic[];
+  readonly ast?: unknown;
+  readonly translationUnit?: unknown;
+  readonly tu?: unknown;
+  readonly parse?: (sourceText: string, options: Record<string, unknown>) => unknown;
+  readonly parserModule?: { readonly parse: (sourceText: string, options: Record<string, unknown>) => unknown };
+  readonly clang?: { readonly parse: (sourceText: string, options: Record<string, unknown>) => unknown };
+  readonly libclang?: { readonly parse: (sourceText: string, options: Record<string, unknown>) => unknown };
+  readonly parserOptions?: Record<string, unknown>;
+  readonly cStandard?: 'c89' | 'c99' | 'c11' | 'c17' | 'c23' | 'gnu11' | 'gnu17' | 'gnu23' | string;
+  readonly compileFlags?: readonly string[];
+  readonly includeSystemHeaders?: boolean;
+  readonly preprocessorRecords?: readonly unknown[] | { readonly records?: readonly unknown[] };
+  readonly includeGraph?: unknown;
+  readonly maxNodes?: number;
+}
+
 export interface TreeSitterNativeImporterAdapterOptions {
   readonly id?: string;
   readonly language?: FrontierSourceLanguage;
@@ -1758,6 +1805,8 @@ export declare function createEstreeNativeImporterAdapter(options?: JavaScriptNa
 export declare function createBabelNativeImporterAdapter(options?: JavaScriptNativeImporterAdapterOptions): NativeImporterAdapter;
 export declare function createTypeScriptCompilerNativeImporterAdapter(options?: TypeScriptCompilerNativeImporterAdapterOptions): NativeImporterAdapter;
 export declare function createPythonAstNativeImporterAdapter(options?: PythonAstNativeImporterAdapterOptions): NativeImporterAdapter;
+export declare function createRustSynNativeImporterAdapter(options?: RustSynNativeImporterAdapterOptions): NativeImporterAdapter;
+export declare function createClangAstNativeImporterAdapter(options?: ClangAstNativeImporterAdapterOptions): NativeImporterAdapter;
 export declare function createTreeSitterNativeImporterAdapter(options?: TreeSitterNativeImporterAdapterOptions): NativeImporterAdapter;
 export declare function runNativeImporterAdapter(adapter: NativeImporterAdapter, input: RunNativeImporterAdapterOptions): Promise<NativeImporterAdapterImportResult>;
 export declare function runNativeTargetProjectionAdapter(adapter: NativeTargetProjectionAdapter, input: NativeTargetProjectionAdapterInput): NativeTargetProjectionResult;

package/dist/index.js

@@ -378,6 +378,43 @@ export const NativeParserAstFormatProfiles = Object.freeze([
     supportsErrorRecovery: false,
     notes: ['Python stdlib AST exposes versioned abstract grammar and source locations, but not formatting trivia.']
   }),
+  nativeParserAstFormatProfile('rust-syn', {
+    aliases: ['syn'],
+    kind: 'abstract-ast',
+    languages: ['rust'],
+    parserAdapters: ['syn', 'rust-syn'],
+    exactness: 'exact-parser-ast',
+    sourceRangeModel: 'proc-macro2-span',
+    preservesTokens: false,
+    preservesTrivia: false,
+    supportsErrorRecovery: false,
+    notes: ['syn parses Rust token streams into an abstract syntax tree; macro expansion, name resolution, type checking, and lossless trivia remain host-owned evidence.']
+  }),
+  nativeParserAstFormatProfile('rust-analyzer-rowan', {
+    aliases: ['rowan', 'rust-analyzer'],
+    kind: 'concrete-syntax-tree',
+    languages: ['rust'],
+    parserAdapters: ['rust-analyzer-rowan'],
+    exactness: 'parser-tree',
+    sourceRangeModel: 'text-range',
+    preservesTokens: true,
+    preservesTrivia: true,
+    supportsIncremental: true,
+    supportsErrorRecovery: true,
+    notes: ['rust-analyzer uses rowan-backed concrete syntax trees with AST wrappers; semantic richness still depends on host analysis evidence.']
+  }),
+  nativeParserAstFormatProfile('clang-ast-json', {
+    aliases: ['clang', 'libclang', 'clang-json', 'clang-ast-dump-json'],
+    kind: 'compiler-ast',
+    languages: ['c', 'cpp'],
+    parserAdapters: ['clang', 'libclang', 'clang-ast-json'],
+    exactness: 'exact-parser-ast',
+    sourceRangeModel: 'clang-loc-range',
+    preservesTokens: false,
+    preservesTrivia: false,
+    supportsErrorRecovery: false,
+    notes: ['Clang JSON AST dumps expose compiler AST declarations and source ranges after preprocessing; compile commands, macros, inactive branches, type checking, and lossless formatting remain host-owned evidence.']
+  }),
   nativeParserAstFormatProfile('tree-sitter', {
     kind: 'concrete-syntax-tree',
     languages: ['mixed'],
@@ -2631,6 +2668,119 @@ export function createPythonAstNativeImporterAdapter(options = {}) {
   };
 }
 
+export function createRustSynNativeImporterAdapter(options = {}) {
+  return {
+    id: options.id ?? 'frontier.rust-syn-native-importer',
+    language: options.language ?? 'rust',
+    parser: options.parser ?? 'syn',
+    version: options.version,
+    capabilities: uniqueStrings(['nativeAst', 'semanticIndex', 'sourceMaps', 'diagnostics', ...(options.capabilities ?? [])]),
+    coverage: nativeImporterAdapterCoverage({
+      exactness: 'exact-parser-ast',
+      exactAst: true,
+      tokens: false,
+      trivia: false,
+      diagnostics: true,
+      sourceRanges: false,
+      generatedRanges: false,
+      semanticCoverage: declarationSemanticCoverage(),
+      notes: [
+        'Normalizes caller-owned syn-shaped Rust ASTs into native AST nodes and declaration-level semantic index records.',
+        'syn does not expand macros, resolve names, type-check, or preserve full concrete syntax/trivia; attach rust-analyzer/rustc evidence for those claims.'
+      ]
+    }, options.coverage),
+    supportedExtensions: options.supportedExtensions ?? ['.rs'],
+    diagnostics: options.diagnostics,
+    parse(input) {
+      const parsed = input.options?.ast
+        ?? input.options?.nativeAst
+        ?? input.options?.file
+        ?? input.options?.sourceFile
+        ?? options.ast
+        ?? options.file
+        ?? options.sourceFile
+        ?? parseRustSynSource(input, options);
+      const root = rustSynAstRoot(parsed);
+      if (!root) {
+        return missingInjectedParserResult(input, {
+          parser: options.parser ?? 'syn',
+          adapterId: options.id ?? 'frontier.rust-syn-native-importer',
+          message: 'createRustSynNativeImporterAdapter requires an injected syn-shaped AST object, parserModule.parse function, parse function, or adapterOptions.ast.'
+        });
+      }
+      const parseDiagnostics = normalizeParserErrors(parsed?.errors ?? parsed?.diagnostics, input, {
+        parser: options.parser ?? 'syn'
+      });
+      return createNativeImportFromRustSyn(root, input, {
+        parser: options.parser ?? 'syn',
+        astFormat: 'rust-syn',
+        maxNodes: options.maxNodes,
+        diagnostics: parseDiagnostics,
+        rustEdition: options.rustEdition ?? input.options?.rustEdition ?? parsed?.rustEdition,
+        includeAttributes: options.includeAttributes ?? input.options?.includeAttributes
+      });
+    }
+  };
+}
+
+export function createClangAstNativeImporterAdapter(options = {}) {
+  return {
+    id: options.id ?? 'frontier.clang-ast-native-importer',
+    language: options.language ?? 'c',
+    parser: options.parser ?? 'clang',
+    version: options.version,
+    capabilities: uniqueStrings(['nativeAst', 'semanticIndex', 'sourceMaps', 'diagnostics', ...(options.capabilities ?? [])]),
+    coverage: nativeImporterAdapterCoverage({
+      exactness: 'exact-parser-ast',
+      exactAst: true,
+      tokens: false,
+      trivia: false,
+      diagnostics: true,
+      sourceRanges: true,
+      generatedRanges: false,
+      semanticCoverage: declarationSemanticCoverage(),
+      notes: [
+        'Normalizes caller-owned Clang -ast-dump=json shaped ASTs into native AST nodes and declaration-level semantic index records.',
+        'Clang JSON ASTs reflect a preprocessed compiler view; compile commands, macros, inactive preprocessor branches, comments/trivia, and full type/reference analysis require host evidence.'
+      ]
+    }, options.coverage),
+    supportedExtensions: options.supportedExtensions ?? ['.c', '.h', '.cc', '.cpp', '.cxx', '.hpp', '.hh'],
+    diagnostics: options.diagnostics,
+    parse(input) {
+      const parsed = input.options?.ast
+        ?? input.options?.nativeAst
+        ?? input.options?.translationUnit
+        ?? input.options?.tu
+        ?? options.ast
+        ?? options.translationUnit
+        ?? options.tu
+        ?? parseClangAstSource(input, options);
+      const root = clangAstRoot(parsed);
+      if (!root) {
+        return missingInjectedParserResult(input, {
+          parser: options.parser ?? 'clang',
+          adapterId: options.id ?? 'frontier.clang-ast-native-importer',
+          message: 'createClangAstNativeImporterAdapter requires an injected Clang JSON AST object, parserModule.parse function, parse function, or adapterOptions.ast.'
+        });
+      }
+      const parseDiagnostics = normalizeParserErrors(parsed?.errors ?? parsed?.diagnostics, input, {
+        parser: options.parser ?? 'clang'
+      });
+      return createNativeImportFromClangAst(root, input, {
+        parser: options.parser ?? 'clang',
+        astFormat: 'clang-ast-json',
+        maxNodes: options.maxNodes,
+        diagnostics: parseDiagnostics,
+        cStandard: options.cStandard ?? input.options?.cStandard ?? parsed?.cStandard,
+        compileFlags: options.compileFlags ?? input.options?.compileFlags ?? parsed?.compileFlags,
+        includeSystemHeaders: options.includeSystemHeaders ?? input.options?.includeSystemHeaders,
+        preprocessorRecords: input.options?.preprocessorRecords ?? options.preprocessorRecords ?? parsed?.preprocessorRecords,
+        includeGraph: input.options?.includeGraph ?? options.includeGraph ?? parsed?.includeGraph
+      });
+    }
+  };
+}
+
 export function createTreeSitterNativeImporterAdapter(options = {}) {
   return {
     id: options.id ?? `frontier.tree-sitter-${idFragment(options.language ?? 'source')}-native-importer`,
@@ -7069,6 +7219,9 @@ function parserAstFormatIdForParser(parser) {
   const text = normalizeParserAstFormatId(parser);
   if (text.includes('typescript')) return 'typescript-compiler-api';
   if (text.includes('python') && text.includes('ast')) return 'python-ast';
+  if (text === 'syn' || text.includes('rust-syn')) return 'rust-syn';
+  if (text.includes('rust-analyzer') || text.includes('rowan')) return 'rust-analyzer-rowan';
+  if (text.includes('clang') || text.includes('libclang')) return 'clang-ast-json';
   if (text.includes('tree-sitter') || text.includes('treesitter')) return 'tree-sitter';
   if (text.includes('babel')) return 'babel';
   if (text.includes('estree')) return 'estree';
@@ -8103,6 +8256,37 @@ function parsePythonAstSource(input, options) {
   return parse(input.sourceText, parserOptions);
 }
 
+function parseRustSynSource(input, options) {
+  const parse = options.parse ?? options.parserModule?.parse ?? options.rustSyn?.parse ?? options.syn?.parse;
+  if (typeof parse !== 'function') return undefined;
+  const parserOptions = {
+    sourcePath: input.sourcePath,
+    filename: input.sourcePath,
+    edition: options.rustEdition ?? input.options?.rustEdition ?? '2021',
+    includeAttributes: options.includeAttributes ?? input.options?.includeAttributes,
+    ...(options.parserOptions ?? {}),
+    ...(input.options?.parserOptions ?? {})
+  };
+  return parse(input.sourceText, parserOptions);
+}
+
+function parseClangAstSource(input, options) {
+  const parse = options.parse ?? options.parserModule?.parse ?? options.clang?.parse ?? options.libclang?.parse;
+  if (typeof parse !== 'function') return undefined;
+  const parserOptions = {
+    sourcePath: input.sourcePath,
+    filename: input.sourcePath,
+    language: options.language ?? input.language,
+    standard: options.cStandard ?? input.options?.cStandard,
+    compileFlags: options.compileFlags ?? input.options?.compileFlags,
+    includeSystemHeaders: options.includeSystemHeaders ?? input.options?.includeSystemHeaders,
+    astDumpFormat: 'json',
+    ...(options.parserOptions ?? {}),
+    ...(input.options?.parserOptions ?? {})
+  };
+  return parse(input.sourceText, parserOptions);
+}
+
 function createNativeImportFromSyntaxAst(ast, input, options) {
   const root = normalizeSyntaxAstRoot(ast, options.astFormat);
   if (!root) {
@@ -8193,6 +8377,72 @@ function createNativeImportFromPythonAst(root, input, options) {
   };
 }
 
+function createNativeImportFromRustSyn(root, input, options) {
+  const context = createAstNormalizationContext(input, options);
+  visitRustSynNode(root, context, 'root');
+  if (context.truncated) {
+    context.losses.push(truncatedAstLoss(input, context, options));
+  }
+  const semantic = semanticIndexFromNativeDeclarations(context.declarations, input, options);
+  return {
+    rootId: context.rootId,
+    nodes: context.nodes,
+    semanticIndex: semantic.semanticIndex,
+    mappings: semantic.mappings,
+    losses: mergeNativeLosses(context.losses, options.diagnostics?.map((diagnostic, index) => adapterDiagnosticToLoss(diagnostic, index, {
+      id: input.adapterId,
+      version: input.adapterVersion
+    }, input)) ?? []),
+    evidence: semantic.evidence,
+    diagnostics: options.diagnostics,
+    metadata: {
+      astFormat: options.astFormat,
+      parser: options.parser,
+      rustEdition: options.rustEdition,
+      includeAttributes: Boolean(options.includeAttributes),
+      normalizedNodeCount: Object.keys(context.nodes).length,
+      declarationCount: context.declarations.length,
+      truncated: context.truncated
+    }
+  };
+}
+
+function createNativeImportFromClangAst(root, input, options) {
+  const context = createAstNormalizationContext(input, options);
+  visitClangAstNode(root, context, 'root');
+  for (const [index, record] of clangPreprocessorRecords(options.preprocessorRecords).entries()) {
+    visitClangAstNode(record, context, `preprocessorRecords[${index}]`);
+  }
+  if (context.truncated) {
+    context.losses.push(truncatedAstLoss(input, context, options));
+  }
+  const semantic = semanticIndexFromNativeDeclarations(context.declarations, input, options);
+  return {
+    rootId: context.rootId,
+    nodes: context.nodes,
+    semanticIndex: semantic.semanticIndex,
+    mappings: semantic.mappings,
+    losses: mergeNativeLosses(context.losses, options.diagnostics?.map((diagnostic, index) => adapterDiagnosticToLoss(diagnostic, index, {
+      id: input.adapterId,
+      version: input.adapterVersion
+    }, input)) ?? []),
+    evidence: semantic.evidence,
+    diagnostics: options.diagnostics,
+    metadata: {
+      astFormat: options.astFormat,
+      parser: options.parser,
+      cStandard: options.cStandard,
+      compileFlags: Array.isArray(options.compileFlags) ? options.compileFlags.slice() : options.compileFlags,
+      includeSystemHeaders: Boolean(options.includeSystemHeaders),
+      preprocessorRecordCount: clangPreprocessorRecords(options.preprocessorRecords).length,
+      includeGraph: serializableIncludeGraphSummary(options.includeGraph),
+      normalizedNodeCount: Object.keys(context.nodes).length,
+      declarationCount: context.declarations.length,
+      truncated: context.truncated
+    }
+  };
+}
+
 function createNativeImportFromTreeSitter(root, input, options) {
   const context = createAstNormalizationContext(input, options);
   visitTreeSitterNode(root, context, 'root');
@@ -8376,6 +8626,128 @@ function visitPythonAstNode(node, context, propertyPath) {
   return id;
 }
 
+function visitRustSynNode(node, context, propertyPath) {
+  if (!isRustSynAstNode(node) || context.truncated) return undefined;
+  if (context.objectIds.has(node)) return context.objectIds.get(node);
+  if (context.counter >= context.maxNodes) {
+    context.truncated = true;
+    return undefined;
+  }
+  const kind = rustSynKind(node);
+  const payload = rustSynPayload(node);
+  const span = spanFromRustSynNode(payload, context.input);
+  const id = nativeNodeId(context, kind, { start: { line: span?.startLine, column: span?.startColumn } }, propertyPath);
+  context.objectIds.set(node, id);
+  if (!context.rootId) context.rootId = id;
+  const children = [];
+  for (const [field, value] of rustSynChildEntries(node)) {
+    if (Array.isArray(value)) {
+      value.forEach((entry, index) => {
+        const childId = visitRustSynNode(entry, context, `${propertyPath}.${field}[${index}]`);
+        if (childId) children.push(childId);
+      });
+    } else {
+      const childId = visitRustSynNode(value, context, `${propertyPath}.${field}`);
+      if (childId) children.push(childId);
+    }
+  }
+  const declaration = rustSynDeclaration(payload, kind, id, context.input);
+  const nativeNode = {
+    id,
+    kind,
+    languageKind: `${context.input.language}.${kind}`,
+    span,
+    value: declaration?.name ?? rustSynNodeValue(payload),
+    fields: primitiveRustSynFields(payload, kind),
+    children,
+    metadata: {
+      astFormat: context.options.astFormat,
+      propertyPath,
+      spanKind: rustSynSpanKind(payload)
+    }
+  };
+  context.nodes[id] = nativeNode;
+  if (declaration) context.declarations.push({ ...declaration, nativeNode });
+  if (rustSynMacroKind(kind)) {
+    context.losses.push({
+      id: `loss_${idFragment(id)}_rust_macro_expansion`,
+      severity: 'warning',
+      phase: 'parse',
+      sourceFormat: context.input.language,
+      kind: 'macroExpansion',
+      message: 'Rust macro syntax was parsed but macro expansion and generated items require host compiler evidence.',
+      span,
+      nodeId: id,
+      metadata: {
+        parser: context.options.parser,
+        astFormat: context.options.astFormat
+      }
+    });
+  }
+  return id;
+}
+
+function visitClangAstNode(node, context, propertyPath) {
+  if (!isClangAstNode(node) || context.truncated) return undefined;
+  if (context.objectIds.has(node)) return context.objectIds.get(node);
+  if (context.counter >= context.maxNodes) {
+    context.truncated = true;
+    return undefined;
+  }
+  const kind = clangAstKind(node);
+  const span = spanFromClangAstNode(node, context.input);
+  const id = nativeNodeId(context, kind, { start: { line: span?.startLine, column: span?.startColumn } }, propertyPath);
+  context.objectIds.set(node, id);
+  if (!context.rootId) context.rootId = id;
+  const children = [];
+  for (const [field, value] of clangAstChildEntries(node)) {
+    if (Array.isArray(value)) {
+      value.forEach((entry, index) => {
+        const childId = visitClangAstNode(entry, context, `${propertyPath}.${field}[${index}]`);
+        if (childId) children.push(childId);
+      });
+    } else {
+      const childId = visitClangAstNode(value, context, `${propertyPath}.${field}`);
+      if (childId) children.push(childId);
+    }
+  }
+  const declaration = clangAstDeclaration(node, kind, id, context.input);
+  const nativeNode = {
+    id,
+    kind,
+    languageKind: `${context.input.language}.${kind}`,
+    span,
+    value: declaration?.name ?? clangAstNodeValue(node),
+    fields: primitiveClangAstFields(node, kind),
+    children,
+    metadata: {
+      astFormat: context.options.astFormat,
+      propertyPath,
+      clangId: typeof node.id === 'string' || typeof node.id === 'number' ? String(node.id) : undefined,
+      locationKind: clangLocationKind(node)
+    }
+  };
+  context.nodes[id] = nativeNode;
+  if (declaration) context.declarations.push({ ...declaration, nativeNode });
+  if (clangPreprocessorKind(kind)) {
+    context.losses.push({
+      id: `loss_${idFragment(id)}_clang_preprocessor`,
+      severity: 'warning',
+      phase: 'parse',
+      sourceFormat: context.input.language,
+      kind: 'preprocessor',
+      message: 'Clang AST preprocessor records were imported, but macro expansion, inactive branches, and compile-command provenance require host evidence.',
+      span,
+      nodeId: id,
+      metadata: {
+        parser: context.options.parser,
+        astFormat: context.options.astFormat
+      }
+    });
+  }
+  return id;
+}
+
 function visitTreeSitterNode(node, context, propertyPath) {
   if (!node || typeof node !== 'object' || context.truncated) return undefined;
   if (context.objectIds.has(node)) return context.objectIds.get(node);
@@ -9530,6 +9902,87 @@ function pythonAstKind(node) {
   return node?._type ?? node?.type ?? node?.kind ?? node?.nodeType;
 }
 
+function rustSynAstRoot(value) {
+  if (!value || typeof value !== 'object') return undefined;
+  if (isRustSynAstNode(value)) return value;
+  if (isRustSynAstNode(value.ast)) return value.ast;
+  if (isRustSynAstNode(value.file)) return value.file;
+  if (isRustSynAstNode(value.root)) return value.root;
+  if (isRustSynAstNode(value.module)) return value.module;
+  if (isRustSynAstNode(value.sourceFile)) return value.sourceFile;
+  return undefined;
+}
+
+function isRustSynAstNode(value) {
+  return Boolean(value && typeof value === 'object' && typeof rustSynKind(value) === 'string');
+}
+
+function rustSynKind(node) {
+  const declared = node?._type ?? node?.type ?? node?.kind ?? node?.nodeType ?? node?.synKind;
+  if (typeof declared === 'string') return normalizeRustSynKind(declared);
+  const wrapper = rustSynWrapperKind(node);
+  if (wrapper) return normalizeRustSynKind(wrapper);
+  if (Array.isArray(node?.items)) return 'File';
+  if (node?.sig && node?.block) return 'ItemFn';
+  if (node?.ident && node?.fields && Array.isArray(node?.variants)) return 'ItemEnum';
+  if (node?.ident && node?.fields) return 'ItemStruct';
+  if (node?.ident && Array.isArray(node?.items)) return 'ItemMod';
+  if (node?.trait_ || node?.self_ty || node?.selfType) return 'ItemImpl';
+  if (node?.path && (node?.tree || node?.trees)) return 'ItemUse';
+  return undefined;
+}
+
+function rustSynPayload(node) {
+  if (!node || typeof node !== 'object') return node;
+  const wrapper = rustSynWrapperKind(node);
+  return wrapper ? node[wrapper] : node;
+}
+
+function rustSynWrapperKind(node) {
+  if (!node || typeof node !== 'object') return undefined;
+  const keys = Object.keys(node).filter((key) => !ignoredRustSynField(key));
+  if (keys.length !== 1) return undefined;
+  const key = keys[0];
+  const value = node[key];
+  if (!value || typeof value !== 'object') return undefined;
+  if (/^(?:Fn|Struct|Enum|Trait|Impl|Use|Mod|Type|Const|Static|Union|Macro)$/.test(key)) return key;
+  if (/^(?:Item|ImplItem|TraitItem|ForeignItem)/.test(key)) return key;
+  return undefined;
+}
+
+function normalizeRustSynKind(kind) {
+  const text = String(kind);
+  const compact = text.replace(/^(?:syn::)?/, '').replace(/^Item::/, 'Item').replace(/^ImplItem::/, 'ImplItem').replace(/^TraitItem::/, 'TraitItem');
+  if (/^fn$/i.test(compact)) return 'ItemFn';
+  if (/^struct$/i.test(compact)) return 'ItemStruct';
+  if (/^enum$/i.test(compact)) return 'ItemEnum';
+  if (/^trait$/i.test(compact)) return 'ItemTrait';
+  if (/^impl$/i.test(compact)) return 'ItemImpl';
+  if (/^use$/i.test(compact)) return 'ItemUse';
+  if (/^mod$/i.test(compact)) return 'ItemMod';
+  if (/^type$/i.test(compact)) return 'ItemType';
+  if (/^const$/i.test(compact)) return 'ItemConst';
+  if (/^static$/i.test(compact)) return 'ItemStatic';
+  if (/^union$/i.test(compact)) return 'ItemUnion';
+  if (/^item_fn$/i.test(compact)) return 'ItemFn';
+  if (/^item_struct$/i.test(compact)) return 'ItemStruct';
+  if (/^item_enum$/i.test(compact)) return 'ItemEnum';
+  if (/^item_trait$/i.test(compact)) return 'ItemTrait';
+  if (/^item_impl$/i.test(compact)) return 'ItemImpl';
+  if (/^item_use$/i.test(compact)) return 'ItemUse';
+  if (/^item_mod$/i.test(compact)) return 'ItemMod';
+  if (/^item_type$/i.test(compact)) return 'ItemType';
+  if (/^item_const$/i.test(compact)) return 'ItemConst';
+  if (/^item_static$/i.test(compact)) return 'ItemStatic';
+  if (/^item_union$/i.test(compact)) return 'ItemUnion';
+  if (/^item_macro$/i.test(compact)) return 'ItemMacro';
+  if (/^macro$/i.test(compact)) return 'Macro';
+  if (/^impl_item_fn$/i.test(compact)) return 'ImplItemFn';
+  if (/^trait_item_fn$/i.test(compact)) return 'TraitItemFn';
+  if (/^foreign_item_fn$/i.test(compact)) return 'ForeignItemFn';
+  return compact;
+}
+
 function ignoredSyntaxField(key) {
   return key === 'type'
     || key === 'kind'
@@ -9564,6 +10017,18 @@ function ignoredPythonAstField(key) {
     || key === 'parent';
 }
 
+function ignoredRustSynField(key) {
+  return key === '_type'
+    || key === 'type'
+    || key === 'kind'
+    || key === 'nodeType'
+    || key === 'synKind'
+    || key === 'span'
+    || key === 'tokens'
+    || key === 'tokenStream'
+    || key === 'parent';
+}
+
 function primitiveSyntaxFields(node) {
   const fields = {};
   for (const key of ['name', 'operator', 'sourceType', 'async', 'generator', 'computed', 'static', 'exportKind', 'importKind', 'optional']) {
@@ -9595,6 +10060,22 @@ function primitivePythonAstFields(node, kind) {
   return fields;
 }
 
+function primitiveRustSynFields(node, kind) {
+  const fields = { kind };
+  const ident = rustSynIdentName(node.ident ?? node.name ?? node.sig?.ident);
+  if (ident) fields.ident = ident;
+  const path = rustSynPathName(node.path ?? node.trait_ ?? node.self_ty ?? node.selfType ?? node.ty);
+  if (path) fields.path = path;
+  const visibility = rustSynVisibility(node.vis ?? node.visibility);
+  if (visibility) fields.visibility = visibility;
+  for (const key of ['mutability', 'defaultness', 'constness', 'asyncness', 'unsafety', 'abi']) {
+    const value = node[key];
+    if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean' || value === null) fields[key] = value;
+  }
+  if (Array.isArray(node.attrs) && node.attrs.length) fields.attributeCount = node.attrs.length;
+  return fields;
+}
+
 function literalSyntaxValue(node) {
   if (node.value === null || typeof node.value === 'string' || typeof node.value === 'number' || typeof node.value === 'boolean') return node.value;
   return undefined;
@@ -9635,6 +10116,36 @@ function spanFromPythonAstNode(node, input) {
   };
 }
 
+function spanFromRustSynNode(node, input) {
+  const span = node.span ?? node.ident?.span ?? node.sig?.ident?.span ?? node.name?.span;
+  if (!span || typeof span !== 'object') return undefined;
+  const start = span.start ?? span.lo ?? span.begin;
+  const end = span.end ?? span.hi;
+  const startLine = span.startLine ?? span.line ?? start?.line;
+  const startColumn = span.startColumn ?? span.column ?? start?.column;
+  const endLine = span.endLine ?? end?.line;
+  const endColumn = span.endColumn ?? end?.column;
+  if (typeof startLine !== 'number') return undefined;
+  return {
+    sourceId: input.sourceHash,
+    path: input.sourcePath,
+    startLine,
+    startColumn: typeof startColumn === 'number' ? rustSynColumnToOneBased(startColumn, span) : undefined,
+    endLine: typeof endLine === 'number' ? endLine : undefined,
+    endColumn: typeof endColumn === 'number' ? rustSynColumnToOneBased(endColumn, span) : undefined
+  };
+}
+
+function rustSynColumnToOneBased(column, span) {
+  return span.columnBase === 1 || span.columnsOneBased ? column : column + 1;
+}
+
+function rustSynSpanKind(node) {
+  const span = node.span ?? node.ident?.span ?? node.sig?.ident?.span ?? node.name?.span;
+  if (!span || typeof span !== 'object') return undefined;
+  return span.kind ?? span.source ?? 'host-span';
+}
+
 function syntaxDeclaration(node, nativeNodeId, input) {
   const kind = String(node.type ?? node.kind ?? '');
   if (kind === 'ImportDeclaration') {
@@ -9671,6 +10182,46 @@ function pythonAstDeclaration(node, kind, nativeNodeId, input) {
   return undefined;
 }
 
+function rustSynDeclaration(node, kind, nativeNodeId, input) {
+  if (kind === 'ItemUse' || kind === 'UseTree' || kind === 'UsePath' || kind === 'UseName') {
+    const name = rustSynUseName(node);
+    if (name) return declarationRecord(input, nativeNodeId, name, 'module', 'import');
+  }
+  if (kind === 'ItemFn' || kind === 'ForeignItemFn') {
+    const name = rustSynIdentName(node.sig?.ident ?? node.ident ?? node.name);
+    if (name) return declarationRecord(input, nativeNodeId, name, 'function', 'definition');
+  }
+  if (kind === 'ImplItemFn' || kind === 'TraitItemFn') {
+    const name = rustSynIdentName(node.sig?.ident ?? node.ident ?? node.name);
+    if (name) return declarationRecord(input, nativeNodeId, name, 'method', 'definition');
+  }
+  if (kind === 'ItemStruct' || kind === 'ItemUnion') {
+    const name = rustSynIdentName(node.ident ?? node.name);
+    if (name) return declarationRecord(input, nativeNodeId, name, 'class', 'definition');
+  }
+  if (kind === 'ItemEnum' || kind === 'ItemTrait' || kind === 'ItemType') {
+    const name = rustSynIdentName(node.ident ?? node.name);
+    if (name) return declarationRecord(input, nativeNodeId, name, 'type', 'definition');
+  }
+  if (kind === 'ItemMod') {
+    const name = rustSynIdentName(node.ident ?? node.name);
+    if (name) return declarationRecord(input, nativeNodeId, name, 'module', 'definition');
+  }
+  if (kind === 'ItemConst' || kind === 'ItemStatic') {
+    const name = rustSynIdentName(node.ident ?? node.name);
+    if (name) return declarationRecord(input, nativeNodeId, name, 'variable', 'definition');
+  }
+  if (kind === 'ItemImpl') {
+    const name = rustSynImplName(node);
+    if (name) return declarationRecord(input, nativeNodeId, name, 'type', 'definition');
+  }
+  if (rustSynMacroKind(kind)) {
+    const name = rustSynIdentName(node.ident ?? node.mac?.path ?? node.path);
+    if (name) return declarationRecord(input, nativeNodeId, name, 'macro', 'definition');
+  }
+  return undefined;
+}
+
 function typeScriptDeclaration(node, kind, nativeNodeId, input) {
   if (kind === 'ImportDeclaration' || kind === 'ImportEqualsDeclaration') {
     const name = stringFromTsExpression(node.moduleSpecifier) ?? stringFromTsExpression(node.externalModuleReference?.expression);
@@ -9725,10 +10276,26 @@ function pythonAstChildEntries(node) {
       : isPythonAstNode(value));
 }
 
+function rustSynChildEntries(node) {
+  const payload = rustSynPayload(node);
+  const fieldNames = Object.keys(payload).filter((key) => !ignoredRustSynField(key));
+  return fieldNames
+    .map((field) => [field, payload[field]])
+    .filter(([, value]) => Array.isArray(value)
+      ? value.some(isRustSynAstNode)
+      : isRustSynAstNode(value));
+}
+
 function pythonAstNodeValue(node) {
   return node.name ?? node.id ?? node.arg ?? node.module ?? pythonAstLiteralValue(node);
 }
 
+function rustSynNodeValue(node) {
+  return rustSynIdentName(node.ident ?? node.name ?? node.sig?.ident)
+    ?? rustSynPathName(node.path ?? node.trait_ ?? node.self_ty ?? node.selfType ?? node.ty)
+    ?? rustSynLiteralValue(node);
+}
+
 function pythonAliasName(alias) {
   if (!alias) return undefined;
   if (typeof alias === 'string') return alias;
@@ -9757,6 +10324,339 @@ function pythonTargetName(target) {
   return undefined;
 }
 
+function rustSynIdentName(value) {
+  if (!value) return undefined;
+  if (typeof value === 'string') return value;
+  if (typeof value.ident === 'string') return value.ident;
+  if (typeof value.name === 'string') return value.name;
+  if (typeof value.text === 'string') return value.text;
+  if (typeof value.sym === 'string') return value.sym;
+  if (typeof value.value === 'string') return value.value;
+  if (typeof value.path === 'string') return value.path;
+  return rustSynPathName(value.path ?? value);
+}
+
+function rustSynPathName(value) {
+  if (!value) return undefined;
+  if (typeof value === 'string') return value;
+  if (typeof value.ident === 'string') return value.ident;
+  if (typeof value.name === 'string') return value.name;
+  if (typeof value.path === 'string') return value.path;
+  if (value.path && typeof value.path === 'object') return rustSynPathName(value.path);
+  if (Array.isArray(value.segments)) {
+    const names = value.segments
+      .map((segment) => rustSynIdentName(segment.ident ?? segment))
+      .filter(Boolean);
+    return names.length ? names.join('::') : undefined;
+  }
+  if (Array.isArray(value.qself)) return value.qself.map(rustSynPathName).filter(Boolean).join('::');
+  if (value.leading_colon && value.segments) {
+    const name = rustSynPathName({ segments: value.segments });
+    return name ? `::${name}` : undefined;
+  }
+  return undefined;
+}
+
+function rustSynUseName(node) {
+  if (!node) return undefined;
+  if (node.prefix && node.tree) {
+    const prefix = rustSynPathName(node.prefix);
+    const child = rustSynUseName(node.tree);
+    return [prefix, child].filter(Boolean).join('::') || undefined;
+  }
+  if (node.ident && node.tree) {
+    const prefix = rustSynIdentName(node.ident);
+    const child = rustSynUseName(node.tree);
+    return [prefix, child].filter(Boolean).join('::') || undefined;
+  }
+  if (node.path && node.tree) {
+    const prefix = rustSynPathName(node.path);
+    const child = rustSynUseName(node.tree);
+    return [prefix, child].filter(Boolean).join('::') || undefined;
+  }
+  if (Array.isArray(node.trees)) return node.trees.map(rustSynUseName).find(Boolean);
+  if (node.tree) return rustSynUseName(node.tree);
+  if (node.path) return rustSynPathName(node.path);
+  if (node.name) return rustSynIdentName(node.name);
+  if (node.ident) return rustSynIdentName(node.ident);
+  if (node.rename) return rustSynIdentName(node.rename);
+  return undefined;
+}
+
+function rustSynImplName(node) {
+  const selfType = rustSynPathName(node.self_ty ?? node.selfType ?? node.ty);
+  const traitPath = Array.isArray(node.trait_)
+    ? rustSynPathName(node.trait_[1] ?? node.trait_[0])
+    : rustSynPathName(node.trait_);
+  if (selfType && traitPath) return `${selfType}.${traitPath}.impl`;
+  if (selfType) return `${selfType}.impl`;
+  if (traitPath) return `${traitPath}.impl`;
+  return undefined;
+}
+
+function rustSynVisibility(value) {
+  if (!value) return undefined;
+  if (typeof value === 'string') return value;
+  if (typeof value.kind === 'string') return value.kind;
+  if (typeof value.type === 'string') return value.type;
+  if (value.pub || value.Public) return 'pub';
+  if (value.restricted || value.Restricted) return 'restricted';
+  return undefined;
+}
+
+function rustSynLiteralValue(node) {
+  const value = node.value ?? node.lit?.value ?? node.lit;
+  if (value === null || typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') return value;
+  return undefined;
+}
+
+function rustSynMacroKind(kind) {
+  return /Macro|MacroRules|MacroCall/.test(String(kind));
+}
+
+function clangAstRoot(value) {
+  if (!value || typeof value !== 'object') return undefined;
+  if (Array.isArray(value)) return { kind: 'TranslationUnitDecl', inner: value };
+  if (isClangAstNode(value)) return value;
+  if (Array.isArray(value.ast)) return { kind: 'TranslationUnitDecl', inner: value.ast };
+  if (isClangAstNode(value.ast)) return value.ast;
+  if (isClangAstNode(value.root)) return value.root;
+  if (isClangAstNode(value.translationUnit)) return value.translationUnit;
+  if (isClangAstNode(value.tu)) return value.tu;
+  if (isClangAstNode(value.file)) return value.file;
+  if (isClangAstNode(value.sourceFile)) return value.sourceFile;
+  return undefined;
+}
+
+function isClangAstNode(value) {
+  return Boolean(value && typeof value === 'object' && typeof clangAstKind(value) === 'string');
+}
+
+function clangAstKind(node) {
+  if (!node || typeof node !== 'object') return undefined;
+  const declared = node.kind ?? node._type ?? node.type ?? node.nodeType ?? node.declKind ?? node.stmtKind;
+  if (typeof declared === 'string') return declared;
+  if (Array.isArray(node.inner) || Array.isArray(node.children) || Array.isArray(node.decls)) return 'TranslationUnitDecl';
+  return undefined;
+}
+
+function ignoredClangAstField(key) {
+  return key === '_type'
+    || key === 'type'
+    || key === 'kind'
+    || key === 'nodeType'
+    || key === 'declKind'
+    || key === 'stmtKind'
+    || key === 'id'
+    || key === 'loc'
+    || key === 'range'
+    || key === 'name'
+    || key === 'displayName'
+    || key === 'qualifiedName'
+    || key === 'mangledName'
+    || key === 'parent'
+    || key === 'parentDeclContextId'
+    || key === 'previousDecl'
+    || key === 'referencedDecl';
+}
+
+function primitiveClangAstFields(node, kind) {
+  const fields = { kind };
+  const name = clangDeclarationName(node);
+  if (name) fields.name = name;
+  const type = clangTypeName(node.type ?? node.qualType);
+  if (type) fields.type = type;
+  for (const key of [
+    'mangledName',
+    'storageClass',
+    'tagUsed',
+    'completeDefinition',
+    'isThisDeclarationADefinition',
+    'inline',
+    'isUsed',
+    'isReferenced',
+    'valueCategory',
+    'opcode',
+    'castKind'
+  ]) {
+    const value = node[key];
+    if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean' || value === null) fields[key] = value;
+  }
+  const includePath = clangIncludePath(node);
+  if (includePath) fields.includePath = includePath;
+  const literal = clangLiteralValue(node);
+  if (literal !== undefined) fields.literal = literal;
+  const referenced = clangDeclarationName(node.referencedDecl);
+  if (referenced) fields.referenced = referenced;
+  return fields;
+}
+
+function spanFromClangAstNode(node, input) {
+  const range = node.range ?? {};
+  const begin = range.begin ?? node.loc ?? node.spellingLoc ?? node.expansionLoc;
+  const end = range.end ?? node.end;
+  const start = clangLocPosition(begin);
+  if (!start) return undefined;
+  const finish = clangLocPosition(end);
+  return {
+    sourceId: input.sourceHash,
+    path: start.path ?? finish?.path ?? input.sourcePath,
+    startLine: start.line,
+    startColumn: start.column,
+    endLine: finish?.line,
+    endColumn: finish?.column
+  };
+}
+
+function clangLocPosition(loc) {
+  if (!loc || typeof loc !== 'object') return undefined;
+  const expanded = loc.expansionLoc ?? loc.spellingLoc ?? loc;
+  const line = expanded.line ?? expanded.startLine ?? expanded.begin?.line;
+  const column = expanded.col ?? expanded.column ?? expanded.startColumn ?? expanded.begin?.col ?? expanded.begin?.column;
+  if (typeof line !== 'number') return undefined;
+  return {
+    path: expanded.file ?? expanded.filename ?? expanded.path,
+    line,
+    column: typeof column === 'number' ? column : undefined
+  };
+}
+
+function clangLocationKind(node) {
+  const loc = node.loc ?? node.range?.begin;
+  if (!loc || typeof loc !== 'object') return undefined;
+  if (loc.expansionLoc) return 'expansionLoc';
+  if (loc.spellingLoc) return 'spellingLoc';
+  if (loc.includedFrom) return 'includedFrom';
+  return 'clang-loc';
+}
+
+function clangAstDeclaration(node, kind, nativeNodeId, input) {
+  if (kind === 'FunctionDecl' || kind === 'CXXMethodDecl' || kind === 'FunctionTemplateDecl') {
+    const name = clangDeclarationName(node);
+    if (name) return declarationRecord(input, nativeNodeId, name, kind === 'CXXMethodDecl' ? 'method' : 'function', clangDeclarationAction(node));
+  }
+  if (kind === 'ParmVarDecl') {
+    const name = clangDeclarationName(node);
+    if (name) return declarationRecord(input, nativeNodeId, name, 'parameter', 'definition');
+  }
+  if (kind === 'RecordDecl' || kind === 'CXXRecordDecl' || kind === 'ClassTemplateDecl') {
+    const name = clangDeclarationName(node);
+    if (name) return declarationRecord(input, nativeNodeId, name, kind === 'CXXRecordDecl' ? 'class' : 'type', clangDeclarationAction(node));
+  }
+  if (kind === 'FieldDecl') {
+    const name = clangDeclarationName(node);
+    if (name) return declarationRecord(input, nativeNodeId, name, 'property', 'definition');
+  }
+  if (kind === 'TypedefDecl' || kind === 'TypeAliasDecl' || kind === 'TypeAliasTemplateDecl') {
+    const name = clangDeclarationName(node);
+    if (name) return declarationRecord(input, nativeNodeId, name, 'type', 'definition');
+  }
+  if (kind === 'EnumDecl') {
+    const name = clangDeclarationName(node);
+    if (name) return declarationRecord(input, nativeNodeId, name, 'type', clangDeclarationAction(node));
+  }
+  if (kind === 'EnumConstantDecl') {
+    const name = clangDeclarationName(node);
+    if (name) return declarationRecord(input, nativeNodeId, name, 'enumMember', 'definition');
+  }
+  if (kind === 'VarDecl') {
+    const name = clangDeclarationName(node);
+    if (name) return declarationRecord(input, nativeNodeId, name, 'variable', clangDeclarationAction(node));
+  }
+  if (/IncludeDirective|InclusionDirective/.test(kind)) {
+    const name = clangIncludePath(node);
+    if (name) return declarationRecord(input, nativeNodeId, name, 'module', 'import');
+  }
+  if (/MacroDefinition|MacroExpansion|MacroInstantiation/.test(kind)) {
+    const name = clangDeclarationName(node) ?? clangIncludePath(node);
+    if (name) return declarationRecord(input, nativeNodeId, name, 'macro', 'definition');
+  }
+  return undefined;
+}
+
+function clangDeclarationAction(node) {
+  if (node.isThisDeclarationADefinition === false) return 'declaration';
+  if (node.isThisDeclarationADefinition === true) return 'definition';
+  if (Array.isArray(node.inner) && node.inner.some((entry) => ['CompoundStmt', 'FieldDecl', 'EnumConstantDecl'].includes(clangAstKind(entry)))) return 'definition';
+  return 'declaration';
+}
+
+function clangAstChildEntries(node) {
+  const fieldNames = Object.keys(node).filter((key) => !ignoredClangAstField(key));
+  return fieldNames
+    .map((field) => [field, node[field]])
+    .filter(([, value]) => Array.isArray(value)
+      ? value.some(isClangAstNode)
+      : isClangAstNode(value));
+}
+
+function clangAstNodeValue(node) {
+  return clangDeclarationName(node)
+    ?? clangIncludePath(node)
+    ?? clangTypeName(node.type ?? node.qualType)
+    ?? clangLiteralValue(node);
+}
+
+function clangDeclarationName(node) {
+  if (!node || typeof node !== 'object') return undefined;
+  for (const key of ['qualifiedName', 'displayName', 'name', 'mangledName']) {
+    if (typeof node[key] === 'string' && node[key]) return node[key];
+  }
+  if (node.name && typeof node.name === 'object') return clangDeclarationName(node.name);
+  if (node.referencedDecl && typeof node.referencedDecl === 'object') return clangDeclarationName(node.referencedDecl);
+  if (node.decl && typeof node.decl === 'object') return clangDeclarationName(node.decl);
+  return undefined;
+}
+
+function clangIncludePath(node) {
+  if (!node || typeof node !== 'object') return undefined;
+  for (const key of ['file', 'filename', 'path', 'spelling', 'source']) {
+    if (typeof node[key] === 'string' && node[key]) return node[key];
+  }
+  if (node.include && typeof node.include === 'object') return clangIncludePath(node.include);
+  return undefined;
+}
+
+function clangTypeName(value) {
+  if (!value) return undefined;
+  if (typeof value === 'string') return value;
+  if (typeof value.qualType === 'string') return value.qualType;
+  if (typeof value.desugaredQualType === 'string') return value.desugaredQualType;
+  if (typeof value.name === 'string') return value.name;
+  if (value.type && typeof value.type === 'object') return clangTypeName(value.type);
+  return undefined;
+}
+
+function clangLiteralValue(node) {
+  const value = node.value ?? node.val ?? node.literal;
+  if (value === null || typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') return value;
+  if (typeof node.valueAsString === 'string') return node.valueAsString;
+  return undefined;
+}
+
+function clangPreprocessorKind(kind) {
+  return /Macro|Preprocess|Preprocessor|IfDirective|IfdefDirective|IfndefDirective|ElifDirective|ElseDirective|EndifDirective/.test(String(kind));
+}
+
+function clangPreprocessorRecords(value) {
+  if (!value) return [];
+  if (Array.isArray(value)) return value.filter(isClangAstNode);
+  if (typeof value === 'object' && Array.isArray(value.records)) return value.records.filter(isClangAstNode);
+  if (isClangAstNode(value)) return [value];
+  return [];
+}
+
+function serializableIncludeGraphSummary(value) {
+  if (!value || typeof value !== 'object') return undefined;
+  if (Array.isArray(value)) return { edgeCount: value.length };
+  const summary = {};
+  if (typeof value.hash === 'string') summary.hash = value.hash;
+  if (typeof value.root === 'string') summary.root = value.root;
+  if (Array.isArray(value.edges)) summary.edgeCount = value.edges.length;
+  if (Array.isArray(value.includes)) summary.includeCount = value.includes.length;
+  return Object.keys(summary).length ? summary : { present: true };
+}
+
 function declarationRecord(input, nativeNodeId, name, symbolKind, role = 'definition') {
   return {
     name: String(name),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shapeshift-labs/frontier-lang-compiler",
-  "version": "0.2.26",
+  "version": "0.2.28",
   "description": "Compiler facade for Frontier Lang source documents and language projection adapters.",
   "type": "module",
   "main": "./dist/index.js",