@zubra/language-server 0.0.0-stage → 5.0.2

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026, Mikey Nichols
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/analysis.js

@@ -0,0 +1,186 @@
+// What the language server knows about a `.zb` document, as plain functions (no LSP types
+// beyond positions), so they can be tested directly.
+
+/** The directives, with their attributes. */
+export const DIRECTIVES = {
+  'zb-if': { description: 'Render the content when `test` is truthy; an optional final `<zb-else>` otherwise.', attributes: { test: 'The condition: `test={…}`.' } },
+  'zb-else': { description: 'The content of an `<zb-if>` when its test is falsy. Must be its last child.', attributes: {} },
+  'zb-each': {
+    description: 'Render the content once per item of `items`. `let:name={…}` names a value per row.',
+    attributes: { items: 'The array: `items={…}`.', as: 'The name of each item.', index: 'The name of the index (optional).', key: 'A unique string or number per item, so rows follow their items: `key={item.id}`.' },
+  },
+  'zb-slot': { description: 'Where content given to the element goes; the children are the fallback.', attributes: { name: 'The slot name (omit for the default slot).' } },
+  'zb-await': { description: 'Show `<zb-pending>` while `value` (a promise, a `resource()`, or an array of them) is pending, then `<zb-then>` or `<zb-catch>`. `<zb-await {user}>` is short for `value={user}`.', attributes: { value: 'The promise, resource, or array of them: `value={…}`.', delay: 'Show the pending content only after this many milliseconds: `delay={200}`.', keep: 'Keep the settled content while a resource reloads; the host gets `:state(loading)`.' } },
+  'zb-switch': { description: 'Render the first `<zb-case>` whose `is` matches `value`, else the final `<zb-else>`.', attributes: { value: 'The value to match: `value={…}`.' } },
+  'zb-case': { description: 'Inside `<zb-switch>`: rendered when `is` equals the value (`is="paid"`), or is an array that contains it (`is={["shipped", "delivered"]}`).', attributes: { is: 'A string (`is="paid"`), a value (`is={…}`) or an array of them.' } },
+  'zb-pending': { description: 'The content of a `<zb-await>` while its value is pending. Comes first.', attributes: {} },
+  'zb-then': { description: 'The content of a `<zb-await>` once its value has resolved.', attributes: { as: 'The name of the resolved value, or a pattern: `as="{ name }"`, `as="[user, posts]"`.' } },
+  'zb-catch': { description: 'The content of a `<zb-await>` if its value rejected. `retry()` runs the value again.', attributes: { as: 'The name of the error, or a pattern: `as="{ message }"`.' } },
+};
+
+/** Line/character → offset. */
+export function offsetAt(text, { line, character }) {
+  let offset = 0;
+  for (let i = 0; i < line; i++) {
+    const next = text.indexOf('\n', offset);
+    if (next < 0) return text.length;
+    offset = next + 1;
+  }
+  return Math.min(offset + character, text.length);
+}
+
+export function positionAt(text, offset) {
+  const before = text.slice(0, offset);
+  const line = before.split('\n').length - 1;
+  return { line, character: offset - (before.lastIndexOf('\n') + 1) };
+}
+
+/** Where the cursor is: in the script or style, in a tag name, in a start tag's attributes, or in the template. */
+export function contextAt(text, offset) {
+  const before = text.slice(0, offset);
+  const lower = before.toLowerCase();
+  for (const block of ['script', 'style']) {
+    const open = lower.lastIndexOf(`<${block}`);
+    if (open >= 0 && lower.indexOf(`</${block}`, open) < 0) return { kind: block };
+  }
+  const lt = before.lastIndexOf('<');
+  const gt = before.lastIndexOf('>');
+  const brace = before.lastIndexOf('{');
+  const closeBrace = before.lastIndexOf('}');
+  if (brace > closeBrace && brace > gt) return { kind: 'expression' };
+  if (lt > gt) {
+    const inside = before.slice(lt + 1);
+    const tag = inside.match(/^\/?[a-zA-Z][\w.-]*/)?.[0] ?? '';
+    if (inside === tag && !tag.startsWith('/')) return { kind: 'tag', prefix: tag };
+    if (!tag.startsWith('/') && /\s/.test(inside.slice(tag.length, tag.length + 1))) {
+      const attribute = inside.match(/([\w:-]*)$/)?.[1] ?? '';
+      // Inside a quoted value?
+      const quotes = (inside.match(/"/g)?.length ?? 0) % 2;
+      if (!quotes) return { kind: 'attribute', tag, prefix: attribute };
+    }
+  }
+  return { kind: 'template' };
+}
+
+/** The host tag and its props, read from the source (for completions in expressions). */
+export function hostOf(text) {
+  const withoutBlocks = text.replace(/<(script|style)[^>]*>[\s\S]*?<\/\1>/gi, (block) => ' '.repeat(block.length)).replace(/<!--[\s\S]*?-->/g, (comment) => ' '.repeat(comment.length));
+  const match = withoutBlocks.match(/<([a-z][\w.]*-[\w.-]*)([^>]*)>/);
+  if (!match) return null;
+  const props = attributeNames(match[2]).filter((name) => !['shadow', 'form-associated'].includes(name));
+  return { tag: match[1], offset: match.index, props: props.map((name) => name.replace(/-([a-z])/g, (_, c) => c.toUpperCase())) };
+}
+
+/** Attribute names in a start tag's attribute text, skipping quoted and `{…}` values. */
+export function attributeNames(text) {
+  const names = [];
+  let i = 0;
+  while (i < text.length) {
+    const character = text[i];
+    if (character === '"' || character === "'") {
+      const end = text.indexOf(character, i + 1);
+      i = end < 0 ? text.length : end + 1;
+    } else if (character === '{') {
+      let depth = 0;
+      for (; i < text.length; i++) {
+        if (text[i] === '{') depth++;
+        else if (text[i] === '}' && --depth === 0) break;
+      }
+      i++;
+    } else if (/[a-zA-Z]/.test(character)) {
+      const name = text.slice(i).match(/^[a-zA-Z][\w:-]*/)[0];
+      names.push(name);
+      i += name.length;
+    } else {
+      i++;
+    }
+  }
+  return names;
+}
+
+/** A component's interface from its Custom Elements Manifest. */
+export function interfaceOf(manifest) {
+  const element = manifest?.modules?.[0]?.declarations?.find((declaration) => declaration.customElement);
+  if (!element) return null;
+  return {
+    tag: element.tagName,
+    description: element.description ?? '',
+    attributes: (element.attributes ?? []).map((attribute) => ({ name: attribute.name, type: attribute.type?.text ?? 'unknown', default: attribute.default })),
+    events: (element.events ?? []).map((event) => ({ name: event.name, type: event.type?.text ?? 'CustomEvent', description: event.description ?? '' })),
+    slots: (element.slots ?? []).map((slot) => slot.name),
+  };
+}
+
+/** Markdown documentation for a component. */
+export function documentation(component) {
+  const lines = [`**<${component.tag}>**`];
+  if (component.description) lines.push('', component.description);
+  if (component.attributes.length) {
+    lines.push('', '| Prop | Type | Default |', '|---|---|---|');
+    for (const attribute of component.attributes) lines.push(`| \`${attribute.name}\` | \`${attribute.type}\` | ${attribute.default === undefined ? 'required' : `\`${attribute.default}\``} |`);
+  }
+  if (component.events.length) {
+    lines.push('', 'Events: ' + component.events.map((event) => `\`${event.name}\` (\`${event.type}\`)`).join(', '));
+  }
+  if (component.slots.length) lines.push('', 'Slots: ' + component.slots.map((name) => (name ? `\`${name}\`` : 'default')).join(', '));
+  return lines.join('\n');
+}
+
+/** The conditions an element can carry as attributes (4.1). */
+export const CONDITIONS = {
+  'zb-if': 'Render this element only when the condition is truthy: `zb-if={…}`.',
+  'zb-else-if': 'Render this element when the `zb-if` (or `zb-else-if`) sibling just before it didn\'t, and this condition is truthy.',
+  'zb-else': 'Render this element when none of the `zb-if` and `zb-else-if` siblings just before it did.',
+};
+const conditionItems = (prefix) => Object.entries(CONDITIONS)
+  .filter(([name]) => name.startsWith(prefix))
+  .map(([name, description]) => ({ label: name, kind: 'attribute', documentation: description, insertText: name === 'zb-else' ? name : `${name}={$1}`, snippet: name !== 'zb-else' }));
+
+/** Completion items (label, kind, detail, documentation, insertText) at `offset`. */
+export function completions(text, offset, components) {
+  const context = contextAt(text, offset);
+  if (context.kind === 'tag') {
+    return [
+      ...Object.entries(DIRECTIVES).map(([name, directive]) => ({ label: name, kind: 'directive', documentation: directive.description })),
+      ...components.map((component) => ({ label: component.tag, kind: 'component', documentation: documentation(component) })),
+    ].filter((item) => item.label.startsWith(context.prefix));
+  }
+  if (context.kind === 'attribute') {
+    const directive = DIRECTIVES[context.tag];
+    if (directive) {
+      return Object.entries(directive.attributes).map(([name, description]) => ({
+        label: name, kind: 'attribute', documentation: description, insertText: name === 'keep' ? 'keep' : ['as', 'index', 'name'].includes(name) ? `${name}="$1"` : `${name}={$1}`, snippet: true,
+      }));
+    }
+    const component = components.find((candidate) => candidate.tag === context.tag);
+    if (!component) return conditionItems(context.prefix);
+    return [
+      ...component.attributes.map((attribute) => ({
+        label: attribute.name, kind: 'attribute', detail: attribute.type,
+        documentation: attribute.default === undefined ? 'Required.' : `Default: \`${attribute.default}\`.`,
+        insertText: `${attribute.name}={$1}`, snippet: true,
+      })),
+      ...component.events.map((event) => ({
+        label: `on${event.name}`, kind: 'event', detail: event.type, documentation: event.description,
+        insertText: `on${event.name}={$1}`, snippet: true,
+      })),
+      ...conditionItems(''),
+    ].filter((item) => item.label.startsWith(context.prefix));
+  }
+  if (context.kind === 'expression') {
+    return (hostOf(text)?.props ?? []).map((name) => ({ label: name, kind: 'variable', detail: 'prop' }));
+  }
+  return [];
+}
+
+/** The tag name under `offset`, with its range. */
+export function tagAt(text, offset) {
+  const start = text.lastIndexOf('<', offset);
+  if (start < 0) return null;
+  const match = text.slice(start).match(/^<\/?([a-zA-Z][\w.-]*)/);
+  if (!match) return null;
+  const nameStart = start + match[0].length - match[1].length;
+  const nameEnd = nameStart + match[1].length;
+  if (offset < nameStart || offset > nameEnd) return null;
+  return { name: match[1], start: nameStart, end: nameEnd };
+}

package/backend.js

@@ -0,0 +1,63 @@
+// How the language server reaches the compiler: the WebAssembly build (@zubra/compiler) when it's
+// installed, otherwise the `zubra` CLI (or the one in `compiler`). Both give the same diagnostics.
+import { spawnSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+
+export async function createBackend({ compiler } = {}) {
+  if (!compiler) {
+    try {
+      const wasm = await import('@zubra/compiler');
+      if (wasm.available()) return wasmBackend(wasm);
+    } catch {
+      // Not installed.
+    }
+  }
+  const chosen = compiler ?? process.env.ZUBRA_COMPILER;
+  if (chosen) return cliBackend(chosen);
+  return cliBackend('zubra');
+}
+
+function wasmBackend(wasm) {
+  return {
+    name: 'wasm',
+    check(path, text) {
+      const files = wasm.sources(path);
+      files[resolve(path)] = text;
+      // Imports of the unsaved text, too.
+      for (const specifier of importsOf(text)) wasm.sources(resolve(dirname(path), specifier), files);
+      return wasm.request({ command: 'check', path: resolve(path), files }).diagnostics;
+    },
+    manifest(path) {
+      const response = wasm.compileFile(path, { emit: 'manifest' });
+      return response.ok ? JSON.parse(response.output) : null;
+    },
+  };
+}
+
+function cliBackend(compiler) {
+  const run = (args, input) => spawnSync(compiler, args, { encoding: 'utf8', input });
+  return {
+    name: 'cli',
+    check(path, text) {
+      const result = run(['check', path, '--stdin', '--format', 'json'], text);
+      if (result.error) return [{ file: path, line: 1, column: 1, severity: 'error', message: `zubra: couldn't run the compiler \`${compiler}\` (${result.error.code ?? result.error.message}); install @zubra/compiler or the zubra CLI`, help: null }];
+      try { return JSON.parse(result.stdout); } catch { return []; }
+    },
+    manifest(path) {
+      const result = run(['compile', path, '--emit', 'manifest']);
+      if (result.status !== 0) return null;
+      try { return JSON.parse(result.stdout); } catch { return null; }
+    },
+  };
+}
+
+/** `.zb` files a component's script imports (relative specifiers). */
+export function importsOf(text) {
+  const script = text.match(/<script[^>]*>([\s\S]*?)<\/script>/i)?.[1] ?? '';
+  return [...script.matchAll(/import\s+(?:[^'"]*?from\s+)?['"](\.{1,2}\/[^'"]+\.zb)['"]/g)].map((match) => match[1]);
+}
+
+export const readText = (path) => {
+  try { return readFileSync(path, 'utf8'); } catch { return null; }
+};

package/package.json

@@ -1,6 +1,34 @@
 {
   "name": "@zubra/language-server",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "5.0.2",
+  "description": "Language server for .zb components: diagnostics, completion, hover and go to definition",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/journey-to-code-org/zubra.git",
+    "directory": "editors/language-server"
+  },
+  "type": "module",
+  "bin": {
+    "zubra-language-server": "server.js"
+  },
+  "exports": {
+    ".": "./server.js",
+    "./analysis": "./analysis.js"
+  },
+  "files": [
+    "server.js",
+    "analysis.js",
+    "backend.js"
+  ],
+  "scripts": {
+    "test": "node --test \"test/*.test.js\""
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "vscode-languageserver": "11.0.0",
+    "vscode-languageserver-textdocument": "1.0.16"
+  }
+}

package/server.js

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+// zubra language server: diagnostics from the compiler as you type, completion of directives,
+// imported components, their props and events, hover documentation from their manifests, and
+// go to definition for imported components. Speaks LSP over stdio (`--stdio`).
+//
+// initializationOptions: { compiler?: "/path/to/zubra" } — otherwise @zubra/compiler (WebAssembly)
+// when installed, else `zubra` on PATH.
+import { createConnection, ProposedFeatures, TextDocuments, TextDocumentSyncKind, DiagnosticSeverity, CompletionItemKind, InsertTextFormat, MarkupKind } from 'vscode-languageserver/node';
+import { TextDocument } from 'vscode-languageserver-textdocument';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { dirname, resolve } from 'node:path';
+import { statSync } from 'node:fs';
+import { createBackend, importsOf, readText } from './backend.js';
+import { completions, documentation, interfaceOf, offsetAt, positionAt, tagAt } from './analysis.js';
+
+const connection = createConnection(ProposedFeatures.all);
+const documents = new TextDocuments(TextDocument);
+let backend;
+const manifests = new Map(); // path → { mtime, component }
+
+connection.onInitialize(async (params) => {
+  backend = await createBackend(params.initializationOptions ?? {});
+  return {
+    capabilities: {
+      textDocumentSync: TextDocumentSyncKind.Incremental,
+      completionProvider: { triggerCharacters: ['<', ' ', '{'] },
+      hoverProvider: true,
+      definitionProvider: true,
+    },
+    serverInfo: { name: 'zubra-language-server', version: '1.2.0' },
+  };
+});
+
+const pathOf = (uri) => fileURLToPath(uri);
+
+/** The components a document imports: { tag, …interface, path }. */
+function componentsOf(uri, text) {
+  const base = dirname(pathOf(uri));
+  const found = [];
+  for (const specifier of importsOf(text)) {
+    const path = resolve(base, specifier);
+    let mtime;
+    try { mtime = statSync(path).mtimeMs; } catch { continue; }
+    let cached = manifests.get(path);
+    if (!cached || cached.mtime !== mtime) {
+      cached = { mtime, component: interfaceOf(backend.manifest(path)) };
+      manifests.set(path, cached);
+    }
+    if (cached.component) found.push({ ...cached.component, path });
+  }
+  return found;
+}
+
+const timers = new Map();
+function validate(document) {
+  clearTimeout(timers.get(document.uri));
+  timers.set(document.uri, setTimeout(() => {
+    const path = pathOf(document.uri);
+    const text = document.getText();
+    const diagnostics = backend.check(path, text)
+      .filter((diagnostic) => resolve(diagnostic.file) === path || diagnostic.file === path)
+      .map((diagnostic) => {
+        const line = Math.max(diagnostic.line - 1, 0);
+        const character = Math.max(diagnostic.column - 1, 0);
+        const lineText = text.split('\n')[line] ?? '';
+        const word = lineText.slice(character).match(/^[\w.$-]+|^./)?.[0] ?? '';
+        return {
+          range: { start: { line, character }, end: { line, character: character + Math.max(word.length, 1) } },
+          severity: diagnostic.severity === 'warning' ? DiagnosticSeverity.Warning : DiagnosticSeverity.Error,
+          source: 'zubra',
+          message: diagnostic.help ? `${diagnostic.message}\n${diagnostic.help}` : diagnostic.message,
+        };
+      });
+    connection.sendDiagnostics({ uri: document.uri, diagnostics });
+  }, 100));
+}
+documents.onDidChangeContent((change) => validate(change.document));
+documents.onDidClose((event) => connection.sendDiagnostics({ uri: event.document.uri, diagnostics: [] }));
+
+const kinds = { directive: CompletionItemKind.Keyword, component: CompletionItemKind.Class, attribute: CompletionItemKind.Property, event: CompletionItemKind.Event, variable: CompletionItemKind.Variable };
+connection.onCompletion(({ textDocument, position }) => {
+  const document = documents.get(textDocument.uri);
+  if (!document) return [];
+  const text = document.getText();
+  return completions(text, offsetAt(text, position), componentsOf(textDocument.uri, text)).map((item) => ({
+    label: item.label,
+    kind: kinds[item.kind],
+    detail: item.detail,
+    documentation: item.documentation ? { kind: MarkupKind.Markdown, value: item.documentation } : undefined,
+    insertText: item.insertText,
+    insertTextFormat: item.snippet ? InsertTextFormat.Snippet : undefined,
+  }));
+});
+
+connection.onHover(({ textDocument, position }) => {
+  const document = documents.get(textDocument.uri);
+  if (!document) return null;
+  const text = document.getText();
+  const tag = tagAt(text, offsetAt(text, position));
+  const component = tag && componentsOf(textDocument.uri, text).find((candidate) => candidate.tag === tag.name);
+  if (!component) return null;
+  return {
+    contents: { kind: MarkupKind.Markdown, value: documentation(component) },
+    range: { start: positionAt(text, tag.start), end: positionAt(text, tag.end) },
+  };
+});
+
+connection.onDefinition(({ textDocument, position }) => {
+  const document = documents.get(textDocument.uri);
+  if (!document) return null;
+  const text = document.getText();
+  const tag = tagAt(text, offsetAt(text, position));
+  const component = tag && componentsOf(textDocument.uri, text).find((candidate) => candidate.tag === tag.name);
+  if (!component) return null;
+  const target = readText(component.path) ?? '';
+  const at = Math.max(target.search(new RegExp(`<${component.tag}[\\s>]`)), 0);
+  const start = positionAt(target, at);
+  return { uri: pathToFileURL(component.path).href, range: { start, end: { line: start.line, character: start.character + component.tag.length + 1 } } };
+});
+
+documents.listen(connection);
+connection.listen();

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-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.