@telorun/ide-support 0.15.0 → 0.16.0

package/src/semantic-tokens/build-semantic-tokens.ts

@@ -5,60 +5,114 @@ import {
   type AnalysisRegistry,
   type AstDocument,
   type AstNode,
+  type AstScalar,
+  type CelScope,
+  type ManifestAnalysis,
 } from "@telorun/analyzer";
 import type { SemanticToken } from "../types.js";
+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<string>(CAPABILITY_VALUES);
 
+/** Append one key segment to a concrete path (`routes[0]` + `handler`). */
+function joinKey(concrete: string, key: string): string {
+  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. */
+ *  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: string,
   registry: AnalysisRegistry | undefined,
   docs?: AstDocument[],
+  analysis?: ManifestAnalysis,
 ): SemanticToken[] {
   const astDocs = docs ?? parseToAst(text);
   const lineOffsets = buildLineOffsets(text);
 
   const tokens: SemanticToken[] = [];
-  const emit = (node: AstNode | undefined, type: SemanticToken["type"]): void => {
-    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: [number, number], type: SemanticToken["type"]): void => {
+    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 emit = (node: AstNode | undefined, type: SemanticToken["type"]): void => {
+    if (node) emitRange(node.range, type);
   };
 
-  const walk = (node: AstNode): void => {
-    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");
+  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: string): CelScope | undefined =>
+      scopeQuery && resource ? scopeQuery.scopeAt(resource, path) : undefined;
+
+    const celTokens = (node: AstScalar, path: string): void => {
+      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: AstNode, concrete: string): void => {
+      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);
         }
-        if (pair.value) walk(pair.value);
+        return;
       }
-    } else if (node.kind === "seq") {
-      for (const item of node.items) walk(item);
-    } else if (node.kind === "scalar" && node.tag === "!ref") {
-      emit(node, "variable");
-    }
-  };
+      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;
+        }
+        celTokens(node, concrete);
+      }
+    };
 
-  for (const doc of astDocs) {
-    if (doc.root) walk(doc.root);
+    walk(doc.root, "");
   }
   return tokens;
 }

package/src/types.ts

@@ -54,14 +54,55 @@ 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. */
-export const SEMANTIC_TOKEN_LEGEND: readonly SemanticTokenType[] = ["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: readonly SemanticTokenType[] = [
+  "type",
+  "interface",
+  "variable",
+  "property",
+  "function",
+  "number",
+  "string",
+  "keyword",
+  "operator",
+  "namespace",
+];
 
 /** One absolute-positioned semantic token. Every Telo semantic token is
  *  single-line (kinds and capabilities never wrap), so a `{line, char, length}`