@telorun/ide-support 0.15.0 → 0.16.0

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;
+}

package/src/completions/detect-context.ts

@@ -1,4 +1,10 @@
-import { parseToAst, readRefSlot, refSlotAnnotation, type AstDocument } from "@telorun/analyzer";
+import {
+  parseToAst,
+  readRefSlot,
+  refSlotAnnotation,
+  type AstDocument,
+  type CelSegment,
+} from "@telorun/analyzer";
 import type { ReplaceRange } from "../types.js";
 import { resolveNodeAtPosition } from "./resolve-node.js";
 
@@ -19,7 +25,17 @@ export type CompletionCtx =
       replaceRange: ReplaceRange;
     }
   | { type: "capability" }
-  | { type: "prop-key"; docKind: string; yamlPath: string[]; existingKeys: Set<string> }
+  | {
+      type: "prop-key";
+      docKind: string;
+      yamlPath: string[];
+      /** The same location with sequence indices kept, so a caller can find the
+       *  manifest node this slot sits in — what resolving an enclosing call's
+       *  reference needs. */
+      concretePath: string;
+      docIndex: number;
+      existingKeys: Set<string>;
+    }
   | {
       /** Cursor sits on the value of an object-form ref's `name:` field
        *  (e.g. `connection: { kind: Sql.Connection, name: |}`). Editor hosts
@@ -43,6 +59,35 @@ export type CompletionCtx =
       prefix: string;
       /** Full source range of the value being completed. */
       replaceRange: ReplaceRange;
+    }
+  | {
+      /** Cursor sits on an ordinary field VALUE whose schema declares the values
+       *  it may take — `enum` (closed) or `examples` (open). Untargeted on
+       *  purpose: every value slot resolves here and the ones declaring neither
+       *  simply offer nothing. */
+      type: "value-suggestions";
+      docKind: string;
+      /** Path from the document root to the field, so its schema can be found. */
+      yamlPath: string[];
+      replaceRange: ReplaceRange;
+    }
+  | {
+      /** Cursor sits inside a CEL body — closed or still open (`!cel "req.|`).
+       *  What completes is decided by the scope the analyzer resolves for this
+       *  site, so the host must supply a `CelScopeQuery`; without one the
+       *  candidate list would be a guess rather than a claim about what
+       *  `telo check` accepts, and nothing is offered. */
+      type: "cel";
+      docKind?: string;
+      /** Which `---` document the cursor is in, so the host can name the
+       *  resource this expression belongs to. */
+      docIndex: number;
+      /** The site's address with sequence indices kept — what the scope is
+       *  resolved at. */
+      concretePath: string;
+      segment: CelSegment;
+      /** Cursor as a document offset. */
+      offset: number;
     };
 
 /** Returns every schema branch reachable from `node` after peeling `anyOf` /
@@ -116,19 +161,52 @@ function resolveLocalRef(
   return current;
 }
 
+/**
+ * Resolves an `x-telo-schema-from` annotation to the schema it derives. Supplied
+ * by the caller because the anchor is alias-qualified and only the registry can
+ * resolve it in the declaring kind's module scope.
+ */
+export type SchemaFromResolver = (schemaFrom: string) => Record<string, any> | undefined;
+
+/**
+ * Expand a node whose shape comes from a sibling kind's schema.
+ *
+ * A slot annotated `x-telo-schema-from` declares NO `properties` of its own — an
+ * `Http.Api` route's `request:` is exactly this — so every walk that reads
+ * `properties` finds an empty node and silently offers nothing. The derived
+ * schema is merged UNDER whatever the slot itself declared, so a slot that adds
+ * a title or narrows a field keeps winning.
+ */
+function resolveSchemaFrom(
+  node: Record<string, any> | undefined,
+  resolve: SchemaFromResolver | undefined,
+): Record<string, any> | undefined {
+  const from = node?.["x-telo-schema-from"];
+  if (!node || !resolve || typeof from !== "string") return node;
+  const derived = resolve(from);
+  if (!derived) return node;
+  return {
+    ...derived,
+    ...node,
+    properties: { ...(derived.properties ?? {}), ...(node.properties ?? {}) },
+  };
+}
+
 /** Navigate a JSON Schema hierarchy following `path`, auto-descending into
- *  array items, peeling `anyOf` / `oneOf` branches and following document-local
- *  `$ref`s. When multiple peeled branches define `properties`, returns a
- *  synthetic node whose `properties` is the union (first-wins on key collision)
- *  and whose `required` is the intersection — enough for propKeyCompletions to
- *  surface every key a value at this slot can legally carry. */
+ *  array items, peeling `anyOf` / `oneOf` branches, following document-local
+ *  `$ref`s and expanding `x-telo-schema-from` slots. When multiple peeled
+ *  branches define `properties`, returns a synthetic node whose `properties` is
+ *  the union (first-wins on key collision) and whose `required` is the
+ *  intersection — enough for propKeyCompletions to surface every key a value at
+ *  this slot can legally carry. */
 export function navigateSchema(
   schema: Record<string, any>,
   path: string[],
+  schemaFrom?: SchemaFromResolver,
 ): Record<string, any> | undefined {
   let current: Record<string, any> | undefined = schema;
   for (const segment of path) {
-    current = resolveLocalRef(current, schema);
+    current = resolveSchemaFrom(resolveLocalRef(current, schema), schemaFrom);
     if (!current) return undefined;
     const candidates = peelCombinators(current).flatMap((node) => {
       const expanded: Record<string, any>[] = [];
@@ -161,7 +239,7 @@ export function navigateSchema(
     if (!next) return undefined;
     current = next;
   }
-  current = resolveLocalRef(current, schema);
+  current = resolveSchemaFrom(resolveLocalRef(current, schema), schemaFrom);
   if (!current) return undefined;
   // Auto-descend through a trailing array at the leaf (e.g. cursor inside `mounts:` items)
   while (current.type === "array" && current.items) {
@@ -227,8 +305,9 @@ function unionLeaves(
 export function lookupRefConstraints(
   definitionSchema: Record<string, any>,
   yamlPath: string[],
+  schemaFrom?: SchemaFromResolver,
 ): string[] {
-  const node = navigateSchema(definitionSchema, yamlPath);
+  const node = navigateSchema(definitionSchema, yamlPath, schemaFrom);
   if (!node) return [];
   return readRefSlot(node)?.kinds ?? [];
 }
@@ -249,9 +328,18 @@ export function detectContext(
   const { docKind } = resolved;
 
   if (resolved.slot === "value") {
-    // Inside a CEL body — structural completion does not apply (a future
-    // CEL-completion feature consumes `resolved.cel`).
-    if (resolved.cel) return undefined;
+    // Inside a CEL body — structural completion does not apply; what completes
+    // are the names the expression may use.
+    if (resolved.cel) {
+      return {
+        type: "cel",
+        docKind,
+        docIndex: resolved.docIndex,
+        concretePath: resolved.concretePath ?? "",
+        segment: resolved.cel.segment,
+        offset: resolved.cel.offset,
+      };
+    }
     const replaceRange = resolved.replaceRange;
     if (!replaceRange) return undefined;
     const key = resolved.path[resolved.path.length - 1];
@@ -297,6 +385,10 @@ export function detectContext(
       }
     }
 
+    if (docKind) {
+      return { type: "value-suggestions", docKind, yamlPath: resolved.path, replaceRange };
+    }
+
     return undefined;
   }
 
@@ -311,6 +403,8 @@ export function detectContext(
     type: "prop-key",
     docKind: scopeKind,
     yamlPath: resolved.path.slice(resolved.resourceDepth ?? 0),
+    concretePath: resolved.concretePath ?? "",
+    docIndex: resolved.docIndex,
     existingKeys: resolved.existingKeys ?? new Set<string>(),
   };
 }

package/src/completions/prop-keys.ts

@@ -25,7 +25,18 @@ export function propKeyCompletions(
   yamlPath: string[],
   existingKeys: Set<string>,
   registry: AnalysisRegistry | undefined,
+  /** The arguments the enclosing call declares, when this path IS that call's
+   *  argument slot. Resolved by the caller, which is the side holding the
+   *  manifest the reference names. */
+  callInputs?: Record<string, any>,
 ): CompletionResult[] {
+  if (callInputs?.properties) {
+    return buildItems(
+      callInputs.properties as Record<string, any>,
+      existingKeys,
+      new Set<string>(Array.isArray(callInputs.required) ? callInputs.required : []),
+    );
+  }
   if (!registry) return [];
 
   const definition = registry.resolveDefinition(kind);
@@ -41,9 +52,20 @@ export function propKeyCompletions(
 
   const targetSchema = yamlPath.length === 0
     ? (definition.schema as Record<string, any>)
-    : navigateSchema(definition.schema as Record<string, any>, yamlPath);
+    : navigateSchema(definition.schema as Record<string, any>, yamlPath, (from) =>
+        registry.resolveSchemaFrom(from, kind),
+      );
+
+  // A NAME-KEYED map declares its keys nowhere in `properties` — they are the
+  // author's own (a media type, a header name). `propertyNames` is JSON
+  // Schema's own vocabulary for what they may be, and it carries the open/closed
+  // distinction already: `enum` constrains, `examples` only suggests. So an open
+  // list of known values needs no annotation and no analyzer-side knowledge of
+  // any domain.
+  const keySuggestions = propertyNameSuggestions(targetSchema, existingKeys);
 
   if (!targetSchema?.properties) {
+    if (keySuggestions.length > 0) return keySuggestions;
     if (yamlPath.length === 0) {
       return buildItems(ROOT_IMPLICIT_PROPS, existingKeys, new Set<string>());
     }
@@ -58,7 +80,42 @@ export function propKeyCompletions(
       ? { ...ROOT_IMPLICIT_PROPS, ...(targetSchema.properties as Record<string, any>) }
       : { ...(targetSchema.properties as Record<string, any>), ...annotationKeys(targetSchema) };
 
-  return buildItems(properties, existingKeys, required);
+  return [...keySuggestions, ...buildItems(properties, existingKeys, required)];
+}
+
+/**
+ * Key candidates a map-valued node declares through `propertyNames`.
+ *
+ * `enum` is a closed set and `examples` an open one — suggestions with no
+ * validation effect, which is exactly "these are the known values, others are
+ * allowed". Both are stock JSON Schema, so nothing here knows what a media type
+ * is and any name-keyed field gains the same behaviour by declaring it.
+ */
+function propertyNameSuggestions(
+  schema: Record<string, any> | undefined,
+  existingKeys: Set<string>,
+): CompletionResult[] {
+  const names = schema?.propertyNames as Record<string, any> | undefined;
+  if (!names || typeof names !== "object") return [];
+  const closed = Array.isArray(names.enum) ? (names.enum as unknown[]) : undefined;
+  const open = Array.isArray(names.examples) ? (names.examples as unknown[]) : [];
+  const values = closed ?? open;
+
+  const out: CompletionResult[] = [];
+  for (const value of values) {
+    if (typeof value !== "string" || existingKeys.has(value)) continue;
+    out.push({
+      label: value,
+      kind: "enumMember",
+      insertText: `${value}: $0`,
+      snippet: true,
+      detail: closed ? names.title ?? "allowed key" : names.title ?? "known key",
+      // Ahead of any structural key at the same level: at a name-keyed slot the
+      // author is choosing one of these, not adding a sibling field.
+      sortText: `0_${value}`,
+    });
+  }
+  return out;
 }
 
 /**