@telorun/ide-support 0.15.0 → 0.16.0

package/src/completions/resolve-node.ts

@@ -48,8 +48,15 @@ export interface ResolvedCursor {
   /** Key slot: number of `path` segments that reach `resourceKind`'s map, so
    *  the schema-relative path is `path.slice(resourceDepth)`. */
   resourceDepth?: number;
-  /** Set when the cursor sits inside a CEL body (closed or open). Populated for
-   *  a future CEL-completion feature; this refactor does not consume it. */
+  /** The path with sequence INDICES kept (`routes[0].handler.url`),
+   *  as distinct from `path`, through which arrays are transparent. This is the
+   *  address the analyzer speaks — an `x-telo-context` scope, an error-bearing
+   *  region and a step's identity are all resolved per item — so it is what a
+   *  CEL site is looked up by. */
+  concretePath?: string;
+  /** Set when the cursor sits inside a CEL body (closed or open). The CEL
+   *  segment plus the cursor's document offset — what completion and hover
+   *  hit-test the expression's chain against. */
   cel?: { segment: CelSegment; offset: number };
 }
 
@@ -109,6 +116,7 @@ type Descent =
       type: "key";
       container: AstMap;
       path: string[];
+      concretePath: string;
       keyNode: AstScalar;
       keyName?: string;
       scope: ResourceScope;
@@ -119,15 +127,22 @@ type Descent =
        *  (which has no keyed siblings). */
       container: AstMap | undefined;
       path: string[];
+      concretePath: string;
       keyName?: string;
       keyEnd: number;
       valueNode: AstNode;
     }
   | { type: "empty" };
 
+/** Append one key segment to a concrete path (`routes[0]` + `handler`). */
+function joinKey(concrete: string, key: string): string {
+  return concrete ? `${concrete}.${key}` : key;
+}
+
 function descend(
   node: AstNode,
   ancestors: string[],
+  concrete: string,
   offset: number,
   scope: ResourceScope,
 ): Descent | undefined {
@@ -140,6 +155,7 @@ function descend(
           type: "key",
           container: node,
           path: ancestors,
+          concretePath: concrete,
           keyNode: pair.key as AstScalar,
           keyName,
           scope: mapScope,
@@ -147,13 +163,15 @@ function descend(
       }
       if (pair.value && within(pair.value.range, offset)) {
         const childAncestors = keyName != null ? [...ancestors, keyName] : ancestors;
+        const childConcrete = keyName != null ? joinKey(concrete, keyName) : concrete;
         if (pair.value.kind === "map" || pair.value.kind === "seq") {
-          return descend(pair.value, childAncestors, offset, mapScope) ?? { type: "empty" };
+          return descend(pair.value, childAncestors, childConcrete, offset, mapScope) ?? { type: "empty" };
         }
         return {
           type: "value",
           container: node,
           path: ancestors,
+          concretePath: childConcrete,
           keyName,
           keyEnd: pair.key.range[1],
           valueNode: pair.value,
@@ -164,16 +182,26 @@ function descend(
   }
   if (node.kind === "seq") {
     // Sequence items are transparent to the key path (mirrors the schema
-    // walker, which auto-descends arrays).
-    for (const item of node.items) {
+    // walker, which auto-descends arrays) but NOT to the concrete path: an
+    // `x-telo-context` scope, an error-bearing region and a step's identity are
+    // all addressed per item, so a CEL site is unreachable without the index.
+    for (const [index, item] of node.items.entries()) {
       if (within(item.range, offset)) {
+        const itemConcrete = `${concrete}[${index}]`;
         if (item.kind === "map" || item.kind === "seq") {
-          return descend(item, ancestors, offset, scope) ?? { type: "empty" };
+          return descend(item, ancestors, itemConcrete, offset, scope) ?? { type: "empty" };
         }
         // A bare scalar list item (`targets:\n  - One`) has no enclosing map of
         // keyed siblings — leave `container` undefined rather than treating the
         // seq as a map.
-        return { type: "value", container: undefined, path: ancestors, keyEnd: item.range[0], valueNode: item };
+        return {
+          type: "value",
+          container: undefined,
+          path: ancestors,
+          concretePath: itemConcrete,
+          keyEnd: item.range[0],
+          valueNode: item,
+        };
       }
     }
     return undefined;
@@ -187,6 +215,9 @@ function descend(
 
 interface MapScope {
   path: string[];
+  /** The same location with sequence indices kept — what addresses a manifest
+   *  node, as distinct from `path`, which addresses a schema node. */
+  concrete: string;
   childColumn: number;
   keys: Set<string>;
   rangeStart: number;
@@ -195,6 +226,7 @@ interface MapScope {
 
 interface PairScope {
   path: string[]; // full key path to this pair
+  concrete: string;
   keyColumn: number;
   keyOffset: number;
   childKeys: Set<string>;
@@ -204,6 +236,7 @@ interface PairScope {
 function collectScopes(
   node: AstNode,
   ancestors: string[],
+  concrete: string,
   scope: ResourceScope,
   lineOffsets: number[],
   maps: MapScope[],
@@ -219,11 +252,19 @@ function collectScopes(
       if (childColumn < 0) childColumn = offsetToPosition(pair.key.range[0], lineOffsets).character;
     }
     if (childColumn >= 0) {
-      maps.push({ path: ancestors, childColumn, keys, rangeStart: node.range[0], scope: mapScope });
+      maps.push({
+        path: ancestors,
+        concrete,
+        childColumn,
+        keys,
+        rangeStart: node.range[0],
+        scope: mapScope,
+      });
     }
     for (const pair of node.entries) {
       const keyName = scalarString(pair.key);
       const fullPath = keyName != null ? [...ancestors, keyName] : ancestors;
+      const fullConcrete = keyName != null ? joinKey(concrete, keyName) : concrete;
       const childKeys = new Set<string>();
       if (pair.value?.kind === "map") {
         for (const p of pair.value.entries) {
@@ -233,20 +274,26 @@ function collectScopes(
       }
       pairs.push({
         path: fullPath,
+        concrete: fullConcrete,
         keyColumn: offsetToPosition(pair.key.range[0], lineOffsets).character,
         keyOffset: pair.key.range[0],
         childKeys,
         scope: mapScope,
       });
-      if (pair.value) collectScopes(pair.value, fullPath, mapScope, lineOffsets, maps, pairs);
+      if (pair.value) {
+        collectScopes(pair.value, fullPath, fullConcrete, mapScope, lineOffsets, maps, pairs);
+      }
     }
   } else if (node.kind === "seq") {
-    for (const item of node.items) collectScopes(item, ancestors, scope, lineOffsets, maps, pairs);
+    node.items.forEach((item, index) =>
+      collectScopes(item, ancestors, `${concrete}[${index}]`, scope, lineOffsets, maps, pairs),
+    );
   }
 }
 
 interface KeyResolution {
   path: string[];
+  concrete: string;
   existingKeys: Set<string>;
   scope: ResourceScope;
 }
@@ -262,7 +309,7 @@ function columnSearch(
 ): KeyResolution {
   const maps: MapScope[] = [];
   const pairs: PairScope[] = [];
-  collectScopes(root, [], { depth: 0 }, lineOffsets, maps, pairs);
+  collectScopes(root, [], "", { depth: 0 }, lineOffsets, maps, pairs);
 
   // Sibling level: a map whose children already sit at the cursor's column.
   let sibling: MapScope | undefined;
@@ -271,7 +318,14 @@ function columnSearch(
       if (!sibling || m.rangeStart > sibling.rangeStart) sibling = m;
     }
   }
-  if (sibling) return { path: sibling.path, existingKeys: sibling.keys, scope: sibling.scope };
+  if (sibling) {
+    return {
+      path: sibling.path,
+      concrete: sibling.concrete,
+      existingKeys: sibling.keys,
+      scope: sibling.scope,
+    };
+  }
 
   // Nest under the nearest-preceding key shallower than the cursor.
   let nest: PairScope | undefined;
@@ -286,9 +340,16 @@ function columnSearch(
       }
     }
   }
-  if (nest) return { path: nest.path, existingKeys: nest.childKeys, scope: nest.scope };
+  if (nest) {
+    return {
+      path: nest.path,
+      concrete: nest.concrete,
+      existingKeys: nest.childKeys,
+      scope: nest.scope,
+    };
+  }
 
-  return { path: [], existingKeys: new Set(), scope: { depth: 0 } };
+  return { path: [], concrete: "", existingKeys: new Set(), scope: { depth: 0 } };
 }
 
 // ---------------------------------------------------------------------------
@@ -326,7 +387,7 @@ export function resolveNodeAtPosition(
   const doc = docs[docIndex];
   const docKind = docKindOf(doc);
 
-  const found = doc.root ? descend(doc.root, [], offset, { depth: 0 }) : undefined;
+  const found = doc.root ? descend(doc.root, [], "", offset, { depth: 0 }) : undefined;
 
   // Cursor sits on an existing map key → key/prop-key position.
   if (found?.type === "key") {
@@ -341,6 +402,7 @@ export function resolveNodeAtPosition(
       docKind,
       slot: "key",
       path: found.path,
+      concretePath: found.concretePath,
       node: found.keyNode,
       replaceRange: { start: toPos(found.keyNode.range[0]), end: toPos(found.keyNode.range[1]) },
       container: found.container,
@@ -365,13 +427,14 @@ export function resolveNodeAtPosition(
       toPos(value.range[0]).line !== toPos(found.keyEnd).line;
     if (isPartialKey && doc.root) {
       const col = toPos(value.range[0]).character;
-      const { path, existingKeys, scope } = columnSearch(doc.root, col, offset, lineOffsets);
+      const { path, concrete, existingKeys, scope } = columnSearch(doc.root, col, offset, lineOffsets);
       return {
         docIndex,
         offset,
         docKind,
         slot: "key",
         path,
+        concretePath: concrete,
         container: found.container,
         existingKeys,
         resourceKind: scope.kind,
@@ -386,6 +449,7 @@ export function resolveNodeAtPosition(
       docKind,
       slot: "value",
       path: found.keyName != null ? [...found.path, found.keyName] : found.path,
+      concretePath: found.concretePath,
       node: value,
       container: found.container,
       prefix: text.slice(value.range[0], clampedEnd),
@@ -400,13 +464,14 @@ export function resolveNodeAtPosition(
   // resolved by cursor column.
   const resolution: KeyResolution = doc.root
     ? columnSearch(doc.root, character, offset, lineOffsets)
-    : { path: [], existingKeys: new Set<string>(), scope: { depth: 0 } };
+    : { path: [], concrete: "", existingKeys: new Set<string>(), scope: { depth: 0 } };
   return {
     docIndex,
     offset,
     docKind,
     slot: "key",
     path: resolution.path,
+    concretePath: resolution.concrete,
     existingKeys: resolution.existingKeys,
     resourceKind: resolution.scope.kind,
     resourceDepth: resolution.scope.depth,

package/src/definition/build-definition.ts

@@ -1,7 +1,15 @@
-import { parseToAst, type AstDocument, type AstScalar, type LoadedGraph } from "@telorun/analyzer";
+import {
+  parseToAst,
+  type AstDocument,
+  type AstScalar,
+  type ManifestAnalysis,
+  type LoadedGraph,
+} from "@telorun/analyzer";
 import type { DefinitionResult } from "../types.js";
 import { resolveNodeAtPosition } from "../completions/resolve-node.js";
 import { splitAliasQualified } from "./alias-qualified-value.js";
+import { locateContextBinding } from "./locate-context-binding.js";
+import { locateStepDeclaration } from "./locate-step.js";
 import { moduleForFile } from "./manifest-navigation.js";
 import { resolveCelTarget } from "./resolve-cel-target.js";
 import { isKindSlot, resolveKindTarget } from "./resolve-kind-target.js";
@@ -30,6 +38,10 @@ export function buildDefinition(
   graph: LoadedGraph,
   currentFilePath: string,
   docs?: AstDocument[],
+  /** Lets a `steps.<name>` read navigate to the step that produced it, and a
+   *  context binding to its declaration — both need the declaring kind's own
+   *  annotations, which only the analysis can read. */
+  analysis?: ManifestAnalysis,
 ): DefinitionResult | undefined {
   const astDocs = docs ?? parseToAst(text);
   const resolved = resolveNodeAtPosition(text, astDocs, line, character);
@@ -38,7 +50,23 @@ export function buildDefinition(
   const currentModule = moduleForFile(graph, currentFilePath) ?? graph.entry;
 
   if (resolved.cel) {
-    return resolveCelTarget(graph, currentModule, resolved.cel.segment, resolved.cel.offset);
+    return resolveCelTarget(graph, currentModule, resolved.cel.segment, resolved.cel.offset, {
+      // A step is resolved in the CURRENT document — `steps.<name>.result` is
+      // readable only inside the resource that declares it, which is one
+      // document. Supplied as a closure so the chain resolver stays free of the
+      // AST and the scope query alike.
+      locateStep: (stepName) =>
+        locateStepDeclaration(graph, currentFilePath, astDocs, resolved.docIndex, stepName, analysis?.celScope),
+      locateContextBinding: (parts) =>
+        locateContextBinding(
+          graph,
+          astDocs,
+          resolved.docIndex,
+          resolved.concretePath ?? "",
+          parts,
+          analysis?.celScope,
+        ),
+    });
   }
 
   const node = resolved.node;

package/src/definition/locate-context-binding.ts

@@ -0,0 +1,53 @@
+/**
+ * Where a CEL context binding was declared.
+ *
+ * `request.query` is written in the route's own `request.schema`, `self.<field>`
+ * in the definition's `schema`, `result.<field>` in the INVOKED resource's
+ * `outputType` — each derived by an `x-telo-context-*` annotation rather than
+ * reached through a reference slot, so none of them is navigable by the graph
+ * walk the other CEL roots use. The scope query resolves the annotation to a
+ * manifest identity plus a path; locating that path in the loaded files is what
+ * this adds.
+ */
+import type { AstDocument, CelScopeQuery, LoadedFile, LoadedGraph } from "@telorun/analyzer";
+import type { DefinitionResult } from "../types.js";
+import { docIdentity } from "../doc-identity.js";
+
+/** Every file of every module in the graph — a binding's declaration may sit in
+ *  another module (an invoked handler's `outputType`), so the search is not
+ *  confined to the current file. */
+function allFiles(graph: LoadedGraph): LoadedFile[] {
+  const out: LoadedFile[] = [];
+  for (const mod of graph.modules.values()) out.push(mod.owner, ...mod.partials);
+  return out;
+}
+
+export function locateContextBinding(
+  graph: LoadedGraph,
+  docs: AstDocument[],
+  docIndex: number,
+  sitePath: string,
+  parts: 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 site = scopeQuery.contextDeclarationSite(resource, sitePath, parts);
+  if (!site) return undefined;
+
+  for (const file of allFiles(graph)) {
+    for (let i = 0; i < file.manifests.length; i++) {
+      const manifest = file.manifests[i] as { kind?: string; metadata?: { name?: string } } | null;
+      if (manifest?.kind !== site.kind || manifest.metadata?.name !== site.name) continue;
+      const index = file.positions[i]?.positionIndex;
+      // The KEY span, so the jump underlines `query:` rather than the block that
+      // follows it — a declaration, not a selection.
+      const range = index?.get(`@key:${site.path}`) ?? index?.get(site.path);
+      if (range) return { uri: file.source, range };
+    }
+  }
+  return undefined;
+}

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,