@telorun/ide-support 0.15.0 → 0.16.0

package/dist/semantic-tokens/build-semantic-tokens.js

@@ -1,55 +1,99 @@
 import { buildLineOffsets, offsetToPosition, parseToAst, } from "@telorun/analyzer";
+import { celSegmentTokens } from "../cel/tokens.js";
+import { docIdentity } from "../doc-identity.js";
 import { scalarString } from "../completions/resolve-node.js";
 import { CAPABILITY_VALUES } from "../completions/valid-capabilities.js";
 const CAPABILITIES = new Set(CAPABILITY_VALUES);
+/** Append one key segment to a concrete path (`routes[0]` + `handler`). */
+function joinKey(concrete, key) {
+    return concrete ? `${concrete}.${key}` : key;
+}
 /** Registry-aware semantic tokens: a `kind:` value that resolves to a known
  *  definition is a `type`; a `capability:` value is an `interface`; a `!ref`
- *  target is a `variable`. Everything else (structure, CEL, tags) is left to the
- *  TextMate grammar. Ref targets are colored here rather than in the grammar
- *  because a `!ref` after a `key:` is tokenized by the bundled YAML grammar
- *  before a Telo pattern can claim it — the AST sees it unambiguously. An
- *  unresolved kind gets no token, so a typo stays uncolored — a quiet signal
- *  that pairs with the analyzer's `UNDEFINED_KIND` diagnostic. */
-export function buildSemanticTokens(text, registry, docs) {
+ *  target is a `variable`. Ref targets are colored here rather than in the
+ *  grammar because a `!ref` after a `key:` is tokenized by the bundled YAML
+ *  grammar before a Telo pattern can claim it — the AST sees it unambiguously.
+ *  An unresolved kind gets no token, so a typo stays uncolored — a quiet signal
+ *  that pairs with the analyzer's `UNDEFINED_KIND` diagnostic.
+ *
+ *  The inside of a `!cel` / `${{ }}` body is colored here too, and for the same
+ *  reason one level down: a grammar can only know the roots someone hardcoded
+ *  into it, while `scopeQuery` knows what is in scope at this exact site. With
+ *  no query the names are colored syntactically instead — a CEL body must never
+ *  read as a plain string, which is what the stock YAML grammar makes of it. */
+export function buildSemanticTokens(text, registry, docs, analysis) {
     const astDocs = docs ?? parseToAst(text);
     const lineOffsets = buildLineOffsets(text);
     const tokens = [];
-    const emit = (node, type) => {
-        if (!node)
-            return;
-        const start = offsetToPosition(node.range[0], lineOffsets);
-        const end = offsetToPosition(node.range[1], lineOffsets);
-        // Kind / capability values never span lines; a clamped single-line token.
+    const emitRange = (range, type) => {
+        const start = offsetToPosition(range[0], lineOffsets);
+        const end = offsetToPosition(range[1], lineOffsets);
+        // Kind / capability values and CEL identifiers never span lines; a clamped
+        // single-line token.
         if (start.line !== end.line)
             return;
-        tokens.push({ line: start.line, character: start.character, length: end.character - start.character, type });
+        tokens.push({
+            line: start.line,
+            character: start.character,
+            length: end.character - start.character,
+            type,
+        });
     };
-    const walk = (node) => {
-        if (node.kind === "map") {
-            for (const pair of node.entries) {
-                const key = scalarString(pair.key);
-                const value = scalarString(pair.value);
-                if (key === "kind" && value && registry?.resolveDefinition(value)) {
-                    emit(pair.value, "type");
+    const emit = (node, type) => {
+        if (node)
+            emitRange(node.range, type);
+    };
+    for (const doc of astDocs) {
+        if (!doc.root)
+            continue;
+        // The scope is resolved per SITE. `scopeAt` caches per (resource, path) for
+        // the analysis's lifetime, which is what keeps a whole-file colourizer off
+        // the per-keystroke cost of rebuilding a context-matched environment.
+        const identity = docIdentity(doc);
+        const scopeQuery = analysis?.celScope;
+        const resource = scopeQuery?.resourceFor(identity.kind, identity.name);
+        const scopeAt = (path) => scopeQuery && resource ? scopeQuery.scopeAt(resource, path) : undefined;
+        const celTokens = (node, path) => {
+            const segments = node.celSegments();
+            if (segments.length === 0)
+                return;
+            const scope = scopeAt(path);
+            for (const segment of segments) {
+                for (const span of celSegmentTokens(text, segment, scope))
+                    emitRange(span.range, span.type);
+            }
+        };
+        const walk = (node, concrete) => {
+            if (node.kind === "map") {
+                for (const pair of node.entries) {
+                    const key = scalarString(pair.key);
+                    const value = scalarString(pair.value);
+                    if (key === "kind" && value && registry?.resolveDefinition(value)) {
+                        emit(pair.value, "type");
+                    }
+                    else if (key === "capability" && value && CAPABILITIES.has(value)) {
+                        emit(pair.value, "interface");
+                    }
+                    if (pair.value)
+                        walk(pair.value, key != null ? joinKey(concrete, key) : concrete);
                 }
-                else if (key === "capability" && value && CAPABILITIES.has(value)) {
-                    emit(pair.value, "interface");
+                return;
+            }
+            if (node.kind === "seq") {
+                // Indices are kept: a CEL site's scope is addressed per item, so an
+                // index-erased path resolves the wrong context or none.
+                node.items.forEach((item, index) => walk(item, `${concrete}[${index}]`));
+                return;
+            }
+            if (node.kind === "scalar") {
+                if (node.tag === "!ref") {
+                    emit(node, "variable");
+                    return;
                 }
-                if (pair.value)
-                    walk(pair.value);
+                celTokens(node, concrete);
             }
-        }
-        else if (node.kind === "seq") {
-            for (const item of node.items)
-                walk(item);
-        }
-        else if (node.kind === "scalar" && node.tag === "!ref") {
-            emit(node, "variable");
-        }
-    };
-    for (const doc of astDocs) {
-        if (doc.root)
-            walk(doc.root);
+        };
+        walk(doc.root, "");
     }
     return tokens;
 }

package/dist/types.d.ts

@@ -33,12 +33,32 @@ export interface HoverResult {
 }
 /** Semantic token type names emitted by `buildSemanticTokens`. Kept to the
  *  standard VS Code / LSP set so hosts register them against a stock legend and
- *  every theme colors them without extra configuration. `type` marks a resolved
- *  resource kind; `interface` marks a capability value; `variable` marks a
- *  `!ref` target. */
-export type SemanticTokenType = "type" | "interface" | "variable";
+ *  every theme colors them without extra configuration.
+ *
+ *  Manifest structure: `type` marks a resolved resource kind; `interface` marks
+ *  a capability value; `variable` marks a `!ref` target.
+ *
+ *  Inside a CEL body: `namespace` marks the ROOT of a chain, `property` a member
+ *  it can resolve, `function` a call, and `number` / `string` / `keyword` /
+ *  `operator` the syntax around them. A CEL name the scope CANNOT confirm gets
+ *  no token — the same quiet signal an unresolved `kind:` gives, pairing with
+ *  the analyzer's `CEL_UNKNOWN_FIELD`.
+ *
+ *  The root is a `namespace` rather than a `variable` because colour encodes
+ *  what a symbol IS, which is the invariant every language holds to — and a CEL
+ *  root is not data the author declared, it is a scope the runtime injects
+ *  (`request`, `steps`, `variables`, `self`). Members are uniformly `property`
+ *  however deep, so a chain reads as scope · path. Colouring by the SHAPE of the
+ *  value behind a name — object vs scalar — was considered and rejected: it is
+ *  type-directed highlighting, so the palette becomes a type legend, a name
+ *  changes colour as analysis resolves, and it says nothing exactly where the
+ *  scope declares no shape. */
+export type SemanticTokenType = "type" | "interface" | "variable" | "property" | "function" | "number" | "string" | "keyword" | "operator" | "namespace";
 /** The legend a host registers before mapping `buildSemanticTokens` output. The
- *  numeric token-type of each `SemanticToken` is its index in this array. */
+ *  numeric token-type of each `SemanticToken` is its index in this array, and a
+ *  host registers it once at activation — so new types are APPENDED, never
+ *  inserted, or an already-registered legend would repaint every existing
+ *  token as something else. */
 export declare const SEMANTIC_TOKEN_LEGEND: readonly SemanticTokenType[];
 /** One absolute-positioned semantic token. Every Telo semantic token is
  *  single-line (kinds and capabilities never wrap), so a `{line, char, length}`

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -2,5 +2,19 @@
 // or `DiagnosticSeverity.Error` import from here.
 export { AnalysisRegistry, DiagnosticSeverity } from "@telorun/analyzer";
 /** The legend a host registers before mapping `buildSemanticTokens` output. The
- *  numeric token-type of each `SemanticToken` is its index in this array. */
-export const SEMANTIC_TOKEN_LEGEND = ["type", "interface", "variable"];
+ *  numeric token-type of each `SemanticToken` is its index in this array, and a
+ *  host registers it once at activation — so new types are APPENDED, never
+ *  inserted, or an already-registered legend would repaint every existing
+ *  token as something else. */
+export const SEMANTIC_TOKEN_LEGEND = [
+    "type",
+    "interface",
+    "variable",
+    "property",
+    "function",
+    "number",
+    "string",
+    "keyword",
+    "operator",
+    "namespace",
+];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/ide-support",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Editor-host-agnostic IDE support (completions, diagnostic normalization) for Telo manifests.",
   "keywords": [
     "telo",
@@ -36,7 +36,7 @@
     "src/**"
   ],
   "dependencies": {
-    "@telorun/analyzer": "0.63.0"
+    "@telorun/analyzer": "0.64.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",

package/src/cel/cursor-chain.ts

@@ -0,0 +1,58 @@
+/**
+ * The dotted chain the cursor is in the middle of typing.
+ *
+ * Deliberately TEXTUAL, and only for completion. `chainAt` (over the parsed
+ * CEL AST) is what hover and go-to-declaration use, because there the
+ * expression is complete and the cursor sits on a specific identifier whose
+ * span matters. Completion fires on text that frequently does not parse —
+ * `req.` is not an expression — so a parse-first approach would go silent
+ * exactly while the user is asking for help. An open segment recovers to its
+ * longest parseable PREFIX, which by definition drops the token being typed.
+ */
+import type { CelSegment } from "@telorun/analyzer";
+
+export interface CelCursorChain {
+  /** Identifiers resolved before the token under the cursor (`req.query.` → `["req","query"]`). */
+  prefix: string[];
+  /** The partial identifier being typed, possibly empty. */
+  token: string;
+  /** True when the cursor follows a `.` — a member position, where only the
+   *  prefix's members are offered and functions are not. */
+  member: boolean;
+}
+
+/** Where `segment.source` starts in document offsets. The segment range spans
+ *  the delimiters (`${{ … }}`) and any trimmed whitespace, so the body has to be
+ *  located inside it rather than assumed to start at `range[0]`. */
+function bodyStart(text: string, segment: CelSegment): number {
+  const span = text.slice(segment.range[0], segment.range[1]);
+  const at = span.indexOf(segment.source);
+  return at < 0 ? segment.range[0] : segment.range[0] + at;
+}
+
+const TRAILING_CHAIN = /[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)*\.?$/;
+
+/**
+ * Split the text before the cursor into a resolved prefix and a partial token.
+ *
+ * Returns undefined when the cursor does not follow an identifier-shaped run —
+ * after an operator, inside a string literal's content, at the start of an
+ * empty body — where the caller offers the root scope instead of a member list.
+ */
+export function celCursorChain(
+  text: string,
+  segment: CelSegment,
+  offset: number,
+): CelCursorChain | undefined {
+  const start = bodyStart(text, segment);
+  const index = Math.max(0, Math.min(offset - start, segment.source.length));
+  const before = segment.source.slice(0, index);
+  const match = TRAILING_CHAIN.exec(before);
+  if (!match) return undefined;
+  const run = match[0];
+  if (run.endsWith(".")) {
+    return { prefix: run.slice(0, -1).split("."), token: "", member: true };
+  }
+  const parts = run.split(".");
+  return { prefix: parts.slice(0, -1), token: parts[parts.length - 1], member: parts.length > 1 };
+}

package/src/cel/symbols.ts

@@ -0,0 +1,189 @@
+/**
+ * **What a name means inside a CEL expression.**
+ *
+ * The TYPE half of CEL language support — completion's candidate list and
+ * hover's tooltip are both this, read off the scope the analyzer resolved. It
+ * is deliberately separate from the DECLARATION half (`definition/`), which
+ * answers where a name was written: the two take different inputs and
+ * legitimately disagree. `steps.encode.result` has a type and no manifest node
+ * to jump to; a transport binding like `request` has a scope entry and no
+ * declaration at all. Joining them is hover's job, not this module's.
+ */
+import type { CelScope } from "@telorun/analyzer";
+import { navigateSchema } from "../completions/detect-context.js";
+
+/** One name in scope, with whatever the scope knows about it. Both `type` and
+ *  `schema` are optional and neither implies the other: a CEL environment
+ *  variable carries a type and no schema, a context property carries a schema
+ *  and gets its type from it. */
+export interface CelSymbol {
+  name: string;
+  /** CEL type name (`int`, `string`, `map`), when the environment declares one. */
+  type?: string;
+  /** JSON Schema node, when the context declares the shape. */
+  schema?: Record<string, any>;
+  description?: string;
+}
+
+/**
+ * One callable, with every overload the environment registered for it.
+ *
+ * Grouped rather than one entry per overload: the registry declares a signature
+ * per accepted argument list — `double` has four — and offering each as its own
+ * candidate turns a completion list into four identical labels the author
+ * cannot choose between. What varies between them is the signature, so that is
+ * what the grouped entry carries.
+ */
+export interface CelFunctionSymbol {
+  name: string;
+  /** Every registered overload's signature, in registration order. */
+  signatures: string[];
+  /** The type a receiver-style call is made ON (`string.startsWith`), or null
+   *  for a global function. Part of the grouping key, since a global and a
+   *  method sharing a name are genuinely two callables. */
+  receiverType: string | null;
+  /** The first description any overload carries — they describe the function,
+   *  not the individual argument list. */
+  description?: string;
+}
+
+/** The type a schema node declares, rendered for display. Unions are joined
+ *  rather than collapsed — a slot admitting several shapes says so. */
+export function schemaTypeName(schema: Record<string, any> | undefined): string | undefined {
+  if (!schema) return undefined;
+  const valueType = schema["x-telo-type"];
+  if (typeof valueType === "string") return valueType;
+  if (valueType && typeof valueType === "object" && typeof valueType.name === "string") {
+    return valueType.name;
+  }
+  const t = schema.type;
+  if (Array.isArray(t)) return t.join(" | ");
+  if (typeof t === "string") return t;
+  if (Array.isArray(schema.anyOf) || Array.isArray(schema.oneOf)) {
+    const branches = (schema.anyOf ?? schema.oneOf) as Record<string, any>[];
+    const names = branches.map((b) => schemaTypeName(b)).filter(Boolean);
+    if (names.length > 0) return [...new Set(names)].join(" | ");
+  }
+  return undefined;
+}
+
+/** The context's property map, or an empty one when the site is typed by the
+ *  environment alone. */
+function contextProperties(scope: CelScope): Record<string, any> {
+  const props = scope.contextSchema?.properties;
+  return props && typeof props === "object" ? (props as Record<string, any>) : {};
+}
+
+/**
+ * The names an expression may start with.
+ *
+ * Both sources, because neither is complete: the context schema carries the
+ * scope's own bindings (`steps`, `error`, a kind's named bindings, a transport's
+ * `request`), while the environment carries what was registered onto it
+ * directly — which is where the kernel globals live when no context applied.
+ * A name in both takes its schema from the context, which is the narrower.
+ */
+export function celRootSymbols(scope: CelScope): CelSymbol[] {
+  const out = new Map<string, CelSymbol>();
+  for (const variable of scope.env.getDefinitions().variables) {
+    out.set(variable.name, {
+      name: variable.name,
+      type: variable.type,
+      description: variable.description ?? undefined,
+    });
+  }
+  for (const [name, schema] of Object.entries(contextProperties(scope))) {
+    const node = schema as Record<string, any>;
+    out.set(name, {
+      name,
+      type: schemaTypeName(node) ?? out.get(name)?.type,
+      schema: node,
+      description:
+        typeof node.description === "string" ? node.description : out.get(name)?.description,
+    });
+  }
+  return [...out.values()];
+}
+
+/** The schema at a dotted path from the scope root, or undefined when the path
+ *  leaves what the context declares. Navigation is the shared schema walk, so a
+ *  member reached through an array, a `$ref` or an `anyOf` branch resolves the
+ *  same way it does for a structural field. */
+function schemaAtPath(scope: CelScope, parts: string[]): Record<string, any> | undefined {
+  if (parts.length === 0) return scope.contextSchema ?? undefined;
+  const root = contextProperties(scope)[parts[0]] as Record<string, any> | undefined;
+  if (!root) return undefined;
+  if (parts.length === 1) return root;
+  return navigateSchema(root, parts.slice(1));
+}
+
+/**
+ * The members available after `prefix`.
+ *
+ * Empty when the prefix resolves to nothing OR to something whose shape the
+ * scope does not declare — an open node, a live value, a permissive contract.
+ * That is the honest answer: offering a guess here would be offering names the
+ * checker has no opinion about, which is exactly what the shared scope rule
+ * exists to prevent.
+ */
+export function celMemberSymbols(scope: CelScope, prefix: string[]): CelSymbol[] {
+  if (prefix.length === 0) return celRootSymbols(scope);
+  const node = schemaAtPath(scope, prefix);
+  const props = node?.properties;
+  if (!props || typeof props !== "object") return [];
+  return Object.entries(props as Record<string, any>).map(([name, raw]) => {
+    const child = raw as Record<string, any>;
+    return {
+      name,
+      type: schemaTypeName(child),
+      schema: child,
+      description: typeof child.description === "string" ? child.description : undefined,
+    };
+  });
+}
+
+/** What the chain `parts` resolves to — used for hover, where the cursor sits on
+ *  one identifier of a complete chain and the symbol wanted is the one at that
+ *  identifier, not at the chain's tail. */
+export function celSymbolAt(scope: CelScope, parts: string[]): CelSymbol | undefined {
+  if (parts.length === 0) return undefined;
+  if (parts.length === 1) {
+    return celRootSymbols(scope).find((s) => s.name === parts[0]);
+  }
+  const schema = schemaAtPath(scope, parts);
+  if (!schema) return undefined;
+  return {
+    name: parts[parts.length - 1],
+    type: schemaTypeName(schema),
+    schema,
+    description: typeof schema.description === "string" ? schema.description : undefined,
+  };
+}
+
+/**
+ * The callables the environment declares, one entry per function.
+ *
+ * Read off `getDefinitions()` rather than a curated list, exactly as the call
+ * classifier does — so a function the registry gained is offered without this
+ * module being told, and one it never had is never offered. Overloads are
+ * folded into their function; see {@link CelFunctionSymbol}.
+ */
+export function celFunctions(scope: CelScope): CelFunctionSymbol[] {
+  const byKey = new Map<string, CelFunctionSymbol>();
+  for (const fn of scope.env.getDefinitions().functions) {
+    const key = `${fn.receiverType ?? ""}.${fn.name}`;
+    const existing = byKey.get(key);
+    if (existing) {
+      if (!existing.signatures.includes(fn.signature)) existing.signatures.push(fn.signature);
+      existing.description ??= fn.description ?? undefined;
+      continue;
+    }
+    byKey.set(key, {
+      name: fn.name,
+      signatures: [fn.signature],
+      receiverType: fn.receiverType,
+      description: fn.description ?? undefined,
+    });
+  }
+  return [...byKey.values()];
+}

package/src/cel/tokens.ts

@@ -0,0 +1,169 @@
+/**
+ * Semantic tokens for the inside of a CEL body.
+ *
+ * A `!cel "..."` scalar is not a string, and under a stock YAML grammar it is
+ * painted as one. Colouring it through the SEMANTIC layer rather than a grammar
+ * is what makes one implementation serve both hosts — VS Code and the editor's
+ * Monaco already share `buildSemanticTokens`, while a Monarch tokenizer beside
+ * the TextMate one would be a second CEL lexer to keep in agreement.
+ *
+ * It is also the only layer that can be right about NAMES. A grammar knows the
+ * seven kernel roots someone hardcoded into it, which is why `request` and
+ * `steps` go uncoloured today; the scope query knows what is actually in scope
+ * at this exact site. So a name the scope confirms is coloured and a name it
+ * cannot is left alone — the quiet signal an unresolved `kind:` already gives.
+ */
+import { CelParseError, type CelNode, type CelScope, type CelSegment } from "@telorun/analyzer";
+import type { SemanticTokenType } from "../types.js";
+import { flattenChain } from "../cel-chain.js";
+import { celRootSymbols, celSymbolAt } from "./symbols.js";
+
+/** A token before it is placed on a line — document offsets, resolved by the
+ *  caller which owns the line table. */
+export interface CelTokenSpan {
+  range: [number, number];
+  type: SemanticTokenType;
+}
+
+/** How a name is coloured when the scope has no opinion. With a scope, an
+ *  unconfirmed name is deliberately left uncoloured; with none — a host that
+ *  passed no query, or a buffer analysis has not reached — every identifier is
+ *  coloured syntactically, so a CEL body still never reads as a plain string. */
+type NameMode = "scoped" | "syntactic";
+
+const LITERAL_TYPE = (value: unknown): SemanticTokenType | undefined => {
+  if (typeof value === "number" || typeof value === "bigint") return "number";
+  if (typeof value === "string") return "string";
+  if (typeof value === "boolean" || value === null) return "keyword";
+  return undefined;
+};
+
+/**
+ * Tokens for one CEL segment.
+ *
+ * A body that does not parse yields nothing: mid-typing is the normal case
+ * here, and the analyzer reports the syntax error itself. Only that failure is
+ * tolerated — a defect in the CEL wrapper propagates.
+ */
+export function celSegmentTokens(
+  text: string,
+  segment: CelSegment,
+  scope: CelScope | undefined,
+): CelTokenSpan[] {
+  let ast: CelNode;
+  try {
+    ast = segment.ast();
+  } catch (error) {
+    if (!(error instanceof CelParseError)) throw error;
+    return [];
+  }
+  const out: CelTokenSpan[] = [];
+  const mode: NameMode = scope ? "scoped" : "syntactic";
+  // Resolved once per SEGMENT, not once per name: the root set is a property of
+  // the scope, and this runs over the whole document on every token request.
+  const inScope = scope ? new Set(celRootSymbols(scope).map((s) => s.name)) : undefined;
+
+  /** True when the scope confirms the chain `parts`. Callers walk a chain
+   *  left-to-right and stop at the first unconfirmed hop, so each name is
+   *  resolved once rather than the chain being re-walked from its root per hop. */
+  const confirms = (parts: string[]): boolean => {
+    if (mode === "syntactic") return true;
+    if (parts.length === 1) return inScope!.has(parts[0]);
+    return celSymbolAt(scope!, parts) !== undefined;
+  };
+
+  /** The span of `name` between two offsets, or undefined when it is not there
+   *  (a receiver-style call written across an unexpected layout). Nothing is
+   *  invented: a token placed on a guessed span would paint the wrong text. */
+  const spanOf = (name: string, from: number, to: number): [number, number] | undefined => {
+    const at = text.indexOf(name, from);
+    return at >= 0 && at + name.length <= to ? [at, at + name.length] : undefined;
+  };
+
+  const visit = (node: CelNode): void => {
+    switch (node.kind) {
+      case "literal": {
+        const type = LITERAL_TYPE(node.value);
+        if (type) out.push({ range: node.range, type });
+        return;
+      }
+      case "ident":
+        // A root-position name is a scope the runtime injects, not data the
+        // author declared — see `SemanticTokenType`.
+        if (confirms([node.name])) out.push({ range: node.range, type: "namespace" });
+        return;
+      case "member": {
+        // A plain chain is resolved as a whole, so each hop is judged against
+        // what the one before it declared — `resources.db.url` colours `db` only
+        // if `resources` really carries it. A chain rooted in something computed
+        // (`f().x`) flattens to nothing, and the scope has no opinion about it.
+        const parts = flattenChain(node);
+        if (parts) {
+          // A hop the scope cannot confirm makes every hop past it unresolvable
+          // too, so the walk STOPS there rather than re-resolving the rest — the
+          // chain is resolved once, not once per hop.
+          for (let i = 0; i < parts.length; i++) {
+            if (!confirms(parts.slice(0, i + 1).map((p) => p.name))) break;
+            out.push({ range: parts[i].range, type: i === 0 ? "namespace" : "property" });
+          }
+          return;
+        }
+        visit(node.target);
+        if (mode === "syntactic") out.push({ range: node.propertyRange, type: "property" });
+        return;
+      }
+      case "index":
+        visit(node.target);
+        visit(node.index);
+        return;
+      case "call": {
+        // `foo(...)` starts with its own name, so the head of the node IS the
+        // callee's span.
+        out.push({ range: [node.range[0], node.range[0] + node.name.length], type: "function" });
+        for (const arg of node.args) visit(arg);
+        return;
+      }
+      case "methodCall": {
+        visit(node.receiver);
+        const span = spanOf(node.name, node.receiver.range[1], node.range[1]);
+        if (span) out.push({ range: span, type: "function" });
+        for (const arg of node.args) visit(arg);
+        return;
+      }
+      case "list":
+        for (const item of node.items) visit(item);
+        return;
+      case "map":
+        for (const entry of node.entries) {
+          visit(entry.key);
+          visit(entry.value);
+        }
+        return;
+      case "ternary":
+        visit(node.cond);
+        visit(node.then);
+        visit(node.else);
+        return;
+      case "unary": {
+        const span = spanOf(node.op, node.range[0], node.operand.range[0]);
+        if (span) out.push({ range: span, type: "operator" });
+        visit(node.operand);
+        return;
+      }
+      case "binary": {
+        visit(node.left);
+        const span = spanOf(node.op, node.left.range[1], node.right.range[0]);
+        if (span) out.push({ range: span, type: "operator" });
+        visit(node.right);
+        return;
+      }
+    }
+    // Exhaustive by construction: a new `CelNode` variant fails the build here
+    // rather than going silently uncoloured.
+    const unhandled: never = node;
+    throw new Error(`Unhandled CEL node: ${JSON.stringify(unhandled)}`);
+  };
+
+  visit(ast);
+  return out;
+}