@telorun/analyzer 0.39.0 → 0.41.0

package/src/position-metadata.ts

@@ -1,10 +1,10 @@
-import { isMap, isPair, isScalar, isSeq, type Document } from "yaml";
 import type { Position, PositionIndex } from "./types.js";
+import type { AstDocument, AstNode } from "./yaml-ast.js";
 
 /** Single source of truth for "given the source text of a multi-document YAML
  *  file, where does each document start, and what is the byte→(line,char)
  *  table for the file." Both the analyzer's `Loader` and editor frontends
- *  feed the same parsed `yaml.Document[]` through this so diagnostics
+ *  feed the same adapted `AstDocument[]` through this so diagnostics
  *  resolved against `positionIndex` / `sourceLine` line up identically
  *  across hosts. */
 
@@ -17,7 +17,7 @@ export interface DocumentPosition {
 /** Builds DocumentPosition entries aligned to `parsedDocs[i]`. */
 export function buildDocumentPositions(
   text: string,
-  parsedDocs: Document[],
+  parsedDocs: AstDocument[],
 ): DocumentPosition[] {
   const docOffsets = documentLineOffsets(text);
   const lineOffsets = buildLineOffsets(text);
@@ -59,7 +59,7 @@ export function buildLineOffsets(text: string): number[] {
   return offsets;
 }
 
-function offsetToPosition(offset: number, lineOffsets: number[]): Position {
+export function offsetToPosition(offset: number, lineOffsets: number[]): Position {
   let lo = 0;
   let hi = lineOffsets.length - 1;
   while (lo < hi) {
@@ -70,40 +70,36 @@ function offsetToPosition(offset: number, lineOffsets: number[]): Position {
   return { line: lo, character: offset - lineOffsets[lo] };
 }
 
-/** Walks the YAML AST and records source ranges for every field value, keyed
+/** Walks the AST and records source ranges for every field value, keyed
  *  by dotted path (e.g. "kind", "config.handler", "config.routes[0].path").
  *  Map keys are also recorded under the `@key:<path>` namespace so diagnostic
  *  resolvers can squiggle just the key identifier instead of the full value
  *  block — used when a diagnostic targets a missing child property and the
  *  resolver has to fall back to the parent. */
-export function buildPositionIndex(doc: Document, lineOffsets: number[]): PositionIndex {
+export function buildPositionIndex(doc: AstDocument, lineOffsets: number[]): PositionIndex {
   const index: PositionIndex = new Map();
 
-  function recordNode(node: any, path: string): void {
-    if (!node || !node.range) return;
-    const [start, , end] = node.range as [number, number, number];
+  function recordNode(node: AstNode, path: string): void {
+    const [start, end] = node.range;
     index.set(path, {
       start: offsetToPosition(start, lineOffsets),
       end: offsetToPosition(end, lineOffsets),
     });
   }
 
-  function walk(node: any, path: string): void {
-    if (isMap(node)) {
-      for (const pair of node.items) {
-        if (!isPair(pair)) continue;
-        const key = isScalar(pair.key) ? String(pair.key.value) : null;
+  function walk(node: AstNode, path: string): void {
+    if (node.kind === "map") {
+      for (const pair of node.entries) {
+        const key = pair.key.kind === "scalar" ? String(pair.key.value) : null;
         if (key == null) continue;
         const childPath = path ? `${path}.${key}` : key;
-        if (pair.key && (pair.key as any).range) {
-          recordNode(pair.key, `@key:${childPath}`);
-        }
-        if (pair.value != null) {
+        recordNode(pair.key, `@key:${childPath}`);
+        if (pair.value) {
           recordNode(pair.value, childPath);
           walk(pair.value, childPath);
         }
       }
-    } else if (isSeq(node)) {
+    } else if (node.kind === "seq") {
       for (let i = 0; i < node.items.length; i++) {
         const item = node.items[i];
         const childPath = `${path}[${i}]`;
@@ -113,8 +109,8 @@ export function buildPositionIndex(doc: Document, lineOffsets: number[]): Positi
     }
   }
 
-  if (doc.contents) {
-    walk(doc.contents, "");
+  if (doc.root) {
+    walk(doc.root, "");
   }
 
   return index;

package/src/sources/local-path-ref.ts

@@ -0,0 +1,5 @@
+/** True when `source` names an on-disk sibling manifest — a relative (`./`,
+ *  `../`) or absolute (`/`) path — rather than a transport-owned remote ref. */
+export function isLocalPathSource(source: string): boolean {
+  return source.startsWith(".") || source.startsWith("/");
+}

package/src/yaml-ast.ts

@@ -0,0 +1,108 @@
+import { defaultCustomTags, isTaggedSentinel } from "@telorun/templating";
+import { isMap, isScalar, isSeq, parseAllDocuments, type Document, type Node } from "yaml";
+import { buildCelSegments, type CelSegment } from "./cel-ast.js";
+
+/** Read-only YAML node model owned by the analyzer — the shared, browser-safe
+ *  structural source of truth for every IDE feature. Ranges are `[start, end]`
+ *  in byte offsets (yaml's value-end, so a range spans exactly the node's own
+ *  text, not the trailing newline). `yaml` is an internal implementation
+ *  detail behind `parseToAst`; no consumer imports it to read structure. */
+export type AstNode = AstMap | AstSeq | AstScalar;
+
+export interface AstMap {
+  kind: "map";
+  range: [number, number];
+  entries: AstPair[];
+}
+
+export interface AstSeq {
+  kind: "seq";
+  range: [number, number];
+  items: AstNode[];
+}
+
+export interface AstScalar {
+  kind: "scalar";
+  range: [number, number];
+  /** Resolved scalar value — a `TaggedSentinel` for `!cel` / `!ref` scalars. */
+  value: unknown;
+  /** The scalar's tag when present (`!cel`, `!ref`, …). */
+  tag?: string;
+  /** The embedded CEL regions (lazy — nothing parses CEL until called). */
+  celSegments(): CelSegment[];
+}
+
+export interface AstPair {
+  key: AstNode;
+  value?: AstNode;
+}
+
+export interface AstDocument {
+  root?: AstNode;
+  /** Full document span `[start, end]` — used to select the `---` document a
+   *  cursor offset falls in. */
+  range: [number, number];
+}
+
+/** Parse `text` into the read-only AST. Wraps `parseAllDocuments` with the
+ *  repo's custom tags (`!cel` / `!ref`) and adapts each `yaml` tree into a
+ *  thin `AstNode` view — CEL parsing stays deferred to `celSegments().ast()`. */
+export function parseToAst(text: string): AstDocument[] {
+  const documents = parseAllDocuments(text, { customTags: defaultCustomTags() });
+  return documents.map((doc) => documentToAst(doc, text));
+}
+
+/** Adapt one already-parsed `yaml.Document` into an `AstDocument`. Lets a host
+ *  that already parsed for analysis reuse that parse instead of re-parsing. */
+export function documentToAst(doc: Document, text: string): AstDocument {
+  const r = doc.range as [number, number, number] | null | undefined;
+  return {
+    root: doc.contents ? adaptNode(doc.contents, text) : undefined,
+    range: r ? [r[0], r[2]] : [0, text.length],
+  };
+}
+
+function nodeRange(node: Node): [number, number] {
+  const r = node.range as [number, number, number] | null | undefined;
+  return r ? [r[0], r[1]] : [0, 0];
+}
+
+function adaptNode(node: Node, text: string): AstNode | undefined {
+  if (isMap(node)) {
+    const entries: AstPair[] = [];
+    for (const item of node.items) {
+      const key = adaptNode(item.key as Node, text);
+      if (!key) continue;
+      const value = item.value != null ? adaptNode(item.value as Node, text) : undefined;
+      entries.push({ key, value });
+    }
+    return { kind: "map", range: nodeRange(node), entries };
+  }
+  if (isSeq(node)) {
+    const items: AstNode[] = [];
+    for (const item of node.items) {
+      const adapted = adaptNode(item as Node, text);
+      if (adapted) items.push(adapted);
+    }
+    return { kind: "seq", range: nodeRange(node), items };
+  }
+  if (isScalar(node)) {
+    const range = nodeRange(node);
+    const value = node.value;
+    const tag = typeof node.tag === "string" ? node.tag : undefined;
+    return {
+      kind: "scalar",
+      range,
+      value,
+      tag,
+      celSegments: () =>
+        buildCelSegments(
+          text.slice(range[0], range[1]),
+          range[0],
+          tag,
+          isTaggedSentinel(value) ? value.source : undefined,
+        ),
+    };
+  }
+  return undefined;
+}