language-service 0.0.2-preview.1
The Zena language service, which gives editors diagnostics, completions and navigation
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—LspServerJSON-RPC request/notification handler (LspServer,MessageReader,frame,offsetOf,positionOf)language-service/protocol— LSP JSON serializers and error codeslanguage-service/framing—Content-Lengthmessage 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 formattinglanguage-service/completion— identifier, member, and keyword completionslanguage-service/symbols— document symbol outline (documentSymbols,DocumentSymbol,SymbolKind)language-service/compile— in-memory compilation to WebAssembly bytes (compileToWasm)language-service/host— overlayCompilerHostserving 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());
}
}
| Version | Published | Dependencies | Approved by |
|---|---|---|---|
| 0.0.2-preview.1 | 2026-11-19 |
|