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

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