@venn-lang/lsp 0.1.0

package/src/hover/keywords.ts

@@ -0,0 +1,168 @@
+import { fence, rule, sections } from "../markdown/index.js";
+
+interface KeywordDoc {
+  summary: string;
+  example?: string;
+}
+
+// What every word of the kernel does. The grammar is fixed and small, so this
+// table is the whole language: a newcomer can learn it by hovering.
+const KEYWORDS: Record<string, KeywordDoc> = {
+  module: {
+    summary: "Name this file. Purely documentation; imports resolve by path, not by module name.",
+    example: "module checkout.payment",
+  },
+  use: {
+    summary: "Load a plugin package, making its namespace available as verbs.",
+    example: 'use "venn/http"\nuse "venn/browser" as b',
+  },
+  import: {
+    summary: "Bring `pub` fragments and functions from another `.vn` file into this one.",
+    example: 'import { login } from "./shared/auth.vn"',
+  },
+  from: {
+    summary: "The module an `import` reads from: a relative path or a `#alias` from `venn.toml`.",
+  },
+  as: {
+    summary: "Rename what you just bound — a `use` namespace, a `repeat` index or a `run` result.",
+  },
+  pub: {
+    summary: "Export this declaration so other files may `import` it.",
+    example: "pub fragment login(user) { … }",
+  },
+  flow: {
+    summary: "A test: the top-level unit the runner schedules and reports.",
+    example:
+      'flow "Checkout" {\n  step "Pay" {\n    const paid = http.post "/pay"\n    expect paid.status == 200\n  }\n}',
+  },
+  step: {
+    summary: "One named unit of work inside a flow. Bindings made inside it are step-local.",
+    example: 'step "Ping" {\n  const health = http.get "/health"\n  expect health.status == 200\n}',
+  },
+  group: {
+    summary: "Label a set of steps. Structure only — it changes no scope.",
+    example: 'group "payment" {\n  step "Charge" { … }\n}',
+  },
+  fragment: {
+    summary: "A reusable block of steps, invoked with `run`. Composition without inheritance.",
+    example: 'fragment login(user) {\n  step "login" { … }\n}',
+  },
+  fn: {
+    summary:
+      "A pure function returning a value — first-class, callable anywhere. `=> expr` for one line; a `{ … }` block returns its last expression. No steps, no I/O.",
+    example: "fn double(x) => x * 2\nconst add = fn (a, b) => a + b",
+  },
+  deco: {
+    summary:
+      "Declare a decorator. The first parameter is the target, and the type written on it is what `@name` may sit on — `Fn`, `Flow`, `Step`, `Binding`, `Type`, `Resource`, or `Node` for anything. The parameters after it are the decorator's own arguments. The body runs before the program exists, so it is pure: no plugin verbs.",
+    example:
+      'deco memoize(target: Fn) {\n  const cache = {}\n  target.wrap(fn (call, args) => cache.get(str(args)) ?? call(args))\n}\n\npub deco retry(target: Flow, times: number) {\n  target.meta "retry" times\n}',
+  },
+  run: {
+    summary: "Invoke a fragment, optionally binding what it returns.",
+    example: 'run login("alice") as session',
+  },
+  expect: {
+    summary:
+      "Assert. Takes a boolean, or a subject plus a matcher. `.all { … }` groups checks; `.soft` records without aborting.",
+    example: 'expect health.status == 200\nexpect user.plan oneOf ["free", "pro"]',
+  },
+  not: { summary: "Negate the expectation that follows.", example: "expect not orders empty" },
+  all: { summary: "Group several checks under one `expect`, each on its own line." },
+  soft: { summary: "Record a failed expectation without aborting the step." },
+  let: { summary: "Bind a value for the rest of the block.", example: 'let plan = "pro"' },
+  const: { summary: "Bind a value that cannot be reassigned.", example: "const retries = 3" },
+  capture: {
+    summary:
+      "Removed. It did exactly what `let` does — use `let` for a value that changes, `const` for one that does not.",
+    example: "const orderId = order.json.id",
+  },
+  env: {
+    summary:
+      "Configuration for this run, read from the `[env.*]` tables of `venn.toml`. `--env <name>` picks which table; `env.name` is the one that was picked.",
+    example:
+      'use "venn/env"\n\nconst token = http.post "${env.BASE_URL}/token" {\n  body: { user: env.USERNAME, pass: env.PASSWORD },\n  encode: "form"\n}',
+  },
+  resource: {
+    summary:
+      "Open something with a lifecycle, closed automatically. `@scope` sets how long it lives.",
+    example: "@scope(flow)\nresource page = browser.newContext",
+  },
+  config: {
+    summary: "Project settings visible to plugins, such as `baseUrl`.",
+    example: "config { baseUrl: env.BASE_URL }",
+  },
+  matrix: {
+    summary: "Run every flow once per combination of these values.",
+    example: 'matrix { browser: ["chromium", "webkit"] }',
+  },
+  dataset: { summary: "A named collection of test data." },
+  factory: { summary: "A named builder for objects, usually backed by `@venn-lang/data`." },
+  type: {
+    summary: "A named shape, used to type parameters and datasets.",
+    example: "type User { email: string }",
+  },
+  report: { summary: "Where results go.", example: 'report junit("./out")' },
+  if: {
+    summary: "Branch on a condition.",
+    example: 'if health.status == 200 {\n  step "ok" { … }\n} else {\n  step "retry" { … }\n}',
+  },
+  else: { summary: "The branch taken when the `if` condition is false." },
+  forEach: {
+    summary: "Repeat the body once per item. The optional map sets `concurrency`.",
+    example: 'forEach user in users { concurrency: 4 } {\n  step "check" { … }\n}',
+  },
+  in: {
+    summary: "Separates the loop variable from its list, and tests membership in an expression.",
+  },
+  repeat: {
+    summary: "Run the body a fixed number of times, optionally binding the 1-based index.",
+    example: 'repeat 3 as attempt {\n  step "poll" { … }\n}',
+  },
+  while: { summary: "Repeat while a condition holds. Every loop inherits a timeout." },
+  parallel: {
+    summary: "Run the statements concurrently and wait for all of them.",
+    example: 'parallel { concurrency: 4 } {\n  step "a" { … }\n  step "b" { … }\n}',
+  },
+  race: {
+    summary: "Run concurrently; the first to finish wins and the others are cancelled.",
+    example: 'race { timeout: 10s } {\n  step "ws" { … }\n  step "poll" { … }\n}',
+  },
+  try: { summary: "Attempt the body, handling failure in `catch` and cleanup in `finally`." },
+  catch: { summary: "Handle a failure from `try`, optionally binding the error." },
+  finally: { summary: "Always runs after `try`, whether it failed or not." },
+  defer: {
+    summary: "Schedule cleanup that runs on the way out of the block, even on failure.",
+    example: 'defer { db.exec "ROLLBACK" }',
+  },
+  setup: { summary: "Runs once before every flow in the file." },
+  teardown: { summary: "Runs once after every flow in the file." },
+  beforeEach: { summary: "Runs before each flow." },
+  afterEach: { summary: "Runs after each flow." },
+  on: {
+    summary: "React to a lifecycle event.",
+    example: "on failure {\n  artifacts.save trace\n}",
+  },
+  return: {
+    summary:
+      "Return a value early. A `fn` already returns its last expression, so `return` is only needed to leave sooner; it also stops a fragment.",
+  },
+  break: { summary: "Leave the innermost loop." },
+  continue: { summary: "Skip to the next iteration of the innermost loop." },
+  true: { summary: "The boolean true." },
+  false: { summary: "The boolean false." },
+  null: { summary: "The absence of a value." },
+};
+
+/** Hover for a keyword of the kernel: what it does, and how it reads. */
+export function keywordHover(word: string): string | undefined {
+  const doc = KEYWORDS[word];
+  if (!doc) return undefined;
+  const example = doc.example ? sections(["**Example**", fence(doc.example)]) : undefined;
+  return rule([fence(word), sections([doc.summary, example])]);
+}
+
+/** Whether the kernel documents this word at all. */
+export function isKeyword(word: string): boolean {
+  return word in KEYWORDS;
+}

package/src/hover/render-action.ts

@@ -0,0 +1,94 @@
+import { type ParamSpec, paramSpecs } from "@venn-lang/sdk";
+import type { ActionEntry, MatcherEntry, SymbolCatalog } from "../catalog/index.js";
+import { code, fence, labelled, rule, sections } from "../markdown/index.js";
+import { callShape, type ShownArg, shownArgs } from "../signature/index.js";
+import { preludeHover } from "./render-symbol.js";
+
+/** Hover for `namespace.action`, or for a prelude verb like `log`. */
+export function actionHover(target: string, catalog: SymbolCatalog): string | undefined {
+  const dot = target.indexOf(".");
+  if (dot < 0) return preludeHover(target);
+  const entry = catalog.action(target.slice(0, dot), target.slice(dot + 1));
+  return entry && renderAction(entry, catalog);
+}
+
+/** Hover for a bareword matcher used after `expect`. */
+export function matcherHover(name: string, catalog: SymbolCatalog): string | undefined {
+  const entry = catalog.matcher(name);
+  return entry && renderMatcher(entry);
+}
+
+function renderAction(entry: ActionEntry, catalog: SymbolCatalog): string {
+  const target = `${entry.namespace}.${entry.name}`;
+  const shape = callShape(target, catalog);
+  const returns = shape?.returns ? ` -> ${shape.returns}` : "";
+  const body = sections([
+    entry.action.doc,
+    argumentsBlock(shape?.args ?? []),
+    optionsBlock(paramSpecs(entry.action.params)),
+  ]);
+  return rule([
+    fence(`${signatureLine(target, shape?.args ?? [])}${returns}`),
+    body || undefined,
+    WHAT_IT_IS,
+    `**Package** ${code(entry.package)}`,
+  ]);
+}
+
+/**
+ * What kind of thing this is, said outright.
+ *
+ * A `fn` hover carries the word `fn` and needs no explaining. A verb carries
+ * nothing that tells it apart from a function the reader could hold, which is
+ * exactly what it is not.
+ */
+const WHAT_IT_IS =
+  "**Verb** — a package contributes it, it reaches the world outside, and the program waits for it without saying so. Naming it calls it; it is not a value you can hold.";
+
+/** The call as it is written: `http.on server handler`, with no brackets. */
+function signatureLine(target: string, args: readonly ShownArg[]): string {
+  const written = args.map((each) => (each.optional ? `${each.name}?` : each.name)).filter(Boolean);
+  return [target, ...written].join(" ");
+}
+
+/** One line per positional argument: the half a Zod schema never describes. */
+function argumentsBlock(args: readonly ShownArg[]): string | undefined {
+  const named = args.filter((each) => each.name);
+  if (named.length === 0) return undefined;
+  return labelled("Arguments", named.map(argumentLine).join("\n"));
+}
+
+function argumentLine(arg: ShownArg): string {
+  const optional = arg.optional ? " *(optional)*" : "";
+  const doc = arg.doc ? ` — ${arg.doc}` : "";
+  return `- ${code(arg.name)}: ${code(arg.type)}${optional}${doc}`;
+}
+
+function renderMatcher(entry: MatcherEntry): string {
+  const applies = entry.matcher.appliesTo
+    ? `Applies to ${code(entry.matcher.appliesTo)}.`
+    : undefined;
+  const args = shownArgs(entry.matcher.args ?? []);
+  const body = sections([
+    applies,
+    argumentsBlock(args),
+    optionsBlock(paramSpecs(entry.matcher.params)),
+  ]);
+  return rule([
+    fence(signatureLine(`expect <subject> ${entry.name}`, args)),
+    body || undefined,
+    `**Package** ${code(entry.package)}`,
+  ]);
+}
+
+/** One line per key: what to write, whether it is required, and what it means. */
+function optionsBlock(specs: ParamSpec[]): string | undefined {
+  if (specs.length === 0) return undefined;
+  return labelled("Options", specs.map(optionLine).join("\n"));
+}
+
+function optionLine(spec: ParamSpec): string {
+  const required = spec.required ? " *(required)*" : "";
+  const doc = spec.doc ? ` — ${spec.doc}` : "";
+  return `- ${code(spec.name)}: ${code(spec.type)}${required}${doc}`;
+}

package/src/hover/render-decl.ts

@@ -0,0 +1,155 @@
+import {
+  type AstNode,
+  type FnDecl,
+  type FragmentDecl,
+  isCaptureStmt,
+  isDatasetDecl,
+  isDecoDecl,
+  isFnDecl,
+  isFnExpr,
+  isForEachStmt,
+  isFragmentDecl,
+  isLetStmt,
+  isParam,
+  isRepeatStmt,
+  type ParamList,
+  type UseDecl,
+} from "@venn-lang/core";
+import { type LangiumDocument, UriUtils } from "langium";
+import type { SymbolCatalog } from "../catalog/index.js";
+import { readDoc, renderDoc } from "../docs/index.js";
+import { type FragmentLocation, findBinding } from "../document/index.js";
+import { code, fence, rule, sections } from "../markdown/index.js";
+import type { TypeService } from "../types/index.js";
+import { typeLabel } from "./type-hover.js";
+
+/** Hover for a fragment: its signature, its documentation, and where it lives. */
+export function fragmentHover(location: FragmentLocation): string {
+  const file = code(UriUtils.basename(location.uri));
+  if (!location.decl || !location.document) {
+    return rule([fence("fragment …"), `Imported from ${file}.`]);
+  }
+  const { decl, document } = location;
+  const params = (decl.params?.params ?? []).map((param) => param.name).join(", ");
+  const signature = `${decl.export ? "pub " : ""}fragment ${decl.name}(${params})`;
+  return rule([fence(signature), renderDoc(readDoc(document, decl)), `Declared in ${file}`]);
+}
+
+/** Hover for a variable reference, resolved to whatever binds it. */
+export function bindingHover(args: {
+  document: LangiumDocument;
+  node: AstNode;
+  name: string;
+  types: TypeService;
+  waiting?: ReadonlySet<string>;
+}): string | undefined {
+  const binding = findBinding(args.node, args.name);
+  return binding && renderBinding({ ...args, binding });
+}
+
+/** Hover on the declaration itself (`let plan = …`, `resource db = …`). */
+export function declarationHover(args: {
+  document: LangiumDocument;
+  node: AstNode;
+  types: TypeService;
+  /** Names of the functions in this file that wait for something. */
+  waiting?: ReadonlySet<string>;
+}): string | undefined {
+  const name = declaredName(args.node);
+  if (name === undefined) return undefined;
+  return renderBinding({ ...args, binding: args.node, name });
+}
+
+/** Hover for `use "venn/http"`: what the package contributes. */
+export function useHover(decl: UseDecl, catalog: SymbolCatalog): string | undefined {
+  const namespace = catalog.namespaceOfPackage(decl.pkg);
+  if (!namespace) return rule([fence(`use "${decl.pkg}"`), "Package is not loaded."]);
+  const count = catalog.actionsIn(namespace).length;
+  const alias = decl.alias ? ` as ${decl.alias}` : "";
+  const verbs = `Contributes ${count} action${count === 1 ? "" : "s"} under ${code(namespace)}.`;
+  return rule([fence(`use "${decl.pkg}"${alias}`), verbs]);
+}
+
+function renderBinding(args: {
+  document: LangiumDocument;
+  binding: AstNode;
+  name: string;
+  types: TypeService;
+  waiting?: ReadonlySet<string>;
+}): string {
+  const { document, binding, name } = args;
+  const waits = Boolean(args.waiting?.has(name)) && isFnDecl(binding);
+  const body = sections([renderDoc(readDoc(document, binding)), describe(binding), waited(waits)]);
+  return rule([fence(signatureOf(binding, name, args.types, waits)), body || undefined]);
+}
+
+/**
+ * Said plainly, because nothing in the source says it. The runtime waits for
+ * this on its own, with no keyword written, so the editor is the only place a
+ * reader can find out.
+ */
+function waited(waits: boolean): string | undefined {
+  if (!waits) return undefined;
+  return "**Waits** — it reaches for a plugin verb, so it hands back a value that is still arriving. Anything that binds it with `let` gets the value.";
+}
+
+function declaredName(node: AstNode): string | undefined {
+  if (isLetStmt(node) || isCaptureStmt(node)) return node.name;
+  if (isFnDecl(node)) return node.name;
+  if (isDatasetDecl(node)) return node.name;
+  return isParam(node) ? node.name : undefined;
+}
+
+/** The signature line, carrying the inferred type when the checker knows one. */
+function signatureOf(binding: AstNode, name: string, types: TypeService, waits = false): string {
+  // `~>` rather than `->`: the arrow says the answer takes a moment.
+  const type = waiting(typeLabel(binding, types), waits);
+  const typed = type ? `: ${type}` : "";
+  if (isFnDecl(binding))
+    return `${binding.export ? "pub " : ""}fn ${written(binding, name)}${typed}`;
+  if (isLetStmt(binding)) return `${binding.kind} ${name}${typed}`;
+  if (isCaptureStmt(binding)) return `capture ${name}`;
+  if (isDatasetDecl(binding)) return `dataset ${name}`;
+  if (isFragmentDecl(binding)) return `fragment ${written(binding, name)}`;
+  if (isParam(binding)) return `${name}${typed || ": parameter"}`;
+  return name;
+}
+
+/**
+ * The name with the parameter list the source actually wrote.
+ *
+ * The type alone says `fn(a, b) -> a`, which tells the reader how many and not
+ * which. The names are right there in the declaration, and they are the half a
+ * caller has to get right.
+ */
+function written(binding: FnDecl | FragmentDecl, name: string): string {
+  const names = (binding.params?.params ?? []).map((param) => param.name);
+  return `${name}(${names.join(", ")})`;
+}
+
+function waiting(type: string | undefined, waits: boolean): string | undefined {
+  return type && waits ? type.replace(" -> ", " ~> ") : type;
+}
+
+/** Where a parameter came from: a function's own list, a decorator's, a fragment's. */
+function paramOwner(param: AstNode): string {
+  const owner = param.$container?.$container;
+  if (isFnDecl(owner)) return "Parameter of this `fn`.";
+  if (isFnExpr(owner)) return "Parameter of this function — typed by where it is called.";
+  if (isDecoDecl(owner)) return decoParam(param);
+  return "Fragment parameter.";
+}
+
+/** A `deco`'s first parameter is the thing decorated; the rest are its arguments. */
+function decoParam(param: AstNode): string {
+  const list = param.$container as ParamList | undefined;
+  if (list?.params[0] !== param) return "Argument of this decorator, filled by `@name(…)`.";
+  return "What this decorator decorates — its type is the kind it may be written on.";
+}
+
+function describe(binding: AstNode): string | undefined {
+  if (isForEachStmt(binding)) return "Loop variable of `forEach`.";
+  if (isRepeatStmt(binding)) return "Loop index of `repeat`.";
+  if (isParam(binding)) return paramOwner(binding);
+  return undefined;
+}

package/src/hover/render-imported.ts

@@ -0,0 +1,49 @@
+import { isDecoDecl, isFragmentDecl } from "@venn-lang/core";
+import { UriUtils } from "langium";
+import { declaredDeco, decoHover } from "../deco/index.js";
+import type { ImportedLocation } from "../document/index.js";
+import { code, fence, rule } from "../markdown/index.js";
+import type { TypeService } from "../types/index.js";
+import { declarationHover, fragmentHover } from "./render-decl.js";
+
+export interface ImportedHoverArgs {
+  location: ImportedLocation;
+  name: string;
+  types: TypeService;
+}
+
+/**
+ * A name as it reads inside `import { … }`.
+ *
+ * Whatever the other file declared, described the way that file would describe
+ * it, so importing a name and standing on its declaration read alike. The
+ * import list is the one place a name is neither a declaration nor a use, so
+ * nothing else in the hover reaches it.
+ */
+export function importedHover(args: ImportedHoverArgs): string | undefined {
+  const { location, name } = args;
+  const { decl, document } = location;
+  if (!decl || !document) return unread(location, name);
+  if (isFragmentDecl(decl)) return fragmentHover({ ...location, decl, document });
+  if (isDecoDecl(decl)) return decoHover(declaredDeco({ decl, document }));
+  return declarationHover({ document, node: decl, types: args.types });
+}
+
+/** The file could not be read, or declares no such name; say what is known. */
+function unread(location: ImportedLocation, name: string): string {
+  return rule([fence(name), `Imported from ${code(UriUtils.basename(location.uri))}.`]);
+}
+
+/**
+ * The specifier itself: where `"#shared/auth.vn"` actually lands.
+ *
+ * An alias is the one specifier a reader cannot resolve in their head: it goes
+ * through `[paths]` in `venn.toml`, which is a different file. Saying the
+ * resolved path is the whole answer.
+ */
+export function importPathHover(args: { location: ImportedLocation; path: string }): string {
+  const { location, path } = args;
+  const file = code(UriUtils.basename(location.uri));
+  const read = location.document ? `Resolves to ${file}.` : `Resolves to ${file} — not readable.`;
+  return rule([fence(`from "${path}"`), read]);
+}

package/src/hover/render-symbol.ts

@@ -0,0 +1,108 @@
+import {
+  createContext,
+  MEMBER_DOCS,
+  memberKind,
+  memberType,
+  PRELUDE_SPECS,
+  type PreludeArg,
+  resolveMember,
+  showType,
+  type Type,
+} from "@venn-lang/core";
+import type { SymbolCatalog } from "../catalog/index.js";
+import { code, fence, labelled, rule, sections } from "../markdown/index.js";
+
+/**
+ * Hover for a prelude name: `range`, `str`, `print`. They belong to no
+ * namespace and are declared nowhere, so without this they read as an unknown
+ * variable of type `dynamic`.
+ */
+export function preludeHover(name: string): string | undefined {
+  const spec = PRELUDE_SPECS[name];
+  if (!spec) return undefined;
+  return rule([
+    fence(spec.signature),
+    sections([spec.doc, argumentsBlock(spec.args), example(spec.example)]),
+    "**Prelude** — available without `use`.",
+  ]);
+}
+
+/** One line per argument, laid out as an action's is; a verb is a verb. */
+function argumentsBlock(args: readonly PreludeArg[] | undefined): string | undefined {
+  if (!args?.length) return undefined;
+  const lines = args.map((arg) => {
+    const doc = arg.doc ? ` — ${arg.doc}` : "";
+    return `- ${code(arg.name)}: ${code(arg.type)}${arg.optional ? " *(optional)*" : ""}${doc}`;
+  });
+  return labelled("Arguments", lines.join("\n"));
+}
+
+/**
+ * Hover for a namespace itself (`fmt`, `http`). A namespace is not a map: it is
+ * the set of verbs a package contributes, and saying so keeps anyone from
+ * reading its members like data.
+ */
+export function namespaceHover(name: string, catalog: SymbolCatalog): string | undefined {
+  if (!catalog.hasNamespace(name)) return undefined;
+  const actions = catalog.actionsIn(name);
+  const shown = actions.slice(0, 8).map((entry) => code(`${name}.${entry.name}`));
+  const more = actions.length > shown.length ? `, …${actions.length - shown.length} more` : "";
+  return rule([
+    fence(`namespace ${name}`),
+    sections([
+      `Contributes ${actions.length} verb${actions.length === 1 ? "" : "s"}.`,
+      actions.length > 0 ? labelled("Verbs", `${shown.join(", ")}${more}`) : undefined,
+    ]),
+    `**Package** ${catalog.packagesFor(name).map(code).join(", ")}`,
+  ]);
+}
+
+/**
+ * Hover for a built-in member of a native value: `xs.map`, `name.slugify`.
+ * The signature comes from the receiver's inferred type, so `xs.first` on a
+ * `list<number>` reads as `number`, not as a type variable.
+ */
+export function memberHover(args: { receiver: Type; member: string }): string | undefined {
+  const kind = memberKind(args.receiver);
+  const doc = kind && MEMBER_DOCS[kind]?.[args.member];
+  if (!doc) return fieldHover(args);
+  if (!kind) return undefined;
+  const type = memberType(args.receiver, args.member, createContext());
+  const shown = type ? ` -> ${showType(type)}` : "";
+  return rule([
+    fence(`${kind}.${args.member}${shown}`),
+    sections([doc.doc, example(doc.example)]),
+    `**Built in** — on every ${code(kind)}.`,
+  ]);
+}
+
+/** A key the data itself carries: `p.age` on `{ name: string, age: number }`. */
+function fieldHover(args: { receiver: Type; member: string }): string | undefined {
+  const type = resolveMember(args.receiver, args.member, createContext());
+  if (!type) return undefined;
+  return rule([
+    fence(`${args.member}: ${showType(type)}`),
+    `**Field** of ${code(showType(args.receiver))}.`,
+    shaping(type),
+  ]);
+}
+
+/**
+ * How to get somewhere from a value nothing can know the shape of.
+ *
+ * `dynamic` is honest: a parsed response is whatever the far end sent, and no
+ * checker can say more. Honesty without a way forward reads as a dead end, so
+ * the hover spells out the way: name a type and annotate the binding.
+ */
+function shaping(type: Type): string | undefined {
+  if (type.kind !== "dynamic") return undefined;
+  return [
+    "**Shape it by naming one** — nothing can know what this holds, so say what you expect:",
+    fence("type Price { symbol: string, price: number }\nconst price: Price = res.json"),
+    "From there it reads as a `Price`: members are offered, and a wrong one is an error.",
+  ].join("\n\n");
+}
+
+function example(source: string | undefined): string | undefined {
+  return source ? labelled("Example", fence(source)) : undefined;
+}

package/src/hover/render-type-name.ts

@@ -0,0 +1,78 @@
+import { BUILTIN_TYPES, KIND_SPECS, TARGET_KINDS } from "@venn-lang/core";
+import type { RecordSpec, TypeSpec } from "@venn-lang/types";
+import { showSpec } from "@venn-lang/types";
+import type { SymbolCatalog } from "../catalog/index.js";
+import { code, fence, labelled, rule, sections } from "../markdown/index.js";
+
+/** What each decorator handle is a handle *on*, in the user's words. */
+const DECORATES: Readonly<Record<string, string>> = {
+  Fn: "a `fn` — its parameters, and what happens around a call to it",
+  Flow: "a `flow` — its title, and what happens around its body",
+  Step: "a `step` — its title, and what happens around its body",
+  Binding: "a `let` or `const` — the value it holds",
+  Type: "a `type` — the fields it declares",
+  Resource: "a `resource` — its name and its metadata",
+  Node: "any declaration at all, by name",
+};
+
+/**
+ * Hover for a type written in an annotation: `target: Fn`, `x: string`.
+ *
+ * A type name is where the reader most needs telling. Unanswered, `Fn` looks
+ * like a name someone made up rather than the surface the body is about to use.
+ */
+export function typeNameHover(name: string, catalog: SymbolCatalog): string | undefined {
+  return builtinHover(name) ?? kindHover(name) ?? publishedHover(name, catalog);
+}
+
+/** One of the language's own types: `string`, `duration`, `dynamic`. */
+function builtinHover(name: string): string | undefined {
+  const builtin = BUILTIN_TYPES[name];
+  if (!builtin) return undefined;
+  return rule([
+    fence(name),
+    sections([builtin.doc, labelled("Written", fence(builtin.example))]),
+    "**Built in** — part of the language, no `use` needed.",
+  ]);
+}
+
+/** One of the seven decorator handles. */
+function kindHover(name: string): string | undefined {
+  if (!TARGET_KINDS.includes(name as (typeof TARGET_KINDS)[number])) return undefined;
+  const spec = KIND_SPECS[name as keyof typeof KIND_SPECS];
+  return rule([
+    fence(`${name} — a decorator target`),
+    sections([
+      `Written as a \`deco\`'s first parameter, it decorates ${DECORATES[name] ?? "a declaration"}.`,
+      membersBlock(spec),
+    ]),
+    "The body runs at expansion time, before the program exists.",
+  ]);
+}
+
+/** A type a plugin published: `http.Response`, `db.Row`. */
+function publishedHover(name: string, catalog: SymbolCatalog): string | undefined {
+  const dot = name.indexOf(".");
+  if (dot < 0) return undefined;
+  const found = catalog
+    .typesIn(name.slice(0, dot))
+    .find((entry) => entry.name === name.slice(dot + 1));
+  if (!found) return undefined;
+  return rule([
+    fence(`${found.namespace}.${found.name}`),
+    membersBlock(found.spec),
+    `**Package** ${code(found.package)}`,
+  ]);
+}
+
+/**
+ * One line per member, rather than one line for all of them. A handle carries
+ * ten verbs, and rendered end to end they run past the edge of any hover.
+ */
+function membersBlock(spec: TypeSpec): string | undefined {
+  if (spec.kind !== "record") return undefined;
+  const fields = Object.entries((spec as RecordSpec).fields);
+  if (fields.length === 0) return undefined;
+  const lines = fields.map(([field, type]) => `- ${code(field)}: ${code(showSpec(type))}`);
+  return labelled("Offers", lines.join("\n"));
+}