@telorun/analyzer 0.39.0 → 0.41.0

package/dist/position-metadata.js

@@ -1,4 +1,3 @@
-import { isMap, isPair, isScalar, isSeq } from "yaml";
 /** Builds DocumentPosition entries aligned to `parsedDocs[i]`. */
 export function buildDocumentPositions(text, parsedDocs) {
     const docOffsets = documentLineOffsets(text);
@@ -40,7 +39,7 @@ export function buildLineOffsets(text) {
     }
     return offsets;
 }
-function offsetToPosition(offset, lineOffsets) {
+export function offsetToPosition(offset, lineOffsets) {
     let lo = 0;
     let hi = lineOffsets.length - 1;
     while (lo < hi) {
@@ -52,7 +51,7 @@ function offsetToPosition(offset, lineOffsets) {
     }
     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
@@ -61,33 +60,27 @@ function offsetToPosition(offset, lineOffsets) {
 export function buildPositionIndex(doc, lineOffsets) {
     const index = new Map();
     function recordNode(node, path) {
-        if (!node || !node.range)
-            return;
-        const [start, , end] = node.range;
+        const [start, end] = node.range;
         index.set(path, {
             start: offsetToPosition(start, lineOffsets),
             end: offsetToPosition(end, lineOffsets),
         });
     }
     function walk(node, path) {
-        if (isMap(node)) {
-            for (const pair of node.items) {
-                if (!isPair(pair))
-                    continue;
-                const key = isScalar(pair.key) ? String(pair.key.value) : null;
+        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.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}]`;
@@ -96,8 +89,8 @@ export function buildPositionIndex(doc, lineOffsets) {
             }
         }
     }
-    if (doc.contents) {
-        walk(doc.contents, "");
+    if (doc.root) {
+        walk(doc.root, "");
     }
     return index;
 }

package/dist/sources/local-path-ref.d.ts

@@ -0,0 +1,4 @@
+/** True when `source` names an on-disk sibling manifest — a relative (`./`,
+ *  `../`) or absolute (`/`) path — rather than a transport-owned remote ref. */
+export declare function isLocalPathSource(source: string): boolean;
+//# sourceMappingURL=local-path-ref.d.ts.map

package/dist/sources/local-path-ref.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-path-ref.d.ts","sourceRoot":"","sources":["../../src/sources/local-path-ref.ts"],"names":[],"mappings":"AAAA;gFACgF;AAChF,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAEzD"}

package/dist/sources/local-path-ref.js

@@ -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) {
+    return source.startsWith(".") || source.startsWith("/");
+}

package/dist/yaml-ast.d.ts

@@ -0,0 +1,46 @@
+import { type Document } from "yaml";
+import { 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 declare function parseToAst(text: string): AstDocument[];
+/** 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 declare function documentToAst(doc: Document, text: string): AstDocument;
+//# sourceMappingURL=yaml-ast.d.ts.map

package/dist/yaml-ast.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"yaml-ast.d.ts","sourceRoot":"","sources":["../src/yaml-ast.ts"],"names":[],"mappings":"AACA,OAAO,EAA6C,KAAK,QAAQ,EAAa,MAAM,MAAM,CAAC;AAC3F,OAAO,EAAoB,KAAK,UAAU,EAAE,MAAM,cAAc,CAAC;AAEjE;;;;4EAI4E;AAC5E,MAAM,MAAM,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;AAElD,MAAM,WAAW,MAAM;IACrB,IAAI,EAAE,KAAK,CAAC;IACZ,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxB,OAAO,EAAE,OAAO,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,MAAM;IACrB,IAAI,EAAE,KAAK,CAAC;IACZ,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxB,KAAK,EAAE,OAAO,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,QAAQ,CAAC;IACf,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxB,8EAA8E;IAC9E,KAAK,EAAE,OAAO,CAAC;IACf,yDAAyD;IACzD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,yEAAyE;IACzE,WAAW,IAAI,UAAU,EAAE,CAAC;CAC7B;AAED,MAAM,WAAW,OAAO;IACtB,GAAG,EAAE,OAAO,CAAC;IACb,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,CAAC,EAAE,OAAO,CAAC;IACf;kCAC8B;IAC9B,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACzB;AAED;;iFAEiF;AACjF,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,EAAE,CAGtD;AAED;+EAC+E;AAC/E,wBAAgB,aAAa,CAAC,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,GAAG,WAAW,CAMtE"}

package/dist/yaml-ast.js

@@ -0,0 +1,58 @@
+import { defaultCustomTags, isTaggedSentinel } from "@telorun/templating";
+import { isMap, isScalar, isSeq, parseAllDocuments } from "yaml";
+import { buildCelSegments } from "./cel-ast.js";
+/** 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) {
+    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, text) {
+    const r = doc.range;
+    return {
+        root: doc.contents ? adaptNode(doc.contents, text) : undefined,
+        range: r ? [r[0], r[2]] : [0, text.length],
+    };
+}
+function nodeRange(node) {
+    const r = node.range;
+    return r ? [r[0], r[1]] : [0, 0];
+}
+function adaptNode(node, text) {
+    if (isMap(node)) {
+        const entries = [];
+        for (const item of node.items) {
+            const key = adaptNode(item.key, text);
+            if (!key)
+                continue;
+            const value = item.value != null ? adaptNode(item.value, text) : undefined;
+            entries.push({ key, value });
+        }
+        return { kind: "map", range: nodeRange(node), entries };
+    }
+    if (isSeq(node)) {
+        const items = [];
+        for (const item of node.items) {
+            const adapted = adaptNode(item, 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;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/analyzer",
-  "version": "0.39.0",
+  "version": "0.41.0",
   "description": "Telo Analyzer - Static manifest validator for Telo manifests.",
   "keywords": [
     "telo",

package/src/cel-ast.ts

@@ -0,0 +1,259 @@
+import { parse, type ASTNode as CelJsNode } from "@marcbachmann/cel-js";
+
+/** Read-only CEL expression tree owned by the analyzer. The third-party
+ *  `@marcbachmann/cel-js` `ASTNode` stays an internal detail — `wrapCelAst`
+ *  translates it into this union so no external AST type leaks through the
+ *  public surface (full symmetry with the YAML `AstNode` decision). Every
+ *  `range` is `[start, end]` in DOCUMENT offsets. */
+export type CelNode =
+  | { kind: "literal"; range: [number, number]; value: unknown }
+  | { kind: "ident"; range: [number, number]; name: string }
+  | {
+      kind: "member";
+      range: [number, number];
+      target: CelNode;
+      property: string;
+      /** Span of just the `.prop` identifier, for a future rename. */
+      propertyRange: [number, number];
+      /** `.?` optional member access. */
+      optional: boolean;
+    }
+  | {
+      kind: "index";
+      range: [number, number];
+      target: CelNode;
+      index: CelNode;
+      /** `[?]` optional index. */
+      optional: boolean;
+    }
+  | { kind: "call"; range: [number, number]; name: string; args: CelNode[] }
+  | {
+      kind: "methodCall";
+      range: [number, number];
+      name: string;
+      receiver: CelNode;
+      args: CelNode[];
+    }
+  | { kind: "list"; range: [number, number]; items: CelNode[] }
+  | { kind: "map"; range: [number, number]; entries: { key: CelNode; value: CelNode }[] }
+  | {
+      kind: "ternary";
+      range: [number, number];
+      cond: CelNode;
+      then: CelNode;
+      else: CelNode;
+    }
+  | { kind: "unary"; range: [number, number]; op: string; operand: CelNode }
+  | { kind: "binary"; range: [number, number]; op: string; left: CelNode; right: CelNode };
+
+/** A `${{ }}` / `!cel` region inside a YAML scalar. Ranges are DOCUMENT
+ *  offsets; `source` is the CEL body (a longest-valid prefix when `open`).
+ *  `ast()` parses lazily — nothing parses CEL during `parseToAst`, only the
+ *  expression a caller actually inspects. */
+export interface CelSegment {
+  /** Segment span in document offsets (includes the `${{ }}` for interpolation). */
+  range: [number, number];
+  /** The CEL body (a prefix when `open`). */
+  source: string;
+  /** True when a `${{` has no matching `}}` yet (the user is mid-typing). */
+  open: boolean;
+  /** Lazily parse + wrap; ranges are already absolute. */
+  ast(): CelNode;
+}
+
+const BINARY_OPS = new Set([
+  "!=",
+  "==",
+  "in",
+  "+",
+  "-",
+  "*",
+  "/",
+  "%",
+  "<",
+  "<=",
+  ">",
+  ">=",
+  "||",
+  "&&",
+]);
+
+/** Maps a `@marcbachmann/cel-js` node into the analyzer `CelNode`, translating
+ *  each node's segment-relative `start`/`end` to absolute document offsets by
+ *  adding `segmentStart`. */
+export function wrapCelAst(node: CelJsNode, segmentStart: number): CelNode {
+  const range = abs(node, segmentStart);
+  const op = node.op;
+  const args = node.args as unknown;
+
+  if (op === "value") return { kind: "literal", range, value: args };
+  if (op === "id") return { kind: "ident", range, name: String(args) };
+  if (op === "." || op === ".?") {
+    const [target, property] = args as [CelJsNode, string];
+    return {
+      kind: "member",
+      range,
+      target: wrapCelAst(target, segmentStart),
+      property,
+      propertyRange: [range[1] - property.length, range[1]],
+      optional: op === ".?",
+    };
+  }
+  if (op === "[]" || op === "[?]") {
+    const [target, index] = args as [CelJsNode, CelJsNode];
+    return {
+      kind: "index",
+      range,
+      target: wrapCelAst(target, segmentStart),
+      index: wrapCelAst(index, segmentStart),
+      optional: op === "[?]",
+    };
+  }
+  if (op === "call") {
+    const [name, callArgs] = args as [string, CelJsNode[]];
+    return { kind: "call", range, name, args: callArgs.map((a) => wrapCelAst(a, segmentStart)) };
+  }
+  if (op === "rcall") {
+    const [name, receiver, callArgs] = args as [string, CelJsNode, CelJsNode[]];
+    return {
+      kind: "methodCall",
+      range,
+      name,
+      receiver: wrapCelAst(receiver, segmentStart),
+      args: callArgs.map((a) => wrapCelAst(a, segmentStart)),
+    };
+  }
+  if (op === "list") {
+    return { kind: "list", range, items: (args as CelJsNode[]).map((a) => wrapCelAst(a, segmentStart)) };
+  }
+  if (op === "map") {
+    return {
+      kind: "map",
+      range,
+      entries: (args as [CelJsNode, CelJsNode][]).map(([k, v]) => ({
+        key: wrapCelAst(k, segmentStart),
+        value: wrapCelAst(v, segmentStart),
+      })),
+    };
+  }
+  if (op === "?:") {
+    const [cond, then, els] = args as [CelJsNode, CelJsNode, CelJsNode];
+    return {
+      kind: "ternary",
+      range,
+      cond: wrapCelAst(cond, segmentStart),
+      then: wrapCelAst(then, segmentStart),
+      else: wrapCelAst(els, segmentStart),
+    };
+  }
+  if (op === "!_" || op === "-_") {
+    return { kind: "unary", range, op, operand: wrapCelAst(args as CelJsNode, segmentStart) };
+  }
+  if (BINARY_OPS.has(op)) {
+    const [left, right] = args as [CelJsNode, CelJsNode];
+    return {
+      kind: "binary",
+      range,
+      op,
+      left: wrapCelAst(left, segmentStart),
+      right: wrapCelAst(right, segmentStart),
+    };
+  }
+  // Unknown operator — surface it as a literal so consumers can still hit-test
+  // the range rather than crash on an unmapped node.
+  return { kind: "literal", range, value: undefined };
+}
+
+function abs(node: CelJsNode, segmentStart: number): [number, number] {
+  const r = node.range ?? { start: node.start, end: node.end };
+  return [r.start + segmentStart, r.end + segmentStart];
+}
+
+/** Parse `source` and wrap it, tolerating a trailing partial member/index
+ *  access (`req.`, `req.fo`) by falling back to the longest parseable prefix.
+ *  Used for `open` segments where completion fires mid-token. */
+function parseLenient(source: string, segmentStart: number, range: [number, number]): CelNode {
+  const candidates = [source, source.replace(/[.?[]+\w*$/, ""), source.replace(/[.?[(]+.*$/, "")];
+  for (const candidate of candidates) {
+    const trimmed = candidate.trim();
+    if (!trimmed) break;
+    try {
+      return wrapCelAst(parse(trimmed).ast, segmentStart);
+    } catch {
+      // try the next-shorter prefix
+    }
+  }
+  return { kind: "ident", range, name: source.trim() };
+}
+
+const OPEN_MARKER = "${{";
+
+/** Build the CEL segments of a scalar from its raw source slice. `scalarText`
+ *  is `text.slice(start, valueEnd)` and `scalarStart` its document offset.
+ *
+ *  - `tag === "!cel"` → one closed segment spanning the tagged body.
+ *  - otherwise → one closed segment per `${{ … }}` match, plus a trailing
+ *    `open` segment for a dangling `${{` with no `}}` (bounded to its line, so
+ *    an unterminated quote that swallowed following lines still recovers the
+ *    region the user is typing in). */
+export function buildCelSegments(
+  scalarText: string,
+  scalarStart: number,
+  tag: string | undefined,
+  taggedSource: string | undefined,
+): CelSegment[] {
+  if (tag === "!cel" && taggedSource != null) {
+    const idx = scalarText.indexOf(taggedSource);
+    const bodyStart = scalarStart + (idx >= 0 ? idx : 0);
+    const range: [number, number] = [bodyStart, bodyStart + taggedSource.length];
+    return [
+      {
+        range,
+        source: taggedSource,
+        open: false,
+        ast: () => wrapCelAst(parse(taggedSource).ast, bodyStart),
+      },
+    ];
+  }
+
+  const segments: CelSegment[] = [];
+  const re = /\$\{\{([\s\S]*?)\}\}/g;
+  let match: RegExpExecArray | null;
+  let lastClosedEnd = 0;
+  while ((match = re.exec(scalarText)) !== null) {
+    const whole = match[0];
+    const inner = match[1];
+    const leadingWs = inner.match(/^\s*/)?.[0].length ?? 0;
+    const bodyStart = scalarStart + match.index + OPEN_MARKER.length + leadingWs;
+    const source = inner.trim();
+    segments.push({
+      range: [scalarStart + match.index, scalarStart + match.index + whole.length],
+      source,
+      open: false,
+      ast: () => wrapCelAst(parse(source).ast, bodyStart),
+    });
+    lastClosedEnd = match.index + whole.length;
+  }
+
+  const openIdx = scalarText.indexOf(OPEN_MARKER, lastClosedEnd);
+  if (openIdx >= 0 && scalarText.indexOf("}}", openIdx) < 0) {
+    let lineEnd = scalarText.indexOf("\n", openIdx);
+    if (lineEnd < 0) lineEnd = scalarText.length;
+    const after = openIdx + OPEN_MARKER.length;
+    // Drop a trailing scalar-closing quote so `foo: "${{ req"` recovers `req`,
+    // not `req"` — the quote closes the YAML string, it isn't part of the CEL.
+    const rawBody = scalarText.slice(after, lineEnd).replace(/["']\s*$/, "");
+    const leadingWs = rawBody.match(/^\s*/)?.[0].length ?? 0;
+    const bodyStart = scalarStart + after + leadingWs;
+    const source = rawBody.trim();
+    const range: [number, number] = [scalarStart + openIdx, scalarStart + lineEnd];
+    segments.push({
+      range,
+      source,
+      open: true,
+      ast: () => parseLenient(source, bodyStart, range),
+    });
+  }
+
+  return segments;
+}

package/src/import-resolution-diagnostics.ts

@@ -0,0 +1,66 @@
+import type { GraphLoadError, LoadedGraph } from "./loaded-types.js";
+import { isLocalPathSource } from "./sources/local-path-ref.js";
+import { isRegistryRef } from "./sources/module-ref.js";
+import { isOciRef } from "./sources/oci-ref.js";
+import { DiagnosticSeverity, type AnalysisDiagnostic } from "./types.js";
+
+const SOURCE = "telo-analyzer";
+
+/** True when `source` is a shape some transport claims — a registry ref, an OCI
+ *  ref, an HTTP(S) URL, or a relative/absolute path. A source matching none of
+ *  these is malformed (no transport can ever resolve it), which we report
+ *  differently from a well-formed ref that simply failed to fetch. */
+function isRecognizedSourceShape(source: string): boolean {
+  return (
+    isRegistryRef(source) ||
+    isOciRef(source) ||
+    source.startsWith("http://") ||
+    source.startsWith("https://") ||
+    isLocalPathSource(source)
+  );
+}
+
+function messageFor(e: GraphLoadError, malformed: boolean): string {
+  const authored = e.source ?? e.url;
+  const via = e.alias ? `import '${e.alias}' → '${authored}'` : `'${authored}'`;
+  if (malformed) {
+    return (
+      `Cannot resolve ${via}: not a recognized module reference. Expected ` +
+      `'namespace/name@version', 'oci://host/repo@tag', 'https://…', or a relative path.`
+    );
+  }
+  return `Cannot resolve ${via}: ${e.error.message}`;
+}
+
+/**
+ * Convert a graph's import-resolution failures (`graph.errors`) into structured,
+ * coded diagnostics. This is the single source of truth for surfacing a broken
+ * import — every host (CLI, VS Code, telo-editor) routes these instead of each
+ * re-deriving the channel and drifting (the VS Code extension used to drop it
+ * entirely, showing nothing for a broken import).
+ *
+ * The analyzer owns only this raw channel conversion; the *presentation* policy
+ * — which analysis cascade to hold back for a compromised file — lives in
+ * `@telorun/ide-support`'s `assembleGraphDiagnostics`.
+ *
+ * Each diagnostic adopts the same `data` shape as version-reconciliation
+ * diagnostics — `{ filePath, path: "imports.<alias>" }` — so the shared
+ * `findPositions` / `resolveRange` routing anchors it on the offending import
+ * line with no host-specific code.
+ */
+export function importResolutionDiagnostics(graph: LoadedGraph): AnalysisDiagnostic[] {
+  return graph.errors.map((e) => {
+    const filePath = e.fromSource ?? graph.entry.owner.source;
+    const malformed = !isRecognizedSourceShape(e.source ?? e.url);
+    const data: { filePath: string; path?: string; sourceLine?: number } = { filePath };
+    if (e.alias) data.path = `imports.${e.alias}`;
+    if (e.sourceLine !== undefined) data.sourceLine = e.sourceLine;
+    return {
+      severity: DiagnosticSeverity.Error,
+      code: malformed ? "INVALID_IMPORT_SOURCE" : "IMPORT_UNRESOLVED",
+      source: SOURCE,
+      message: messageFor(e, malformed),
+      data,
+    };
+  });
+}

package/src/index.ts

@@ -1,6 +1,7 @@
 export { AnalysisRegistry } from "./analysis-registry.js";
 export type { RefFieldInfo } from "./analysis-registry.js";
 export { StaticAnalyzer } from "./analyzer.js";
+export { importResolutionDiagnostics } from "./import-resolution-diagnostics.js";
 export type {
     GraphLoadError,
     ImportEdge,
@@ -67,6 +68,7 @@ export {
     buildLineOffsets,
     buildPositionIndex,
     documentLineOffsets,
+    offsetToPosition,
 } from "./position-metadata.js";
 export type { DocumentPosition } from "./position-metadata.js";
 export { HttpSource } from "./sources/http-source.js";
@@ -84,6 +86,7 @@ export { parseModuleRef, isRegistryRef } from "./sources/module-ref.js";
 export type { ParsedModuleRef } from "./sources/module-ref.js";
 export { OCI_SCHEME, isOciRef, parseOciRef } from "./sources/oci-ref.js";
 export type { ParsedOciRef } from "./sources/oci-ref.js";
+export { isLocalPathSource } from "./sources/local-path-ref.js";
 export {
   MANIFEST_CACHE_BASE_URL,
   ManifestCacheSource,
@@ -95,6 +98,10 @@ export {
 } from "./sources/manifest-cache.js";
 export type { ManifestCacheCoords } from "./sources/manifest-cache.js";
 export { withSyntheticPositions } from "./with-synthetic-positions.js";
+export { documentToAst, parseToAst } from "./yaml-ast.js";
+export type { AstDocument, AstMap, AstNode, AstPair, AstScalar, AstSeq } from "./yaml-ast.js";
+export { buildCelSegments, wrapCelAst } from "./cel-ast.js";
+export type { CelNode, CelSegment } from "./cel-ast.js";
 export { DEFAULT_MANIFEST_FILENAME, DiagnosticSeverity } from "./types.js";
 export type {
     AnalysisDiagnostic,

package/src/loaded-types.ts

@@ -2,6 +2,7 @@ import type { ResourceManifest } from "@telorun/sdk";
 import type { Document } from "yaml";
 import type { DocumentPosition } from "./position-metadata.js";
 import type { AnalysisDiagnostic, Range } from "./types.js";
+import type { AstDocument } from "./yaml-ast.js";
 
 /** One physical file's parsed result. Returned for the owner manifest, for
  *  each `include:` partial, and for each external import target.
@@ -17,8 +18,13 @@ export interface LoadedFile {
   requestedUrl: string;
   /** Raw text exactly as `read()` returned it. */
   text: string;
-  /** Per-document parsed AST, in source order. */
+  /** Per-document parsed `yaml` AST, in source order. The editor's mutable
+   *  round-trip model reads this handle; structure-only consumers use the
+   *  read-only `astDocuments` instead so `yaml` stays an internal detail. */
   documents: Document[];
+  /** Per-document read-only `AstNode` view (`yaml`-free), aligned to
+   *  `documents`. The shared structural source of truth for IDE features. */
+  astDocuments: AstDocument[];
   /** Per-document JSON projection (`doc.toJSON()`). Aligned to `documents`. */
   manifests: Array<ResourceManifest | null>;
   /** Per-document `{sourceLine, positionIndex}`. Aligned to `documents`. */
@@ -96,9 +102,20 @@ export interface LoadedGraph {
 }
 
 export interface GraphLoadError {
-  /** URL of the file that failed to load. */
+  /** URL of the file that failed to load (resolved — may be a `file://` URL for
+   *  a relative import). */
   url: string;
+  /** The import source string exactly as authored (`./lib`, `std/x@1.0.0`),
+   *  before relative-path resolution. Preferred over `url` for classification
+   *  and display, so a diagnostic quotes what the author wrote. */
+  source?: string;
   /** Source of the import that triggered the load, or null for the entry. */
   fromSource: string | null;
+  /** Import alias the failed source was bound to in `fromSource`'s `imports:`
+   *  map, when the failure is a transitive import (absent for an entry-load
+   *  failure). Lets a consumer anchor the diagnostic at `imports.<alias>`. */
+  alias?: string;
+  /** Line of the `Telo.Import` doc in `fromSource`, for position fallback. */
+  sourceLine?: number;
   error: Error;
 }

package/src/manifest-loader.ts

@@ -258,7 +258,10 @@ export class Loader {
           } catch (err) {
             errors.push({
               url: importSource,
+              source: importSource,
               fromSource: file.source,
+              alias,
+              sourceLine,
               error: err instanceof Error ? err : new Error(String(err)),
             });
             continue;
@@ -284,7 +287,14 @@ export class Loader {
             } catch (err) {
               const e = err instanceof Error ? err : new Error(String(err));
               (e as { sourceLine?: number }).sourceLine = sourceLine;
-              errors.push({ url: resolvedTarget, fromSource: file.source, error: e });
+              errors.push({
+                url: resolvedTarget,
+                source: importSource,
+                fromSource: file.source,
+                alias,
+                sourceLine,
+                error: e,
+              });
               continue;
             }
           }

package/src/parse-loaded-file.ts

@@ -6,6 +6,7 @@ import { buildCelEnvironment } from "./cel-environment.js";
 import type { LoadedFile, ParseError } from "./loaded-types.js";
 import { buildDocumentPositions } from "./position-metadata.js";
 import { precompileDoc } from "./precompile.js";
+import { documentToAst } from "./yaml-ast.js";
 
 export interface ParseOptions {
   /** When true, runs `precompileDoc` per document and stamps compiled CEL
@@ -49,7 +50,8 @@ export function parseLoadedFile(
   options?: ParseOptions,
 ): LoadedFile {
   const documents = parseAllDocuments(text, { customTags: defaultCustomTags() });
-  const positions = buildDocumentPositions(text, documents);
+  const astDocuments = documents.map((doc) => documentToAst(doc, text));
+  const positions = buildDocumentPositions(text, astDocuments);
 
   const parseErrors: ParseError[] = [];
   documents.forEach((doc, documentIndex) => {
@@ -90,6 +92,7 @@ export function parseLoadedFile(
     requestedUrl,
     text,
     documents,
+    astDocuments,
     manifests,
     positions,
     parseErrors,