@fossil-lang/wasm 0.3.0-alpha.1

package/pkg/fossil_wasm.d.ts

@@ -0,0 +1,284 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/**
+ * Opaque handle the JS side keys on. Plain `u32` newtype; NOT the Salsa
+ * interned id (which doesn't cross the JS boundary).
+ *
+ * `Copy + Clone + Eq + Hash` so it can be a `HashMap` key on the Rust
+ * side; `#[wasm_bindgen]` so JS can pass it back across the boundary.
+ */
+export class FileHandle {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+}
+
+/**
+ * JS-facing handle for the Fossil compiler running inside a WASM module.
+ *
+ * One instance owns one [`WasmDb`] (Salsa store + injected [`WasmSystem`]
+ * + `Arc<OutputDescriptorKind>`). Hosts construct a single playground per
+ * browser tab / Node process and reuse it across all method calls to
+ * amortise the Salsa interning + memoisation overhead.
+ */
+export class FossilPlayground {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Run `parse → def_map → typecheck_mapping` across every open file and
+     * return a flat JS array of `{ uri, range, severity, message }` rows
+     * keyed by file URI. The LSP Worker (07-03) republishes these grouped
+     * by URI as `textDocument/publishDiagnostics` notifications.
+     *
+     * `range` is the UTF-16 LSP range (via `fossil_ide::LineIndex` — the
+     * rust-analyzer model from 06-05). `severity` is the LSP integer
+     * constant (1 = error, 2 = warning, 3 = info). `message` carries any
+     * `suggestion_source` as a `\nhelp: ...` suffix (mirroring `fossil-lsp`
+     * `to_lsp_diagnostic` in 06-09).
+     *
+     * # Errors
+     *
+     * Returns a JS error only if the result fails to serialize to `JsValue`.
+     */
+    check(): any;
+    /**
+     * Return the stdlib classification manifest as a JS array of
+     * `{ name, wasm_class }` objects (STDL-07).
+     *
+     * `wasm_class` is the string `"pure_sql"` or `"native_udf_only"`. The
+     * playground reads this once at startup to render `native_udf_only`
+     * functions as disabled with a "native-only — unavailable in the browser"
+     * tooltip (SC#1 playground half). `DuckDB`-WASM cannot register the Rust
+     * UDFs those functions need (Pitfall 3), so the classification is the
+     * authority on what is runnable in-browser.
+     *
+     * This is pure read-only data projected from the `&'static`-ready
+     * `fossil_registry::FunctionRegistry` — no `DuckDB`, no native UDF code,
+     * WASM-clean.
+     *
+     * # Errors
+     *
+     * Returns a JS error only if the manifest fails to serialize to `JsValue`.
+     */
+    classification(): any;
+    /**
+     * Close a file in the workspace. Idempotent in spirit but strict in
+     * signal: closing an unknown / already-closed handle is an error so
+     * JS-side bugs surface loudly (mirrors `ty_wasm`).
+     *
+     * # Errors
+     *
+     * Returns a JS error if `handle` was never opened or was already closed.
+     */
+    close_file(handle: FileHandle): void;
+    /**
+     * Per-file diagnostic drain — the B3 follow-up accessor the LSP Worker
+     * (07-03) consumes for its per-file `publishDiagnostics` notifications.
+     * `check()` returns the workspace-wide flat array; `diagnostics_for`
+     * returns just one file's rows so 07-03 can dispatch one notification
+     * per affected URI without partitioning the workspace array on the JS
+     * side.
+     *
+     * # Errors
+     *
+     * Returns a JS error if `handle` is unknown, or if serialization fails.
+     */
+    diagnostics_for(handle: FileHandle): any;
+    /**
+     * Construct a new playground.
+     *
+     * Installs `console_error_panic_hook` (idempotent — RESEARCH.md
+     * Don't-Hand-Roll #8) so any panic inside compiler-core surfaces as a
+     * `console.error` stack trace in the host (browser `DevTools` or Node).
+     */
+    constructor();
+    /**
+     * Open a file in the workspace. Returns a [`FileHandle`] the JS side
+     * keys subsequent `update_file` / `close_file` / `compile_file` calls
+     * on. `path` is the URI / virtual path the diagnostics carry back to
+     * the LSP client.
+     *
+     * Mirrors `ty_wasm::Workspace::open_file` (Astral). Interns a fresh
+     * [`fossil_base::SourceFile`] under the current Salsa revision.
+     *
+     * # Errors
+     *
+     * Returns a JS error only if the internal counter is exhausted
+     * (`u32::MAX` files — would require a runaway loop in JS, not a normal
+     * failure mode).
+     */
+    open_file(path: string, contents: string): FileHandle;
+    /**
+     * Register an [`fossil_descriptors_input::InferredDescriptor`] for a
+     * source binding name BEFORE invoking [`Self::compile`] /
+     * [`Self::compile_file`]. The Rust compiler reads from this registration
+     * during forward type propagation (Phase 3 CORE-05 rewired in plan
+     * 13-02).
+     *
+     * `descriptor_json` is the JSON serialisation of `InferredDescriptor`;
+     * the canonical shape is exposed in `packages/wasm/src/index.ts` as
+     * `InferredDescriptorJson`:
+     *
+     * ```json
+     * {
+     *   "source_name": "users",
+     *   "columns": [
+     *     { "name": "id", "primitive": "Integer" },
+     *     { "name": "name", "primitive": "String" }
+     *   ],
+     *   "content_hash": ""
+     * }
+     * ```
+     *
+     * Called by the browser-side playground orchestration AFTER running
+     * DuckDB-WASM `DESCRIBE read_csv_auto('<resolved-url>')` and BEFORE
+     * invoking `compile()` / `compile_file()`. Keyed by source-binding
+     * name (`"users"` for `users := io.csv("...")`), NOT by URL.
+     *
+     * Idempotent: re-registering with the same `source_name` OVERWRITES the
+     * previous entry — intentional, since the host may re-introspect when
+     * file content changes.
+     *
+     * # Errors
+     *
+     * - Malformed JSON / missing required fields → JS `Error` with the
+     *   underlying `serde_json` message.
+     *
+     * Implementation: thin shim over the pure-Rust
+     * [`Self::register_inferred_descriptor_native`] helper.
+     */
+    registerInferredDescriptor(descriptor_json: string): void;
+    /**
+     * Install a user-supplied `ShEx` schema as the active output descriptor.
+     * On parse failure the previously-installed descriptor is RETAINED (no
+     * half-applied state — a broken schema must never wedge the editor;
+     * same contract as `fossil-lsp`'s `load_sibling_shex` in 06-09).
+     *
+     * The schema is parsed via
+     * [`fossil_descriptors_output::ShExDescriptor::from_reader`] (no
+     * network access — Pitfall 1) and wrapped in
+     * [`OutputDescriptorKind::ShEx`]. The resulting `Arc` is swapped into
+     * the [`WasmDb`]'s descriptor slot atomically; future `fossil-ide`
+     * feature calls (hover, completion) reading
+     * [`HirDb::output_descriptor_kind`] see the new schema.
+     *
+     * # Errors
+     *
+     * Returns a JS error if the text is not a parseable `ShEx` schema.
+     */
+    set_target_shex(text: string): void;
+    /**
+     * Apply an edit to an open file. Mutates the SAME `SourceFile` via the
+     * Salsa [`salsa::Setter`] (`set_text`) — this BUMPS THE REVISION, the
+     * real cancellation trigger (ADR-0022): any in-flight analysis from the
+     * previous keystroke observes the new revision at its next cooperative
+     * checkpoint. NO new `SourceFile` is interned — the Salsa input
+     * identity stays stable across the file's lifetime, so memoised
+     * downstream queries (`def_map`, `typecheck_mapping`) invalidate
+     * incrementally instead of falling off a cliff.
+     *
+     * # Errors
+     *
+     * Returns a JS error if `handle` was never opened or was already closed.
+     */
+    update_file(handle: FileHandle, contents: string): void;
+}
+
+/**
+ * `JS`-facing re-export of the Phase-6 06-07 semantic-token legend.
+ *
+ * Returns `{ tokenTypes: string[], tokenModifiers: string[] }` — the exact
+ * LSP `SemanticTokensLegend` shape. `CodeMirror` (plan 08-08 +
+ * `packages/codemirror-fossil/src/tags.ts`) uses this to translate
+ * LSP `semanticTokens/full` response indices into highlight tag names.
+ *
+ * Delegates to [`fossil_ide::semantic_legend`] (the 06-07 authoritative
+ * definition) — NO duplicate legend definition lives here.
+ *
+ * # Errors
+ *
+ * Returns a JS error only if `serde_wasm_bindgen` fails (impossible in
+ * practice for the legend shape).
+ */
+export function semantic_legend(): any;
+
+/**
+ * Worker entrypoint. Idempotent in spirit — calling twice replaces the
+ * previous `onmessage` handler (the leaked Closure from the first call
+ * stays alive but is no longer referenced by the global scope).
+ *
+ * Must be called from a `DedicatedWorker` global scope; returns a JS error
+ * otherwise (e.g. if called from the main thread).
+ *
+ * # Errors
+ *
+ * Returns a JS error when not running inside a `DedicatedWorker` scope.
+ */
+export function start_lsp_worker(): void;
+
+/**
+ * `JS`-facing tokenize. Returns the same row stream as [`tokenize_native`],
+ * serialised via `serde_wasm_bindgen`. Consumed by
+ * `@fossil-lang/codemirror-fossil`'s `StreamParser` (plan 08-08).
+ *
+ * # Errors
+ *
+ * Returns a JS error only if `serde_wasm_bindgen` fails to serialise the
+ * row vector (effectively impossible for `Vec<{u32,u32,u32}>` — kept on the
+ * signature for forward compatibility if `TokenRow` ever grows non-trivial
+ * fields).
+ */
+export function tokenize(text: string): any;
+
+export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
+
+export interface InitOutput {
+    readonly memory: WebAssembly.Memory;
+    readonly start_lsp_worker: () => [number, number];
+    readonly tokenize: (a: number, b: number) => [number, number, number];
+    readonly semantic_legend: () => [number, number, number];
+    readonly __wbg_filehandle_free: (a: number, b: number) => void;
+    readonly __wbg_fossilplayground_free: (a: number, b: number) => void;
+    readonly fossilplayground_new: () => number;
+    readonly fossilplayground_classification: (a: number) => [number, number, number];
+    readonly fossilplayground_open_file: (a: number, b: number, c: number, d: number, e: number) => [number, number, number];
+    readonly fossilplayground_update_file: (a: number, b: number, c: number, d: number) => [number, number];
+    readonly fossilplayground_close_file: (a: number, b: number) => [number, number];
+    readonly fossilplayground_check: (a: number) => [number, number, number];
+    readonly fossilplayground_diagnostics_for: (a: number, b: number) => [number, number, number];
+    readonly fossilplayground_set_target_shex: (a: number, b: number, c: number) => [number, number];
+    readonly fossilplayground_registerInferredDescriptor: (a: number, b: number, c: number) => [number, number];
+    readonly wasm_bindgen__convert__closures_____invoke__h4393dedb0066ad40: (a: number, b: number, c: any) => void;
+    readonly __wbindgen_malloc_command_export: (a: number, b: number) => number;
+    readonly __wbindgen_realloc_command_export: (a: number, b: number, c: number, d: number) => number;
+    readonly __wbindgen_exn_store_command_export: (a: number) => void;
+    readonly __externref_table_alloc_command_export: () => number;
+    readonly __wbindgen_externrefs: WebAssembly.Table;
+    readonly __wbindgen_free_command_export: (a: number, b: number, c: number) => void;
+    readonly __wbindgen_destroy_closure_command_export: (a: number, b: number) => void;
+    readonly __externref_table_dealloc_command_export: (a: number) => void;
+    readonly __wbindgen_start: () => void;
+}
+
+export type SyncInitInput = BufferSource | WebAssembly.Module;
+
+/**
+ * Instantiates the given `module`, which can either be bytes or
+ * a precompiled `WebAssembly.Module`.
+ *
+ * @param {{ module: SyncInitInput }} module - Passing `SyncInitInput` directly is deprecated.
+ *
+ * @returns {InitOutput}
+ */
+export function initSync(module: { module: SyncInitInput } | SyncInitInput): InitOutput;
+
+/**
+ * If `module_or_path` is {RequestInfo} or {URL}, makes a request and
+ * for everything else, calls `WebAssembly.instantiate` directly.
+ *
+ * @param {{ module_or_path: InitInput | Promise<InitInput> }} module_or_path - Passing `InitInput` directly is deprecated.
+ *
+ * @returns {Promise<InitOutput>}
+ */
+export default function __wbg_init (module_or_path?: { module_or_path: InitInput | Promise<InitInput> } | InitInput | Promise<InitInput>): Promise<InitOutput>;