@telorun/ide-support 0.23.0 → 0.24.0

package/dist/value-tags/offered-value-tags.d.ts

@@ -0,0 +1,56 @@
+/**
+ * A YAML tag an author may write on a value, and what it means to write one.
+ *
+ * The split with `@telorun/templating` is deliberate. An engine declares what a
+ * tag PRODUCES (`producedType()`) and where its CEL is (`expressionRegions`);
+ * this declares how the tag is PRESENTED to an author, which is editor knowledge
+ * no engine should carry. Applicability is derived from the engine's own
+ * declaration rather than from a list of names here — so the table says how to
+ * describe a tag, never which tags fit where.
+ *
+ * Shared by every editor host (VS Code completion, studio's source view and
+ * schema form), so the hosts cannot disagree about which tags a field takes.
+ */
+export interface ValueTag {
+    /** Engine name, which is the YAML tag without its `!`. */
+    id: string;
+    /** How the tag is written. */
+    label: string;
+    /** One line on what the tag does. */
+    hint: string;
+    /** Only meaningful where the slot is EVALUATED — the tag decides what
+     *  evaluation does with the value (`!cel` supplies the expression, `!literal`
+     *  opts out of interpolation), so outside such a field it says nothing the
+     *  plain value does not. An embed is the other case: it supplies a value, and
+     *  evaluation was never involved. */
+    requiresEvalSlot?: boolean;
+    /** Set when the scalar under the tag is a module-root-relative location of
+     *  something that ships with the module, saying what it may name. */
+    names?: "file" | "file-or-directory";
+}
+/** The authorable tag an engine name denotes, or undefined for a tag no host
+ *  offers (`!ref`, `!sql`, an unknown one). */
+export declare function valueTag(id: string): ValueTag | undefined;
+/**
+ * The tags offerable at one field.
+ *
+ * Two rules, both read off the engine rather than off its name:
+ *
+ *  - CAN its value satisfy the slot? A tag that declares a produced type is
+ *    offered only where that type fits. This is what puts `!include-bytes` on a
+ *    `Telo.Bytes` slot and keeps it off a string one — and what keeps
+ *    `!literal`, which is always text, off a boolean predicate. Checked with
+ *    the analyzer's own comparator so the editor and `telo check` agree about
+ *    what fits. A tag declaring no produced type (`!cel`) produces whatever the
+ *    slot says and constrains nothing here.
+ *  - Is it MEANINGFUL here? A tag that decides what evaluation does with the
+ *    value needs a slot that is evaluated at all: outside one, `!cel` is a
+ *    value the runtime never evaluates (`CEL_IN_NON_EVAL_FIELD`), and
+ *    `!literal` suppresses an interpolation that was never going to happen.
+ *
+ * `prop` undefined is a field with no declared schema, which constrains
+ * nothing. `evalMode` undefined means no rule decides whether the field is
+ * evaluated, so the second question is not asked.
+ */
+export declare function offeredValueTags(prop: Record<string, unknown> | undefined, evalMode: "compile" | "runtime" | null | undefined): ValueTag[];
+//# sourceMappingURL=offered-value-tags.d.ts.map

package/dist/value-tags/offered-value-tags.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"offered-value-tags.d.ts","sourceRoot":"","sources":["../../src/value-tags/offered-value-tags.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,QAAQ;IACvB,0DAA0D;IAC1D,EAAE,EAAE,MAAM,CAAC;IACX,8BAA8B;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,qCAAqC;IACrC,IAAI,EAAE,MAAM,CAAC;IACb;;;;yCAIqC;IACrC,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B;yEACqE;IACrE,KAAK,CAAC,EAAE,MAAM,GAAG,mBAAmB,CAAC;CACtC;AA4CD;+CAC+C;AAC/C,wBAAgB,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,CAGzD;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EACzC,QAAQ,EAAE,SAAS,GAAG,SAAS,GAAG,IAAI,GAAG,SAAS,GACjD,QAAQ,EAAE,CAWZ"}

package/dist/value-tags/offered-value-tags.js

@@ -0,0 +1,92 @@
+import { checkSchemaCompatibility } from "@telorun/analyzer";
+import { builtinEngines, producedTypeOf } from "@telorun/templating";
+/**
+ * The tags an author may write, by engine name.
+ *
+ * `!ref` is absent on purpose: it names a RESOURCE rather than producing a
+ * value, so it belongs to a reference slot, never to a value one. `!sql` is
+ * absent until a host can edit it as SQL — a plain text box would be the wrong
+ * widget, and the hosts offer one set. An engine with no entry is simply not
+ * offered, which is the safe direction.
+ */
+const AUTHORABLE = {
+    cel: {
+        label: "!cel",
+        hint: "A CEL expression, evaluated against this field's scope.",
+        requiresEvalSlot: true,
+    },
+    interpolate: {
+        label: "!interpolate",
+        hint: "Text with `${{ }}` holes, each a CEL expression; always a string.",
+        requiresEvalSlot: true,
+    },
+    literal: {
+        label: "!literal",
+        hint: "Opaque text. `${{ }}` inside it is not interpolated.",
+        requiresEvalSlot: true,
+    },
+    "include-text": {
+        label: "!include-text",
+        hint: "Contents of a file shipped with this module, as text.",
+        names: "file",
+    },
+    "include-bytes": {
+        label: "!include-bytes",
+        hint: "Contents of a file shipped with this module, as raw bytes.",
+        names: "file",
+    },
+    "module-path": {
+        label: "!module-path",
+        hint: "Location of a file or directory shipped with this module.",
+        names: "file-or-directory",
+    },
+};
+/** The authorable tag an engine name denotes, or undefined for a tag no host
+ *  offers (`!ref`, `!sql`, an unknown one). */
+export function valueTag(id) {
+    const entry = AUTHORABLE[id];
+    return entry ? { id, ...entry } : undefined;
+}
+/**
+ * The tags offerable at one field.
+ *
+ * Two rules, both read off the engine rather than off its name:
+ *
+ *  - CAN its value satisfy the slot? A tag that declares a produced type is
+ *    offered only where that type fits. This is what puts `!include-bytes` on a
+ *    `Telo.Bytes` slot and keeps it off a string one — and what keeps
+ *    `!literal`, which is always text, off a boolean predicate. Checked with
+ *    the analyzer's own comparator so the editor and `telo check` agree about
+ *    what fits. A tag declaring no produced type (`!cel`) produces whatever the
+ *    slot says and constrains nothing here.
+ *  - Is it MEANINGFUL here? A tag that decides what evaluation does with the
+ *    value needs a slot that is evaluated at all: outside one, `!cel` is a
+ *    value the runtime never evaluates (`CEL_IN_NON_EVAL_FIELD`), and
+ *    `!literal` suppresses an interpolation that was never going to happen.
+ *
+ * `prop` undefined is a field with no declared schema, which constrains
+ * nothing. `evalMode` undefined means no rule decides whether the field is
+ * evaluated, so the second question is not asked.
+ */
+export function offeredValueTags(prop, evalMode) {
+    const out = [];
+    for (const engine of builtinEngines) {
+        const tag = valueTag(engine.name);
+        if (!tag)
+            continue;
+        const produced = producedTypeOf(engine.name);
+        const fitsSlot = produced && prop ? producedFits(produced, prop) : true;
+        const meaningful = tag.requiresEvalSlot && evalMode !== undefined ? evalMode !== null : true;
+        if (fitsSlot && meaningful)
+            out.push(tag);
+    }
+    return out;
+}
+/** Whether a tag's produced type satisfies the slot's declared one. An
+ *  undeclared slot accepts anything — it constrains nothing, so nothing about
+ *  the value can contradict it. A union declares through its branches. */
+function producedFits(produced, prop) {
+    if (!prop.type && !prop["x-telo-type"] && !prop.anyOf && !prop.oneOf)
+        return true;
+    return checkSchemaCompatibility(produced, prop).compatible;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/ide-support",
-  "version": "0.23.0",
+  "version": "0.24.0",
   "description": "Editor-host-agnostic IDE support (completions, diagnostic normalization) for Telo manifests.",
   "keywords": [
     "telo",
@@ -37,7 +37,8 @@
   ],
   "dependencies": {
     "yaml": "^2.8.3",
-    "@telorun/analyzer": "0.83.0"
+    "@telorun/analyzer": "0.84.0",
+    "@telorun/templating": "0.25.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",

package/src/completions/build.ts

@@ -12,6 +12,8 @@ import { celCompletions } from "./cel-completions.js";
 import { docIdentity } from "../doc-identity.js";
 import { detectContext, lookupRefConstraints, navigateSchema } from "./detect-context.js";
 import { importSourceCompletions } from "./import-source.js";
+import { moduleFileCompletions } from "./module-file-completions.js";
+import { valueTagCompletions } from "./value-tag-completions.js";
 import { propKeyCompletions } from "./prop-keys.js";
 import { CAPABILITY_VALUES } from "./valid-capabilities.js";
 
@@ -192,6 +194,10 @@ export async function buildCompletions(
     return kindCompletions(registry, ctx.docKind, ctx.yamlPath, ctx.replaceRange);
   }
   if (ctx.type === "capability") return capabilityCompletions();
+  if (ctx.type === "value-tag") return valueTagCompletions(ctx, registry);
+  if (ctx.type === "module-file") {
+    return moduleFileCompletions(ctx.names, ctx.prefix, ctx.replaceRange, adapter);
+  }
   if (ctx.type === "value-suggestions") {
     return valueSuggestions(registry, ctx.docKind, ctx.yamlPath, ctx.replaceRange);
   }

package/src/completions/detect-context.ts

@@ -6,6 +6,7 @@ import {
   type CelSegment,
 } from "@telorun/analyzer";
 import type { ReplaceRange } from "../types.js";
+import { valueTag } from "../value-tags/offered-value-tags.js";
 import { resolveNodeAtPosition } from "./resolve-node.js";
 
 export type { ReplaceRange };
@@ -88,6 +89,32 @@ export type CompletionCtx =
       segment: CelSegment;
       /** Cursor as a document offset. */
       offset: number;
+    }
+  | {
+      /** Cursor sits on a value's YAML tag (`root: !mo|`). What is offered is
+       *  every tag the field takes, so its schema is addressed relative to the
+       *  nearest enclosing resource. */
+      type: "value-tag";
+      /** Absent at a document declaring no resource kind. */
+      kind?: string;
+      yamlPath: string[];
+      /** Resource-relative, sequence indices kept — what the eval mode is
+       *  resolved at. */
+      concretePath: string;
+      /** The value is a sequence item, so the field's schema is its item's. */
+      isItem: boolean;
+      /** Nothing follows the tag yet, so a pick may lead into the value. */
+      bare: boolean;
+      replaceRange: ReplaceRange;
+    }
+  | {
+      /** Cursor sits in the value of a tag naming a location inside the module
+       *  (`!module-path ./pu|`). */
+      type: "module-file";
+      names: "file" | "file-or-directory";
+      /** Text from the start of the value to the cursor. */
+      prefix: string;
+      replaceRange: ReplaceRange;
     };
 
 /** Returns every schema branch reachable from `node` after peeling `anyOf` /
@@ -250,6 +277,38 @@ export function navigateSchema(
   return unionLeaves(current, leaves);
 }
 
+/**
+ * The schema of the field at `path`, as DECLARED — combinators kept.
+ *
+ * `navigateSchema` merges a leaf's branches into one object node, which is what
+ * key completion wants and exactly what a type comparison must not see: a
+ * `Telo.HostPath` branch of an `anyOf` stops being one. `isItem` selects the
+ * field's item schema, for a value written as a sequence item.
+ */
+export function fieldSchemaAt(
+  schema: Record<string, any>,
+  path: string[],
+  isItem: boolean,
+  schemaFrom?: SchemaFromResolver,
+): Record<string, any> | undefined {
+  if (path.length === 0) return undefined;
+  const parent = navigateSchema(schema, path.slice(0, -1), schemaFrom);
+  const key = path[path.length - 1]!;
+  let field = parent?.properties?.[key] ?? parent?.additionalProperties;
+  if (!field || typeof field !== "object") return undefined;
+  field = resolveLocalRef(field, schema);
+  if (isItem) {
+    while (field?.type === "array" && field.items) field = resolveLocalRef(field.items, schema);
+  }
+  return field;
+}
+
+/** `concretePath` relative to the resource map at `resourceConcrete`. */
+function relativeConcretePath(concretePath: string, resourceConcrete: string): string {
+  if (!resourceConcrete) return concretePath;
+  return concretePath.slice(resourceConcrete.length).replace(/^\./, "");
+}
+
 /** Merge multiple peeled schema branches into one node for completion purposes.
  *  Property maps are unioned (first branch wins on key collision). `required`
  *  becomes the intersection so optional-in-any-branch keys still surface.
@@ -328,6 +387,31 @@ export function detectContext(
   const { docKind } = resolved;
 
   if (resolved.slot === "value") {
+    const tag = resolved.tag;
+    if (tag?.prefix !== undefined) {
+      const depth = resolved.resourceDepth ?? 0;
+      return {
+        type: "value-tag",
+        kind: resolved.resourceKind ?? docKind,
+        yamlPath: resolved.path.slice(depth),
+        concretePath: relativeConcretePath(
+          resolved.concretePath ?? "",
+          resolved.resourceConcretePath ?? "",
+        ),
+        isItem: resolved.container === undefined,
+        bare: tag.bare,
+        replaceRange: tag.replaceRange,
+      };
+    }
+    const names = tag ? valueTag(tag.text.slice(1))?.names : undefined;
+    if (names && resolved.replaceRange) {
+      return {
+        type: "module-file",
+        names,
+        prefix: resolved.prefix ?? "",
+        replaceRange: resolved.replaceRange,
+      };
+    }
     // Inside a CEL body — structural completion does not apply; what completes
     // are the names the expression may use.
     if (resolved.cel) {

package/src/completions/module-file-completions.ts

@@ -0,0 +1,64 @@
+import type { CompletionResult, IdeEnvironmentAdapter, ReplaceRange } from "../types.js";
+
+/** Caps one listing; a popover shows far fewer. */
+const ENTRY_LIMIT = 200;
+
+/**
+ * Completions for the value of a tag naming a location inside the module
+ * (`!include-text`, `!include-bytes`, `!module-path`).
+ *
+ * Paths are measured from the MODULE ROOT, never from the declaring file, so the
+ * listing is asked of the host against that root. The typed text up to its last
+ * `/` is the directory listed, and is kept on every insertion, so `./` stays
+ * where the author wrote it. A directory is a value in its own right where the
+ * tag may name one; where it names a file, a directory is only a way down, so a
+ * pick inserts its `/` and reopens completion. Dot-entries are listed only once
+ * the typed name starts with `.`, as a shell completes them.
+ *
+ * Nothing is offered above the root or for an absolute or URL-shaped path: the
+ * tag refuses those, and a listing there would offer what cannot be written.
+ */
+export async function moduleFileCompletions(
+  names: "file" | "file-or-directory",
+  prefix: string,
+  replaceRange: ReplaceRange,
+  adapter: IdeEnvironmentAdapter | undefined,
+): Promise<CompletionResult[]> {
+  if (!adapter || /^["']/.test(prefix)) return [];
+  const lastSlash = prefix.lastIndexOf("/");
+  const dirPart = prefix.slice(0, lastSlash + 1);
+  const namePart = prefix.slice(lastSlash + 1);
+  if (!staysInModule(dirPart)) return [];
+
+  const entries = await adapter.listModuleEntries(dirPart === "" ? "." : dirPart);
+  return entries
+    .filter((e) => e.name.startsWith(namePart) && (namePart.startsWith(".") || !e.name.startsWith(".")))
+    .sort((a, b) => Number(b.directory) - Number(a.directory) || a.name.localeCompare(b.name))
+    .slice(0, ENTRY_LIMIT)
+    .map((entry) => {
+      const navigateOnly = entry.directory && names === "file";
+      const path = dirPart + entry.name + (navigateOnly ? "/" : "");
+      return {
+        label: entry.directory ? `${entry.name}/` : entry.name,
+        kind: entry.directory ? "folder" : "file",
+        insertText: path,
+        filterText: path,
+        replaceRange,
+        retrigger: navigateOnly,
+        sortText: `${entry.directory ? 0 : 1}_${entry.name}`,
+      } satisfies CompletionResult;
+    });
+}
+
+/** Whether a module-root-relative directory stays inside the module. Pure string
+ *  work, by the rule the tags' own path grammar applies. */
+function staysInModule(dir: string): boolean {
+  if (/^([/\\]|[a-z][a-z0-9+.-]*:)/i.test(dir)) return false;
+  let depth = 0;
+  for (const segment of dir.split(/[/\\]+/)) {
+    if (segment === "" || segment === ".") continue;
+    depth += segment === ".." ? -1 : 1;
+    if (depth < 0) return false;
+  }
+  return true;
+}

package/src/completions/resolve-node.ts

@@ -41,13 +41,18 @@ export interface ResolvedCursor {
   /** 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. */
+  /** The kind of the nearest enclosing inline resource (or the root resource),
+   *  whose schema the slot is completed against. Absent at a root declaring no
+   *  resource kind. */
   resourceKind?: string;
-  /** Key slot: number of `path` segments that reach `resourceKind`'s map, so
-   *  the schema-relative path is `path.slice(resourceDepth)`. */
+  /** Number of `path` segments that reach `resourceKind`'s map, so the
+   *  schema-relative path is `path.slice(resourceDepth)`. */
   resourceDepth?: number;
+  /** Value slot: the concrete path of `resourceKind`'s map, so the
+   *  resource-relative concrete path is what follows it in `concretePath`. */
+  resourceConcretePath?: string;
+  /** Value slot: the scalar's tag, when written out in front of it. */
+  tag?: ResolvedTag;
   /** 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
@@ -60,6 +65,17 @@ export interface ResolvedCursor {
   cel?: { segment: CelSegment; offset: number };
 }
 
+export interface ResolvedTag {
+  /** The tag as written, `!` included. */
+  text: string;
+  replaceRange: { start: Position; end: Position };
+  /** Set when the cursor sits on the tag: its text up to the cursor. */
+  prefix?: string;
+  /** True when nothing follows the tag on its line — the value is still to be
+   *  written. */
+  bare: boolean;
+}
+
 function within(range: [number, number], offset: number): boolean {
   return offset >= range[0] && offset <= range[1];
 }
@@ -96,15 +112,43 @@ function resourceKindOf(map: AstMap): string | 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)`. */
+ *  map, so a prop-key `yamlPath` relative to it is `path.slice(depth)`;
+ *  `concrete` is that map's own concrete path. */
 interface ResourceScope {
   kind?: string;
   depth: number;
+  concrete: string;
 }
 
-function enter(scope: ResourceScope, map: AstMap, ancestorsLen: number): ResourceScope {
+const ROOT_SCOPE: ResourceScope = { depth: 0, concrete: "" };
+
+function enter(
+  scope: ResourceScope,
+  map: AstMap,
+  ancestorsLen: number,
+  concrete: string,
+): ResourceScope {
   const kind = resourceKindOf(map);
-  return kind ? { kind, depth: ancestorsLen } : scope;
+  return kind ? { kind, depth: ancestorsLen, concrete } : scope;
+}
+
+/** The span of a scalar's tag, when it is written out in front of the value.
+ *  The AST's range covers the value alone; the tag precedes it, separated by
+ *  whitespace — or ends exactly at the range for a tag with no value yet. A tag
+ *  whose text does not read back verbatim (`!!str`, which the parser expands)
+ *  has no span. */
+function tagSpan(node: AstNode, text: string): [number, number] | undefined {
+  if (node.kind !== "scalar" || !node.tag) return undefined;
+  let end = node.range[0];
+  while (end > 0 && /\s/.test(text[end - 1]!)) end--;
+  const start = end - node.tag.length;
+  return start >= 0 && text.slice(start, end) === node.tag ? [start, end] : undefined;
+}
+
+/** A value's span with its tag included, so a cursor on the tag is on the value. */
+function valueSpan(node: AstNode, text: string): [number, number] {
+  const tag = tagSpan(node, text);
+  return tag ? [tag[0], node.range[1]] : node.range;
 }
 
 // ---------------------------------------------------------------------------
@@ -131,6 +175,7 @@ type Descent =
       keyName?: string;
       keyEnd: number;
       valueNode: AstNode;
+      scope: ResourceScope;
     }
   | { type: "empty" };
 
@@ -145,9 +190,10 @@ function descend(
   concrete: string,
   offset: number,
   scope: ResourceScope,
+  text: string,
 ): Descent | undefined {
   if (node.kind === "map") {
-    const mapScope = enter(scope, node, ancestors.length);
+    const mapScope = enter(scope, node, ancestors.length, concrete);
     for (const pair of node.entries) {
       const keyName = scalarString(pair.key);
       if (within(pair.key.range, offset)) {
@@ -161,11 +207,15 @@ function descend(
           scope: mapScope,
         };
       }
-      if (pair.value && within(pair.value.range, offset)) {
+      if (pair.value && within(valueSpan(pair.value, text), 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, childConcrete, offset, mapScope) ?? { type: "empty" };
+          return (
+            descend(pair.value, childAncestors, childConcrete, offset, mapScope, text) ?? {
+              type: "empty",
+            }
+          );
         }
         return {
           type: "value",
@@ -175,6 +225,7 @@ function descend(
           keyName,
           keyEnd: pair.key.range[1],
           valueNode: pair.value,
+          scope: mapScope,
         };
       }
     }
@@ -186,10 +237,10 @@ function descend(
     // `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)) {
+      if (within(valueSpan(item, text), offset)) {
         const itemConcrete = `${concrete}[${index}]`;
         if (item.kind === "map" || item.kind === "seq") {
-          return descend(item, ancestors, itemConcrete, offset, scope) ?? { type: "empty" };
+          return descend(item, ancestors, itemConcrete, offset, scope, text) ?? { type: "empty" };
         }
         // A bare scalar list item (`targets:\n  - One`) has no enclosing map of
         // keyed siblings — leave `container` undefined rather than treating the
@@ -201,6 +252,7 @@ function descend(
           concretePath: itemConcrete,
           keyEnd: item.range[0],
           valueNode: item,
+          scope,
         };
       }
     }
@@ -243,7 +295,7 @@ function collectScopes(
   pairs: PairScope[],
 ): void {
   if (node.kind === "map") {
-    const mapScope = enter(scope, node, ancestors.length);
+    const mapScope = enter(scope, node, ancestors.length, concrete);
     const keys = new Set<string>();
     let childColumn = -1;
     for (const pair of node.entries) {
@@ -309,7 +361,7 @@ function columnSearch(
 ): KeyResolution {
   const maps: MapScope[] = [];
   const pairs: PairScope[] = [];
-  collectScopes(root, [], "", { depth: 0 }, lineOffsets, maps, pairs);
+  collectScopes(root, [], "", ROOT_SCOPE, lineOffsets, maps, pairs);
 
   // Sibling level: a map whose children already sit at the cursor's column.
   let sibling: MapScope | undefined;
@@ -349,7 +401,7 @@ function columnSearch(
     };
   }
 
-  return { path: [], concrete: "", existingKeys: new Set(), scope: { depth: 0 } };
+  return { path: [], concrete: "", existingKeys: new Set(), scope: ROOT_SCOPE };
 }
 
 // ---------------------------------------------------------------------------
@@ -387,7 +439,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, ROOT_SCOPE, text) : undefined;
 
   // Cursor sits on an existing map key → key/prop-key position.
   if (found?.type === "key") {
@@ -443,6 +495,17 @@ export function resolveNodeAtPosition(
     }
 
     const clampedEnd = Math.min(offset, value.range[1]);
+    const span = tagSpan(value, text);
+    let tag: ResolvedTag | undefined;
+    if (span) {
+      const lineEnd = text.indexOf("\n", span[1]);
+      tag = {
+        text: value.tag!,
+        replaceRange: { start: toPos(span[0]), end: toPos(span[1]) },
+        prefix: within(span, offset) ? text.slice(span[0], offset) : undefined,
+        bare: text.slice(span[1], lineEnd < 0 ? text.length : lineEnd).trim() === "",
+      };
+    }
     return {
       docIndex,
       offset,
@@ -456,7 +519,12 @@ export function resolveNodeAtPosition(
       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,
+      resourceKind: found.scope.kind,
+      resourceDepth: found.scope.depth,
+      resourceConcretePath: found.scope.concrete,
+      tag,
+      // The tag is not the value: a cursor on it is not inside its expression.
+      cel: tag?.prefix !== undefined ? undefined : cel,
     };
   }
 
@@ -464,7 +532,7 @@ export function resolveNodeAtPosition(
   // resolved by cursor column.
   const resolution: KeyResolution = doc.root
     ? columnSearch(doc.root, character, offset, lineOffsets)
-    : { path: [], concrete: "", existingKeys: new Set<string>(), scope: { depth: 0 } };
+    : { path: [], concrete: "", existingKeys: new Set<string>(), scope: ROOT_SCOPE };
   return {
     docIndex,
     offset,

package/src/completions/value-tag-completions.ts

@@ -0,0 +1,55 @@
+import type { AnalysisRegistry } from "@telorun/analyzer";
+import type { CompletionResult, ReplaceRange } from "../types.js";
+import { offeredValueTags, type ValueTag } from "../value-tags/offered-value-tags.js";
+import { fieldSchemaAt, lookupRefConstraints } from "./detect-context.js";
+
+/** `!ref` names a resource rather than producing a value, so it is offered at a
+ *  reference slot alone — never beside the value tags. */
+const REF_TAG: ValueTag = { id: "ref", label: "!ref", hint: "A reference to a named resource." };
+
+export interface ValueTagSite {
+  kind?: string;
+  yamlPath: string[];
+  concretePath: string;
+  isItem: boolean;
+  bare: boolean;
+  replaceRange: ReplaceRange;
+}
+
+/**
+ * The YAML tags the field under the cursor takes.
+ *
+ * The same rule studio's schema form applies (`offeredValueTags`), asked of the
+ * field's declared schema and of the analyzer's eval mode at the site. Where the
+ * field cannot be resolved nothing is known against a tag, so every one is
+ * offered rather than none.
+ *
+ * On a tag with nothing after it, a pick carries a trailing space and, for a tag
+ * naming a module location, reopens completion on the path.
+ */
+export function valueTagCompletions(
+  site: ValueTagSite,
+  registry: AnalysisRegistry | undefined,
+): CompletionResult[] {
+  return tagsAt(site, registry).map((tag, index) => ({
+    label: tag.label,
+    kind: "keyword",
+    detail: tag.hint,
+    insertText: site.bare ? `${tag.label} ` : tag.label,
+    replaceRange: site.replaceRange,
+    retrigger: site.bare && tag.names !== undefined,
+    sortText: String(index).padStart(2, "0"),
+  }));
+}
+
+function tagsAt(site: ValueTagSite, registry: AnalysisRegistry | undefined): ValueTag[] {
+  const { kind } = site;
+  const schema = kind ? registry?.resolveDefinition(kind)?.schema : undefined;
+  if (!registry || !kind || !schema) return [...offeredValueTags(undefined, undefined), REF_TAG];
+  const schemaFrom = (from: string) => registry.resolveSchemaFrom(from, kind);
+  if (lookupRefConstraints(schema as Record<string, any>, site.yamlPath, schemaFrom).length > 0) {
+    return [REF_TAG];
+  }
+  const field = fieldSchemaAt(schema as Record<string, any>, site.yamlPath, site.isItem, schemaFrom);
+  return offeredValueTags(field, registry.celEvalModeAt(kind, site.concretePath));
+}

package/src/index.ts

@@ -8,6 +8,8 @@ export * from "./rename/index.js";
 export * from "./signature-help/index.js";
 export * from "./import-upgrades/index.js";
 export * from "./workspace/index.js";
+// Which YAML tags a field takes — shared so every host offers the same set.
+export { offeredValueTags, valueTag, type ValueTag } from "./value-tags/offered-value-tags.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.