@telorun/ide-support 0.8.0 → 0.9.0

package/dist/definition/resolve-export-chain.js

@@ -0,0 +1,89 @@
+import { parseExportEntry, resolveExportedKinds, } from "@telorun/analyzer";
+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, block) {
+    const exports = moduleDoc(mod)?.exports;
+    const list = exports?.[block];
+    if (!Array.isArray(list))
+        return undefined;
+    return list.filter((e) => 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) {
+    const byName = new Map();
+    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, targetSource, name) {
+    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, targetSource, name, seen = new Set()) {
+    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/dist/definition/resolve-kind-target.d.ts

@@ -0,0 +1,26 @@
+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";
+/** 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 declare function isKindSlot(resolved: ResolvedCursor): boolean;
+/** 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 declare function resolveKindTarget(graph: LoadedGraph, currentModule: LoadedModule, kind: AliasQualifiedValue): DefinitionResult | undefined;
+//# sourceMappingURL=resolve-kind-target.d.ts.map

package/dist/definition/resolve-kind-target.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-kind-target.d.ts","sourceRoot":"","sources":["../../src/definition/resolve-kind-target.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACnE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AACrE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAMtE;;;;;;;;;;6DAU6D;AAC7D,wBAAgB,UAAU,CAAC,QAAQ,EAAE,cAAc,GAAG,OAAO,CAQ5D;AAED;;;;;;;+EAO+E;AAC/E,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,WAAW,EAClB,aAAa,EAAE,YAAY,EAC3B,IAAI,EAAE,mBAAmB,GACxB,gBAAgB,GAAG,SAAS,CAkB9B"}

package/dist/definition/resolve-kind-target.js

@@ -0,0 +1,51 @@
+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) {
+    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, currentModule, kind) {
+    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/dist/definition/resolve-ref-target.d.ts

@@ -0,0 +1,14 @@
+import type { LoadedGraph, LoadedModule } from "@telorun/analyzer";
+import type { DefinitionResult } from "../types.js";
+import type { AliasQualifiedValue } from "./alias-qualified-value.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 declare function resolveRefTarget(graph: LoadedGraph, currentModule: LoadedModule, ref: AliasQualifiedValue): DefinitionResult | undefined;
+//# sourceMappingURL=resolve-ref-target.d.ts.map

package/dist/definition/resolve-ref-target.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-ref-target.d.ts","sourceRoot":"","sources":["../../src/definition/resolve-ref-target.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACnE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAItE;;;;;;;;yCAQyC;AACzC,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,WAAW,EAClB,aAAa,EAAE,YAAY,EAC3B,GAAG,EAAE,mBAAmB,GACvB,gBAAgB,GAAG,SAAS,CAc9B"}

package/dist/definition/resolve-ref-target.js

@@ -0,0 +1,25 @@
+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, currentModule, ref) {
+    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);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/ide-support",
-  "version": "0.8.0",
+  "version": "0.9.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.51.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)
+  );
+}