language-service 0.0.2-preview.1

The Zena language service, which gives editors diagnostics, completions and navigation

Readme Files Dependencies Versions

language-service#

The Zena language service and Language Server Protocol (LSP) library: diagnostics, lint findings and quick fixes, hover, completions, go-to-definition, document symbols, and formatting.

Used by zena lsp (in packages/cli) and compiled to WebAssembly by @zena-lang/compiler (packages/compiler-js) for JavaScript, browser, and VS Code hosts.

Usage in Zena#

import { createLanguageService } from 'language-service';
import { LspServer } from 'language-service/server';
import { readFile } from 'zena:fs';

async function readOrNull(path: String): Future<String | null> {
  try {
    return await readFile(path);
  } catch (e) {
    return null;
  }
}

let service = createLanguageService('/stdlib', readOrNull, 'zena-component');
let diagnostics = await service.check('/workspace/main.zena', 'export let x = 42;');

Zena Libraries#

  • language-service / language-service/service — LanguageService (createLanguageService, check, lint, hover, completions, definition, documentSymbols)
  • language-service/server — LspServer JSON-RPC request/notification handler (LspServer, MessageReader, frame, offsetOf, positionOf)
  • language-service/protocol — LSP JSON serializers and error codes
  • language-service/framing — Content-Length message framing (MessageReader, frame)
  • language-service/positions — UTF-16 line/character positions to and from byte offsets (offsetOf, positionOf)
  • language-service/hover — hover type and doc-comment formatting
  • language-service/completion — identifier, member, and keyword completions
  • language-service/symbols — document symbol outline (documentSymbols, DocumentSymbol, SymbolKind)
  • language-service/compile — in-memory compilation to WebAssembly bytes (compileToWasm)
  • language-service/host — overlay CompilerHost serving open documents in place of disk files (DocumentHost)
  • language-service/analysis — per-document checked AST and scope analysis

License#

MIT

15.3 KiB Raw
/**
 * A language server: the Language Server Protocol over the language
 * service, for editors that start a server process and talk to it over
 * its standard input and output (Neovim, Helix, Zed and others).
 *
 * Messages are JSON-RPC, each framed by a `Content-Length` header.
 * `MessageReader` (in `framing.zena`) takes the bytes apart into
 * messages, `LspServer` answers each one, and `frame` puts a reply's
 * header on. The transport is the caller's: `zena lsp` connects them to
 * stdin and stdout.
 *
 * The server keeps whole documents: the client sends the full text of a
 * document when it opens and on every change. Positions in the protocol
 * are a line and a UTF-16 character offset into it; the service works in
 * UTF-8 byte offsets, and `positions.zena` converts.
 */

import { JsonBuilder, JsonObject, JsonValue, parseJson } from 'zena:json';
import { fileURLToPath, pathToFileURL } from 'zena:url';
import { Diagnostic, DiagnosticCode } from 'compiler/diagnostics';
import { format as formatSource } from 'formatter';
import { growable } from 'zena:core';
import { Edit } from 'lint/source';
import { FileReader, LanguageService } from './service.zena';
import { normalizePath } from './host.zena';
import { offsetOf, positionOf } from './positions.zena';
import {
  ErrorCode, RequestError, initializeResult, writeCodeAction, writeCompletion, writeDiagnostic,
  writeHover, writeLintDiagnostic, writeRange, writeSpan, writeSymbol,
} from './protocol.zena';

/** Whether a finding starts at `offset`. */
function hasFindingAt(findings: GrowableArray<Edit>, offset: i32): boolean {
  for (let finding in findings) {
    if (finding.start == offset) {
      return true;
    }
  }
  return false;
}

/** Whether a finding for `rule` lies inside `[start, end)`. */
function hasRuleFindingIn(findings: GrowableArray<Edit>, rule: String,
    start: i32, end: i32): boolean {
  for (let finding in findings) {
    if (finding.rule == rule && finding.start >= start && finding.end <= end) {
      return true;
    }
  }
  return false;
}

export { MessageReader, frame } from './framing.zena';
export { Position, offsetOf, positionOf } from './positions.zena';

/**
 * The path a document's URI names. A URI other than a `file:` one, like
 * the `untitled:` an editor gives a buffer never saved, is used as the
 * path as it is.
 */
function pathOf(uri: String) {
  return if (uri.startsWith('file:')) { fileURLToPath(uri) } else { uri };
}

/** The URI for a path `pathOf` returned. */
function uriOf(path: String) {
  return if (path.startsWith('/')) { pathToFileURL(path) } else { path };
}

/**
 * Answers the protocol's messages from a language service.
 *
 * `send` is called with each outgoing message's JSON: replies to
 * requests, and the diagnostics it publishes when a document opens or
 * changes. Frame it with `frame` before writing it out.
 */
export final class LspServer {
  #service: LanguageService;
  #readFile: FileReader;
  #send: (json: String) => void;
  /** The text of each open document, by path. */
  #documents = new Map<String, String>();
  var #exited = false;

  new(service: LanguageService, readFile: FileReader, send: (json: String) => void)
    : #service = service, #readFile = readFile, #send = send;

  /** True once the client has sent `exit`. */
  exited: boolean {
    get {
      return this.#exited;
    }
  }

  /**
   * Answers one message's body. A message that opens or changes a
   * document checks it, which awaits the service; the caller awaits each
   * message before reading the next, so messages are answered in order.
   */
  async handle(body: String): Future<void> {
    let message = this.#parse(body);
    if (message == null) {
      return;
    }
    let method = message.stringAt('method') ?? '';
    // Absent params read as an empty object, so a request that needs one
    // of its fields gets the error for that field.
    let params = message.objectAt('params') ?? new JsonObject();
    if (!message.has('id')) {
      try {
        await this.#notification(method, params);
      } catch (e) {
        console.error(`zena lsp: ${method}: ${e.message}`);
      }
      return;
    }
    let id = message['id'];
    try {
      let result = await this.#request(method, params);
      if (result == null) {
        this.#error(id, ErrorCode.MethodNotFound, `Unsupported request: ${method}`);
      } else {
        this.#reply(id, result);
      }
    } catch (e) {
      let code = if (e is RequestError) { e.code } else { ErrorCode.InternalError };
      this.#error(id, code, e.message);
    }
  }

  /** A message's JSON object, or null after answering one that is not. */
  #parse(body: String): JsonObject | null {
    let message = try {
      parseJson(body)
    } catch (e) {
      this.#error(null, ErrorCode.ParseError, `Not JSON: ${e.message}`);
      return null;
    };
    if (message is JsonObject) {
      return message;
    }
    this.#error(null, ErrorCode.InvalidRequest, 'A message must be a JSON object');
    return null;
  }

  async #notification(method: String, params: JsonObject): Future<void> {
    match (method) {
      case 'exit': {
        this.#exited = true;
      }
      case 'textDocument/didOpen': {
        await this.#setDocument(this.#uriIn(params), params.stringAt('textDocument.text') ?? '');
      }
      case 'textDocument/didChange': {
        // Full synchronization: the last change holds the whole text.
        if (let (true, changes) = params.arrayAt('contentChanges')) {
          let last = if (changes.length > 0) { changes[changes.length - 1] } else { null };
          if (last is JsonObject) {
            await this.#setDocument(this.#uriIn(params), last.stringAt('text') ?? '');
          }
        }
      }
      case 'textDocument/didClose': {
        let uri = this.#uriIn(params);
        let path = pathOf(uri);
        this.#documents.delete(path);
        this.#service.closeDocument(path);
        this.#publish(uri, path, '', new Array<Diagnostic>(), new GrowableArray<Edit>(0));
      }
      case _: {
        // Everything else ('initialized', '$/cancelRequest', saves) needs
        // nothing from a server that keeps whole documents.
      }
    }
  }

  /** A request's result as JSON, or null for a method the server lacks. */
  async #request(method: String, params: JsonObject): Future<String | null> {
    if (method == 'textDocument/definition') {
      // Reads the file the definition is in, which may be on disk.
      return await this.#definition(params);
    }
    return match (method) {
      case 'initialize': initializeResult()
      case 'shutdown': 'null'
      case 'textDocument/hover': this.#hover(params)
      case 'textDocument/documentSymbol': this.#documentSymbols(params)
      case 'textDocument/completion': this.#completions(params)
      case 'textDocument/formatting': this.#formatting(params)
      case 'textDocument/codeAction': this.#codeActions(params)
      case _: null
    };
  }

  /** The URI of the document a message is about. */
  #uriIn(params: JsonObject): String {
    if (let (true, uri) = params.stringAt('textDocument.uri')) {
      return uri;
    }
    throw new RequestError(ErrorCode.InvalidParams, 'The message names no document');
  }

  /** The text of an open document; empty for one the client has not opened. */
  #openText(path: String): String {
    return this.#documents.getOr(path, '');
  }

  /** The byte offset in `text` of the position a request names. */
  #offsetIn(params: JsonObject, text: String): i32 {
    if (let (true, line) = params.intAt('position.line')) {
      if (let (true, character) = params.intAt('position.character')) {
        return offsetOf(text, {line: line, character: character});
      }
    }
    throw new RequestError(ErrorCode.InvalidParams, 'The request has no position');
  }

  /** Records a document's text, checks it, and publishes what it found. */
  async #setDocument(uri: String, text: String): Future<void> {
    let path = pathOf(uri);
    this.#documents[path] = text;
    let diagnostics = await this.#service.check(path, text);
    this.#publish(uri, path, text, diagnostics, this.#service.lint(path));
  }

  /**
   * Sends the diagnostics that belong to `path`, the checker's and then
   * the lint findings. A check also reports problems in the files a
   * document imports; those are left for when the files are opened
   * themselves. The checker's own "unnecessary cast" warning is left
   * out when the lint rule reports the same cast with its fix.
   */
  #publish(uri: String, path: String, text: String, diagnostics: Array<Diagnostic>,
      findings: GrowableArray<Edit>): void {
    let b = new JsonBuilder();
    b.beginObject().key('jsonrpc').string('2.0')
      .key('method').string('textDocument/publishDiagnostics')
      .key('params').beginObject().key('uri').string(uri)
      .key('diagnostics').beginArray();
    let key = normalizePath(path);
    for (let diagnostic in diagnostics) {
      let location = diagnostic.location;
      if (location == null || normalizePath(location.file) == key) {
        if (diagnostic.code == DiagnosticCode.UnnecessaryCast && location != null &&
            hasFindingAt(findings, location.start)) {
          continue;
        }
        if (diagnostic.code == DiagnosticCode.UnnecessaryNullish && location != null &&
            diagnostic.message.contains('optional chaining') &&
            hasRuleFindingIn(findings, 'unnecessary-optional-chain',
                location.start, location.start + location.length)) {
          continue;
        }
        writeDiagnostic(b, text, diagnostic);
      }
    }
    for (let finding in findings) {
      if (!finding.shared) {
        writeLintDiagnostic(b, text, finding, this.#service.lintMessage(finding));
      }
    }
    b.endArray().endObject().endObject();
    let send = this.#send;
    send(b.toString());
  }

  /**
   * The code actions for a range: a quick fix for each lint finding that
   * touches it, and when the document has any finding at all, one that
   * fixes them all.
   */
  #codeActions(params: JsonObject): String {
    let uri = this.#uriIn(params);
    let path = pathOf(uri);
    let text = this.#openText(path);
    let start = this.#offsetAt(params, 'range.start', text);
    let end = this.#offsetAt(params, 'range.end', text);
    let findings = this.#service.lint(path);
    let b = new JsonBuilder();
    b.beginArray();
    for (let finding in findings) {
      if (finding.shared || finding.end < start || finding.start > end) {
        continue;
      }
      // A fix takes the supporting edits of its rule (an import) along.
      let one = growable<Edit>([finding]);
      for (let other in findings) {
        if (other.shared && other.rule == finding.rule) {
          one.push(other);
        }
      }
      writeCodeAction(b, `Fix: ${this.#service.lintMessage(finding)}`, 'quickfix', uri, text,
          one, this.#diagnosticFor(params, text, finding));
    }
    if (findings.length > 0) {
      writeCodeAction(b, 'Fix all lint findings', 'source.fixAll.zena', uri, text,
          findings, null);
    }
    b.endArray();
    return b.toString();
  }

  /**
   * The diagnostic the client sent for a finding, as JSON, so the quick
   * fix can name it and the editor can clear it; null when the client
   * sent none that starts where the finding does.
   */
  #diagnosticFor(params: JsonObject, text: String, finding: Edit): String | null {
    if (let (true, diagnostics) = params.arrayAt('context.diagnostics')) {
      let at = positionOf(text, finding.start);
      var i = 0;
      while (i < diagnostics.length) {
        let candidate = diagnostics[i];
        i += 1;
        if (candidate is JsonObject) {
          if ((candidate.stringAt('source') ?? '') == 'zena-lint' &&
              (candidate.intAt('range.start.line') ?? -1) == at.line &&
              (candidate.intAt('range.start.character') ?? -1) == at.character) {
            return candidate.stringify();
          }
        }
      }
    }
    return null;
  }

  /** The byte offset in `text` of the position at `key` in the params. */
  #offsetAt(params: JsonObject, key: String, text: String): i32 {
    if (let (true, line) = params.intAt(`${key}.line`)) {
      if (let (true, character) = params.intAt(`${key}.character`)) {
        return offsetOf(text, {line: line, character: character});
      }
    }
    throw new RequestError(ErrorCode.InvalidParams, `The request has no ${key}`);
  }

  #hover(params: JsonObject): String {
    let path = pathOf(this.#uriIn(params));
    let hover = this.#service.getHover(path, this.#offsetIn(params, this.#openText(path)));
    if (hover == null) {
      return 'null';
    }
    let b = new JsonBuilder();
    writeHover(b, hover);
    return b.toString();
  }

  /** The text of a file, open or on disk; null when it cannot be read. */
  async #fileText(path: String): Future<String | null> {
    if (let (true, open) = this.#documents.get(path)) {
      return open;
    }
    let read = this.#readFile;
    return await read(path);
  }

  async #definition(params: JsonObject): Future<String> {
    let path = pathOf(this.#uriIn(params));
    let span = this.#service.getDefinition(path, this.#offsetIn(params, this.#openText(path)));
    if (span == null) {
      return 'null';
    }
    let b = new JsonBuilder();
    b.beginObject().key('uri').string(uriOf(span.file)).key('range');
    let text = await this.#fileText(span.file);
    if (text != null) {
      writeSpan(b, text, span.start, span.start + span.length);
    } else {
      // Without the text, the line and column the span carries are the
      // best there is; the column counts bytes.
      let at = {line: span.line - 1, character: span.column - 1};
      writeRange(b, at, at);
    }
    b.endObject();
    return b.toString();
  }

  #documentSymbols(params: JsonObject): String {
    let path = pathOf(this.#uriIn(params));
    let text = this.#openText(path);
    let b = new JsonBuilder();
    b.beginArray();
    for (let entry in this.#service.getDocumentSymbols(path, text)) {
      writeSymbol(b, text, entry);
    }
    b.endArray();
    return b.toString();
  }

  #completions(params: JsonObject): String {
    let path = pathOf(this.#uriIn(params));
    let b = new JsonBuilder();
    b.beginArray();
    for (let item in this.#service.getCompletions(path, this.#offsetIn(params, this.#openText(path)))) {
      writeCompletion(b, item);
    }
    b.endArray();
    return b.toString();
  }

  /** One edit replacing the whole document, or none if it is formatted. */
  #formatting(params: JsonObject): String {
    let text = this.#openText(pathOf(this.#uriIn(params)));
    let formatted = formatSource(text);
    let b = new JsonBuilder();
    b.beginArray();
    if (formatted != text) {
      b.beginObject().key('range');
      writeSpan(b, text, 0, text.length);
      b.key('newText').string(formatted).endObject();
    }
    b.endArray();
    return b.toString();
  }

  /** Sends a request's result, given as JSON. */
  #reply(id: JsonValue, result: String): void {
    let b = new JsonBuilder();
    b.beginObject()
      .key('jsonrpc').string('2.0')
      .key('id').value(id)
      .key('result').raw(result)
      .endObject();
    let send = this.#send;
    send(b.toString());
  }

  #error(id: JsonValue, code: ErrorCode, message: String): void {
    let b = new JsonBuilder();
    b.beginObject()
      .key('jsonrpc').string('2.0')
      .key('id').value(id)
      .key('error').beginObject()
        .key('code').i32(code as i32)
        .key('message').string(message)
        .endObject()
      .endObject();
    let send = this.#send;
    send(b.toString());
  }
}
  • compiler compiler.zena-lang.pkg.zena-lang.dev 0.0.2-preview.1
  • formatter formatter.zena-lang.pkg.zena-lang.dev 0.0.2-preview.1
  • lint lint.zena-lang.pkg.zena-lang.dev 0.0.2-preview.1
VersionPublishedDependenciesApproved by
0.0.2-preview.1 2026-11-19
  • compiler compiler.zena-lang.pkg.zena-lang.dev 0.0.2-preview.1
  • formatter formatter.zena-lang.pkg.zena-lang.dev 0.0.2-preview.1
  • lint lint.zena-lang.pkg.zena-lang.dev 0.0.2-preview.1