@venn-lang/lsp 0.1.0

package/src/hover/resolve-symbol.ts

@@ -0,0 +1,77 @@
+import { type AstNode, createContext, isPrelude, resolveMember, type Type } from "@venn-lang/core";
+import type { LangiumDocument } from "langium";
+import type { SymbolCatalog } from "../catalog/index.js";
+import { findBinding } from "../document/index.js";
+import type { TypeService } from "../types/index.js";
+import { actionHover } from "./render-action.js";
+import { bindingHover } from "./render-decl.js";
+import { memberHover, namespaceHover, preludeHover } from "./render-symbol.js";
+
+export interface ResolveArgs {
+  /** The dotted path under the cursor, e.g. `people.maxBy`. */
+  path: string;
+  /** Which segment the cursor sits on; `0` is the head. */
+  segment: number;
+  /** A node inside the file, for looking a name up in scope. */
+  host: AstNode;
+  document: LangiumDocument;
+  catalog: SymbolCatalog;
+  types: TypeService;
+}
+
+/**
+ * Describe what a dotted path refers to, wherever it is written: a prelude verb,
+ * a plugin namespace or one of its actions, a built-in member of a value, or a
+ * binding the file declared.
+ *
+ * It resolves from the path's text rather than from parsed nodes, because an
+ * expression inside `"${…}"` is parsed apart from the document. That way the
+ * same name reads the same in both places.
+ */
+export function resolveSymbol(args: ResolveArgs): string | undefined {
+  const segments = args.path.split(".");
+  const head = segments[0];
+  if (!head) return undefined;
+  const binding = findBinding(args.host, head);
+  if (args.segment === 0) return headHover({ head, binding, args });
+  if (!binding && args.catalog.hasNamespace(head)) return actionHover(args.path, args.catalog);
+  return memberOf({ segments, binding, args });
+}
+
+/** The first segment: something the file bound, a namespace, or a prelude name. */
+function headHover(input: {
+  head: string;
+  binding: AstNode | undefined;
+  args: ResolveArgs;
+}): string | undefined {
+  const { head, binding, args } = input;
+  if (binding) {
+    return bindingHover({
+      document: args.document,
+      node: args.host,
+      name: head,
+      types: args.types,
+    });
+  }
+  return namespaceHover(head, args.catalog) ?? (isPrelude(head) ? preludeHover(head) : undefined);
+}
+
+/** `xs.map`, `cfg.server.port`: walk to the receiver, then describe its member. */
+function memberOf(input: {
+  segments: readonly string[];
+  binding: AstNode | undefined;
+  args: ResolveArgs;
+}): string | undefined {
+  const { segments, binding, args } = input;
+  const member = segments[args.segment];
+  let receiver = binding && args.types.of(args.document).types.get(binding);
+  if (!receiver || !member) return undefined;
+  for (const step of segments.slice(1, args.segment)) {
+    const next = resolveMember(receiver, step, createContext());
+    if (!next) return undefined;
+    receiver = next;
+  }
+  return memberHover({ receiver, member });
+}
+
+export type { Type };

package/src/hover/type-hover.ts

@@ -0,0 +1,62 @@
+import { type AstNode, isExpr, prune, showType, type Type } from "@venn-lang/core";
+import { AstUtils, type CstNode } from "langium";
+import type { TypeService } from "../types/index.js";
+
+/** The inferred type of a node: `list<number>`, `fn(number) -> number`. */
+export function typeLabel(node: AstNode | undefined, types: TypeService): string | undefined {
+  if (!node) return undefined;
+  const found = types.of(AstUtils.getDocument(node)).types.get(node);
+  return found ? spread(found) : undefined;
+}
+
+/** Past this many fields a shape stops reading as a line and starts reading as a wall. */
+const INLINE_FIELDS = 3;
+
+/**
+ * The same type, one field per line once there are enough of them to matter.
+ *
+ * A diagnostic wants a type on one line, which is what `showType` gives. A
+ * hover has room, and a decorator handle carrying ten verbs on one line is
+ * exactly as much use as no hover at all.
+ */
+function spread(type: Type): string {
+  const pruned = prune(type);
+  if (pruned.kind !== "record" || pruned.fields.size <= INLINE_FIELDS) return showType(pruned);
+  const fields = [...pruned.fields].map(([name, field]) => `  ${name}: ${showType(field)},`);
+  return `{\n${fields.join("\n")}\n}`;
+}
+
+/**
+ * The type of the expression a token belongs to, as a hover. Used when nothing
+ * else describes the token, so hovering `.len` or a literal still answers.
+ */
+export function inferredType(leaf: CstNode, types: TypeService): string | undefined {
+  if (!carriesMeaning(leaf.text)) return undefined;
+  const known = types.of(AstUtils.getDocument(leaf.astNode)).types;
+  const type = nearestType(leaf, known);
+  return type ? `\`\`\`venn\n${showType(type)}\n\`\`\`` : undefined;
+}
+
+const NAME_OR_LITERAL = /^([A-Za-z_]\w*|\d|["'])/;
+
+/**
+ * Only a name or a literal describes a value. A bracket or a comma belongs to
+ * the expression around it, so answering for one would make hovering `(`
+ * report the type of whatever it encloses.
+ */
+function carriesMeaning(text: string): boolean {
+  return NAME_OR_LITERAL.test(text);
+}
+
+/** Walk from the token's node outward to the nearest expression that has a type. */
+function nearestType(leaf: CstNode, types: ReadonlyMap<AstNode, Type>): Type | undefined {
+  let node: AstNode | undefined = leaf.astNode;
+  while (node) {
+    if (isExpr(node)) {
+      const type = types.get(node);
+      if (type) return type;
+    }
+    node = node.$container;
+  }
+  return undefined;
+}

package/src/index.ts

@@ -0,0 +1,38 @@
+// @venn-lang/lsp: the Venn language server. Diagnostics, semantic highlighting,
+// hover, go-to-definition, completion and the document outline.
+
+export type { ActionEntry, MatcherEntry, SymbolCatalog } from "./catalog/index.js";
+export { buildCatalog } from "./catalog/index.js";
+export type { CompletionContext } from "./completion/index.js";
+export { contextAt, modulePaths, VennCompletionProvider } from "./completion/index.js";
+export type { DecoInfo, DecoScope } from "./deco/index.js";
+export { builtinDecos, decoNamed, decosInScope } from "./deco/index.js";
+export { VennDefinitionProvider } from "./definition/index.js";
+export type { DocBlock, DocParam } from "./docs/index.js";
+export { parseDoc, readDoc, renderDoc } from "./docs/index.js";
+export type { FragmentLocation } from "./document/index.js";
+export {
+  exportedNames,
+  findBinding,
+  findFragment,
+  importedNames,
+  resolveFragment,
+} from "./document/index.js";
+export { VennFormatter } from "./formatting/index.js";
+export { VennHoverProvider } from "./hover/index.js";
+export {
+  findOccurrences,
+  occurrencesIn,
+  symbolAt,
+  VennDocumentHighlightProvider,
+  VennReferencesProvider,
+} from "./references/index.js";
+export { VennRenameProvider } from "./rename/index.js";
+export { VennSemanticTokenProvider } from "./semantic/index.js";
+export { startVennServer } from "./server/index.js";
+export type { VennAddedServices, VennServices } from "./services/index.js";
+export { createVennLspServices } from "./services/index.js";
+export { VennSignatureHelpProvider } from "./signature/index.js";
+export { VennDocumentSymbolProvider } from "./symbols/index.js";
+export { registerVennChecks } from "./validation/index.js";
+export { createImportResolver, type ImportResolver } from "./workspace/index.js";

package/src/markdown/index.ts

@@ -0,0 +1 @@
+export { code, fence, labelled, rule, sections } from "./markdown.js";

package/src/markdown/markdown.ts

@@ -0,0 +1,38 @@
+/** A fenced `venn` block: the signature line at the top of a hover. */
+export function fence(source: string): string {
+  return ["```venn", source, "```"].join("\n");
+}
+
+/** An inline code span. */
+export function code(text: string): string {
+  return `\`${text}\``;
+}
+
+/**
+ * Hovers read best with three levels of separation, strongest to weakest:
+ *
+ * - {@link rule}: a horizontal line between the signature, the body and the
+ *   provenance footer. This is what VS Code's own hovers use.
+ * - {@link sections}: a blank line between blocks inside the body.
+ * - a plain newline: a label and the content it introduces stay glued together.
+ *
+ * The blank line before `---` matters: markdown would otherwise read it as a
+ * setext heading and turn the preceding paragraph into an `<h2>`.
+ */
+export function rule(parts: Array<string | undefined>): string {
+  return present(parts).join("\n\n---\n\n");
+}
+
+/** Join the blocks that exist, separated by blank lines. */
+export function sections(parts: Array<string | undefined>): string {
+  return present(parts).join("\n\n");
+}
+
+/** Glue a label to the content it introduces, with no gap between them. */
+export function labelled(label: string, content: string): string {
+  return `${label}\n${content}`;
+}
+
+function present(parts: Array<string | undefined>): string[] {
+  return parts.filter((part): part is string => Boolean(part));
+}

package/src/references/document-highlight.ts

@@ -0,0 +1,45 @@
+import type { Document } from "@venn-lang/core";
+import type { LangiumDocument } from "langium";
+import type { DocumentHighlightProvider } from "langium/lsp";
+import {
+  type DocumentHighlight,
+  DocumentHighlightKind,
+  type DocumentHighlightParams,
+} from "vscode-languageserver";
+import { rangeOf } from "./occurrence-range.js";
+import { occurrencesIn } from "./occurrences.js";
+import type { Occurrence } from "./symbol.types.js";
+import { symbolAt } from "./symbol-at.js";
+
+/**
+ * The other places the name under the cursor appears, marked in this file.
+ *
+ * Only this file, whatever the symbol's reach: highlighting is about the page
+ * being read. Where the name is introduced is drawn apart from where it is
+ * used, which is the quickest way to see that a value is written once and read
+ * four times, or written twice, which is usually the bug being looked for.
+ */
+export class VennDocumentHighlightProvider implements DocumentHighlightProvider {
+  getDocumentHighlight(
+    document: LangiumDocument,
+    params: DocumentHighlightParams,
+  ): DocumentHighlight[] {
+    const symbol = symbolAt(document, params.position);
+    const root = document.parseResult?.value as Document | undefined;
+    if (!symbol || !root) return [];
+    return marked(occurrencesIn({ root, symbol }));
+  }
+}
+
+function marked(occurrences: readonly Occurrence[]): DocumentHighlight[] {
+  const found: DocumentHighlight[] = [];
+  for (const each of occurrences) {
+    const range = rangeOf(each);
+    if (range) found.push({ range, kind: kindOf(each) });
+  }
+  return found;
+}
+
+function kindOf(occurrence: Occurrence): DocumentHighlightKind {
+  return occurrence.declaration ? DocumentHighlightKind.Write : DocumentHighlightKind.Read;
+}

package/src/references/find-occurrences.ts

@@ -0,0 +1,49 @@
+import type { Document } from "@venn-lang/core";
+import type { LangiumDocument, LangiumDocuments } from "langium";
+import type { Location, Range } from "vscode-languageserver";
+import { rangesOf } from "./occurrence-range.js";
+import { occurrencesIn } from "./occurrences.js";
+import { crossesFiles, type FoundSymbol, type Occurrence } from "./symbol.types.js";
+
+/** One document's share of the answer. */
+export interface FoundIn {
+  uri: string;
+  occurrences: readonly Occurrence[];
+}
+
+/**
+ * Every place a symbol appears, in the file that asked and in the workspace
+ * when the symbol reaches that far.
+ *
+ * A file-scoped binding is never searched for elsewhere. That is not an
+ * optimisation: a `const` named `user` next door is a different `user`, and
+ * offering it as a reference sends the reader somewhere unrelated.
+ */
+export function findOccurrences(args: {
+  symbol: FoundSymbol;
+  document: LangiumDocument;
+  documents: LangiumDocuments;
+}): FoundIn[] {
+  const here = inDocument(args.document, args.symbol);
+  if (!crossesFiles(args.symbol.kind)) return here ? [here] : [];
+  const found: FoundIn[] = [];
+  for (const document of args.documents.all) {
+    const one = inDocument(document, args.symbol);
+    if (one) found.push(one);
+  }
+  return found;
+}
+
+function inDocument(document: LangiumDocument, symbol: FoundSymbol): FoundIn | undefined {
+  const root = document.parseResult?.value as Document | undefined;
+  if (!root) return undefined;
+  const occurrences = occurrencesIn({ root, symbol });
+  return occurrences.length > 0 ? { uri: document.uri.toString(), occurrences } : undefined;
+}
+
+/** The same answer as locations, which is the shape the editor asks for. */
+export function locationsOf(found: readonly FoundIn[]): Location[] {
+  return found.flatMap((one) =>
+    rangesOf(one.occurrences).map((range: Range) => ({ uri: one.uri, range })),
+  );
+}

package/src/references/index.ts

@@ -0,0 +1,13 @@
+export { VennDocumentHighlightProvider } from "./document-highlight.js";
+export { type FoundIn, findOccurrences, locationsOf } from "./find-occurrences.js";
+export { nameProperty } from "./name-property.js";
+export { rangeOf, rangesOf } from "./occurrence-range.js";
+export { occurrencesIn } from "./occurrences.js";
+export { VennReferencesProvider } from "./references.js";
+export {
+  crossesFiles,
+  type FoundSymbol,
+  type Occurrence,
+  type SymbolKind,
+} from "./symbol.types.js";
+export { leafAt, symbolAt } from "./symbol-at.js";

package/src/references/name-property.ts

@@ -0,0 +1,14 @@
+import { type AstNode, isForEachStmt, isRepeatStmt } from "@venn-lang/core";
+
+/**
+ * Which property of a declaration carries the name it binds.
+ *
+ * Most spell it `name`; a `forEach` calls its variable `item` and a `repeat`
+ * calls its counter `index`. Kept in one place because every reader of a
+ * declaration needs the answer, and copies of it drift.
+ */
+export function nameProperty(node: AstNode | object): string | undefined {
+  if (isForEachStmt(node)) return "item";
+  if (isRepeatStmt(node)) return "index";
+  return "name" in node ? "name" : undefined;
+}

package/src/references/occurrence-range.ts

@@ -0,0 +1,23 @@
+import { GrammarUtils } from "langium";
+import type { Range } from "vscode-languageserver";
+import type { Occurrence } from "./symbol.types.js";
+
+/** Where an occurrence sits in the text, or nothing when the CST has no node. */
+export function rangeOf(occurrence: Occurrence): Range | undefined {
+  const cst = GrammarUtils.findNodeForProperty(
+    occurrence.node.$cstNode,
+    occurrence.property,
+    occurrence.index,
+  );
+  return cst?.range;
+}
+
+/** The occurrences that resolved to a real range, as ranges. */
+export function rangesOf(occurrences: readonly Occurrence[]): Range[] {
+  const found: Range[] = [];
+  for (const each of occurrences) {
+    const range = rangeOf(each);
+    if (range) found.push(range);
+  }
+  return found;
+}

package/src/references/occurrences.ts

@@ -0,0 +1,124 @@
+import {
+  type AstNode,
+  type Document,
+  isAnnotation,
+  isDecoDecl,
+  isFnDecl,
+  isFragmentDecl,
+  isNamedType,
+  isRef,
+  isRunStmt,
+  isTypeDecl,
+  isValueImport,
+  walkAst,
+} from "@venn-lang/core";
+import { findBinding } from "../document/index.js";
+import { nameProperty } from "./name-property.js";
+import type { FoundSymbol, Occurrence } from "./symbol.types.js";
+
+/**
+ * Every place one symbol appears in one document.
+ *
+ * One walk, one answer, whatever the caller wants it for: "find all references"
+ * shows them, the editor highlights them, and rename rewrites them. Three
+ * separate readings of the tree would be three chances to disagree.
+ */
+export function occurrencesIn(args: { root: Document; symbol: FoundSymbol }): Occurrence[] {
+  const found = importNames(args.root, args.symbol.name);
+  for (const node of walkAst(args.root)) {
+    const one = occurrenceAt({ node, symbol: args.symbol });
+    if (one) found.push(one);
+  }
+  return found;
+}
+
+function occurrenceAt(args: { node: AstNode; symbol: FoundSymbol }): Occurrence | undefined {
+  const { node, symbol } = args;
+  if (symbol.kind === "binding") return bindingUse(node, symbol);
+  if (symbol.kind === "type") return typeUse(node, symbol.name);
+  if (symbol.kind === "deco") return decoUse(node, symbol.name);
+  if (symbol.kind === "fragment") return fragmentUse(node, symbol.name);
+  if (symbol.kind === "fn") return fnUse(node, symbol.name);
+  return externalUse(node, symbol.name);
+}
+
+/**
+ * A name this file imported: found wherever a name of any importable kind can
+ * appear.
+ *
+ * Which of the three it is (fragment, function or decorator) is written in the
+ * file it came from, and this is asked of every file in the workspace, one of
+ * which is that one. Matching all three shapes reaches it without reading
+ * ahead, and no shape can match a name that is not this one.
+ */
+function externalUse(node: AstNode, name: string): Occurrence | undefined {
+  return fnUse(node, name) ?? fragmentUse(node, name) ?? decoUse(node, name);
+}
+
+/** `import { a, b }`: one node holding several names, so each is found by index. */
+function importNames(root: Document, name: string): Occurrence[] {
+  const found: Occurrence[] = [];
+  for (const decl of root.imports) {
+    if (!isValueImport(decl)) continue;
+    decl.names.forEach((each, index) => {
+      if (each === name) found.push({ node: decl, property: "names", index, declaration: false });
+    });
+  }
+  return found;
+}
+
+function fragmentUse(node: AstNode, name: string): Occurrence | undefined {
+  if (isFragmentDecl(node) && node.name === name) return declaration(node);
+  if (isRunStmt(node) && node.target === name) {
+    return { node, property: "target", declaration: false };
+  }
+  return undefined;
+}
+
+function decoUse(node: AstNode, name: string): Occurrence | undefined {
+  if (isDecoDecl(node) && node.name === name) return declaration(node);
+  if (isAnnotation(node) && node.name === name) {
+    return { node, property: "name", declaration: false };
+  }
+  return undefined;
+}
+
+/**
+ * A function: where it is declared, and every name that reads it.
+ *
+ * Matched by name rather than by resolving each reference back to the
+ * declaration, because a `pub fn` is read in files that never declared it: the
+ * file next door holds the same name and means the same thing.
+ */
+function fnUse(node: AstNode, name: string): Occurrence | undefined {
+  if (isFnDecl(node) && node.name === name) return declaration(node);
+  if (isRef(node) && node.name === name) return { node, property: "name", declaration: false };
+  return undefined;
+}
+
+function typeUse(node: AstNode, name: string): Occurrence | undefined {
+  if (isTypeDecl(node) && node.name === name) return declaration(node);
+  if (isNamedType(node) && node.name === name) {
+    return { node, property: "name", declaration: false };
+  }
+  return undefined;
+}
+
+/**
+ * A binding, and only the reads that resolve back to this one.
+ *
+ * A name shadowed in an inner block is a different binding wearing the same
+ * spelling, and reporting it would send the reader to a line that has nothing
+ * to do with what they asked about.
+ */
+function bindingUse(node: AstNode, symbol: FoundSymbol): Occurrence | undefined {
+  if (node === symbol.binding) return declaration(node);
+  if (!isRef(node) || node.name !== symbol.name) return undefined;
+  if (findBinding(node, symbol.name) !== symbol.binding) return undefined;
+  return { node, property: "name", declaration: false };
+}
+
+function declaration(node: AstNode): Occurrence | undefined {
+  const property = nameProperty(node);
+  return property ? { node, property, declaration: true } : undefined;
+}

package/src/references/references.ts

@@ -0,0 +1,38 @@
+import type { LangiumDocument, LangiumDocuments } from "langium";
+import type { ReferencesProvider } from "langium/lsp";
+import type { Location, ReferenceParams } from "vscode-languageserver";
+import type { VennServices } from "../services/lsp.types.js";
+import { findOccurrences, locationsOf } from "./find-occurrences.js";
+import { symbolAt } from "./symbol-at.js";
+
+/**
+ * Shift+F12: every place a name is used.
+ *
+ * Langium's own provider resolves cross-references the grammar declares, and
+ * this grammar declares none: a `run` target is a string, a `@name` is a string,
+ * and which `const` a `Ref` means is worked out by walking scopes. So the answer
+ * has to be worked out the same way the checker and the evaluator work it out,
+ * which is what this shares with them.
+ */
+export class VennReferencesProvider implements ReferencesProvider {
+  private readonly documents: LangiumDocuments;
+
+  constructor(services: VennServices) {
+    this.documents = services.shared.workspace.LangiumDocuments;
+  }
+
+  findReferences(document: LangiumDocument, params: ReferenceParams): Location[] {
+    const symbol = symbolAt(document, params.position);
+    if (!symbol) return [];
+    const found = findOccurrences({ symbol, document, documents: this.documents });
+    const wanted = params.context?.includeDeclaration === false ? uses(found) : found;
+    return locationsOf(wanted);
+  }
+}
+
+/** The editor may ask for the uses without the line that introduces the name. */
+function uses(found: ReturnType<typeof findOccurrences>): ReturnType<typeof findOccurrences> {
+  return found
+    .map((one) => ({ ...one, occurrences: one.occurrences.filter((each) => !each.declaration) }))
+    .filter((one) => one.occurrences.length > 0);
+}

package/src/references/symbol-at.ts

@@ -0,0 +1,114 @@
+import {
+  type AstNode,
+  isAnnotation,
+  isCaptureStmt,
+  isDatasetDecl,
+  isDecoDecl,
+  isDocument,
+  isFnDecl,
+  isForEachStmt,
+  isFragmentDecl,
+  isLetStmt,
+  isNamedType,
+  isParam,
+  isRef,
+  isRepeatStmt,
+  isRunStmt,
+  isTypeDecl,
+  isValueImport,
+} from "@venn-lang/core";
+import { AstUtils, type CstNode, CstUtils, type LangiumDocument } from "langium";
+import type { Position } from "vscode-languageserver";
+import { findBinding } from "../document/index.js";
+import { nameProperty } from "./name-property.js";
+import type { FoundSymbol } from "./symbol.types.js";
+
+/**
+ * The symbol a position names, or nothing when it names none.
+ *
+ * Read from the token under the cursor rather than from the node containing it:
+ * one node often carries two names (`import { a, b }` is a single node, and so
+ * is `run login("x")`), and the answer depends on which word was clicked.
+ */
+export function symbolAt(document: LangiumDocument, position: Position): FoundSymbol | undefined {
+  const leaf = leafAt(document, position);
+  if (!leaf) return undefined;
+  return declared(leaf) ?? used(leaf);
+}
+
+export function leafAt(document: LangiumDocument, position: Position): CstNode | undefined {
+  const root = document.parseResult?.value?.$cstNode;
+  const offset = document.textDocument.offsetAt(position);
+  return root ? CstUtils.findLeafNodeAtOffset(root, offset) : undefined;
+}
+
+/** The cursor is on the word that introduces the name. */
+function declared(leaf: CstNode): FoundSymbol | undefined {
+  const node = leaf.astNode;
+  const name = leaf.text;
+  if (isFragmentDecl(node) && node.name === name) return { kind: "fragment", name };
+  if (isDecoDecl(node) && node.name === name) return { kind: "deco", name };
+  if (isFnDecl(node) && node.name === name) return { kind: "fn", name };
+  if (isTypeDecl(node) && node.name === name) return { kind: "type", name, binding: node };
+  return declaredBinding(leaf);
+}
+
+/**
+ * The cursor on the word a `const`, a parameter or a loop variable introduces.
+ *
+ * Told apart from a use by the node it sits on, never by the text. A `Ref` also
+ * carries a `name` equal to the word under the cursor, and treating one as a
+ * declaration would make the binding be itself, so no read of it would resolve.
+ */
+function declaredBinding(leaf: CstNode): FoundSymbol | undefined {
+  const node = leaf.astNode;
+  if (!binds(node)) return undefined;
+  const property = nameProperty(node);
+  const written = property && (node as unknown as Record<string, unknown>)[property];
+  return written === leaf.text ? { kind: "binding", name: leaf.text, binding: node } : undefined;
+}
+
+function binds(node: AstNode): boolean {
+  return (
+    isLetStmt(node) ||
+    isCaptureStmt(node) ||
+    isDatasetDecl(node) ||
+    isParam(node) ||
+    isForEachStmt(node) ||
+    isRepeatStmt(node)
+  );
+}
+
+/** The cursor is on a use of the name, or on one inside an `import { … }`. */
+function used(leaf: CstNode): FoundSymbol | undefined {
+  const node = leaf.astNode;
+  const name = leaf.text;
+  if (isRunStmt(node) && node.target === name) return { kind: "fragment", name };
+  if (isAnnotation(node) && node.name === name) return { kind: "deco", name };
+  if (isNamedType(node) && node.name === name) return { kind: "type", name };
+  if (isValueImport(node) && node.names.includes(name)) return { kind: "external", name };
+  return isRef(node) && node.name === name ? boundSymbol(node, name) : undefined;
+}
+
+/**
+ * A plain name: which binding it resolves to decides how far it reaches.
+ *
+ * A `fn` this file declared is importable, so its uses may be anywhere; a
+ * `const` or a parameter is bound here and a name spelled the same next door is
+ * a different name entirely.
+ */
+function boundSymbol(node: AstNode, name: string): FoundSymbol {
+  const binding = findBinding(node, name);
+  if (binding && isFnDecl(binding)) return { kind: "fn", name };
+  if (binding && isFragmentDecl(binding)) return { kind: "fragment", name };
+  if (binding && isDecoDecl(binding)) return { kind: "deco", name };
+  // Nothing here binds it and the file imported it, so it belongs to another
+  // file. Calling it a local binding would keep the search inside this one.
+  if (!binding && isImported(node, name)) return { kind: "external", name };
+  return { kind: "binding", name, binding };
+}
+
+function isImported(from: AstNode, name: string): boolean {
+  const root = AstUtils.getContainerOfType(from, isDocument);
+  return (root?.imports ?? []).some((decl) => isValueImport(decl) && decl.names.includes(name));
+}