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

6.5 KiB Raw
/**
 * The protocol's JSON: how the server writes positions, ranges,
 * diagnostics, symbols and completions, what it says it can do, and the
 * codes it answers a failed request with.
 */

import { JsonBuilder } from 'zena:json';
import { Diagnostic, DiagnosticSeverity } from 'compiler/diagnostics';
import { CompletionItem } from './completion.zena';
import { HoverResult } from './hover.zena';
import { DocumentSymbol } from './symbols.zena';
import { Position, positionOf } from './positions.zena';
import { Edit } from 'lint/source';

/** The JSON-RPC error codes the server answers with. */
export enum ErrorCode {
  ParseError = -32700,
  InvalidRequest = -32600,
  MethodNotFound = -32601,
  InvalidParams = -32602,
  InternalError = -32603,
}

/** A request that cannot be answered, and the code to answer it with. */
export class RequestError extends Error {
  code: ErrorCode;

  new(code: ErrorCode, message: String) : code = code, super(message);
}

/** The protocol's DiagnosticSeverity number for a severity. */
function severityNumber(severity: DiagnosticSeverity): i32 {
  return match (severity) {
  case DiagnosticSeverity.Error: 1
  case DiagnosticSeverity.Warning: 2
  case DiagnosticSeverity.Information: 3
};
}

export function writePosition(b: JsonBuilder, position: Position): void {
  b.beginObject()
    .key('line').i32(position.line)
    .key('character').i32(position.character)
    .endObject();
}

export function writeRange(b: JsonBuilder, start: Position, end: Position): void {
  b.beginObject().key('start');
  writePosition(b, start);
  b.key('end');
  writePosition(b, end);
  b.endObject();
}

/** The range of the bytes `start` to `end` of `source`. */
export function writeSpan(b: JsonBuilder, source: String, start: i32, end: i32): void {
  writeRange(b, positionOf(source, start), positionOf(source, end));
}

/** Markdown content: `{kind: 'markdown', value}`. */
function writeMarkdown(b: JsonBuilder, value: String) {
  b.beginObject().key('kind').string('markdown').key('value').string(value).endObject();
}

/** A diagnostic in `source`, the text of the document it belongs to. */
export function writeDiagnostic(b: JsonBuilder, source: String, diagnostic: Diagnostic): void {
  b.beginObject().key('range');
  let location = diagnostic.location;
  if (location == null) {
    writeSpan(b, source, 0, 0);
  } else {
    writeSpan(b, source, location.start, location.start + location.length);
  }
  b.key('severity').i32(severityNumber(diagnostic.severity))
    .key('source').string('zena')
    .key('message').string(diagnostic.message)
    .endObject();
}

/**
 * A lint finding as a diagnostic: a warning from the rules in
 * `packages/lint`, with `zena-lint` as its source, which an editor shows
 * beside other linters', and the rule as its code so a client can filter
 * on it.
 */
export function writeLintDiagnostic(b: JsonBuilder, source: String, edit: Edit, message: String): void {
  b.beginObject().key('range');
  writeSpan(b, source, edit.start, edit.end);
  b.key('severity').i32(2)
    .key('source').string('zena-lint')
    .key('code').string(edit.rule)
    .key('message').string(message)
    .endObject();
}

/** A `TextEdit`: the bytes `start` to `end` of `source` become `newText`. */
export function writeTextEdit(b: JsonBuilder, source: String, start: i32, end: i32, newText: String): void {
  b.beginObject().key('range');
  writeSpan(b, source, start, end);
  b.key('newText').string(newText).endObject();
}

/**
 * A `CodeAction` editing one document: `edits` applied to `uri`, whose
 * text is `source`. `diagnosticsJson` is the finding's diagnostic as the
 * client sent it back, or null for an action that answers no diagnostic.
 */
export function writeCodeAction(
  b: JsonBuilder,
  title: String,
  kind: String,
  uri: String,
  source: String,
  edits: GrowableArray<Edit>,
  diagnosticJson: String | null
): void {
  b.beginObject().key('title').string(title).key('kind').string(kind);
  if (diagnosticJson != null) {
    b.key('diagnostics').beginArray().raw(diagnosticJson).endArray();
  }
  b.key('edit').beginObject().key('changes').beginObject().key(uri).beginArray();
  for (let edit in edits) {
    writeTextEdit(b, source, edit.start, edit.end, edit.replacement);
  }
  b.endArray().endObject().endObject().endObject();
}

/** A hover: the label as Zena code, then the doc comment if there is one. */
export function writeHover(b: JsonBuilder, hover: HoverResult): void {
  let label = `\`\`\`zena\n${hover.label}\n\`\`\``;
  let value = if (hover.docComment == '') { label } else { `${label}\n\n---\n\n${hover.docComment}` };
  b.beginObject().key('contents');
  writeMarkdown(b, value);
  b.endObject();
}

export function writeSymbol(b: JsonBuilder, source: String, entry: DocumentSymbol): void {
  b.beginObject()
    .key('name').string(entry.name)
    .key('kind').i32(entry.kind as i32)
    .key('range');
  writeSpan(b, source, entry.start, entry.end);
  b.key('selectionRange');
  writeSpan(b, source, entry.selStart, entry.selEnd);
  if (entry.children.length > 0) {
    b.key('children').beginArray();
    for (let child in entry.children) {
      writeSymbol(b, source, child);
    }
    b.endArray();
  }
  b.endObject();
}

export function writeCompletion(b: JsonBuilder, item: CompletionItem): void {
  b.beginObject()
    .key('label').string(item.label)
    .key('kind').i32(item.kind as i32);
  if (item.detail != '') {
    b.key('detail').string(item.detail);
  }
  if (item.docComment != '') {
    b.key('documentation');
    writeMarkdown(b, item.docComment);
  }
  b.endObject();
}

/** What the server can do, as `initialize` reports it. */
export function initializeResult(): String {
  let b = new JsonBuilder();
  b.beginObject().key('capabilities').beginObject()
    // Full text on open and on every change (TextDocumentSyncKind.Full).
    .key('textDocumentSync').beginObject()
      .key('openClose').bool(true).key('change').i32(1).endObject()
    .key('hoverProvider').bool(true)
    .key('definitionProvider').bool(true)
    .key('documentSymbolProvider').bool(true)
    .key('completionProvider').beginObject()
      .key('triggerCharacters').beginArray().string('.').endArray().endObject()
    .key('documentFormattingProvider').bool(true)
    // Each lint finding is a quick fix; `source.fixAll.zena` applies them
    // all, for clients that run one on save.
    .key('codeActionProvider').beginObject()
      .key('codeActionKinds').beginArray()
        .string('quickfix').string('source.fixAll.zena').endArray()
      .endObject()
    .endObject()
    .key('serverInfo').beginObject().key('name').string('zena').endObject()
    .endObject();
  return 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