@venn-lang/lsp 0.1.0

package/src/signature/render-shape.ts

@@ -0,0 +1,92 @@
+import type { ParamSpec } from "@venn-lang/sdk";
+import type { ParameterInformation, SignatureInformation } from "vscode-languageserver";
+import type { CallShape, ShownArg } from "./call-shape.types.js";
+
+/**
+ * A call written out the way it is actually written: `http.on server handler`,
+ * no brackets, no commas. Each argument carries the character range it occupies
+ * in that line, which is what lets the editor bold the one being typed instead
+ * of guessing by substring.
+ */
+export function signatureOfShape(shape: CallShape): SignatureInformation {
+  return render(shape, { open: " ", separator: " ", close: "" });
+}
+
+/**
+ * The same call, written the way a bracketed one is: `saudacao(nome: a, idade: b)`.
+ *
+ * Two renderings because the language has two call syntaxes, and a hint that
+ * shows the wrong one teaches the wrong thing.
+ */
+export function bracketed(shape: CallShape): SignatureInformation {
+  return render(shape, { open: "(", separator: ", ", close: ")" });
+}
+
+interface Punctuation {
+  open: string;
+  separator: string;
+  close: string;
+}
+
+/**
+ * One renderer for both syntaxes: only the punctuation between the parts
+ * differs, and the options are the last part in either. They are an argument
+ * like any other, so they get a range and documentation of their own rather
+ * than being printed as decoration nobody can point at.
+ */
+function render(shape: CallShape, punctuation: Punctuation): SignatureInformation {
+  const texts = [...shape.args.map(label), ...optionsPart(shape)];
+  const parameters: ParameterInformation[] = [];
+  let at = shape.target.length + punctuation.open.length;
+  texts.forEach((text, index) => {
+    parameters.push({ label: [at, at + text.length], documentation: docFor(shape, index) });
+    at += text.length + punctuation.separator.length;
+  });
+  const body = texts.join(punctuation.separator);
+  return {
+    label: `${shape.target}${texts.length ? punctuation.open : ""}${body}${texts.length ? punctuation.close : ""}`,
+    parameters,
+    documentation: summary(shape),
+  };
+}
+
+/** The options, when the verb accepts any: one last argument, always a map. */
+function optionsPart(shape: CallShape): string[] {
+  return shape.options.length > 0 ? ["{ … }"] : [];
+}
+
+/** An argument's own line, or, for the last part, the keys the map accepts. */
+function docFor(shape: CallShape, index: number): string | undefined {
+  const arg = shape.args[index];
+  if (arg) return arg.doc;
+  return shape.options.map(optionLine).join("\n");
+}
+
+function optionLine(spec: ParamSpec): string {
+  const required = spec.required ? " *(required)*" : "";
+  const doc = spec.doc ? ` — ${spec.doc}` : "";
+  return `- \`${spec.name}\`: \`${spec.type}\`${required}${doc}`;
+}
+
+/**
+ * `server: HttpServer`, or `reason?: string` when the call works without it.
+ * An argument nobody named shows as its type alone, rather than as a stray colon.
+ */
+function label(arg: ShownArg): string {
+  if (!arg.name) return arg.type;
+  return `${arg.name}${mark(arg)}: ${arg.type}`;
+}
+
+function mark(arg: ShownArg): string {
+  if (arg.rest) return "…";
+  return arg.optional ? "?" : "";
+}
+
+/**
+ * The line under the signature. It says what the verb does and what it gives
+ * back: the two questions someone halfway through typing it is asking.
+ */
+function summary(shape: CallShape): string | undefined {
+  const returns = shape.returns ? `Gives back ${shape.returns}.` : undefined;
+  return [shape.doc, returns].filter(Boolean).join(" ") || undefined;
+}

package/src/signature/shape-at.ts

@@ -0,0 +1,35 @@
+import type { AstNode } from "@venn-lang/core";
+import type { LangiumDocument } from "langium";
+import type { SymbolCatalog } from "../catalog/index.js";
+import { findBinding } from "../document/index.js";
+import type { TypeService } from "../types/index.js";
+import { callShape } from "./call-shape.js";
+import type { CallShape } from "./call-shape.types.js";
+import { declaredShape } from "./declared-shape.js";
+
+export interface ShapeAtArgs {
+  /** The dotted name being called. */
+  path: string;
+  /** A node in the calling scope, for looking that name up. */
+  host: AstNode | undefined;
+  document: LangiumDocument;
+  catalog: SymbolCatalog;
+  types: TypeService;
+}
+
+/**
+ * What the callee of `f(…)` takes.
+ *
+ * One resolver for every kind of callee, so a call reads the same whoever wrote
+ * it. A name the file bound wins (a `fn`, a `fragment`, a `const` holding a
+ * lambda); otherwise the prelude and the loaded plugins answer. That a local
+ * name beats a namespace is the rule the evaluator follows too.
+ */
+export function shapeAt(args: ShapeAtArgs): CallShape | undefined {
+  const head = args.path.split(".")[0];
+  if (!head) return undefined;
+  const binding = args.host && findBinding(args.host, head);
+  if (!binding) return callShape(args.path, args.catalog);
+  if (args.path !== head) return undefined;
+  return declaredShape({ binding, name: head, document: args.document, types: args.types });
+}

package/src/signature/signature-help.ts

@@ -0,0 +1,98 @@
+import type { LangiumDocument } from "langium";
+import type { SignatureHelpProvider } from "langium/lsp";
+import type {
+  SignatureHelp,
+  SignatureHelpOptions,
+  SignatureHelpParams,
+} from "vscode-languageserver";
+import type { SymbolCatalog } from "../catalog/index.js";
+import type { VennServices } from "../services/lsp.types.js";
+import type { TypeService } from "../types/index.js";
+import { activeArg, enclosingMatcher } from "./action-call.js";
+import { enclosingBareCall } from "./bare-call.js";
+import { callShape, matcherShape } from "./call-shape.js";
+import type { CallShape } from "./call-shape.types.js";
+import { enclosingParenCall } from "./paren-call.js";
+import { bracketed, signatureOfShape } from "./render-shape.js";
+import { shapeAt } from "./shape-at.js";
+
+/**
+ * What the call being typed takes, one argument at a time.
+ *
+ * The space is a trigger character because Venn's calls have no brackets to
+ * hang one off: `http.on ` is already a call with an argument due. Waiting for
+ * a `(` that never comes is how a language ends up unable to explain itself.
+ */
+export class VennSignatureHelpProvider implements SignatureHelpProvider {
+  private readonly catalog: SymbolCatalog;
+  private readonly types: TypeService;
+
+  constructor(services: VennServices) {
+    this.catalog = services.catalog;
+    this.types = services.types;
+  }
+
+  get signatureHelpOptions(): SignatureHelpOptions {
+    return { triggerCharacters: ["(", ",", " "], retriggerCharacters: [" ", ","] };
+  }
+
+  provideSignatureHelp(
+    document: LangiumDocument,
+    params: SignatureHelpParams,
+  ): SignatureHelp | undefined {
+    const offset = document.textDocument.offsetAt(params.position);
+    return (
+      this.forParens(document, offset) ??
+      this.forMatcher(document, offset) ??
+      this.forAction(document, offset)
+    );
+  }
+
+  /** `saudacao(▮)`: a call with brackets, wherever its callee was declared. */
+  private forParens(document: LangiumDocument, offset: number): SignatureHelp | undefined {
+    const found = enclosingParenCall(document, offset);
+    if (!found) return undefined;
+    const shape = shapeAt({ ...found, document, catalog: this.catalog, types: this.types });
+    if (!shape || parts(shape) === 0) return undefined;
+    return help(bracketed(shape), found.active, parts(shape));
+  }
+
+  /** `expect res contains ▮`: the value the check is waiting for. */
+  private forMatcher(document: LangiumDocument, offset: number): SignatureHelp | undefined {
+    const clause = enclosingMatcher(document, offset);
+    if (!clause) return undefined;
+    const shape = matcherShape(clause.name, this.catalog);
+    if (!shape || parts(shape) === 0) return undefined;
+    return help(signatureOfShape(shape), activeArg(clause, offset), parts(shape));
+  }
+
+  /** `http.on api handler`: a verb and its bare arguments, bound or not. */
+  private forAction(document: LangiumDocument, offset: number): SignatureHelp | undefined {
+    const call = enclosingBareCall(document, offset);
+    if (!call) return undefined;
+    const shape = callShape(call.target, this.catalog);
+    if (!shape || parts(shape) === 0) return undefined;
+    return help(signatureOfShape(shape), activeArg(call, offset), parts(shape));
+  }
+}
+
+/**
+ * How many things the signature can point at: the positional arguments, plus
+ * the options map when there is one. The map is the last argument, not
+ * decoration.
+ */
+function parts(shape: CallShape): number {
+  return shape.args.length + (shape.options.length > 0 ? 1 : 0);
+}
+
+function help(
+  signature: SignatureHelp["signatures"][number],
+  active: number,
+  count: number,
+): SignatureHelp {
+  return {
+    signatures: [signature],
+    activeSignature: 0,
+    activeParameter: Math.min(active, Math.max(count - 1, 0)),
+  };
+}

package/src/symbols/document-symbols.ts

@@ -0,0 +1,68 @@
+import {
+  type AstNode,
+  type Block,
+  type Document,
+  isDecoDecl,
+  isFlowDecl,
+  isFragmentDecl,
+  isGroupDecl,
+  isStepDecl,
+} from "@venn-lang/core";
+import type { LangiumDocument } from "langium";
+import type { DocumentSymbolProvider } from "langium/lsp";
+import { type DocumentSymbol, SymbolKind } from "vscode-languageserver";
+
+const ORIGIN = { start: { line: 0, character: 0 }, end: { line: 0, character: 0 } };
+
+/** The outline: flows with their steps and groups, plus fragments and resources. */
+export class VennDocumentSymbolProvider implements DocumentSymbolProvider {
+  getSymbols(document: LangiumDocument): DocumentSymbol[] {
+    const root = document.parseResult?.value as Document | undefined;
+    return root ? root.decls.flatMap(topSymbol) : [];
+  }
+}
+
+function topSymbol(decl: AstNode): DocumentSymbol[] {
+  if (isFlowDecl(decl)) {
+    const children = blockSymbols(decl.body);
+    return [symbol({ node: decl, name: decl.title, kind: SymbolKind.Event, children })];
+  }
+  if (isFragmentDecl(decl)) {
+    return [symbol({ node: decl, name: decl.name, kind: SymbolKind.Function })];
+  }
+  // A `deco` is a declaration a reader looks for by name, like a fragment.
+  if (isDecoDecl(decl)) {
+    return [symbol({ node: decl, name: decl.name, kind: SymbolKind.Function })];
+  }
+  return [];
+}
+
+function blockSymbols(block: Block): DocumentSymbol[] {
+  return block.stmts.flatMap((stmt) => {
+    if (isStepDecl(stmt)) {
+      const children = blockSymbols(stmt.body);
+      return [symbol({ node: stmt, name: stmt.title, kind: SymbolKind.Method, children })];
+    }
+    if (isGroupDecl(stmt)) {
+      const children = blockSymbols(stmt.body);
+      return [symbol({ node: stmt, name: stmt.title, kind: SymbolKind.Namespace, children })];
+    }
+    return [];
+  });
+}
+
+function symbol(args: {
+  node: AstNode;
+  name: string;
+  kind: SymbolKind;
+  children?: DocumentSymbol[];
+}): DocumentSymbol {
+  const range = args.node.$cstNode?.range ?? ORIGIN;
+  return {
+    name: args.name,
+    kind: args.kind,
+    range,
+    selectionRange: range,
+    children: args.children,
+  };
+}

package/src/symbols/index.ts

@@ -0,0 +1 @@
+export { VennDocumentSymbolProvider } from "./document-symbols.js";

package/src/testing/fixtures/alias-import.vn

@@ -0,0 +1,16 @@
+# Imports through a `#alias` path declared in [paths] of venn.toml.
+module fixtures.aliasimport
+
+use "venn/assert"
+use "venn/http"
+
+import { authHeader, login } from "#shared/auth.vn"
+
+flow "Alias import" {
+  run login("alice")
+  step "after login" {
+    expect authHeader("abc123") == "Bearer abc123"
+    http.get "https://example.com/dashboard"
+    expect true
+  }
+}

package/src/testing/fixtures/shared/auth.vn

@@ -0,0 +1,33 @@
+module fixtures.shared.auth
+
+use "venn/http"
+use "venn/assert"
+
+## Signs a user in through the API and asserts the session is live.
+##
+## Put it at the top of any flow that needs an authenticated account. The
+## response stays available to the caller as `res`.
+##
+## @param user  The account name to sign in as.
+## @returns The HTTP response of the sign-in call.
+## @example
+## run login("alice")
+## expect res.status == 200
+pub fragment login(user) {
+  step "login" {
+    let res = http.get "https://example.com"
+    expect res.status == 200
+  }
+}
+
+## Builds the Authorization header a signed-in request carries.
+##
+## A `pub fn` crosses files the same way a fragment does: it is a value, so it
+## can be called, passed and held, and it runs inside *this* file, where
+## `SCHEME` below is private and never leaves.
+##
+## @param token  The session token to send.
+## @returns The header value, scheme included.
+pub fn authHeader(token: string) -> string => "${SCHEME} ${token}"
+
+const SCHEME = "Bearer"

package/src/testing/fixtures/venn.toml

@@ -0,0 +1,8 @@
+# The manifest these fixtures resolve against. `#shared` is what the alias
+# tests follow, so it has to be declared here rather than inherited.
+[package]
+name = "lsp-fixtures"
+version = "0.0.0"
+
+[paths]
+"#shared" = "./shared"

package/src/testing/lsp-fixture.ts

@@ -0,0 +1,77 @@
+import { readFileSync } from "node:fs";
+import { EmptyFileSystem, type LangiumDocument, URI } from "langium";
+import type { LangiumSharedServices } from "langium/lsp";
+import { NodeFileSystem } from "langium/node";
+import type { Position, TextEdit } from "vscode-languageserver";
+import { createVennLspServices } from "../services/index.js";
+import type { VennServices } from "../services/lsp.types.js";
+
+/** A built language service plus one parsed, validated in-memory document. */
+export interface Fixture {
+  services: VennServices;
+  document: LangiumDocument;
+  uri: string;
+}
+
+// Three slashes: the path must carry the `.vn` extension for the service registry.
+const FOLDER = "memory:///";
+const NAME = "test.vn";
+
+/**
+ * Build the services and a validated document: the seam every LSP test drives.
+ *
+ * `modules` are files placed beside it, keyed by file name, so an `import …
+ * from "./lib.vn"` resolves without a disk anywhere in sight.
+ */
+export async function fixture(
+  source: string,
+  modules: Record<string, string> = {},
+): Promise<Fixture> {
+  const { shared, Venn } = createVennLspServices(EmptyFileSystem);
+  const beside = Object.entries(modules).map(([name, text]) => added(shared, name, text));
+  const document = added(shared, NAME, source);
+  await shared.workspace.DocumentBuilder.build([...beside, document], { validation: true });
+  // The document's own string form: vscode-uri normalises, so never re-derive it.
+  return { services: Venn, document, uri: document.uri.toString() };
+}
+
+function added(shared: LangiumSharedServices, name: string, source: string): LangiumDocument {
+  const uri = URI.parse(`${FOLDER}${name}`);
+  const document = shared.workspace.LangiumDocumentFactory.fromString(source, uri);
+  shared.workspace.LangiumDocuments.addDocument(document);
+  return document;
+}
+
+/**
+ * Same, but for a real file on disk, on the node filesystem, so `venn.toml`,
+ * `#alias` paths and imported documents all resolve the way they do in an editor.
+ */
+export async function fixtureFromFile(path: string): Promise<Fixture> {
+  const { shared, Venn } = createVennLspServices(NodeFileSystem);
+  const uri = URI.file(path);
+  const source = readFileSync(path, "utf8");
+  const document = shared.workspace.LangiumDocumentFactory.fromString(source, uri);
+  shared.workspace.LangiumDocuments.addDocument(document);
+  await shared.workspace.DocumentBuilder.build([document], { validation: false });
+  return { services: Venn, document, uri: document.uri.toString() };
+}
+
+/** Apply edits to the document's text, last-to-first so earlier offsets stay valid. */
+export function applyEdits(document: LangiumDocument, edits: readonly TextEdit[]): string {
+  const text = document.textDocument;
+  const offset = (edit: TextEdit): number => text.offsetAt(edit.range.start);
+  const sorted = [...edits].sort((a, b) => offset(b) - offset(a));
+  let out = text.getText();
+  for (const edit of sorted) {
+    out = out.slice(0, offset(edit)) + edit.newText + out.slice(text.offsetAt(edit.range.end));
+  }
+  return out;
+}
+
+/**
+ * The position where `needle` starts, which is inside its first token, even for
+ * one-character names like `x`.
+ */
+export function positionOf(document: LangiumDocument, needle: string): Position {
+  return document.textDocument.positionAt(document.textDocument.getText().indexOf(needle));
+}

package/src/types/index.ts

@@ -0,0 +1,3 @@
+export type { DocumentTypes, TypeService } from "./type-service.js";
+export { createTypeService } from "./type-service.js";
+export { warmTypes } from "./warm-types.js";

package/src/types/type-service.ts

@@ -0,0 +1,144 @@
+import {
+  type AstNode,
+  checkTypes,
+  type Document,
+  type Expr,
+  type ImportedDeco,
+  importedTypes,
+  isPackageSpecifier,
+  isValueImport,
+  type Problem,
+  type Type,
+  type TypeCatalog,
+} from "@venn-lang/core";
+import { createTypeCatalog } from "@venn-lang/runtime";
+import { allPlugins } from "@venn-lang/stdlib";
+import type { TypeSpec } from "@venn-lang/types";
+import type { LangiumDocument } from "langium";
+import { importedDecos } from "../deco/index.js";
+import { importedModules, type ModuleGraph } from "../document/index.js";
+import type { VennServices } from "../services/lsp.types.js";
+
+/** What inference found for one document: its type errors and every node's type. */
+export interface DocumentTypes {
+  problems: readonly Problem[];
+  types: ReadonlyMap<AstNode, Type>;
+  /**
+   * Per string literal, the expression inference parsed from each `${…}`. The
+   * document's own tree stops at the string, so these are the only nodes the
+   * editor can reach for code written inside one.
+   */
+  slots: ReadonlyMap<AstNode, readonly (Expr | undefined)[]>;
+}
+
+/**
+ * Type information for the workspace, computed once per parse of a document.
+ *
+ * Inference walks a whole file, and several features want its result:
+ * diagnostics on every edit, hover on every mouse move. Without a shared cache
+ * the same file is re-checked many times per keystroke; with it, a file is
+ * checked once when it changes and every reader is served from memory.
+ */
+export interface TypeService {
+  /** Everything inference knows about this document, cached until it is reparsed. */
+  of(document: LangiumDocument): DocumentTypes;
+  /** What is already cached, or undefined, for readers that must not block. */
+  peek(document: LangiumDocument): DocumentTypes | undefined;
+  /** Forget a document: it was deleted, or its folder was closed. */
+  forget(uri: string): void;
+}
+
+const EMPTY: DocumentTypes = { problems: [], types: new Map(), slots: new Map() };
+
+interface Entry {
+  /** The AST this was computed from. A reparse yields a new root, so a stale
+   * entry can never be mistaken for a fresh one. A version number could be,
+   * since replacing a document resets it to zero. */
+  root: object;
+  result: DocumentTypes;
+}
+
+export function createTypeService(services: VennServices): TypeService {
+  const cache = new Map<string, Entry>();
+  // Built once: reading every plugin's published types on each keystroke would
+  // be work the answer never changes for.
+  const catalog = createTypeCatalog(allPlugins);
+  return {
+    of(document) {
+      const cached = hit(cache, document);
+      if (cached) return cached;
+      const root = document.parseResult?.value;
+      const result = compute({ document, catalog, ...outside(document, services) });
+      if (root) cache.set(document.uri.toString(), { root, result });
+      return result;
+    },
+    peek: (document) => hit(cache, document),
+    forget: (uri) => void cache.delete(uri),
+  };
+}
+
+/**
+ * The `pub deco`s this file imports.
+ *
+ * Read here rather than in {@link compute} because the services are resolved
+ * lazily: touching them while the module is still being built would close a
+ * loop that only opens once everything is constructed.
+ */
+function outside(
+  document: LangiumDocument,
+  services: VennServices,
+): {
+  decos?: Map<string, ImportedDeco>;
+  graph?: ModuleGraph;
+  packages?: Map<string, Record<string, TypeSpec>>;
+} {
+  const root = document.parseResult?.value as Document | undefined;
+  if (!root) return {};
+  const scope = {
+    root,
+    uri: document.uri,
+    documents: services.shared.workspace.LangiumDocuments,
+    imports: services.imports,
+  };
+  return {
+    decos: importedDecos(scope),
+    graph: importedModules(scope),
+    packages: services.imports.packageTypes(document.uri, packagesNamed(root)),
+  };
+}
+
+/** The bare specifiers this file imports: the ones that name a package. */
+function packagesNamed(root: Document): string[] {
+  return root.imports
+    .filter(isValueImport)
+    .map((decl) => decl.path)
+    .filter(isPackageSpecifier);
+}
+
+function hit(cache: Map<string, Entry>, document: LangiumDocument): DocumentTypes | undefined {
+  const entry = cache.get(document.uri.toString());
+  return entry && entry.root === document.parseResult?.value ? entry.result : undefined;
+}
+
+function compute(args: {
+  document: LangiumDocument;
+  catalog: TypeCatalog;
+  decos?: Map<string, ImportedDeco>;
+  graph?: ModuleGraph;
+  packages?: Map<string, Record<string, TypeSpec>>;
+}): DocumentTypes {
+  const { document, catalog, decos, graph } = args;
+  const root = document.parseResult?.value as Document | undefined;
+  if (!root) return EMPTY;
+  const uri = document.uri.toString();
+  // What the imported names are, worked out from the files they were written
+  // in, so an imported function has a hover and its arguments are checked.
+  const imports =
+    graph && importedTypes({ ...graph, document: root, uri, catalog, packages: args.packages });
+  const checked = checkTypes(root, { uri, catalog, decos, imports });
+  return {
+    problems: checked.problems,
+    types: checked.types as ReadonlyMap<AstNode, Type>,
+    slots: checked.slots as ReadonlyMap<AstNode, readonly (Expr | undefined)[]>,
+  };
+}

package/src/types/warm-types.ts

@@ -0,0 +1,30 @@
+import { DocumentState, type LangiumDocument, type URI } from "langium";
+import type { LangiumSharedServices } from "langium/lsp";
+import type { TypeService } from "./type-service.js";
+
+/**
+ * Keep the workspace's types warm.
+ *
+ * Langium already indexes every `.vn` in the opened folder, and re-indexes a
+ * file when it changes. Hooking the same cycle means the project is fully typed
+ * by the time you touch anything, and a keystroke re-types only the file you
+ * edited, never the rest.
+ */
+export function warmTypes(shared: LangiumSharedServices, types: TypeService): void {
+  const builder = shared.workspace.DocumentBuilder;
+  builder.onBuildPhase(DocumentState.IndexedContent, (documents: LangiumDocument[]) => {
+    for (const document of documents) warm(document, types);
+  });
+  builder.onUpdate((_changed: URI[], deleted: URI[]) => {
+    for (const uri of deleted) types.forget(uri.toString());
+  });
+}
+
+/** Inference must never take the server down: a bad file loses its types, nothing more. */
+function warm(document: LangiumDocument, types: TypeService): void {
+  try {
+    types.of(document);
+  } catch {
+    types.forget(document.uri.toString());
+  }
+}