@emnudge/wat-lsp 0.1.0

package/README.md

@@ -0,0 +1,119 @@
+# @emnudge/wat-lsp
+
+WebAssembly Text Format (WAT) Language Server - WASM build for browser and Node.js.
+
+## Installation
+
+```bash
+npm install @emnudge/wat-lsp
+```
+
+## Usage
+
+### Basic Usage
+
+```javascript
+import { createWatLSP } from '@emnudge/wat-lsp';
+
+// Create and initialize the LSP
+const lsp = await createWatLSP();
+
+// Parse a WAT document
+lsp.parse(`
+  (module
+    (func $add (param $a i32) (param $b i32) (result i32)
+      local.get $a
+      local.get $b
+      i32.add
+    )
+    (export "add" (func $add))
+  )
+`);
+
+// Get hover information
+const hover = lsp.provideHover(2, 12); // line 2, column 12
+console.log(hover?.contents.value);
+
+// Get diagnostics (syntax errors)
+const diagnostics = lsp.provideDiagnostics();
+
+// Go to definition
+const definition = lsp.provideDefinition(5, 16);
+
+// Find references
+const references = lsp.provideReferences(2, 12, true);
+```
+
+### With Custom WASM Paths
+
+When bundling for a web application, you may need to serve the WASM files from a specific location:
+
+```javascript
+import { createWatLSP, assets } from '@emnudge/wat-lsp';
+
+// Use custom paths
+const lsp = await createWatLSP({
+  treeSitterWasmPath: '/assets/tree-sitter.wasm',
+  watLspWasmPath: '/assets/wat_lsp_rust_bg.wasm',
+});
+
+// Or use the bundled asset URLs directly
+console.log(assets.treeSitterWasm); // URL to bundled tree-sitter.wasm
+console.log(assets.watLspWasm);     // URL to bundled wat_lsp_rust_bg.wasm
+```
+
+### Using the WatLanguageServer Class
+
+For a more LSP-like interface:
+
+```javascript
+import { WatLanguageServer } from '@emnudge/wat-lsp';
+
+const server = new WatLanguageServer();
+await server.initialize();
+
+// Update document
+server.updateDocument('(module (func $foo))');
+
+// Use LSP-style methods
+const hover = server.provideHover(0, 15);
+const diagnostics = server.provideDiagnostics();
+```
+
+### Low-level WASM Access
+
+For advanced usage, you can access the raw WASM bindings:
+
+```javascript
+import { WatLSP, initWasm } from '@emnudge/wat-lsp';
+import { Parser } from 'web-tree-sitter';
+
+// Initialize tree-sitter yourself
+await Parser.init({
+  locateFile: (file) => `/my-path/${file}`,
+});
+
+// Initialize the WASM module
+await initWasm('/my-path/wat_lsp_rust_bg.wasm');
+
+// Create and use WatLSP directly
+const lsp = new WatLSP();
+await lsp.initialize();
+```
+
+## Features
+
+- **Hover**: Get documentation for WAT instructions and symbols
+- **Go to Definition**: Jump to function, global, and type definitions
+- **Find References**: Find all usages of a symbol
+- **Diagnostics**: Syntax error detection using `wast` parser
+- **Semantic Tokens**: Tree-sitter based syntax highlighting
+
+## Requirements
+
+- Modern browser with WebAssembly support, or Node.js 16+
+- `web-tree-sitter` (peer dependency)
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,216 @@
+/**
+ * @emnudge/wat-lsp - WebAssembly Text Format Language Server
+ */
+
+export { WatLSP } from './wasm/wat_lsp_rust.js';
+export { default as initWasm } from './wasm/wat_lsp_rust.js';
+
+/**
+ * LSP Position
+ */
+export interface Position {
+  line: number;
+  character: number;
+}
+
+/**
+ * LSP Range
+ */
+export interface Range {
+  start: Position;
+  end: Position;
+}
+
+/**
+ * Hover result from the LSP
+ */
+export interface HoverResult {
+  contents: {
+    kind: 'markdown' | 'plaintext';
+    value: string;
+  };
+  range?: Range;
+}
+
+/**
+ * Definition result from the LSP
+ */
+export interface DefinitionResult {
+  range: Range;
+}
+
+/**
+ * Reference result from the LSP
+ */
+export interface ReferenceResult {
+  range: Range;
+}
+
+/**
+ * Diagnostic from the LSP
+ */
+export interface Diagnostic {
+  range: Range;
+  message: string;
+  severity: 1 | 2 | 3 | 4; // Error, Warning, Info, Hint
+}
+
+/**
+ * Completion item from the LSP
+ */
+export interface CompletionItem {
+  label: string;
+  kind?: number;
+  detail?: string;
+  insertText?: string;
+  insertTextRules?: number;
+  documentation?: string;
+}
+
+/**
+ * Semantic tokens legend
+ */
+export interface SemanticTokensLegend {
+  tokenTypes: string[];
+  tokenModifiers: string[];
+}
+
+/**
+ * Server capabilities
+ */
+export interface ServerCapabilities {
+  hoverProvider: boolean;
+  definitionProvider: boolean;
+  referencesProvider: boolean;
+  documentSymbolProvider: boolean;
+  completionProvider: boolean;
+  semanticTokensProvider: {
+    legend: SemanticTokensLegend;
+    full: boolean;
+  };
+}
+
+/**
+ * Path helpers for locating bundled WASM assets
+ */
+export const assets: {
+  /** URL to tree-sitter.wasm */
+  treeSitterWasm: string;
+  /** URL to wat_lsp_rust_bg.wasm */
+  watLspWasm: string;
+};
+
+/**
+ * Options for createWatLSP
+ */
+export interface CreateWatLSPOptions {
+  /** Custom path to tree-sitter.wasm */
+  treeSitterWasmPath?: string;
+  /** Custom path to wat_lsp_rust_bg.wasm */
+  watLspWasmPath?: string;
+  /** Skip tree-sitter initialization if already done */
+  skipTreeSitterInit?: boolean;
+}
+
+/**
+ * Create and initialize a WAT Language Server instance.
+ *
+ * @example
+ * const lsp = await createWatLSP();
+ * lsp.parse('(module (func $add (param i32 i32) (result i32)))');
+ * const hover = lsp.provideHover(0, 15);
+ */
+export function createWatLSP(options?: CreateWatLSPOptions): Promise<WatLSP>;
+
+/**
+ * WAT Language Server instance (from WASM)
+ */
+export interface WatLSP {
+  /** Check if the LSP is ready */
+  readonly ready: boolean;
+
+  /** Initialize the LSP (loads tree-sitter) */
+  initialize(): Promise<boolean>;
+
+  /** Parse a WAT document */
+  parse(document: string): void;
+
+  /** Provide hover information at position */
+  provideHover(line: number, col: number): HoverResult | null;
+
+  /** Provide go-to-definition at position */
+  provideDefinition(line: number, col: number): DefinitionResult | null;
+
+  /** Provide find-references at position */
+  provideReferences(
+    line: number,
+    col: number,
+    includeDeclaration: boolean
+  ): ReferenceResult[];
+
+  /** Provide diagnostics for the current document */
+  provideDiagnostics(): Diagnostic[];
+
+  /** Provide code completion at position */
+  provideCompletion(line: number, col: number): CompletionItem[];
+
+  /** Provide semantic tokens for syntax highlighting */
+  provideSemanticTokens(): Uint32Array;
+
+  /** Get the semantic tokens legend */
+  getSemanticTokensLegend(): SemanticTokensLegend;
+
+  /** Get symbol table as HTML (for debugging) */
+  getSymbolTableHTML(): string;
+
+  /** Debug: get word info at position */
+  debugWordAt(line: number, col: number): {
+    word: string | null;
+    hasFunction?: boolean;
+    functionRange?: string;
+    functionLine?: number | null;
+  };
+}
+
+/**
+ * LSP-like message handler wrapper.
+ * Provides a cleaner interface for the WAT LSP.
+ */
+export class WatLanguageServer {
+  /** Check if the server is ready */
+  readonly ready: boolean;
+
+  /** Initialize the language server */
+  initialize(options?: CreateWatLSPOptions): Promise<{ capabilities: ServerCapabilities }>;
+
+  /** Get server capabilities */
+  getCapabilities(): ServerCapabilities;
+
+  /** Update the document content */
+  updateDocument(content: string): void;
+
+  /** Provide hover information */
+  provideHover(line: number, character: number): HoverResult | null;
+
+  /** Provide go-to-definition */
+  provideDefinition(line: number, character: number): DefinitionResult | null;
+
+  /** Provide find-references */
+  provideReferences(
+    line: number,
+    character: number,
+    includeDeclaration?: boolean
+  ): ReferenceResult[];
+
+  /** Provide diagnostics */
+  provideDiagnostics(): Diagnostic[];
+
+  /** Provide code completion */
+  provideCompletion(line: number, character: number): CompletionItem[];
+
+  /** Provide semantic tokens */
+  provideSemanticTokens(): Uint32Array;
+
+  /** Get semantic tokens legend */
+  getSemanticTokensLegend(): SemanticTokensLegend;
+}

package/dist/index.js

@@ -0,0 +1,201 @@
+/**
+ * @emnudge/wat-lsp - WebAssembly Text Format Language Server
+ *
+ * A WASM-based language server for WAT files that runs in the browser or Node.js.
+ */
+
+import { Parser } from 'web-tree-sitter';
+
+// Re-export the raw WASM bindings for advanced usage
+export { WatLSP } from './wasm/wat_lsp_rust.js';
+export { default as initWasm } from './wasm/wat_lsp_rust.js';
+
+/**
+ * Path helpers for locating bundled WASM assets.
+ * Use these when you need to serve the WASM files from a specific location.
+ */
+export const assets = {
+  /**
+   * Get the path to tree-sitter.wasm relative to this package.
+   * You'll need to serve this file and configure web-tree-sitter to find it.
+   */
+  treeSitterWasm: new URL('./wasm/tree-sitter.wasm', import.meta.url).href,
+
+  /**
+   * Get the path to the main wat-lsp WASM module.
+   */
+  watLspWasm: new URL('./wasm/wat_lsp_rust_bg.wasm', import.meta.url).href,
+};
+
+/**
+ * Create and initialize a WAT Language Server instance.
+ *
+ * This is a convenience function that handles all the initialization steps:
+ * 1. Initialize web-tree-sitter runtime
+ * 2. Initialize the wat-lsp WASM module
+ * 3. Create and initialize the WatLSP instance
+ *
+ * @param {Object} options - Configuration options
+ * @param {string} [options.treeSitterWasmPath] - Custom path to tree-sitter.wasm
+ * @param {string} [options.watLspWasmPath] - Custom path to wat_lsp_rust_bg.wasm
+ * @param {boolean} [options.skipTreeSitterInit=false] - Skip tree-sitter init if already done
+ * @returns {Promise<import('./wasm/wat_lsp_rust.js').WatLSP>} Initialized WatLSP instance
+ *
+ * @example
+ * // Basic usage
+ * const lsp = await createWatLSP();
+ * lsp.parse('(module (func $add (param i32 i32) (result i32)))');
+ * const hover = lsp.provideHover(0, 15);
+ *
+ * @example
+ * // With custom paths (e.g., when bundling for a web app)
+ * const lsp = await createWatLSP({
+ *   treeSitterWasmPath: '/assets/tree-sitter.wasm',
+ *   watLspWasmPath: '/assets/wat_lsp_rust_bg.wasm'
+ * });
+ */
+export async function createWatLSP(options = {}) {
+  const {
+    treeSitterWasmPath,
+    watLspWasmPath,
+    skipTreeSitterInit = false,
+  } = options;
+
+  // Step 1: Initialize web-tree-sitter (if not already done)
+  if (!skipTreeSitterInit) {
+    await Parser.init({
+      locateFile: (file) => {
+        if (file === 'tree-sitter.wasm') {
+          return treeSitterWasmPath || assets.treeSitterWasm;
+        }
+        return file;
+      },
+    });
+  }
+
+  // Step 2: Initialize the WASM module
+  const { default: initWasm, WatLSP } = await import('./wasm/wat_lsp_rust.js');
+  await initWasm(watLspWasmPath || assets.watLspWasm);
+
+  // Step 3: Create and initialize the LSP instance
+  const lsp = new WatLSP();
+  const success = await lsp.initialize();
+
+  if (!success) {
+    throw new Error('Failed to initialize WAT LSP');
+  }
+
+  return lsp;
+}
+
+/**
+ * LSP-like message handler wrapper.
+ * Provides a JSON-RPC style interface for the WAT LSP.
+ *
+ * Note: This is a simplified wrapper, not a full LSP implementation.
+ * For a complete LSP server, you'd need to handle all LSP methods and lifecycle.
+ */
+export class WatLanguageServer {
+  /** @type {import('./wasm/wat_lsp_rust.js').WatLSP | null} */
+  #lsp = null;
+
+  /** @type {string} */
+  #currentDocument = '';
+
+  /**
+   * Check if the server is ready
+   */
+  get ready() {
+    return this.#lsp?.ready ?? false;
+  }
+
+  /**
+   * Initialize the language server
+   * @param {Object} options - Same options as createWatLSP
+   */
+  async initialize(options = {}) {
+    this.#lsp = await createWatLSP(options);
+    return { capabilities: this.getCapabilities() };
+  }
+
+  /**
+   * Get server capabilities
+   */
+  getCapabilities() {
+    return {
+      hoverProvider: true,
+      definitionProvider: true,
+      referencesProvider: true,
+      documentSymbolProvider: false, // Not implemented yet
+      completionProvider: false, // Uses static completions
+      semanticTokensProvider: {
+        legend: this.#lsp?.getSemanticTokensLegend() ?? { tokenTypes: [], tokenModifiers: [] },
+        full: true,
+      },
+    };
+  }
+
+  /**
+   * Update the document content
+   * @param {string} content - The new document content
+   */
+  updateDocument(content) {
+    this.#currentDocument = content;
+    this.#lsp?.parse(content);
+  }
+
+  /**
+   * Provide hover information
+   * @param {number} line - 0-indexed line number
+   * @param {number} character - 0-indexed character position
+   * @returns {Object|null} Hover result or null
+   */
+  provideHover(line, character) {
+    return this.#lsp?.provideHover(line, character) ?? null;
+  }
+
+  /**
+   * Provide go-to-definition
+   * @param {number} line - 0-indexed line number
+   * @param {number} character - 0-indexed character position
+   * @returns {Object|null} Definition location or null
+   */
+  provideDefinition(line, character) {
+    return this.#lsp?.provideDefinition(line, character) ?? null;
+  }
+
+  /**
+   * Provide find-references
+   * @param {number} line - 0-indexed line number
+   * @param {number} character - 0-indexed character position
+   * @param {boolean} includeDeclaration - Whether to include the declaration
+   * @returns {Array} Array of reference locations
+   */
+  provideReferences(line, character, includeDeclaration = true) {
+    return this.#lsp?.provideReferences(line, character, includeDeclaration) ?? [];
+  }
+
+  /**
+   * Provide diagnostics for the current document
+   * @returns {Array} Array of diagnostic objects
+   */
+  provideDiagnostics() {
+    return this.#lsp?.provideDiagnostics() ?? [];
+  }
+
+  /**
+   * Provide semantic tokens for syntax highlighting
+   * @returns {Uint32Array} Delta-encoded semantic tokens
+   */
+  provideSemanticTokens() {
+    return this.#lsp?.provideSemanticTokens() ?? new Uint32Array(0);
+  }
+
+  /**
+   * Get the semantic tokens legend
+   * @returns {Object} Token types and modifiers
+   */
+  getSemanticTokensLegend() {
+    return this.#lsp?.getSemanticTokensLegend() ?? { tokenTypes: [], tokenModifiers: [] };
+  }
+}

package/dist/wasm/wat_lsp_rust.d.ts

@@ -0,0 +1,132 @@
+/* tslint:disable */
+/* eslint-disable */
+
+export class WatLSP {
+  free(): void;
+  [Symbol.dispose](): void;
+  /**
+   * Initialize the LSP (initializes tree-sitter). Returns true if successful.
+   */
+  initialize(): Promise<boolean>;
+  /**
+   * Debug: get info about a word at position
+   */
+  debugWordAt(line: number, col: number): any;
+  /**
+   * Provide hover information at the given position (uses tree-sitter based hover)
+   */
+  provideHover(line: number, col: number): any;
+  /**
+   * Provide code completion items at the given position
+   * Returns an array of completion item objects
+   */
+  provideCompletion(line: number, col: number): any;
+  /**
+   * Provide go-to-definition at the given position
+   */
+  provideDefinition(line: number, col: number): any;
+  /**
+   * Provide find-references at the given position
+   */
+  provideReferences(line: number, col: number, include_declaration: boolean): any;
+  /**
+   * Get diagnostics (syntax errors) for the current document
+   */
+  provideDiagnostics(): any;
+  /**
+   * Get symbol table as HTML for debugging
+   */
+  getSymbolTableHTML(): string;
+  /**
+   * Provide folding ranges for the current document
+   * Returns an array of folding range objects with startLine, endLine, and kind
+   */
+  provideFoldingRanges(): any;
+  /**
+   * Provide semantic tokens for syntax highlighting
+   * Returns a flat array of u32 values in Monaco's delta-encoded format:
+   * [deltaLine, deltaStartChar, length, tokenType, tokenModifiers, ...]
+   */
+  provideSemanticTokens(): Uint32Array;
+  /**
+   * Provide document symbols (outline) for the current document
+   * Returns a hierarchical array of symbols matching the LSP DocumentSymbol structure
+   */
+  provideDocumentSymbols(): any;
+  /**
+   * Get the semantic token legend (token types and modifiers)
+   */
+  getSemanticTokensLegend(): any;
+  /**
+   * Create a new WAT LSP instance
+   */
+  constructor();
+  /**
+   * Parse a WAT document and build symbol table using tree-sitter
+   */
+  parse(document: string): void;
+  /**
+   * Check if the LSP is ready
+   */
+  readonly ready: boolean;
+}
+
+/**
+ * Initialize panic hook for better error messages in the browser console
+ */
+export function init(): void;
+
+export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
+
+export interface InitOutput {
+  readonly memory: WebAssembly.Memory;
+  readonly __wbg_watlsp_free: (a: number, b: number) => void;
+  readonly watlsp_debugWordAt: (a: number, b: number, c: number) => any;
+  readonly watlsp_getSemanticTokensLegend: (a: number) => any;
+  readonly watlsp_getSymbolTableHTML: (a: number) => [number, number];
+  readonly watlsp_initialize: (a: number) => any;
+  readonly watlsp_new: () => number;
+  readonly watlsp_parse: (a: number, b: number, c: number) => void;
+  readonly watlsp_provideCompletion: (a: number, b: number, c: number) => any;
+  readonly watlsp_provideDefinition: (a: number, b: number, c: number) => any;
+  readonly watlsp_provideDiagnostics: (a: number) => any;
+  readonly watlsp_provideDocumentSymbols: (a: number) => any;
+  readonly watlsp_provideFoldingRanges: (a: number) => any;
+  readonly watlsp_provideHover: (a: number, b: number, c: number) => any;
+  readonly watlsp_provideReferences: (a: number, b: number, c: number, d: number) => any;
+  readonly watlsp_provideSemanticTokens: (a: number) => any;
+  readonly watlsp_ready: (a: number) => number;
+  readonly init: () => void;
+  readonly wasm_bindgen__convert__closures_____invoke__hc43d41e9321ebc8f: (a: number, b: number, c: any) => void;
+  readonly wasm_bindgen__closure__destroy__hb94a2c2b7eee95bf: (a: number, b: number) => void;
+  readonly wasm_bindgen__convert__closures_____invoke__h17d4e94d5fe1e6e2: (a: number, b: number, c: any, d: any) => void;
+  readonly __wbindgen_exn_store: (a: number) => void;
+  readonly __externref_table_alloc: () => number;
+  readonly __wbindgen_externrefs: WebAssembly.Table;
+  readonly __wbindgen_malloc: (a: number, b: number) => number;
+  readonly __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
+  readonly __wbindgen_free: (a: number, b: number, c: 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>;