@reactivescript/language-server 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,101 @@
-# Temporary Holding Version
+# rx-language-server
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The `.rx` language server (spec/11 CP-8e), built on [Volar](https://volarjs.dev).
+A `.rx` file's virtual code is its TSX projection (spec/13 TY-1c), which the
+crate makes with mappings back onto the `.rx` (CP-8c). TypeScript answers hover,
+go to definition, references, rename, completion and type errors on the
+projection, and Volar maps the answers back. The crate's own diagnostics (parse
+errors, else the checker's, each with its rule) are a second service.
+
+- `src/rxc.js` asks the crate for a file's analysis, with the editor's unsaved
+  text as overlays: its WebAssembly build in process (`src/wasm.rs`; one build
+  for every platform, about a millisecond a file once loaded), or, when `RXC`
+  names a binary, `rxc serve` as a process per request. It writes the
+  projection's prelude to `node_modules/.reactivescript/prelude.d.ts`.
+- `src/index.js` is the language plugin (exact mappings carry every feature;
+  ranges only place type errors) and the diagnostics service.
+- `bin/server.js` is the server, over stdio or IPC.
+
+The project needs a `tsconfig.json` with Solid's JSX (`"jsx": "preserve"`,
+`"jsxImportSource": "@solidjs/web"`) and Solid in its `node_modules`.
+
+## Running it
+
+From npm (published from this folder, `../RELEASING.md`):
+
+```sh
+npx @reactivescript/language-server --stdio
+```
+
+From the repository:
+
+```sh
+cargo build --lib --release --target wasm32-unknown-unknown --manifest-path ../../compiler/Cargo.toml
+npm install
+node bin/server.js --stdio
+```
+
+`initializationOptions: { typescript: { tsdk } }` picks TypeScript's `lib`
+folder; without it, the server uses its own `typescript`.
+
+## Editors
+
+**VS Code** (and Cursor, VSCodium): the extension in
+[`../vscode-rx`](../vscode-rx), which bundles this server and the WebAssembly
+build.
+
+**Neovim** (0.11+), in `init.lua`:
+
+```lua
+vim.filetype.add({ extension = { rx = "reactivescript" } })
+vim.lsp.config("rx", {
+  cmd = { "node", "/path/to/reactivescript/tooling/rx-language-server/bin/server.js", "--stdio" },
+  filetypes = { "reactivescript" },
+  root_markers = { "tsconfig.json", "package.json" },
+})
+vim.lsp.enable("rx")
+```
+
+Neovim has no `.rx` grammar yet; the server's semantic tokens color names.
+
+**Helix**, in `languages.toml`:
+
+```toml
+[language-server.rx]
+command = "node"
+args = ["/path/to/reactivescript/tooling/rx-language-server/bin/server.js", "--stdio"]
+
+[[language]]
+name = "reactivescript"
+scope = "source.rx"
+file-types = ["rx"]
+roots = ["tsconfig.json", "package.json"]
+language-servers = ["rx"]
+```
+
+**JetBrains IDEs** (WebStorm, IntelliJ): install the
+[LSP4IJ](https://plugins.jetbrains.com/plugin/23257-lsp4ij) plugin, add a
+language server with the command
+`node /path/to/reactivescript/tooling/rx-language-server/bin/server.js --stdio`,
+map the file name pattern `*.rx` to it, and add the `tooling/vscode-rx`
+folder under Settings › Editor › TextMate Bundles for highlighting.
+
+**Zed** needs an extension of its own (a Zed extension declares the language
+and starts the server); there isn't one yet.
+
+The `/path/to/reactivescript` paths are a checkout of this repository; with
+the npm package, the command is `npx @reactivescript/language-server --stdio`
+instead (or `rx-language-server --stdio` once installed).
+
+## Tests
+
+```sh
+cargo build --release --manifest-path ../../compiler/Cargo.toml
+npm install && node test/run.js      # VERBOSE=1 prints each answer
+```
+
+`test/run.js` drives the server over LSP on a copy of `examples/shop` (Solid's
+types from `ref/node_modules`, via `ref/scripts/solid-next.sh`): hover, go to
+definition across modules, references, completion while typing (in code and in
+markup), a parse error, a TypeScript type error and a crate diagnostic, each
+placed on the `.rx`.

package/bin/server.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+// The .rx language server over stdio (or whatever transport the client asks for): Volar's TypeScript project with the
+// .rx language plugin, TypeScript's services, and the crate's diagnostics.
+const { createConnection, createServer, createTypeScriptProject, loadTsdkByPath } = require("@volar/language-server/node");
+const { create: createTypeScriptServices } = require("volar-service-typescript");
+const { rxLanguagePlugin, rxDiagnostics } = require("../src/index.js");
+
+const connection = createConnection();
+const server = createServer(connection);
+
+connection.listen();
+
+connection.onInitialize(params => {
+  const tsdkPath = params.initializationOptions?.typescript?.tsdk ?? require("node:path").dirname(require.resolve("typescript"));
+  const tsdk = loadTsdkByPath(tsdkPath, params.locale);
+  return server.initialize(
+    params,
+    createTypeScriptProject(tsdk.typescript, tsdk.diagnosticMessages, () => ({ languagePlugins: [rxLanguagePlugin(tsdk.typescript)] })),
+    [...createTypeScriptServices(tsdk.typescript), rxDiagnostics()],
+  );
+});
+
+connection.onInitialized(server.initialized);
+connection.onShutdown(server.shutdown);

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "@reactivescript/language-server",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "The .rx language server (spec/11 CP-8): Volar over the crate's TSX projection, TypeScript's answers mapped back onto .rx, the crate's own diagnostics.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/solidjs/reactivescript.git",
+    "directory": "tooling/rx-language-server"
+  },
+  "type": "commonjs",
+  "bin": {
+    "rx-language-server": "./bin/server.js"
+  },
+  "main": "./src/index.js",
+  "files": [
+    "bin",
+    "src"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node test/run.js",
+    "prepack": "node scripts/wasm.js"
+  },
+  "dependencies": {
+    "@volar/language-core": "2.4.30",
+    "@volar/language-server": "2.4.30",
+    "@volar/typescript": "2.4.30",
+    "volar-service-typescript": "0.0.71",
+    "vscode-uri": "^3.0.8",
+    "typescript": "^6.0.3"
+  },
+  "devDependencies": {
+    "@volar/test-utils": "2.4.30"
+  }
+}

package/src/index.js

@@ -0,0 +1,98 @@
+// The .rx language plugin for Volar (spec/11 CP-8). A `.rx` file's virtual code is its TSX projection (spec/13 TY-1c),
+// made by the crate with mappings onto the `.rx`: TypeScript's hover, definition, references, rename, completion and
+// type errors come back through them. The crate's own diagnostics (rule IDs, spec/99) are a service of their own.
+const { analyze, preludeFor } = require("./rxc");
+
+/** Every feature, where the projection copies the `.rx`'s text (a name, a member, a literal, a type, a tag). */
+const EXACT = { verification: true, completion: true, semantic: true, navigation: true, structure: true, format: false };
+/** Where it wrote text for a piece of the `.rx` (an expression, a statement): only for placing type errors. */
+const COARSE = { verification: true };
+
+/** A module: `.rx`, not a declaration file (`.d.rx`, MO-8/MO-9), which the crate reads beside the modules that import it. */
+const isModule = f => f.endsWith(".rx") && !f.endsWith(".d.rx");
+
+const snapshotOf = text => ({ getText: (s, e) => text.slice(s, e), getLength: () => text.length, getChangeRange: () => undefined });
+
+/** The last analysis of each file, by its text: the virtual code and the diagnostics share one `rxc` run. */
+const cache = new Map();
+function analysis(file, text) {
+  const hit = cache.get(file);
+  if (hit && hit.text === text) return hit.result;
+  let result;
+  try { result = analyze(file, text, preludeFor(file)); } catch (e) {
+    console.error(`rx: analyzing ${file} failed: ${e?.stack ?? e}`); // the server's log, else the failure is silent
+    result = { code: null, mappings: [], ranges: [], diagnostics: [], error: String(e) };
+  }
+  cache.set(file, { text, result });
+  return result;
+}
+
+function virtualCode(file, snapshot) {
+  const text = snapshot.getText(0, snapshot.getLength());
+  const a = analysis(file, text);
+  const code = a.code ?? "";
+  const mappings = [
+    ...(a.mappings ?? []).map(([g, s, n]) => ({ sourceOffsets: [s], generatedOffsets: [g], lengths: [n], data: EXACT })),
+    ...(a.ranges ?? []).map(([g, gn, s, n]) => ({ sourceOffsets: [s], generatedOffsets: [g], lengths: [n], generatedLengths: [gn], data: COARSE })),
+  ];
+  return {
+    id: "root",
+    languageId: "reactivescript",
+    snapshot,
+    mappings: [{ sourceOffsets: [0], generatedOffsets: [0], lengths: [text.length], data: { verification: true, completion: true, semantic: true, navigation: true, structure: true, format: true } }],
+    embeddedCodes: [{ id: "tsx", languageId: "typescriptreact", snapshot: snapshotOf(code), mappings }],
+  };
+}
+
+/** @param {typeof import("typescript")} ts */
+function rxLanguagePlugin(ts, asFileName = uri => uri.fsPath ?? String(uri)) {
+  return {
+    getLanguageId(id) { return isModule(String(id.path ?? id)) ? "reactivescript" : undefined; },
+    createVirtualCode(id, languageId, snapshot) {
+      if (languageId !== "reactivescript" || !isModule(asFileName(id))) return undefined;
+      return virtualCode(asFileName(id), snapshot);
+    },
+    typescript: {
+      extraFileExtensions: [{ extension: "rx", isMixedContent: true, scriptKind: ts.ScriptKind.Deferred }],
+      getServiceScript(root) {
+        const tsx = root.embeddedCodes?.find(c => c.id === "tsx");
+        return tsx ? { code: tsx, extension: ".tsx", scriptKind: ts.ScriptKind.TSX } : undefined;
+      },
+    },
+  };
+}
+
+/** The crate's diagnostics on a `.rx` document: the editor's parse's errors, else the checker's (CP-8d). Volar hands
+ *  the service the root virtual code's document, whose URI encodes the `.rx` file's. */
+function rxDiagnostics() {
+  return {
+    name: "reactivescript-diagnostics",
+    capabilities: { diagnosticProvider: { interFileDependencies: true, workspaceDiagnostics: false } },
+    create(context) {
+      return {
+        provideDiagnostics(document) {
+          if (document.languageId !== "reactivescript") return;
+          const { URI } = require("vscode-uri");
+          const uri = URI.parse(document.uri);
+          const source = context.decodeEmbeddedDocumentUri(uri)?.[0] ?? uri;
+          if (source.scheme !== "file") return;
+          const file = source.fsPath;
+          if (!isModule(file)) return;
+          const a = analysis(file, document.getText());
+          return (a.diagnostics ?? []).filter(d => d.range).map(d => ({
+            range: {
+              start: { line: d.range.start.line - 1, character: d.range.start.column },
+              end: { line: d.range.end.line - 1, character: d.range.end.column },
+            },
+            severity: 1,
+            source: "rx",
+            code: d.code,
+            message: `${d.message} (${d.rule})`,
+          }));
+        },
+      };
+    },
+  };
+}
+
+module.exports = { rxLanguagePlugin, rxDiagnostics, analysis };

package/src/rxc.js

@@ -0,0 +1,94 @@
+// The crate's side of the server: `rxc serve`'s requests (spec/11 CP-8e). Volar asks for a file's virtual code
+// synchronously, so the requests are synchronous calls: into the crate's WebAssembly build, loaded in process (one build
+// for every platform), or, when $RXC names a binary, a short `rxc serve` run per request.
+const { spawnSync } = require("node:child_process");
+const { existsSync, mkdirSync, writeFileSync, readFileSync, statSync } = require("node:fs");
+const path = require("node:path");
+
+const repo = path.resolve(__dirname, "../../..");
+
+/** The `rxc` binary, when $RXC names one. */
+function rxcPath() {
+  return process.env.RXC || path.join(repo, "compiler/target/release/rxc");
+}
+
+/** The WebAssembly build: $RX_WASM, else the one bundled beside this file (the packaged extension), else the
+ *  repository's (`cargo build --lib --release --target wasm32-unknown-unknown`). */
+function wasmPath() {
+  if (process.env.RX_WASM) return process.env.RX_WASM;
+  for (const f of [path.join(__dirname, "rxc.wasm"), path.join(repo, "compiler/target/wasm32-unknown-unknown/release/reactivescript.wasm")]) if (existsSync(f)) return f;
+  return undefined;
+}
+
+/** The crate in process, over `src/wasm.rs`'s ABI. */
+function loadWasm(file) {
+  let x;
+  const enc = new TextEncoder(), dec = new TextDecoder();
+  const put = bytes => {
+    const p = x.rx_alloc(bytes.length + 4);
+    const m = new Uint8Array(x.memory.buffer);
+    new DataView(x.memory.buffer).setUint32(p, bytes.length, true);
+    m.set(bytes, p + 4);
+    return p;
+  };
+  const env = {
+    rx_read(ptr, len) {
+      const f = dec.decode(new Uint8Array(x.memory.buffer, ptr, len));
+      try { if (!statSync(f).isFile()) return 0; return put(readFileSync(f)); } catch { return 0; }
+    },
+  };
+  x = new WebAssembly.Instance(new WebAssembly.Module(readFileSync(file)), { env }).exports;
+  return (method, params) => {
+    const req = enc.encode(JSON.stringify({ method, params }));
+    const p = x.rx_alloc(req.length);
+    new Uint8Array(x.memory.buffer).set(req, p);
+    const out = x.rx_call(p, req.length);
+    const n = new DataView(x.memory.buffer).getUint32(out, true);
+    const text = dec.decode(new Uint8Array(x.memory.buffer, out + 4, n));
+    x.rx_free(out, n + 4);
+    return JSON.parse(text);
+  };
+}
+
+function viaProcess(method, params) {
+  const r = spawnSync(rxcPath(), ["serve"], { input: JSON.stringify({ id: 1, method, params }) + "\n", maxBuffer: 1 << 28 });
+  if (r.error) throw r.error;
+  const line = r.stdout.toString().split("\n").find(Boolean);
+  if (!line) throw new Error(`rxc serve: no answer (${r.stderr.toString().slice(0, 300)})`);
+  return JSON.parse(line).result;
+}
+
+let wasm;
+function ask(method, params) {
+  if (process.env.RXC || !wasmPath()) return viaProcess(method, params);
+  try {
+    return (wasm ??= loadWasm(wasmPath()))(method, params);
+  } catch (e) {
+    wasm = undefined; // a trap (a panic in the crate) leaves the instance unusable: the next request makes a new one
+    throw e;
+  }
+}
+
+/** A file's projection (`code`, `mappings`, `ranges`, UTF-16 offsets) and its diagnostics, as the editor has it. */
+function analyze(file, text, prelude) {
+  return ask("analyze", { file, overlays: { [file]: text }, prelude });
+}
+
+/** Where a file's projection imports the prelude from: written once beside the nearest `node_modules`, so its own
+ *  `@solidjs/web` resolves; a `.d.ts`, so the import needs no extension. */
+const preludes = new Map();
+function preludeFor(file) {
+  let dir = path.dirname(file);
+  while (!existsSync(path.join(dir, "node_modules")) && path.dirname(dir) !== dir) dir = path.dirname(dir);
+  const at = path.join(dir, "node_modules", ".reactivescript", "prelude");
+  if (!preludes.has(at)) {
+    const text = ask("prelude", {});
+    mkdirSync(path.dirname(at), { recursive: true });
+    const f = at + ".d.ts";
+    if (!existsSync(f) || readFileSync(f, "utf8") !== text) writeFileSync(f, text);
+    preludes.set(at, true);
+  }
+  return at;
+}
+
+module.exports = { analyze, preludeFor, rxcPath, wasmPath };