pike-language-server 0.8.49

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 TheSmuks
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,45 @@
+# Pike Language Server
+
+Tier-3 LSP implementation for [Pike](https://pike.lysator.liu.se/), for any
+LSP-capable editor. Runs on Node 18+ or Bun — nothing to build.
+
+## Install
+
+    npm install -g pike-language-server
+
+## Use
+
+    pike-language-server --stdio
+
+### Helix — `~/.config/helix/languages.toml`
+
+    [language-server.pike-lsp]
+    command = "pike-language-server"
+    args = ["--stdio"]
+
+    [[language]]
+    name = "pike"
+    scope = "source.pike"
+    file-types = ["pike", "pmod", "mmod"]
+    comment-token = "//"
+    indent = { tab-width = 2, unit = "  " }
+    roots = ["pike.json", ".git"]
+    language-servers = ["pike-lsp"]
+
+Full guide, including syntax highlighting:
+[docs/helix-installation.md](docs/helix-installation.md)
+
+### Neovim and other clients
+
+[docs/other-editors.md](docs/other-editors.md)
+
+## Diagnostics
+
+Install [Pike](https://pike.lysator.liu.se/) 8.0+ and keep `pike` on PATH.
+Every other feature works without it.
+
+## VS Code
+
+Use the
+[marketplace extension](https://marketplace.visualstudio.com/items?itemName=thesmuks.pike-language-server)
+instead — this package is for other editors.

package/bin/pike-language-server

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+/**
+ * Pike Language Server — executable entry point.
+ *
+ * Speaks LSP over stdio. Point your editor at this file:
+ *   pike-language-server --stdio
+ *
+ * Runs the server in-process on whichever runtime launched it (Node or Bun) —
+ * the standalone bundle is built with a createRequire banner so it works on
+ * both. It used to spawn a `bun` child process, which made Bun a hard
+ * requirement and broke `npx pike-language-server` for Node-only users.
+ *
+ * Resolves the bundle from either layout:
+ *   - npm package:  <pkg>/standalone/server.js
+ *   - repo clone:   <repo>/standalone/server.js   (after build:standalone)
+ */
+
+import { resolve, dirname } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { existsSync } from "node:fs";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const serverPath = resolve(here, "..", "standalone", "server.js");
+
+if (!existsSync(serverPath)) {
+  process.stderr.write(
+    `pike-language-server: server bundle not found at ${serverPath}\n` +
+    `If you are running from a clone, build it first:\n` +
+    `  bun install && bun run build:standalone\n`,
+  );
+  process.exit(1);
+}
+
+// main.ts starts listening only when PIKE_LSP_STDIO=1 or --stdio is present.
+// Default to stdio so a bare `pike-language-server` still serves, and keep the
+// env var so an explicit --socket=/--node-ipc transport also starts listening.
+const args = process.argv.slice(2);
+if (!args.some(a => a === "--stdio" || a === "--node-ipc" || a.startsWith("--socket="))) {
+  process.argv.push("--stdio");
+}
+process.env.PIKE_LSP_STDIO = "1";
+
+// ─── V8 memory flags (Node only) ────────────────────────────────────────────
+//
+// The VSCode client launches the server with --max-old-space-size and
+// --expose-gc: the cap bounds V8's allocation high-water during indexing
+// bursts (measured on Pike's own stdlib: ~620MB uncapped vs ~335MB capped,
+// with no latency cost), and --expose-gc lets the memory governor force a
+// collection under budget pressure. Editors that launch this script directly
+// (Neovim, Helix) would get neither, so re-exec Node once with the same flags.
+//
+// Skipped when: already re-execed; running under Bun (no V8 flags); or the
+// user supplied their own Node flags (an explicit execArgv wins).
+// PIKE_LSP_MEMORY_BUDGET_MB overrides the 512MB default budget; the cap
+// formula mirrors computeHeapCapMb in the VSCode client.
+const isNode = !process.versions.bun;
+if (isNode && !process.env.PIKE_LSP_NO_REEXEC && process.execArgv.length === 0) {
+  const rawBudget = Number.parseInt(process.env.PIKE_LSP_MEMORY_BUDGET_MB ?? "512", 10);
+  const budget = Number.isFinite(rawBudget) ? Math.min(8192, Math.max(64, rawBudget)) : 512;
+  const capMb = Math.max(budget + 256, Math.round(budget * 1.5));
+
+  const { spawn } = await import("node:child_process");
+  const child = spawn(
+    process.execPath,
+    [`--max-old-space-size=${capMb}`, "--expose-gc", fileURLToPath(import.meta.url), ...process.argv.slice(2)],
+    {
+      stdio: "inherit",
+      env: { ...process.env, PIKE_LSP_NO_REEXEC: "1" },
+    },
+  );
+  // Mirror the child's lifecycle: the editor manages THIS process, so its
+  // signals must reach the server and the server's exit code must come back.
+  for (const signal of ["SIGTERM", "SIGINT", "SIGHUP"]) {
+    process.on(signal, () => child.kill(signal));
+  }
+  child.on("exit", (code, signal) => {
+    if (signal) process.kill(process.pid, signal);
+    process.exit(code ?? 0);
+  });
+} else {
+  // pathToFileURL: a bare Windows path (C:\...) is not a valid import specifier.
+  await import(pathToFileURL(serverPath).href);
+}

package/docs/helix-installation.md

@@ -0,0 +1,275 @@
+# Installing the Pike Language Server for Helix
+
+A complete, step-by-step setup for Helix — from nothing to a working Pike LSP
+with syntax highlighting.
+
+Verified against **Helix 25.01.1** on Linux. Every command and config block
+below was run end-to-end against a real Helix install.
+
+Helix needs two independent things, and they are configured separately:
+
+| What | Gives you | Needs |
+|------|-----------|-------|
+| **Language server** | hover, completion, goto, references, rename, diagnostics | `[language-server.pike-lsp]` + `[[language]]` |
+| **Tree-sitter grammar** | syntax highlighting | `[[grammar]]` + `hx --grammar build` + highlight queries |
+
+Setting up only the first leaves you with a working LSP and **no highlighting**.
+Steps 1–5 cover the LSP; step 6 covers highlighting.
+
+---
+
+## 1. Install Helix
+
+Follow the official instructions: <https://docs.helix-editor.com/install.html>
+
+Verify:
+
+```bash
+hx --version
+```
+
+## 2. Install the server
+
+Pick **one**. Nothing here requires cloning or building.
+
+[Pike](https://pike.lysator.liu.se/) 8.0+ on `PATH` is optional: it powers
+diagnostics only. Hover, completion, goto, references, and rename all work
+without it.
+
+### a. Native binary — no runtime at all (simplest)
+
+One self-contained executable. No Node, no Bun.
+
+```bash
+# pick your platform: linux-x64, linux-arm64, darwin-x64, darwin-arm64, windows-x64.exe
+curl -L -o pike-language-server \
+  https://github.com/TheSmuks/pike-language-server/releases/latest/download/pike-language-server-linux-x64
+chmod +x pike-language-server
+sudo mv pike-language-server /usr/local/bin/
+```
+
+The binary embeds its own tree-sitter grammar and stdlib index, so it works from
+anywhere. It is ~90MB — that is a whole JavaScript runtime inside.
+
+### b. npm — needs Node 18+ (easiest to update)
+
+```bash
+npm install -g pike-language-server
+```
+
+### c. Tarball — needs Node 18+ or Bun
+
+```bash
+curl -L https://github.com/TheSmuks/pike-language-server/releases/latest/download/pike-language-server-standalone.tar.gz \
+  | tar xz -C ~/.local/share
+```
+
+Extracts to `~/.local/share/pike-language-server/`. Keep the `.wasm` and `.json`
+files next to `server.js` — they are resolved relative to it.
+
+### Verify
+
+```bash
+pike-language-server --stdio    # binary or npm
+```
+
+It waits silently for LSP traffic on stdin; `Ctrl-D` exits. (It will also exit
+immediately on end-of-input, which is normal — a client keeps the stream open.)
+
+### d. From source
+
+Only if you want to modify the server:
+
+```bash
+git clone https://github.com/TheSmuks/pike-language-server.git
+cd pike-language-server
+bun install
+bun run build:standalone
+bun run check:standalone   # asserts it really answers LSP
+```
+
+## 4. Configure Helix
+
+Add to `~/.config/helix/languages.toml` (create the file if it does not exist).
+
+If you installed the **binary** or the **npm package**, `command` is just the
+executable name:
+
+```toml
+[language-server.pike-lsp]
+command = "pike-language-server"
+args = ["--stdio"]
+# Optional — see "Helix configuration" below:
+# config = { diagnosticMode = "realtime" }
+
+[[language]]
+name = "pike"
+scope = "source.pike"
+file-types = ["pike", "pmod", "mmod"]
+comment-token = "//"
+indent = { tab-width = 2, unit = "  " }
+roots = ["pike.json", ".git"]
+language-servers = ["pike-lsp"]
+```
+
+If you installed the **tarball** (or built from source), replace the first two
+lines with the interpreter plus the path to `server.js` — everything else is
+identical:
+
+```toml
+command = "node"                                    # or "bun"
+args = ["/home/you/.local/share/pike-language-server/server.js", "--stdio"]
+```
+
+Helix ships no built-in Pike language, so you define it yourself. Two fields are
+easy to omit and both are fatal:
+
+- **`scope` is mandatory.** Without it Helix rejects the *entire* user language
+  config — every language, not just Pike — and falls back to defaults.
+- **`file-types` is what attaches Pike to your files.** Without it, Helix never
+  recognises a `.pike` file and the server never starts.
+
+## 5. Verify the language server
+
+```bash
+hx --health pike
+```
+
+You want a green check next to `bun`:
+
+```
+Configured language servers:
+  ✓ bun: /home/you/.bun/bin/bun
+```
+
+Then open a Pike file and confirm the server actually attached:
+
+```bash
+hx -v some-file.pike
+```
+
+`-v` logs LSP traffic to `~/.cache/helix/helix.log`. In another shell:
+
+```bash
+grep -c "pike-lsp" ~/.cache/helix/helix.log
+```
+
+A non-zero count means Helix and the server are talking. Inside the editor,
+`gd` (goto definition), `K` (hover), and `<space>r` (rename) should now work.
+
+At this point the LSP is fully working, but the file is **not highlighted**.
+
+## 6. Syntax highlighting
+
+Highlighting is tree-sitter, entirely separate from the LSP. It needs a
+compiled grammar **and** highlight queries — one without the other gives you
+nothing.
+
+Add the grammar to the same `~/.config/helix/languages.toml`:
+
+```toml
+[[grammar]]
+name = "pike"
+source = { git = "https://github.com/TheSmuks/tree-sitter-pike", rev = "main" }
+```
+
+Fetch and compile it, then install the queries from this repository:
+
+```bash
+hx --grammar fetch
+hx --grammar build
+mkdir -p ~/.config/helix/runtime/queries/pike/
+cp queries/highlights.scm ~/.config/helix/runtime/queries/pike/highlights.scm
+```
+
+`hx --grammar fetch` and `build` operate on *every* grammar Helix knows about,
+so they take a while and may report unrelated grammars failing — that is
+expected and harmless. Only the Pike result matters:
+
+```bash
+hx --health pike
+```
+
+```
+Tree-sitter parser: ✓
+Highlight queries: ✓
+Textobject queries: ✘
+Indent queries: ✘
+```
+
+`Textobject` and `Indent` stay `✘` — this repository ships no such queries.
+
+## 7. Optional configuration
+
+Server settings go in a `config` key on the language-server block you already
+created. Helix delivers it as `initializationOptions`, which is the only place
+this server reads settings from:
+
+```toml
+config = { diagnosticMode = "realtime" }  # "realtime" | "saveOnly" | "off"
+```
+
+Do **not** repeat the `[language-server.pike-lsp]` header a second time in the
+file — duplicate TOML tables make Helix reject the whole config.
+
+| Option | Values | Default |
+|--------|--------|---------|
+| `diagnosticMode` | `"realtime"`, `"saveOnly"`, `"off"` | `"realtime"` |
+| `diagnosticDebounceMs` | positive integer | `500` |
+| `maxNumberOfProblems` | positive integer | `100` |
+
+## Troubleshooting
+
+**`Language 'pike' not found`** — `file-types` is missing, or the config failed
+to parse and Helix silently fell back to defaults. Run `hx --health pike` and
+read the first line of output.
+
+**`Error parsing user language config: missing field 'scope'`** — add
+`scope = "source.pike"`. Until you do, *no* language config of yours loads.
+
+**`Error parsing user language config: TOML parse error`** — you almost
+certainly declared `[language-server.pike-lsp]` twice. Merge the blocks.
+
+**`hx --health pike` shows `✘ bun`** — Bun is not on the `PATH` Helix sees. Use
+an absolute path in `command`, e.g. `command = "/home/you/.bun/bin/bun"`.
+
+**Server never attaches** — check the path in `args` resolves, then re-test the
+build from the repository clone:
+
+```bash
+bun run check:standalone
+```
+
+This spawns the server exactly as Helix does and asserts it answers an LSP
+`initialize`. If it fails, re-run `bun run build:standalone`. (Running
+`bun standalone/server.js --stdio` by hand proves little: with no LSP client on
+the other end it reads end-of-input and exits 0 straight away.)
+
+**No highlighting, LSP works** — `hx --health pike` reports
+`Tree-sitter parser: None`. Finish step 6; queries alone are not enough.
+
+**No diagnostics, everything else works** — Pike is not on `PATH`. Check
+`pike --version`. Diagnostics are the only feature that needs the Pike binary.
+
+**Nothing works after an upgrade** — Helix config errors are printed at startup
+and scroll past instantly. `hx --health pike` reprints them.
+
+## What works
+
+Every feature below was exercised against Helix 25.01.1's own client
+capabilities and confirmed to return real results (`bun run check:helix`
+re-runs this):
+
+- Document symbols, hover, goto-definition, find references
+- Completion (trigger characters `.`, `>`, `:`, `!`) and signature help
+- Rename and prepareRename
+- Document highlight, selection range, workspace symbols
+- Formatting, inlay hints, code actions
+- Diagnostics (pushed by the server; requires Pike on `PATH`)
+
+Helix 25.01 has no semantic-token support, so the server's semantic tokens are
+unused there — highlighting comes from the tree-sitter grammar instead.
+
+**One known limitation:** a *file-scope* declaration whose name collides with a
+Pike stdlib or predef name (`write`, `count`, `size`, …) cannot be renamed, in
+any editor. Locals, parameters, and class members are always renameable.

package/docs/other-editors.md

@@ -0,0 +1,242 @@
+# Using Pike LSP with Other Editors
+
+The Pike Language Server communicates over stdio using the standard LSP protocol. It works with any LSP-capable editor.
+
+## Prerequisites
+
+1. [Bun](https://bun.sh/) runtime installed and on PATH
+2. [Pike](https://pike.lysator.liu.se/) 8.0+ installed and on PATH
+3. Clone and build the server:
+
+```bash
+git clone https://github.com/TheSmuks/pike-language-server.git
+cd pike-language-server
+bun install
+bun run build:standalone
+```
+
+The server binary is at `standalone/server.js`. Run it with:
+
+```bash
+bun /path/to/pike-language-server/standalone/server.js --stdio
+```
+
+## Neovim (verified)
+
+Tested with Neovim 0.10.4 and [nvim-lspconfig](https://github.com/neovim/nvim-lspconfig).
+
+### Setup with nvim-lspconfig
+
+Install nvim-lspconfig, then add to your `init.lua`:
+
+```lua
+local configs = require("lspconfig.configs")
+local lspconfig = require("lspconfig")
+
+-- Register the pike-lsp config (if not already registered)
+if not configs.pike_lsp then
+  configs.pike_lsp = {
+    default_config = {
+      cmd = { "bun", "/path/to/pike-language-server/standalone/server.js", "--stdio" },
+      filetypes = { "pike", "pmod" },
+      root_dir = function(fname)
+        return vim.fs.dirname(vim.fs.find(".git", { path = fname, upward = true })[1])
+          or vim.fn.getcwd()
+      end,
+      single_file_support = true,
+    },
+  }
+end
+
+lspconfig.pike_lsp.setup({})
+```
+
+Replace `/path/to/pike-language-server` with the actual clone path.
+
+### Features verified on Neovim
+
+- LSP client attaches on `.pike` and `.pmod` files
+- Document symbols (classes, functions, variables, enums)
+- Hover (type info, AutoDoc documentation)
+- Completion with trigger characters `.`, `>`, `:`
+- Go-to-definition (same-file and cross-file)
+- Find references (workspace-wide)
+- Rename (with prepareRename support)
+
+### Configuration
+
+The server reads its configuration from `initializationOptions` only — it never
+issues a `workspace/configuration` request. Use `init_options`; a `settings`
+block is silently ignored.
+
+```lua
+lspconfig.pike_lsp.setup({
+  init_options = {
+    diagnosticMode = "realtime",  -- "realtime" | "saveOnly" | "off"
+  },
+})
+```
+
+## Helix (verified)
+
+> **Setting up Helix from scratch?** Follow the step-by-step
+> [Helix installation guide](helix-installation.md) instead — it covers
+> installing Helix, syntax highlighting, and troubleshooting. The summary below
+> assumes you already know your way around `languages.toml`.
+
+Tested with Helix 25.01.1. Helix has no built-in Pike language, so you must
+define it yourself — `scope` and `file-types` are both required, and Helix
+rejects the *entire* user language config if `scope` is missing.
+
+Add to `~/.config/helix/languages.toml`:
+
+```toml
+[language-server.pike-lsp]
+command = "bun"
+args = ["/path/to/pike-language-server/standalone/server.js", "--stdio"]
+# Optional — see "Helix configuration" below:
+# config = { diagnosticMode = "realtime" }
+
+[[language]]
+name = "pike"
+scope = "source.pike"
+file-types = ["pike", "pmod", "mmod"]
+comment-token = "//"
+indent = { tab-width = 2, unit = "  " }
+roots = ["pike.json", ".git"]
+language-servers = ["pike-lsp"]
+```
+
+Verify the language server is wired up:
+
+```bash
+hx --health pike
+```
+
+### Helix configuration
+
+Helix passes a `config` block to the server as `initializationOptions`, which is
+exactly where this server reads its settings from. Add the `config` key to the
+`[language-server.pike-lsp]` block you already defined above — do not repeat the
+block, or Helix will reject the file as a duplicate TOML table:
+
+```toml
+config = { diagnosticMode = "realtime" }  # "realtime" | "saveOnly" | "off"
+```
+
+### Features verified on Helix
+
+Exercised against the standalone bundle using Helix 25.01.1's own client
+capabilities, and confirmed to return real results:
+
+- Document symbols, hover, goto-definition, find references
+- Completion (trigger characters `.`, `>`, `:`, `!`) and signature help
+- Rename and prepareRename — see the limitation below
+- Document highlight, selection range, workspace symbols
+- Formatting, inlay hints, code actions
+- Diagnostics (pushed by the server)
+
+Helix 25.01 has no semantic-token support, so the server's semantic tokens go
+unused there; highlighting comes from the tree-sitter grammar instead.
+
+**Rename limitation:** a *file-scope* declaration whose name collides with a
+Pike stdlib or predef name (`write`, `count`, `size`, …) cannot be renamed — it
+shadows the predef and propagates to dependent files by name, which the rename
+engine cannot disambiguate. Locals, parameters, and class members are always
+renameable, whatever they are called. This is not Helix-specific; it applies to
+every client, VSCode included.
+
+### Helix syntax highlighting with tree-sitter
+
+Highlight queries alone are **not** enough — Helix also needs a compiled Pike
+grammar, or it loads no parser and nothing is highlighted. You need both.
+
+Add the grammar to the same `languages.toml`:
+
+```toml
+[[grammar]]
+name = "pike"
+source = { git = "https://github.com/TheSmuks/tree-sitter-pike", rev = "main" }
+```
+
+Then fetch and build it, and install the highlight queries:
+
+```bash
+hx --grammar fetch
+hx --grammar build
+mkdir -p ~/.config/helix/runtime/queries/pike/
+cp queries/highlights.scm ~/.config/helix/runtime/queries/pike/highlights.scm
+```
+
+Confirm both parts are present — `hx --health pike` should report
+`Tree-sitter parser: ✓` and `Highlight queries: ✓`. This repository ships no
+textobject or indent queries, so those stay `✘`.
+
+### Neovim with nvim-treesitter
+
+nvim-treesitter uses tree-sitter queries for syntax highlighting. Copy
+`queries/highlights.scm` from this repository to your nvim-treesitter queries
+directory:
+
+```bash
+mkdir -p ~/.local/share/nvim/site/queries/pike/
+cp queries/highlights.scm ~/.local/share/nvim/site/queries/pike/
+```
+
+```lua
+-- In your init.lua or treesitter config:
+require('nvim-treesitter.configs').setup {
+  ensure_installed = { 'pike' }, -- requires tree-sitter-pike parser
+  highlight = {
+    enable = true,
+    custom_captures = {
+      -- Map @keyword.import to @include for consistent styling
+      ['keyword.import'] = 'include',
+      ['function.method'] = 'function',
+      ['variable.parameter'] = 'variable',
+    },
+  },
+}
+```
+
+The `custom_captures` map the audit-required captures to standard nvim-treesitter
+highlight groups. The tree-sitter-pike parser must be installed separately
+(via `:TSInstall pike` or your plugin manager).
+
+## Generic LSP client configuration
+
+The server requires:
+- **Transport:** stdio
+- **Command:** `bun /path/to/pike-language-server/standalone/server.js --stdio`
+- **File types:** `.pike`, `.pmod`, `.mmod`
+- **Trigger characters:** `.`, `>`, `:`
+
+### Server capabilities
+
+| Capability | Supported |
+|------------|-----------|
+| documentSymbol | Yes |
+| definition | Yes |
+| references | Yes |
+| hover | Yes |
+| completion | Yes |
+| rename | Yes (with prepareRename) |
+| diagnostics | Yes (pushed by server) |
+
+## Troubleshooting
+
+### "Parser not initialized" errors
+
+The server initializes the tree-sitter parser on the `initialized` notification. If your client doesn't send this notification, parsing won't work. This is a bug in the client, not the server.
+
+### No diagnostics
+
+Diagnostics require Pike 8.0+ on PATH. Verify with:
+
+```bash
+pike --version
+```
+
+### No completion for stdlib symbols
+
+The server includes a pre-built stdlib index (5,505 symbols). This should work without any configuration. If completions are missing, check that `stdlib-autodoc.json` exists in the same directory as `server.js`.