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
16.0 KiB
Raw
/**
* Language service entry point.
*
* This module is compiled to WASM and loaded by the VS Code extension.
* It exports functions that the JS host calls to check source files,
* format documents, and read back diagnostics.
*
* The API is handle-based: check() returns an opaque result reference
* (a WASM GC object passed as externref). The host passes this handle
* back to getter functions to read individual diagnostic fields. When
* the JS side drops the reference, the WASM GC collects the result.
*
* String parameters (source, path) are passed as externref via the
* $stringCreate/$stringSetByte exports. String results (messages) are
* returned as externref and read via $stringGetByte/$stringGetLength.
*
* Cross-module imports are resolved via the full Compiler pipeline.
* The host provides a read_file import so the compiler can load
* dependency sources from the filesystem.
*/
import { Diagnostic, DiagnosticSeverity, SourceSpan } from 'compiler/diagnostics';
import { PackageConfig } from 'compiler/module-resolver';
import { loadWorkspace } from 'compiler/package-manifest';
import { DocumentHost } from './host.zena';
import { format as formatSource } from 'formatter';
import {
CompletionItem, DocumentSymbol, Edit, HoverResult, LanguageService,
createLanguageService,
} from './service.zena';
import { compileToWasm as compileDocument } from './compile.zena';
import { pending, toPromise } from 'zena:js';
// ============================================================================
// Host imports
// ============================================================================
/**
* Read a file from the host filesystem by absolute path. The JS side
* provides this import at instantiation time, as a host-async import
* (`asyncImports` in `@zena-lang/runtime`): it completes `handle` with
* the file's text, or fails it when there is no such file.
*/
@external("compiler", "read_file")
declare function __read_file(handle: i32, path: String, len: i32): void;
@external("compiler", "list_dir")
declare function __list_dir(handle: i32, path: String, len: i32): void;
/**
* Reads a file through the JS host's `read_file` import; null when
* there is no such file.
*/
async function readHostFile(path: String): Future<String | null> {
let p = pending<String>();
__read_file(p.handle, path, path.length);
try {
return await p.future;
} catch (e) {
return null;
}
}
/**
* Lists directory entry names through the JS host's `list_dir` import
* (newline-joined); null when the path is not a directory.
*/
async function readHostDir(path: String): Future<Array<String> | null> {
let p = pending<String>();
__list_dir(p.handle, path, path.length);
try {
let raw = await p.future;
let out = new Array<String>();
if (raw != '') {
for (let part in raw.split('\n')) {
out.push(part);
}
}
return out;
} catch (e) {
return null;
}
}
// ============================================================================
// WASM Exports — flat function API for the JS host
// ============================================================================
/** Singleton LanguageService, created by init(). */
var __ls: LanguageService | null = null;
/**
* The exports that compile, or read files, await the service, and a
* Wasm export cannot return a `Future` the host could use. Each returns
* a JavaScript promise instead, which `toPromise` settles as the future
* does: with the handle the synchronous export used to return, or a
* rejection carrying the failure's message.
*/
/**
* Initialize the language service with the path to the stdlib sources.
* Must be called once before check(); the promise settles when the
* service is ready.
*/
export function init(stdlibRoot: String): anyref {
return toPromise(initService(stdlibRoot, 'zena-js', '.', ''));
}
/**
* Initialize the language service with explicit target, workspace root,
* and package cache directory (empty string for none).
*/
export function initWithOptions(
stdlibRoot: String,
target: String,
workspaceRoot: String,
packageCache: String,
): anyref {
return toPromise(initService(stdlibRoot, target, workspaceRoot, packageCache));
}
async function initService(
stdlibRoot: String,
target: String,
workspaceRoot: String,
packageCache: String,
): Future<void> {
// The workspace's packages, when the host can read its manifests from
// `workspaceRoot`, so that imports like `zena-lang:wit-parser` or
// `protobuf/runtime` resolve the way they do for `zena build`.
let root = if (workspaceRoot == '') { '.' } else { workspaceRoot };
let cache = if (packageCache == '') { null } else { packageCache };
let manifestPath = if (root == '.') {
'zena-package.json'
} else if (root == '/') {
'/zena-package.json'
} else {
`${root}/zena-package.json`
};
let manifest = await readHostFile(manifestPath);
let packageMap: Map<String, PackageConfig> | null = if (manifest != null) {
try {
await loadWorkspace(
new DocumentHost(stdlibRoot, readHostFile, readHostDir),
root,
null,
cache,
)
} catch (e) {
console.error(`Failed to load workspace at ${root}: ${e.message}`);
null
}
} else {
null
};
__ls = createLanguageService(
stdlibRoot,
readHostFile,
if (target == '') { 'zena-js' } else { target },
packageMap,
readHostDir,
);
}
/**
* Check a source file. See LanguageService.check(). The promise resolves
* with the diagnostics' handle.
*/
export function check(path: String, source: String): anyref {
return toPromise((__ls as LanguageService).check(path, source));
}
/**
* Check a source file against an explicit target.
*/
export function checkForTarget(path: String, source: String, target: String): anyref {
return toPromise((__ls as LanguageService).checkForTarget(path, source, target));
}
/**
* Register or update an open document.
*/
export function openDocument(path: String, source: String): void {
if (__ls != null) {
__ls.openDocument(path, source);
}
}
/**
* Close an open document and remove it from cache.
*/
export function closeDocument(path: String): void {
if (__ls != null) {
__ls.closeDocument(path);
}
}
/**
* Format a Zena source string and return the formatted result.
*/
export function format(source: String): String {
return formatSource(source);
}
/**
* Find the definition at a byte offset. See LanguageService.getDefinition().
*/
export function getDefinition(path: String, offset: i32): SourceSpan | null {
return (__ls as LanguageService).getDefinition(path, offset);
}
// ============================================================================
// Definition Getters
// ============================================================================
/**
* Get the file path of a definition result.
*/
export function getDefinitionFile(result: SourceSpan): String {
return result.file;
}
/**
* Get the 1-based line number of a definition result.
*/
export function getDefinitionLine(result: SourceSpan): i32 {
return result.line;
}
/**
* Get the 1-based column number of a definition result.
*/
export function getDefinitionColumn(result: SourceSpan): i32 {
return result.column;
}
/**
* Get the 0-based start byte offset of a definition result.
*/
export function getDefinitionStart(result: SourceSpan): i32 {
return result.start;
}
/**
* Get the byte length of the definition span.
*/
export function getDefinitionLength(result: SourceSpan): i32 {
return result.length;
}
// ============================================================================
// Diagnostic Getters
// ============================================================================
/**
* Get the number of diagnostics in a result.
*/
export function getDiagnosticCount(diagnostics: Array<Diagnostic>): i32 {
return diagnostics.length;
}
/**
* Get the 1-based line number of the i-th diagnostic.
* Returns 0 if the diagnostic has no location.
*/
export function getDiagnosticLine(diagnostics: Array<Diagnostic>, index: i32): i32 {
let diag = diagnostics[index];
if (diag.location != null) {
return (diag.location as SourceSpan).line;
}
return 0;
}
/**
* Get the 1-based column number of the i-th diagnostic.
* Returns 0 if the diagnostic has no location.
*/
export function getDiagnosticColumn(diagnostics: Array<Diagnostic>, index: i32): i32 {
let diag = diagnostics[index];
if (diag.location != null) {
return (diag.location as SourceSpan).column;
}
return 0;
}
/**
* Get the 0-based start byte offset of the i-th diagnostic.
* Returns -1 if the diagnostic has no location.
*/
export function getDiagnosticStart(diagnostics: Array<Diagnostic>, index: i32): i32 {
let diag = diagnostics[index];
if (diag.location != null) {
return (diag.location as SourceSpan).start;
}
return -1;
}
/**
* Get the byte length of the span of the i-th diagnostic.
* Returns 0 if the diagnostic has no location.
*/
export function getDiagnosticLength(diagnostics: Array<Diagnostic>, index: i32): i32 {
let diag = diagnostics[index];
if (diag.location != null) {
return (diag.location as SourceSpan).length;
}
return 0;
}
/**
* Get the severity of the i-th diagnostic as an i32.
* 0 = Error, 1 = Warning, 2 = Information.
*/
export function getDiagnosticSeverity(diagnostics: Array<Diagnostic>, index: i32): i32 {
let diag = diagnostics[index];
match (diag.severity) {
case DiagnosticSeverity.Error: 0
case DiagnosticSeverity.Warning: 1
case DiagnosticSeverity.Information: 2
}
}
/**
* Get the message of the i-th diagnostic.
*/
export function getDiagnosticMessage(diagnostics: Array<Diagnostic>, index: i32): String {
return diagnostics[index].message;
}
/**
* Get the file path of the i-th diagnostic.
* Returns an empty string if the diagnostic has no location.
*/
export function getDiagnosticFile(diagnostics: Array<Diagnostic>, index: i32): String {
let diag = diagnostics[index];
if (diag.location != null) {
return (diag.location as SourceSpan).file;
}
return "";
}
// ============================================================================
// Hover Exports
// ============================================================================
/**
* Get hover information at a byte offset.
* Returns a HoverResult or null if no info is available.
*/
export function getHover(path: String, offset: i32): HoverResult | null {
return (__ls as LanguageService).getHover(path, offset);
}
/**
* Get the type string from a hover result (e.g., "i32", "(a: i32) => i32").
*/
export function getHoverType(result: HoverResult): String {
return result.typeStr;
}
/**
* Get the display label from a hover result (e.g., "let x: i32").
*/
export function getHoverLabel(result: HoverResult): String {
return result.label;
}
/**
* Get the doc comment from a hover result.
* Returns an empty string if no doc comment is available.
*/
export function getHoverDoc(result: HoverResult): String {
return result.docComment;
}
// ============================================================================
// Document Symbols Exports
// ============================================================================
/**
* Get document symbols for the outline view.
*/
export function getDocumentSymbols(path: String, source: String): Array<DocumentSymbol> {
return (__ls as LanguageService).getDocumentSymbols(path, source);
}
/**
* Get the number of symbols in a result array.
*/
export function getSymbolCount(symbols: Array<DocumentSymbol>): i32 {
return symbols.length;
}
/**
* Get the i-th symbol from a result array.
*/
export function getSymbol(symbols: Array<DocumentSymbol>, index: i32): DocumentSymbol {
return symbols[index];
}
/**
* Get the name of a symbol.
*/
export function getSymbolName(sym: DocumentSymbol): String {
return sym.name;
}
/**
* Get the kind of a symbol (VS Code SymbolKind value).
*/
export function getSymbolKind(sym: DocumentSymbol): i32 {
return sym.kind as i32;
}
/**
* Get the full range start byte offset of a symbol.
*/
export function getSymbolStart(sym: DocumentSymbol): i32 {
return sym.start;
}
/**
* Get the full range end byte offset of a symbol.
*/
export function getSymbolEnd(sym: DocumentSymbol): i32 {
return sym.end;
}
/**
* Get the selection range start byte offset of a symbol.
*/
export function getSymbolSelStart(sym: DocumentSymbol): i32 {
return sym.selStart;
}
/**
* Get the selection range end byte offset of a symbol.
*/
export function getSymbolSelEnd(sym: DocumentSymbol): i32 {
return sym.selEnd;
}
/**
* Get the number of children of a symbol.
*/
export function getSymbolChildCount(sym: DocumentSymbol): i32 {
return sym.children.length;
}
/**
* Get the i-th child of a symbol.
*/
export function getSymbolChild(sym: DocumentSymbol, index: i32): DocumentSymbol {
return sym.children[index];
}
// ============================================================================
// Lint Exports
// ============================================================================
/**
* What the lint rules find in a document `check` has seen: each finding
* is a byte range and the text that fixes it. See LanguageService.lint().
*/
export function lint(path: String): Array<Edit> {
return (__ls as LanguageService).lint(path);
}
export function getLintCount(findings: Array<Edit>): i32 {
return findings.length;
}
/** The 0-based start byte offset of the i-th finding. */
export function getLintStart(findings: Array<Edit>, index: i32): i32 {
return findings[index].start;
}
/** The byte offset just past the i-th finding. */
export function getLintEnd(findings: Array<Edit>, index: i32): i32 {
return findings[index].end;
}
/** The name of the rule behind the i-th finding. */
export function getLintRule(findings: Array<Edit>, index: i32): String {
return findings[index].rule;
}
/** The one-line message of the i-th finding. */
export function getLintMessage(findings: Array<Edit>, index: i32): String {
return (__ls as LanguageService).lintMessage(findings[index]);
}
/** The text that replaces the i-th finding's range to fix it. */
export function getLintReplacement(findings: Array<Edit>, index: i32): String {
return findings[index].replacement;
}
/**
* Whether the i-th entry supports the fixes of its rule (an import they
* need) rather than being a finding: shown as nothing, applied with any
* fix of that rule.
*/
export function getLintShared(findings: Array<Edit>, index: i32): boolean {
return findings[index].shared;
}
/**
* Compile source to WebAssembly binary (ByteArray). The promise resolves
* with the bytes' handle, or null when the source does not compile.
*/
export function compileToWasm(path: String, source: String): anyref {
return toPromise(compileDocument(__ls as LanguageService, path, source));
}
/**
* Compile source to WebAssembly binary (ByteArray) for an explicit target.
*/
export function compileToWasmForTarget(path: String, source: String, target: String): anyref {
return toPromise(compileDocument(__ls as LanguageService, path, source, target));
}
/**
* Get the length of a ByteArray.
*/
export function getByteArrayLength(bytes: ByteArray): i32 {
return bytes.length;
}
/**
* Get byte at index from ByteArray.
*/
export function getByteArrayByte(bytes: ByteArray, index: i32): i32 {
// A byte reads as `u8` now that ByteArray is `array<u8>`. The i32
// return is the host boundary's shape, so widen explicitly.
return bytes[index] as i32;
}
/**
* Get code completions at the specified offset.
*/
export function getCompletions(path: String, offset: i32): Array<CompletionItem> {
return (__ls as LanguageService).getCompletions(path, offset);
}
export function getCompletionCount(items: Array<CompletionItem>): i32 {
return items.length;
}
export function getCompletionItem(items: Array<CompletionItem>, index: i32): CompletionItem {
return items[index];
}
export function getCompletionLabel(item: CompletionItem): String {
return item.label;
}
export function getCompletionKind(item: CompletionItem): i32 {
return item.kind as i32;
}
export function getCompletionDetail(item: CompletionItem): String {
return item.detail;
}
export function getCompletionDoc(item: CompletionItem): String {
return item.docComment;
}
| Version | Published | Dependencies | Approved by |
|---|---|---|---|
| 0.0.2-preview.1 | 2026-11-19 |
|