@venn-lang/lsp 0.1.0

package/src/completion/completion.ts

@@ -0,0 +1,416 @@
+import { type AstNode, type Document, isUseDecl } from "@venn-lang/core";
+import type { LangiumDocument, LangiumDocuments } from "langium";
+import type { CompletionProvider } from "langium/lsp";
+import type {
+  CompletionItem,
+  CompletionList,
+  CompletionParams,
+  Position,
+  Range,
+} from "vscode-languageserver";
+import type { SymbolCatalog } from "../catalog/index.js";
+import { decosInScope } from "../deco/index.js";
+import {
+  exportedNames,
+  hostAt,
+  importedFragments,
+  importedModules,
+  namesInScope,
+  type ScopedName,
+} from "../document/index.js";
+import { envVars } from "../env/index.js";
+import type { VennServices } from "../services/lsp.types.js";
+import {
+  activeArg,
+  type CallShape,
+  callShape,
+  enclosingBareCall,
+  enclosingCall,
+  enclosingMatcher,
+  enclosingParenCall,
+  matcherShape,
+  type ShownArg,
+  shapeAt,
+} from "../signature/index.js";
+import type { TypeService } from "../types/index.js";
+import type { ImportResolver } from "../workspace/index.js";
+import { argumentItems, boundItems } from "./argument-items.js";
+import type { CompletionContext } from "./completion.types.js";
+import { contextAt } from "./context.js";
+import {
+  actionItems,
+  annotationItems,
+  envItems,
+  exportItems,
+  fragmentItems,
+  matcherItems,
+  openingItems,
+  optionItems,
+  packageItems,
+  pathItems,
+  typeItems,
+} from "./items.js";
+import { memberItems, membersOfNode } from "./member-items.js";
+import { modulePaths } from "./module-paths.js";
+import { optionsMapItems } from "./options-map-items.js";
+import { typeNameItems } from "./type-name-items.js";
+
+/**
+ * Context-aware completion, driven by the text before the cursor.
+ *
+ * `contextAt` classifies the cursor, and each context has exactly one source of
+ * items: a namespace's verbs, an options map's keys, the names in scope.
+ */
+export class VennCompletionProvider implements CompletionProvider {
+  private readonly catalog: SymbolCatalog;
+  private readonly documents: LangiumDocuments;
+  private readonly imports: ImportResolver;
+  private readonly types: TypeService;
+
+  constructor(services: VennServices) {
+    this.catalog = services.catalog;
+    this.documents = services.shared.workspace.LangiumDocuments;
+    this.imports = services.imports;
+    this.types = services.types;
+  }
+
+  async getCompletion(
+    document: LangiumDocument,
+    params: CompletionParams,
+  ): Promise<CompletionList> {
+    const line = lineAt(document, params.position);
+    const text = document.textDocument.getText();
+    const offset = document.textDocument.offsetAt(params.position);
+    const context = contextAt({
+      prefix: line.slice(0, params.position.character),
+      line,
+      before: text.slice(0, offset),
+    });
+    const range = rangeOf(context, params.position);
+    return { isIncomplete: false, items: await this.itemsFor(context, range, document, offset) };
+  }
+
+  /**
+   * What follows a dot. A name the file bound wins over a plugin namespace, the
+   * same rule the evaluator and the highlighter follow, so a variable named
+   * `auth` completes as its own value even when `@venn-lang/auth` is loaded.
+   */
+  private afterDot(
+    receiver: string,
+    range: Range,
+    document: LangiumDocument,
+    offset: number,
+  ): CompletionItem[] {
+    const types = this.types.of(document);
+    const host = hostAt({ document, offset, types, prefer: "before" });
+    const members = host
+      ? memberItems({ receiver, host, document, types: this.types, range })
+      : undefined;
+    if (members?.length) return members;
+    if (receiver === "env") return this.env(document, range);
+    // A namespace answers with what it does and with what it deals in.
+    return [
+      ...actionItems(receiver, this.catalog, range),
+      ...typeItems(receiver, this.catalog, range),
+    ];
+  }
+
+  /**
+   * What follows a dot no name can precede: `(1234.567).`, `f(x).`, `xs[0].`.
+   * The receiver has no text to look up, so its inferred type answers.
+   */
+  private afterExpression(
+    range: Range,
+    document: LangiumDocument,
+    offset: number,
+  ): CompletionItem[] {
+    const types = this.types.of(document);
+    const host = hostAt({ document, offset, types, prefer: "before" });
+    return host ? membersOfNode({ host, at: offset, document, types: this.types, range }) : [];
+  }
+
+  private env(document: LangiumDocument, range: Range): CompletionItem[] {
+    const uri = document.uri;
+    return envItems(envVars(this.imports.env(uri), this.imports.envDocs(uri)), range);
+  }
+
+  private async itemsFor(
+    context: CompletionContext,
+    range: Range,
+    document: LangiumDocument,
+    offset: number,
+  ): Promise<CompletionItem[]> {
+    if (context.kind === "package") return packageItems(this.catalog, range);
+    if (context.kind === "modulePath") return this.paths(context.partial, range, document);
+    if (context.kind === "importName") return this.exports(context.path, range, document);
+    if (context.kind === "action") return this.afterDot(context.receiver, range, document, offset);
+    if (context.kind === "member") return this.afterExpression(range, document, offset);
+    if (context.kind === "annotation") return this.decorators(document, range);
+    if (context.kind === "fragment") return this.fragments(range, document);
+    if (context.kind === "matcher") return matcherItems(this.catalog, range);
+    if (context.kind === "optionKey") {
+      return optionItems({ target: context.target, catalog: this.catalog, range });
+    }
+    if (context.kind === "typeName") return this.typeNames(range, document);
+    if (context.kind === "argument") return this.argument(context, range, document, offset);
+    return this.fallback(range, document, offset);
+  }
+
+  /**
+   * Every name in scope, with an imported one drawn as what it really is.
+   *
+   * `namesInScope` reads this file's tree, so it can say only that a name came
+   * from an import. Its kind lives in the file it came from, which is in reach
+   * here, so an imported fragment is drawn as a fragment rather than as an
+   * anonymous binding.
+   */
+  private scopeNames(host: AstNode, at: number, document: LangiumDocument): ScopedName[] {
+    const found = namesInScope(host, at);
+    if (!found.some((one) => one.origin === "import")) return found;
+    const root = rootOf(document);
+    const known = root ? this.publishedTo(root, document) : new Map<string, string>();
+    return found.map((one) =>
+      one.origin === "import" ? { ...one, origin: known.get(one.name) ?? one.origin } : one,
+    );
+  }
+
+  /** What each name this file imported was declared as, in the file it came from. */
+  private publishedTo(root: Document, document: LangiumDocument): Map<string, string> {
+    const graph = importedModules({
+      root,
+      uri: document.uri,
+      documents: this.documents,
+      imports: this.imports,
+    });
+    const known = new Map<string, string>();
+    for (const module of graph.modules.values()) {
+      for (const each of exportedNames(module)) known.set(each.name, each.origin);
+    }
+    return known;
+  }
+
+  /**
+   * `run ▮`: the fragments this file declared, and the ones it imported.
+   *
+   * `run` can only invoke a fragment, so an imported name is offered only once
+   * the file it came from confirms it is one.
+   */
+  private fragments(range: Range, document: LangiumDocument): CompletionItem[] {
+    const root = rootOf(document);
+    if (!root) return [];
+    const graph = importedModules({
+      root,
+      uri: document.uri,
+      documents: this.documents,
+      imports: this.imports,
+    });
+    const imported = importedFragments({ document: root, uri: document.uri.toString(), graph });
+    return fragmentItems({ document: root, imported, range });
+  }
+
+  /** `id: ▮`: the language's own types, this file's, and its imports'. */
+  private typeNames(range: Range, document: LangiumDocument): CompletionItem[] {
+    const root = rootOf(document);
+    return typeNameItems({
+      root,
+      catalog: this.catalog,
+      imported: root ? namespacesUsed(root, this.catalog) : [],
+      range,
+    });
+  }
+
+  /**
+   * The last two shapes a cursor can be in before it is simply a new statement:
+   * inside a call's brackets, or after a matcher word.
+   */
+  private fallback(range: Range, document: LangiumDocument, offset: number): CompletionItem[] {
+    return (
+      this.inBrackets(range, document, offset) ??
+      this.afterBareCall(range, document, offset) ??
+      this.afterMatcher(range, document, offset) ??
+      this.opening(range, document, offset)
+    );
+  }
+
+  /**
+   * A fresh statement: the names already bound, then the words that open one.
+   *
+   * Calling a function is itself a statement, so bound names belong here. They
+   * come first because the language's own vocabulary is always available.
+   */
+  private opening(range: Range, document: LangiumDocument, offset: number): CompletionItem[] {
+    const host = hostAt({ document, offset, types: this.types.of(document), prefer: "before" });
+    const bound = host ? boundItems(this.scopeNames(host, offset, document), range) : [];
+    return [...bound, ...openingItems(this.catalog, range)];
+  }
+
+  /**
+   * `const r = http.get "u" ▮`: a bracket-less call bound to a name.
+   *
+   * The `argument` context reads the head of the line, which here is `const`
+   * rather than the verb. Same words deserve the same help, so it is caught
+   * separately.
+   */
+  private afterBareCall(
+    range: Range,
+    document: LangiumDocument,
+    offset: number,
+  ): CompletionItem[] | undefined {
+    const call = enclosingBareCall(document, offset);
+    const shape = call && callShape(call.target, this.catalog);
+    if (!call || !shape) return undefined;
+    return this.dueAt({
+      active: activeArg(call, offset),
+      shape,
+      host: call.node,
+      range,
+      document,
+      at: offset,
+    });
+  }
+
+  /** What may go in this position: a value, or the options map that ends the call. */
+  private dueAt(args: {
+    active: number;
+    shape: CallShape;
+    host: AstNode;
+    range: Range;
+    document: LangiumDocument;
+    at: number;
+  }): CompletionItem[] {
+    const { active, shape } = args;
+    if (active >= shape.args.length && shape.options.length > 0) {
+      return optionsMapItems(shape.options, args.range);
+    }
+    return this.valuesFor({ ...args, expects: shape.args[active] });
+  }
+
+  /** `expect res contains ▮`: the value the check is waiting for. */
+  private afterMatcher(
+    range: Range,
+    document: LangiumDocument,
+    offset: number,
+  ): CompletionItem[] | undefined {
+    const clause = enclosingMatcher(document, offset);
+    if (!clause) return undefined;
+    const shape = matcherShape(clause.name, this.catalog);
+    const expects = shape?.args[activeArg(clause, offset)];
+    return this.valuesFor({ host: clause, expects, range, document, at: offset });
+  }
+
+  /**
+   * `saudacao(▮)`, `fmt.json(x, ▮)`: inside a bracketed call.
+   *
+   * Reached last, before offering a fresh statement. Everything more specific
+   * (a dot, an options key, a bare argument) has already had its turn, so what
+   * is left inside brackets is a value.
+   */
+  private inBrackets(
+    range: Range,
+    document: LangiumDocument,
+    offset: number,
+  ): CompletionItem[] | undefined {
+    const found = enclosingParenCall(document, offset);
+    if (!found?.host) return undefined;
+    const shape = shapeAt({ ...found, document, catalog: this.catalog, types: this.types });
+    if (!shape)
+      return this.valuesFor({ host: found.host, expects: undefined, range, document, at: offset });
+    return this.dueAt({
+      active: found.active,
+      shape,
+      host: found.host,
+      range,
+      document,
+      at: offset,
+    });
+  }
+
+  /**
+   * `http.on ▮`: what the program already holds, before what the stdlib offers.
+   * A name the text took for a verb but the language does not know is not an
+   * argument position at all, so that falls back to a fresh statement.
+   */
+  private argument(
+    context: { target: string; from: number },
+    range: Range,
+    document: LangiumDocument,
+    offset: number,
+  ): CompletionItem[] {
+    const shape = callShape(context.target, this.catalog);
+    const call = enclosingCall(document, offset);
+    // The text took the head of the line for a verb and the language disagrees:
+    // `const t = saudacao(▮)` reads that way and is a bracketed call.
+    if (!shape || !call) {
+      return this.fallback(range, document, offset);
+    }
+    const expects = shape.args[activeArg(call, offset)];
+    return this.valuesFor({ host: call, expects, range, document, at: offset });
+  }
+
+  /** What the program holds that could go here, the fitting ones first. */
+  private valuesFor(args: {
+    host: AstNode;
+    expects: ShownArg | undefined;
+    range: Range;
+    document: LangiumDocument;
+    at: number;
+  }): CompletionItem[] {
+    return argumentItems({
+      names: this.scopeNames(args.host, args.at, args.document),
+      types: this.types.of(args.document).types,
+      expects: args.expects,
+      catalog: this.catalog,
+      range: args.range,
+    });
+  }
+
+  // The built-ins, the `deco`s this file declares, and the `pub deco`s it imported.
+  private async decorators(document: LangiumDocument, range: Range): Promise<CompletionItem[]> {
+    const scope = { document, documents: this.documents, imports: this.imports };
+    return annotationItems(await decosInScope(scope), range);
+  }
+
+  private paths(partial: string, range: Range, document: LangiumDocument): CompletionItem[] {
+    const paths = modulePaths({ partial, base: document.uri, imports: this.imports });
+    return pathItems(paths, range);
+  }
+
+  // Only what the imported module marks `pub` may be named inside `import { … }`.
+  private async exports(
+    path: string | undefined,
+    range: Range,
+    document: LangiumDocument,
+  ): Promise<CompletionItem[]> {
+    if (!path) return [];
+    const uri = this.imports.resolve(path, document.uri);
+    const target = await this.documents.getOrCreateDocument(uri).catch(() => undefined);
+    const root = target?.parseResult?.value as Document | undefined;
+    return root ? exportItems(exportedNames(root), range) : [];
+  }
+}
+
+function rangeOf(context: CompletionContext, position: Position): Range {
+  return { start: { line: position.line, character: context.from }, end: position };
+}
+
+function rootOf(document: LangiumDocument): Document | undefined {
+  return document.parseResult?.value as Document | undefined;
+}
+
+function lineAt(document: LangiumDocument, position: Position): string {
+  const text = document.textDocument.getText();
+  const start = document.textDocument.offsetAt({ line: position.line, character: 0 });
+  const end = text.indexOf("\n", start);
+  return text.slice(start, end < 0 ? text.length : end);
+}
+
+/** The namespaces this file brought in; a type it cannot name is not offered. */
+function namespacesUsed(root: Document, catalog: SymbolCatalog): string[] {
+  const names: string[] = [];
+  for (const decl of root.imports) {
+    if (!isUseDecl(decl)) continue;
+    const namespace = decl.alias ?? catalog.namespaceOfPackage(decl.pkg);
+    if (namespace) names.push(namespace);
+  }
+  return names;
+}

package/src/completion/completion.types.ts

@@ -0,0 +1,38 @@
+/**
+ * Where the cursor sits, and from which character the completion should
+ * replace. Without that range VS Code falls back to its own word rules, which
+ * break on `@` and `/`: accepting `@venn-lang/http` inside `"@venn-lang/"` would paste
+ * the prefix twice.
+ */
+export type CompletionContext =
+  | { kind: "package"; from: number }
+  | { kind: "modulePath"; from: number; partial: string }
+  | { kind: "importName"; from: number; path?: string }
+  /** After a dot. `receiver` is the whole path before it: a namespace or a value. */
+  | { kind: "action"; from: number; receiver: string }
+  /** After a dot whose receiver is not a name: the AST node has to answer. */
+  | { kind: "member"; from: number }
+  | { kind: "annotation"; from: number }
+  | { kind: "fragment"; from: number }
+  | { kind: "matcher"; from: number }
+  /** Inside the `{ … }` of a call; `target` is the action whose keys to offer. */
+  | { kind: "optionKey"; from: number; target: string }
+  /**
+   * After a verb and a space: `http.on ▮`. Whether `target` really is a verb is
+   * not a question text can answer, so the provider checks and falls back to a
+   * plain statement when nothing in the language answers to that name.
+   */
+  | { kind: "argument"; from: number; target: string }
+  /** Where a type goes: after the `:` of a field, a parameter or a binding. */
+  | { kind: "typeName"; from: number }
+  | { kind: "statement"; from: number };
+
+/** The text the classifier reads: the current line, and everything before the cursor. */
+export interface CursorText {
+  /** The current line up to the cursor; `from` is a column on this line. */
+  prefix: string;
+  /** The whole current line. */
+  line: string;
+  /** The whole document up to the cursor; an options map spans lines. */
+  before: string;
+}

package/src/completion/context.ts

@@ -0,0 +1,144 @@
+import type { CompletionContext, CursorText } from "./completion.types.js";
+
+const PACKAGE = /\buse\s+"([^"]*)$/;
+const MODULE_PATH = /\bfrom\s+"([^"]*)$/;
+const IMPORT_NAME = /\bimport\s*\{([^}]*)$/;
+/**
+ * The whole dotted receiver, so `cfg.server.` offers what `cfg.server` holds.
+ *
+ * The lookbehind makes the match start at a token boundary. Without it the
+ * receiver could be found inside something else: `_` opens an identifier, so
+ * `1_000_000.` would take `_000_000` for its receiver and offer nothing.
+ */
+const ACTION = /(?<![\w.])([A-Za-z_]\w*(?:\.\w+)*)\.(\w*)$/;
+const ANNOTATION = /@(\w*)$/;
+const FRAGMENT = /\brun\s+(\w*)$/;
+const MATCHER = /\bexpect\b\s+\S+\s+(\w*)$/;
+const WORD = /(\w*)$/;
+/**
+ * Where a type goes: after the `:` of a field, a parameter or a binding, after
+ * the `->` of a declared return, or after the `|` of a union.
+ *
+ * A name has to sit before the colon, which is what tells a type annotation
+ * from a map entry: `{ port: ▮ }` holds a value, `port: ▮` in a `type` block
+ * holds a type. The brace is the difference, and the caller has already
+ * classified an open one.
+ */
+const TYPE_POSITION = /(?:^|[^:])(?::|->|\|)\s*([A-Za-z_][\w.]*)?$/;
+/**
+ * A verb, a space, and whatever is being written after it: `http.on ▮`,
+ * `http.on api ▮`, `print ▮`. The leading anchor keeps this to the head of a
+ * statement, so `1 + ▮` and the tail of an expression are not swept in.
+ */
+const ARGUMENT = /^\s*([A-Za-z_]\w*(?:\.\w+)*)\s+[^{}]*?(\w*)$/;
+const FROM_PATH = /\bfrom\s+"([^"]+)"/;
+/**
+ * A dot whose receiver no path can name: `1234.567.round`, `f(x).len`,
+ * `xs[0].name`, `"ab".upper`. Tried after {@link ACTION}, so a receiver that is
+ * a name goes there first and this catches the rest: a digit, a closing
+ * bracket, a quote. There is nothing to look up by text, so the node under the
+ * cursor answers instead.
+ */
+const MEMBER = /[\w)\]"']\.(\w*)$/;
+
+/** The dotted path that owns the `{` we are inside of, with no brace between. */
+const OPTION_OWNER = /([A-Za-z_]\w*(?:\.\w+)+)[^{}]*$/;
+
+/**
+ * Classify the cursor from the text before it. String contexts are tested first:
+ * a module path like `#shared/auth.vn` also looks like `namespace.action`.
+ *
+ * @param text The line, the prefix up to the cursor and the document before it.
+ * @returns The narrowest context that matches, or `statement` when none does.
+ */
+export function contextAt(text: CursorText): CompletionContext {
+  const { prefix, line } = text;
+  const inString = stringContext(prefix, line);
+  if (inString) return inString;
+  const action = ACTION.exec(prefix);
+  if (action?.[1]) return { kind: "action", receiver: action[1], from: back(prefix, action[2]) };
+  const member = MEMBER.exec(prefix);
+  if (member) return { kind: "member", from: back(prefix, member[1]) };
+  const annotation = ANNOTATION.exec(prefix);
+  if (annotation) return { kind: "annotation", from: back(prefix, annotation[1]) };
+  const fragment = FRAGMENT.exec(prefix);
+  if (fragment) return { kind: "fragment", from: back(prefix, fragment[1]) };
+  const matcher = MATCHER.exec(prefix);
+  if (matcher) return { kind: "matcher", from: back(prefix, matcher[1]) };
+  return (
+    optionContext(text) ??
+    typeContext(text) ??
+    argumentContext(prefix) ?? { kind: "statement", from: back(prefix, WORD.exec(prefix)?.[1]) }
+  );
+}
+
+/**
+ * `id: ▮`: a type is due.
+ *
+ * Only outside an options map, which the caller has already ruled out: inside
+ * `{ … }` a colon introduces a value, and the two look identical to a regex.
+ */
+function typeContext(text: CursorText): CompletionContext | undefined {
+  const found = TYPE_POSITION.exec(text.prefix);
+  if (!found) return undefined;
+  return { kind: "typeName", from: back(text.prefix, found[1]) };
+}
+
+/** `http.on ▮`: the head of the line is a verb, and an argument is due. */
+function argumentContext(prefix: string): CompletionContext | undefined {
+  const found = ARGUMENT.exec(prefix);
+  if (!found?.[1]) return undefined;
+  return { kind: "argument", target: found[1], from: back(prefix, found[2]) };
+}
+
+/**
+ * `http.post url { … }`: offer the keys that call accepts. Only the map that
+ * belongs to the call qualifies: a nested `{ … }` has a shape of its own that
+ * the schema does not describe, so nothing is offered there rather than
+ * something wrong.
+ */
+function optionContext(text: CursorText): CompletionContext | undefined {
+  const open = innermostOpenBrace(text.before);
+  if (open < 0) return undefined;
+  const target = OPTION_OWNER.exec(text.before.slice(0, open))?.[1];
+  if (!target) return undefined;
+  return { kind: "optionKey", target, from: back(text.prefix, WORD.exec(text.prefix)?.[1]) };
+}
+
+/** The `{` still open at the cursor, scanning backwards. */
+function innermostOpenBrace(before: string): number {
+  let depth = 0;
+  for (let index = before.length - 1; index >= 0; index -= 1) {
+    if (before[index] === "}") depth += 1;
+    else if (before[index] === "{") {
+      if (depth === 0) return index;
+      depth -= 1;
+    }
+  }
+  return -1;
+}
+
+function stringContext(prefix: string, line: string): CompletionContext | undefined {
+  const pkg = PACKAGE.exec(prefix);
+  if (pkg) return { kind: "package", from: back(prefix, pkg[1]) };
+  const path = MODULE_PATH.exec(prefix);
+  if (path) return { kind: "modulePath", from: back(prefix, path[1]), partial: path[1] ?? "" };
+  const named = IMPORT_NAME.exec(prefix);
+  if (named)
+    return { kind: "importName", from: back(prefix, lastName(named[1])), path: pathOf(line) };
+  return undefined;
+}
+
+// The name being typed inside `{ a, b| }`: everything after the last comma.
+function lastName(inside: string | undefined): string {
+  const tail = (inside ?? "").split(",").pop() ?? "";
+  return tail.trimStart();
+}
+
+function pathOf(line: string): string | undefined {
+  return FROM_PATH.exec(line)?.[1];
+}
+
+function back(prefix: string, partial: string | undefined): number {
+  return prefix.length - (partial?.length ?? 0);
+}

package/src/completion/icons.ts

@@ -0,0 +1,83 @@
+import { CompletionItemKind } from "vscode-languageserver";
+
+/**
+ * One icon per kind of thing, decided in one place so the item builders cannot
+ * disagree about what a published type or a bound name looks like.
+ *
+ * The rule the icons follow is what the reader is about to write: a `Method`
+ * needs brackets, a `Property` is computed and read bare, a `Field` is data
+ * sitting there. Everything else names the sort of declaration it came from.
+ */
+export interface IconTable {
+  readonly constant: CompletionItemKind;
+  readonly variable: CompletionItemKind;
+  readonly callable: CompletionItemKind;
+  readonly fragment: CompletionItemKind;
+  readonly verb: CompletionItemKind;
+  readonly matcher: CompletionItemKind;
+  readonly decorator: CompletionItemKind;
+  readonly namespace: CompletionItemKind;
+  readonly type: CompletionItemKind;
+  readonly builtinType: CompletionItemKind;
+  readonly key: CompletionItemKind;
+  readonly computed: CompletionItemKind;
+  readonly method: CompletionItemKind;
+  readonly env: CompletionItemKind;
+  readonly path: CompletionItemKind;
+  readonly keyword: CompletionItemKind;
+}
+
+export const ICON: IconTable = {
+  /** `const x = …`: bound once, never reassigned. */
+  constant: CompletionItemKind.Constant,
+  /** `let x = …`, a parameter, a loop variable. */
+  variable: CompletionItemKind.Variable,
+  /** A `fn`: called for a value, in an expression. */
+  callable: CompletionItemKind.Function,
+  /**
+   * A `fragment`: a named piece of a flow, invoked with `run`.
+   *
+   * Deliberately not the icon a function carries. A function gives back a
+   * value; a fragment gives back steps that the report records and that can
+   * fail. The icon has to separate them while the reader is still choosing.
+   */
+  fragment: CompletionItemKind.Snippet,
+  /** A verb a plugin contributes: `http.get`. */
+  verb: CompletionItemKind.Function,
+  /** A word usable after `expect`: `contains`, `oneOf`. */
+  matcher: CompletionItemKind.Function,
+  /** A `deco`, applied with `@`. */
+  decorator: CompletionItemKind.Function,
+  /** A plugin namespace, or a package to `use`. */
+  namespace: CompletionItemKind.Module,
+  /** A type: declared here, published by a package, or a `type` alias. */
+  type: CompletionItemKind.Struct,
+  /** One of the language's own types: `string`, `duration`. */
+  builtinType: CompletionItemKind.Keyword,
+  /** A key of a map someone writes: an option, a field of a record. */
+  key: CompletionItemKind.Field,
+  /** Read bare, computed each time: `xs.len`, `m.keys`. */
+  computed: CompletionItemKind.Property,
+  /** Called with brackets: `m.get(k)`, `xs.map(f)`. */
+  method: CompletionItemKind.Method,
+  /** A variable the manifest declares. */
+  env: CompletionItemKind.Constant,
+  /** A file path, offered inside an import string. */
+  path: CompletionItemKind.File,
+  /** A keyword of the language: `step`, `forEach`. */
+  keyword: CompletionItemKind.Keyword,
+};
+
+/**
+ * The icon for a name the program bound, from how it was bound.
+ *
+ * `origin` is what {@link ScopedName} recorded when the name was found, so the
+ * editor draws a `const` apart from a `let` apart from a `fn` without anyone
+ * having to look the declaration up a second time.
+ */
+export function iconForOrigin(origin: string): CompletionItemKind {
+  if (origin === "const" || origin === "dataset") return ICON.constant;
+  if (origin === "fragment") return ICON.fragment;
+  if (origin === "fn" || origin === "deco") return ICON.callable;
+  return ICON.variable;
+}

package/src/completion/index.ts

@@ -0,0 +1,4 @@
+export { VennCompletionProvider } from "./completion.js";
+export type { CompletionContext } from "./completion.types.js";
+export { contextAt } from "./context.js";
+export { modulePaths } from "./module-paths.js";