@telorun/ide-support 0.15.0 → 0.16.1

package/src/cel/tokens.ts

@@ -0,0 +1,169 @@
+/**
+ * Semantic tokens for the inside of a CEL body.
+ *
+ * A `!cel "..."` scalar is not a string, and under a stock YAML grammar it is
+ * painted as one. Colouring it through the SEMANTIC layer rather than a grammar
+ * is what makes one implementation serve both hosts — VS Code and the editor's
+ * Monaco already share `buildSemanticTokens`, while a Monarch tokenizer beside
+ * the TextMate one would be a second CEL lexer to keep in agreement.
+ *
+ * It is also the only layer that can be right about NAMES. A grammar knows the
+ * seven kernel roots someone hardcoded into it, which is why `request` and
+ * `steps` go uncoloured today; the scope query knows what is actually in scope
+ * at this exact site. So a name the scope confirms is coloured and a name it
+ * cannot is left alone — the quiet signal an unresolved `kind:` already gives.
+ */
+import { CelParseError, type CelNode, type CelScope, type CelSegment } from "@telorun/analyzer";
+import type { SemanticTokenType } from "../types.js";
+import { flattenChain } from "../cel-chain.js";
+import { celRootSymbols, celSymbolAt } from "./symbols.js";
+
+/** A token before it is placed on a line — document offsets, resolved by the
+ *  caller which owns the line table. */
+export interface CelTokenSpan {
+  range: [number, number];
+  type: SemanticTokenType;
+}
+
+/** How a name is coloured when the scope has no opinion. With a scope, an
+ *  unconfirmed name is deliberately left uncoloured; with none — a host that
+ *  passed no query, or a buffer analysis has not reached — every identifier is
+ *  coloured syntactically, so a CEL body still never reads as a plain string. */
+type NameMode = "scoped" | "syntactic";
+
+const LITERAL_TYPE = (value: unknown): SemanticTokenType | undefined => {
+  if (typeof value === "number" || typeof value === "bigint") return "number";
+  if (typeof value === "string") return "string";
+  if (typeof value === "boolean" || value === null) return "keyword";
+  return undefined;
+};
+
+/**
+ * Tokens for one CEL segment.
+ *
+ * A body that does not parse yields nothing: mid-typing is the normal case
+ * here, and the analyzer reports the syntax error itself. Only that failure is
+ * tolerated — a defect in the CEL wrapper propagates.
+ */
+export function celSegmentTokens(
+  text: string,
+  segment: CelSegment,
+  scope: CelScope | undefined,
+): CelTokenSpan[] {
+  let ast: CelNode;
+  try {
+    ast = segment.ast();
+  } catch (error) {
+    if (!(error instanceof CelParseError)) throw error;
+    return [];
+  }
+  const out: CelTokenSpan[] = [];
+  const mode: NameMode = scope ? "scoped" : "syntactic";
+  // Resolved once per SEGMENT, not once per name: the root set is a property of
+  // the scope, and this runs over the whole document on every token request.
+  const inScope = scope ? new Set(celRootSymbols(scope).map((s) => s.name)) : undefined;
+
+  /** True when the scope confirms the chain `parts`. Callers walk a chain
+   *  left-to-right and stop at the first unconfirmed hop, so each name is
+   *  resolved once rather than the chain being re-walked from its root per hop. */
+  const confirms = (parts: string[]): boolean => {
+    if (mode === "syntactic") return true;
+    if (parts.length === 1) return inScope!.has(parts[0]);
+    return celSymbolAt(scope!, parts) !== undefined;
+  };
+
+  /** The span of `name` between two offsets, or undefined when it is not there
+   *  (a receiver-style call written across an unexpected layout). Nothing is
+   *  invented: a token placed on a guessed span would paint the wrong text. */
+  const spanOf = (name: string, from: number, to: number): [number, number] | undefined => {
+    const at = text.indexOf(name, from);
+    return at >= 0 && at + name.length <= to ? [at, at + name.length] : undefined;
+  };
+
+  const visit = (node: CelNode): void => {
+    switch (node.kind) {
+      case "literal": {
+        const type = LITERAL_TYPE(node.value);
+        if (type) out.push({ range: node.range, type });
+        return;
+      }
+      case "ident":
+        // A root-position name is a scope the runtime injects, not data the
+        // author declared — see `SemanticTokenType`.
+        if (confirms([node.name])) out.push({ range: node.range, type: "namespace" });
+        return;
+      case "member": {
+        // A plain chain is resolved as a whole, so each hop is judged against
+        // what the one before it declared — `resources.db.url` colours `db` only
+        // if `resources` really carries it. A chain rooted in something computed
+        // (`f().x`) flattens to nothing, and the scope has no opinion about it.
+        const parts = flattenChain(node);
+        if (parts) {
+          // A hop the scope cannot confirm makes every hop past it unresolvable
+          // too, so the walk STOPS there rather than re-resolving the rest — the
+          // chain is resolved once, not once per hop.
+          for (let i = 0; i < parts.length; i++) {
+            if (!confirms(parts.slice(0, i + 1).map((p) => p.name))) break;
+            out.push({ range: parts[i].range, type: i === 0 ? "namespace" : "property" });
+          }
+          return;
+        }
+        visit(node.target);
+        if (mode === "syntactic") out.push({ range: node.propertyRange, type: "property" });
+        return;
+      }
+      case "index":
+        visit(node.target);
+        visit(node.index);
+        return;
+      case "call": {
+        // `foo(...)` starts with its own name, so the head of the node IS the
+        // callee's span.
+        out.push({ range: [node.range[0], node.range[0] + node.name.length], type: "function" });
+        for (const arg of node.args) visit(arg);
+        return;
+      }
+      case "methodCall": {
+        visit(node.receiver);
+        const span = spanOf(node.name, node.receiver.range[1], node.range[1]);
+        if (span) out.push({ range: span, type: "function" });
+        for (const arg of node.args) visit(arg);
+        return;
+      }
+      case "list":
+        for (const item of node.items) visit(item);
+        return;
+      case "map":
+        for (const entry of node.entries) {
+          visit(entry.key);
+          visit(entry.value);
+        }
+        return;
+      case "ternary":
+        visit(node.cond);
+        visit(node.then);
+        visit(node.else);
+        return;
+      case "unary": {
+        const span = spanOf(node.op, node.range[0], node.operand.range[0]);
+        if (span) out.push({ range: span, type: "operator" });
+        visit(node.operand);
+        return;
+      }
+      case "binary": {
+        visit(node.left);
+        const span = spanOf(node.op, node.left.range[1], node.right.range[0]);
+        if (span) out.push({ range: span, type: "operator" });
+        visit(node.right);
+        return;
+      }
+    }
+    // Exhaustive by construction: a new `CelNode` variant fails the build here
+    // rather than going silently uncoloured.
+    const unhandled: never = node;
+    throw new Error(`Unhandled CEL node: ${JSON.stringify(unhandled)}`);
+  };
+
+  visit(ast);
+  return out;
+}

package/src/completions/build.ts

@@ -1,7 +1,16 @@
-import { parseToAst, type AnalysisRegistry, type AstDocument, type AstMap } from "@telorun/analyzer";
+import {
+  parseToAst,
+  type AnalysisRegistry,
+  type AstDocument,
+  type AstMap,
+  type ManifestAnalysis,
+} from "@telorun/analyzer";
 import type { CompletionResult, IdeEnvironmentAdapter } from "../types.js";
 import type { ReplaceRange } from "./detect-context.js";
-import { detectContext, lookupRefConstraints } from "./detect-context.js";
+import { callInputsAt } from "./call-inputs.js";
+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 { propKeyCompletions } from "./prop-keys.js";
 import { CAPABILITY_VALUES } from "./valid-capabilities.js";
@@ -16,23 +25,9 @@ interface ResourceRecord {
  *  either is simply skipped; the analyzer remains the source of truth. */
 function extractInFileResources(docs: AstDocument[]): ResourceRecord[] {
   const out: ResourceRecord[] = [];
-  const scalar = (node: { kind: string; value?: unknown } | undefined): string | undefined =>
-    node?.kind === "scalar" && typeof node.value === "string" ? node.value : undefined;
-
   for (const doc of docs) {
-    if (doc.root?.kind !== "map") continue;
-    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);
-      }
-    }
-    if (kind && name) out.push({ kind, name });
+    const identity = docIdentity(doc);
+    if (identity.kind && identity.name) out.push({ kind: identity.kind, name: identity.name });
   }
   return out;
 }
@@ -98,6 +93,7 @@ function refConstrainedKinds(
   const constraints = lookupRefConstraints(
     definition.schema as Record<string, any>,
     parentYamlPath,
+    (from) => registry.resolveSchemaFrom(from, parentDocKind),
   );
   if (constraints.length === 0) return undefined;
   const resolved = constraints.map((c) => registry.userFacingKindsForRef(c));
@@ -133,6 +129,39 @@ function kindCompletions(
   return results;
 }
 
+/**
+ * The values a field's schema says it may take.
+ *
+ * `enum` is closed and `examples` open — the same distinction `propertyNames`
+ * carries for a map's keys, one level down. Nothing is offered when the schema
+ * declares neither, which is most slots.
+ */
+function valueSuggestions(
+  registry: AnalysisRegistry | undefined,
+  docKind: string,
+  yamlPath: string[],
+  replaceRange: ReplaceRange,
+): CompletionResult[] {
+  const definition = registry?.resolveDefinition(docKind);
+  if (!registry || !definition?.schema || yamlPath.length === 0) return [];
+  const field = navigateSchema(definition.schema as Record<string, any>, yamlPath, (from) =>
+    registry.resolveSchemaFrom(from, docKind),
+  );
+  if (!field) return [];
+  const closed = Array.isArray(field.enum) ? (field.enum as unknown[]) : undefined;
+  const values = closed ?? (Array.isArray(field.examples) ? (field.examples as unknown[]) : []);
+  return values
+    .filter((v) => v !== null && typeof v !== "object")
+    .map((value) => ({
+      label: String(value),
+      kind: "enumMember" as const,
+      detail: closed ? "allowed value" : "known value",
+      // Whole-value replacement, so picking over a partially typed value leaves
+      // no suffix — the rule every other value completion here follows.
+      replaceRange,
+    }));
+}
+
 function capabilityCompletions(): CompletionResult[] {
   return CAPABILITY_VALUES.map((cap) => ({
     label: cap,
@@ -148,6 +177,10 @@ export async function buildCompletions(
   registry: AnalysisRegistry | undefined,
   adapter?: IdeEnvironmentAdapter,
   docs?: AstDocument[],
+  /** The host's analysis of the manifests it loaded. Required for anything
+   *  that has to resolve against the manifest SET — CEL completion, and a
+   *  target's declared inputs. */
+  analysis?: ManifestAnalysis,
 ): Promise<CompletionResult[]> {
   // Reuse the host's already-parsed AST when it matches the current buffer;
   // otherwise parse once here (Part 1 stands alone). Both `detectContext` and
@@ -159,11 +192,27 @@ export async function buildCompletions(
     return kindCompletions(registry, ctx.docKind, ctx.yamlPath, ctx.replaceRange);
   }
   if (ctx.type === "capability") return capabilityCompletions();
+  if (ctx.type === "value-suggestions") {
+    return valueSuggestions(registry, ctx.docKind, ctx.yamlPath, ctx.replaceRange);
+  }
+  if (ctx.type === "cel") {
+    return celCompletions(
+      text,
+      ctx.segment,
+      ctx.offset,
+      ctx.concretePath,
+      docIdentity(astDocs[ctx.docIndex]),
+      analysis?.celScope,
+    );
+  }
   if (ctx.type === "ref-name") {
     const definition = registry?.resolveDefinition(ctx.docKind);
-    const refConstraints = definition?.schema
-      ? lookupRefConstraints(definition.schema as Record<string, any>, ctx.yamlPath)
-      : [];
+    const refConstraints =
+      registry && definition?.schema
+        ? lookupRefConstraints(definition.schema as Record<string, any>, ctx.yamlPath, (from) =>
+            registry.resolveSchemaFrom(from, ctx.docKind),
+          )
+        : [];
     return refNameCompletions(astDocs, ctx.refKind, refConstraints, registry, ctx.replaceRange);
   }
   if (ctx.type === "field-value") {
@@ -172,5 +221,19 @@ export async function buildCompletions(
     }
     return [];
   }
-  return propKeyCompletions(ctx.docKind, ctx.yamlPath, ctx.existingKeys, registry);
+  // A slot that IS an enclosing call's argument map completes from the target's
+  // declared inputs rather than from its own (open) schema.
+  return propKeyCompletions(
+    ctx.docKind,
+    ctx.yamlPath,
+    ctx.existingKeys,
+    registry,
+    callInputsAt(
+      registry,
+      analysis,
+      docIdentity(astDocs[ctx.docIndex]).kind ?? ctx.docKind,
+      docIdentity(astDocs[ctx.docIndex]).name,
+      ctx.concretePath,
+    ),
+  );
 }

package/src/completions/call-inputs.ts

@@ -0,0 +1,92 @@
+/**
+ * The arguments a call site declares.
+ *
+ * A slot that transfers control names its argument slot on its own `x-telo-ref`
+ * — `inputs: /inputs`, a JSON Pointer relative to the object enclosing the slot.
+ * That is the only thing tying an `inputs:` map to the resource it is arguments
+ * FOR: the map itself is an open object, and the reference sits in a sibling
+ * field whose name no walker may assume.
+ *
+ * Reading the pointer here means completion offers exactly the keys the invoked
+ * target declares — resolved through the shared contract resolver, so they are
+ * the keys `telo check` validates that call against and the kernel binds at
+ * dispatch, instance declaration first.
+ */
+import {
+  navigateConcretePath,
+  readRefSlot,
+  type AnalysisRegistry,
+  type ManifestAnalysis,
+  type ManifestRef,
+} from "@telorun/analyzer";
+import { navigateSchema } from "./detect-context.js";
+
+/** Resolve a JSON Pointer that is a plain property path (`/inputs`) into path
+ *  segments. Pointers here address a sibling FIELD, never an array element, so
+ *  anything else is left alone rather than guessed at. */
+function pointerSegments(pointer: string): string[] | undefined {
+  if (!pointer.startsWith("/")) return undefined;
+  const segments = pointer
+    .slice(1)
+    .split("/")
+    .map((s) => s.replace(/~1/g, "/").replace(/~0/g, "~"));
+  return segments.every((s) => s.length > 0 && !/^\d+$/.test(s)) ? segments : undefined;
+}
+
+/**
+ * The declared input contract of the call whose argument slot is at
+ * `concretePath`, or undefined when this path is not one.
+ *
+ * Both halves have to line up: the enclosing object's schema must declare a ref
+ * slot whose `inputs` pointer names this field, and the manifest must fill that
+ * ref. Either missing means there is no call here to take arguments for.
+ */
+export function callInputsAt(
+  registry: AnalysisRegistry | undefined,
+  analysis: ManifestAnalysis | undefined,
+  docKind: string,
+  resourceName: string | undefined,
+  concretePath: string,
+): Record<string, any> | undefined {
+  if (!registry || !analysis || !concretePath) return undefined;
+  const resource = analysis.resourceFor(docKind, resourceName);
+  if (!resource) return undefined;
+  const definition = registry.resolveDefinition(docKind);
+  if (!definition?.schema) return undefined;
+
+  const segments = concretePath.split(".").map((seg) => seg.replace(/\[\d+\]$/, ""));
+
+  // The pointer is relative to the object ENCLOSING the annotated slot, and it
+  // may name a nested field (`/handler/inputs`), so every prefix of this path is
+  // a candidate enclosing object — not just the immediate parent. Trying them
+  // longest-first keeps the nearest enclosing declaration winning.
+  const concreteSegments = concretePath.split(".");
+  for (let depth = segments.length - 1; depth >= 0; depth--) {
+    const enclosing = segments.slice(0, depth);
+    const tail = segments.slice(depth);
+    const enclosingSchema = navigateSchema(
+      definition.schema as Record<string, any>,
+      // Schema navigation is index-free; the concrete path is not.
+      enclosing.filter(Boolean),
+      (from) => registry.resolveSchemaFrom(from, docKind),
+    );
+    const properties = enclosingSchema?.properties as Record<string, any> | undefined;
+    if (!properties) continue;
+
+    for (const [siblingName, siblingSchema] of Object.entries(properties)) {
+      const slot = readRefSlot(siblingSchema);
+      if (!slot?.inputs) continue;
+      const pointed = pointerSegments(slot.inputs);
+      if (!pointed || pointed.length !== tail.length) continue;
+      if (!pointed.every((seg, i) => seg === tail[i])) continue;
+
+      const refPath = [...concreteSegments.slice(0, depth), siblingName].filter(Boolean).join(".");
+      const ref = navigateConcretePath(resource as Record<string, any>, refPath) as
+        | ManifestRef
+        | undefined;
+      if (!ref || typeof ref !== "object" || !ref.name) continue;
+      return analysis.contractFor(ref, "inputType");
+    }
+  }
+  return undefined;
+}

package/src/completions/cel-completions.ts

@@ -0,0 +1,108 @@
+/**
+ * Completion inside a CEL body.
+ *
+ * Every candidate comes from the scope the analyzer resolved for this exact
+ * site, so the list is a claim that what it offers will type-check — not a
+ * separate model of what CEL sees. Where the scope declares nothing (an open
+ * node, a permissive contract, a live value) nothing is offered, which is the
+ * honest answer rather than a guess.
+ */
+import type { CelScopeQuery, CelSegment } from "@telorun/analyzer";
+import type { CompletionResult, ReplaceRange } from "../types.js";
+import { celCursorChain } from "../cel/cursor-chain.js";
+import { celFunctions, celMemberSymbols, celRootSymbols, type CelSymbol } from "../cel/symbols.js";
+
+/** The resource a cursor's document addresses. */
+export interface CelCompletionTarget {
+  kind?: string;
+  name?: string;
+}
+
+/** Markdown listing every overload, with the function's own description above
+ *  it. A single-signature function needs no list — its one signature is already
+ *  on the detail line. */
+function describeOverloads(signatures: string[], description?: string): string | undefined {
+  if (signatures.length <= 1) return description;
+  const list = signatures.map((s) => `- \`${s}\``).join("\n");
+  return description ? `${description}\n\n${list}` : list;
+}
+
+function toResult(symbol: CelSymbol, replaceRange?: ReplaceRange): CompletionResult {
+  return {
+    label: symbol.name,
+    kind: "property",
+    detail: symbol.type,
+    documentation: symbol.description,
+    replaceRange,
+  };
+}
+
+/**
+ * Candidates for the cursor inside `segment`.
+ *
+ * A member position (`req.|`) offers only what the prefix declares — no
+ * functions, since a receiver-style call is rare next to a field access and
+ * mixing them buries the fields. A root position offers the scope's names
+ * first, then the global functions the environment declares.
+ */
+export function celCompletions(
+  text: string,
+  segment: CelSegment,
+  offset: number,
+  concretePath: string,
+  target: CelCompletionTarget,
+  query: CelScopeQuery | undefined,
+): CompletionResult[] {
+  if (!query) return [];
+  const resource = query.resourceFor(target.kind, target.name);
+  if (!resource) return [];
+  const scope = query.scopeAt(resource, concretePath);
+
+  const chain = celCursorChain(text, segment, offset);
+  const prefix = chain?.prefix ?? [];
+
+  if (chain?.member) {
+    return celMemberSymbols(scope, prefix).map((s) => toResult(s));
+  }
+
+  const roots = celRootSymbols(scope);
+  const results = roots.map((s) => toResult(s));
+  // A CEL type name (`double`, `int`, `string`) is registered as a variable of
+  // type `type` AND as the conversion function of the same name. Both are real,
+  // but two identical labels are two things an author cannot choose between, so
+  // the callable form wins the slot and says it also names the type — that is
+  // the form written at a root position.
+  const typeNames = new Set(roots.filter((s) => s.type === "type").map((s) => s.name));
+
+  // Global functions only: a receiver-style one (`string.startsWith`) is
+  // reachable through a member position, where the receiver's type is known.
+  for (const fn of celFunctions(scope)) {
+    if (fn.receiverType) continue;
+    const alsoAType = typeNames.has(fn.name);
+    if (alsoAType) {
+      const at = results.findIndex((r) => r.label === fn.name);
+      if (at >= 0) results.splice(at, 1);
+    }
+    results.push({
+      label: fn.name,
+      kind: "value",
+      // One candidate per function, so the extra overloads are reported IN it
+      // rather than as repeated labels: the count on the detail line, the
+      // signatures themselves in the documentation.
+      detail:
+        fn.signatures.length > 1
+          ? `${fn.signatures[0]}  (+${fn.signatures.length - 1} overloads)`
+          : fn.signatures[0],
+      documentation: describeOverloads(
+        fn.signatures,
+        alsoAType
+          ? [fn.description, `Also names the CEL type \`${fn.name}\`.`].filter(Boolean).join("\n\n")
+          : fn.description,
+      ),
+      // Sorted after the scope's own names: a variable is what an author is
+      // reaching for at a root position far more often than a built-in.
+      sortText: `z${fn.name}`,
+    });
+  }
+  return results;
+}