@telorun/ide-support 0.5.0 → 0.7.0

package/src/definition/build-definition.ts

@@ -0,0 +1,123 @@
+import {
+  parseToAst,
+  type AstDocument,
+  type LoadedFile,
+  type LoadedGraph,
+  type LoadedModule,
+  type Range,
+} from "@telorun/analyzer";
+import type { DefinitionResult } from "../types.js";
+import { resolveNodeAtPosition } from "../completions/resolve-node.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.
+ *
+ *  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). */
+export function buildDefinition(
+  text: string,
+  line: number,
+  character: number,
+  graph: LoadedGraph,
+  currentFilePath: string,
+  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 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);
+  }
+
+  const edge = graph.importEdges.get(currentModule.owner.source)?.get(alias);
+  if (!edge) return undefined;
+  return resolveExported(graph, edge.targetSource, name);
+}

package/src/definition/index.ts

@@ -0,0 +1 @@
+export { buildDefinition } from "./build-definition.js";

package/src/hover/build-hover.ts

@@ -0,0 +1,149 @@
+import {
+  parseToAst,
+  type AnalysisRegistry,
+  type AstDocument,
+} from "@telorun/analyzer";
+import type { HoverResult } from "../types.js";
+import { navigateSchema } from "../completions/detect-context.js";
+import {
+  resolveNodeAtPosition,
+  scalarString,
+  type ResolvedCursor,
+} from "../completions/resolve-node.js";
+import { CAPABILITY_DOCS } from "../completions/valid-capabilities.js";
+
+type Definition = NonNullable<ReturnType<AnalysisRegistry["resolveDefinition"]>>;
+
+/** Docs for the structural keys shared by every module doc, so hover is useful
+ *  even at the root, where there is no user-authored schema to navigate. */
+const STRUCTURAL_KEY_DOCS: Record<string, string> = {
+  kind: "The resource kind — `Alias.Name` for an imported kind, or a `Telo.*` root kind.",
+  metadata: "Resource identity: `name` (kebab-case, dot-free) and optional `namespace`.",
+  imports: "Dependency map: PascalCase alias → `namespace/name@version` source string or object.",
+  targets: "Boot sequence run after init — references to `Runnable`/`Service` resources or inline invoke steps.",
+  variables: "Typed inputs bound from host env vars (`env:` + JSON-Schema `type:`).",
+  secrets: "Secret inputs bound from host env vars (`env:` + `type:`).",
+  ports: "Inbound ports the app listens on, each bound to a host env var (Application only).",
+  exports: "What importers may reference: `kinds` (kind gate) and `resources` (instance singletons).",
+  include: "Partial files loaded into this module scope (paths / globs).",
+  capability: "The lifecycle role of the kind this definition registers.",
+  schema: "JSON Schema for the kind's config fields, with `x-telo-*` annotations.",
+  extends: "Alias-form kind this definition specializes (abstract contract or concrete parent).",
+  base: "Construction mapping (`super(...)`) over `self` for a concrete-`extends` definition.",
+  controllers: "Controller locator (`pkg:npm`) implementing this kind.",
+};
+
+/** The kind value of the map that directly encloses `keyName` in the value slot. */
+function typeName(t: string | Record<string, any> | undefined): string | undefined {
+  if (typeof t === "string") return t;
+  if (t && typeof t === "object" && typeof t.title === "string") return t.title;
+  return undefined;
+}
+
+function kindHover(kind: string, def: Definition | undefined): string {
+  if (!def) return `\`${kind}\``;
+  const lines: string[] = [`### ${kind}`];
+  const role = def.capability ? `\`${def.capability}\`` : "resource";
+  const module = def.metadata?.module ? ` · module \`${def.metadata.module}\`` : "";
+  lines.push(`${role}${module}`);
+  const schema = def.schema as Record<string, any> | undefined;
+  const desc = schema?.description ?? schema?.title;
+  if (typeof desc === "string" && desc) lines.push("", desc);
+  if (def.extends) lines.push("", `Extends \`${def.extends}\``);
+  const input = typeName(def.inputType);
+  const output = typeName(def.outputType);
+  if (input) lines.push(`Input \`${input}\``);
+  if (output) lines.push(`Output \`${output}\``);
+  return lines.join("\n");
+}
+
+function fieldHover(keyName: string, field: Record<string, any>): string {
+  const lines: string[] = [];
+  const type = Array.isArray(field.type) ? field.type.join(" | ") : field.type;
+  const head = type ? `**${keyName}**: \`${type}\`` : `**${keyName}**`;
+  lines.push(head);
+  if (typeof field.description === "string" && field.description) {
+    lines.push("", field.description);
+  }
+  const ref = field["x-telo-ref"];
+  if (typeof ref === "string") lines.push("", `Reference → \`${ref}\``);
+  if (Array.isArray(field.enum) && field.enum.length > 0) {
+    lines.push("", `Allowed: ${field.enum.map((v: unknown) => `\`${v}\``).join(", ")}`);
+  }
+  if (field.default !== undefined) lines.push(`Default: \`${JSON.stringify(field.default)}\``);
+  return lines.length > 0 ? lines.join("\n") : `**${keyName}**`;
+}
+
+/** Field schema at the nearest enclosing resource, or undefined when the scope
+ *  can't be resolved (no kind-bearing ancestor, or the path doesn't navigate). */
+function fieldSchemaFor(
+  resourceKind: string | undefined,
+  relativePath: string[],
+  registry: AnalysisRegistry | undefined,
+): Record<string, any> | undefined {
+  if (!resourceKind || !registry) return undefined;
+  const def = registry.resolveDefinition(resourceKind);
+  if (!def?.schema) return undefined;
+  return navigateSchema(def.schema as Record<string, any>, relativePath);
+}
+
+export function buildHover(
+  text: string,
+  line: number,
+  character: number,
+  registry: AnalysisRegistry | undefined,
+  docs?: AstDocument[],
+): HoverResult | undefined {
+  const astDocs = docs ?? parseToAst(text);
+  const resolved = resolveNodeAtPosition(text, astDocs, line, character);
+  if (!resolved) return undefined;
+
+  if (resolved.slot === "value") return hoverForValue(resolved, registry);
+  return hoverForKey(resolved, registry);
+}
+
+function hoverForValue(
+  resolved: ResolvedCursor,
+  registry: AnalysisRegistry | undefined,
+): HoverResult | undefined {
+  const key = resolved.path[resolved.path.length - 1];
+  const value = scalarString(resolved.node);
+  const range = resolved.replaceRange;
+
+  if (key === "kind" && value) {
+    return { contents: kindHover(value, registry?.resolveDefinition(value)), range };
+  }
+  if (key === "capability" && resolved.docKind === "Telo.Definition" && value) {
+    const doc = CAPABILITY_DOCS[value];
+    return doc ? { contents: `**${value}**\n\n${doc}`, range } : undefined;
+  }
+
+  // Field value: describe the field via the enclosing resource's schema. Works
+  // when the value sits directly under a kind-bearing map (`siblingKind`); the
+  // field path relative to that map is just the key.
+  if (key) {
+    const field = fieldSchemaFor(resolved.siblingKind, [key], registry);
+    if (field) return { contents: fieldHover(key, field), range };
+  }
+  return undefined;
+}
+
+function hoverForKey(
+  resolved: ResolvedCursor,
+  registry: AnalysisRegistry | undefined,
+): HoverResult | undefined {
+  const keyName = scalarString(resolved.node);
+  if (!keyName) return undefined;
+  const range = resolved.replaceRange;
+
+  const resourceKind = resolved.resourceKind ?? resolved.docKind;
+  const relativePath = [...resolved.path.slice(resolved.resourceDepth ?? 0), keyName];
+  const field = fieldSchemaFor(resourceKind, relativePath, registry);
+  if (field) return { contents: fieldHover(keyName, field), range };
+
+  const structural = STRUCTURAL_KEY_DOCS[keyName];
+  if (structural && relativePath.length === 1) {
+    return { contents: `**${keyName}**\n\n${structural}`, range };
+  }
+  return undefined;
+}

package/src/hover/index.ts

@@ -0,0 +1 @@
+export { buildHover } from "./build-hover.js";

package/src/index.ts

@@ -1,3 +1,6 @@
 export * from "./types.js";
 export * from "./completions/index.js";
 export * from "./diagnostics/index.js";
+export * from "./hover/index.js";
+export * from "./semantic-tokens/index.js";
+export * from "./definition/index.js";

package/src/semantic-tokens/build-semantic-tokens.ts

@@ -0,0 +1,64 @@
+import {
+  buildLineOffsets,
+  offsetToPosition,
+  parseToAst,
+  type AnalysisRegistry,
+  type AstDocument,
+  type AstNode,
+} from "@telorun/analyzer";
+import type { SemanticToken } from "../types.js";
+import { scalarString } from "../completions/resolve-node.js";
+import { CAPABILITY_VALUES } from "../completions/valid-capabilities.js";
+
+const CAPABILITIES = new Set<string>(CAPABILITY_VALUES);
+
+/** Registry-aware semantic tokens: a `kind:` value that resolves to a known
+ *  definition is a `type`; a `capability:` value is an `interface`; a `!ref`
+ *  target is a `variable`. Everything else (structure, CEL, tags) is left to the
+ *  TextMate grammar. Ref targets are colored here rather than in the grammar
+ *  because a `!ref` after a `key:` is tokenized by the bundled YAML grammar
+ *  before a Telo pattern can claim it — the AST sees it unambiguously. An
+ *  unresolved kind gets no token, so a typo stays uncolored — a quiet signal
+ *  that pairs with the analyzer's `UNDEFINED_KIND` diagnostic. */
+export function buildSemanticTokens(
+  text: string,
+  registry: AnalysisRegistry | undefined,
+  docs?: AstDocument[],
+): SemanticToken[] {
+  const astDocs = docs ?? parseToAst(text);
+  const lineOffsets = buildLineOffsets(text);
+
+  const tokens: SemanticToken[] = [];
+  const emit = (node: AstNode | undefined, type: SemanticToken["type"]): void => {
+    if (!node) return;
+    const start = offsetToPosition(node.range[0], lineOffsets);
+    const end = offsetToPosition(node.range[1], lineOffsets);
+    // Kind / capability values never span lines; a clamped single-line token.
+    if (start.line !== end.line) return;
+    tokens.push({ line: start.line, character: start.character, length: end.character - start.character, type });
+  };
+
+  const walk = (node: AstNode): void => {
+    if (node.kind === "map") {
+      for (const pair of node.entries) {
+        const key = scalarString(pair.key);
+        const value = scalarString(pair.value);
+        if (key === "kind" && value && registry?.resolveDefinition(value)) {
+          emit(pair.value, "type");
+        } else if (key === "capability" && value && CAPABILITIES.has(value)) {
+          emit(pair.value, "interface");
+        }
+        if (pair.value) walk(pair.value);
+      }
+    } else if (node.kind === "seq") {
+      for (const item of node.items) walk(item);
+    } else if (node.kind === "scalar" && node.tag === "!ref") {
+      emit(node, "variable");
+    }
+  };
+
+  for (const doc of astDocs) {
+    if (doc.root) walk(doc.root);
+  }
+  return tokens;
+}

package/src/semantic-tokens/index.ts

@@ -0,0 +1 @@
+export { buildSemanticTokens } from "./build-semantic-tokens.js";

package/src/types.ts

@@ -10,10 +10,22 @@ export type {
   PositionIndex,
 } from "@telorun/analyzer";
 
-import type { AnalysisRegistry, DiagnosticSeverity, PositionIndex, Range } from "@telorun/analyzer";
+import type {
+  AnalysisRegistry,
+  DiagnosticSeverity,
+  Position,
+  PositionIndex,
+  Range,
+} from "@telorun/analyzer";
 
 export type CompletionKind = "class" | "enumMember" | "property" | "folder" | "module" | "value";
 
+/** A source span the host replaces wholesale when a completion is accepted. */
+export interface ReplaceRange {
+  start: Position;
+  end: Position;
+}
+
 export interface CompletionResult {
   label: string;
   kind: CompletionKind;
@@ -24,24 +36,69 @@ export interface CompletionResult {
   preselect?: boolean;
   sortText?: string;
   filterText?: string;
-  /** When set, the host should replace text from this 0-based column on the
-   *  cursor's line up to the cursor. Required when the completion value
-   *  contains non-word characters (`/`, `@`, `.`) that the host's default
-   *  word boundary would not include in the replaced range. */
-  replaceFromColumn?: number;
+  /** When set, the host replaces this whole source range with the accepted
+   *  value — the full span of the existing node, not just the prefix up to the
+   *  cursor. This overwrites any suffix after the cursor (`Sql.Co|nnection` +
+   *  `Sql.Connection` → no leftover `nnection`) and cleanly replaces values
+   *  containing non-word characters (`/`, `@`, `.`). A zero-width range is a
+   *  pure insert. */
+  replaceRange?: ReplaceRange;
+}
+
+/** Rendered hover for the symbol under the cursor. `contents` is GitHub-flavored
+ *  markdown; `range` (when present) is the source span the host underlines. */
+export interface HoverResult {
+  contents: string;
+  range?: ReplaceRange;
+}
+
+/** Semantic token type names emitted by `buildSemanticTokens`. Kept to the
+ *  standard VS Code / LSP set so hosts register them against a stock legend and
+ *  every theme colors them without extra configuration. `type` marks a resolved
+ *  resource kind; `interface` marks a capability value; `variable` marks a
+ *  `!ref` target. */
+export type SemanticTokenType = "type" | "interface" | "variable";
+
+/** The legend a host registers before mapping `buildSemanticTokens` output. The
+ *  numeric token-type of each `SemanticToken` is its index in this array. */
+export const SEMANTIC_TOKEN_LEGEND: readonly SemanticTokenType[] = ["type", "interface", "variable"];
+
+/** One absolute-positioned semantic token. Every Telo semantic token is
+ *  single-line (kinds and capabilities never wrap), so a `{line, char, length}`
+ *  triple is sufficient; the host encodes it into its own builder. */
+export interface SemanticToken {
+  line: number;
+  character: number;
+  length: number;
+  type: SemanticTokenType;
+}
+
+/** Where a `!ref` target is defined — for go-to-definition. `uri` is the
+ *  target file's canonical source (absolute path for local files, an http/oci
+ *  URL for a registry import); `range` spans the target resource's
+ *  `metadata.name` (falling back to its first line). */
+export interface DefinitionResult {
+  uri: string;
+  range: Range;
 }
 
-export interface RegistryModule {
-  namespace: string;
-  name: string;
-  version: string;
+/** A candidate module ref surfaced by the hub's `/refs` lexical autocomplete.
+ *  Identity is the location ref, never `namespace/name` — an OCI module has no
+ *  addressable `namespace/name`. `latestVersion` seeds a pinned `ref@version`
+ *  insert so a picked completion is directly usable. */
+export interface HubRef {
+  ref: string;
+  latestVersion: string;
   description?: string;
 }
 
 /** Host-supplied bridge that lets ide-support reach the filesystem and the
- *  module registry without depending on Node, Tauri, or vscode APIs. Each
+ *  federated telo hub without depending on Node, Tauri, or vscode APIs. Each
  *  host (VSCode extension, Telo editor) builds an adapter scoped to the
- *  currently-edited manifest before calling `buildCompletions`. */
+ *  currently-edited manifest before calling `buildCompletions`. Hub lookups are
+ *  ref-keyed: the hub aggregates modules across every transport (OCI, HTTP,
+ *  direct URL), so completion speaks its `/refs` + `/module/versions` verbs
+ *  rather than any single registry. */
 export interface IdeEnvironmentAdapter {
   /** Subdirectory names within `relPath` (resolved against the manifest's
    *  directory). Returns [] if the path doesn't exist or isn't a directory.
@@ -50,12 +107,15 @@ export interface IdeEnvironmentAdapter {
   /** True iff `<relPath>/telo.yaml` exists relative to the manifest dir.
    *  Used to mark directories that are valid import targets. */
   hasManifest(relPath: string): Promise<boolean>;
-  /** Free-text search against the configured module registry. Matches against
-   *  name, namespace, and description. Empty `query` should return the full
-   *  (capped) catalog. */
-  searchRegistry(query: string): Promise<RegistryModule[]>;
-  /** All published versions for a module, newest first. */
-  listRegistryVersions(namespace: string, name: string): Promise<string[]>;
+  /** Fuzzy lexical ref autocomplete against the configured telo hub
+   *  (`GET /refs?q=`). The query is matched as a substring over every
+   *  registered ref, so a bare token (`youtrack`) hits the same ref as its full
+   *  `oci://…` form. Best-effort — hosts swallow network errors and return []. */
+  searchRefs(query: string): Promise<HubRef[]>;
+  /** All tracked versions for a location ref, newest first
+   *  (`GET /module/versions?ref=`). The browser cannot call OCI `tags/list`;
+   *  the hub holds them from ingest. */
+  listVersionsForRef(ref: string): Promise<string[]>;
 }
 
 export interface NormalizedDiagnostic {