@venn-lang/lsp 0.1.0

package/src/document/host-at.ts

@@ -0,0 +1,61 @@
+import { type AstNode, EXPRESSION_OFFSET } from "@venn-lang/core";
+import { type CstNode, CstUtils, type LangiumDocument, type LeafCstNode } from "langium";
+import { slotAt } from "./interpolation-at.js";
+
+/** The slots a document's inference recorded, keyed by string literal. */
+export interface SlotSource {
+  slots: ReadonlyMap<AstNode, readonly (AstNode | undefined)[]>;
+}
+
+/**
+ * The node a name at this offset should be resolved against.
+ *
+ * Usually that is simply the node under the cursor. Inside `"${…}"` it is not:
+ * the document's tree stops at the string, so a lambda parameter written in
+ * there exists only in the expression inference parsed. This reaches that one,
+ * which is what makes `p` in `"${xs.map(fn (p) => p.name)}"` resolve at all.
+ */
+export function hostAt(args: HostArgs): AstNode | undefined {
+  return inInterpolation(args) ?? nodeAt(args);
+}
+
+export interface HostArgs {
+  document: LangiumDocument;
+  offset: number;
+  types: SlotSource;
+  /**
+   * Which token answers. Hover asks about the one under the cursor; completion
+   * about the one that *ends* at it, since `p.` is typed before it is asked.
+   */
+  prefer?: "at" | "before";
+}
+
+function inInterpolation(args: HostArgs): AstNode | undefined {
+  const hit = slotAt(args);
+  if (!hit) return undefined;
+  const root = args.types.slots.get(hit.host)?.[hit.index];
+  const cst = root?.$cstNode;
+  return cst && leafNear(cst, hit.inner + EXPRESSION_OFFSET, args.prefer)?.astNode;
+}
+
+function nodeAt(args: HostArgs): AstNode | undefined {
+  const root = args.document.parseResult?.value?.$cstNode;
+  return root ? leafNear(root, args.offset, args.prefer)?.astNode : undefined;
+}
+
+/**
+ * Mid-typing, the cursor often sits past the last token the parser kept (`p.`
+ * at the end of a line), so fall back to the token just before it.
+ */
+function leafNear(
+  root: CstNode,
+  offset: number,
+  prefer?: "at" | "before",
+): LeafCstNode | undefined {
+  // Langium's "before" still returns a token that *starts* at the offset, so
+  // asking for the one that ends at the cursor means asking one back.
+  const where = prefer === "before" ? offset - 1 : offset;
+  return (
+    CstUtils.findLeafNodeAtOffset(root, where) ?? CstUtils.findLeafNodeBeforeOffset(root, where)
+  );
+}

package/src/document/imported-modules.ts

@@ -0,0 +1,91 @@
+import { type Document, isFragmentDecl, isValueImport } from "@venn-lang/core";
+import { type LangiumDocument, type LangiumDocuments, URI } from "langium";
+import type { ImportResolver } from "../workspace/index.js";
+
+export interface ModuleGraphScope {
+  root: Document;
+  uri: URI;
+  documents: LangiumDocuments;
+  imports: ImportResolver;
+}
+
+/** The files an import graph reaches, and how one names another. */
+export interface ModuleGraph {
+  modules: ReadonlyMap<string, Document>;
+  resolve: (from: string, spec: string) => string;
+}
+
+/**
+ * Every module this file reaches, read straight out of the workspace index.
+ *
+ * Synchronous on purpose, for the same reason the decorators are: the checker
+ * runs on every keystroke and cannot await a file load. A neighbour the
+ * workspace has not indexed yet contributes nothing this pass and is picked up
+ * on the next, which is a moment of silence rather than a wrong answer.
+ *
+ * Walked transitively, because a `pub fn` that calls another file has the
+ * signature it really has only once that file has been read too.
+ */
+export function importedModules(scope: ModuleGraphScope): ModuleGraph {
+  const modules = new Map<string, Document>();
+  const resolve = (from: string, spec: string): string =>
+    scope.imports.resolve(spec, URI.parse(from)).toString();
+  walk({ document: scope.root, uri: scope.uri.toString(), modules, resolve, scope });
+  return { modules, resolve };
+}
+
+interface WalkArgs {
+  document: Document;
+  uri: string;
+  modules: Map<string, Document>;
+  resolve: (from: string, spec: string) => string;
+  scope: ModuleGraphScope;
+}
+
+function walk(args: WalkArgs): void {
+  for (const decl of args.document.imports) {
+    if (!isValueImport(decl)) continue;
+    const target = args.resolve(args.uri, decl.path);
+    if (args.modules.has(target)) continue;
+    const root = rootAt(target, args.scope);
+    if (!root) continue;
+    args.modules.set(target, root);
+    walk({ ...args, document: root, uri: target });
+  }
+}
+
+function rootAt(uri: string, scope: ModuleGraphScope): Document | undefined {
+  const document = scope.documents.getDocument(URI.parse(uri));
+  return document && rootOf(document);
+}
+
+function rootOf(document: LangiumDocument): Document | undefined {
+  return document.parseResult?.value as Document | undefined;
+}
+
+/**
+ * Which of the names a file imports are fragments.
+ *
+ * The answer comes from what the neighbouring files declare, never from the
+ * import list alone: `run` accepts only a fragment, and a `pub fn` is not one.
+ */
+export function importedFragments(args: {
+  document: Document;
+  uri: string;
+  graph: ModuleGraph;
+}): Set<string> {
+  const found = new Set<string>();
+  for (const decl of args.document.imports) {
+    if (!isValueImport(decl)) continue;
+    const module = args.graph.modules.get(args.graph.resolve(args.uri, decl.path));
+    if (!module) continue;
+    for (const name of decl.names) {
+      if (declaresFragment(module, name)) found.add(name);
+    }
+  }
+  return found;
+}
+
+function declaresFragment(module: Document, name: string): boolean {
+  return module.decls.some((decl) => isFragmentDecl(decl) && decl.export && decl.name === name);
+}

package/src/document/imported-names.ts

@@ -0,0 +1,15 @@
+import { type Document, isValueImport, type ValueImport } from "@venn-lang/core";
+
+/** The names a document pulls in via `import { a, b } from "…"`. */
+export function importedNames(document: Document): string[] {
+  const names: string[] = [];
+  for (const decl of document.imports) {
+    if (isValueImport(decl)) names.push(...namesOf(decl));
+  }
+  return names;
+}
+
+function namesOf(decl: ValueImport): string[] {
+  if (decl.names.length > 0) return decl.names;
+  return decl.default ? [decl.default] : [];
+}

package/src/document/index.ts

@@ -0,0 +1,19 @@
+export { type ExportedName, exportedNames } from "./exported-names.js";
+export { pathOf, stdlibAction } from "./expression-path.js";
+export { findBinding, findDeclaration, findFragment } from "./find-binding.js";
+export type { HostArgs, SlotSource } from "./host-at.js";
+export { hostAt } from "./host-at.js";
+export {
+  importedFragments,
+  importedModules,
+  type ModuleGraph,
+} from "./imported-modules.js";
+export { importedNames } from "./imported-names.js";
+export type { InterpolationHit, SlotHit } from "./interpolation-at.js";
+export { interpolationAt, slotAt } from "./interpolation-at.js";
+export type { ScopedName } from "./names-in-scope.js";
+export { namesInScope } from "./names-in-scope.js";
+export type { FragmentLocation, ResolveFragmentArgs } from "./resolve-fragment.js";
+export { resolveFragment } from "./resolve-fragment.js";
+export type { ImportedLocation, ResolveImportedArgs } from "./resolve-imported.js";
+export { resolveImported } from "./resolve-imported.js";

package/src/document/interpolation-at.ts

@@ -0,0 +1,134 @@
+import {
+  type AstNode,
+  type InterpolationSlot,
+  isStringLit,
+  scanInterpolations,
+} from "@venn-lang/core";
+import { CstUtils, type LangiumDocument } from "langium";
+
+/** A dotted path of identifiers, e.g. `env.KEYCLOAK_URL`. */
+const PATH = /[A-Za-z_]\w*(?:\.[A-Za-z_]\w*)*/g;
+
+/** What the cursor is pointing at inside a `${…}` placeholder. */
+export interface InterpolationHit {
+  /** The string literal holding the placeholder: the anchor for scope lookup. */
+  host: AstNode;
+  /** The whole dotted path under the cursor. */
+  path: string;
+  /** Just the segment under the cursor. */
+  name: string;
+  /** True on the first segment, the only one a scope can bind. */
+  isHead: boolean;
+  /** Which dotted segment the cursor is on: 0 is the head. */
+  segment: number;
+  /** Absolute offset and length of {@link name}, for ranges the editor needs. */
+  offset: number;
+  length: number;
+  /** Which `${…}` of the string this is: the index inference recorded it under. */
+  slot: number;
+  /** Where the cursor sits inside that placeholder's source. */
+  inner: number;
+}
+
+/**
+ * Resolve an offset that falls inside an interpolated string. Without this the
+ * editor treats `"${base}/users"` as prose: no hover, no jump, no rename.
+ */
+export function interpolationAt(args: {
+  document: LangiumDocument;
+  offset: number;
+}): InterpolationHit | undefined {
+  const found = slotAt(args);
+  if (!found) return undefined;
+  const { host, slot, index, inner } = found;
+  const hit = hitIn({ host, slot, at: inner, base: found.base });
+  return hit && { ...hit, slot: index, inner };
+}
+
+/** Which `${…}` the offset falls in, whether or not a name sits under it. */
+export interface SlotHit {
+  host: AstNode;
+  slot: InterpolationSlot;
+  /** The placeholder's position among the string's, as inference recorded it. */
+  index: number;
+  /** Where the cursor sits inside the placeholder's source. */
+  inner: number;
+  /** Absolute offset of the placeholder's source, for ranges the editor needs. */
+  base: number;
+}
+
+/**
+ * Locate the placeholder alone. Completion asks this after a dot, where there
+ * is no name yet and {@link interpolationAt} would find nothing to describe.
+ */
+export function slotAt(args: { document: LangiumDocument; offset: number }): SlotHit | undefined {
+  const host = stringAt(args);
+  const cst = host?.$cstNode;
+  if (!host || !cst) return undefined;
+  const local = args.offset - cst.offset;
+  const slots = scanInterpolations(cst.text);
+  const index = slots.findIndex((each) => inside(each, local));
+  const slot = slots[index];
+  if (!slot) return undefined;
+  return {
+    host,
+    slot,
+    index,
+    inner: local - slot.sourceStart,
+    base: cst.offset + slot.sourceStart,
+  };
+}
+
+/** A hit before the placeholder it came from is known. */
+type Located = Omit<InterpolationHit, "slot" | "inner">;
+
+function inside(slot: InterpolationSlot, offset: number): boolean {
+  return offset > slot.start && offset < slot.end;
+}
+
+function stringAt(args: { document: LangiumDocument; offset: number }): AstNode | undefined {
+  const root = args.document.parseResult?.value?.$cstNode;
+  const leaf = root && CstUtils.findLeafNodeAtOffset(root, args.offset);
+  const node = leaf?.astNode;
+  return node && isStringLit(node) ? node : undefined;
+}
+
+function hitIn(args: {
+  host: AstNode;
+  slot: InterpolationSlot;
+  at: number;
+  base: number;
+}): Located | undefined {
+  for (const match of args.slot.source.matchAll(PATH)) {
+    const start = match.index;
+    if (args.at < start || args.at > start + match[0].length) continue;
+    return segmentAt({
+      host: args.host,
+      path: match[0],
+      base: args.base + start,
+      at: args.at - start,
+    });
+  }
+  return undefined;
+}
+
+/** Which dotted segment the cursor landed on, and where it sits in the document. */
+function segmentAt(args: { host: AstNode; path: string; base: number; at: number }): Located {
+  const parts = args.path.split(".");
+  let cursor = 0;
+  let index = 0;
+  while (index < parts.length - 1 && args.at > cursor + (parts[index]?.length ?? 0)) {
+    cursor += (parts[index]?.length ?? 0) + 1;
+    index += 1;
+  }
+  const name = parts[index] ?? args.path;
+  return {
+    host: args.host,
+    path: args.path,
+    name,
+    isHead: index === 0,
+    segment: index,
+    offset: args.base + cursor,
+    length: name.length,
+  };
+}

package/src/document/names-in-scope.ts

@@ -0,0 +1,126 @@
+import {
+  type AstNode,
+  type Block,
+  type Document,
+  isBlock,
+  isCaptureStmt,
+  isDatasetDecl,
+  isDecoDecl,
+  isDocument,
+  isFnBody,
+  isFnDecl,
+  isFnExpr,
+  isForEachStmt,
+  isFragmentDecl,
+  isLetStmt,
+  isRepeatStmt,
+  isValueImport,
+  type ParamList,
+} from "@venn-lang/core";
+
+/** A name the program has bound, and the node that bound it. */
+export interface ScopedName {
+  name: string;
+  node: AstNode;
+  /** How it came to be here: `const`, `parameter`, `fragment`, `resource`. */
+  origin: string;
+}
+
+/**
+ * Every name visible from `from`, innermost first.
+ *
+ * The mirror of `findBinding`, which answers about one name at a time. Asking
+ * the other way round is what lets the editor offer what is actually there:
+ * `http.on ` suggests the server two lines up, not every namespace loaded.
+ */
+export function namesInScope(from: AstNode, at?: number): ScopedName[] {
+  const found: ScopedName[] = [];
+  const seen = new Set<string>();
+  let node: AstNode | undefined = from;
+  while (node) {
+    for (const each of bindingsIn(node)) {
+      if (seen.has(each.name) || beingWritten(each, at)) continue;
+      seen.add(each.name);
+      found.push(each);
+    }
+    node = node.$container;
+  }
+  return found;
+}
+
+/**
+ * Whether the cursor is inside what this binding is being given.
+ *
+ * `const t = saudacao(▮)` must not offer `t`: nothing holds it yet, and
+ * accepting it would write a definition in terms of itself.
+ */
+function beingWritten(scoped: ScopedName, at: number | undefined): boolean {
+  if (at === undefined) return false;
+  const value = (isLetStmt(scoped.node) || isDatasetDecl(scoped.node)) && scoped.node.value;
+  const cst = value ? value.$cstNode : undefined;
+  return Boolean(cst && at >= cst.offset && at <= cst.end);
+}
+
+function bindingsIn(node: AstNode): ScopedName[] {
+  if (isForEachStmt(node)) return [{ name: node.item, node, origin: "each" }];
+  if (isRepeatStmt(node)) return node.index ? [{ name: node.index, node, origin: "index" }] : [];
+  if (isFragmentDecl(node) || isFnDecl(node) || isFnExpr(node) || isDecoDecl(node))
+    return params(node.params);
+  if (isFnBody(node)) return node.locals.map((local) => named(local, local.name, "let"));
+  if (isBlock(node)) return blockNames(node);
+  if (isDocument(node)) return documentNames(node);
+  return [];
+}
+
+function blockNames(block: Block): ScopedName[] {
+  return block.stmts
+    .filter((stmt) => isLetStmt(stmt) || isCaptureStmt(stmt))
+    .map((stmt) => named(stmt, (stmt as { name: string }).name, kindOf(stmt)));
+}
+
+function documentNames(document: Document): ScopedName[] {
+  const declared = document.decls.filter(declares).map((decl) => {
+    const name = (decl as unknown as { name: string }).name;
+    return named(decl, name, kindOf(decl));
+  });
+  return [...declared, ...importedInto(document)];
+}
+
+/**
+ * The names this file pulled in from another.
+ *
+ * An imported name is bound as firmly as a local one: it can be called, passed
+ * and held, so it belongs in scope like any other.
+ */
+function importedInto(document: Document): ScopedName[] {
+  const found: ScopedName[] = [];
+  for (const decl of document.imports) {
+    if (!isValueImport(decl)) continue;
+    const names = decl.wildcard ? [decl.wildcard] : decl.names;
+    for (const name of names) found.push(named(decl, name, "import"));
+  }
+  return found;
+}
+
+/**
+ * A `fn` counts: it is a value the file bound, and passing one by name is how
+ * `http.on(api, route)` is written.
+ */
+function declares(decl: AstNode): boolean {
+  return isLetStmt(decl) || isDatasetDecl(decl) || isFragmentDecl(decl) || isFnDecl(decl);
+}
+
+function kindOf(node: AstNode): string {
+  if (isLetStmt(node)) return node.kind;
+  if (isDatasetDecl(node)) return "dataset";
+  if (isFragmentDecl(node)) return "fragment";
+  return isFnDecl(node) ? "fn" : "let";
+}
+
+function params(list: ParamList | undefined): ScopedName[] {
+  return (list?.params ?? []).map((param) => named(param, param.name, "parameter"));
+}
+
+function named(node: AstNode, name: string, origin: string): ScopedName {
+  return { name, node, origin };
+}

package/src/document/resolve-fragment.ts

@@ -0,0 +1,38 @@
+import { type Document, type FragmentDecl, isValueImport } from "@venn-lang/core";
+import type { LangiumDocument, LangiumDocuments, URI } from "langium";
+import type { ImportResolver } from "../workspace/index.js";
+import { findFragment } from "./find-binding.js";
+
+/** Where a fragment lives. `decl` is absent when the file could not be read. */
+export interface FragmentLocation {
+  uri: URI;
+  decl?: FragmentDecl;
+  document?: LangiumDocument;
+}
+
+export interface ResolveFragmentArgs {
+  name: string;
+  document: LangiumDocument;
+  documents: LangiumDocuments;
+  imports: ImportResolver;
+}
+
+/** Find a fragment: declared in this file, or followed through the `import` naming it. */
+export async function resolveFragment(
+  args: ResolveFragmentArgs,
+): Promise<FragmentLocation | undefined> {
+  const root = args.document.parseResult?.value as Document | undefined;
+  if (!root) return undefined;
+  const local = findFragment(root, args.name);
+  if (local) return { uri: args.document.uri, decl: local, document: args.document };
+  const decl = root.imports.find((node) => isValueImport(node) && node.names.includes(args.name));
+  return isValueImport(decl) ? fromImport(decl.path, args) : undefined;
+}
+
+async function fromImport(path: string, args: ResolveFragmentArgs): Promise<FragmentLocation> {
+  const uri = args.imports.resolve(path, args.document.uri);
+  const document = await args.documents.getOrCreateDocument(uri).catch(() => undefined);
+  const root = document?.parseResult?.value as Document | undefined;
+  const decl = root ? findFragment(root, args.name) : undefined;
+  return { uri, decl, document };
+}

package/src/document/resolve-imported.ts

@@ -0,0 +1,35 @@
+import type { AstNode, Document, ValueImport } from "@venn-lang/core";
+import type { LangiumDocument, LangiumDocuments, URI } from "langium";
+import type { ImportResolver } from "../workspace/index.js";
+import { findDeclaration } from "./find-binding.js";
+
+/** Where an imported name was declared. `decl` is absent when the file cannot be read. */
+export interface ImportedLocation {
+  uri: URI;
+  decl?: AstNode;
+  document?: LangiumDocument;
+}
+
+export interface ResolveImportedArgs {
+  name: string;
+  /** The `import { … } from "…"` that names it. */
+  decl: ValueImport;
+  document: LangiumDocument;
+  documents: LangiumDocuments;
+  imports: ImportResolver;
+}
+
+/**
+ * Follow a name in an `import` list back to whatever declares it.
+ *
+ * Unlike `resolveFragment`, this does not care what kind of thing it finds: an
+ * import list holds `pub fn`, `pub fragment`, `pub deco` and `pub const` side
+ * by side with nothing distinguishing them, so the name is all there is to go
+ * on until the other file is read.
+ */
+export async function resolveImported(args: ResolveImportedArgs): Promise<ImportedLocation> {
+  const uri = args.imports.resolve(args.decl.path, args.document.uri);
+  const document = await args.documents.getOrCreateDocument(uri).catch(() => undefined);
+  const root = document?.parseResult?.value as Document | undefined;
+  return { uri, decl: root ? findDeclaration(root, args.name) : undefined, document };
+}

package/src/effects/index.ts

@@ -0,0 +1 @@
+export { waitingFns } from "./waiting-fns.js";

package/src/effects/waiting-fns.ts

@@ -0,0 +1,83 @@
+import {
+  type AstNode,
+  type Document,
+  type FnDecl,
+  isCall,
+  isFnDecl,
+  isMember,
+  isRef,
+} from "@venn-lang/core";
+import { AstUtils } from "langium";
+import type { SymbolCatalog } from "../catalog/index.js";
+
+/**
+ * Which functions in a file wait for something.
+ *
+ * A plugin verb runs asynchronously, so anything that reaches for one hands
+ * back a value still arriving, and so does anything that calls that. The
+ * runtime does the waiting without a word being written; this is what lets the
+ * hover say so.
+ *
+ * It lives here rather than in the checker because deciding whether a dotted
+ * path names a verb needs the plugin registry, and `@venn-lang/core` deliberately
+ * knows nothing about plugins. Being an editor's answer, it may be approximate:
+ * missing one costs a hint, never a wrong program.
+ */
+export function waitingFns(document: Document, catalog: SymbolCatalog): ReadonlySet<string> {
+  const bodies = declaredFns(document);
+  const waiting = new Set<string>();
+  for (const [name, decl] of bodies) {
+    if (callsAVerb(decl, catalog)) waiting.add(name);
+  }
+  spread(bodies, waiting);
+  return waiting;
+}
+
+function declaredFns(document: Document): Map<string, FnDecl> {
+  const out = new Map<string, FnDecl>();
+  for (const decl of document.decls) {
+    if (isFnDecl(decl)) out.set(decl.name, decl);
+  }
+  return out;
+}
+
+/** A verb somewhere in the body, whether named or called. */
+function callsAVerb(decl: FnDecl, catalog: SymbolCatalog): boolean {
+  for (const node of AstUtils.streamAst(decl.body)) {
+    const head = pathHead(node);
+    if (head && catalog.hasNamespace(head)) return true;
+  }
+  return false;
+}
+
+/**
+ * Then outwards, until nothing new is found: a function that calls one that
+ * waits, waits. Bounded by the number of functions, so it always settles.
+ */
+function spread(bodies: Map<string, FnDecl>, waiting: Set<string>): void {
+  for (let pass = 0; pass < bodies.size; pass += 1) {
+    let grew = false;
+    for (const [name, decl] of bodies) {
+      if (waiting.has(name)) continue;
+      if (!callsAnyOf(decl, waiting)) continue;
+      waiting.add(name);
+      grew = true;
+    }
+    if (!grew) return;
+  }
+}
+
+function callsAnyOf(decl: FnDecl, names: ReadonlySet<string>): boolean {
+  for (const node of AstUtils.streamAst(decl.body)) {
+    if (isCall(node) && isRef(node.callee) && names.has(node.callee.name)) return true;
+  }
+  return false;
+}
+
+/** The first name of a dotted path: `http` in `http.get`, `fmt` in `fmt.json`. */
+function pathHead(node: AstNode): string | undefined {
+  if (!isMember(node)) return undefined;
+  let receiver = node.receiver;
+  while (isMember(receiver)) receiver = receiver.receiver;
+  return isRef(receiver) ? receiver.name : undefined;
+}