@telorun/ide-support 0.15.0 → 0.16.1

package/src/definition/locate-step.ts

@@ -0,0 +1,50 @@
+/**
+ * Where a `Run` step is declared.
+ *
+ * The one CEL scope whose members really are written in the manifest but are
+ * reached through no reference slot — `steps.encode.result` names something a
+ * `!ref` resolver has never heard of. Finding it needs the declaring kind's own
+ * step-body annotation, which is why it goes through the scope query rather
+ * than through the graph navigation the other CEL roots use.
+ */
+import type { AstDocument, CelScopeQuery, LoadedFile, LoadedGraph } from "@telorun/analyzer";
+import type { DefinitionResult } from "../types.js";
+import { docIdentity } from "../doc-identity.js";
+
+/** The loaded file for `filePath`, whose position index maps a manifest path to
+ *  a source range. */
+function loadedFile(graph: LoadedGraph, filePath: string): LoadedFile | undefined {
+  for (const mod of graph.modules.values()) {
+    if (mod.owner.source === filePath) return mod.owner;
+    const partial = mod.partials.find((p) => p.source === filePath);
+    if (partial) return partial;
+  }
+  return undefined;
+}
+
+export function locateStepDeclaration(
+  graph: LoadedGraph,
+  filePath: string,
+  docs: AstDocument[],
+  docIndex: number,
+  stepName: string,
+  scopeQuery: CelScopeQuery | undefined,
+): DefinitionResult | undefined {
+  if (!scopeQuery) return undefined;
+  const identity = docIdentity(docs[docIndex]);
+  const resource = scopeQuery.resourceFor(identity.kind, identity.name);
+  if (!resource) return undefined;
+
+  const stepPath = scopeQuery.stepDeclarationPath(resource, stepName);
+  if (!stepPath) return undefined;
+
+  const file = loadedFile(graph, filePath);
+  const index = file?.positions[docIndex]?.positionIndex;
+  if (!index) return undefined;
+  // The step's own `name:` value is what the jump underlines — the step object's
+  // range would highlight the whole block, which reads as a selection rather
+  // than as a declaration.
+  const range =
+    index.get(`${stepPath}.name`) ?? index.get(`@key:${stepPath}.name`) ?? index.get(stepPath);
+  return range ? { uri: file!.source, range } : undefined;
+}

package/src/definition/resolve-cel-target.ts

@@ -55,11 +55,23 @@ function resolveResourceChain(
  *  analyzer reports the syntax error itself. Only that failure is tolerated: a
  *  defect in the CEL wrapper propagates rather than reading as "nothing to
  *  navigate to". */
+export interface CelTargetResolvers {
+  /** Where a step of the CURRENT resource is declared. Supplied by the caller
+   *  because finding one needs the declaring kind's step-body annotation, which
+   *  the graph alone does not carry. */
+  locateStep?(stepName: string): DefinitionResult | undefined;
+  /** Where a context binding (`request.query`, `self.<field>`,
+   *  `result.<field>`) was declared. Same reason: the site is derived by an
+   *  `x-telo-context-*` annotation, which only the scope query can read. */
+  locateContextBinding?(parts: string[]): DefinitionResult | undefined;
+}
+
 export function resolveCelTarget(
   graph: LoadedGraph,
   currentModule: LoadedModule,
   segment: CelSegment,
   offset: number,
+  resolvers?: CelTargetResolvers,
 ): DefinitionResult | undefined {
   let ast: CelNode;
   try {
@@ -80,5 +92,18 @@ export function resolveCelTarget(
     return undefined;
   }
   if (root === "resources") return resolveResourceChain(graph, currentModule, parts, index);
+  // `steps.<name>` navigates to the step; `steps` itself and `.result` do not —
+  // the first names no one step, the second is the contract's output, which is
+  // declared by the invoked target rather than at the read site.
+  if (root === "steps" && index === 1 && resolvers?.locateStep) {
+    return resolvers.locateStep(parts[1].name);
+  }
+  // Anything else in scope came from an `x-telo-context-*` annotation, which
+  // names a real manifest node for `request` / `self` / `result` and friends.
+  // The chain UP TO the cursor is what resolves — hovering `query` in
+  // `request.query.lastEventId` navigates to `query`, not to the leaf.
+  if (index >= 1 && resolvers?.locateContextBinding) {
+    return resolvers.locateContextBinding(parts.slice(0, index + 1).map((p) => p.name));
+  }
   return undefined;
 }

package/src/doc-identity.ts

@@ -0,0 +1,31 @@
+/**
+ * A document's `kind` + `metadata.name` — the pair that names the resource an
+ * analyzed manifest set holds it under.
+ *
+ * Its own module because it is a document-identity primitive, not a completion
+ * one: hover, semantic tokens and both declaration locators need it, and
+ * reaching it through the completion entry point dragged that whole module
+ * graph — CEL completion, call-input resolution, the import-source machinery —
+ * into surfaces that use none of it.
+ */
+import type { AstDocument, AstMap } from "@telorun/analyzer";
+
+const scalar = (node: { kind: string; value?: unknown } | undefined): string | undefined =>
+  node?.kind === "scalar" && typeof node.value === "string" ? node.value : undefined;
+
+/** Either half may be absent while the author is still writing the document. */
+export function docIdentity(doc: AstDocument | undefined): { kind?: string; name?: string } {
+  if (doc?.root?.kind !== "map") return {};
+  let kind: string | undefined;
+  let name: string | undefined;
+  for (const pair of doc.root.entries) {
+    const key = scalar(pair.key);
+    if (key === "kind") kind = scalar(pair.value);
+    else if (key === "metadata" && pair.value?.kind === "map") {
+      const meta = pair.value as AstMap;
+      const nameEntry = meta.entries.find((e) => scalar(e.key) === "name");
+      name = scalar(nameEntry?.value);
+    }
+  }
+  return { kind, name };
+}

package/src/hover/build-hover.ts

@@ -1,10 +1,17 @@
 import {
+  CelParseError,
   parseToAst,
   readRefSlot,
   type AnalysisRegistry,
   type AstDocument,
+  type CelNode,
+  type CelScopeQuery,
+  type ManifestAnalysis,
 } from "@telorun/analyzer";
 import type { HoverResult } from "../types.js";
+import { chainAt } from "../cel-chain.js";
+import { celSymbolAt } from "../cel/symbols.js";
+import { docIdentity } from "../doc-identity.js";
 import { navigateSchema } from "../completions/detect-context.js";
 import {
   resolveNodeAtPosition,
@@ -90,7 +97,9 @@ function fieldSchemaFor(
   if (!resourceKind || !registry) return undefined;
   const def = registry.resolveDefinition(resourceKind);
   if (!def?.schema) return undefined;
-  return navigateSchema(def.schema as Record<string, any>, relativePath);
+  return navigateSchema(def.schema as Record<string, any>, relativePath, (from) =>
+    registry.resolveSchemaFrom(from, resourceKind),
+  );
 }
 
 export function buildHover(
@@ -99,15 +108,72 @@ export function buildHover(
   character: number,
   registry: AnalysisRegistry | undefined,
   docs?: AstDocument[],
+  /** The host's analysis. Without it a CEL identifier hovers as nothing — its
+   *  type is a property of the resolved scope, and there is no second source
+   *  for it. */
+  analysis?: ManifestAnalysis,
 ): HoverResult | undefined {
   const astDocs = docs ?? parseToAst(text);
   const resolved = resolveNodeAtPosition(text, astDocs, line, character);
   if (!resolved) return undefined;
 
+  if (resolved.cel) {
+    const hover = hoverForCel(resolved, astDocs, analysis?.celScope);
+    // A CEL body is still a field value; when the cursor is on nothing
+    // nameable inside it (an operator, a literal), fall through to the field's
+    // own hover rather than reporting nothing.
+    if (hover) return hover;
+  }
   if (resolved.slot === "value") return hoverForValue(resolved, registry);
   return hoverForKey(resolved, registry);
 }
 
+/**
+ * Hover for one identifier of a CEL chain.
+ *
+ * The TYPE comes from the resolved scope; a DESCRIPTION comes from whatever
+ * schema node declared the name. Where to jump is the other half's answer
+ * (`resolveCelTarget`) and is deliberately not consulted here — hover must
+ * still say what `steps.encode.result` IS even though nothing in the manifest
+ * declares it.
+ */
+function hoverForCel(
+  resolved: ResolvedCursor,
+  docs: AstDocument[],
+  scopeQuery: CelScopeQuery | undefined,
+): HoverResult | undefined {
+  if (!resolved.cel || !scopeQuery) return undefined;
+  const identity = docIdentity(docs[resolved.docIndex]);
+  const resource = scopeQuery.resourceFor(identity.kind, identity.name);
+  if (!resource) return undefined;
+
+  let ast: CelNode;
+  try {
+    ast = resolved.cel.segment.ast();
+  } catch (error) {
+    // An expression the author is still writing does not parse. That means
+    // there is no chain to hit-test, not an error to report from a hover — the
+    // analyzer reports the syntax error itself. Only that failure is tolerated.
+    if (!(error instanceof CelParseError)) throw error;
+    return undefined;
+  }
+
+  const hit = chainAt(ast, resolved.cel.offset);
+  if (!hit) return undefined;
+  // The chain UP TO the cursor, not the whole chain: hovering `resources` in
+  // `resources.db.url` describes `resources`.
+  const parts = hit.parts.slice(0, hit.index + 1).map((p) => p.name);
+  const scope = scopeQuery.scopeAt(resource, resolved.concretePath ?? "");
+  const symbol = celSymbolAt(scope, parts);
+  if (!symbol) return undefined;
+
+  const lines = [symbol.type ? `**${symbol.name}**: \`${symbol.type}\`` : `**${symbol.name}**`];
+  if (symbol.description) lines.push("", symbol.description);
+  const chainText = parts.join(".");
+  if (chainText !== symbol.name) lines.push("", `\`${chainText}\``);
+  return { contents: lines.join("\n") };
+}
+
 function hoverForValue(
   resolved: ResolvedCursor,
   registry: AnalysisRegistry | undefined,

package/src/index.ts

@@ -6,3 +6,7 @@ export * from "./semantic-tokens/index.js";
 export * from "./definition/index.js";
 export * from "./rename/index.js";
 export * from "./import-upgrades/index.js";
+// The repo's single CEL-tree walk. Exported because every host that has to
+// answer "where is this name read" needs it and a second copy would be a second
+// answer — the editor asks it before deleting a resource.
+export { walkCel, flattenChain, chainAt, type ChainPart } from "./cel-chain.js";

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}`