@fossil-lang/wasm 0.3.0-alpha.2 → 0.3.0-alpha.5

package/pkg/fossil_wasm.d.ts

@@ -7,6 +7,24 @@
  *
  * `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.
+ *
+ * # Every exported method takes `&FileHandle`, and it has to
+ *
+ * wasm-bindgen CONSUMES an exported struct passed by value: the generated glue
+ * calls `__destroy_into_raw()` on the JS wrapper, which nulls its pointer. A
+ * handle passed by value is therefore good for exactly one call, and the second
+ * throws *"null pointer passed to rust"* — from inside a method that has nothing
+ * wrong with it, naming no handle and no file.
+ *
+ * `Copy` does not save it. The derive is a Rust-side property; nothing about it
+ * reaches the JS boundary, where this is a class holding a pointer like any
+ * other. The three methods a host calls repeatedly with one handle
+ * (`update_file`, `close_file`, `diagnostics_for`) take `&FileHandle` so
+ * wasm-bindgen borrows instead, and the handle stays live across the whole
+ * lifetime `open_file`'s doc comment promises.
+ *
+ * This was reachable from the FIRST loop an editor runs: `updateFile(h, text)` on
+ * every check, with the handle `openFile` returned once.
  */
 export class FileHandle {
     private constructor();
@@ -15,163 +33,178 @@ export class FileHandle {
 }
 
 /**
- * JS-facing handle for the Fossil compiler running inside a WASM module.
+ * The JS-facing workspace — `FossilPlayground` on the JS side, and a
+ * `RefCell` around the Rust one.
+ *
+ * # Why the interior `RefCell`, and it is not a style choice
+ *
+ * `wasm-bindgen` wraps every exported struct in its own `WasmRefCell`. A
+ * method taking `&mut self` borrows that cell EXCLUSIVELY for the call, and a
+ * failed borrow does not return — it panics, with
+ * *"recursive use of an object detected which would lead to unsafe aliasing in
+ * rust"*. On `wasm32-unknown-unknown` a panic is an abort: the trap unwinds
+ * nothing, so the borrow flag it was holding is never cleared, and **every
+ * later call on that object fails the same way for the life of the module.**
+ * One bad call poisons the workspace permanently.
+ *
+ * That is a real defect and it was reachable from correct host code:
+ * `apps/playground` reproduced it by typing sixteen characters faster than its
+ * debounce, and the app carried a `busy` flag and a 120 ms coalesce to stay
+ * out of it. A mitigation a host has to remember is not a fix — and an editor
+ * is precisely the workload that forgets.
+ *
+ * So no exported method takes `&mut self`. Every one takes `&self`, which
+ * wasm-bindgen borrows SHARED — shared borrows nest, so re-entry cannot fail
+ * there — and the mutation goes through this `RefCell` with
+ * `try_borrow_mut`. Genuine re-entry (a JS callback that calls back in while a
+ * call is live) now returns a catchable `Error` naming what happened, and
+ * **the workspace is still usable afterwards**, because a returned `Err` drops
+ * its guard where a panic did not.
  *
- * 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.
+ * The Rust-side [`FossilPlayground`] keeps its `&mut self` signatures
+ * untouched: `lsp_worker` already owns it inside an `Rc<RefCell<…>>`, and the
+ * native tests drive it directly. Only the JS boundary changed.
  */
 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.
+     * Every open **program**'s diagnostics as a flat JS array of
+     * `{ uri, range, severity, message }` rows keyed by file URI — the
+     * playground's panel view. It is NOT what the LSP Worker publishes; see
+     * [`CheckRow`], and `lsp_worker::publish_diagnostics` for the wire.
+     *
+     * A buffer the installed provider catalogue claims — the `.shex` the
+     * playground had to open to give the compiler a document, a `.csv`, a
+     * `.parquet` — is an INPUT and is not parsed as fossil.
+     * [`fossil_ide::diagnostics()`] is where that is said and measured, for both
+     * hosts.
      *
      * `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).
+     * rust-analyzer model). `severity` is the LSP integer constant
+     * (1 = error, 2 = warning, 3 = info). `message` carries any
+     * `suggestion_source` as a `\nhelp: ...` suffix. All three come from
+     * [`fossil_ide::lsp_diagnostic`], the rendering an editor is shown.
      *
      * # Errors
      *
-     * Returns a JS error only if the result fails to serialize to `JsValue`.
+     * Returns a JS error if the workspace is busy, or 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).
+     * 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,
+     * or if the workspace is busy.
+     */
+    close_file(handle: FileHandle): void;
+    /**
+     * The completion candidates at a position: `{ label, kind, detail }` rows,
+     * already narrowed by the receiver — `str.` offers string members and no
+     * reader, a property key position offers the target shape's predicates and
+     * no catalogue row.
+     *
+     * `kind` is the LSP `CompletionItemKind` **by name** (`"function"`,
+     * `"field"`). See [`ide::CompletionRow`] for why a number does not cross
+     * this boundary.
      *
-     * `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.
+     * # Errors
      *
-     * This is pure read-only data projected from the `&'static`-ready
-     * `fossil_registry::FunctionRegistry` — no `DuckDB`, no native UDF code,
-     * WASM-clean.
+     * Returns a JS error if the workspace is busy, or if the result fails to
+     * serialize to `JsValue`. An unknown handle is an empty array.
+     */
+    completions(handle: FileHandle, line: number, character: number): any;
+    /**
+     * Per-file diagnostic drain: `check()` returns the workspace-wide flat
+     * array, this returns one file's rows, so a host can refresh one buffer's
+     * panel without partitioning the workspace array on the JS side. It is NOT
+     * what the LSP Worker publishes — that is
+     * [`fossil_ide::lsp_diagnostics`], through `lsp_worker::publish_diagnostics`.
      *
      * # Errors
      *
-     * Returns a JS error only if the manifest fails to serialize to `JsValue`.
+     * Returns a JS error if `handle` is unknown, if the workspace is busy, or
+     * if serialization fails.
      */
-    classification(): any;
+    diagnostics_for(handle: FileHandle): 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`).
+     * Where the name under the cursor is defined: `{ uri, range }` rows, empty
+     * when nothing there has a definition.
+     *
+     * `uri` is the key the host opened the buffer under, verbatim — and two of
+     * the three positions goto-def recognises resolve into the shape document,
+     * so a host with one pane has to read it before moving a cursor.
      *
      * # Errors
      *
-     * Returns a JS error if `handle` was never opened or was already closed.
+     * Returns a JS error if the workspace is busy, or if the result fails to
+     * serialize to `JsValue`.
      */
-    close_file(handle: FileHandle): void;
+    gotoDefinition(handle: FileHandle, line: number, character: number): any;
     /**
-     * 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.
+     * What is under the cursor: `{ markdown, range }`, or `null` when the
+     * cursor is on whitespace, on an expression the checker inferred no type
+     * for, or outside any mapping.
+     *
+     * `line` / `character` are LSP — zero-based, and `character` in UTF-16
+     * code units, which is what a JS host counts in anyway. The `range` comes
+     * back in the same units.
      *
      * # Errors
      *
-     * Returns a JS error if `handle` is unknown, or if serialization fails.
+     * Returns a JS error if the workspace is busy, or if the result fails to
+     * serialize to `JsValue`. An unknown handle is `null`, not an error —
+     * see [`FossilPlayground::hover_row`].
      */
-    diagnostics_for(handle: FileHandle): any;
+    hover(handle: FileHandle, line: number, character: number): 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).
+     * Installs `console_error_panic_hook` (idempotent) 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.
+     * keys subsequent `update_file` / `close_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).
+     * Returns a JS error if the workspace is already inside another call —
+     * see the type-level note on [`WasmPlayground`].
      */
     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).
+     * source binding name BEFORE invoking `check`. The Rust compiler reads
+     * from this registration during forward type propagation — the browser has
+     * no filesystem to introspect a CSV from, so the column types must arrive
+     * from the host.
      *
-     * `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.
+     * Registering the same URI twice REPLACES the previous descriptor
+     * — intentional, since the host re-introspects when the source 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.
+     * - The workspace is busy.
      */
     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
+     * real cancellation trigger: 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
@@ -180,21 +213,46 @@ export class FossilPlayground {
      *
      * # Errors
      *
-     * Returns a JS error if `handle` was never opened or was already closed.
+     * Returns a JS error if `handle` was never opened or was already closed,
+     * or if the workspace is already inside another call — see the type-level
+     * note on [`WasmPlayground`]. **Neither leaves the workspace unusable**,
+     * which is the whole reason this method takes `&self`.
      */
     update_file(handle: FileHandle, contents: string): void;
 }
 
 /**
- * `JS`-facing re-export of the Phase-6 06-07 semantic-token legend.
+ * The providers this host installs (`io.csv`, `io.rdf`, `io.shex`, …) as a JS
+ * array of `{ name, extensions, kind }`. Pure projection of the provider
+ * registry — no parsing, no db. `kind` is read off each row's capabilities, so
+ * the two shape-document rows come back as `Schema`.
+ *
+ * # Errors
+ * Returns a JS error only if the result fails to serialize to `JsValue`.
+ */
+export function providers(): any;
+
+/**
+ * Parse `program` and return its external references — every data URI +
+ * `schema =` argument, each tagged with its `@conn` alias (`null` for a direct
+ * path) and role (`Data` / `Schema`) — as a JS array of
+ * `{ connection, path, role }`. Parse-only; the host resolves `@conn` →
+ * `{base}/path` itself (its data-plane job, kept out of fossil's semantics).
+ *
+ * # Errors
+ * Returns a JS error only if the result fails to serialize to `JsValue`.
+ */
+export function refs(program: string): any;
+
+/**
+ * `JS`-facing re-export of the 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.
+ * LSP `SemanticTokensLegend` shape, which is what turns the indices in a
+ * `semanticTokens/full` response into names a host can style.
  *
- * Delegates to [`fossil_ide::semantic_legend`] (the 06-07 authoritative
- * definition) — NO duplicate legend definition lives here.
+ * Delegates to [`fossil_ide::semantic_legend`], the one definition — a second
+ * legend here would desynchronise the indices the native LSP already emits.
  *
  * # Errors
  *
@@ -217,10 +275,31 @@ export function semantic_legend(): any;
  */
 export function start_lsp_worker(): void;
 
+/**
+ * The name of every [`TokenRow::kind`], indexed BY that kind.
+ *
+ * `token_kinds()[row.kind]` is the variant name — `"Comment"`, `"KwFrom"`,
+ * `"String"`. A host maps names to highlight categories and never writes a
+ * discriminant down, which is the only version of this contract that survives
+ * a reorder of the lexer.
+ *
+ * This is the same move [`semantic_legend`] makes for LSP semantic tokens: the
+ * indices are meaningless without the legend, so ship the legend.
+ *
+ * A kind past the end of the array is a variant appended by a newer compiler
+ * than the host was built against. That is BACKWARDS-COMPATIBLE by
+ * construction: the host sees `undefined` and styles the span as plain text.
+ *
+ * # Errors
+ *
+ * Returns a JS error only if `serde_wasm_bindgen` fails to serialise a
+ * `Vec<&str>` (impossible in practice).
+ */
+export function tokenKinds(): any;
+
 /**
  * `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).
+ * serialised via `serde_wasm_bindgen`.
  *
  * # Errors
  *
@@ -238,18 +317,22 @@ export interface InitOutput {
     readonly start_lsp_worker: () => [number, number];
     readonly tokenize: (a: number, b: number) => [number, number, number];
     readonly semantic_legend: () => [number, number, number];
+    readonly tokenKinds: () => [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_hover: (a: number, b: number, c: number, d: number) => [number, number, number];
+    readonly fossilplayground_completions: (a: number, b: number, c: number, d: number) => [number, number, number];
+    readonly fossilplayground_gotoDefinition: (a: number, b: number, c: number, d: number) => [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 providers: () => [number, number, number];
+    readonly refs: (a: number, b: number) => [number, number, number];
+    readonly wasm_bindgen__convert__closures_____invoke__h900f85fb942a113b: (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;