@sanbus/galley-bun 0.0.1

package/README.md

@@ -0,0 +1,8 @@
+# JavaScript Bindings for Bun
+
+`@sanbus/galley-core` over `bun:ffi` and `bindings/c/galley.h`. No native
+dependencies beyond the built parser library.
+
+See `docs/bindings_js_bun.md` and `examples/js/bun` for the consumer flow.
+
+One shared library embeds one parser; sessions are not thread-safe.

package/build.mjs

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+/**
+ * Builds a Galley parser and its shared library for a JavaScript consumer
+ * on Bun.
+ *
+ * Usage:
+ *   npx galley-js-bun <language-dir>
+ *
+ * Thin wrapper over the shared gate (`@sanbus/galley-core/build/builder.mjs`),
+ * which documents the accepted grammar files and owns the build. For both
+ * legs at once, use the single entry instead: `galley build <language-dir>`
+ * from `@sanbus/galley`.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { buildParserArtifact } from "@sanbus/galley-core/build/builder.mjs";
+
+const LIBRARY_NAME = "galley-js-bun";
+
+function fatal(message) {
+  console.error(`galley-bindings: ${message}`);
+  process.exit(1);
+}
+
+async function main() {
+  if (process.argv.length !== 3) fatal("usage: npx galley-js-bun <language-dir>");
+  const bindingsDirectory = path.dirname(fileURLToPath(import.meta.url));
+  const languageDirectory = path.resolve(process.argv[2]);
+  await buildParserArtifact({
+    languageDirectory,
+    libraryName: LIBRARY_NAME,
+    bindingsDirectory,
+    dependencyName: "@sanbus/galley-core",
+    installCommand: "bun install",
+  });
+
+  // Bun snapshots `file:` dependencies into node_modules at install time,
+  // so a consumer's copy can predate the build outputs (dist/ and the
+  // nested @sanbus/galley-core, materialized above, after install) and fail
+  // resolution with "Cannot find package". Refresh every snapshot copy
+  // reachable from this build: the language dir's own and the invoking
+  // directory's (the benchmark flow builds benchmark/ while resolving
+  // through the parent example dir). The npm-based adapters symlink
+  // `file:` dirs and never need this. This stays in the wrapper: it is a
+  // Bun install-layout quirk, not build semantics.
+  const refreshed = new Set();
+  for (const rootDirectory of [languageDirectory, process.cwd()]) {
+    const resolved = path.resolve(rootDirectory);
+    if (refreshed.has(resolved)) continue;
+    refreshed.add(resolved);
+    refreshSnapshot(resolved, bindingsDirectory);
+  }
+}
+
+function refreshSnapshot(rootDirectory, bindingsDirectory) {
+  const snapshotDirectory = path.join(rootDirectory, "node_modules", "@sanbus/galley-bun");
+  const snapshotPackage = path.join(snapshotDirectory, "package.json");
+  if (!fs.existsSync(snapshotPackage)) return;
+  // Only touch our own snapshot copy, never an unrelated registry install.
+  const bindingsPackage = JSON.parse(fs.readFileSync(path.join(bindingsDirectory, "package.json"), "utf-8"));
+  const snapshotManifest = JSON.parse(fs.readFileSync(snapshotPackage, "utf-8"));
+  if (
+    snapshotManifest.name !== bindingsPackage.name ||
+    snapshotManifest.version !== bindingsPackage.version
+  )
+    return;
+  const snapshotDist = path.join(snapshotDirectory, "dist");
+  fs.rmSync(snapshotDist, { recursive: true, force: true });
+  fs.cpSync(path.join(bindingsDirectory, "dist"), snapshotDist, { recursive: true });
+  console.log(`galley-bindings: refreshed ${snapshotDist}`);
+  const snapshotCore = path.join(snapshotDirectory, "node_modules", "@sanbus/galley-core");
+  fs.rmSync(snapshotCore, { recursive: true, force: true });
+  fs.mkdirSync(path.join(snapshotDirectory, "node_modules"), { recursive: true });
+  // Dereference: the source entry is usually a symlink into the checkout,
+  // which would dangle from inside the snapshot.
+  fs.cpSync(path.join(bindingsDirectory, "node_modules", "@sanbus/galley-core"), snapshotCore, {
+    recursive: true,
+    dereference: true,
+  });
+  console.log(`galley-bindings: refreshed ${snapshotCore}`);
+}
+
+main().catch((error) => fatal(error?.message ?? String(error)));

package/dist/dispatch.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Bun procedure-dispatch installer.
+ *
+ * Owns the `JSCallback` that the shared JS shim
+ * (`galley_install_js_dispatch_id`, generated by `@sanbus/galley-core/build/shim.mjs`)
+ * forwards every parser hook through, plus the `require()`-based auto-scan
+ * of `procedures.*` in the language directory (Bun loads TypeScript
+ * synchronously, like Node). The registry and the ID-to-name dispatcher
+ * live in the core; this module only bridges the native boundary.
+ * Libraries that predate integer hook IDs still export the name-carrying
+ * `galley_install_js_dispatch`, used as a fallback.
+ */
+import type { FfiPort } from "@sanbus/galley-core";
+import type { BunPort } from "./ffi.ts";
+export declare function ensureDispatchFor(port: BunPort & FfiPort): void;

package/dist/dispatch.js

@@ -0,0 +1,135 @@
+/**
+ * Bun procedure-dispatch installer.
+ *
+ * Owns the `JSCallback` that the shared JS shim
+ * (`galley_install_js_dispatch_id`, generated by `@sanbus/galley-core/build/shim.mjs`)
+ * forwards every parser hook through, plus the `require()`-based auto-scan
+ * of `procedures.*` in the language directory (Bun loads TypeScript
+ * synchronously, like Node). The registry and the ID-to-name dispatcher
+ * live in the core; this module only bridges the native boundary.
+ * Libraries that predate integer hook IDs still export the name-carrying
+ * `galley_install_js_dispatch`, used as a fallback.
+ */
+import { createRequire } from "node:module";
+import * as path from "node:path";
+import { JSCallback, FFIType, toArrayBuffer } from "bun:ffi";
+import { dispatchProcedure, installProcedures, listProcedures } from "@sanbus/galley-core";
+const require = createRequire(import.meta.url);
+const textDecoder = new TextDecoder();
+// Held to prevent GC of the callbacks; installed per library path.
+// ID and name paths keep separate slots: their signatures differ.
+let dispatchIdCallback = null;
+let dispatchIdPointer = null;
+let dispatchCallback = null;
+let dispatchPointer = null;
+const installedFor = new Set();
+let autoAttempted = false;
+function isProcedureName(name) {
+    return name === "reduction" || name.startsWith("reduction_") || name.startsWith("hook_");
+}
+function tryAutoRegister(libPath) {
+    if (listProcedures().length > 0 || autoAttempted)
+        return;
+    autoAttempted = true;
+    const tryLoadModule = (modulePath) => {
+        try {
+            const loadedModule = require(modulePath);
+            let hasHook = false;
+            for (const [name, value] of Object.entries(loadedModule)) {
+                if (typeof value !== "function" || !isProcedureName(name))
+                    continue;
+                hasHook = true;
+                break;
+            }
+            if (hasHook)
+                return installProcedures(loadedModule) > 0;
+            const defaultExport = loadedModule.default;
+            if (defaultExport && typeof defaultExport === "object") {
+                return installProcedures(defaultExport) > 0;
+            }
+        }
+        catch { }
+        return false;
+    };
+    // One place: the directory holding the loaded library. Anything found
+    // there belongs to this grammar; nothing else is even looked at.
+    const baseDirectory = path.dirname(libPath);
+    const extensions = ["", ".js", ".ts"];
+    for (const extension of extensions) {
+        if (tryLoadModule(path.join(baseDirectory, `procedures${extension}`)))
+            return;
+    }
+}
+export function ensureDispatchFor(port) {
+    if (!port.supportsDispatch) {
+        // Library was built for C procedures (no shim); installs will be no-ops.
+        return;
+    }
+    tryAutoRegister(port.libraryPath);
+    if (installedFor.has(port.libraryPath))
+        return;
+    if (typeof port.native.galley_install_js_dispatch_id === "function" &&
+        port.procedureNames().length > 0) {
+        installIdDispatch(port);
+    }
+    else {
+        installNameDispatch(port);
+    }
+    installedFor.add(port.libraryPath);
+}
+function installIdDispatch(port) {
+    if (dispatchIdCallback === null) {
+        // Integer hook IDs: no string copy or decode on the hot path. The table
+        // is fixed per library build; unknown IDs are silent no-ops.
+        const table = port.procedureNames();
+        const cb = new JSCallback((id, argsPtr) => {
+            const name = table[id];
+            if (name === undefined)
+                return;
+            dispatchProcedure(name, argsPtr, port);
+        }, { args: [FFIType.u32, FFIType.ptr], returns: FFIType.void });
+        // Prevent GC — the trampoline must stay reachable for the process lifetime.
+        globalThis.__galley_js_dispatchIdCallback = cb;
+        dispatchIdCallback = cb;
+        dispatchIdPointer = cb.ptr;
+    }
+    try {
+        port.native.galley_install_js_dispatch_id(dispatchIdPointer);
+    }
+    catch {
+        // Installer resolution is lazy on some runtimes; a missing installer
+        // means a C-procedures library — installs stay no-ops.
+    }
+}
+function installNameDispatch(port) {
+    if (dispatchCallback === null) {
+        // Signature mirrors Zig: fn([*]const u8, usize, ?*anyopaque) callconv(.c) void.
+        // Note: usize arrives as bigint in callbacks.
+        const cb = new JSCallback((namePtr, nameLen, argsPtr) => {
+            if (!namePtr)
+                return;
+            let name;
+            try {
+                const bytes = toArrayBuffer(namePtr, 0, Number(nameLen));
+                name = textDecoder.decode(bytes);
+            }
+            catch (e) {
+                console.error("galley procedure dispatch: failed to decode name", e);
+                return;
+            }
+            dispatchProcedure(name, argsPtr, port);
+        }, { args: [FFIType.ptr, FFIType.u64, FFIType.ptr], returns: FFIType.void });
+        // Prevent GC — the trampoline must stay reachable for the process lifetime.
+        globalThis.__galley_js_dispatchCallback = cb;
+        dispatchCallback = cb;
+        dispatchPointer = cb.ptr;
+    }
+    try {
+        port.native.galley_install_js_dispatch(dispatchPointer);
+    }
+    catch {
+        // Installer resolution is lazy on some runtimes; a missing installer
+        // means a C-procedures library — installs stay no-ops.
+    }
+}
+//# sourceMappingURL=dispatch.js.map

package/dist/dispatch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch.js","sourceRoot":"","sources":["../src/dispatch.ts"],"names":[],"mappings":"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"}

package/dist/ffi.d.ts

@@ -0,0 +1,255 @@
+/**
+ * Bun adapter for the Galley JavaScript bindings: `bun:ffi` bindings over
+ * `bindings/c/galley.h`, implementing the core `FfiPort`.
+ *
+ * Zero npm dependencies: `bun:ffi` is built into the runtime. The core
+ * (`@sanbus/galley-core`) owns all session logic; memory copying and integer
+ * normalization live here. Library discovery mirrors the Node adapter.
+ */
+import type { FfiPort, Handle, SessionCOptions, TreeSnapshot, WalkedStep } from "@sanbus/galley-core";
+/** Native handles are addresses; 0 is null. */
+type NativeHandle = number;
+/** Callable view of the native symbols (see `BASE_SYMBOLS` below). */
+interface GalleySymbols {
+    galley_version(): string;
+    galley_parser_type(): bigint;
+    galley_error_recovery_mode(): bigint;
+    galley_has_ast(): number;
+    galley_has_procedures(): number;
+    galley_allows_no_ast_tree_procedures(): number;
+    galley_source_retention_enabled(): number;
+    galley_has_position_tracking(): number;
+    galley_has_input_streaming(): number;
+    galley_uses_verbatim(): number;
+    galley_stack_overflow_recovery_available(): number;
+    galley_symbol_count(): bigint;
+    galley_variable_count(): bigint;
+    galley_status_string(status: bigint): string;
+    galley_symbol_name(session: NativeHandle, index: bigint, outData: number, outLen: number): bigint;
+    galley_symbol_is_terminal(session: NativeHandle, index: bigint): number;
+    galley_variable_name(session: NativeHandle, index: bigint, outData: number, outLen: number): bigint;
+    galley_session_create(): NativeHandle;
+    galley_session_create_ex(options: number): NativeHandle;
+    galley_session_destroy(session: NativeHandle): void;
+    galley_session_set_message_override(session: NativeHandle, name: number, nameLen: bigint, message: number, messageLen: bigint): bigint;
+    galley_parse(session: NativeHandle, data: number, len: bigint): bigint;
+    galley_parse_file(session: NativeHandle, path: number): bigint;
+    galley_last_position(session: NativeHandle, outLine: number, outCol: number): bigint;
+    galley_node_count(session: NativeHandle): bigint;
+    galley_reserve_nodes(session: NativeHandle, capacity: bigint): bigint;
+    galley_node_capacity(session: NativeHandle): bigint;
+    galley_root_node(session: NativeHandle): bigint;
+    galley_node_is_valid(session: NativeHandle, node: bigint): number;
+    galley_node_child_count(session: NativeHandle, node: bigint): number;
+    galley_node_first_child(session: NativeHandle, node: bigint): bigint;
+    galley_node_last_child(session: NativeHandle, node: bigint): bigint;
+    galley_node_next_sibling(session: NativeHandle, node: bigint): bigint;
+    galley_node_prior_sibling(session: NativeHandle, node: bigint): bigint;
+    galley_node_parent(session: NativeHandle, node: bigint): bigint;
+    galley_tree_snapshot(session: NativeHandle, outParent: number, outFirstChild: number, outNext: number, outChildCount: number, outVariable: number, outSpanStart: number, outSpanLen: number, capacity: bigint): bigint;
+    galley_walker_create(session: NativeHandle, node: bigint, skipSemanticErrors: number): NativeHandle;
+    galley_walker_next(walker: NativeHandle, outNode: number, outDepth: number, outFlag: number): number;
+    galley_walker_skip_children(walker: NativeHandle): void;
+    galley_walker_destroy(walker: NativeHandle): void;
+    galley_node_span(session: NativeHandle, node: bigint, outStart: number, outLen: number): bigint;
+    galley_node_symbol_name(session: NativeHandle, node: bigint, outData: number, outLen: number): bigint;
+    galley_node_variable_index(session: NativeHandle, node: bigint): bigint;
+    galley_node_text(session: NativeHandle, node: bigint, outData: number, outLen: number): bigint;
+    galley_node_line_column(session: NativeHandle, node: bigint, outLine: number, outCol: number): bigint;
+    galley_has_diagnostic(session: NativeHandle): number;
+    galley_diagnostic_kind(session: NativeHandle): bigint;
+    galley_diagnostic_message(session: NativeHandle, out: number): bigint;
+    galley_diagnostic_message_ansi(session: NativeHandle, out: number): bigint;
+    galley_diagnostic_position(session: NativeHandle, outLine: number, outCol: number): bigint;
+    galley_diagnostic_unexpected_token(session: NativeHandle, outData: number, outLen: number): bigint;
+    galley_diagnostic_expected_count(session: NativeHandle): bigint;
+    galley_diagnostic_expected_at(session: NativeHandle, index: bigint, outData: number, outLen: number): bigint;
+    galley_diagnostic_context_count(session: NativeHandle): bigint;
+    galley_diagnostic_context_at(session: NativeHandle, index: bigint, outData: number, outLen: number): bigint;
+    galley_diagnostic_indentation(session: NativeHandle, outSpaces: number, outWidth: number): bigint;
+    galley_syntax_error_count(session: NativeHandle): bigint;
+    galley_semantic_error_count(session: NativeHandle): bigint;
+    galley_diagnostic_semantic(session: NativeHandle, outVariable: number, outVariableLen: number, outMessage: number, outMessageLen: number): bigint;
+    galley_diagnostic_recovery_kind(session: NativeHandle): bigint;
+    galley_diagnostic_recovery_terminal(session: NativeHandle, outData: number, outLen: number): bigint;
+    galley_diagnostic_recovery_resume(session: NativeHandle, out: number): bigint;
+    galley_diagnostic_recovery_lhs_variable(session: NativeHandle, outData: number, outLen: number): bigint;
+    galley_diagnostic_recovery_production(session: NativeHandle, outVar: number, outLen: number, outIdx: number): bigint;
+    galley_diagnostic_recovery_occurrence(session: NativeHandle, outParent: number, outParentLen: number, outRhs: number, outSym: number, outVar: number, outVarLen: number): bigint;
+    galley_recorded_diagnostic_count(session: NativeHandle): bigint;
+    galley_recorded_diagnostic_kind(session: NativeHandle, diagIndex: bigint): bigint;
+    galley_recorded_diagnostic_position(session: NativeHandle, diagIndex: bigint, outLine: number, outCol: number): bigint;
+    galley_recorded_unexpected_token(session: NativeHandle, diagIndex: bigint, outData: number, outLen: number): bigint;
+    galley_recorded_diagnostic_message(session: NativeHandle, diagIndex: bigint, out: number): bigint;
+    galley_recorded_indentation(session: NativeHandle, diagIndex: bigint, outSpaces: number, outWidth: number): bigint;
+    galley_recorded_semantic(session: NativeHandle, diagIndex: bigint, outVariable: number, outVariableLen: number, outMessage: number, outMessageLen: number): bigint;
+    galley_recorded_expected_count(session: NativeHandle, diagIndex: bigint): bigint;
+    galley_recorded_expected_token(session: NativeHandle, diagIndex: bigint, tokenIndex: bigint, outData: number, outLen: number): bigint;
+    galley_recorded_context_count(session: NativeHandle, diagIndex: bigint): bigint;
+    galley_recorded_context_name(session: NativeHandle, diagIndex: bigint, ctxIndex: bigint, outData: number, outLen: number): bigint;
+    galley_recorded_diagnostic_recovery_kind(session: NativeHandle, diagIndex: bigint): bigint;
+    galley_recorded_recovery_terminal(session: NativeHandle, diagIndex: bigint, outData: number, outLen: number): bigint;
+    galley_recorded_recovery_resume(session: NativeHandle, diagIndex: bigint, out: number): bigint;
+    galley_recorded_recovery_lhs_variable(session: NativeHandle, diagIndex: bigint, outData: number, outLen: number): bigint;
+    galley_recorded_recovery_production(session: NativeHandle, diagIndex: bigint, outVar: number, outLen: number, outIdx: number): bigint;
+    galley_recorded_recovery_occurrence(session: NativeHandle, diagIndex: bigint, outParent: number, outParentLen: number, outRhs: number, outSym: number, outVar: number, outVarLen: number): bigint;
+    galley_tree_append_children(session: NativeHandle, parent: bigint, first: bigint): bigint;
+    galley_tree_insert_before(session: NativeHandle, target: bigint, first: bigint): bigint;
+    galley_tree_insert_after(session: NativeHandle, target: bigint, first: bigint): bigint;
+    galley_tree_remove_siblings(session: NativeHandle, node: bigint, count: bigint, outHead: number): bigint;
+    galley_tree_remove_self(session: NativeHandle, node: bigint, outHead: number): bigint;
+    galley_tree_promote_children_over_wrapper(session: NativeHandle, wrapper: bigint, outHead: number): bigint;
+    galley_tree_clean_children(session: NativeHandle, node: bigint, outHead: number): bigint;
+    galley_tree_unlink_wrapper(session: NativeHandle, wrapper: bigint): bigint;
+    galley_tree_insert_children_at(session: NativeHandle, parent: bigint, index: bigint, first: bigint): bigint;
+    galley_tree_remove_children_at(session: NativeHandle, parent: bigint, index: bigint, count: bigint, outHead: number): bigint;
+    galley_procedure_session(args: NativeHandle): NativeHandle;
+    galley_procedure_current_node(args: NativeHandle): bigint;
+    galley_procedure_set_current_node(args: NativeHandle, node: bigint): void;
+    galley_procedure_drop_self(args: NativeHandle): bigint;
+    galley_procedure_drop_children(args: NativeHandle): bigint;
+    galley_procedure_drop_if_empty(args: NativeHandle): bigint;
+    galley_procedure_replace_with_children(args: NativeHandle): bigint;
+    galley_procedure_context_line(args: NativeHandle): number;
+    galley_procedure_context_column(args: NativeHandle): number;
+    galley_procedure_report_semantic_error(args: NativeHandle, message: number, messageLen: bigint): bigint;
+    galley_install_js_dispatch(callback: NativeHandle): void;
+    galley_install_js_dispatch_id?(callback: NativeHandle): void;
+    galley_js_procedure_count?(): number;
+    galley_js_procedure_name_ptr?(index: number): bigint;
+    galley_js_procedure_name_len?(index: number): bigint;
+    galley_js_procedure_enable?(name: number, nameLen: bigint): number;
+    galley_js_procedure_clear?(): void;
+}
+export declare function libFileName(base?: string): string;
+export declare function findLibrary(explicit?: string): string;
+/** Copy (addr,len) into a Uint8Array owning its bytes. */
+export declare function readBytes(addr: bigint, len: bigint): Uint8Array;
+export declare function readCString(addr: bigint): string;
+export declare class BunPort implements FfiPort {
+    #private;
+    readonly native: GalleySymbols;
+    readonly libraryPath: string;
+    readonly supportsDispatch: boolean;
+    constructor(native: GalleySymbols, libraryPath: string, supportsDispatch: boolean);
+    syncProcedures(names: string[]): void;
+    procedureNames(): string[];
+    version(): string;
+    parserType(): number;
+    errorRecoveryMode(): number;
+    hasAst(): boolean;
+    hasProcedures(): boolean;
+    allowsNoAstTreeProcedures(): boolean;
+    sourceRetentionEnabled(): boolean;
+    hasPositionTracking(): boolean;
+    hasInputStreaming(): boolean;
+    usesVerbatim(): boolean;
+    stackOverflowRecoveryAvailable(): boolean;
+    symbolCount(): number;
+    variableCount(): number;
+    statusString(status: number): string | null;
+    createSession(options: SessionCOptions | null): Handle;
+    destroySession(handle: Handle): void;
+    setMessageOverride(handle: Handle, name: Uint8Array, message: Uint8Array): number;
+    parse(handle: Handle, data: Uint8Array): number;
+    parseFile(handle: Handle, filePath: string): number;
+    lastPosition(handle: Handle): [number, number] | null;
+    nodeCount(handle: Handle): number;
+    reserveNodes(handle: Handle, capacity: bigint): number;
+    nodeCapacity(handle: Handle): number;
+    rootNode(handle: Handle): bigint;
+    nodeValid(handle: Handle, node: bigint): boolean;
+    childCount(handle: Handle, node: bigint): number;
+    firstChild(handle: Handle, node: bigint): bigint;
+    lastChild(handle: Handle, node: bigint): bigint;
+    nextSibling(handle: Handle, node: bigint): bigint;
+    priorSibling(handle: Handle, node: bigint): bigint;
+    parent(handle: Handle, node: bigint): bigint;
+    treeSnapshot(handle: Handle): TreeSnapshot;
+    walkerCreate(handle: Handle, node: bigint, skipSemanticErrors: boolean): Handle | null;
+    walkerNext(walker: Handle): WalkedStep | null;
+    walkerSkipChildren(walker: Handle): void;
+    walkerDestroy(walker: Handle): void;
+    nodeSymbolName(handle: Handle, node: bigint): Uint8Array | null;
+    nodeText(handle: Handle, node: bigint): Uint8Array | null;
+    nodeSpan(handle: Handle, node: bigint): [bigint, bigint] | null;
+    nodeLineColumn(handle: Handle, node: bigint): [number, number] | null;
+    nodeVariableIndex(handle: Handle, node: bigint): number;
+    symbolNameAt(handle: Handle, index: number): Uint8Array | null;
+    symbolIsTerminal(handle: Handle, index: number): boolean;
+    variableNameAt(handle: Handle, index: number): Uint8Array | null;
+    hasDiagnostic(handle: Handle): boolean;
+    diagnosticKind(handle: Handle): number;
+    diagnosticMessage(handle: Handle): string | null;
+    diagnosticMessageAnsi(handle: Handle): string | null;
+    diagnosticPosition(handle: Handle): [number, number] | null;
+    diagnosticUnexpectedToken(handle: Handle): Uint8Array | null;
+    diagnosticExpectedCount(handle: Handle): number;
+    diagnosticExpectedAt(handle: Handle, index: number): Uint8Array | null;
+    diagnosticContextCount(handle: Handle): number;
+    diagnosticContextAt(handle: Handle, index: number): Uint8Array | null;
+    syntaxErrorCount(handle: Handle): number;
+    semanticErrorCount(handle: Handle): number;
+    diagnosticSemantic(handle: Handle): [string, string] | null;
+    diagnosticIndentation(handle: Handle): [number, number] | null;
+    diagnosticRecoveryKind(handle: Handle): number;
+    diagnosticRecoveryTerminal(handle: Handle): Uint8Array | null;
+    diagnosticRecoveryResume(handle: Handle): number | null;
+    diagnosticRecoveryLhsVariable(handle: Handle): string | null;
+    diagnosticRecoveryProduction(handle: Handle): [string, number] | null;
+    diagnosticRecoveryOccurrence(handle: Handle): [string, number, number, string] | null;
+    recordedDiagnosticCount(handle: Handle): number;
+    recordedDiagnosticKind(handle: Handle, diagIndex: number): number;
+    recordedDiagnosticPosition(handle: Handle, diagIndex: number): [number, number] | null;
+    recordedUnexpectedToken(handle: Handle, diagIndex: number): Uint8Array | null;
+    recordedDiagnosticMessage(handle: Handle, diagIndex: number): string | null;
+    recordedIndentation(handle: Handle, diagIndex: number): [number, number] | null;
+    recordedSemantic(handle: Handle, diagIndex: number): [string, string] | null;
+    recordedExpectedCount(handle: Handle, diagIndex: number): number;
+    recordedExpectedToken(handle: Handle, diagIndex: number, tokenIndex: number): Uint8Array | null;
+    recordedContextCount(handle: Handle, diagIndex: number): number;
+    recordedContextName(handle: Handle, diagIndex: number, contextIndex: number): Uint8Array | null;
+    recordedRecoveryKind(handle: Handle, diagIndex: number): number;
+    recordedRecoveryTerminal(handle: Handle, diagIndex: number): Uint8Array | null;
+    recordedRecoveryResume(handle: Handle, diagIndex: number): number | null;
+    recordedRecoveryLhsVariable(handle: Handle, diagIndex: number): string | null;
+    recordedRecoveryProduction(handle: Handle, diagIndex: number): [string, number] | null;
+    recordedRecoveryOccurrence(handle: Handle, diagIndex: number): [string, number, number, string] | null;
+    treeAppendChildren(handle: Handle, parent: bigint, first: bigint): number;
+    treeInsertBefore(handle: Handle, target: bigint, first: bigint): number;
+    treeInsertAfter(handle: Handle, target: bigint, first: bigint): number;
+    treeRemoveSiblings(handle: Handle, node: bigint, count: number): {
+        status: number;
+        head: bigint;
+    };
+    treeRemoveSelf(handle: Handle, node: bigint): {
+        status: number;
+        head: bigint;
+    };
+    treePromoteChildrenOverWrapper(handle: Handle, wrapper: bigint): {
+        status: number;
+        head: bigint;
+    };
+    treeCleanChildren(handle: Handle, node: bigint): {
+        status: number;
+        head: bigint;
+    };
+    treeUnlinkWrapper(handle: Handle, wrapper: bigint): number;
+    treeInsertChildrenAt(handle: Handle, parent: bigint, index: number, first: bigint): number;
+    treeRemoveChildrenAt(handle: Handle, parent: bigint, index: number, count: number): {
+        status: number;
+        head: bigint;
+    };
+    procCurrentNode(args: Handle): bigint;
+    procSetCurrentNode(args: Handle, node: bigint): void;
+    procDropSelf(args: Handle): number;
+    procDropChildren(args: Handle): number;
+    procDropIfEmpty(args: Handle): number;
+    procReplaceWithChildren(args: Handle): number;
+    procContextLine(args: Handle): number;
+    procContextColumn(args: Handle): number;
+    procReportSemanticError(args: Handle, message: Uint8Array): number;
+}
+/** Port for the library at `explicitPath` (or default discovery), cached per path. */
+export declare function getBunPort(explicitPath?: string): BunPort;
+export {};