@venn-lang/lsp 0.1.0

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@venn-lang/lsp",
+  "version": "0.1.0",
+  "description": "The Venn language server: diagnostics, hover, completion, definition, references, rename, signature help, semantic tokens, formatting, document highlight and quick fixes for .vn files.",
+  "keywords": [
+    "venn",
+    "testing",
+    "e2e",
+    "lsp",
+    "language-server",
+    "editor"
+  ],
+  "homepage": "https://github.com/venn-lang/venn/tree/main/packages/lsp#readme",
+  "bugs": "https://github.com/venn-lang/venn/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/venn-lang/venn.git",
+    "directory": "packages/lsp"
+  },
+  "license": "MIT",
+  "author": "Vinicius Borges",
+  "type": "module",
+  "bin": {
+    "venn-lsp": "./dist/bin/venn-lsp.mjs"
+  },
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.suite.ts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "langium": "^4.3.1",
+    "vscode-languageserver": "^10.0.1",
+    "vscode-languageserver-textdocument": "^1.0.13",
+    "@venn-lang/contracts": "0.1.0",
+    "@venn-lang/core": "0.1.0",
+    "@venn-lang/runtime": "0.1.0",
+    "@venn-lang/sdk": "0.1.0",
+    "@venn-lang/stdlib": "0.1.0",
+    "@venn-lang/types": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24",
+    "tsdown": "^0.22.14",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/bin/venn-lsp.ts

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+import { type Connection, createConnection, ProposedFeatures } from "vscode-languageserver/node";
+import { startVennServer } from "../server/index.js";
+
+const TRANSPORT_FLAGS = ["--stdio", "--node-ipc", "--socket"];
+
+// Editors pass a transport flag; with none given, default to stdio so the server
+// is usable straight from a shell.
+function connect(): Connection {
+  const flagged = process.argv.some((arg) => TRANSPORT_FLAGS.some((flag) => arg.startsWith(flag)));
+  const connection = flagged
+    ? createConnection(ProposedFeatures.all)
+    : createConnection(ProposedFeatures.all, process.stdin, process.stdout);
+  return connection as Connection;
+}
+
+startVennServer(connect());

package/src/catalog/build-catalog.ts

@@ -0,0 +1,72 @@
+import type { PluginDefinition } from "@venn-lang/sdk";
+import type { ActionEntry, MatcherEntry, SymbolCatalog, TypeEntry } from "./catalog.types.js";
+
+interface Index {
+  actions: Map<string, ActionEntry>;
+  matchers: Map<string, MatcherEntry>;
+  byNamespace: Map<string, ActionEntry[]>;
+  typesByNamespace: Map<string, TypeEntry[]>;
+  packages: Map<string, string>;
+}
+
+/**
+ * Index the loaded plugins so completion, hover and tokens can look symbols up.
+ *
+ * @param plugins The plugin definitions loaded for the workspace.
+ * @returns A read-only view over their actions, matchers and published types.
+ */
+export function buildCatalog(plugins: readonly PluginDefinition[]): SymbolCatalog {
+  const index: Index = {
+    actions: new Map(),
+    matchers: new Map(),
+    byNamespace: new Map(),
+    typesByNamespace: new Map(),
+    packages: new Map(),
+  };
+  for (const plugin of plugins) addPlugin(plugin, index);
+  return view(index, plugins);
+}
+
+function view(index: Index, plugins: readonly PluginDefinition[]): SymbolCatalog {
+  return {
+    namespaces: () => [...index.byNamespace.keys()],
+    packages: () => plugins.map((plugin) => plugin.name),
+    hasNamespace: (namespace) => index.byNamespace.has(namespace),
+    actionsIn: (namespace) => index.byNamespace.get(namespace) ?? [],
+    action: (namespace, name) => index.actions.get(`${namespace}.${name}`),
+    typesIn: (namespace) => index.typesByNamespace.get(namespace) ?? [],
+    matchers: () => [...index.matchers.values()],
+    matcher: (name) => index.matchers.get(name),
+    namespaceOfPackage: (pkg) => index.packages.get(pkg),
+    packagesFor: (namespace) =>
+      [...index.packages.entries()]
+        .filter(([, contributed]) => contributed === namespace)
+        .map(([pkg]) => pkg),
+  };
+}
+
+function addPlugin(plugin: PluginDefinition, index: Index): void {
+  index.packages.set(plugin.name, plugin.namespace);
+  const list = index.byNamespace.get(plugin.namespace) ?? [];
+  index.byNamespace.set(plugin.namespace, list);
+  for (const action of plugin.actions ?? []) {
+    const entry = { namespace: plugin.namespace, name: action.name, package: plugin.name, action };
+    index.actions.set(`${plugin.namespace}.${action.name}`, entry);
+    list.push(entry);
+  }
+  for (const matcher of plugin.matchers ?? []) {
+    index.matchers.set(matcher.name, { name: matcher.name, package: plugin.name, matcher });
+  }
+  addTypes(plugin, index);
+}
+
+/** A namespace offers its published types alongside its verbs: `http.Request`. */
+function addTypes(plugin: PluginDefinition, index: Index): void {
+  const entries = Object.entries(plugin.typeDefs ?? {});
+  if (entries.length === 0) return;
+  const list = index.typesByNamespace.get(plugin.namespace) ?? [];
+  for (const [name, spec] of entries) {
+    list.push({ namespace: plugin.namespace, name, package: plugin.name, spec });
+  }
+  index.typesByNamespace.set(plugin.namespace, list);
+}

package/src/catalog/catalog.types.ts

@@ -0,0 +1,44 @@
+import type { ActionDefinition, MatcherDefinition } from "@venn-lang/sdk";
+import type { TypeSpec } from "@venn-lang/types";
+
+/** One type a plugin publishes: `http.Request`, and the shape behind it. */
+export interface TypeEntry {
+  namespace: string;
+  name: string;
+  package: string;
+  spec: TypeSpec;
+}
+
+/** One action, with the package that contributes it. */
+export interface ActionEntry {
+  namespace: string;
+  name: string;
+  package: string;
+  action: ActionDefinition;
+}
+
+/** One matcher, with the package that contributes it. */
+export interface MatcherEntry {
+  name: string;
+  package: string;
+  matcher: MatcherDefinition;
+}
+
+/**
+ * Everything the editor needs to resolve, list and describe stdlib symbols.
+ * The grammar cannot tell `http.post` from `myHelper.foo`; this catalogue can.
+ */
+export interface SymbolCatalog {
+  namespaces(): readonly string[];
+  packages(): readonly string[];
+  hasNamespace(namespace: string): boolean;
+  actionsIn(namespace: string): readonly ActionEntry[];
+  action(namespace: string, name: string): ActionEntry | undefined;
+  /** The types that namespace publishes: what `http.` offers besides verbs. */
+  typesIn(namespace: string): readonly TypeEntry[];
+  matchers(): readonly MatcherEntry[];
+  matcher(name: string): MatcherEntry | undefined;
+  namespaceOfPackage(pkg: string): string | undefined;
+  /** Every package contributing this namespace: the `use` options to offer. */
+  packagesFor(namespace: string): readonly string[];
+}

package/src/catalog/index.ts

@@ -0,0 +1,2 @@
+export { buildCatalog } from "./build-catalog.js";
+export type { ActionEntry, MatcherEntry, SymbolCatalog } from "./catalog.types.js";

package/src/code-actions/anchor.ts

@@ -0,0 +1,49 @@
+import { type Document, type ImportDecl, isUseDecl, isValueImport } from "@venn-lang/core";
+import type { LangiumDocument } from "langium";
+import type { Position, TextEdit } from "vscode-languageserver";
+
+/** Which header group a new line joins. `use` always precedes `import`. */
+export type HeaderKind = "use" | "import";
+
+/**
+ * Insert a header line after the last one of its own kind, so `use` lines stay
+ * grouped above `import` lines rather than landing wherever the header ends.
+ */
+export function headerEdit(document: LangiumDocument, line: string, kind: HeaderKind): TextEdit {
+  const position = anchor(document, kind);
+  return { range: { start: position, end: position }, newText: `${line}\n` };
+}
+
+function anchor(document: LangiumDocument, kind: HeaderKind): Position {
+  const root = document.parseResult?.value as Document | undefined;
+  const imports = root?.imports ?? [];
+  const preferred = last(imports, kind === "use" ? isUseDecl : isValueImport);
+  const fallback = kind === "import" ? last(imports, isUseDecl) : undefined;
+  const end = endOf(preferred ?? fallback) ?? moduleEnd(root);
+  if (end === undefined) return { line: 0, character: 0 };
+  return { line: document.textDocument.positionAt(end).line + 1, character: 0 };
+}
+
+function last(
+  imports: readonly ImportDecl[],
+  is: (node: ImportDecl) => boolean,
+): ImportDecl | undefined {
+  return [...imports].reverse().find((decl) => is(decl));
+}
+
+function endOf(decl: ImportDecl | undefined): number | undefined {
+  const cst = decl?.$cstNode;
+  return cst ? cst.offset + cst.length : undefined;
+}
+
+function moduleEnd(root: Document | undefined): number | undefined {
+  if (!root?.name || !root.$cstNode) return undefined;
+  const newline = root.$cstNode.text.indexOf("\n");
+  return newline < 0 ? undefined : root.$cstNode.offset + newline;
+}
+
+/** True when the file already has an `import` naming this module path. */
+export function alreadyImports(document: LangiumDocument, path: string): boolean {
+  const root = document.parseResult?.value as Document | undefined;
+  return (root?.imports ?? []).some((decl) => isValueImport(decl) && decl.path === path);
+}

package/src/code-actions/code-actions.ts

@@ -0,0 +1,139 @@
+import {
+  type AstNode,
+  isActionCall,
+  isLetStmt,
+  isMatcherClause,
+  isRunStmt,
+  isStringLit,
+} from "@venn-lang/core";
+import { CstUtils, type LangiumDocument } from "langium";
+import type { CodeActionProvider } from "langium/lsp";
+import {
+  type CodeAction,
+  CodeActionKind,
+  type CodeActionParams,
+  type Diagnostic,
+  type TextEdit,
+} from "vscode-languageserver";
+import type { SymbolCatalog } from "../catalog/index.js";
+import { pathOf } from "../document/index.js";
+import type { VennServices } from "../services/lsp.types.js";
+import type { ImportResolver } from "../workspace/index.js";
+import { alreadyImports, headerEdit } from "./anchor.js";
+import { modulesExporting } from "./exporting-modules.js";
+
+interface FixArgs {
+  title: string;
+  edit: TextEdit;
+  document: LangiumDocument;
+  diagnostic: Diagnostic;
+  preferred: boolean;
+}
+
+/**
+ * Lightbulb fixes for the two "you never brought this in" diagnostics. When more
+ * than one source provides the name, every source is offered and the first is
+ * marked preferred, so the editor shows it first and applies it on Quick Fix.
+ */
+export class VennCodeActionProvider implements CodeActionProvider {
+  private readonly catalog: SymbolCatalog;
+  private readonly imports: ImportResolver;
+
+  constructor(services: VennServices) {
+    this.catalog = services.catalog;
+    this.imports = services.imports;
+  }
+
+  getCodeActions(document: LangiumDocument, params: CodeActionParams): CodeAction[] {
+    return params.context.diagnostics.flatMap((diagnostic) => this.fixes(diagnostic, document));
+  }
+
+  private fixes(diagnostic: Diagnostic, document: LangiumDocument): CodeAction[] {
+    if (diagnostic.code === "VN2007") return this.addUse(diagnostic, document);
+    if (diagnostic.code === "VN2005") return this.addImport(diagnostic, document);
+    if (diagnostic.code === "VN5001") return this.useLet(diagnostic, document);
+    return [];
+  }
+
+  private addUse(diagnostic: Diagnostic, document: LangiumDocument): CodeAction[] {
+    const node = nodeAt(document, diagnostic);
+    return this.sources(node).map((pkg, index) =>
+      fix({
+        title: `Add use "${pkg}"`,
+        edit: headerEdit(document, `use "${pkg}"`, "use"),
+        document,
+        diagnostic,
+        preferred: index === 0,
+      }),
+    );
+  }
+
+  /** Every package that would bring this name in, as action, matcher or call. */
+  private sources(node: AstNode | undefined): readonly string[] {
+    if (!node) return [];
+    if (isMatcherClause(node)) {
+      const found = this.catalog.matcher(node.name);
+      return found ? [found.package] : [];
+    }
+    // The read may hide inside `${…}`, where the node is the string, not a path.
+    if (isStringLit(node)) return this.interpolatedSources(node);
+    // A bare path counts too: `env.BASE_URL` is a read, and it still needs a `use`.
+    const path = isActionCall(node) ? node.target : pathOf(isLetStmt(node) ? node.value : node);
+    const namespace = path?.split(".")[0];
+    return namespace ? this.catalog.packagesFor(namespace) : [];
+  }
+
+  /** The package for the first namespace read in `"…${env.X}…"` we recognise. */
+  private interpolatedSources(node: { value?: string }): readonly string[] {
+    for (const match of (node.value ?? "").matchAll(/\$\{\s*([A-Za-z_]\w*)\./g)) {
+      const packages = this.catalog.packagesFor(match[1] ?? "");
+      if (packages.length > 0) return packages;
+    }
+    return [];
+  }
+
+  /** `capture` is spelled `let`, so the fix is exactly one word wide. */
+  private useLet(diagnostic: Diagnostic, document: LangiumDocument): CodeAction[] {
+    const { start } = diagnostic.range;
+    const end = { line: start.line, character: start.character + "capture".length };
+    const edit = { range: { start, end }, newText: "let" };
+    return [
+      fix({ title: "Replace `capture` with `let`", edit, document, diagnostic, preferred: true }),
+    ];
+  }
+
+  private addImport(diagnostic: Diagnostic, document: LangiumDocument): CodeAction[] {
+    const node = nodeAt(document, diagnostic);
+    if (!node || !isRunStmt(node)) return [];
+    const name = node.target;
+    const modules = modulesExporting({ name, base: document.uri, imports: this.imports });
+    return modules
+      .filter((module) => !alreadyImports(document, module.specifier))
+      .map((module, index) =>
+        fix({
+          title: `Import ${name} from "${module.specifier}"`,
+          edit: headerEdit(document, `import { ${name} } from "${module.specifier}"`, "import"),
+          document,
+          diagnostic,
+          preferred: index === 0,
+        }),
+      );
+  }
+}
+
+function fix(args: FixArgs): CodeAction {
+  return {
+    title: args.title,
+    kind: CodeActionKind.QuickFix,
+    diagnostics: [args.diagnostic],
+    isPreferred: args.preferred,
+    edit: { changes: { [args.document.uri.toString()]: [args.edit] } },
+  };
+}
+
+function nodeAt(document: LangiumDocument, diagnostic: Diagnostic): AstNode | undefined {
+  const root = document.parseResult?.value?.$cstNode;
+  if (!root) return undefined;
+  const offset = document.textDocument.offsetAt(diagnostic.range.start);
+  return CstUtils.findLeafNodeAtOffset(root, offset)?.astNode;
+}

package/src/code-actions/exporting-modules.ts

@@ -0,0 +1,73 @@
+import { type Dirent, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parse } from "@venn-lang/core";
+import { type URI, UriUtils } from "langium";
+import { exportedNames } from "../document/index.js";
+import type { ImportResolver } from "../workspace/index.js";
+
+const EXTENSION = ".vn";
+const MAX_DEPTH = 4;
+const SKIP = new Set(["node_modules", "dist", ".git"]);
+
+/** A module that exports the wanted name, and how to write its specifier. */
+export interface ExportingModule {
+  specifier: string;
+  file: string;
+}
+
+/**
+ * Every `.vn` file near this one that marks `name` as `pub`. Specifiers prefer
+ * a configured `#alias`, falling back to a relative path.
+ */
+export function modulesExporting(args: {
+  name: string;
+  base: URI;
+  imports: ImportResolver;
+}): ExportingModule[] {
+  const aliases = args.imports.aliases(args.base);
+  const root = UriUtils.dirname(args.base);
+  const found: ExportingModule[] = [];
+  for (const file of walk(root.fsPath, "", 0)) {
+    if (!exportsName(join(root.fsPath, file), args.name)) continue;
+    found.push({ specifier: specifierFor(file, root, aliases), file });
+  }
+  return found;
+}
+
+function exportsName(path: string, name: string): boolean {
+  try {
+    const { ast, problems } = parse(readFileSync(path, "utf8"), { uri: path });
+    return problems.length === 0 && exportedNames(ast).some((each) => each.name === name);
+  } catch {
+    return false;
+  }
+}
+
+// `#shared/auth.vn` reads better than `./shared/auth.vn` when an alias covers it.
+function specifierFor(file: string, root: URI, aliases: Record<string, URI>): string {
+  const absolute = UriUtils.resolvePath(root, file).toString();
+  for (const [alias, folder] of Object.entries(aliases)) {
+    const prefix = `${folder.toString()}/`;
+    if (absolute.startsWith(prefix)) return `${alias}/${absolute.slice(prefix.length)}`;
+  }
+  return `./${file}`;
+}
+
+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/code-actions/index.ts

@@ -0,0 +1,5 @@
+export type { HeaderKind } from "./anchor.js";
+export { alreadyImports, headerEdit } from "./anchor.js";
+export { VennCodeActionProvider } from "./code-actions.js";
+export type { ExportingModule } from "./exporting-modules.js";
+export { modulesExporting } from "./exporting-modules.js";

package/src/completion/argument-items.ts

@@ -0,0 +1,81 @@
+import { type AstNode, showType, type Type } from "@venn-lang/core";
+import type { CompletionItem, Range } from "vscode-languageserver";
+import type { SymbolCatalog } from "../catalog/index.js";
+import type { ScopedName } from "../document/index.js";
+import type { ShownArg } from "../signature/index.js";
+import { ICON, iconForOrigin } from "./icons.js";
+import { item } from "./items.js";
+
+export interface ArgumentItemsArgs {
+  names: readonly ScopedName[];
+  types: ReadonlyMap<AstNode, Type>;
+  /** The argument being written, when the verb said what it takes. */
+  expects: ShownArg | undefined;
+  catalog: SymbolCatalog;
+  range: Range;
+}
+
+/**
+ * What can go here, most likely first.
+ *
+ * An argument almost always wants something the program already has: the server
+ * two lines up, the parameter of the enclosing function. Offering the loaded
+ * namespaces first, as a fresh statement would, buries the one answer under
+ * dozens that cannot be right.
+ */
+export function argumentItems(args: ArgumentItemsArgs): CompletionItem[] {
+  const values = args.names.map((each) => valueItem(each, args));
+  const namespaces = args.catalog.namespaces().map((name) => nsItem(name, args.range));
+  return [...values, ...namespaces];
+}
+
+/**
+ * The names a program holds, offered where no type is expected of them.
+ *
+ * The start of a statement is such a place: nothing says what should go there,
+ * so nothing can be ranked as fitting, only drawn for what it is.
+ */
+export function boundItems(names: readonly ScopedName[], range: Range): CompletionItem[] {
+  return names.map((scoped) => ({
+    ...item({
+      label: scoped.name,
+      kind: iconForOrigin(scoped.origin),
+      range,
+      detail: scoped.origin,
+    }),
+    sortText: `0${scoped.name}`,
+  }));
+}
+
+function valueItem(scoped: ScopedName, args: ArgumentItemsArgs): CompletionItem {
+  const type = args.types.get(scoped.node);
+  const shown = type ? showType(type) : undefined;
+  return {
+    ...item({
+      label: scoped.name,
+      kind: iconForOrigin(scoped.origin),
+      range: args.range,
+      detail: shown ? `${scoped.origin} ${scoped.name}: ${shown}` : scoped.origin,
+    }),
+    sortText: `${fits(shown, args.expects) ? "0" : "1"}${scoped.name}`,
+  };
+}
+
+function nsItem(name: string, range: Range): CompletionItem {
+  return {
+    ...item({ label: name, kind: ICON.namespace, range }),
+    sortText: `2${name}`,
+  };
+}
+
+/**
+ * Whether a value is the kind of thing this argument wants. Compared as the two
+ * read, not by unification: the checker's types carry inference variables that
+ * matching would have to bind, and ranking a list must not change what a
+ * program means.
+ */
+function fits(shown: string | undefined, expects: ShownArg | undefined): boolean {
+  if (!shown || !expects) return false;
+  if (shown === expects.type) return true;
+  return expects.type.startsWith("fn(") && shown.startsWith("fn(");
+}