@venn-lang/lsp 0.1.0

package/src/references/symbol.types.ts

@@ -0,0 +1,38 @@
+import type { AstNode } from "@venn-lang/core";
+
+/**
+ * What a name under the cursor turns out to be.
+ *
+ * The kinds differ in one thing that decides everything downstream: how far the
+ * name reaches. A `fragment`, a `deco` and a `pub fn` cross files, so finding
+ * every use means reading the workspace. A `const`, a parameter or a loop
+ * variable is bound in one place in one file, and a name spelled the same
+ * anywhere else is a different name: following it out of the file would report
+ * strangers as references.
+ */
+export type SymbolKind = "fragment" | "deco" | "fn" | "type" | "binding" | "external";
+
+export interface FoundSymbol {
+  kind: SymbolKind;
+  name: string;
+  /**
+   * The node that binds it, when the kind is file-scoped. Two `const`s of the
+   * same name in one file are two symbols, and this is what tells them apart.
+   */
+  binding?: AstNode;
+}
+
+/** One place a name appears, named by the property of the node that holds it. */
+export interface Occurrence {
+  node: AstNode;
+  property: string;
+  /** For a list-valued property: the names inside `import { a, b }`. */
+  index?: number;
+  /** Whether this is where the name is introduced, rather than used. */
+  declaration: boolean;
+}
+
+/** Whether a symbol's uses can be in another file at all. */
+export function crossesFiles(kind: SymbolKind): boolean {
+  return kind !== "binding" && kind !== "type";
+}

package/src/rename/declares-deco.ts

@@ -0,0 +1,15 @@
+import { type Document, isDecoDecl } from "@venn-lang/core";
+import type { LangiumDocument, LangiumDocuments } from "langium";
+
+/** Whether any open document declares a `deco` by this name. */
+export function declaresDeco(documents: LangiumDocuments, name: string): boolean {
+  for (const document of documents.all) {
+    const decls = rootOf(document)?.decls ?? [];
+    if (decls.some((decl) => isDecoDecl(decl) && decl.name === name)) return true;
+  }
+  return false;
+}
+
+function rootOf(document: LangiumDocument): Document | undefined {
+  return document.parseResult?.value as Document | undefined;
+}

package/src/rename/index.ts

@@ -0,0 +1 @@
+export { VennRenameProvider } from "./rename.js";

package/src/rename/rename.ts

@@ -0,0 +1,73 @@
+import type { LangiumDocument, LangiumDocuments } from "langium";
+import type { RenameProvider } from "langium/lsp";
+import type {
+  PrepareRenameParams,
+  Range,
+  RenameParams,
+  TextEdit,
+  WorkspaceEdit,
+} from "vscode-languageserver";
+import {
+  type FoundSymbol,
+  findOccurrences,
+  leafAt,
+  type Occurrence,
+  rangeOf,
+  symbolAt,
+} from "../references/index.js";
+import type { VennServices } from "../services/lsp.types.js";
+import { declaresDeco } from "./declares-deco.js";
+
+/**
+ * F2: rename a name wherever it means this one.
+ *
+ * Reads the same occurrences "find all references" reports, so the two cannot
+ * disagree. A rename that silently misses a use is worse than no rename at all.
+ */
+export class VennRenameProvider implements RenameProvider {
+  private readonly documents: LangiumDocuments;
+
+  constructor(services: VennServices) {
+    this.documents = services.shared.workspace.LangiumDocuments;
+  }
+
+  rename(document: LangiumDocument, params: RenameParams): WorkspaceEdit | undefined {
+    const symbol = this.wanted(document, params);
+    if (!symbol) return undefined;
+    const changes: Record<string, TextEdit[]> = {};
+    for (const found of findOccurrences({ symbol, document, documents: this.documents })) {
+      const edits = rewrites(found.occurrences, params.newName);
+      if (edits.length > 0) changes[found.uri] = edits;
+    }
+    return Object.keys(changes).length > 0 ? { changes } : undefined;
+  }
+
+  prepareRename(document: LangiumDocument, params: PrepareRenameParams): Range | undefined {
+    return this.wanted(document, params) ? leafAt(document, params.position)?.range : undefined;
+  }
+
+  /**
+   * The symbol under the cursor, when it is one this can rewrite.
+   *
+   * A built-in decorator has no source to rewrite, and changing one use of it
+   * would break the program while looking like a rename.
+   */
+  private wanted(
+    document: LangiumDocument,
+    params: { position: PrepareRenameParams["position"] },
+  ): FoundSymbol | undefined {
+    const symbol = symbolAt(document, params.position);
+    if (!symbol) return undefined;
+    if (symbol.kind === "deco" && !declaresDeco(this.documents, symbol.name)) return undefined;
+    return symbol;
+  }
+}
+
+function rewrites(occurrences: readonly Occurrence[], newName: string): TextEdit[] {
+  const edits: TextEdit[] = [];
+  for (const each of occurrences) {
+    const range = rangeOf(each);
+    if (range) edits.push({ range, newText: newName });
+  }
+  return edits;
+}

package/src/semantic/highlight-calls.ts

@@ -0,0 +1,56 @@
+import {
+  type ActionCall,
+  isActionCall,
+  isAnnotation,
+  isMatcherClause,
+  isRunStmt,
+} from "@venn-lang/core";
+import { GrammarUtils } from "langium";
+import { SemanticTokenModifiers, SemanticTokenTypes } from "vscode-languageserver";
+import type { HighlightArgs } from "./highlight.types.js";
+
+/** Everything that reads as an invocation: actions, matchers, fragments, annotations. */
+export function highlightCalls(args: HighlightArgs): void {
+  const { node, acceptor } = args;
+  if (isActionCall(node)) target(node, args);
+  else if (isMatcherClause(node))
+    acceptor({ node, property: "name", type: SemanticTokenTypes.method });
+  else if (isAnnotation(node))
+    acceptor({ node, property: "name", type: SemanticTokenTypes.decorator });
+  else if (isRunStmt(node)) runTarget(args);
+}
+
+function runTarget(args: HighlightArgs): void {
+  const { node, acceptor } = args;
+  if (!isRunStmt(node)) return;
+  // The same type the declaration carries: what `run` names is a fragment, and
+  // the two places the reader sees that name should agree about what it is.
+  acceptor({ node, property: "target", type: SemanticTokenTypes.macro });
+  if (node.bind) {
+    const type = SemanticTokenTypes.variable;
+    acceptor({ node, property: "bind", type, modifier: SemanticTokenModifiers.declaration });
+  }
+}
+
+// `http.get` is a single grammar token: colour the namespace and the action apart.
+function target(node: ActionCall, args: HighlightArgs): void {
+  const cst = GrammarUtils.findNodeForProperty(node.$cstNode, "target");
+  if (!cst) return;
+  const dot = node.target.indexOf(".");
+  const { line, character } = cst.range.start;
+  const known = dot > 0 && args.catalog.hasNamespace(node.target.slice(0, dot));
+  const modifier = known ? SemanticTokenModifiers.defaultLibrary : [];
+  if (dot > 0) {
+    const options = { line, char: character, length: dot, type: SemanticTokenTypes.namespace };
+    args.acceptor({ ...options, modifier });
+  }
+  const from = dot > 0 ? dot + 1 : 0;
+  const length = node.target.length - from;
+  args.acceptor({
+    line,
+    char: character + from,
+    length,
+    type: SemanticTokenTypes.function,
+    modifier,
+  });
+}

package/src/semantic/highlight-interpolation.ts

@@ -0,0 +1,135 @@
+import {
+  EXPRESSION_OFFSET,
+  type Expr,
+  type InterpolationSlot,
+  isCall,
+  isMember,
+  isPrelude,
+  isRef,
+  isStringLit,
+  type Member,
+  parseExpression,
+  scanInterpolations,
+} from "@venn-lang/core";
+import { AstUtils, type CstNode, GrammarUtils } from "langium";
+import type { SemanticTokenAcceptor } from "langium/lsp";
+import { type Range, SemanticTokenTypes } from "vscode-languageserver";
+import type { TextDocument } from "vscode-languageserver-textdocument";
+import type { SymbolCatalog } from "../catalog/index.js";
+import { pathOf } from "../document/index.js";
+import type { HighlightArgs } from "./highlight.types.js";
+
+interface Segment {
+  offset: number;
+  length: number;
+  type: string;
+}
+
+/**
+ * A string holding `${…}` is not one string token: the placeholders carry code,
+ * and code the editor paints as prose is code nobody can read.
+ *
+ * Returns whether it claimed the node, so the plain-literal pass leaves it
+ * alone: semantic tokens must not overlap.
+ */
+export function highlightInterpolation(args: HighlightArgs): boolean {
+  const { node, acceptor } = args;
+  if (!isStringLit(node) || !node.$cstNode) return false;
+  const raw = node.$cstNode.text;
+  const slots = scanInterpolations(raw);
+  if (slots.length === 0) return false;
+  const doc = AstUtils.getDocument(node).textDocument;
+  emitSegments({ acceptor, doc, raw, base: node.$cstNode.offset, slots, catalog: args.catalog });
+  return true;
+}
+
+interface EmitArgs {
+  acceptor: SemanticTokenAcceptor;
+  doc: TextDocument;
+  base: number;
+  catalog: SymbolCatalog;
+}
+
+function emitSegments(args: EmitArgs & { raw: string; slots: readonly InterpolationSlot[] }): void {
+  let cursor = 0;
+  for (const slot of args.slots) {
+    const tail = slot.sourceStart + slot.source.length;
+    emit(args, { offset: cursor, length: slot.start - cursor, type: SemanticTokenTypes.string });
+    emit(args, { offset: slot.start, length: 2, type: SemanticTokenTypes.operator });
+    for (const part of expressionSegments(slot, args.catalog)) emit(args, part);
+    emit(args, { offset: tail, length: slot.end - tail, type: SemanticTokenTypes.operator });
+    cursor = slot.end;
+  }
+  emit(args, { offset: cursor, length: args.raw.length - cursor, type: SemanticTokenTypes.string });
+}
+
+/** One token. Empty spans are skipped: a placeholder can sit flush to a quote. */
+function emit(args: EmitArgs, segment: Segment): void {
+  if (segment.length <= 0) return;
+  args.acceptor({
+    range: rangeAt(args.doc, args.base + segment.offset, segment.length),
+    type: segment.type,
+  });
+}
+
+function rangeAt(doc: TextDocument, offset: number, length: number): Range {
+  return { start: doc.positionAt(offset), end: doc.positionAt(offset + length) };
+}
+
+/**
+ * The tokens inside one placeholder, in document order. A placeholder that does
+ * not parse stays plain string; the validator is what complains about it.
+ */
+function expressionSegments(slot: InterpolationSlot, catalog: SymbolCatalog): Segment[] {
+  const expr = parseExpression(slot.source);
+  if (!expr) {
+    return [
+      { offset: slot.sourceStart, length: slot.source.length, type: SemanticTokenTypes.string },
+    ];
+  }
+  const shift = slot.sourceStart - EXPRESSION_OFFSET;
+  return namedParts(expr, catalog)
+    .map((part) => ({ ...part, offset: part.offset + shift }))
+    .sort((left, right) => left.offset - right.offset);
+}
+
+/**
+ * Classify the names inside a placeholder the same way code outside one is
+ * classified: a namespace head reads as a namespace, a called member as a
+ * method, a plain read as a property. Anything less and `${fmt.json(xs.map(f))}`
+ * comes out as flat prose.
+ */
+function namedParts(expr: Expr, catalog: SymbolCatalog): Segment[] {
+  const found: Segment[] = [];
+  for (const node of AstUtils.streamAst(expr)) {
+    if (isRef(node)) collect(found, node.$cstNode, headType(node.name, catalog));
+    else if (isMember(node)) {
+      const cst = GrammarUtils.findNodeForProperty(node.$cstNode, "member");
+      collect(found, cst, memberTokenType(node, catalog));
+    }
+  }
+  return found;
+}
+
+/** The head of `fmt.json` is a namespace; a prelude name reads as a function. */
+function headType(name: string, catalog: SymbolCatalog): string {
+  if (catalog.hasNamespace(name)) return SemanticTokenTypes.namespace;
+  return isPrelude(name) ? SemanticTokenTypes.function : SemanticTokenTypes.variable;
+}
+
+function memberTokenType(node: Member, catalog: SymbolCatalog): string {
+  const path = pathOf(node);
+  const dot = path?.indexOf(".") ?? -1;
+  if (path && dot > 0 && catalog.hasNamespace(path.slice(0, dot))) {
+    return catalog.action(path.slice(0, dot), path.slice(dot + 1))
+      ? SemanticTokenTypes.function
+      : SemanticTokenTypes.property;
+  }
+  return isCall(node.$container) && node.$container.callee === node
+    ? SemanticTokenTypes.method
+    : SemanticTokenTypes.property;
+}
+
+function collect(into: Segment[], cst: CstNode | undefined, type: string): void {
+  if (cst) into.push({ offset: cst.offset, length: cst.length, type });
+}

package/src/semantic/highlight-keywords.ts

@@ -0,0 +1,115 @@
+import {
+  type AstNode,
+  isBreakStmt,
+  isCaptureStmt,
+  isConfigDecl,
+  isContinueStmt,
+  isDatasetDecl,
+  isDecoDecl,
+  isDocument,
+  isExpectStmt,
+  isFactoryDecl,
+  isFlowDecl,
+  isFnDecl,
+  isForEachStmt,
+  isFragmentDecl,
+  isGroupDecl,
+  isIfStmt,
+  isLetStmt,
+  isLifecycleDecl,
+  isMatrixDecl,
+  isParallelStmt,
+  isRaceStmt,
+  isRepeatStmt,
+  isReportDecl,
+  isReturnStmt,
+  isRunStmt,
+  isStepDecl,
+  isTryStmt,
+  isTypeDecl,
+  isUseDecl,
+  isValueImport,
+  isWhileStmt,
+} from "@venn-lang/core";
+import type { SemanticTokenAcceptor } from "langium/lsp";
+import { SemanticTokenModifiers, SemanticTokenTypes } from "vscode-languageserver";
+
+// §23: `keyword.declaration` is the LSP `keyword` type plus the `declaration`
+// modifier, for the words that introduce a name. The rest are plain keywords.
+const DECLARING = new Set(["module", "use", "import", "fn", "deco", "fragment", "type"]);
+
+/** Emit a keyword token for each literal keyword this node owns. */
+export function highlightKeywords(node: AstNode, acceptor: SemanticTokenAcceptor): void {
+  for (const word of keywordsOf(node)) {
+    acceptor({
+      node,
+      keyword: word,
+      type: SemanticTokenTypes.keyword,
+      modifier: DECLARING.has(word) ? SemanticTokenModifiers.declaration : [],
+    });
+  }
+}
+
+function keywordsOf(node: AstNode): string[] {
+  return declarations(node) ?? bindings(node) ?? control(node) ?? [];
+}
+
+function declarations(node: AstNode): string[] | undefined {
+  if (isDocument(node)) return node.name ? ["module"] : [];
+  if (isUseDecl(node)) return node.alias ? ["use", "as"] : ["use"];
+  if (isValueImport(node)) return ["import", "from"];
+  if (isFlowDecl(node)) return ["flow"];
+  if (isFragmentDecl(node)) return ["fragment"];
+  if (isFnDecl(node)) return ["fn", "return"];
+  if (isDecoDecl(node)) return ["deco"];
+  if (isTypeDecl(node)) return ["type"];
+  if (isFactoryDecl(node)) return ["factory"];
+  if (isDatasetDecl(node)) return ["dataset"];
+  return undefined;
+}
+
+function bindings(node: AstNode): string[] | undefined {
+  if (isConfigDecl(node)) return ["config"];
+  if (isMatrixDecl(node)) return ["matrix"];
+  if (isReportDecl(node)) return ["report"];
+  if (isLetStmt(node)) return [node.kind];
+  if (isCaptureStmt(node)) return node.opts ? ["capture"] : ["capture"];
+  if (isRunStmt(node)) return node.bind ? ["run", "as"] : ["run"];
+  if (isExpectStmt(node)) return expectWords(node.modifier, node.negate);
+  return undefined;
+}
+
+function control(node: AstNode): string[] | undefined {
+  if (isStepDecl(node)) return ["step"];
+  if (isGroupDecl(node)) return ["group"];
+  if (isIfStmt(node)) return node.otherwise ? ["if", "else"] : ["if"];
+  if (isForEachStmt(node)) return ["forEach", "in"];
+  if (isRepeatStmt(node)) return node.index ? ["repeat", "as"] : ["repeat"];
+  if (isWhileStmt(node)) return ["while"];
+  if (isParallelStmt(node)) return ["parallel"];
+  if (isRaceStmt(node)) return ["race"];
+  if (isTryStmt(node)) return tryWords(node.handler, node.finalizer);
+  if (isLifecycleDecl(node)) return [node.hook ?? "on"];
+  return loops(node);
+}
+
+function loops(node: AstNode): string[] | undefined {
+  if (isReturnStmt(node)) return ["return"];
+  if (isBreakStmt(node)) return ["break"];
+  if (isContinueStmt(node)) return ["continue"];
+  return undefined;
+}
+
+function expectWords(modifier: string | undefined, negate: boolean | undefined): string[] {
+  const words = ["expect"];
+  if (modifier) words.push(modifier);
+  if (negate) words.push("not");
+  return words;
+}
+
+function tryWords(handler: unknown, finalizer: unknown): string[] {
+  const words = ["try"];
+  if (handler) words.push("catch");
+  if (finalizer) words.push("finally");
+  return words;
+}

package/src/semantic/highlight-literals.ts

@@ -0,0 +1,38 @@
+import {
+  isBoolLit,
+  isInstantLit,
+  isMapEntry,
+  isMember,
+  isNamedType,
+  isNullLit,
+  isNumberLit,
+  isRef,
+  isStringLit,
+} from "@venn-lang/core";
+import { SemanticTokenTypes } from "vscode-languageserver";
+import type { HighlightArgs } from "./highlight.types.js";
+import { highlightInterpolation } from "./highlight-interpolation.js";
+import { highlightPath } from "./highlight-paths.js";
+
+/** Literals, references and type names inside expressions. */
+export function highlightLiterals(args: HighlightArgs): void {
+  const { node, acceptor } = args;
+  if (isStringLit(node)) {
+    // An interpolated string is painted piece by piece; tokens cannot overlap.
+    if (!highlightInterpolation(args)) {
+      acceptor({ node, property: "value", type: SemanticTokenTypes.string });
+    }
+  } else if (isNumberLit(node))
+    acceptor({ node, property: "raw", type: SemanticTokenTypes.number });
+  else if (isInstantLit(node))
+    acceptor({ node, property: "value", type: SemanticTokenTypes.number });
+  else if (isBoolLit(node)) acceptor({ node, property: "value", type: SemanticTokenTypes.keyword });
+  // A stdlib path (`http.post`) is a call, not a variable; the catalog decides.
+  else if (isRef(node) || isMember(node)) {
+    if (!highlightPath(args) && isRef(node)) {
+      acceptor({ node, property: "name", type: SemanticTokenTypes.variable });
+    }
+  } else if (isNamedType(node)) acceptor({ node, property: "name", type: SemanticTokenTypes.type });
+  else if (isMapEntry(node)) acceptor({ node, property: "key", type: SemanticTokenTypes.property });
+  else if (isNullLit(node)) acceptor({ node, keyword: "null", type: SemanticTokenTypes.keyword });
+}

package/src/semantic/highlight-module.ts

@@ -0,0 +1,36 @@
+import { isDocument, isUseDecl, isValueImport, type ValueImport } from "@venn-lang/core";
+import { SemanticTokenModifiers, SemanticTokenTypes } from "vscode-languageserver";
+import type { HighlightArgs } from "./highlight.types.js";
+
+const DECLARATION = SemanticTokenModifiers.declaration;
+
+/**
+ * The module header. These are plain string properties in the grammar, not
+ * expression nodes, so nothing else would ever colour them.
+ */
+export function highlightModule(args: HighlightArgs): void {
+  const { node, acceptor } = args;
+  if (isDocument(node) && node.name) {
+    acceptor({ node, property: "name", type: SemanticTokenTypes.namespace });
+  } else if (isUseDecl(node)) {
+    acceptor({ node, property: "pkg", type: SemanticTokenTypes.string });
+    if (node.alias) {
+      const type = SemanticTokenTypes.namespace;
+      acceptor({ node, property: "alias", type, modifier: DECLARATION });
+    }
+  } else if (isValueImport(node)) {
+    importedNames(node, args);
+  }
+}
+
+function importedNames(node: ValueImport, args: HighlightArgs): void {
+  const { acceptor } = args;
+  acceptor({ node, property: "path", type: SemanticTokenTypes.string });
+  node.names.forEach((_name, index) => {
+    acceptor({ node, property: "names", index, type: SemanticTokenTypes.function });
+  });
+  const bound = node.wildcard ?? node.default;
+  if (!bound) return;
+  const property = node.wildcard ? "wildcard" : "default";
+  acceptor({ node, property, type: SemanticTokenTypes.namespace, modifier: DECLARATION });
+}

package/src/semantic/highlight-names.ts

@@ -0,0 +1,97 @@
+import {
+  isCaptureStmt,
+  isDatasetDecl,
+  isDecoDecl,
+  isFactoryDecl,
+  isFieldDecl,
+  isFlowDecl,
+  isFnDecl,
+  isForEachStmt,
+  isFragmentDecl,
+  isGroupDecl,
+  isLetStmt,
+  isLifecycleDecl,
+  isParam,
+  isRepeatStmt,
+  isStepDecl,
+  isTryStmt,
+  isTypeDecl,
+} from "@venn-lang/core";
+import { SemanticTokenModifiers, SemanticTokenTypes } from "vscode-languageserver";
+import type { HighlightArgs } from "./highlight.types.js";
+
+const DECLARATION = SemanticTokenModifiers.declaration;
+const CALLABLE = { type: SemanticTokenTypes.function, modifier: DECLARATION } as const;
+/**
+ * A `fragment` is invoked, not called: `run` expands it into the steps it
+ * declares, which the report then records. `macro` is the standard type that
+ * carries that meaning, and, crucially, themes draw it apart from a function.
+ * Painting the two alike would claim they are one kind of thing, which is the
+ * mistake the checker refuses.
+ */
+const FRAGMENT = { type: SemanticTokenTypes.macro, modifier: DECLARATION } as const;
+const VALUE = { type: SemanticTokenTypes.variable, modifier: DECLARATION } as const;
+
+/** Every name a declaration introduces, plus the titles that label a flow. */
+export function highlightNames(args: HighlightArgs): void {
+  callableNames(args);
+  decoratorNames(args);
+  valueNames(args);
+  memberNames(args);
+  boundNames(args);
+  titles(args);
+}
+
+// `deco memoize` and `@memoize` are one thing seen twice, so they colour alike.
+function decoratorNames(args: HighlightArgs): void {
+  const { node, acceptor } = args;
+  if (!isDecoDecl(node)) return;
+  acceptor({ node, property: "name", type: SemanticTokenTypes.decorator, modifier: DECLARATION });
+}
+
+function callableNames(args: HighlightArgs): void {
+  const { node, acceptor } = args;
+  if (isFragmentDecl(node)) acceptor({ node, property: "name", ...FRAGMENT });
+  else if (isFnDecl(node)) acceptor({ node, property: "name", ...CALLABLE });
+  else if (isFactoryDecl(node)) acceptor({ node, property: "name", ...CALLABLE });
+}
+
+function valueNames(args: HighlightArgs): void {
+  const { node, acceptor } = args;
+  if (isCaptureStmt(node)) acceptor({ node, property: "name", ...VALUE });
+  else if (isDatasetDecl(node)) acceptor({ node, property: "name", ...VALUE });
+  else if (isLetStmt(node)) acceptor({ node, property: "name", ...readonlyFor(node.kind) });
+}
+
+function memberNames(args: HighlightArgs): void {
+  const { node, acceptor } = args;
+  const type = SemanticTokenTypes.type;
+  if (isParam(node)) acceptor({ node, property: "name", type: SemanticTokenTypes.parameter });
+  else if (isTypeDecl(node)) acceptor({ node, property: "name", type, modifier: DECLARATION });
+  else if (isFieldDecl(node)) acceptor({ node, property: "name", type: "property" });
+}
+
+// Names bound by a construct rather than declared: loop variables, `catch err`, `on <event>`.
+function boundNames(args: HighlightArgs): void {
+  const { node, acceptor } = args;
+  if (isForEachStmt(node)) acceptor({ node, property: "item", ...VALUE });
+  else if (isRepeatStmt(node) && node.index) acceptor({ node, property: "index", ...VALUE });
+  else if (isTryStmt(node) && node.error) acceptor({ node, property: "error", ...VALUE });
+  else if (isLifecycleDecl(node) && node.event) {
+    acceptor({ node, property: "event", type: SemanticTokenTypes.enumMember });
+  }
+}
+
+function titles(args: HighlightArgs): void {
+  const { node, acceptor } = args;
+  const title = { property: "title", type: SemanticTokenTypes.string } as const;
+  if (isFlowDecl(node)) acceptor({ node, ...title });
+  else if (isStepDecl(node)) acceptor({ node, ...title });
+  else if (isGroupDecl(node)) acceptor({ node, ...title });
+}
+
+function readonlyFor(kind: string): { type: string; modifier: string[] } {
+  const modifier =
+    kind === "const" ? [DECLARATION, SemanticTokenModifiers.readonly] : [DECLARATION];
+  return { type: SemanticTokenTypes.variable, modifier };
+}