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
7.5 KiB
Raw
/**
* Document symbols: the outline of a file, its declarations and their
* members. In a test file the suites and tests are in it too.
*/
import {
Node, SourceLocation, Identifier, IdentifierPattern, Expression, Module, ClassDeclaration, InterfaceDeclaration, EnumDeclaration, MixinDeclaration, TypeAliasDeclaration, DeclareFunction, SymbolDeclaration, ImportDeclaration, VariableDeclaration, FunctionDeclaration, ExpressionStatement, BlockStatement, FunctionExpression, CallExpression, StringLiteral, MethodDefinition, FieldDefinition, AccessorDeclaration, MethodSignature, AccessorSignature,
} from 'compiler/ast';
/**
* The kinds of symbol Zena reports, numbered as the language server
* protocol's `SymbolKind` numbers them.
*/
export enum SymbolKind {
Class = 5,
Method = 6,
Property = 8,
Constructor = 9,
Enum = 10,
Interface = 11,
Function = 12,
Variable = 13,
EnumMember = 22,
}
/**
* A declaration in the outline: the span of the whole declaration, the
* span of its name, and the declarations inside it.
*/
export class DocumentSymbol {
name: String;
kind: SymbolKind;
start: i32;
end: i32;
selStart: i32;
selEnd: i32;
var children: GrowableArray<DocumentSymbol> = new Array<DocumentSymbol>();
new(this.name, this.kind, this.start, this.end, this.selStart, this.selEnd);
}
function startOf(loc: SourceLocation | null): i32 {
return loc?.start ?? 0;
}
function endOf(loc: SourceLocation | null): i32 {
return loc?.end ?? 0;
}
/**
* A symbol spanning `loc`, whose name is at `nameLoc`, or anywhere in
* `loc` when the name has no location of its own.
*/
function symbolAt(
name: String,
kind: SymbolKind,
loc: SourceLocation | null,
nameLoc: SourceLocation | null,
) {
let selection = nameLoc ?? loc;
return new DocumentSymbol(name, kind, startOf(loc), endOf(loc), startOf(selection), endOf(selection));
}
/** A symbol for a declaration whose name is an identifier node. */
function namedSymbol(name: Node, kind: SymbolKind, loc: SourceLocation | null) {
let text = if (let Identifier {name as id} = name) { id } else { '<unknown>' };
return symbolAt(text, kind, loc, name.loc);
}
/** Adds a class or interface body's members to `parent`. */
function addMembers(body: Array<Node>, parent: DocumentSymbol) {
for (let member in body) {
let child = match (member) {
case MethodDefinition {name, loc}: {
let isConstructor = if (let Identifier {name as id} = name) {
id == 'new' || id == '<constructor>'
} else {
false
};
let kind = if (isConstructor) { SymbolKind.Constructor } else { SymbolKind.Method };
namedSymbol(name, kind, loc)
}
case FieldDefinition {name, loc}: namedSymbol(name, SymbolKind.Property, loc)
case AccessorDeclaration {name, loc}: namedSymbol(name, SymbolKind.Property, loc)
case MethodSignature {name, loc}: namedSymbol(name, SymbolKind.Method, loc)
case AccessorSignature {name, loc}: namedSymbol(name, SymbolKind.Property, loc)
case _: null
};
if (child != null) {
parent.children.push(child);
}
}
}
/** Whether the module imports `zena:test`, which makes it a test file. */
function isTestFile(ast: Module): boolean {
for (let stmt in ast.body) {
if (let ImportDeclaration {moduleSpecifier} = stmt) {
if (moduleSpecifier.value == 'zena:test') {
return true;
}
}
}
return false;
}
/**
* The callback of a call to the test framework's `suite` or `test`,
* like the function in `suite('parser', () => { ... })`, when `expr` is
* a call to `fn`.
*/
function testCallback(expr: Expression, fn: String): FunctionExpression | null {
return match (expr) {
case CallExpression {callee: Identifier {name}, args} if name == fn && args.length >= 2: {
let callback = args[1];
if (callback is FunctionExpression) { callback } else { null }
}
case _: null
};
}
/**
* Adds the suites and tests a function body declares to `parent`,
* nesting each suite's own.
*/
function addTests(body: Node, parent: DocumentSymbol) {
if (let BlockStatement {body as statements} = body) {
for (let stmt in statements) {
if (let ExpressionStatement {expression} = stmt) {
addTest(expression, parent);
}
}
}
}
/** Adds a `suite(...)` or `test(...)` call with a literal name to `parent`. */
function addTest(expr: Expression, parent: DocumentSymbol): void {
if (let CallExpression {callee: Identifier {name as fn}, args, loc} = expr) {
if (fn != 'suite' && fn != 'test') {
return;
}
let callback = testCallback(expr, fn);
if (callback == null) {
return;
}
if (let StringLiteral {value} = args[0]) {
let isSuite = fn == 'suite';
let entry = symbolAt(value, if (isSuite) { SymbolKind.Method } else { SymbolKind.Function }, loc, null);
if (isSuite) {
addTests(callback.body, entry);
}
parent.children.push(entry);
}
}
}
/**
* The symbol for a top-level `let` or `var` that binds a name. A function
* value is a function, and so is a test file's suite.
*/
function variableSymbol(
pattern: Node,
init: Expression,
loc: SourceLocation | null,
inTestFile: boolean,
): DocumentSymbol | null {
if (let IdentifierPattern {name} = pattern) {
let suite = if (inTestFile) { testCallback(init, 'suite') } else { null };
let isFunction = init is FunctionExpression;
let kind = if (isFunction || suite != null) { SymbolKind.Function } else { SymbolKind.Variable };
let entry = symbolAt(name, kind, loc, pattern.loc);
if (suite != null) {
addTests(suite.body, entry);
} else if (inTestFile && init is FunctionExpression) {
addTests(init.body, entry);
}
return entry;
}
return null;
}
/** The symbol for a top-level statement, or null for one that declares nothing. */
function statementSymbol(stmt: Node, inTestFile: boolean): DocumentSymbol | null {
return match (stmt) {
case ClassDeclaration {name, body, sealedVariants, loc}: {
let entry = namedSymbol(name, SymbolKind.Class, loc);
addMembers(body, entry);
if (sealedVariants != null) {
for (let variant in sealedVariants) {
entry.children.push(namedSymbol(variant.name, SymbolKind.Class, variant.loc));
}
}
entry
}
case InterfaceDeclaration {name, body, loc}: {
let entry = namedSymbol(name, SymbolKind.Interface, loc);
addMembers(body, entry);
entry
}
case EnumDeclaration {name, members, loc}: {
let entry = namedSymbol(name, SymbolKind.Enum, loc);
for (let member in members) {
entry.children.push(namedSymbol(member.name, SymbolKind.EnumMember, member.loc));
}
entry
}
case MixinDeclaration {name, loc}: namedSymbol(name, SymbolKind.Class, loc)
case TypeAliasDeclaration {name, loc}: namedSymbol(name, SymbolKind.Variable, loc)
case DeclareFunction {name, loc}: namedSymbol(name, SymbolKind.Function, loc)
case SymbolDeclaration {name, loc}: namedSymbol(name, SymbolKind.Variable, loc)
case FunctionDeclaration {name, func, loc}: {
let entry = symbolAt(name.name, SymbolKind.Function, loc, name.loc);
if (inTestFile) {
addTests(func.body, entry);
}
entry
}
case VariableDeclaration {pattern, init, loc}: variableSymbol(pattern, init, loc, inTestFile)
case _: null
};
}
/** The outline of a module: its top-level declarations, with their members. */
export function documentSymbols(ast: Module): Array<DocumentSymbol> {
let symbols = new Array<DocumentSymbol>();
let inTestFile = isTestFile(ast);
for (let stmt in ast.body) {
let entry = statementSymbol(stmt, inTestFile);
if (entry != null) {
symbols.push(entry);
}
}
return symbols;
}
| Version | Published | Dependencies | Approved by |
|---|---|---|---|
| 0.0.2-preview.1 | 2026-11-19 |
|