@telorun/ide-support 0.23.0 → 0.102.0

package/src/import-upgrades/build-import-upgrades.ts

@@ -42,9 +42,9 @@ export interface ModuleVersion {
  *
  *  Deliberately NOT `adapter.listVersionsForRef`, which answers `string[]`:
  *  completion offers names, an upgrade writes a pin, so the two want different
- *  things from one route. A host backed by the hub fetches
- *  `GET /module/versions` and passes the body through
- *  {@link parseModuleVersions}. */
+ *  things from one route. A host backed by the hub reads
+ *  `GET /module/versions`, carrying an `integrity` only when it is a canonical
+ *  pin. */
 export type ModuleVersionLookup = (baseRef: string) => Promise<ModuleVersion[]>;
 
 /** Everything an upgrade needs from its host: what versions exist, and whether

package/src/import-upgrades/index.ts

@@ -14,7 +14,6 @@ export type {
   ModuleVersionLookup,
 } from "./build-import-upgrades.js";
 export { moduleManifestCacheUrl } from "./manifest-cache-url.js";
-export { parseModuleVersions } from "./parse-module-versions.js";
 export { findImportEntries } from "./find-import-entries.js";
 export type {
   ImportEntry,

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.

package/src/types.ts

@@ -20,7 +20,15 @@ import type {
   Range,
 } from "@telorun/analyzer";
 
-export type CompletionKind = "class" | "enumMember" | "property" | "folder" | "module" | "value";
+export type CompletionKind =
+  | "class"
+  | "enumMember"
+  | "property"
+  | "folder"
+  | "file"
+  | "module"
+  | "value"
+  | "keyword";
 
 /** A source span the host replaces wholesale when a completion is accepted. */
 export interface ReplaceRange {
@@ -45,6 +53,9 @@ export interface CompletionResult {
    *  containing non-word characters (`/`, `@`, `.`). A zero-width range is a
    *  pure insert. */
   replaceRange?: ReplaceRange;
+  /** The host reopens completion once this item is accepted — what comes next
+   *  has completions of its own (a tag's value, a directory's entries). */
+  retrigger?: boolean;
 }
 
 /** Rendered hover for the symbol under the cursor. `contents` is GitHub-flavored
@@ -172,6 +183,16 @@ export interface IdeEnvironmentAdapter {
    *  (`GET /module/versions?ref=`). The browser cannot call OCI `tags/list`;
    *  the hub holds them from ingest. */
   listVersionsForRef(ref: string): Promise<string[]>;
+  /** Entries of `relPath`, resolved against the ROOT of the module the manifest
+   *  belongs to — the directory every `!include-*` / `!module-path` path is
+   *  measured from, which for a partial is not the partial's own directory.
+   *  Returns [] if the path doesn't exist or isn't a directory. */
+  listModuleEntries(relPath: string): Promise<ModuleEntry[]>;
+}
+
+export interface ModuleEntry {
+  name: string;
+  directory: boolean;
 }
 
 export interface NormalizedDiagnostic {

package/src/value-tags/offered-value-tags.ts

@@ -0,0 +1,127 @@
+import { checkSchemaCompatibility } from "@telorun/analyzer";
+import { builtinEngines, producedTypeOf } from "@telorun/templating";
+
+/**
+ * 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 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: Record<string, Omit<ValueTag, "id">> = {
+  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: string): ValueTag | undefined {
+  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: Record<string, unknown> | undefined,
+  evalMode: "compile" | "runtime" | null | undefined,
+): ValueTag[] {
+  const out: ValueTag[] = [];
+  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: Record<string, unknown>, prop: Record<string, unknown>): boolean {
+  if (!prop.type && !prop["x-telo-type"] && !prop.anyOf && !prop.oneOf) return true;
+  return checkSchemaCompatibility(produced, prop).compatible;
+}

package/dist/import-upgrades/parse-module-versions.d.ts

@@ -1,19 +0,0 @@
-import type { ModuleVersion } from "./build-import-upgrades.js";
-/**
- * Read the hub's `GET /module/versions` payload into {@link ModuleVersion}s,
- * newest first (the route's own ordering, preserved).
- *
- * Pure — the host owns the `fetch`, as everything else in this package does.
- * It lives here rather than in each host because the shape is this package's:
- * three hosts parsing the same route by hand is how one of them was left
- * filtering for strings after the route started returning objects, which
- * TypeScript could not catch behind the response cast and which surfaced only
- * as a silently empty version list.
- *
- * Tolerant by design: an entry with no usable `version` is dropped rather than
- * throwing, and an `integrity` that is not a canonical `sha256-<base64url>` is
- * discarded rather than carried — a pin is spliced into the author's YAML, so a
- * malformed one has to become "no pin", never corrupt text.
- */
-export declare function parseModuleVersions(payload: unknown): ModuleVersion[];
-//# sourceMappingURL=parse-module-versions.d.ts.map

package/dist/import-upgrades/parse-module-versions.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"parse-module-versions.d.ts","sourceRoot":"","sources":["../../src/import-upgrades/parse-module-versions.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAEhE;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,aAAa,EAAE,CAUrE"}

package/dist/import-upgrades/parse-module-versions.js

@@ -1,29 +0,0 @@
-import { isCanonicalIntegrity } from "@telorun/analyzer";
-/**
- * Read the hub's `GET /module/versions` payload into {@link ModuleVersion}s,
- * newest first (the route's own ordering, preserved).
- *
- * Pure — the host owns the `fetch`, as everything else in this package does.
- * It lives here rather than in each host because the shape is this package's:
- * three hosts parsing the same route by hand is how one of them was left
- * filtering for strings after the route started returning objects, which
- * TypeScript could not catch behind the response cast and which surfaced only
- * as a silently empty version list.
- *
- * Tolerant by design: an entry with no usable `version` is dropped rather than
- * throwing, and an `integrity` that is not a canonical `sha256-<base64url>` is
- * discarded rather than carried — a pin is spliced into the author's YAML, so a
- * malformed one has to become "no pin", never corrupt text.
- */
-export function parseModuleVersions(payload) {
-    const versions = payload?.versions;
-    if (!Array.isArray(versions))
-        return [];
-    return versions.flatMap((entry) => {
-        const version = entry?.version;
-        if (typeof version !== "string" || version === "")
-            return [];
-        const integrity = entry.integrity;
-        return [isCanonicalIntegrity(integrity) ? { version, integrity } : { version }];
-    });
-}

package/src/import-upgrades/parse-module-versions.ts

@@ -1,30 +0,0 @@
-import { isCanonicalIntegrity } from "@telorun/analyzer";
-import type { ModuleVersion } from "./build-import-upgrades.js";
-
-/**
- * Read the hub's `GET /module/versions` payload into {@link ModuleVersion}s,
- * newest first (the route's own ordering, preserved).
- *
- * Pure — the host owns the `fetch`, as everything else in this package does.
- * It lives here rather than in each host because the shape is this package's:
- * three hosts parsing the same route by hand is how one of them was left
- * filtering for strings after the route started returning objects, which
- * TypeScript could not catch behind the response cast and which surfaced only
- * as a silently empty version list.
- *
- * Tolerant by design: an entry with no usable `version` is dropped rather than
- * throwing, and an `integrity` that is not a canonical `sha256-<base64url>` is
- * discarded rather than carried — a pin is spliced into the author's YAML, so a
- * malformed one has to become "no pin", never corrupt text.
- */
-export function parseModuleVersions(payload: unknown): ModuleVersion[] {
-  const versions = (payload as { versions?: unknown } | null | undefined)?.versions;
-  if (!Array.isArray(versions)) return [];
-
-  return versions.flatMap((entry) => {
-    const version = (entry as { version?: unknown } | null)?.version;
-    if (typeof version !== "string" || version === "") return [];
-    const integrity = (entry as { integrity?: unknown }).integrity;
-    return [isCanonicalIntegrity(integrity) ? { version, integrity } : { version }];
-  });
-}