@venn-lang/lsp 0.1.0

package/src/deco/declared-deco.ts

@@ -0,0 +1,56 @@
+import {
+  type DecoDecl,
+  type Document,
+  isDecoDecl,
+  isNamedType,
+  type Param,
+  type SingleType,
+  type TypeRef,
+} from "@venn-lang/core";
+import type { LangiumDocument } from "langium";
+import { readDoc, renderDoc } from "../docs/index.js";
+import type { DecoInfo } from "./deco.types.js";
+
+/**
+ * Read a `deco` the way whoever writes `@name` sees it.
+ *
+ * The first parameter is the target, so the type written on it is what the
+ * decorator decorates. Nothing else in the declaration says so, and nothing
+ * outside it can disagree.
+ */
+export function declaredDeco(args: { decl: DecoDecl; document: LangiumDocument }): DecoInfo {
+  const { decl, document } = args;
+  return {
+    name: decl.name,
+    decorates: typeNames(decl.params?.params[0]?.paramType),
+    signature: signatureOf(decl),
+    doc: renderDoc(readDoc(document, decl)),
+    decl,
+    document,
+  };
+}
+
+/** Every `deco` a document declares, in the order it declares them. */
+export function localDecos(root: Document, document: LangiumDocument): DecoInfo[] {
+  return root.decls.filter(isDecoDecl).map((decl) => declaredDeco({ decl, document }));
+}
+
+function signatureOf(decl: DecoDecl): string {
+  const params = (decl.params?.params ?? []).map(paramText).join(", ");
+  return `${decl.export ? "pub " : ""}deco ${decl.name}(${params})`;
+}
+
+function paramText(param: Param): string {
+  const type = typeNames(param.paramType).join(" | ");
+  return type ? `${param.name}: ${type}` : param.name;
+}
+
+/** Each alternative of a written type: `Fn | Flow` is two kinds, not one. */
+function typeNames(ref: TypeRef | undefined): string[] {
+  return (ref?.members ?? []).map(memberName).filter((name) => name.length > 0);
+}
+
+// The source's own text, so a generic like `list<number>` survives the trip.
+function memberName(member: SingleType): string {
+  return member.$cstNode?.text ?? (isNamedType(member) ? member.name : "");
+}

package/src/deco/deco.types.ts

@@ -0,0 +1,23 @@
+import type { DecoDecl } from "@venn-lang/core";
+import type { LangiumDocument } from "langium";
+
+/**
+ * One decorator a `@name` could mean here: a `deco` some file declares, or one
+ * the language ships with.
+ *
+ * `decorates` is in the language's own words (`Fn`, `Flow`, `Step`), never a
+ * node type. What a decorator applies to is part of its signature, so reading
+ * one costs nobody a lesson in the compiler's vocabulary.
+ */
+export interface DecoInfo {
+  name: string;
+  /** The kinds it may sit on. Empty means it constrains nothing. */
+  decorates: readonly string[];
+  /** The line a hover fences: `pub deco retry(target: Flow, times: number)`. */
+  signature: string;
+  doc?: string;
+  /** The declaration, when a `.vn` declares it: where go-to-definition lands. */
+  decl?: DecoDecl;
+  /** The document holding {@link decl}. Absent for a built-in. */
+  document?: LangiumDocument;
+}

package/src/deco/decos-in-scope.ts

@@ -0,0 +1,63 @@
+import { type Document, isValueImport, type ValueImport } from "@venn-lang/core";
+import type { LangiumDocument, LangiumDocuments } from "langium";
+import type { ImportResolver } from "../workspace/index.js";
+import { builtinDecos } from "./builtin-decos.js";
+import { localDecos } from "./declared-deco.js";
+import type { DecoInfo } from "./deco.types.js";
+
+/** What a file needs consulted before it can say what `@name` means. */
+export interface DecoScope {
+  document: LangiumDocument;
+  documents: LangiumDocuments;
+  imports: ImportResolver;
+}
+
+/**
+ * Every decorator a `@name` written in this file could mean: the ones the
+ * language ships with, the `pub deco`s it imported, and the `deco`s it declares
+ * itself.
+ *
+ * Later wins, on the same rule the runtime already follows for plugins: the
+ * built-ins are a stdlib, not a reserved word list, so a file that declares its
+ * own `deco retry` means its own.
+ */
+export async function decosInScope(scope: DecoScope): Promise<DecoInfo[]> {
+  const root = rootOf(scope.document);
+  if (!root) return builtinDecos();
+  const imported = await importedDecos(root, scope);
+  return dedupe([...builtinDecos(), ...imported, ...localDecos(root, scope.document)]);
+}
+
+/** The decorator a `@name` resolves to, or nothing when no decorator carries it. */
+export async function decoNamed(name: string, scope: DecoScope): Promise<DecoInfo | undefined> {
+  return (await decosInScope(scope)).find((info) => info.name === name);
+}
+
+async function importedDecos(root: Document, scope: DecoScope): Promise<DecoInfo[]> {
+  const found: DecoInfo[] = [];
+  for (const decl of root.imports) {
+    if (isValueImport(decl)) found.push(...(await fromModule(decl, scope)));
+  }
+  return found;
+}
+
+// Only what the other file marked `pub`, and only the names this one asked for.
+async function fromModule(decl: ValueImport, scope: DecoScope): Promise<DecoInfo[]> {
+  const uri = scope.imports.resolve(decl.path, scope.document.uri);
+  const document = await scope.documents.getOrCreateDocument(uri).catch(() => undefined);
+  const root = document && rootOf(document);
+  if (!document || !root) return [];
+  return localDecos(root, document).filter(
+    (info) => info.decl?.export && decl.names.includes(info.name),
+  );
+}
+
+function dedupe(all: readonly DecoInfo[]): DecoInfo[] {
+  const byName = new Map<string, DecoInfo>();
+  for (const info of all) byName.set(info.name, info);
+  return [...byName.values()];
+}
+
+function rootOf(document: LangiumDocument): Document | undefined {
+  return document.parseResult?.value as Document | undefined;
+}

package/src/deco/imported-decos.ts

@@ -0,0 +1,49 @@
+import { type Document, type ImportedDeco, isDecoDecl, isValueImport } from "@venn-lang/core";
+import type { LangiumDocument, LangiumDocuments, URI } from "langium";
+import type { ImportResolver } from "../workspace/index.js";
+
+/** What is needed to read a neighbour without waiting for it to load. */
+export interface ImportedDecoScope {
+  root: Document;
+  uri: URI;
+  documents: LangiumDocuments;
+  imports: ImportResolver;
+}
+
+/**
+ * The `pub deco`s this file imports, read straight out of the workspace index.
+ *
+ * Synchronous on purpose: 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 by the next build, which is a moment of
+ * silence rather than a wrong answer.
+ */
+export function importedDecos(scope: ImportedDecoScope): Map<string, ImportedDeco> {
+  const found = new Map<string, ImportedDeco>();
+  for (const decl of scope.root.imports) {
+    if (isValueImport(decl)) collect({ scope, spec: decl.path, names: decl.names, found });
+  }
+  return found;
+}
+
+function collect(args: {
+  scope: ImportedDecoScope;
+  spec: string;
+  names: readonly string[];
+  found: Map<string, ImportedDeco>;
+}): void {
+  const uri = args.scope.imports.resolve(args.spec, args.scope.uri);
+  const document = args.scope.documents.getDocument(uri);
+  const root = document && rootOf(document);
+  if (!root) return;
+  // Only what the other file marked `pub`, and only the names this one asked for.
+  for (const decl of root.decls) {
+    if (isDecoDecl(decl) && decl.export && args.names.includes(decl.name)) {
+      args.found.set(decl.name, { decl, uri: uri.toString() });
+    }
+  }
+}
+
+function rootOf(document: LangiumDocument): Document | undefined {
+  return document.parseResult?.value as Document | undefined;
+}

package/src/deco/index.ts

@@ -0,0 +1,9 @@
+export { builtinDecos } from "./builtin-decos.js";
+export { declaredDeco, localDecos } from "./declared-deco.js";
+export type { DecoInfo } from "./deco.types.js";
+export type { DecoScope } from "./decos-in-scope.js";
+export { decoNamed, decosInScope } from "./decos-in-scope.js";
+export type { ImportedDecoScope } from "./imported-decos.js";
+export { importedDecos } from "./imported-decos.js";
+export { kindOf } from "./kind-of.js";
+export { decoHover, decoratesLabel, documentedHover } from "./render-deco.js";

package/src/deco/kind-of.ts

@@ -0,0 +1,15 @@
+/** Where dropping the suffix would be wrong, because the user's word differs. */
+const KINDS: Record<string, string> = {
+  LetStmt: "Binding",
+  CaptureStmt: "Binding",
+};
+
+/**
+ * The user's word for a node type.
+ *
+ * `targets: ["FlowDecl"]` is the compiler talking to itself. A decorator says
+ * it decorates a `Flow`, and that is the only spelling the editor shows.
+ */
+export function kindOf(type: string): string {
+  return KINDS[type] ?? type.replace(/(Decl|Stmt|Expr)$/, "");
+}

package/src/deco/render-deco.ts

@@ -0,0 +1,44 @@
+import { UriUtils } from "langium";
+import { code, fence, rule, sections } from "../markdown/index.js";
+import { decoratorDoc } from "./builtin-docs.js";
+import type { DecoInfo } from "./deco.types.js";
+
+/**
+ * Hover for a decorator: the same text whether the cursor sits on `@memoize`
+ * or on the `deco memoize` that defines it. They are one thing seen twice, so
+ * they read the same.
+ */
+export function decoHover(info: DecoInfo): string {
+  return rule([fence(info.signature), sections([decorates(info), info.doc]), origin(info)]);
+}
+
+/**
+ * A decorator the language documents but no source declares, such as `@load`
+ * until `@venn-lang/load` contributes it. Explaining it beats saying nothing.
+ */
+export function documentedHover(name: string): string | undefined {
+  const doc = decoratorDoc(name);
+  return doc && rule([fence(`@${name}`), doc]);
+}
+
+/** What it decorates, in one phrase: the detail beside a completion item. */
+export function decoratesLabel(decorates: readonly string[]): string {
+  const named = namedKinds(decorates);
+  return named.length > 0 ? named.join(", ") : "anything";
+}
+
+function decorates(info: DecoInfo): string {
+  const named = namedKinds(info.decorates);
+  if (named.length === 0) return "Decorates **anything**.";
+  return `Decorates ${named.map(code).join(", ")}.`;
+}
+
+// `Node` is how a target says "anything", so it names nothing in particular.
+function namedKinds(decorates: readonly string[]): string[] {
+  return decorates.filter((kind) => kind !== "Node");
+}
+
+function origin(info: DecoInfo): string {
+  if (!info.document) return "Built into the language.";
+  return `Declared in ${code(UriUtils.basename(info.document.uri))}`;
+}

package/src/definition/definition.ts

@@ -0,0 +1,93 @@
+import { type AstNode, isAnnotation, isRef, isRunStmt, isValueImport } from "@venn-lang/core";
+import { CstUtils, type LangiumDocument, type LangiumDocuments, type URI } from "langium";
+import type { DefinitionProvider } from "langium/lsp";
+import type { DefinitionParams, LocationLink } from "vscode-languageserver";
+import { decoNamed } from "../deco/index.js";
+import { findBinding, interpolationAt, resolveFragment } from "../document/index.js";
+import type { VennServices } from "../services/lsp.types.js";
+import type { ImportResolver } from "../workspace/index.js";
+
+const ORIGIN = { start: { line: 0, character: 0 }, end: { line: 0, character: 0 } };
+
+/** Ctrl+Click: `run` fragments (local or imported), bindings, and imported files. */
+export class VennDefinitionProvider implements DefinitionProvider {
+  private readonly documents: LangiumDocuments;
+  private readonly imports: ImportResolver;
+
+  constructor(services: VennServices) {
+    this.documents = services.shared.workspace.LangiumDocuments;
+    this.imports = services.imports;
+  }
+
+  async getDefinition(
+    document: LangiumDocument,
+    params: DefinitionParams,
+  ): Promise<LocationLink[] | undefined> {
+    const root = document.parseResult?.value?.$cstNode;
+    if (!root) return undefined;
+    const offset = document.textDocument.offsetAt(params.position);
+    const inString = this.interpolated({ document, offset });
+    if (inString) return [inString];
+    const node = CstUtils.findLeafNodeAtOffset(root, offset)?.astNode;
+    const link = node && (await this.resolve(node, document));
+    return link ? [link] : undefined;
+  }
+
+  /** `"${base}/users"`: the name inside the placeholder is a real reference. */
+  private interpolated(args: {
+    document: LangiumDocument;
+    offset: number;
+  }): LocationLink | undefined {
+    const hit = interpolationAt(args);
+    if (!hit?.isHead) return undefined;
+    return localLink(findBinding(hit.host, hit.name), args.document);
+  }
+
+  private async resolve(
+    node: AstNode,
+    document: LangiumDocument,
+  ): Promise<LocationLink | undefined> {
+    if (isRunStmt(node)) return this.fragment(node.target, document);
+    if (isAnnotation(node)) return this.decorator(node.name, document);
+    if (isRef(node)) return localLink(findBinding(node, node.name), document);
+    if (isValueImport(node)) return fileLink(this.imports.resolve(node.path, document.uri));
+    return undefined;
+  }
+
+  // `@memoize` lands on the `deco memoize` that defines it, here or across an
+  // import. A built-in has no source to land on, so nothing happens.
+  private async decorator(
+    name: string,
+    document: LangiumDocument,
+  ): Promise<LocationLink | undefined> {
+    const scope = { document, documents: this.documents, imports: this.imports };
+    const found = await decoNamed(name, scope);
+    return found?.document ? localLink(found.decl, found.document) : undefined;
+  }
+
+  // Land on the declaration when the file can be read; otherwise open the file.
+  private async fragment(
+    name: string,
+    document: LangiumDocument,
+  ): Promise<LocationLink | undefined> {
+    const location = await resolveFragment({
+      name,
+      document,
+      documents: this.documents,
+      imports: this.imports,
+    });
+    if (!location) return undefined;
+    const precise = location.document && localLink(location.decl, location.document);
+    return precise ?? fileLink(location.uri);
+  }
+}
+
+function localLink(node: AstNode | undefined, document: LangiumDocument): LocationLink | undefined {
+  const range = node?.$cstNode?.range;
+  if (!range) return undefined;
+  return { targetUri: document.uri.toString(), targetRange: range, targetSelectionRange: range };
+}
+
+function fileLink(uri: URI): LocationLink {
+  return { targetUri: uri.toString(), targetRange: ORIGIN, targetSelectionRange: ORIGIN };
+}

package/src/definition/index.ts

@@ -0,0 +1 @@
+export { VennDefinitionProvider } from "./definition.js";

package/src/docs/doc.types.ts

@@ -0,0 +1,17 @@
+/** One documented parameter. */
+export interface DocParam {
+  name: string;
+  text: string;
+}
+
+/**
+ * A parsed documentation block: the `##` lines above a declaration, or its
+ * `@doc("…")` annotation (§08). Summary and every field are markdown.
+ */
+export interface DocBlock {
+  summary: string;
+  params: DocParam[];
+  returns?: string;
+  examples: string[];
+  deprecated?: string;
+}

package/src/docs/index.ts

@@ -0,0 +1,4 @@
+export type { DocBlock, DocParam } from "./doc.types.js";
+export { parseDoc } from "./parse-doc.js";
+export { readDoc } from "./read-doc.js";
+export { renderDoc } from "./render-doc.js";

package/src/docs/parse-doc.ts

@@ -0,0 +1,42 @@
+import type { DocBlock } from "./doc.types.js";
+
+const TAG = /^@(param|returns?|example|deprecated)\b[ \t]*(.*)$/;
+
+interface Section {
+  tag: string;
+  lines: string[];
+}
+
+/** Split doc lines into a summary plus `@param` / `@returns` / `@example` / `@deprecated`. */
+export function parseDoc(lines: readonly string[]): DocBlock {
+  const doc: DocBlock = { summary: "", params: [], examples: [] };
+  const summary: string[] = [];
+  let section: Section | undefined;
+  for (const line of lines) {
+    const match = TAG.exec(line.trim());
+    if (!match) (section ? section.lines : summary).push(line);
+    else {
+      apply(doc, section);
+      section = { tag: match[1] as string, lines: [match[2] ?? ""] };
+    }
+  }
+  apply(doc, section);
+  doc.summary = summary.join("\n").trim();
+  return doc;
+}
+
+function apply(doc: DocBlock, section: Section | undefined): void {
+  if (!section) return;
+  const text = section.lines.join("\n").trim();
+  if (section.tag === "param") doc.params.push(splitParam(text));
+  else if (section.tag === "example") doc.examples.push(text);
+  else if (section.tag === "deprecated") doc.deprecated = text || "This is deprecated.";
+  else doc.returns = text;
+}
+
+// `@param user  The account to log in with.`: the first word is the name.
+function splitParam(text: string): { name: string; text: string } {
+  const space = text.search(/\s/);
+  if (space < 0) return { name: text, text: "" };
+  return { name: text.slice(0, space), text: text.slice(space).trim() };
+}

package/src/docs/read-doc.ts

@@ -0,0 +1,45 @@
+import { type Annotation, type AstNode, isStringLit } from "@venn-lang/core";
+import type { LangiumDocument } from "langium";
+import type { DocBlock } from "./doc.types.js";
+import { parseDoc } from "./parse-doc.js";
+
+const DOC_PREFIX = "##";
+
+/**
+ * The documentation attached to a declaration: a `##` block directly above it,
+ * or its `@doc("…")` annotation (§08). `##` wins when both are present.
+ *
+ * @returns The parsed block, or `undefined` when the declaration has neither.
+ */
+export function readDoc(document: LangiumDocument, node: AstNode): DocBlock | undefined {
+  const lines = docLinesAbove(document, node);
+  if (lines.length > 0) return parseDoc(lines);
+  const annotated = docAnnotation(node);
+  return annotated ? parseDoc(annotated.split("\n")) : undefined;
+}
+
+// Walk back over whole lines while they keep starting with `##`.
+function docLinesAbove(document: LangiumDocument, node: AstNode): string[] {
+  const offset = node.$cstNode?.offset;
+  if (offset === undefined) return [];
+  const before = document.textDocument.getText().slice(0, offset).split("\n");
+  before.pop();
+  const lines: string[] = [];
+  for (let index = before.length - 1; index >= 0; index--) {
+    const text = (before[index] ?? "").trim();
+    if (!text.startsWith(DOC_PREFIX)) break;
+    lines.unshift(strip(text));
+  }
+  return lines;
+}
+
+function strip(line: string): string {
+  return line.slice(DOC_PREFIX.length).replace(/^ /, "");
+}
+
+function docAnnotation(node: AstNode): string | undefined {
+  const annotations = (node as { annotations?: Annotation[] }).annotations ?? [];
+  const doc = annotations.find((annotation) => annotation.name === "doc");
+  const first = doc?.args?.args?.[0]?.value;
+  return first && isStringLit(first) ? first.value : undefined;
+}

package/src/docs/render-doc.ts

@@ -0,0 +1,42 @@
+import { code, fence, labelled, rule, sections } from "../markdown/index.js";
+import type { DocBlock, DocParam } from "./doc.types.js";
+
+/**
+ * Render a doc block. The prose keeps its own paragraph rhythm; the tagged
+ * sections sit below a rule so they read as a distinct band, not as more prose.
+ *
+ * @returns Markdown, or `undefined` when the block has nothing worth showing.
+ */
+export function renderDoc(doc: DocBlock | undefined): string | undefined {
+  if (!doc) return undefined;
+  const prose = sections([deprecatedLine(doc.deprecated), doc.summary || undefined]);
+  const tags = sections([
+    paramsSection(doc.params),
+    returnsLine(doc.returns),
+    examplesSection(doc.examples),
+  ]);
+  return rule([prose || undefined, tags || undefined]) || undefined;
+}
+
+function deprecatedLine(deprecated: string | undefined): string | undefined {
+  return deprecated && `⚠️ **Deprecated** — ${deprecated}`;
+}
+
+function paramsSection(params: readonly DocParam[]): string | undefined {
+  if (params.length === 0) return undefined;
+  const items = params.map((param) => `- ${code(param.name)}${suffix(param.text)}`);
+  return labelled("**Parameters**", items.join("\n"));
+}
+
+function suffix(text: string): string {
+  return text ? ` — ${text}` : "";
+}
+
+function returnsLine(returns: string | undefined): string | undefined {
+  return returns && `**Returns** — ${returns}`;
+}
+
+function examplesSection(examples: readonly string[]): string | undefined {
+  if (examples.length === 0) return undefined;
+  return labelled("**Example**", examples.map((example) => fence(example)).join("\n"));
+}

package/src/document/exported-names.ts

@@ -0,0 +1,30 @@
+import { type AstNode, type Document, isDecoDecl, isFnDecl, isFragmentDecl } from "@venn-lang/core";
+
+/** A name a module publishes, and which kind of thing it is. */
+export interface ExportedName {
+  name: string;
+  /** `fragment`, `fn` or `deco`: what the editor draws it as. */
+  origin: string;
+}
+
+/**
+ * The names a module marks `pub`: everything another file is allowed to import.
+ * A `deco` crosses files like a fragment or a function does.
+ *
+ * The kind travels with the name because the two are read together everywhere:
+ * an `import { … }` list draws a fragment apart from a function, and `run`
+ * accepts only one of them.
+ */
+export function exportedNames(document: Document): ExportedName[] {
+  const found: ExportedName[] = [];
+  for (const decl of document.decls) {
+    if (!isFragmentDecl(decl) && !isFnDecl(decl) && !isDecoDecl(decl)) continue;
+    if (decl.export) found.push({ name: decl.name, origin: originOf(decl) });
+  }
+  return found;
+}
+
+function originOf(decl: AstNode): string {
+  if (isFragmentDecl(decl)) return "fragment";
+  return isFnDecl(decl) ? "fn" : "deco";
+}

package/src/document/expression-path.ts

@@ -0,0 +1,43 @@
+import { type AstNode, type Expr, isMember, isRef } from "@venn-lang/core";
+import type { SymbolCatalog } from "../catalog/index.js";
+import { findBinding } from "./find-binding.js";
+
+/** The dotted path an expression spells, or undefined when it is not a plain one. */
+export function pathOf(expr: Expr | AstNode | undefined): string | undefined {
+  if (!expr) return undefined;
+  if (isRef(expr)) return expr.name;
+  if (!isMember(expr) || expr.optional) return undefined;
+  const receiver = pathOf(expr.receiver);
+  return receiver === undefined ? undefined : `${receiver}.${expr.member}`;
+}
+
+/**
+ * The action a path names, if the catalog knows it. `let auth = http.post …`
+ * spells a call as a member chain; only the catalog can tell that apart from
+ * `res.status`, and both the colours and the hover need the same answer.
+ */
+export function stdlibAction(
+  node: AstNode | undefined,
+  catalog: SymbolCatalog,
+): string | undefined {
+  const path = pathOf(outermost(node));
+  const dot = path?.indexOf(".") ?? -1;
+  if (!path || dot < 0 || !node) return undefined;
+  // A name in scope always wins, so a variable called `auth` stays a variable
+  // however many stdlib namespaces happen to share its name.
+  if (findBinding(node, path.slice(0, dot))) return undefined;
+  return catalog.action(path.slice(0, dot), path.slice(dot + 1)) ? path : undefined;
+}
+
+/** Climb to the end of the member chain: from `http` in `http.post`, to `http.post`. */
+function outermost(node: AstNode | undefined): AstNode | undefined {
+  let current = node;
+  while (
+    current?.$container &&
+    isMember(current.$container) &&
+    current.$container.receiver === current
+  ) {
+    current = current.$container;
+  }
+  return current;
+}

package/src/document/find-binding.ts

@@ -0,0 +1,82 @@
+import {
+  type AstNode,
+  type Block,
+  type Document,
+  type FragmentDecl,
+  isBlock,
+  isCaptureStmt,
+  isDatasetDecl,
+  isDecoDecl,
+  isDocument,
+  isFnBody,
+  isFnDecl,
+  isFnExpr,
+  isForEachStmt,
+  isFragmentDecl,
+  isLetStmt,
+  isRepeatStmt,
+  type ParamList,
+} from "@venn-lang/core";
+
+/** The node that binds `name`, searched from `from` outwards to the document. */
+export function findBinding(from: AstNode, name: string): AstNode | undefined {
+  let node: AstNode | undefined = from;
+  while (node) {
+    const found = bindingIn(node, name);
+    if (found) return found;
+    node = node.$container;
+  }
+  return undefined;
+}
+
+/** The fragment a document declares under `name`. */
+export function findFragment(document: Document, name: string): FragmentDecl | undefined {
+  return document.decls.find(
+    (decl): decl is FragmentDecl => isFragmentDecl(decl) && decl.name === name,
+  );
+}
+
+/**
+ * The top-level declaration a document makes under `name`.
+ *
+ * The same lookup a name written in that file resolves to, reused from outside
+ * it, which is what following an `import` does.
+ */
+export function findDeclaration(document: Document, name: string): AstNode | undefined {
+  return documentBinding(document, name);
+}
+
+function bindingIn(node: AstNode, name: string): AstNode | undefined {
+  if (isForEachStmt(node)) return node.item === name ? node : undefined;
+  if (isRepeatStmt(node)) return node.index === name ? node : undefined;
+  // A `deco` binds its parameters the way a `fn` does. The first one being the
+  // target is a fact about its type, not about how it comes into scope.
+  if (isFragmentDecl(node) || isFnDecl(node) || isFnExpr(node) || isDecoDecl(node))
+    return paramNamed(node.params, name);
+  if (isFnBody(node)) return node.locals.find((local) => local.name === name);
+  if (isBlock(node)) return statementBinding(node, name);
+  if (isDocument(node)) return documentBinding(node, name);
+  return undefined;
+}
+
+function statementBinding(block: Block, name: string): AstNode | undefined {
+  return block.stmts.find((stmt) => (isLetStmt(stmt) || isCaptureStmt(stmt)) && stmt.name === name);
+}
+
+function documentBinding(document: Document, name: string): AstNode | undefined {
+  return document.decls.find((decl) => declares(decl, name));
+}
+
+/**
+ * A `fn` is a value like any other: it can be passed, bound and called, so a
+ * file that declares one has bound that name.
+ */
+function declares(decl: AstNode, name: string): boolean {
+  if (isLetStmt(decl) || isDatasetDecl(decl)) return decl.name === name;
+  if (isFnDecl(decl) || isDecoDecl(decl)) return decl.name === name;
+  return isFragmentDecl(decl) && decl.name === name;
+}
+
+function paramNamed(params: ParamList | undefined, name: string): AstNode | undefined {
+  return (params?.params ?? []).find((param) => param.name === name);
+}