@venn-lang/lsp 0.1.0

package/src/completion/items.ts

@@ -0,0 +1,232 @@
+import { type Document, isFragmentDecl, showType, specToType } from "@venn-lang/core";
+import { type ActionDefinition, paramSpecs } from "@venn-lang/sdk";
+import { showSpec } from "@venn-lang/types";
+import { type CompletionItem, CompletionItemKind, type Range } from "vscode-languageserver";
+import type { SymbolCatalog } from "../catalog/index.js";
+import { type DecoInfo, decoratesLabel } from "../deco/index.js";
+import type { ExportedName } from "../document/index.js";
+import type { EnvVar } from "../env/index.js";
+import { ICON, iconForOrigin } from "./icons.js";
+
+const KEYWORDS = [
+  "step",
+  "group",
+  "if",
+  "else",
+  "forEach",
+  "repeat",
+  "while",
+  "parallel",
+  "race",
+  "try",
+  "catch",
+  "finally",
+  "expect",
+  "run",
+  "let",
+  "const",
+  "return",
+  "break",
+  "continue",
+  "defer",
+  "setup",
+  "teardown",
+  "beforeEach",
+  "afterEach",
+];
+// Callable without a `use`: verbs that act, plus the values with no receiver.
+const PRELUDE = [
+  "print",
+  "log",
+  "wait",
+  "skip",
+  "fail",
+  "exit",
+  "range",
+  "str",
+  "typeOf",
+  "pretty",
+];
+
+/**
+ * Every item carries an explicit `textEdit` over `range`. VS Code's default word
+ * rules stop at `@` and `/`, so without it accepting `@venn-lang/http` inside
+ * `"@venn-lang/"` would paste the prefix twice.
+ */
+export function item(args: {
+  label: string;
+  kind: CompletionItemKind;
+  range: Range;
+  detail?: string;
+  documentation?: string;
+  /** What to write, when it differs from the label: `body` inserts `body: `. */
+  insert?: string;
+}): CompletionItem {
+  return {
+    label: args.label,
+    kind: args.kind,
+    detail: args.detail,
+    documentation: args.documentation,
+    filterText: args.label,
+    textEdit: { range: args.range, newText: args.insert ?? args.label },
+  };
+}
+
+/**
+ * The keys of an action's options map, read from its params schema. That is the
+ * schema the runtime validates against, so the editor cannot drift from it.
+ */
+export function optionItems(args: {
+  target: string;
+  catalog: SymbolCatalog;
+  range: Range;
+}): CompletionItem[] {
+  const dot = args.target.indexOf(".");
+  if (dot < 0) return [];
+  const entry = args.catalog.action(args.target.slice(0, dot), args.target.slice(dot + 1));
+  return paramSpecs(entry?.action.params).map((spec) =>
+    item({
+      label: spec.name,
+      kind: ICON.key,
+      range: args.range,
+      detail: spec.required ? `${spec.type} (required)` : spec.type,
+      documentation: spec.doc,
+      insert: `${spec.name}: `,
+    }),
+  );
+}
+
+/** `env.`: the variables `venn.toml` declares, secrets shown without values. */
+export function envItems(vars: readonly EnvVar[], range: Range): CompletionItem[] {
+  return vars.map((variable) =>
+    item({
+      label: variable.name,
+      kind: ICON.env,
+      range,
+      detail: variable.secret ? "secret" : variable.values[0]?.value,
+      documentation:
+        variable.doc ??
+        `Declared in venn.toml for ${variable.values.map((v) => v.environment).join(", ")}.`,
+    }),
+  );
+}
+
+export function packageItems(catalog: SymbolCatalog, range: Range): CompletionItem[] {
+  return catalog.packages().map((label) => {
+    const namespace = catalog.namespaceOfPackage(label);
+    return item({ label, kind: ICON.namespace, range, detail: namespace });
+  });
+}
+
+/**
+ * The types a namespace publishes: `http.Request`, `http.Server`.
+ *
+ * They stand beside the verbs because that is where they are written. A
+ * namespace answering only with verbs leaves the author guessing what those
+ * verbs deal in.
+ */
+export function typeItems(
+  namespace: string,
+  catalog: SymbolCatalog,
+  range: Range,
+): CompletionItem[] {
+  return catalog.typesIn(namespace).map((entry) =>
+    item({
+      label: entry.name,
+      kind: ICON.type,
+      range,
+      detail: showType(specToType(entry.spec, () => undefined)),
+      documentation: `Type published by ${entry.package}.`,
+    }),
+  );
+}
+
+export function actionItems(
+  namespace: string,
+  catalog: SymbolCatalog,
+  range: Range,
+): CompletionItem[] {
+  return catalog.actionsIn(namespace).map((entry) =>
+    item({
+      label: entry.name,
+      kind: ICON.verb,
+      range,
+      detail: returnOf(entry.action) ?? entry.package,
+      documentation: entry.action.doc,
+    }),
+  );
+}
+
+/** What the verb answers with, taken from its declared type, never from prose. */
+function returnOf(action: ActionDefinition): string | undefined {
+  const result = action.signature?.result;
+  if (!result || (result.kind === "prim" && result.name === "void")) return undefined;
+  return `-> ${showSpec(result)}`;
+}
+
+export function matcherItems(catalog: SymbolCatalog, range: Range): CompletionItem[] {
+  return catalog
+    .matchers()
+    .map((entry) => item({ label: entry.name, kind: ICON.matcher, range, detail: entry.package }));
+}
+
+/**
+ * After `@`: every decorator in scope, each saying what it decorates.
+ *
+ * What it decorates is the detail, not an afterthought: applying one to the
+ * wrong kind is the mistake this list exists to prevent.
+ */
+export function annotationItems(decos: readonly DecoInfo[], range: Range): CompletionItem[] {
+  return decos.map((deco) =>
+    item({
+      label: deco.name,
+      kind: ICON.decorator,
+      range,
+      detail: decoratesLabel(deco.decorates),
+      documentation: deco.doc,
+    }),
+  );
+}
+
+export function fragmentItems(args: {
+  document: Document | undefined;
+  /** The imported names that really are fragments, from the files they came from. */
+  imported: ReadonlySet<string>;
+  range: Range;
+}): CompletionItem[] {
+  if (!args.document) return [];
+  const local = args.document.decls.filter(isFragmentDecl).map((decl) => decl.name);
+  return simple([...local, ...args.imported], ICON.fragment, args.range);
+}
+
+export function pathItems(paths: readonly string[], range: Range): CompletionItem[] {
+  return simple(paths, CompletionItemKind.File, range);
+}
+
+export function exportItems(names: readonly ExportedName[], range: Range): CompletionItem[] {
+  return names.map((each) =>
+    item({
+      label: each.name,
+      kind: iconForOrigin(each.origin),
+      range,
+      detail: `pub ${each.origin}`,
+    }),
+  );
+}
+
+/** At the start of a statement: namespaces, prelude verbs and structural keywords. */
+export function openingItems(catalog: SymbolCatalog, range: Range): CompletionItem[] {
+  return [
+    ...simple(catalog.namespaces(), CompletionItemKind.Module, range),
+    ...simple(PRELUDE, CompletionItemKind.Function, range),
+    ...simple(KEYWORDS, CompletionItemKind.Keyword, range),
+  ];
+}
+
+function simple(
+  labels: readonly string[],
+  kind: CompletionItemKind,
+  range: Range,
+): CompletionItem[] {
+  return labels.map((label) => item({ label, kind, range }));
+}

package/src/completion/member-items.ts

@@ -0,0 +1,147 @@
+import {
+  type AstNode,
+  createContext,
+  MEMBER_DOCS,
+  memberKind,
+  memberType,
+  type OpaqueType,
+  prune,
+  resolveMember,
+  showType,
+  type Type,
+} from "@venn-lang/core";
+import type { LangiumDocument } from "langium";
+import type { CompletionItem, CompletionItemKind, Range } from "vscode-languageserver";
+import { findBinding } from "../document/index.js";
+import type { TypeService } from "../types/index.js";
+import { ICON } from "./icons.js";
+import { item } from "./items.js";
+import { receiverTypeAt } from "./read-from.js";
+
+export interface MemberArgs {
+  /** The dotted path before the cursor's dot: `p`, `cfg.server`. */
+  receiver: string;
+  /** A node inside the file, for looking the head up in scope. */
+  host: AstNode;
+  document: LangiumDocument;
+  types: TypeService;
+  range: Range;
+}
+
+/**
+ * What a value offers after a dot: the built-ins of its type, plus the fields it
+ * carries when it is a map. Driven by the same inference the checker runs, so
+ * `p` inside `people.filter(fn (p) => …)` completes as a person, not as nothing.
+ */
+export function memberItems(args: MemberArgs): CompletionItem[] {
+  const type = receiverType(args);
+  if (!type) return [];
+  return [...fieldItems(type, args.range), ...builtinItems(type, args.range)];
+}
+
+/** Walk the path from the binding the file declared to the type it holds here. */
+function receiverType(args: MemberArgs): Type | undefined {
+  const segments = args.receiver.split(".");
+  const head = segments[0];
+  const binding = head ? findBinding(args.host, head) : undefined;
+  let type = binding && args.types.of(args.document).types.get(binding);
+  for (const name of segments.slice(1)) {
+    if (!type) return undefined;
+    type = resolveMember(type, name, createContext());
+  }
+  return type && prune(type);
+}
+
+/**
+ * How the editor orders what comes after a dot.
+ *
+ * What the value is comes before what every value of its kind can do: someone
+ * who typed `price.` wants `id` and `price`, not the dozens of built-ins that
+ * are the same on every map in the language.
+ */
+const OWN = "0";
+const BUILT_IN = "1";
+
+function fieldItems(type: Type, range: Range): CompletionItem[] {
+  if (type.kind === "opaque") return publishedItems(type, range);
+  if (type.kind !== "record") return [];
+  return [...type.fields].map(([name, field]) => ({
+    ...item({
+      label: name,
+      kind: kindOf(field, true),
+      range,
+      detail: showType(field),
+      documentation: "Field of this map.",
+    }),
+    sortText: `${OWN}${name}`,
+  }));
+}
+
+/**
+ * Which of three things this member is.
+ *
+ * The icon answers the question the reader is about to act on: do I write
+ * brackets? A method needs `(…)`; everything else is written bare. Of the bare
+ * ones, a field is data the value carries and a property is computed on read.
+ */
+function kindOf(member: Type, stored: boolean): CompletionItemKind {
+  if (member.kind === "fn") return ICON.method;
+  return stored ? ICON.key : ICON.computed;
+}
+
+/**
+ * What a handle publishes, and only that. A server is not a map: it answers to
+ * `close`, never to `merge`, so offering `merge` would invite code that cannot
+ * work.
+ */
+function publishedItems(type: OpaqueType, range: Range): CompletionItem[] {
+  return [...(type.members ?? [])].map(([name, member]) => ({
+    ...item({
+      label: name,
+      kind: kindOf(member, false),
+      range,
+      detail: showType(member),
+      documentation: `Published by \`${type.name}\`.`,
+    }),
+    sortText: `${OWN}${name}`,
+  }));
+}
+
+function builtinItems(type: Type, range: Range): CompletionItem[] {
+  const kind = memberKind(type);
+  const docs = kind ? MEMBER_DOCS[kind] : undefined;
+  if (!kind || !docs) return [];
+  return Object.entries(docs).map(([name, doc]) => {
+    const member = memberType(type, name, createContext());
+    return {
+      ...item({
+        label: name,
+        kind: member ? kindOf(member, false) : ICON.method,
+        range,
+        detail: member ? showType(member) : undefined,
+        documentation: doc.example ? `${doc.doc}\n\n${doc.example}` : doc.doc,
+      }),
+      sortText: `${BUILT_IN}${name}`,
+    };
+  });
+}
+
+/**
+ * The members of whatever the node under the cursor evaluates to.
+ *
+ * For a receiver no path can name (`(1234.567).`, `f(x).`, `xs[0].`) there is
+ * nothing to look up by text, but the checker already typed the expression.
+ */
+export function membersOfNode(args: {
+  host: AstNode;
+  /** Where the cursor is: what tells a finished member from one being typed. */
+  at: number;
+  document: LangiumDocument;
+  types: TypeService;
+  range: Range;
+}): CompletionItem[] {
+  const types = args.types.of(args.document).types;
+  const type = receiverTypeAt({ host: args.host, at: args.at, document: args.document, types });
+  if (!type) return [];
+  return [...fieldItems(type, args.range), ...builtinItems(type, args.range)];
+}

package/src/completion/module-paths.ts

@@ -0,0 +1,63 @@
+import { type Dirent, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { type URI, UriUtils } from "langium";
+import type { ImportResolver } from "../workspace/index.js";
+
+const EXTENSION = ".vn";
+const MAX_DEPTH = 3;
+const SKIP = new Set(["node_modules", "dist", ".git"]);
+
+export interface PathArgs {
+  partial: string;
+  base: URI;
+  imports: ImportResolver;
+}
+
+/**
+ * What may follow `from "`: a `#alias/…` path from `venn.toml`, or a relative
+ * path to a sibling `.vn` file. The `#` only marks an alias; plain relative
+ * paths need no prefix.
+ *
+ * @returns Path strings ready to insert, without the surrounding quotes.
+ */
+export function modulePaths(args: PathArgs): string[] {
+  return args.partial.startsWith("#") ? aliasPaths(args) : relativePaths(args.base);
+}
+
+function aliasPaths(args: PathArgs): string[] {
+  const aliases = Object.entries(args.imports.aliases(args.base));
+  const matched = aliases.find(([key]) => args.partial.startsWith(`${key}/`));
+  if (!matched) return aliases.map(([key]) => `${key}/`);
+  const [key, folder] = matched;
+  return sourceFiles(folder).map((file) => `${key}/${file}`);
+}
+
+function relativePaths(base: URI): string[] {
+  const self = UriUtils.basename(base);
+  return sourceFiles(UriUtils.dirname(base))
+    .filter((file) => file !== self)
+    .map((file) => `./${file}`);
+}
+
+function sourceFiles(folder: URI): string[] {
+  return walk(folder.fsPath, "", 0);
+}
+
+function walk(root: string, relative: string, depth: number): string[] {
+  if (depth > MAX_DEPTH) return [];
+  const found: string[] = [];
+  for (const entry of read(join(root, relative))) {
+    const child = relative ? `${relative}/${entry.name}` : entry.name;
+    if (entry.isDirectory() && !SKIP.has(entry.name)) found.push(...walk(root, child, depth + 1));
+    else if (entry.isFile() && entry.name.endsWith(EXTENSION)) found.push(child);
+  }
+  return found;
+}
+
+function read(directory: string): Dirent[] {
+  try {
+    return readdirSync(directory, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+}

package/src/completion/options-map-items.ts

@@ -0,0 +1,47 @@
+import type { ParamSpec } from "@venn-lang/sdk";
+import type { Range } from "vscode-languageserver";
+import { type CompletionItem, InsertTextFormat } from "vscode-languageserver";
+import { ICON } from "./icons.js";
+
+/**
+ * Where a verb's options are due: offer the map itself, then its keys.
+ *
+ * At `http.get("u", ▮)` the braces have to exist before anything can go inside
+ * them, so the map comes first and the keys after. Accepting either writes
+ * `{ headers: … }` in a single step.
+ */
+export function optionsMapItems(options: readonly ParamSpec[], range: Range): CompletionItem[] {
+  return [wholeMap(options, range), ...options.map((spec) => keyItem(spec, range))];
+}
+
+/** `{ … }`: the options map, with the required keys already in place. */
+function wholeMap(options: readonly ParamSpec[], range: Range): CompletionItem {
+  const required = options.filter((spec) => spec.required);
+  const inner = (required.length > 0 ? required : options.slice(0, 1))
+    .map((spec, index) => `${spec.name}: \${${index + 1}:${spec.type}}`)
+    .join(", ");
+  return {
+    label: "{ … }",
+    kind: ICON.key,
+    detail: `options of this call — ${options.map((spec) => spec.name).join(", ")}`,
+    insertText: `{ ${inner} }`,
+    insertTextFormat: InsertTextFormat.Snippet,
+    textEdit: { range, newText: `{ ${inner} }` },
+    sortText: "0",
+  };
+}
+
+/** One key, written into a fresh map so it lands somewhere valid. */
+function keyItem(spec: ParamSpec, range: Range): CompletionItem {
+  const text = `{ ${spec.name}: $1 }`;
+  return {
+    label: spec.name,
+    kind: ICON.key,
+    detail: spec.required ? `${spec.type} (required)` : spec.type,
+    documentation: spec.doc,
+    insertText: text,
+    insertTextFormat: InsertTextFormat.Snippet,
+    textEdit: { range, newText: text },
+    sortText: `1${spec.name}`,
+  };
+}

package/src/completion/read-from.ts

@@ -0,0 +1,77 @@
+import { type AstNode, isMember, prune, type Type } from "@venn-lang/core";
+import { type CstNode, CstUtils, type LangiumDocument } from "langium";
+
+export interface ReadFromArgs {
+  /** The node the cursor's dot was found against. */
+  host: AstNode;
+  /** Where the cursor is: what tells a finished member from one being typed. */
+  at: number;
+  document: LangiumDocument;
+  types: ReadonlyMap<object, Type>;
+}
+
+/**
+ * The type on the left of a dot: what the members after it belong to.
+ *
+ * Three shapes sit here that look alike and are not: a member still being
+ * typed, a member already written, and a bracket that only groups. Each is read
+ * differently, which is why a plain `a.b.c.` is not the whole problem.
+ */
+export function receiverTypeAt(args: ReadFromArgs): Type | undefined {
+  const node = holderOf(args.host, args.at);
+  const found = args.types.get(node) ?? groupType(args);
+  return found && prune(found);
+}
+
+/**
+ * A member already written, told apart from one still being typed.
+ *
+ * `xs[0].ma▮` is half a member with no type of its own, so its receiver
+ * answers. `xs[0].entries.▮` is finished and its type is the list it gives
+ * back, so past the member's last character it answers for itself.
+ */
+function holderOf(host: AstNode, at: number): AstNode {
+  if (!isMember(host)) return host;
+  const end = host.$cstNode?.end;
+  return end !== undefined && end < at ? host : host.receiver;
+}
+
+/**
+ * What a grouping `(…)` holds: `(1 + 2).▮` is a number.
+ *
+ * Brackets that only group carry no node of their own, so the `)` belongs to
+ * the enclosing statement and the cursor lands on something untyped. A call or
+ * an index does have a node ending at its bracket, so this runs only when the
+ * direct reading comes up empty.
+ */
+function groupType(args: ReadFromArgs): Type | undefined {
+  const root = args.document.parseResult?.value?.$cstNode;
+  if (!root) return undefined;
+  const closing = before(root, args.at - 1);
+  if (closing?.text !== ")") return undefined;
+  const last = before(root, closing.offset - 1)?.astNode;
+  return last && outermostTyped({ from: last, end: closing.offset, types: args.types });
+}
+
+function before(root: CstNode, at: number): CstNode | undefined {
+  return CstUtils.findLeafNodeAtOffset(root, at) ?? CstUtils.findLeafNodeBeforeOffset(root, at);
+}
+
+/**
+ * The largest expression that still ends inside the brackets: `("a" + "b").`
+ * is the whole sum, not its last word. Only a node the checker gave a type to
+ * counts: the tree also holds an argument list and a call ending in the same
+ * place, and neither is a value anyone can read a member from.
+ */
+function outermostTyped(args: {
+  from: AstNode;
+  end: number;
+  types: ReadonlyMap<object, Type>;
+}): Type | undefined {
+  let found: Type | undefined;
+  for (let node: AstNode | undefined = args.from; node; node = node.$container) {
+    if ((node.$cstNode?.end ?? args.end + 1) > args.end) break;
+    found = args.types.get(node) ?? found;
+  }
+  return found;
+}

package/src/completion/type-name-items.ts

@@ -0,0 +1,62 @@
+import { BUILTIN_TYPES, type Document, isTypeDecl } from "@venn-lang/core";
+import type { CompletionItem, Range } from "vscode-languageserver";
+import type { SymbolCatalog } from "../catalog/index.js";
+import { ICON } from "./icons.js";
+import { item } from "./items.js";
+
+export interface TypeNameArgs {
+  root: Document | undefined;
+  catalog: SymbolCatalog;
+  /** Namespaces this file brought in; a type it cannot name is not offered. */
+  imported: readonly string[];
+  range: Range;
+}
+
+/**
+ * Every type that may be written here: the language's own, the ones this file
+ * declared, and the ones its imports publish, in that order.
+ */
+export function typeNameItems(args: TypeNameArgs): CompletionItem[] {
+  return [...builtins(args.range), ...declared(args), ...published(args)];
+}
+
+function builtins(range: Range): CompletionItem[] {
+  return Object.entries(BUILTIN_TYPES).map(([name, builtin]) => ({
+    ...item({
+      label: name,
+      kind: ICON.builtinType,
+      range,
+      detail: "built in",
+      documentation: builtin.doc,
+    }),
+    sortText: `0${name}`,
+  }));
+}
+
+/** What this file declared with `type`. */
+function declared(args: TypeNameArgs): CompletionItem[] {
+  return (args.root?.decls ?? []).filter(isTypeDecl).map((decl) => ({
+    ...item({
+      label: decl.name,
+      kind: ICON.type,
+      range: args.range,
+      detail: "declared here",
+    }),
+    sortText: `1${decl.name}`,
+  }));
+}
+
+/** What the imported packages publish, written qualified, as they are used. */
+function published(args: TypeNameArgs): CompletionItem[] {
+  return args.imported.flatMap((namespace) =>
+    args.catalog.typesIn(namespace).map((entry) => ({
+      ...item({
+        label: `${entry.namespace}.${entry.name}`,
+        kind: ICON.type,
+        range: args.range,
+        detail: entry.package,
+      }),
+      sortText: `2${entry.namespace}.${entry.name}`,
+    })),
+  );
+}

package/src/deco/builtin-decos.ts

@@ -0,0 +1,35 @@
+import type { DecoratorDefinition } from "@venn-lang/core";
+import { builtinDecorators } from "@venn-lang/runtime";
+import { decoratorDoc } from "./builtin-docs.js";
+import type { DecoInfo } from "./deco.types.js";
+import { kindOf } from "./kind-of.js";
+
+/**
+ * `@doc` is written like a decorator and read like one, but expansion never
+ * sees it: it is where a declaration's documentation lives when no `##` block
+ * does, and the editor is what reads it.
+ */
+const DOC: DecoInfo = {
+  name: "doc",
+  decorates: [],
+  signature: "@doc(text)",
+  doc: decoratorDoc("doc"),
+};
+
+/**
+ * The decorators every file has without asking: the ones the runtime ships.
+ * They are read through the same shape a declared `deco` produces, so the
+ * editor holds one notion of what a decorator is rather than two.
+ */
+export function builtinDecos(): DecoInfo[] {
+  return [...builtinDecorators.map(fromDefinition), DOC];
+}
+
+function fromDefinition(decorator: DecoratorDefinition): DecoInfo {
+  return {
+    name: decorator.name,
+    decorates: (decorator.targets ?? []).map(kindOf),
+    signature: `@${decorator.name}`,
+    doc: decoratorDoc(decorator.name) ?? decorator.doc,
+  };
+}

package/src/deco/builtin-docs.ts

@@ -0,0 +1,26 @@
+/**
+ * What each decorator the language documents is for, per spec §08.
+ *
+ * Longer than the one-line `doc` a `DecoratorDefinition` carries, because a
+ * hover is where someone actually reads it. A name here that no decorator
+ * implements is still documented: the editor can explain `@load` long before
+ * `@venn-lang/load` contributes it.
+ */
+const DOCS: Record<string, string> = {
+  doc: "Documentation shown in the editor and the node tooltip.",
+  timeout: "Abort the flow or step after a duration, e.g. `@timeout(90s)`.",
+  retry: "Re-run on failure with backoff, e.g. `@retry(2, { backoff: 500ms })`.",
+  skip: "Skip this flow or step, optionally conditionally.",
+  only: "Focus: run only the annotated flows.",
+  serial: "Forbid concurrent execution with sibling flows.",
+  lock: 'Named mutex held across workers, e.g. `@lock("orders")`.',
+  scope: "Resource lifetime: `suite`, `worker`, `flow` or `step`.",
+  flaky: "Declared flakiness tolerance, e.g. `@flaky(ratio: 0.05)`.",
+  tags: "Tags matched by the runner's `--tags` filter.",
+  load: "Run the flow as a load test (from `@venn-lang/load`).",
+};
+
+/** The prose for a decorator the language documents, if it documents one. */
+export function decoratorDoc(name: string): string | undefined {
+  return DOCS[name];
+}