@telorun/ide-support 0.8.0 → 0.10.0

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

@@ -0,0 +1,29 @@
+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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/ide-support",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "Editor-host-agnostic IDE support (completions, diagnostic normalization) for Telo manifests.",
   "keywords": [
     "telo",
@@ -36,7 +36,7 @@
     "src/**"
   ],
   "dependencies": {
-    "@telorun/analyzer": "0.50.0"
+    "@telorun/analyzer": "0.52.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",

package/src/completions/import-source.ts

@@ -161,8 +161,8 @@ async function refSearchCompletions(
 
 /** The `org/name` tail of a location ref: its last two path segments, with the
  *  transport scheme (`oci://`, `https://`, …) and registry host dropped.
- *  `oci://ghcr.io/telorun/telo-console` → `telorun/telo-console`; `std/console`
- *  → `std/console`. Falls back to fewer segments (or the whole ref) when there
+ *  `oci://ghcr.io/telorun/telo-console` → `telorun/telo-console`; `acme/console`
+ *  → `acme/console`. Falls back to fewer segments (or the whole ref) when there
  *  aren't two. */
 function refDisplayName(ref: string): string {
   const withoutScheme = ref.replace(/^[a-z][a-z0-9+.-]*:\/\//i, "");

package/src/completions/resolve-node.ts

@@ -16,6 +16,11 @@ import {
  *  "which container am I typing into". */
 export interface ResolvedCursor {
   docIndex: number;
+  /** The cursor as a document offset. Carried so a consumer hit-testing inside a
+   *  node (a CEL chain, the halves of an `Alias.Name` value) reuses the one this
+   *  resolution was performed with, rather than recomputing the line table and
+   *  risking a different answer. */
+  offset: number;
   /** Top-level `kind:` value of the cursor's document, when present. */
   docKind?: string;
   slot: "key" | "value";
@@ -332,6 +337,7 @@ export function resolveNodeAtPosition(
     }
     return {
       docIndex,
+      offset,
       docKind,
       slot: "key",
       path: found.path,
@@ -362,6 +368,7 @@ export function resolveNodeAtPosition(
       const { path, existingKeys, scope } = columnSearch(doc.root, col, offset, lineOffsets);
       return {
         docIndex,
+        offset,
         docKind,
         slot: "key",
         path,
@@ -375,6 +382,7 @@ export function resolveNodeAtPosition(
     const clampedEnd = Math.min(offset, value.range[1]);
     return {
       docIndex,
+      offset,
       docKind,
       slot: "value",
       path: found.keyName != null ? [...found.path, found.keyName] : found.path,
@@ -395,6 +403,7 @@ export function resolveNodeAtPosition(
     : { path: [], existingKeys: new Set<string>(), scope: { depth: 0 } };
   return {
     docIndex,
+    offset,
     docKind,
     slot: "key",
     path: resolution.path,

package/src/definition/alias-qualified-value.ts

@@ -0,0 +1,42 @@
+import type { AstScalar } from "@telorun/analyzer";
+
+/** An `<Alias>.<Name>` scalar split at its first dot — the grammar `kind:`,
+ *  `extends:`, `x-telo-ref` and `!ref` all share — plus which half the cursor
+ *  sits on, so the alias navigates to its import and the suffix to the thing
+ *  the alias qualifies. */
+export interface AliasQualifiedValue {
+  /** Undefined for an unqualified value (a bare local name). */
+  alias?: string;
+  /** Everything after the first dot, or the whole value when unqualified. */
+  name: string;
+  /** True when the cursor sits on the alias half (dot inclusive). */
+  onAlias: boolean;
+}
+
+/** Split the scalar at `node` around the cursor at `offset` (a document offset).
+ *
+ *  The parsed value is authoritative where there is one — the source range spans
+ *  the whole scalar token, so a quoted `x-telo-ref: "Alias.Kind"` would otherwise
+ *  carry its quotes into the alias and miss every lookup. A `!ref` / `!cel`
+ *  scalar resolves to a tagged sentinel rather than a string, so those fall back
+ *  to the raw slice. The range is still what locates the value inside the token,
+ *  which is what the cursor is hit-tested against. */
+export function splitAliasQualified(
+  text: string,
+  node: AstScalar,
+  offset: number,
+): AliasQualifiedValue | undefined {
+  const raw = text.slice(node.range[0], node.range[1]);
+  const value = typeof node.value === "string" ? node.value : raw.trim();
+  if (!value) return undefined;
+  const at = raw.indexOf(value);
+  const start = node.range[0] + (at >= 0 ? at : 0);
+
+  const dot = value.indexOf(".");
+  if (dot === -1) return { name: value, onAlias: false };
+  return {
+    alias: value.slice(0, dot),
+    name: value.slice(dot + 1),
+    onAlias: offset <= start + dot,
+  };
+}

package/src/definition/build-definition.ts

@@ -1,97 +1,28 @@
-import {
-  parseToAst,
-  type AstDocument,
-  type LoadedFile,
-  type LoadedGraph,
-  type LoadedModule,
-  type Range,
-} from "@telorun/analyzer";
+import { parseToAst, type AstDocument, type AstScalar, type LoadedGraph } from "@telorun/analyzer";
 import type { DefinitionResult } from "../types.js";
 import { resolveNodeAtPosition } from "../completions/resolve-node.js";
+import { splitAliasQualified } from "./alias-qualified-value.js";
+import { moduleForFile } from "./manifest-navigation.js";
+import { resolveCelTarget } from "./resolve-cel-target.js";
+import { isKindSlot, resolveKindTarget } from "./resolve-kind-target.js";
+import { resolveRefTarget } from "./resolve-ref-target.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.
+/** Resolve the symbol under the cursor to where it is declared.
  *
- *  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). */
+ *  Three navigable symbol classes, each dispatched on what the cursor sits in
+ *  rather than on the field it happens to be under:
+ *
+ *  - a CEL identifier (`variables.port`, `resources.Store.conn`) → its
+ *    declaration on the module doc, or the resource it names;
+ *  - an alias-qualified kind (`kind: Http.Server`, `extends:`, `x-telo-ref`) →
+ *    the `Telo.Definition` that registers it;
+ *  - a `!ref` target → the resource instance it names.
+ *
+ *  In the last two the alias half (`Http`) navigates to the import that declares
+ *  it, and the suffix to what the alias qualifies. Returns `undefined` when the
+ *  cursor is on nothing navigable, or the target can't be found (a kernel
+ *  built-in, a scope-local name, an unexported entry, or an import that failed
+ *  to load). */
 export function buildDefinition(
   text: string,
   line: number,
@@ -101,23 +32,22 @@ export function buildDefinition(
   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 resolved = resolveNodeAtPosition(text, astDocs, line, character);
+  if (!resolved) 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);
+  if (resolved.cel) {
+    return resolveCelTarget(graph, currentModule, resolved.cel.segment, resolved.cel.offset);
   }
 
-  const edge = graph.importEdges.get(currentModule.owner.source)?.get(alias);
-  if (!edge) return undefined;
-  return resolveExported(graph, edge.targetSource, name);
+  const node = resolved.node;
+  if (resolved.slot !== "value" || node?.kind !== "scalar") return undefined;
+
+  const split = splitAliasQualified(text, node as AstScalar, resolved.offset);
+  if (!split) return undefined;
+
+  if (node.tag === "!ref") return resolveRefTarget(graph, currentModule, split);
+  if (isKindSlot(resolved)) return resolveKindTarget(graph, currentModule, split);
+  return undefined;
 }

package/src/definition/manifest-navigation.ts

@@ -0,0 +1,124 @@
+import type { LoadedFile, LoadedGraph, LoadedModule, Range } from "@telorun/analyzer";
+import type { DefinitionResult } from "../types.js";
+
+/** The shape every navigation lookup reads off a `LoadedFile.manifests` entry.
+ *  Narrower than `ResourceManifest` on purpose — navigation only ever asks what
+ *  kind a doc is and what it is named. */
+export interface NavigableManifest {
+  kind?: string;
+  metadata?: { name?: string };
+}
+
+const MODULE_DOC_KINDS = new Set(["Telo.Application", "Telo.Library"]);
+const KIND_DOC_KINDS = new Set(["Telo.Definition", "Telo.Abstract"]);
+
+/** The module whose owner or partials includes `filePath`. */
+export 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;
+}
+
+/** Every file in a module's scope, owner first. */
+export function moduleFiles(mod: LoadedModule): LoadedFile[] {
+  return [mod.owner, ...mod.partials];
+}
+
+function rangeAt(file: LoadedFile, docIndex: number, key: string): Range | undefined {
+  return file.positions[docIndex]?.positionIndex.get(key);
+}
+
+/** The value span of `path`, falling back to its key when the value has none. */
+function valueRange(file: LoadedFile, docIndex: number, path: string): Range | undefined {
+  return rangeAt(file, docIndex, path) ?? rangeAt(file, docIndex, `@key:${path}`);
+}
+
+/** The key span of `path` — what a declaration jump underlines, so the target
+ *  reads as `variables:` / `imports.Http`, not the whole block that follows. */
+function keyRange(file: LoadedFile, docIndex: number, path: string): Range | undefined {
+  return rangeAt(file, docIndex, `@key:${path}`) ?? rangeAt(file, docIndex, path);
+}
+
+function docStartRange(file: LoadedFile, docIndex: number): Range | undefined {
+  const pos = file.positions[docIndex];
+  if (!pos) return undefined;
+  return {
+    start: { line: pos.sourceLine, character: 0 },
+    end: { line: pos.sourceLine, character: 0 },
+  };
+}
+
+/** First manifest across `files` satisfying `match`, 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. */
+export function locateManifest(
+  files: LoadedFile[],
+  match: (manifest: NavigableManifest) => boolean,
+): DefinitionResult | undefined {
+  for (const file of files) {
+    for (let i = 0; i < file.manifests.length; i++) {
+      const manifest = file.manifests[i] as NavigableManifest | null;
+      if (!manifest || !match(manifest)) continue;
+      const range = valueRange(file, i, "metadata.name") ?? docStartRange(file, i);
+      if (range) return { uri: file.source, range };
+    }
+  }
+  return undefined;
+}
+
+/** The resource instance named `name` in a module scope. */
+export function locateResource(files: LoadedFile[], name: string): DefinitionResult | undefined {
+  return locateManifest(files, (m) => m.metadata?.name === name);
+}
+
+/** The `Telo.Definition` / `Telo.Abstract` doc registering kind suffix `name`.
+ *  Filtered by doc kind so an instance sharing the name never shadows it. */
+export function locateKindDefinition(
+  files: LoadedFile[],
+  name: string,
+): DefinitionResult | undefined {
+  return locateManifest(files, (m) => KIND_DOC_KINDS.has(m.kind ?? "") && m.metadata?.name === name);
+}
+
+/** Index of the module's `Telo.Application` / `Telo.Library` doc in its owner
+ *  file — where `imports`, `variables`, `secrets` and `ports` are declared. */
+function moduleDocIndex(mod: LoadedModule): number {
+  return mod.owner.manifests.findIndex((m) =>
+    MODULE_DOC_KINDS.has((m as NavigableManifest | null)?.kind ?? ""),
+  );
+}
+
+/** The module doc's JSON projection, for reading its `exports` block. */
+export function moduleDoc(mod: LoadedModule): Record<string, unknown> | undefined {
+  const index = moduleDocIndex(mod);
+  return index < 0 ? undefined : (mod.owner.manifests[index] as Record<string, unknown> | null) ?? undefined;
+}
+
+/** The module's `metadata.name` — the identity a canonical kind (`<module>.<Kind>`)
+ *  and an `ImportEdge.targetModuleName` are expressed in. */
+export function moduleName(mod: LoadedModule): string | undefined {
+  return (moduleDoc(mod) as NavigableManifest | undefined)?.metadata?.name;
+}
+
+/** A dotted key path on the module doc (`imports.Http`, `variables.port`),
+ *  located at the key itself. */
+export function locateModuleDocKey(
+  mod: LoadedModule,
+  path: string,
+): DefinitionResult | undefined {
+  const index = moduleDocIndex(mod);
+  if (index < 0) return undefined;
+  const range = keyRange(mod.owner, index, path);
+  return range ? { uri: mod.owner.source, range } : undefined;
+}
+
+/** Where the import bound to `alias` is declared: the `imports:` map entry, or
+ *  the legacy standalone `Telo.Import` doc named after the alias. */
+export function locateImport(mod: LoadedModule, alias: string): DefinitionResult | undefined {
+  return (
+    locateModuleDocKey(mod, `imports.${alias}`) ??
+    locateManifest(moduleFiles(mod), (m) => m.kind === "Telo.Import" && m.metadata?.name === alias)
+  );
+}

package/src/definition/resolve-cel-target.ts

@@ -0,0 +1,151 @@
+import {
+  CelParseError,
+  type CelNode,
+  type CelSegment,
+  type LoadedGraph,
+  type LoadedModule,
+} from "@telorun/analyzer";
+import type { DefinitionResult } from "../types.js";
+import {
+  locateImport,
+  locateModuleDocKey,
+  locateResource,
+  moduleFiles,
+} from "./manifest-navigation.js";
+import { resolveExportedResource } from "./resolve-export-chain.js";
+
+/** Root CEL scopes whose members are declared as a block on the module doc, so
+ *  `variables.port` navigates to `variables:` and then to its `port:` entry. */
+const DECLARATION_SCOPES = new Set(["variables", "secrets", "ports"]);
+
+/** One identifier of a dotted CEL chain, with the span the cursor hit-tests
+ *  against. */
+interface ChainPart {
+  name: string;
+  range: [number, number];
+}
+
+/** Flatten `a.b.c` into its identifiers. Returns undefined as soon as the chain
+ *  is rooted in something other than a plain identifier (a call, an index), so a
+ *  navigable prefix is never invented out of a computed expression. */
+function flattenChain(node: CelNode): ChainPart[] | undefined {
+  if (node.kind === "ident") return [{ name: node.name, range: node.range }];
+  if (node.kind !== "member") return undefined;
+  const head = flattenChain(node.target);
+  return head ? [...head, { name: node.property, range: node.propertyRange }] : undefined;
+}
+
+/** Exhaustive by construction: a new `CelNode` variant fails the build here
+ *  rather than silently going unwalked, so the analyzer's node model and this
+ *  walk cannot drift apart unnoticed. */
+function celChildren(node: CelNode): CelNode[] {
+  switch (node.kind) {
+    case "literal":
+    case "ident":
+      return [];
+    case "member":
+      return [node.target];
+    case "index":
+      return [node.target, node.index];
+    case "call":
+      return node.args;
+    case "methodCall":
+      return [node.receiver, ...node.args];
+    case "list":
+      return node.items;
+    case "map":
+      return node.entries.flatMap((e) => [e.key, e.value]);
+    case "ternary":
+      return [node.cond, node.then, node.else];
+    case "unary":
+      return [node.operand];
+    case "binary":
+      return [node.left, node.right];
+  }
+  const unhandled: never = node;
+  throw new Error(`Unhandled CEL node: ${JSON.stringify(unhandled)}`);
+}
+
+/** The dotted chain under `offset`, and which of its identifiers was hit. The
+ *  walk is outermost-first so the longest chain wins — `resources.Store.conn`
+ *  resolves as one chain rather than as its `resources.Store` prefix. */
+function chainAt(
+  node: CelNode,
+  offset: number,
+): { parts: ChainPart[]; index: number } | undefined {
+  if (offset < node.range[0] || offset > node.range[1]) return undefined;
+  const parts = flattenChain(node);
+  if (parts) {
+    const index = parts.findIndex((p) => offset >= p.range[0] && offset <= p.range[1]);
+    if (index >= 0) return { parts, index };
+  }
+  for (const child of celChildren(node)) {
+    const hit = chainAt(child, offset);
+    if (hit) return hit;
+  }
+  return undefined;
+}
+
+/** `resources.<name>` is a local instance; `resources.<Alias>.<name>` is an
+ *  imported module's exported one. A local name wins over an import alias, so a
+ *  deeper access on a local instance (`resources.db.url`) reads as a field of
+ *  that instance rather than as a cross-module lookup. */
+function resolveResourceChain(
+  graph: LoadedGraph,
+  currentModule: LoadedModule,
+  parts: ChainPart[],
+  index: number,
+): DefinitionResult | undefined {
+  if (index === 0) return undefined;
+  const first = parts[1].name;
+
+  const local = locateResource(moduleFiles(currentModule), first);
+  if (local) return index === 1 ? local : undefined;
+
+  const edge = graph.importEdges.get(currentModule.owner.source)?.get(first);
+  if (!edge) return undefined;
+  if (index === 1) return locateImport(currentModule, first);
+  if (index === 2) return resolveExportedResource(graph, edge.targetSource, parts[2].name);
+  return undefined;
+}
+
+/** Resolve the CEL identifier under the cursor to where it is declared.
+ *
+ *  `variables` / `secrets` / `ports` navigate to their block on the module doc,
+ *  and their member to that block's entry. `resources` navigates through the
+ *  same instance lookup a `!ref` uses. Anything else (a step result, a handler
+ *  scope like `request`, a member of a resolved value) has no manifest
+ *  declaration to jump to and resolves to nothing.
+ *
+ *  A body the author is still writing may not parse; that means there is no
+ *  chain to hit-test, not an error to surface from a navigation request — the
+ *  analyzer reports the syntax error itself. Only that failure is tolerated: a
+ *  defect in the CEL wrapper propagates rather than reading as "nothing to
+ *  navigate to". */
+export function resolveCelTarget(
+  graph: LoadedGraph,
+  currentModule: LoadedModule,
+  segment: CelSegment,
+  offset: number,
+): DefinitionResult | undefined {
+  let ast: CelNode;
+  try {
+    ast = segment.ast();
+  } catch (error) {
+    if (!(error instanceof CelParseError)) throw error;
+    return undefined;
+  }
+
+  const hit = chainAt(ast, offset);
+  if (!hit) return undefined;
+  const { parts, index } = hit;
+  const root = parts[0].name;
+
+  if (DECLARATION_SCOPES.has(root)) {
+    if (index === 0) return locateModuleDocKey(currentModule, root);
+    if (index === 1) return locateModuleDocKey(currentModule, `${root}.${parts[1].name}`);
+    return undefined;
+  }
+  if (root === "resources") return resolveResourceChain(graph, currentModule, parts, index);
+  return undefined;
+}