@telorun/ide-support 0.6.0 → 0.7.0

package/src/completions/resolve-node.ts

@@ -0,0 +1,405 @@
+import {
+  buildLineOffsets,
+  offsetToPosition,
+  type AstDocument,
+  type AstMap,
+  type AstNode,
+  type AstScalar,
+  type CelSegment,
+  type Position,
+} from "@telorun/analyzer";
+
+/** The cursor's resolved position against the read-only AST. `locate` produces
+ *  this; `detect-context` maps it onto a `CompletionCtx`. Structure comes from
+ *  the AST; the cursor *column* is used only to resolve empty-space (blank /
+ *  trailing-indent) key positions, where indentation is the sole signal for
+ *  "which container am I typing into". */
+export interface ResolvedCursor {
+  docIndex: number;
+  /** Top-level `kind:` value of the cursor's document, when present. */
+  docKind?: string;
+  slot: "key" | "value";
+  /** Value slot: ancestor keys + the field key (last element is the field).
+   *  Key slot: the container map's ancestor key chain. */
+  path: string[];
+  node?: AstNode;
+  container?: AstMap;
+  replaceRange?: { start: Position; end: Position };
+  /** Value slot: text from the value start up to the cursor. */
+  prefix?: string;
+  /** Value slot: true when whitespace separates the key's colon from the value
+   *  (distinguishes `Console: ` — a value — from `Tiny:` — a bare header). */
+  spaceAfterColon?: boolean;
+  /** Value slot: the value of a sibling `kind:` in the same map (object-form
+   *  ref name completion). */
+  siblingKind?: string;
+  /** Key slot: keys already present in the container (the key under the cursor
+   *  excluded so it still suggests itself). */
+  existingKeys?: Set<string>;
+  /** Key slot: the kind of the nearest enclosing inline resource (or the root
+   *  resource), whose schema the prop keys are completed against. Falls back to
+   *  the document kind at the root. */
+  resourceKind?: string;
+  /** 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. */
+  cel?: { segment: CelSegment; offset: number };
+}
+
+function within(range: [number, number], offset: number): boolean {
+  return offset >= range[0] && offset <= range[1];
+}
+
+export function scalarString(node: AstNode | undefined): string | undefined {
+  if (node?.kind === "scalar" && typeof node.value === "string") return node.value;
+  return undefined;
+}
+
+/** The `kind:` value of a document's root map, if any. */
+function docKindOf(doc: AstDocument): string | undefined {
+  if (doc.root?.kind !== "map") return undefined;
+  for (const pair of doc.root.entries) {
+    if (scalarString(pair.key) === "kind") return scalarString(pair.value);
+  }
+  return undefined;
+}
+
+/** Value of a sibling `kind:` entry in `map`, for object-form ref detection. */
+function siblingKindOf(map: AstMap): string | undefined {
+  for (const pair of map.entries) {
+    if (scalarString(pair.key) === "kind") return scalarString(pair.value);
+  }
+  return undefined;
+}
+
+/** The map's `kind:` value when it names a resource kind (`Alias.Kind`), i.e.
+ *  the map is an inline resource. A prop-key position inside such a map is
+ *  completed against *this* kind's schema, not the outer ref slot's. */
+function resourceKindOf(map: AstMap): string | undefined {
+  const kind = siblingKindOf(map);
+  return kind && /^\w+\.\w+/.test(kind) ? kind : undefined;
+}
+
+/** The kind + path-depth of the nearest enclosing inline resource (or the root
+ *  resource). `depth` is the number of `path` segments consumed to reach that
+ *  map, so a prop-key `yamlPath` relative to it is `path.slice(depth)`. */
+interface ResourceScope {
+  kind?: string;
+  depth: number;
+}
+
+function enter(scope: ResourceScope, map: AstMap, ancestorsLen: number): ResourceScope {
+  const kind = resourceKindOf(map);
+  return kind ? { kind, depth: ancestorsLen } : scope;
+}
+
+// ---------------------------------------------------------------------------
+// Containment descent — used for the cursor sitting ON a real node.
+// ---------------------------------------------------------------------------
+
+type Descent =
+  | {
+      type: "key";
+      container: AstMap;
+      path: string[];
+      keyNode: AstScalar;
+      keyName?: string;
+      scope: ResourceScope;
+    }
+  | {
+      type: "value";
+      /** The enclosing map, or `undefined` for a bare scalar sequence item
+       *  (which has no keyed siblings). */
+      container: AstMap | undefined;
+      path: string[];
+      keyName?: string;
+      keyEnd: number;
+      valueNode: AstNode;
+    }
+  | { type: "empty" };
+
+function descend(
+  node: AstNode,
+  ancestors: string[],
+  offset: number,
+  scope: ResourceScope,
+): Descent | undefined {
+  if (node.kind === "map") {
+    const mapScope = enter(scope, node, ancestors.length);
+    for (const pair of node.entries) {
+      const keyName = scalarString(pair.key);
+      if (within(pair.key.range, offset)) {
+        return {
+          type: "key",
+          container: node,
+          path: ancestors,
+          keyNode: pair.key as AstScalar,
+          keyName,
+          scope: mapScope,
+        };
+      }
+      if (pair.value && within(pair.value.range, offset)) {
+        const childAncestors = keyName != null ? [...ancestors, keyName] : ancestors;
+        if (pair.value.kind === "map" || pair.value.kind === "seq") {
+          return descend(pair.value, childAncestors, offset, mapScope) ?? { type: "empty" };
+        }
+        return {
+          type: "value",
+          container: node,
+          path: ancestors,
+          keyName,
+          keyEnd: pair.key.range[1],
+          valueNode: pair.value,
+        };
+      }
+    }
+    return undefined;
+  }
+  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) {
+      if (within(item.range, offset)) {
+        if (item.kind === "map" || item.kind === "seq") {
+          return descend(item, ancestors, 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 undefined;
+  }
+  return undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Column search — used for empty-space (blank / trailing-indent) key positions.
+// ---------------------------------------------------------------------------
+
+interface MapScope {
+  path: string[];
+  childColumn: number;
+  keys: Set<string>;
+  rangeStart: number;
+  scope: ResourceScope;
+}
+
+interface PairScope {
+  path: string[]; // full key path to this pair
+  keyColumn: number;
+  keyOffset: number;
+  childKeys: Set<string>;
+  scope: ResourceScope;
+}
+
+function collectScopes(
+  node: AstNode,
+  ancestors: string[],
+  scope: ResourceScope,
+  lineOffsets: number[],
+  maps: MapScope[],
+  pairs: PairScope[],
+): void {
+  if (node.kind === "map") {
+    const mapScope = enter(scope, node, ancestors.length);
+    const keys = new Set<string>();
+    let childColumn = -1;
+    for (const pair of node.entries) {
+      const keyName = scalarString(pair.key);
+      if (keyName != null) keys.add(keyName);
+      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 });
+    }
+    for (const pair of node.entries) {
+      const keyName = scalarString(pair.key);
+      const fullPath = keyName != null ? [...ancestors, keyName] : ancestors;
+      const childKeys = new Set<string>();
+      if (pair.value?.kind === "map") {
+        for (const p of pair.value.entries) {
+          const k = scalarString(p.key);
+          if (k != null) childKeys.add(k);
+        }
+      }
+      pairs.push({
+        path: fullPath,
+        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);
+    }
+  } else if (node.kind === "seq") {
+    for (const item of node.items) collectScopes(item, ancestors, scope, lineOffsets, maps, pairs);
+  }
+}
+
+interface KeyResolution {
+  path: string[];
+  existingKeys: Set<string>;
+  scope: ResourceScope;
+}
+
+/** Resolve the container a new key at `cursorColumn` belongs to. Prefers an
+ *  existing sibling level (a map whose child keys sit at exactly `cursorColumn`);
+ *  otherwise nests under the nearest-preceding shallower key. */
+function columnSearch(
+  root: AstNode,
+  cursorColumn: number,
+  cursorOffset: number,
+  lineOffsets: number[],
+): KeyResolution {
+  const maps: MapScope[] = [];
+  const pairs: PairScope[] = [];
+  collectScopes(root, [], { depth: 0 }, lineOffsets, maps, pairs);
+
+  // Sibling level: a map whose children already sit at the cursor's column.
+  let sibling: MapScope | undefined;
+  for (const m of maps) {
+    if (m.childColumn === cursorColumn && m.rangeStart < cursorOffset) {
+      if (!sibling || m.rangeStart > sibling.rangeStart) sibling = m;
+    }
+  }
+  if (sibling) return { path: sibling.path, existingKeys: sibling.keys, scope: sibling.scope };
+
+  // Nest under the nearest-preceding key shallower than the cursor.
+  let nest: PairScope | undefined;
+  for (const p of pairs) {
+    if (p.keyColumn < cursorColumn && p.keyOffset < cursorOffset) {
+      if (
+        !nest ||
+        p.keyColumn > nest.keyColumn ||
+        (p.keyColumn === nest.keyColumn && p.keyOffset > nest.keyOffset)
+      ) {
+        nest = p;
+      }
+    }
+  }
+  if (nest) return { path: nest.path, existingKeys: nest.childKeys, scope: nest.scope };
+
+  return { path: [], existingKeys: new Set(), scope: { depth: 0 } };
+}
+
+// ---------------------------------------------------------------------------
+
+function selectDoc(docs: AstDocument[], offset: number): number {
+  let best = -1;
+  for (let i = 0; i < docs.length; i++) {
+    if (docs[i].range[0] <= offset) best = i;
+  }
+  return best < 0 ? (docs.length > 0 ? 0 : -1) : best;
+}
+
+function celAt(node: AstScalar, offset: number): ResolvedCursor["cel"] {
+  for (const segment of node.celSegments()) {
+    if (offset >= segment.range[0] && offset <= segment.range[1]) return { segment, offset };
+  }
+  return undefined;
+}
+
+/** Resolve `(line, character)` against the AST (Approach B: AST for structure,
+ *  cursor column only to place empty-space key positions). */
+export function resolveNodeAtPosition(
+  text: string,
+  docs: AstDocument[],
+  line: number,
+  character: number,
+): ResolvedCursor | undefined {
+  if (docs.length === 0) return undefined;
+  const lineOffsets = buildLineOffsets(text);
+  const offset = (lineOffsets[line] ?? 0) + character;
+  const toPos = (o: number): Position => offsetToPosition(o, lineOffsets);
+
+  const docIndex = selectDoc(docs, offset);
+  if (docIndex < 0) return undefined;
+  const doc = docs[docIndex];
+  const docKind = docKindOf(doc);
+
+  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") {
+    const existingKeys = new Set<string>();
+    for (const pair of found.container.entries) {
+      const k = scalarString(pair.key);
+      if (k != null && k !== found.keyName) existingKeys.add(k);
+    }
+    return {
+      docIndex,
+      docKind,
+      slot: "key",
+      path: found.path,
+      node: found.keyNode,
+      replaceRange: { start: toPos(found.keyNode.range[0]), end: toPos(found.keyNode.range[1]) },
+      container: found.container,
+      existingKeys,
+      resourceKind: found.scope.kind,
+      resourceDepth: found.scope.depth,
+    };
+  }
+
+  // Cursor sits on a scalar value.
+  if (found?.type === "value" && found.valueNode.kind === "scalar") {
+    const value = found.valueNode;
+    const cel = celAt(value, offset);
+    // A bare identifier on its own line with no colon is a partial *key* being
+    // typed as a first child (yaml parses it as the parent's value). Route to a
+    // key position via column search — the documented cursor-line carve-out.
+    const lineText = text.slice(lineOffsets[line] ?? 0, lineOffsets[line + 1] ?? text.length);
+    const isPartialKey =
+      typeof value.value === "string" &&
+      !lineText.includes(":") &&
+      /^\s*[A-Za-z_][\w-]*\s*$/.test(lineText) &&
+      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);
+      return {
+        docIndex,
+        docKind,
+        slot: "key",
+        path,
+        container: found.container,
+        existingKeys,
+        resourceKind: scope.kind,
+        resourceDepth: scope.depth,
+      };
+    }
+
+    const clampedEnd = Math.min(offset, value.range[1]);
+    return {
+      docIndex,
+      docKind,
+      slot: "value",
+      path: found.keyName != null ? [...found.path, found.keyName] : found.path,
+      node: value,
+      container: found.container,
+      prefix: text.slice(value.range[0], clampedEnd),
+      spaceAfterColon: value.range[0] - found.keyEnd >= 2,
+      siblingKind: found.container ? siblingKindOf(found.container) : undefined,
+      replaceRange: { start: toPos(value.range[0]), end: toPos(value.range[1]) },
+      cel,
+    };
+  }
+
+  // Empty space (blank line, trailing indent, empty document) → key position,
+  // resolved by cursor column.
+  const resolution: KeyResolution = doc.root
+    ? columnSearch(doc.root, character, offset, lineOffsets)
+    : { path: [], existingKeys: new Set<string>(), scope: { depth: 0 } };
+  return {
+    docIndex,
+    docKind,
+    slot: "key",
+    path: resolution.path,
+    existingKeys: resolution.existingKeys,
+    resourceKind: resolution.scope.kind,
+    resourceDepth: resolution.scope.depth,
+  };
+}

package/src/completions/valid-capabilities.ts

@@ -6,3 +6,14 @@ export const CAPABILITY_VALUES = [
   "Telo.Mount",
   "Telo.Type",
 ] as const;
+
+/** One-line role summary per capability, surfaced on hover. Kept in sync with
+ *  the capability list in `CLAUDE.md` / the kernel builtins. */
+export const CAPABILITY_DOCS: Record<string, string> = {
+  "Telo.Service": "Long-lived resource: `init()` + optional `teardown()` (servers, pools).",
+  "Telo.Runnable": "One-shot task: `run()` (pipelines, boot steps).",
+  "Telo.Invocable": "Request handler: `invoke(inputs)` (scripts, endpoints).",
+  "Telo.Provider": "Value-flow source: `init()` + optional `provide()` (config, secrets).",
+  "Telo.Mount": "Mounted into a Service (HTTP APIs, middleware).",
+  "Telo.Type": "Pure schema definition — no runtime instance.",
+};

package/src/definition/build-definition.ts

@@ -0,0 +1,123 @@
+import {
+  parseToAst,
+  type AstDocument,
+  type LoadedFile,
+  type LoadedGraph,
+  type LoadedModule,
+  type Range,
+} from "@telorun/analyzer";
+import type { DefinitionResult } from "../types.js";
+import { resolveNodeAtPosition } from "../completions/resolve-node.js";
+
+/** The module whose owner or partials includes `filePath`. */
+function moduleForFile(graph: LoadedGraph, filePath: string): LoadedModule | undefined {
+  for (const mod of graph.modules.values()) {
+    if (mod.owner.source === filePath) return mod;
+    if (mod.partials.some((p) => p.source === filePath)) return mod;
+  }
+  return undefined;
+}
+
+/** First resource named `name` across `files`, located at its `metadata.name`
+ *  (or its first line as a fallback). Names are unique within a module scope, so
+ *  the first hit is the definition. */
+function locateResource(files: LoadedFile[], name: string): DefinitionResult | undefined {
+  for (const file of files) {
+    for (let i = 0; i < file.manifests.length; i++) {
+      const manifest = file.manifests[i];
+      if (!manifest || manifest.metadata?.name !== name) continue;
+      const pos = file.positions[i];
+      const range: Range | undefined =
+        pos?.positionIndex.get("metadata.name") ??
+        pos?.positionIndex.get("@key:metadata.name") ??
+        (pos ? { start: { line: pos.sourceLine, character: 0 }, end: { line: pos.sourceLine, character: 0 } } : undefined);
+      if (range) return { uri: file.source, range };
+    }
+  }
+  return undefined;
+}
+
+/** The `exports.resources` list of a module's owner doc (empty when absent). */
+function exportedResources(mod: LoadedModule): string[] {
+  const doc = mod.owner.manifests.find(
+    (m) => m?.kind === "Telo.Library" || m?.kind === "Telo.Application",
+  ) as { exports?: { resources?: unknown } } | undefined;
+  const list = doc?.exports?.resources;
+  return Array.isArray(list) ? list.filter((e): e is string => typeof e === "string") : [];
+}
+
+/** Follow `name` into `moduleSource` across the export boundary, honoring the
+ *  `exports.resources` gate and re-export chains (`app → api → domain → …`). A
+ *  terminal match is a locally-owned instance the module actually exports; a
+ *  re-export entry `InnerAlias.name` hops through that module's own import edge.
+ *  `seen` bounds cyclic import graphs. */
+function resolveExported(
+  graph: LoadedGraph,
+  moduleSource: string,
+  name: string,
+  seen: Set<string> = new Set(),
+): DefinitionResult | undefined {
+  if (seen.has(moduleSource)) return undefined;
+  seen.add(moduleSource);
+  const mod = graph.modules.get(moduleSource);
+  if (!mod) return undefined;
+
+  const exports = exportedResources(mod);
+
+  // No `exports.resources` block → ungated (the module hasn't opted into the
+  // gate, same as `exports.kinds`): a plain name match keeps navigation working
+  // for modules that predate explicit exports.
+  if (exports.length === 0) {
+    return locateResource([mod.owner, ...mod.partials], name);
+  }
+
+  if (exports.includes(name)) {
+    const local = locateResource([mod.owner, ...mod.partials], name);
+    if (local) return local;
+  }
+
+  const reexport = exports.find((e) => e.endsWith(`.${name}`));
+  if (!reexport) return undefined;
+  const innerAlias = reexport.slice(0, reexport.length - name.length - 1);
+  const edge = graph.importEdges.get(mod.owner.source)?.get(innerAlias);
+  return edge ? resolveExported(graph, edge.targetSource, name, seen) : undefined;
+}
+
+/** Resolve the `!ref` under the cursor to its target resource's definition.
+ *
+ *  The ref grammar mirrors `resolveRefSentinels`: the tag's value is split on
+ *  the first dot — a bare name (or `Self.name`) is a local resource in the
+ *  current module; `Alias.name` is an exported instance of the module the import
+ *  `Alias` points at, followed transitively through re-exports and gated on each
+ *  module's `exports.resources`. Returns `undefined` when the cursor isn't on a
+ *  `!ref`, or the target can't be found (e.g. a scope-local name, an unexported
+ *  instance, or an import that failed to load). */
+export function buildDefinition(
+  text: string,
+  line: number,
+  character: number,
+  graph: LoadedGraph,
+  currentFilePath: string,
+  docs?: AstDocument[],
+): DefinitionResult | undefined {
+  const astDocs = docs ?? parseToAst(text);
+  const node = resolveNodeAtPosition(text, astDocs, line, character)?.node;
+  if (!node || node.kind !== "scalar" || node.tag !== "!ref") return undefined;
+
+  // The scalar's range covers the ref target text (the value after `!ref`).
+  const source = text.slice(node.range[0], node.range[1]).trim();
+  if (!source) return undefined;
+
+  const currentModule = moduleForFile(graph, currentFilePath) ?? graph.entry;
+  const dot = source.indexOf(".");
+  const alias = dot === -1 ? undefined : source.slice(0, dot);
+  const name = dot === -1 ? source : source.slice(dot + 1);
+
+  if (alias === undefined || alias === "Self") {
+    return locateResource([currentModule.owner, ...currentModule.partials], name);
+  }
+
+  const edge = graph.importEdges.get(currentModule.owner.source)?.get(alias);
+  if (!edge) return undefined;
+  return resolveExported(graph, edge.targetSource, name);
+}

package/src/definition/index.ts

@@ -0,0 +1 @@
+export { buildDefinition } from "./build-definition.js";

package/src/hover/build-hover.ts

@@ -0,0 +1,149 @@
+import {
+  parseToAst,
+  type AnalysisRegistry,
+  type AstDocument,
+} from "@telorun/analyzer";
+import type { HoverResult } from "../types.js";
+import { navigateSchema } from "../completions/detect-context.js";
+import {
+  resolveNodeAtPosition,
+  scalarString,
+  type ResolvedCursor,
+} from "../completions/resolve-node.js";
+import { CAPABILITY_DOCS } from "../completions/valid-capabilities.js";
+
+type Definition = NonNullable<ReturnType<AnalysisRegistry["resolveDefinition"]>>;
+
+/** Docs for the structural keys shared by every module doc, so hover is useful
+ *  even at the root, where there is no user-authored schema to navigate. */
+const STRUCTURAL_KEY_DOCS: Record<string, string> = {
+  kind: "The resource kind — `Alias.Name` for an imported kind, or a `Telo.*` root kind.",
+  metadata: "Resource identity: `name` (kebab-case, dot-free) and optional `namespace`.",
+  imports: "Dependency map: PascalCase alias → `namespace/name@version` source string or object.",
+  targets: "Boot sequence run after init — references to `Runnable`/`Service` resources or inline invoke steps.",
+  variables: "Typed inputs bound from host env vars (`env:` + JSON-Schema `type:`).",
+  secrets: "Secret inputs bound from host env vars (`env:` + `type:`).",
+  ports: "Inbound ports the app listens on, each bound to a host env var (Application only).",
+  exports: "What importers may reference: `kinds` (kind gate) and `resources` (instance singletons).",
+  include: "Partial files loaded into this module scope (paths / globs).",
+  capability: "The lifecycle role of the kind this definition registers.",
+  schema: "JSON Schema for the kind's config fields, with `x-telo-*` annotations.",
+  extends: "Alias-form kind this definition specializes (abstract contract or concrete parent).",
+  base: "Construction mapping (`super(...)`) over `self` for a concrete-`extends` definition.",
+  controllers: "Controller locator (`pkg:npm`) implementing this kind.",
+};
+
+/** The kind value of the map that directly encloses `keyName` in the value slot. */
+function typeName(t: string | Record<string, any> | undefined): string | undefined {
+  if (typeof t === "string") return t;
+  if (t && typeof t === "object" && typeof t.title === "string") return t.title;
+  return undefined;
+}
+
+function kindHover(kind: string, def: Definition | undefined): string {
+  if (!def) return `\`${kind}\``;
+  const lines: string[] = [`### ${kind}`];
+  const role = def.capability ? `\`${def.capability}\`` : "resource";
+  const module = def.metadata?.module ? ` · module \`${def.metadata.module}\`` : "";
+  lines.push(`${role}${module}`);
+  const schema = def.schema as Record<string, any> | undefined;
+  const desc = schema?.description ?? schema?.title;
+  if (typeof desc === "string" && desc) lines.push("", desc);
+  if (def.extends) lines.push("", `Extends \`${def.extends}\``);
+  const input = typeName(def.inputType);
+  const output = typeName(def.outputType);
+  if (input) lines.push(`Input \`${input}\``);
+  if (output) lines.push(`Output \`${output}\``);
+  return lines.join("\n");
+}
+
+function fieldHover(keyName: string, field: Record<string, any>): string {
+  const lines: string[] = [];
+  const type = Array.isArray(field.type) ? field.type.join(" | ") : field.type;
+  const head = type ? `**${keyName}**: \`${type}\`` : `**${keyName}**`;
+  lines.push(head);
+  if (typeof field.description === "string" && field.description) {
+    lines.push("", field.description);
+  }
+  const ref = field["x-telo-ref"];
+  if (typeof ref === "string") lines.push("", `Reference → \`${ref}\``);
+  if (Array.isArray(field.enum) && field.enum.length > 0) {
+    lines.push("", `Allowed: ${field.enum.map((v: unknown) => `\`${v}\``).join(", ")}`);
+  }
+  if (field.default !== undefined) lines.push(`Default: \`${JSON.stringify(field.default)}\``);
+  return lines.length > 0 ? lines.join("\n") : `**${keyName}**`;
+}
+
+/** Field schema at the nearest enclosing resource, or undefined when the scope
+ *  can't be resolved (no kind-bearing ancestor, or the path doesn't navigate). */
+function fieldSchemaFor(
+  resourceKind: string | undefined,
+  relativePath: string[],
+  registry: AnalysisRegistry | undefined,
+): Record<string, any> | undefined {
+  if (!resourceKind || !registry) return undefined;
+  const def = registry.resolveDefinition(resourceKind);
+  if (!def?.schema) return undefined;
+  return navigateSchema(def.schema as Record<string, any>, relativePath);
+}
+
+export function buildHover(
+  text: string,
+  line: number,
+  character: number,
+  registry: AnalysisRegistry | undefined,
+  docs?: AstDocument[],
+): HoverResult | undefined {
+  const astDocs = docs ?? parseToAst(text);
+  const resolved = resolveNodeAtPosition(text, astDocs, line, character);
+  if (!resolved) return undefined;
+
+  if (resolved.slot === "value") return hoverForValue(resolved, registry);
+  return hoverForKey(resolved, registry);
+}
+
+function hoverForValue(
+  resolved: ResolvedCursor,
+  registry: AnalysisRegistry | undefined,
+): HoverResult | undefined {
+  const key = resolved.path[resolved.path.length - 1];
+  const value = scalarString(resolved.node);
+  const range = resolved.replaceRange;
+
+  if (key === "kind" && value) {
+    return { contents: kindHover(value, registry?.resolveDefinition(value)), range };
+  }
+  if (key === "capability" && resolved.docKind === "Telo.Definition" && value) {
+    const doc = CAPABILITY_DOCS[value];
+    return doc ? { contents: `**${value}**\n\n${doc}`, range } : undefined;
+  }
+
+  // Field value: describe the field via the enclosing resource's schema. Works
+  // when the value sits directly under a kind-bearing map (`siblingKind`); the
+  // field path relative to that map is just the key.
+  if (key) {
+    const field = fieldSchemaFor(resolved.siblingKind, [key], registry);
+    if (field) return { contents: fieldHover(key, field), range };
+  }
+  return undefined;
+}
+
+function hoverForKey(
+  resolved: ResolvedCursor,
+  registry: AnalysisRegistry | undefined,
+): HoverResult | undefined {
+  const keyName = scalarString(resolved.node);
+  if (!keyName) return undefined;
+  const range = resolved.replaceRange;
+
+  const resourceKind = resolved.resourceKind ?? resolved.docKind;
+  const relativePath = [...resolved.path.slice(resolved.resourceDepth ?? 0), keyName];
+  const field = fieldSchemaFor(resourceKind, relativePath, registry);
+  if (field) return { contents: fieldHover(keyName, field), range };
+
+  const structural = STRUCTURAL_KEY_DOCS[keyName];
+  if (structural && relativePath.length === 1) {
+    return { contents: `**${keyName}**\n\n${structural}`, range };
+  }
+  return undefined;
+}