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

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;
}
  • 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