@telorun/ide-support 0.6.0 → 0.7.0

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,11 +36,50 @@ 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;
 }
 
 /** A candidate module ref surfaced by the hub's `/refs` lexical autocomplete.