@venn-lang/core 0.1.0

package/src/expand/handles/common-verbs.ts

@@ -0,0 +1,40 @@
+import type { AstNode } from "langium";
+import { nativeFn } from "../../expr/index.js";
+import { writeMeta } from "../node-meta.js";
+import { swapNode } from "../swap-node.js";
+import type { VerbTable } from "./handle.types.js";
+
+/**
+ * What every kind answers to: what it is called, what it carries, and leaving.
+ *
+ * `meta` is how a decorator says something the grammar has no word for, the same
+ * channel `@retry(2)` uses, so a `deco` written in the language reaches exactly
+ * what a plugin's TypeScript decorator reaches.
+ */
+export const COMMON_VERBS: VerbTable = {
+  props: { name: (node) => nameOf(node) },
+  calls: {
+    meta: (node) =>
+      nativeFn((args) => {
+        writeMeta(node, String(args[0]), args[1]);
+        return null;
+      }),
+    remove: (node) =>
+      nativeFn(() => {
+        swapNode(node, undefined);
+        return null;
+      }),
+  },
+};
+
+/**
+ * A flow or a step has a title rather than a name, and answers with it.
+ *
+ * Empty for the things that have neither. `$type` would answer, but with a word
+ * out of the compiler's own tree: the one vocabulary this whole surface exists
+ * to keep out of the language.
+ */
+function nameOf(node: AstNode): string {
+  const named = node as { name?: string; title?: string };
+  return named.name ?? named.title ?? "";
+}

package/src/expand/handles/fn-verbs.ts

@@ -0,0 +1,58 @@
+import { nativeFn } from "../../expr/index.js";
+import type { FnDecl, Param, ParamList } from "../../generated/ast.js";
+import type { VerbTable } from "./handle.types.js";
+
+/**
+ * A function's shape: the parameters it takes and the name it answers to.
+ *
+ * Every one of these edits the declaration itself, before it is compiled, so a
+ * parameter added here is in scope for the body that was written without it.
+ * That is what `@inject("who")` depends on.
+ */
+export const FN_VERBS: VerbTable = {
+  props: { params: (node) => names(node as FnDecl) },
+  calls: {
+    addParam: (node) => nativeFn((args) => addParam(node as FnDecl, String(args[0]))),
+    removeParam: (node) => nativeFn((args) => removeParam(node as FnDecl, String(args[0]))),
+    rename: (node) => nativeFn((args) => rename(node as FnDecl, String(args[0]))),
+  },
+};
+
+function names(decl: FnDecl): string[] {
+  return (decl.params?.params ?? []).map((param) => param.name);
+}
+
+function addParam(decl: FnDecl, name: string): null {
+  const list = paramList(decl);
+  if (!list.params.some((param) => param.name === name)) list.params.push(param(list, name));
+  return null;
+}
+
+function removeParam(decl: FnDecl, name: string): null {
+  const list = decl.params;
+  if (!list) return null;
+  list.params = list.params.filter((param) => param.name !== name);
+  return null;
+}
+
+function rename(decl: FnDecl, name: string): null {
+  decl.name = name;
+  return null;
+}
+
+/** A function written `fn f()` has no list at all until something adds to it. */
+function paramList(decl: FnDecl): ParamList {
+  if (decl.params) return decl.params;
+  const list = node<ParamList>({ $type: "ParamList", params: [] }, decl, "params");
+  decl.params = list;
+  return list;
+}
+
+function param(list: ParamList, name: string): Param {
+  return node<Param>({ $type: "Param", annotations: [], name }, list, "params");
+}
+
+/** A synthesized node, containered the way the parser would have containered it. */
+function node<T>(shape: object, container: object, property: string): T {
+  return { ...shape, $container: container, $containerProperty: property } as T;
+}

package/src/expand/handles/handle.types.ts

@@ -0,0 +1,33 @@
+import type { AstNode } from "langium";
+
+/**
+ * What a `deco` decorates, written as the type of its first parameter.
+ *
+ * These are the words the language uses about itself. A decorator author says
+ * `target: Fn` and never learns that the compiler calls that node a `FnDecl`,
+ * which is the whole reason this vocabulary exists.
+ */
+export type TargetKind = "Fn" | "Flow" | "Step" | "Binding" | "Type" | "Node";
+
+/**
+ * The value a decorator body holds for its target: named members over the real
+ * declaration. Reading one may refuse, so the members are defined as getters.
+ */
+export type TargetHandle = Record<string, unknown>;
+
+/** What a handle is, for a caller holding one: its kind and every name it answers to. */
+export interface HandleSurface {
+  readonly kind: TargetKind;
+  readonly offered: readonly string[];
+}
+
+/** How one member is built, given the node the handle stands for. */
+export type Verb = (node: AstNode) => unknown;
+
+/** A slice of the handle surface: what to read, and what to call. */
+export interface VerbTable {
+  /** Members read as values: `.name`, `.params`, `.title`, `.value`, `.fields`. */
+  readonly props: Readonly<Record<string, Verb>>;
+  /** Members that do something: `.meta`, `.remove`, `.addParam`, `.wrap`. */
+  readonly calls: Readonly<Record<string, Verb>>;
+}

package/src/expand/handles/index.ts

@@ -0,0 +1,4 @@
+export type { HandleSurface, TargetHandle, TargetKind, Verb, VerbTable } from "./handle.types.js";
+export { isTargetKind, kindOf, TARGET_KINDS } from "./kind-of.js";
+export { handleSurface, makeHandle } from "./make-handle.js";
+export { missingVerb, verbRefusal } from "./missing-verb.js";

package/src/expand/handles/kind-of.ts

@@ -0,0 +1,36 @@
+import type { AstNode } from "langium";
+import type { TargetKind } from "./handle.types.js";
+
+/** Every kind a `deco` may name, in the order a diagnostic should list them. */
+export const TARGET_KINDS: readonly TargetKind[] = [
+  "Fn",
+  "Flow",
+  "Step",
+  "Binding",
+  "Type",
+  "Node",
+];
+
+/**
+ * The only place the two vocabularies meet.
+ *
+ * `Node` is absent on purpose: it is not one node type, it is the absence of a
+ * restriction, so it maps to no `$type` and to every one.
+ */
+const BY_TYPE: Readonly<Record<string, TargetKind>> = {
+  FnDecl: "Fn",
+  FlowDecl: "Flow",
+  StepDecl: "Step",
+  LetStmt: "Binding",
+  TypeDecl: "Type",
+};
+
+/** What kind of thing a node is, in the language's own words. */
+export function kindOf(node: AstNode): TargetKind {
+  return BY_TYPE[node.$type] ?? "Node";
+}
+
+/** Whether a written type name is one of the kinds. */
+export function isTargetKind(name: string): name is TargetKind {
+  return (TARGET_KINDS as readonly string[]).includes(name);
+}

package/src/expand/handles/make-handle.ts

@@ -0,0 +1,100 @@
+import type { AstNode } from "langium";
+import { BODY_AROUND_VERBS, CALL_AROUND_VERBS } from "./around-verbs.js";
+import { BINDING_VERBS } from "./binding-verbs.js";
+import { COMMON_VERBS } from "./common-verbs.js";
+import { FN_VERBS } from "./fn-verbs.js";
+import type { HandleSurface, TargetHandle, TargetKind, VerbTable } from "./handle.types.js";
+import { missingVerb } from "./missing-verb.js";
+import { RUNNABLE_VERBS } from "./runnable-verbs.js";
+import { TYPE_VERBS } from "./type-verbs.js";
+
+/** What each kind offers, assembled from the slices it shares with the others. */
+const SURFACE: Readonly<Record<TargetKind, readonly VerbTable[]>> = {
+  Fn: [COMMON_VERBS, FN_VERBS, CALL_AROUND_VERBS],
+  Flow: [COMMON_VERBS, RUNNABLE_VERBS, BODY_AROUND_VERBS],
+  Step: [COMMON_VERBS, RUNNABLE_VERBS, BODY_AROUND_VERBS],
+  Binding: [COMMON_VERBS, BINDING_VERBS],
+  Type: [COMMON_VERBS, TYPE_VERBS],
+  Node: [COMMON_VERBS],
+};
+
+/** Every verb any kind has, so a kind without one can say so instead of vanishing. */
+const ALL_VERBS: readonly string[] = [
+  ...new Set(Object.values(SURFACE).flatMap((tables) => tables.flatMap(namesOf))),
+];
+
+/**
+ * The typed mutable handle a decorator holds: verbs over the real declaration.
+ *
+ * Built like the native members of a list or a string, as a table of names and a
+ * value produced on read, because that is what it is: the built-in members of
+ * one more kind of value, whose receiver happens to be a piece of the program
+ * rather than a piece of its data.
+ *
+ * Every verb any kind has is installed. The ones this kind lacks throw a
+ * `ProblemError` naming the surface it does offer, so a reach for the wrong verb
+ * is refused rather than read as nothing.
+ */
+export function makeHandle(args: { node: AstNode; kind: TargetKind }): TargetHandle {
+  const handle: TargetHandle = {};
+  const offered = install(handle, args);
+  for (const verb of ALL_VERBS) {
+    if (!offered.has(verb)) refuse(handle, { verb, kind: args.kind, offered });
+  }
+  brand(handle, { kind: args.kind, offered: [...offered] });
+  return handle;
+}
+
+const HANDLE = Symbol("venn.handle");
+
+/**
+ * What this handle answers to, or nothing when the value is not one.
+ *
+ * A getter can only refuse a name some kind has; a name no kind has would still
+ * read as nothing. The caller that reaches for one asks here instead, so
+ * `target.wobble` is refused in the same sentence as `target.addParam`.
+ */
+export function handleSurface(value: unknown): HandleSurface | undefined {
+  if (typeof value !== "object" || value === null) return undefined;
+  return (value as { [HANDLE]?: HandleSurface })[HANDLE];
+}
+
+function brand(handle: TargetHandle, surface: HandleSurface): void {
+  Object.defineProperty(handle, HANDLE, { value: surface });
+}
+
+function install(handle: TargetHandle, args: { node: AstNode; kind: TargetKind }): Set<string> {
+  const offered = new Set<string>();
+  for (const table of SURFACE[args.kind]) {
+    for (const [verb, make] of entriesOf(table)) {
+      offered.add(verb);
+      define(handle, verb, () => make(args.node));
+    }
+  }
+  return offered;
+}
+
+function refuse(
+  handle: TargetHandle,
+  args: { verb: string; kind: TargetKind; offered: Set<string> },
+): void {
+  define(handle, args.verb, () => {
+    throw missingVerb(args);
+  });
+}
+
+/**
+ * Non-enumerable on purpose: a handle is verbs, not data, so serialising one
+ * must not run every getter, including the ones whose whole job is to refuse.
+ */
+function define(handle: TargetHandle, verb: string, get: () => unknown): void {
+  Object.defineProperty(handle, verb, { get, configurable: true });
+}
+
+function entriesOf(table: VerbTable): [string, (node: AstNode) => unknown][] {
+  return [...Object.entries(table.props), ...Object.entries(table.calls)];
+}
+
+function namesOf(table: VerbTable): string[] {
+  return [...Object.keys(table.props), ...Object.keys(table.calls)];
+}

package/src/expand/handles/missing-verb.ts

@@ -0,0 +1,27 @@
+import { buildProblem, CODES } from "../../codes/index.js";
+import { ProblemError } from "../../problem/index.js";
+import type { TargetKind } from "./handle.types.js";
+
+/** Filled in by the body runner, which knows which statement asked. */
+const NO_SPAN = { uri: "", offset: 0, length: 0, line: 1, column: 1 };
+
+/**
+ * The verb this kind does not have, answered with the ones it does.
+ *
+ * Never `undefined`, never a `TypeError`: a decorator that reaches for
+ * `.addParam` on a flow has made a mistake the language can name, and naming it
+ * beside the whole surface of that kind is the shortest path to the fix.
+ */
+export function missingVerb(args: {
+  verb: string;
+  kind: TargetKind;
+  offered: Iterable<string>;
+}): ProblemError {
+  const has = [...args.offered].join(", ");
+  return verbRefusal(`A ${args.kind} has no \`${args.verb}\` — it has ${has}.`);
+}
+
+/** A verb this target cannot honour, for a reason of its own. */
+export function verbRefusal(title: string): ProblemError {
+  return new ProblemError(buildProblem({ spec: CODES.VN2017_DECO_VERB, span: NO_SPAN, title }));
+}

package/src/expand/handles/runnable-verbs.ts

@@ -0,0 +1,13 @@
+import type { FlowDecl, StepDecl } from "../../generated/ast.js";
+import type { VerbTable } from "./handle.types.js";
+
+/**
+ * What a flow and a step have beyond the common surface: the sentence they are
+ * known by. Read-only, because a title is what the reporter, the `--flow` filter
+ * and the trace all key off, and renaming it mid-expansion would leave every one
+ * of them pointing at a run nobody asked for.
+ */
+export const RUNNABLE_VERBS: VerbTable = {
+  props: { title: (node) => (node as FlowDecl | StepDecl).title },
+  calls: {},
+};

package/src/expand/handles/type-verbs.ts

@@ -0,0 +1,56 @@
+import { nativeFn } from "../../expr/index.js";
+import type { FieldDecl, TypeBody, TypeDecl, TypeRef } from "../../generated/ast.js";
+import type { VerbTable } from "./handle.types.js";
+import { verbRefusal } from "./missing-verb.js";
+
+/** The fields of a `type { … }`, and the two ways to change the set. */
+export const TYPE_VERBS: VerbTable = {
+  props: { fields: (node) => (bodyOf(node as TypeDecl)?.fields ?? []).map((one) => one.name) },
+  calls: {
+    addField: (node) =>
+      nativeFn((args) => addField(node as TypeDecl, String(args[0]), String(args[1] ?? "string"))),
+    removeField: (node) => nativeFn((args) => removeField(node as TypeDecl, String(args[0]))),
+  },
+};
+
+function bodyOf(decl: TypeDecl): TypeBody | undefined {
+  return decl.body;
+}
+
+/** `type Id = string` has no fields to change, and says so rather than growing one. */
+function requireBody(decl: TypeDecl, verb: string): TypeBody {
+  const body = bodyOf(decl);
+  if (body) return body;
+  throw verbRefusal(`\`${decl.name}\` is an alias, so \`${verb}\` has no fields to change.`);
+}
+
+function addField(decl: TypeDecl, name: string, type: string): null {
+  const body = requireBody(decl, "addField");
+  if (body.fields.some((field) => field.name === name)) return null;
+  body.fields.push(field({ body, name, type }));
+  return null;
+}
+
+function removeField(decl: TypeDecl, name: string): null {
+  const body = requireBody(decl, "removeField");
+  body.fields = body.fields.filter((one) => one.name !== name);
+  return null;
+}
+
+function field(args: { body: TypeBody; name: string; type: string }): FieldDecl {
+  return {
+    $type: "FieldDecl",
+    $container: args.body,
+    $containerProperty: "fields",
+    annotations: [],
+    name: args.name,
+    optional: false,
+    fieldType: typeRef(args.type),
+  } as unknown as FieldDecl;
+}
+
+function typeRef(name: string): TypeRef {
+  const ref = { $type: "TypeRef", members: [] } as unknown as TypeRef;
+  ref.members.push({ $type: "NamedType", $container: ref, name, args: [] } as unknown as never);
+  return ref;
+}

package/src/expand/index.ts

@@ -0,0 +1,40 @@
+export { acceptedKinds, decoTarget } from "./accepted-kinds.js";
+export type {
+  DecoBodyArgs,
+  DecoSignature,
+  DocumentDecoArgs,
+  ImportedDeco,
+  SignatureResult,
+} from "./deco/index.js";
+export { decoCannotCall, decoDecorator, readSignature, withDocumentDecos } from "./deco/index.js";
+export { decorateCallable } from "./decorate-callable.js";
+export type { Decorations } from "./decorations.js";
+export { AROUND_KEYS, addDecoration, readDecorations } from "./decorations.js";
+export { expand } from "./expand.js";
+export type {
+  DecoratedNode,
+  DecoratorDefinition,
+  DecoratorSource,
+  ExpandContext,
+  ExpandResult,
+  NodeMeta,
+} from "./expand.types.js";
+export type { HandleSurface, TargetHandle, TargetKind } from "./handles/index.js";
+export {
+  handleSurface,
+  isTargetKind,
+  kindOf,
+  makeHandle,
+  TARGET_KINDS,
+} from "./handles/index.js";
+export { metaOf, readMeta, writeMeta } from "./node-meta.js";
+export { spanOf } from "./node-span.js";
+export { swapNode } from "./swap-node.js";
+export {
+  everyKindWritten,
+  kindWords,
+  nodeWord,
+  wrongKind,
+  wrongKindTitle,
+  wrongTargetTitle,
+} from "./wrong-kind.js";

package/src/expand/make-context.ts

@@ -0,0 +1,69 @@
+import type { AstNode } from "langium";
+import { buildProblem } from "../codes/index.js";
+import { evaluate } from "../expr/index.js";
+import type { Annotation } from "../generated/ast.js";
+import { isRef } from "../generated/ast.js";
+import type { Problem } from "../problem/index.js";
+import type { ExpandContext } from "./expand.types.js";
+import { writeMeta } from "./node-meta.js";
+import { spanOf } from "./node-span.js";
+import { swapNode } from "./swap-node.js";
+
+/**
+ * The handle one decorator gets on one node.
+ *
+ * `replace` and `remove` write straight into the parent's own array or field.
+ * That is the tree the checker and the runtime read, not a copy of it, so a
+ * decorator's rewrite is indistinguishable downstream from source the author
+ * wrote by hand.
+ */
+export function makeContext(args: {
+  node: AstNode;
+  annotation: Annotation;
+  uri?: string;
+  problems: Problem[];
+}): ExpandContext {
+  const { node, annotation } = args;
+  return {
+    node,
+    parent: node.$container,
+    args: evaluatedArgs(annotation),
+    // The expressions as written, for a decorator that needs the tree and not
+    // the value: a macro reads its argument, it does not compute it.
+    written: (annotation.args?.args ?? []).map((arg) => arg.value),
+    replace: (next) => swapNode(node, next),
+    remove: () => swapNode(node, undefined),
+    meta: (key, value) => writeMeta(node, key, value),
+    reject: (rejection) => args.problems.push(problemOf({ ...args, ...rejection })),
+  };
+}
+
+/**
+ * A decorator's arguments are evaluated once, here, against nothing.
+ *
+ * They are written before the program runs and cannot depend on it: `@retry(2)`
+ * is part of the shape of the program, not of its execution. That is also why a
+ * bare name inside one is a *word* and not a variable. `@tags(smoke)` and
+ * `@scope(worker)` name a tag and a lifetime, and nothing exists yet for them to
+ * refer to.
+ */
+function evaluatedArgs(annotation: Annotation): unknown[] {
+  const nothing = { lookup: () => undefined };
+  return (annotation.args?.args ?? []).map((arg) =>
+    isRef(arg.value) ? arg.value.name : evaluate(arg.value, nothing),
+  );
+}
+
+/** A decorator names its own code, so a plugin can refuse a program in its own terms. */
+function problemOf(args: {
+  annotation: Annotation;
+  uri?: string;
+  code: string;
+  title: string;
+}): Problem {
+  return buildProblem({
+    spec: { code: args.code, severity: "error" },
+    span: spanOf(args.annotation, args.uri ?? "memory://inline.vn"),
+    title: args.title,
+  });
+}

package/src/expand/node-meta.ts

@@ -0,0 +1,30 @@
+import type { NodeMeta } from "./expand.types.js";
+
+/** Where a decorator's leavings live on the node. */
+const META = "$meta";
+
+/**
+ * What the decorators left on this node, or nothing.
+ *
+ * Metadata rather than a rewrite is how a decorator says something the grammar
+ * has no word for. `@retry(2)` cannot be expressed as a tree of existing
+ * statements, so it is expressed as a fact about one.
+ */
+export function metaOf(node: object): NodeMeta | undefined {
+  return (node as { $meta?: NodeMeta }).$meta;
+}
+
+/** Read one key, typed by the caller who knows what it wrote. */
+export function readMeta<T>(node: object, key: string): T | undefined {
+  return metaOf(node)?.[key] as T | undefined;
+}
+
+/** Attach a fact to a node. Non-enumerable, so it never lands in a serialised AST. */
+export function writeMeta(node: object, key: string, value: unknown): void {
+  const existing = metaOf(node);
+  if (existing) {
+    existing[key] = value;
+    return;
+  }
+  Object.defineProperty(node, META, { value: { [key]: value }, configurable: true });
+}

package/src/expand/node-span.ts

@@ -0,0 +1,17 @@
+import type { AstNode } from "langium";
+import type { Span } from "../problem/index.js";
+
+/** Where a node sits in its file, for a Problem that has to point at it. */
+export function spanOf(node: AstNode, uri: string): Span {
+  const cst = node.$cstNode as
+    | { offset: number; length: number; range?: { start: { line: number; character: number } } }
+    | undefined;
+  const start = cst?.range?.start;
+  return {
+    uri,
+    offset: cst?.offset ?? 0,
+    length: cst?.length ?? 0,
+    line: (start?.line ?? 0) + 1,
+    column: (start?.character ?? 0) + 1,
+  };
+}

package/src/expand/swap-node.ts

@@ -0,0 +1,28 @@
+import type { AstNode } from "langium";
+
+/**
+ * Put `next` where `node` is, in its parent's list or in the field holding it.
+ * Passing nothing takes the node out of the program entirely.
+ *
+ * The write goes straight into the parent's own array or field. That is the tree
+ * the checker and the runtime read, not a copy of it, so a decorator's rewrite
+ * is indistinguishable downstream from source the author wrote.
+ */
+export function swapNode(node: AstNode, next: AstNode | undefined): void {
+  const parent = node.$container as Record<string, unknown> | undefined;
+  const property = node.$containerProperty;
+  if (!parent || !property) return;
+  const held = parent[property];
+  if (Array.isArray(held)) {
+    swapInList(held, node, next);
+    return;
+  }
+  parent[property] = next;
+}
+
+function swapInList(list: unknown[], node: AstNode, next: AstNode | undefined): void {
+  const at = list.indexOf(node);
+  if (at < 0) return;
+  if (next) list[at] = next;
+  else list.splice(at, 1);
+}

package/src/expand/wrong-kind.ts

@@ -0,0 +1,102 @@
+import type { AstNode } from "langium";
+import { kindOf, TARGET_KINDS, type TargetKind } from "./handles/index.js";
+
+/** What each kind is called in a sentence someone reads. */
+const KIND_WORDS: Readonly<Record<TargetKind, string>> = {
+  Fn: "a function",
+  Flow: "a flow",
+  Step: "a step",
+  Binding: "a binding",
+  Type: "a type",
+  Node: "anything",
+};
+
+/**
+ * What a node is called in that same sentence.
+ *
+ * Wider than {@link KIND_WORDS} on purpose: a fragment and a group have no kind
+ * of their own, but a message that cannot name what the author actually wrote
+ * is a message that sends them looking for it.
+ */
+const NODE_WORDS: Readonly<Record<string, string>> = {
+  FnDecl: "a function",
+  FlowDecl: "a flow",
+  StepDecl: "a step",
+  GroupDecl: "a group",
+  LetStmt: "a binding",
+  TypeDecl: "a type",
+  FragmentDecl: "a fragment",
+  DecoDecl: "a decorator",
+  FieldDecl: "a field",
+  Param: "a parameter",
+  ActionCall: "a call",
+};
+
+/** A list of alternatives, read the way it is spoken: "a flow, a step or a group". */
+function oneOf(words: readonly string[]): string {
+  const all = [...words];
+  const last = all.pop();
+  return all.length === 0 ? (last ?? "") : `${all.join(", ")} or ${last}`;
+}
+
+/** The kinds a signature allows, read as prose: "a function or a flow". */
+export function kindWords(kinds: readonly TargetKind[]): string {
+  return oneOf(kinds.map((kind) => KIND_WORDS[kind]));
+}
+
+/** Every kind, listed for an author who has to pick one. */
+export function everyKindWritten(): string {
+  return oneOf(TARGET_KINDS);
+}
+
+/**
+ * What a node is called for someone reading a message.
+ *
+ * A plugin's decorator may name any node it is able to read, so an unlisted one
+ * has its word derived rather than printed: `FlowDecl` is the compiler talking
+ * to itself, and a word nobody ever typed has no business on a user's screen.
+ */
+export function nodeWord(type: string): string {
+  return NODE_WORDS[type] ?? `a ${type.replace(/(Decl|Stmt|Expr|Lit)$/, "").toLowerCase()}`;
+}
+
+/** "@memoize decorates a function, and this is a flow." */
+export function wrongKindTitle(args: {
+  name: string;
+  kinds: readonly TargetKind[];
+  node: AstNode;
+}): string {
+  return `@${args.name} decorates ${kindWords(args.kinds)}, and this is ${nodeWord(args.node.$type)}.`;
+}
+
+/**
+ * The same sentence for a plugin's decorator, whose reach is a list of node
+ * types. It still reads as prose: what the author wrote is what they are told
+ * about, and the list they never wrote stays out of it.
+ */
+export function wrongTargetTitle(args: {
+  name: string;
+  targets: readonly string[];
+  node: AstNode;
+}): string {
+  const allowed = oneOf([...new Set(args.targets.map(nodeWord))]);
+  return `@${args.name} decorates ${allowed}, and this is ${nodeWord(args.node.$type)}.`;
+}
+
+/**
+ * Why a `@name` does not belong on this node, if it does not.
+ *
+ * Nothing when the signature never said which kinds it takes: that is a fault
+ * committed once, where the `deco` is written, and repeating it at every use
+ * site would bury the one message that can be acted on.
+ */
+export function wrongKind(args: {
+  name: string;
+  kinds: readonly TargetKind[];
+  node: AstNode;
+}): string | undefined {
+  const { kinds, node } = args;
+  if (kinds.length === 0 || kinds.includes("Node") || kinds.includes(kindOf(node)))
+    return undefined;
+  return wrongKindTitle(args);
+}