@telorun/ide-support 0.8.0 → 0.9.0

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

package/src/definition/resolve-export-chain.ts

@@ -0,0 +1,119 @@
+import {
+  parseExportEntry,
+  resolveExportedKinds,
+  type LoadedGraph,
+  type LoadedModule,
+} from "@telorun/analyzer";
+import type { DefinitionResult } from "../types.js";
+import {
+  locateKindDefinition,
+  locateResource,
+  moduleDoc,
+  moduleFiles,
+  moduleName,
+} from "./manifest-navigation.js";
+
+/** One `exports.*` list as authored. `undefined` means the block is ABSENT,
+ *  which is not the same as an empty list — the distinction is the gate itself,
+ *  and it is load-bearing in both halves (`AliasResolver.registerImport`,
+ *  `ModuleContext.buildExportTable`), so it must survive here too. */
+function exportList(
+  mod: LoadedModule,
+  block: "kinds" | "resources",
+): readonly string[] | undefined {
+  const exports = (moduleDoc(mod) as { exports?: Record<string, unknown> } | undefined)?.exports;
+  const list = exports?.[block];
+  if (!Array.isArray(list)) return undefined;
+  return list.filter((e): e is string => typeof e === "string");
+}
+
+/** Every loaded module keyed by its `metadata.name` — what `resolveExportedKinds`
+ *  speaks, since a canonical kind names its owning module rather than a URL. */
+function modulesByName(graph: LoadedGraph): Map<string, LoadedModule> {
+  const byName = new Map<string, LoadedModule>();
+  for (const mod of graph.modules.values()) {
+    const name = moduleName(mod);
+    if (name && !byName.has(name)) byName.set(name, mod);
+  }
+  return byName;
+}
+
+/** Resolve the kind suffix `name` exported by the module at `targetSource` to
+ *  the `Telo.Definition` / `Telo.Abstract` doc that owns it.
+ *
+ *  The gate and the transitive re-export chain come from the analyzer's own
+ *  `resolveExportedKinds` fixpoint rather than a local walk, so navigation
+ *  cannot disagree with `telo check` about what an import exposes — including
+ *  the two rules a hand-rolled walk gets wrong: `exports.kinds: []` gates
+ *  everything while an absent block gates nothing, and a re-export FROM an
+ *  ungated module resolves straight to it. */
+export function resolveExportedKind(
+  graph: LoadedGraph,
+  targetSource: string,
+  name: string,
+): DefinitionResult | undefined {
+  const target = graph.modules.get(targetSource);
+  if (!target) return undefined;
+
+  // No `exports.kinds` block → every kind the module defines is importable (the
+  // legacy permissive default the kernel still honors for already-published
+  // versions). The fixpoint builds tables only from declared entries, so an
+  // ungated module has none to look this up in — and this is also the cheap
+  // path, so it settles before anything is indexed.
+  if (exportList(target, "kinds") === undefined) {
+    return locateKindDefinition(moduleFiles(target), name);
+  }
+
+  const targetName = moduleName(target);
+  if (!targetName) return undefined;
+
+  const byName = modulesByName(graph);
+  const tables = resolveExportedKinds(
+    [...byName].map(([module, mod]) => ({ module, exportsKinds: exportList(mod, "kinds") })),
+    (module, alias) => {
+      const owner = byName.get(module)?.owner.source;
+      return owner ? graph.importEdges.get(owner)?.get(alias)?.targetModuleName ?? undefined : undefined;
+    },
+  );
+
+  const canonical = tables.get(targetName)?.get(name);
+  if (!canonical) return undefined;
+
+  // `<owningModule>.<Kind>` — a re-export resolves to its true owner, so the
+  // jump lands where the kind is actually declared, however many hops away.
+  const dot = canonical.lastIndexOf(".");
+  const owner = byName.get(canonical.slice(0, dot));
+  return owner ? locateKindDefinition(moduleFiles(owner), canonical.slice(dot + 1)) : undefined;
+}
+
+/** Resolve the instance `name` exported by the module at `targetSource`,
+ *  following `<Alias>.<name>` re-exports transitively. `seen` bounds cyclic
+ *  import graphs.
+ *
+ *  Unlike kinds there is no permissive default: the kernel reads
+ *  `exports.resources ?? []` and builds its export table strictly from that, so
+ *  an absent block exports nothing and an unlisted name is an
+ *  `UNRESOLVED_REFERENCE` — navigating to it would tell the author a wiring is
+ *  real that the analyzer rejects. */
+export function resolveExportedResource(
+  graph: LoadedGraph,
+  targetSource: string,
+  name: string,
+  seen: Set<string> = new Set(),
+): DefinitionResult | undefined {
+  if (seen.has(targetSource)) return undefined;
+  seen.add(targetSource);
+  const target = graph.modules.get(targetSource);
+  if (!target) return undefined;
+
+  const entries = (exportList(target, "resources") ?? []).map(parseExportEntry);
+  const entry = entries.find((e) => e.name === name);
+  if (!entry) return undefined;
+
+  // `Self.<name>` names the declaring module's own instance, exactly as a bare
+  // name does — `ModuleContext.buildExportTable` treats the two alike.
+  if (!entry.alias || entry.alias === "Self") return locateResource(moduleFiles(target), name);
+
+  const edge = graph.importEdges.get(target.owner.source)?.get(entry.alias);
+  return edge ? resolveExportedResource(graph, edge.targetSource, name, seen) : undefined;
+}

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

@@ -0,0 +1,61 @@
+import type { LoadedGraph, LoadedModule } from "@telorun/analyzer";
+import type { DefinitionResult } from "../types.js";
+import type { ResolvedCursor } from "../completions/resolve-node.js";
+import type { AliasQualifiedValue } from "./alias-qualified-value.js";
+import { locateImport, locateKindDefinition, moduleFiles } from "./manifest-navigation.js";
+import { resolveExportedKind } from "./resolve-export-chain.js";
+
+const DEFINITION_DOC_KINDS = new Set(["Telo.Definition", "Telo.Abstract"]);
+
+/** Whether the cursor sits in a slot whose value is an alias-qualified kind.
+ *
+ *  `x-telo-ref` is an `x-telo-*` annotation, unambiguous wherever it appears.
+ *  `extends:` is only a kind at the top level of a definition doc, so it is
+ *  gated on both. `kind:` is positional by nature: a map carrying a
+ *  `<Alias>.<Kind>` value under `kind` IS an inline resource declaration as far
+ *  as the analyzer is concerned too (`resourceKindOf`), so there is no further
+ *  structure to check — an unresolvable value simply navigates nowhere.
+ *
+ *  `capability:` is deliberately absent — its values are kernel built-ins with
+ *  no manifest to jump to (hover documents them instead). */
+export function isKindSlot(resolved: ResolvedCursor): boolean {
+  const key = resolved.path[resolved.path.length - 1];
+  if (key === "x-telo-ref" || key === "kind") return true;
+  return (
+    key === "extends" &&
+    resolved.path.length === 1 &&
+    DEFINITION_DOC_KINDS.has(resolved.docKind ?? "")
+  );
+}
+
+/** Resolve an alias-qualified kind (`Http.Server`) to the `Telo.Definition` /
+ *  `Telo.Abstract` doc that registers it, or — when the cursor sits on the
+ *  alias — to the import that declares the alias.
+ *
+ *  `Self.<Kind>` is the declaring module's own kind; `Telo.<Kind>` is a kernel
+ *  built-in with no manifest, so it resolves to nothing. Across an import the
+ *  walk honors `exports.kinds` and follows `<Inner>.<Kind>` re-exports to the
+ *  owning module, matching what the kernel resolves the kind to at runtime. */
+export function resolveKindTarget(
+  graph: LoadedGraph,
+  currentModule: LoadedModule,
+  kind: AliasQualifiedValue,
+): DefinitionResult | undefined {
+  const { alias, name, onAlias } = kind;
+
+  if (alias === undefined) {
+    // The legacy `<namespace>/<module>#<Kind>` identity form of `x-telo-ref`
+    // still resolves for already-published module versions, but it names a
+    // module this manifest need not import, so there is no alias to follow.
+    if (name.includes("#")) return undefined;
+    return locateKindDefinition(moduleFiles(currentModule), name);
+  }
+  if (alias === "Self") return locateKindDefinition(moduleFiles(currentModule), name);
+  if (alias === "Telo") return undefined;
+
+  if (onAlias) return locateImport(currentModule, alias);
+
+  const edge = graph.importEdges.get(currentModule.owner.source)?.get(alias);
+  if (!edge) return undefined;
+  return resolveExportedKind(graph, edge.targetSource, name);
+}

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

@@ -0,0 +1,34 @@
+import type { LoadedGraph, LoadedModule } from "@telorun/analyzer";
+import type { DefinitionResult } from "../types.js";
+import type { AliasQualifiedValue } from "./alias-qualified-value.js";
+import { locateImport, locateResource, moduleFiles } from "./manifest-navigation.js";
+import { resolveExportedResource } from "./resolve-export-chain.js";
+
+/** Resolve a `!ref` target to the resource instance it names.
+ *
+ *  The grammar mirrors `resolveRefSentinels`: 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`. The alias half
+ *  navigates to the import that declares it. Returns `undefined` when the target
+ *  can't be found (a scope-local name, an instance the target does not export,
+ *  or an import that failed to load). */
+export function resolveRefTarget(
+  graph: LoadedGraph,
+  currentModule: LoadedModule,
+  ref: AliasQualifiedValue,
+): DefinitionResult | undefined {
+  const { alias, name, onAlias } = ref;
+
+  if (alias === undefined || alias === "Self") {
+    // `Self` names the declaring module itself — there is no import to jump to,
+    // so the alias half resolves like the name half.
+    return locateResource(moduleFiles(currentModule), name);
+  }
+
+  if (onAlias) return locateImport(currentModule, alias);
+
+  const edge = graph.importEdges.get(currentModule.owner.source)?.get(alias);
+  if (!edge) return undefined;
+  return resolveExportedResource(graph, edge.targetSource, name);
+}