@venn-lang/lsp 0.1.0

package/src/semantic/highlight-paths.ts

@@ -0,0 +1,80 @@
+import { isCall, isMember, isRef, MEMBER_DOCS } from "@venn-lang/core";
+import { SemanticTokenModifiers, SemanticTokenTypes } from "vscode-languageserver";
+import type { SymbolCatalog } from "../catalog/index.js";
+import { findBinding, pathOf } from "../document/index.js";
+import type { HighlightArgs } from "./highlight.types.js";
+
+const LIB = SemanticTokenModifiers.defaultLibrary;
+
+/** Every built-in member name, whatever kind of value it hangs off. */
+const BUILT_IN = new Set(Object.values(MEMBER_DOCS).flatMap((table) => Object.keys(table)));
+
+/**
+ * Colour what a `.` reaches. The parser cannot tell `http.post` from
+ * `res.status`, since both are member chains, so the catalog and the built-in
+ * tables decide: a plugin verb reads as a function, a built-in as a method, and
+ * anything else as the field it is.
+ *
+ * Returns whether it claimed the node; tokens must not overlap.
+ */
+export function highlightPath(args: HighlightArgs): boolean {
+  const { node, acceptor } = args;
+  if (isRef(node)) return namespaceHead(node.name, args);
+  if (!isMember(node)) return false;
+  acceptor({ node, property: "member", ...memberToken(node.member, args) });
+  return true;
+}
+
+interface Token {
+  type: string;
+  modifier?: string | string[];
+}
+
+/** A plugin verb, a built-in method, or an ordinary field. */
+function memberToken(member: string, args: HighlightArgs): Token {
+  const path = pathOf(args.node);
+  if (path && isStdlibPath(path, args)) return stdlibToken(path, args.catalog);
+  if (BUILT_IN.has(member)) {
+    return { type: methodOrProperty(args), modifier: LIB };
+  }
+  return { type: SemanticTokenTypes.property };
+}
+
+/** `xs.map(…)` is a method; `xs.len` is a property, read without parentheses. */
+function methodOrProperty(args: HighlightArgs): string {
+  return isCall(args.node.$container) && args.node.$container.callee === args.node
+    ? SemanticTokenTypes.method
+    : SemanticTokenTypes.property;
+}
+
+/** The head of `http.post` is a namespace, not a variable nobody declared. */
+function namespaceHead(name: string, args: HighlightArgs): boolean {
+  if (!isNamespace(name, args)) return false;
+  args.acceptor({
+    node: args.node,
+    property: "name",
+    type: SemanticTokenTypes.namespace,
+    modifier: LIB,
+  });
+  return true;
+}
+
+/** Scope wins: a variable named `auth` stays a variable even though `auth` is a namespace. */
+function isNamespace(name: string, args: HighlightArgs): boolean {
+  return args.catalog.hasNamespace(name) && !findBinding(args.node, name);
+}
+
+/** The last segment is the verb when the whole path names an action. */
+function stdlibToken(path: string, catalog: SymbolCatalog): Token {
+  const namespace = path.slice(0, path.indexOf("."));
+  const name = path.slice(path.indexOf(".") + 1);
+  const type = catalog.action(namespace, name)
+    ? SemanticTokenTypes.function
+    : SemanticTokenTypes.property;
+  return { type, modifier: LIB };
+}
+
+function isStdlibPath(path: string, args: HighlightArgs): boolean {
+  const dot = path.indexOf(".");
+  return dot > 0 && isNamespace(path.slice(0, dot), args);
+}

package/src/semantic/highlight.types.ts

@@ -0,0 +1,10 @@
+import type { AstNode } from "@venn-lang/core";
+import type { SemanticTokenAcceptor } from "langium/lsp";
+import type { SymbolCatalog } from "../catalog/index.js";
+
+/** What a highlight pass needs: the node, where to emit, and symbol resolution. */
+export interface HighlightArgs {
+  node: AstNode;
+  acceptor: SemanticTokenAcceptor;
+  catalog: SymbolCatalog;
+}

package/src/semantic/index.ts

@@ -0,0 +1 @@
+export { VennSemanticTokenProvider } from "./semantic-tokens.js";

package/src/semantic/semantic-tokens.ts

@@ -0,0 +1,32 @@
+import type { AstNode } from "langium";
+import { AbstractSemanticTokenProvider, type SemanticTokenAcceptor } from "langium/lsp";
+import type { SymbolCatalog } from "../catalog/index.js";
+import type { VennServices } from "../services/lsp.types.js";
+import { highlightCalls } from "./highlight-calls.js";
+import { highlightKeywords } from "./highlight-keywords.js";
+import { highlightLiterals } from "./highlight-literals.js";
+import { highlightModule } from "./highlight-module.js";
+import { highlightNames } from "./highlight-names.js";
+
+/**
+ * Colours a `.vn` the way §23 specifies. The grammar cannot tell `http.post`
+ * from `myHelper.foo`, since both are `ActionCall`, so the catalog decides.
+ * Each pass owns one family of tokens, and a node matches at most one of them.
+ */
+export class VennSemanticTokenProvider extends AbstractSemanticTokenProvider {
+  private readonly catalog: SymbolCatalog;
+
+  constructor(services: VennServices) {
+    super(services);
+    this.catalog = services.catalog;
+  }
+
+  protected override highlightElement(node: AstNode, acceptor: SemanticTokenAcceptor): void {
+    const args = { node, acceptor, catalog: this.catalog };
+    highlightKeywords(node, acceptor);
+    highlightModule(args);
+    highlightCalls(args);
+    highlightLiterals(args);
+    highlightNames(args);
+  }
+}

package/src/server/index.ts

@@ -0,0 +1 @@
+export { startVennServer } from "./start-server.js";

package/src/server/start-server.ts

@@ -0,0 +1,15 @@
+import { startLanguageServer } from "langium/lsp";
+import { NodeFileSystem } from "langium/node";
+import type { Connection } from "vscode-languageserver";
+import { createVennLspServices } from "../services/index.js";
+
+/**
+ * Start the Venn language server on an established connection. This is the one
+ * wiring shared by the standalone `venn-lsp` binary and the VS Code extension.
+ *
+ * @param connection An LSP connection the caller has already created.
+ */
+export function startVennServer(connection: Connection): void {
+  const { shared } = createVennLspServices({ connection, ...NodeFileSystem });
+  startLanguageServer(shared);
+}

package/src/services/index.ts

@@ -0,0 +1,2 @@
+export type { VennAddedServices, VennServices } from "./lsp.types.js";
+export { createVennLspServices } from "./venn-lsp-module.js";

package/src/services/lsp.types.ts

@@ -0,0 +1,14 @@
+import type { LangiumServices } from "langium/lsp";
+import type { SymbolCatalog } from "../catalog/index.js";
+import type { TypeService } from "../types/index.js";
+import type { ImportResolver } from "../workspace/index.js";
+
+/** The extra services Venn adds on top of Langium's LSP stack. */
+export interface VennAddedServices {
+  catalog: SymbolCatalog;
+  imports: ImportResolver;
+  types: TypeService;
+}
+
+/** The full language services for Venn. */
+export type VennServices = LangiumServices & VennAddedServices;

package/src/services/venn-lsp-module.ts

@@ -0,0 +1,65 @@
+import { VennGeneratedModule, VennGeneratedSharedModule, VennLexer } from "@venn-lang/core";
+import { allPlugins } from "@venn-lang/stdlib";
+import { inject, type Module } from "langium";
+import {
+  createDefaultModule,
+  createDefaultSharedModule,
+  type DefaultSharedModuleContext,
+  type LangiumSharedServices,
+  type PartialLangiumServices,
+} from "langium/lsp";
+import { buildCatalog } from "../catalog/index.js";
+import { VennCodeActionProvider } from "../code-actions/index.js";
+import { VennCompletionProvider } from "../completion/index.js";
+import { VennDefinitionProvider } from "../definition/index.js";
+import { VennFormatter } from "../formatting/index.js";
+import { VennHoverProvider } from "../hover/index.js";
+import { VennDocumentHighlightProvider, VennReferencesProvider } from "../references/index.js";
+import { VennRenameProvider } from "../rename/index.js";
+import { VennSemanticTokenProvider } from "../semantic/index.js";
+import { VennSignatureHelpProvider } from "../signature/index.js";
+import { VennDocumentSymbolProvider } from "../symbols/index.js";
+import { createTypeService, warmTypes } from "../types/index.js";
+import { registerVennChecks } from "../validation/index.js";
+import { createImportResolver } from "../workspace/index.js";
+import type { VennAddedServices, VennServices } from "./lsp.types.js";
+
+const VennModule: Module<VennServices, PartialLangiumServices & VennAddedServices> = {
+  catalog: () => buildCatalog(allPlugins),
+  imports: () => createImportResolver(),
+  types: (services) => createTypeService(services),
+  parser: { Lexer: (services) => new VennLexer(services) },
+  lsp: {
+    SemanticTokenProvider: (services) => new VennSemanticTokenProvider(services),
+    HoverProvider: (services) => new VennHoverProvider(services),
+    DefinitionProvider: (services) => new VennDefinitionProvider(services),
+    CompletionProvider: (services) => new VennCompletionProvider(services),
+    DocumentSymbolProvider: () => new VennDocumentSymbolProvider(),
+    RenameProvider: (services) => new VennRenameProvider(services),
+    ReferencesProvider: (services) => new VennReferencesProvider(services),
+    DocumentHighlightProvider: () => new VennDocumentHighlightProvider(),
+    CodeActionProvider: (services) => new VennCodeActionProvider(services),
+    SignatureHelp: (services) => new VennSignatureHelpProvider(services),
+    Formatter: (services) => new VennFormatter(services),
+  },
+};
+
+/**
+ * Build the Venn language services on top of Langium's LSP stack. Registering
+ * the validator and warming the type cache happen here, so a caller only has to
+ * supply a connection and start the server.
+ *
+ * @param context Langium's shared module context: a connection and a file system.
+ * @returns The shared Langium services, and the Venn services built on them.
+ */
+export function createVennLspServices(context: DefaultSharedModuleContext): {
+  shared: LangiumSharedServices;
+  Venn: VennServices;
+} {
+  const shared = inject(createDefaultSharedModule(context), VennGeneratedSharedModule);
+  const Venn = inject(createDefaultModule({ shared }), VennGeneratedModule, VennModule);
+  shared.ServiceRegistry.register(Venn);
+  registerVennChecks(Venn);
+  warmTypes(shared, Venn.types);
+  return { shared, Venn };
+}

package/src/signature/action-call.ts

@@ -0,0 +1,82 @@
+import {
+  type ActionCall,
+  type Expr,
+  isActionCall,
+  isMatcherClause,
+  type MatcherClause,
+} from "@venn-lang/core";
+import { AstUtils, type LangiumDocument } from "langium";
+
+/** Anything written as a bare word followed by bare arguments. */
+interface Bareword {
+  args?: readonly Expr[];
+  readonly $cstNode?: { offset: number };
+}
+
+/**
+ * The action call the cursor is writing, if it is writing one.
+ *
+ * Not found by walking up from the token under the cursor: the cursor is on
+ * whitespace here (`http.on ` is the whole point), and in this grammar the
+ * newline is a real token belonging to the document, not to the statement. So
+ * the call is found by where it starts instead: the one that begins on this
+ * line, before the cursor. A statement holds at most one, so there is no
+ * innermost to choose between.
+ */
+export function enclosingCall(document: LangiumDocument, offset: number): ActionCall | undefined {
+  const root = document.parseResult?.value;
+  if (!root) return undefined;
+  const from = lineStart(document.textDocument.getText(), offset);
+  let found: ActionCall | undefined;
+  for (const node of AstUtils.streamAst(root)) {
+    const start = node.$cstNode?.offset;
+    if (isActionCall(node) && start !== undefined && start >= from && start < offset) found = node;
+  }
+  return found;
+}
+
+/** The same for `expect subject contains ▮`; a matcher takes bare arguments too. */
+export function enclosingMatcher(
+  document: LangiumDocument,
+  offset: number,
+): MatcherClause | undefined {
+  const root = document.parseResult?.value;
+  if (!root) return undefined;
+  const from = lineStart(document.textDocument.getText(), offset);
+  let found: MatcherClause | undefined;
+  for (const node of AstUtils.streamAst(root)) {
+    const start = node.$cstNode?.offset;
+    if (isMatcherClause(node) && start !== undefined && start >= from && start < offset) {
+      found = node;
+    }
+  }
+  return found && offset > (found.$cstNode?.offset ?? 0) + found.name.length ? found : undefined;
+}
+
+function lineStart(text: string, offset: number): number {
+  return text.lastIndexOf("\n", Math.max(0, offset - 1)) + 1;
+}
+
+/**
+ * Which argument the cursor is on.
+ *
+ * An argument that ends before the cursor has been written; one that ends at it
+ * is still being typed. So `http.on api|` is on the first argument and
+ * `http.on api |` has moved to the second, which is what makes the highlight
+ * move as the space is pressed rather than a keystroke late.
+ */
+export function activeArg(call: Bareword, offset: number): number {
+  let written = 0;
+  for (const arg of call.args ?? []) {
+    const end = arg.$cstNode?.end;
+    if (end === undefined || end >= offset) break;
+    written += 1;
+  }
+  return written;
+}
+
+/** Whether the cursor sits after the verb rather than still inside its name. */
+export function pastTarget(call: ActionCall, offset: number): boolean {
+  const start = call.$cstNode?.offset ?? 0;
+  return offset > start + call.target.length;
+}

package/src/signature/bare-call.ts

@@ -0,0 +1,55 @@
+import { dottedPath, type Expr, isActionCall, isLetStmt, type LetStmt } from "@venn-lang/core";
+import { type AstNode, AstUtils, type LangiumDocument } from "langium";
+
+/** A call written without brackets, wherever the language allows one. */
+export interface BareCall {
+  /** The verb being called: `http.get`. */
+  target: string;
+  /** The bare arguments after it, in order. */
+  args: readonly Expr[];
+  /** Where the verb's own name ends; the cursor must be past it. */
+  after: number;
+  /** The node it was found on, for looking names up in scope. */
+  node: AstNode;
+}
+
+/**
+ * The bracket-less call the cursor is writing.
+ *
+ * Two nodes spell one thing. `http.get "u"` standing alone is an action call;
+ * bound with `const r = http.get "u"` it is a `let` whose value happens to name
+ * a verb, with the arguments hanging off the statement. The same words deserve
+ * the same help, so both are found here.
+ */
+export function enclosingBareCall(document: LangiumDocument, offset: number): BareCall | undefined {
+  const root = document.parseResult?.value;
+  if (!root) return undefined;
+  const from = lineStart(document.textDocument.getText(), offset);
+  let found: BareCall | undefined;
+  for (const node of AstUtils.streamAst(root)) {
+    const start = node.$cstNode?.offset;
+    if (start === undefined || start < from || start >= offset) continue;
+    found = asBareCall(node) ?? found;
+  }
+  return found && offset > found.after ? found : undefined;
+}
+
+function asBareCall(node: unknown): BareCall | undefined {
+  if (isActionCall(node)) {
+    const start = node.$cstNode?.offset ?? 0;
+    return { target: node.target, args: node.args, after: start + node.target.length, node };
+  }
+  return isLetStmt(node) ? letCall(node) : undefined;
+}
+
+/** `const r = http.get "u" { … }`: the verb is the value, the args follow it. */
+function letCall(node: LetStmt): BareCall | undefined {
+  const target = dottedPath(node.value);
+  const end = node.value.$cstNode?.end;
+  if (!target || end === undefined) return undefined;
+  return { target, args: node.args, after: end, node };
+}
+
+function lineStart(text: string, offset: number): number {
+  return text.lastIndexOf("\n", Math.max(0, offset - 1)) + 1;
+}

package/src/signature/call-shape.ts

@@ -0,0 +1,90 @@
+import { PRELUDE_SPECS } from "@venn-lang/core";
+import { type ActionDefinition, type ArgSpec, paramSpecs } from "@venn-lang/sdk";
+import { type FnSpec, showSpec } from "@venn-lang/types";
+import type { SymbolCatalog } from "../catalog/index.js";
+import type { CallShape, ShownArg } from "./call-shape.types.js";
+
+/**
+ * What `target` takes, as the editor describes it back.
+ *
+ * A verb people can call is a verb people can be told about, whether a plugin
+ * contributes it or the prelude does. Returns undefined only when nothing in
+ * the language answers to that name.
+ */
+export function callShape(target: string, catalog: SymbolCatalog): CallShape | undefined {
+  const dot = target.indexOf(".");
+  if (dot < 0) return preludeShape(target);
+  const entry = catalog.action(target.slice(0, dot), target.slice(dot + 1));
+  if (!entry) return undefined;
+  return {
+    target,
+    args: entry.action.args ? shownArgs(entry.action.args) : unnamed(entry.action.signature),
+    options: paramSpecs(entry.action.params),
+    doc: entry.action.doc,
+    returns: returnOf(entry.action),
+  };
+}
+
+/** The same, for a bareword matcher: `expect res contains "ok"`. */
+export function matcherShape(name: string, catalog: SymbolCatalog): CallShape | undefined {
+  const entry = catalog.matcher(name);
+  if (!entry) return undefined;
+  return {
+    target: name,
+    args: shownArgs(entry.matcher.args ?? []),
+    options: paramSpecs(entry.matcher.params),
+    doc: entry.matcher.appliesTo ? `Applies to ${entry.matcher.appliesTo}.` : undefined,
+  };
+}
+
+/**
+ * What the verb gives back, in the language's own words.
+ *
+ * Read from the declared type, never from prose beside it: a second place to
+ * say the same thing is a second place to say it differently.
+ */
+function returnOf(action: ActionDefinition): string | undefined {
+  const result = action.signature?.result;
+  // Nothing worth saying about a verb that answers nothing.
+  if (!result || (result.kind === "prim" && result.name === "void")) return undefined;
+  return showSpec(result);
+}
+
+/** Published argument specs as the editor shows them. */
+export function shownArgs(specs: readonly ArgSpec[]): readonly ShownArg[] {
+  return specs.map(shownArg);
+}
+
+/**
+ * What can still be said about a verb whose author named nothing: how many
+ * arguments it takes, and of what. Worse than a name and far better than
+ * silence, and the only thing a plugin from outside this repo may ever offer.
+ */
+function unnamed(signature: FnSpec | undefined): readonly ShownArg[] {
+  return (signature?.params ?? []).map((type) => ({ name: "", type: showSpec(type) }));
+}
+
+function shownArg(spec: ArgSpec): ShownArg {
+  return {
+    name: spec.name,
+    type: showSpec(spec.type),
+    doc: spec.doc,
+    optional: spec.optional,
+    rest: spec.rest,
+  };
+}
+
+/**
+ * The prelude describes itself already: the checker reads its types and the
+ * editor its prose. This reads the same table, so the two never disagree.
+ */
+function preludeShape(name: string): CallShape | undefined {
+  const spec = PRELUDE_SPECS[name];
+  if (!spec) return undefined;
+  return {
+    target: name,
+    args: (spec.args ?? []).map((each) => ({ ...each })),
+    options: [],
+    doc: spec.doc,
+  };
+}

package/src/signature/call-shape.types.ts

@@ -0,0 +1,34 @@
+import type { ParamSpec } from "@venn-lang/sdk";
+
+/**
+ * A call as the editor describes it back to whoever is typing it.
+ *
+ * Deliberately not an LSP type: the same shape answers signature help, hover
+ * and the completion detail line, and only one of those speaks LSP.
+ */
+export interface CallShape {
+  /** What is being called: `http.on`, `print`. */
+  target: string;
+  args: readonly ShownArg[];
+  /**
+   * The keys the trailing `{ … }` accepts, empty when it accepts none.
+   *
+   * The options are an argument like any other, the last one and a map, so they
+   * are described here rather than flagged with a boolean. A reader halfway
+   * through `http.get(url, ` is asking exactly what may go next.
+   */
+  options: readonly ParamSpec[];
+  doc?: string;
+  /** Prose for what comes back, when the author wrote any. */
+  returns?: string;
+}
+
+export interface ShownArg {
+  name: string;
+  /** The type as text: `string`, `HttpServer`, `fn(request) -> reply`. */
+  type: string;
+  doc?: string;
+  optional?: boolean;
+  /** Takes this one and every argument after it. */
+  rest?: boolean;
+}

package/src/signature/declared-shape.ts

@@ -0,0 +1,52 @@
+import {
+  type AstNode,
+  DYNAMIC,
+  isDatasetDecl,
+  isFnDecl,
+  isFnExpr,
+  isFragmentDecl,
+  isLetStmt,
+  type ParamList,
+  showTypes,
+} from "@venn-lang/core";
+import type { LangiumDocument } from "langium";
+import type { TypeService } from "../types/index.js";
+import type { CallShape } from "./call-shape.types.js";
+
+export interface DeclaredShapeArgs {
+  /** The node that binds the name: what `findBinding` answered. */
+  binding: AstNode;
+  name: string;
+  document: LangiumDocument;
+  types: TypeService;
+}
+
+/**
+ * What a function the file itself declares takes, by name.
+ *
+ * The names are written right there in the source; the types come from
+ * inference, which for an unannotated `fn` means a variable until the body
+ * pins it down. A name with `a` next to it still tells the reader which
+ * argument they are on, which is the question a half-typed call asks.
+ */
+export function declaredShape(args: DeclaredShapeArgs): CallShape | undefined {
+  const params = paramsOf(args.binding);
+  if (!params) return undefined;
+  const known = args.types.of(args.document).types;
+  // Named together, so two unrelated parameters do not both come back as `a`.
+  const shown = showTypes(params.params.map((param) => known.get(param) ?? DYNAMIC));
+  return {
+    target: args.name,
+    args: params.params.map((param, at) => ({ name: param.name, type: shown[at] ?? "dynamic" })),
+    options: [],
+    returns: undefined,
+  };
+}
+
+/** The parameter list, wherever the binding keeps one. */
+function paramsOf(binding: AstNode): ParamList | undefined {
+  if (isFnDecl(binding) || isFragmentDecl(binding) || isFnExpr(binding)) return binding.params;
+  // `const op = (a, b) => a + b`: the parameters belong to the lambda it holds.
+  const value = (isLetStmt(binding) || isDatasetDecl(binding)) && binding.value;
+  return value && isFnExpr(value) ? value.params : undefined;
+}

package/src/signature/index.ts

@@ -0,0 +1,11 @@
+export { activeArg, enclosingCall, enclosingMatcher, pastTarget } from "./action-call.js";
+export type { BareCall } from "./bare-call.js";
+export { enclosingBareCall } from "./bare-call.js";
+export { callShape, matcherShape, shownArgs } from "./call-shape.js";
+export type { CallShape, ShownArg } from "./call-shape.types.js";
+export { declaredShape } from "./declared-shape.js";
+export type { ParenCall } from "./paren-call.js";
+export { enclosingParenCall } from "./paren-call.js";
+export { bracketed, signatureOfShape } from "./render-shape.js";
+export { shapeAt } from "./shape-at.js";
+export { VennSignatureHelpProvider } from "./signature-help.js";

package/src/signature/paren-call.ts

@@ -0,0 +1,77 @@
+import type { AstNode } from "@venn-lang/core";
+import { CstUtils, type LangiumDocument } from "langium";
+
+/** A bracketed call the cursor is inside, read from the text. */
+export interface ParenCall {
+  /** The dotted name being called: `saudacao`, `fmt.json`. */
+  path: string;
+  /** Which argument is being written, counted by the commas before it. */
+  active: number;
+  /** A node in the same scope, for looking the name up. */
+  host: AstNode | undefined;
+}
+
+/**
+ * The innermost `f(…)` whose brackets hold the cursor.
+ *
+ * Read from the text rather than from the tree, because the states that most
+ * need explaining are exactly the ones that do not parse: `f("a", ▮)` has a
+ * trailing comma, which is a syntax error, and a hint that disappears the
+ * moment you press comma is a hint that is never there when wanted.
+ */
+export function enclosingParenCall(
+  document: LangiumDocument,
+  offset: number,
+): ParenCall | undefined {
+  const text = document.textDocument.getText();
+  const open = innermostOpenParen(text, offset);
+  if (open < 0) return undefined;
+  const path = nameBefore(text.slice(0, open));
+  if (!path) return undefined;
+  return { path, active: commas(text.slice(open + 1, offset)), host: nodeNear(document, open) };
+}
+
+/** How far back to look for the bracket. A call this long is not being typed. */
+const REACH = 2000;
+
+/** The `(` still open at the cursor, scanning backwards. */
+function innermostOpenParen(text: string, offset: number): number {
+  let depth = 0;
+  for (let at = offset - 1; at >= Math.max(0, offset - REACH); at -= 1) {
+    const char = text[at];
+    if (char === ")") depth += 1;
+    else if (char === "(") {
+      if (depth === 0) return at;
+      depth -= 1;
+    }
+  }
+  return -1;
+}
+
+const CALLEE = /([A-Za-z_]\w*(?:\.\w+)*)$/;
+
+/** The dotted name written immediately before the bracket. */
+function nameBefore(before: string): string | undefined {
+  return CALLEE.exec(before)?.[1];
+}
+
+/** Commas at this bracket's own level: those in a nested call are not ours. */
+function commas(inside: string): number {
+  let depth = 0;
+  let count = 0;
+  for (const char of inside) {
+    if (char === "(" || char === "[" || char === "{") depth += 1;
+    else if (char === ")" || char === "]" || char === "}") depth -= 1;
+    else if (char === "," && depth === 0) count += 1;
+  }
+  return count;
+}
+
+/** Any node at the bracket, so a name can be looked up in the right scope. */
+function nodeNear(document: LangiumDocument, offset: number): AstNode | undefined {
+  const root = document.parseResult?.value?.$cstNode;
+  if (!root) return undefined;
+  const leaf =
+    CstUtils.findLeafNodeAtOffset(root, offset) ?? CstUtils.findLeafNodeBeforeOffset(root, offset);
+  return leaf?.astNode;
+}