@xoong/lsp 0.0.0-stage → 0.0.35

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Duong Tran Xuan
+
+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

@@ -1,3 +1,24 @@
-# Temporary Holding Version
+# @xoong/lsp
 
-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.
+A language server for xoong screens: the diagnostics of `xoong check`, completion of operation names and `xo-*` attributes, and hover documentation in any editor that speaks LSP.
+
+## Install
+
+```bash
+npm install @xoong/lsp
+```
+
+## Use
+
+```bash
+npx xoong-lsp
+```
+
+## More
+
+* Documentation and demos: https://github.com/fpt-duongtx/xoong#readme
+* Source: https://github.com/fpt-duongtx/xoong/tree/main/packages/lsp
+* All packages share one version number and are released together: https://github.com/fpt-duongtx/xoong/releases
+* xoong is a working prototype (0.0.x): the HTML syntax is still Draft.
+
+MIT licence.

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "@xoong/lsp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.35",
+  "description": "Language server for xoong screens: the same diagnostics as `xoong check`, completion of operation names and xo-* attributes, hover docs. Any editor that speaks LSP.",
+  "type": "module",
+  "bin": {
+    "xoong-lsp": "src/cli.js"
+  },
+  "exports": {
+    ".": "./src/server.js"
+  },
+  "files": [
+    "src"
+  ],
+  "keywords": [
+    "xoong",
+    "language-server",
+    "lsp"
+  ],
+  "engines": {
+    "node": ">=22.12"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@xoong/cli": "0.0.35",
+    "@xoong/core": "0.0.35"
+  },
+  "author": "Duong Tran Xuan <duongtx1505@icloud.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fpt-duongtx/xoong.git",
+    "directory": "packages/lsp"
+  },
+  "bugs": {
+    "url": "https://github.com/fpt-duongtx/xoong/issues"
+  },
+  "homepage": "https://github.com/fpt-duongtx/xoong#readme",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/cli.js

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+// @ts-check
+// xoong-lsp: language server over stdio (Content-Length framing). Finds .xoong/operations.json from the workspace folder upward.
+import { readFile, stat } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createLanguageServer } from './server.js';
+
+let root = process.cwd();
+let cached = { file: '', mtime: 0, table: /** @type {any} */ (null) };
+
+async function operations() {
+  for (let dir = root; ; dir = dirname(dir)) {
+    const file = join(dir, '.xoong', 'operations.json');
+    try {
+      const { mtimeMs } = await stat(file);
+      if (cached.file !== file || cached.mtime !== mtimeMs) cached = { file, mtime: mtimeMs, table: JSON.parse(await readFile(file, 'utf8')) };
+      return cached.table;
+    } catch { /* look one folder up */ }
+    if (dirname(dir) === dir) return null;
+  }
+}
+
+const server = createLanguageServer({ operations });
+const send = (m) => { const body = Buffer.from(JSON.stringify(m)); process.stdout.write(`Content-Length: ${body.length}\r\n\r\n`); process.stdout.write(body); };
+
+let buffer = Buffer.alloc(0);
+let chain = Promise.resolve(); // messages are handled one after another, so responses cannot overtake each other
+
+async function process_(msg) {
+  try {
+    if (msg.method === 'initialize' && typeof msg.params?.rootUri === 'string' && msg.params.rootUri.startsWith('file:')) root = fileURLToPath(msg.params.rootUri);
+    if (msg.method === 'exit') process.exit(0);
+    for (const out of await server.handle(msg)) send(out);
+  } catch (e) {
+    console.error('xoong-lsp:', e); // stderr only: stdout carries the protocol
+  }
+}
+
+process.stdin.on('data', (chunk) => {
+  buffer = Buffer.concat([buffer, chunk]);
+  for (;;) {
+    const sep = buffer.indexOf('\r\n\r\n');
+    if (sep < 0) return;
+    const length = Number(/Content-Length: (\d+)/i.exec(buffer.subarray(0, sep).toString())?.[1]);
+    if (!length) { buffer = buffer.subarray(sep + 4); continue; } // a header we cannot use: drop it and keep going
+    if (buffer.length < sep + 4 + length) return;
+    const body = buffer.subarray(sep + 4, sep + 4 + length).toString();
+    buffer = buffer.subarray(sep + 4 + length);
+    let msg;
+    try { msg = JSON.parse(body); } catch { send({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } }); continue; }
+    chain = chain.then(() => process_(msg));
+  }
+});

package/src/server.js

@@ -0,0 +1,152 @@
+// @ts-check
+/**
+ * xoong language server core: pure message handling, no I/O. `handle(message)` returns the messages to send back
+ * (a response and/or notifications), so it can be tested without a process. `cli.js` adds stdio framing.
+ *
+ * Features (one engine, see docs/editor-integration.md):
+ *   diagnostics  the findings of `xoong check`, with the same message and fix, as you type
+ *   completion   operation names inside xo-click, xo-submit, get and op; xo-* attribute names
+ *   hover        what an xo-* attribute or element does
+ *   code action  "Use <closest operation>" for unknown operations
+ */
+import { checkHtml, checkScript } from '@xoong/cli/check';
+import { ATTRIBUTE_DOCS, ELEMENT_DOCS } from '@xoong/cli/html-data';
+import { XO_ATTRIBUTES, XO_ELEMENTS, XO_UI_ATTRIBUTES, XO_UI_ELEMENTS, XO_CONTROL_ATTRIBUTES, XO_CONTROL_ELEMENTS } from '@xoong/core/syntax';
+
+const ATTRS = [...XO_ATTRIBUTES, ...XO_UI_ATTRIBUTES, ...XO_CONTROL_ATTRIBUTES];
+const TAGS = [...XO_ELEMENTS, ...XO_UI_ELEMENTS, ...XO_CONTROL_ELEMENTS];
+const isScript = (uri) => /\.(c|m)?[jt]sx?$/.test(uri);
+const isMutationAttr = (name) => name === 'xo-click' || name === 'xo-submit' || name === 'op';
+
+/**
+ * @param {{ operations: () => Promise<{ operations: Record<string, any> } | null> }} ctx
+ *   `operations()` returns the synced table (re-read on every call so `xoong sync` is picked up) or null if there is none yet.
+ */
+export function createLanguageServer(ctx) {
+  /** @type {Map<string, string>} open documents */
+  const docs = new Map();
+
+  const notify = (method, params) => ({ jsonrpc: '2.0', method, params });
+  const reply = (id, result) => ({ jsonrpc: '2.0', id, result });
+
+  /** End of the word that starts at (line, col) (0-based), so the squiggle covers the attribute or value, not one letter. */
+  function rangeAt(text, line, col) {
+    const row = text.split('\n')[line] ?? '';
+    let end = col;
+    while (end < row.length && !/[\s"'<>=]/.test(row[end])) end++;
+    if (end === col) end = Math.min(col + 1, row.length);
+    return { start: { line, character: col }, end: { line, character: end } };
+  }
+
+  async function diagnose(uri) {
+    const text = docs.get(uri) ?? '';
+    const table = await ctx.operations();
+    if (!table) return notify('textDocument/publishDiagnostics', { uri, diagnostics: [{ range: rangeAt(text, 0, 0), severity: 3, source: 'xoong', code: 'no-operations', message: 'No .xoong/operations.json found. Run `xoong sync <openapi>` so operations can be checked.' }] });
+    const findings = isScript(uri) ? checkScript(text, table, uri) : checkHtml(text, table, uri);
+    return notify('textDocument/publishDiagnostics', {
+      uri,
+      diagnostics: findings.map((f) => ({
+        range: rangeAt(text, f.line - 1, f.column - 1),
+        severity: f.level === 'error' ? 1 : 2,
+        source: 'xoong', code: f.code,
+        message: `${f.message}\nfix: ${f.fix}`,
+        data: { fix: f.fix },
+      })),
+    });
+  }
+
+  /** The text of the line before the cursor. */
+  const before = (uri, pos) => (docs.get(uri)?.split('\n')[pos.line] ?? '').slice(0, pos.character);
+
+  async function complete(uri, pos) {
+    const line = before(uri, pos);
+    const value = /(?<![\w:.-])(xo-click|xo-submit|get|op)\s*=\s*(["'])([^"']*)$/.exec(line);
+    if (value) {
+      const table = await ctx.operations();
+      if (!table) return [];
+      const [, attr, , typed] = value;
+      const reads = attr === 'get';
+      const items = [];
+      for (const o of Object.values(table.operations)) {
+        if (reads ? o.method !== 'GET' : o.method === 'GET') continue;
+        for (const label of reads ? [o.id, o.path] : [o.id, `${o.method} ${o.path}`]) if (label.toLowerCase().includes(typed.toLowerCase())) {
+          items.push({ label, kind: 12, detail: `${o.method} ${o.path}`, documentation: o.bodyFields ? `Body: ${o.bodyFields.map((b) => b.name + (b.required ? '*' : '')).join(', ')}` : undefined,
+            textEdit: { range: { start: { line: pos.line, character: pos.character - typed.length }, end: pos }, newText: label } });
+        }
+      }
+      return items;
+    }
+    const attr = /<[\w-]+[^<>]*\s(xo-[\w-]*|[\w-]*)$/.exec(line);
+    if (attr && attr[1].startsWith('xo-')) return ATTRS.map((name) => ({ label: name, kind: 10, documentation: ATTRIBUTE_DOCS[name] }));
+    const tag = /<(xo-[\w-]*)$/.exec(line);
+    if (tag) return TAGS.map((name) => ({ label: name, kind: 7, documentation: ELEMENT_DOCS[name]?.[0] }));
+    return [];
+  }
+
+  function hover(uri, pos) {
+    const row = docs.get(uri)?.split('\n')[pos.line] ?? '';
+    for (const m of row.matchAll(/xo-[\w-]+/g)) {
+      if (m.index <= pos.character && pos.character <= m.index + m[0].length) {
+        const name = m[0];
+        const text = ATTRIBUTE_DOCS[name] ?? ELEMENT_DOCS[name]?.[0];
+        if (text) return { contents: { kind: 'markdown', value: `**${name}**\n\n${text}` } };
+      }
+    }
+    return null;
+  }
+
+  function codeActions(uri, diagnostics) {
+    const actions = [];
+    for (const d of diagnostics ?? []) {
+      const closest = d.code === 'XO201' && /Use "([^"]+)"/.exec(d.data?.fix ?? '')?.[1];
+      if (!closest) continue;
+      const text = docs.get(uri) ?? '';
+      const row = text.split('\n')[d.range.start.line] ?? '';
+      let start, length;
+      if (isScript(uri)) { // the diagnostic starts at the operation name itself
+        const typo = /unknown operation "([^"]+)"/.exec(d.message)?.[1];
+        if (!typo || !row.startsWith(typo, d.range.start.character)) continue;
+        start = d.range.start.character; length = typo.length;
+      } else { // the diagnostic starts at the attribute: replace the quoted value after it
+        const quoted = /(["'])([^"']*)\1/.exec(row.slice(d.range.start.character));
+        if (!quoted) continue;
+        start = d.range.start.character + quoted.index + 1; length = quoted[2].length;
+      }
+      actions.push({ title: `Use "${closest}"`, kind: 'quickfix', diagnostics: [d], isPreferred: true,
+        edit: { changes: { [uri]: [{ range: { start: { line: d.range.start.line, character: start }, end: { line: d.range.start.line, character: start + length } }, newText: closest }] } } });
+    }
+    return actions;
+  }
+
+  /** @param {any} msg @returns {Promise<any[]>} */
+  async function handle(msg) {
+    try {
+      return await dispatch(msg ?? {});
+    } catch (e) { // one bad message must never take the server down
+      return msg?.id !== undefined ? [{ jsonrpc: '2.0', id: msg.id, error: { code: -32603, message: String(e instanceof Error ? e.message : e) } }] : [];
+    }
+  }
+
+  async function dispatch(msg) {
+    const { method, id, params } = msg;
+    switch (method) {
+      case 'initialize': return [reply(id, { capabilities: { textDocumentSync: 1, completionProvider: { triggerCharacters: ['"', "'", '-', '<'] }, hoverProvider: true, codeActionProvider: true }, serverInfo: { name: 'xoong-lsp', version: '0.0.1' } })];
+      case 'shutdown': return [reply(id, null)];
+      case 'textDocument/didOpen': docs.set(params.textDocument.uri, params.textDocument.text); return [await diagnose(params.textDocument.uri)];
+      case 'textDocument/didChange': {
+        const text = params?.contentChanges?.at(-1)?.text;
+        if (typeof text !== 'string') return []; // nothing usable: keep the last known text
+        docs.set(params.textDocument.uri, text);
+        return [await diagnose(params.textDocument.uri)];
+      }
+      case 'textDocument/didSave': return docs.has(params.textDocument.uri) ? [await diagnose(params.textDocument.uri)] : []; // also picks up a fresh `xoong sync`
+      case 'textDocument/didClose': docs.delete(params.textDocument.uri); return [notify('textDocument/publishDiagnostics', { uri: params.textDocument.uri, diagnostics: [] })];
+      case 'textDocument/completion': return [reply(id, await complete(params.textDocument.uri, params.position))];
+      case 'textDocument/hover': return [reply(id, hover(params.textDocument.uri, params.position))];
+      case 'textDocument/codeAction': return [reply(id, codeActions(params.textDocument.uri, params.context?.diagnostics))];
+      default: return id !== undefined ? [{ jsonrpc: '2.0', id, error: { code: -32601, message: `Method not found: ${method}` } }] : [];
+    }
+  }
+
+  return { handle };
+}