@telorun/analyzer 0.8.1 → 0.10.0

package/src/normalize-inline-resources.ts

@@ -36,6 +36,7 @@ export function normalizeInlineResources(
   resources: ResourceManifest[],
   registry: DefinitionRegistry,
   aliases?: AliasResolver,
+  aliasesByModule?: Map<string, AliasResolver>,
 ): ResourceManifest[] {
   const result = [...resources];
 
@@ -48,7 +49,13 @@ export function normalizeInlineResources(
   let i = 0;
   while (i < queue.length) {
     const resource = queue[i++];
-    const fieldMap = registry.getFieldMapForKind(resource.kind, aliases);
+    // When aliasesByModule is available, use the expanded map so inline refs
+    // hidden behind an x-telo-schema-from indirection (e.g. an encoder inside
+    // an HttpDispatch.Outcomes/$defs/Returns sub-schema) reach extraction.
+    const fieldMap =
+      aliases && aliasesByModule
+        ? registry.expandedFieldMapForResource(resource, aliases, aliasesByModule)
+        : registry.getFieldMapForKind(resource.kind, aliases);
     if (!fieldMap) continue;
 
     const parentName = resource.metadata.name as string;

package/src/parse-loaded-file.ts

@@ -0,0 +1,70 @@
+import type { Environment } from "@marcbachmann/cel-js";
+import type { ResourceManifest } from "@telorun/sdk";
+import { defaultCustomTags } from "@telorun/templating";
+import { parseAllDocuments } from "yaml";
+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";
+
+export interface ParseOptions {
+  /** When true, runs `precompileDoc` per document and stamps compiled CEL
+   *  on the manifests — same flag `LoadOptions.compile` carries today. */
+  compile?: boolean;
+  /** CEL environment for precompile. Defaults to `buildCelEnvironment()`. */
+  celEnv?: Environment;
+}
+
+/** Pure: text in, structured load result out. No I/O, no caches. */
+export function parseLoadedFile(
+  source: string,
+  requestedUrl: string,
+  text: string,
+  options?: ParseOptions,
+): LoadedFile {
+  const documents = parseAllDocuments(text, { customTags: defaultCustomTags() });
+  const positions = buildDocumentPositions(text, documents);
+
+  const parseErrors: ParseError[] = [];
+  documents.forEach((doc, documentIndex) => {
+    for (const err of doc.errors) {
+      parseErrors.push({
+        documentIndex,
+        message: err.message,
+      });
+    }
+  });
+
+  const manifests: Array<ResourceManifest | null> = [];
+  let env: Environment | undefined;
+  for (const doc of documents) {
+    const raw = doc.toJSON();
+    if (raw === null || raw === undefined) {
+      manifests.push(null);
+      continue;
+    }
+    if (options?.compile) {
+      env ??= options.celEnv ?? buildCelEnvironment();
+      try {
+        const compiled = precompileDoc(raw, env);
+        manifests.push(compiled as ResourceManifest);
+      } catch (error) {
+        throw new Error(
+          `Failed to compile manifest in ${source}: ${error instanceof Error ? error.message : String(error)}`,
+        );
+      }
+    } else {
+      manifests.push(raw as ResourceManifest);
+    }
+  }
+
+  return {
+    source,
+    requestedUrl,
+    text,
+    documents,
+    manifests,
+    positions,
+    parseErrors,
+  };
+}

package/src/position-metadata.ts

@@ -0,0 +1,106 @@
+import { isMap, isPair, isScalar, isSeq, type Document } from "yaml";
+import type { Position, PositionIndex } from "./types.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
+ *  resolved against `positionIndex` / `sourceLine` line up identically
+ *  across hosts. */
+
+/** Per-document position metadata used by `normalizeDiagnostic`'s fallback chain. */
+export interface DocumentPosition {
+  sourceLine: number;
+  positionIndex: PositionIndex;
+}
+
+/** Builds DocumentPosition entries aligned to `parsedDocs[i]`. */
+export function buildDocumentPositions(
+  text: string,
+  parsedDocs: Document[],
+): DocumentPosition[] {
+  const docOffsets = documentLineOffsets(text);
+  const lineOffsets = buildLineOffsets(text);
+  return parsedDocs.map((doc, i) => ({
+    sourceLine: docOffsets[i] ?? 0,
+    positionIndex: buildPositionIndex(doc, lineOffsets),
+  }));
+}
+
+/** Line numbers (0-indexed) where each YAML document in a multi-doc file
+ *  starts. The first document is always at line 0; subsequent entries point
+ *  to the line after each `---` directive. */
+export function documentLineOffsets(text: string): number[] {
+  const offsets = [0];
+  const lines = text.split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    const t = lines[i].trimEnd();
+    if (t === "---" || t.startsWith("--- ")) offsets.push(i + 1);
+  }
+  return offsets;
+}
+
+/** Byte-offset → start-of-line lookup table. Index `i` is the byte offset of
+ *  the first character on line `i`. Used with `offsetToPosition` to turn a
+ *  yaml-AST node range into Range coordinates. */
+export function buildLineOffsets(text: string): number[] {
+  const offsets: number[] = [0];
+  for (let i = 0; i < text.length; i++) {
+    if (text[i] === "\n") offsets.push(i + 1);
+  }
+  return offsets;
+}
+
+function offsetToPosition(offset: number, lineOffsets: number[]): Position {
+  let lo = 0;
+  let hi = lineOffsets.length - 1;
+  while (lo < hi) {
+    const mid = (lo + hi + 1) >> 1;
+    if (lineOffsets[mid] <= offset) lo = mid;
+    else hi = mid - 1;
+  }
+  return { line: lo, character: offset - lineOffsets[lo] };
+}
+
+/** Walks the YAML AST and records source ranges for every field value, keyed
+ *  by dotted path (e.g. "kind", "config.handler", "config.routes[0].path"). */
+export function buildPositionIndex(doc: Document, 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];
+    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;
+        if (key == null) continue;
+        const childPath = path ? `${path}.${key}` : key;
+        if (pair.value != null) {
+          recordNode(pair.value, childPath);
+          walk(pair.value, childPath);
+        }
+      }
+    } else if (isSeq(node)) {
+      for (let i = 0; i < node.items.length; i++) {
+        const item = node.items[i];
+        const childPath = `${path}[${i}]`;
+        recordNode(item, childPath);
+        walk(item, childPath);
+      }
+    }
+  }
+
+  if (doc.contents) {
+    walk(doc.contents, "");
+  }
+
+  return index;
+}

package/src/reference-field-map.ts

@@ -135,6 +135,19 @@ function collectRefs(node: Record<string, any>): string[] {
   return refs;
 }
 
+/** Traverses an arbitrary JSON Schema starting at the given path prefix. Used to
+ *  expand x-telo-schema-from sub-schemas into nested ref/scope entries so Phase 2
+ *  inline normalization and Phase 5 injection see slots that the local field map
+ *  hid behind the schema-from indirection. */
+export function buildFieldMapAtPath(
+  schema: Record<string, any>,
+  pathPrefix: string,
+): ReferenceFieldMap {
+  const map: ReferenceFieldMap = new Map();
+  traverseNode(schema, pathPrefix, map);
+  return map;
+}
+
 function traverseNode(node: Record<string, any>, path: string, map: ReferenceFieldMap): void {
   // Scope slot — record and stop; do not recurse into scope contents
   if ("x-telo-scope" in node) {

package/src/types.ts

@@ -92,4 +92,10 @@ export interface AnalysisOptions {
 export interface AnalysisContext {
   aliases?: import("./alias-resolver.js").AliasResolver;
   definitions?: import("./definition-registry.js").DefinitionRegistry;
+  /** Per-library alias resolvers keyed by the library's module name. Populated by
+   *  the analyzer when imports are forwarded from inside imported libraries.
+   *  Validators that resolve schema-side annotations (e.g. x-telo-schema-from
+   *  pointing at an imported kind) consult the kind owner's scope here, since
+   *  the consumer's aliases will not contain a library's private imports. */
+  aliasesByModule?: Map<string, import("./alias-resolver.js").AliasResolver>;
 }

package/src/validate-references.ts

@@ -73,6 +73,7 @@ export function validateReferences(
   const diagnostics: AnalysisDiagnostic[] = [];
   const aliases = context.aliases;
   const registry = context.definitions;
+  const aliasesByModule = context.aliasesByModule;
   if (!aliases || !registry) return diagnostics;
 
   // Build outer resource lookup by name for resolution check.
@@ -86,7 +87,12 @@ export function validateReferences(
   for (const r of resources) {
     if (!r.metadata?.name || !r.kind || SYSTEM_KINDS.has(r.kind)) continue;
 
-    const fieldMap = registry.getFieldMapForKind(r.kind, aliases);
+    // Use the expanded map so refs nested behind x-telo-schema-from get the
+    // same kind-check / unresolved-name validation as locally-declared refs.
+    // Falls back to the base map when aliasesByModule isn't supplied.
+    const fieldMap = aliasesByModule
+      ? registry.expandedFieldMapForResource(r, aliases, aliasesByModule)
+      : registry.getFieldMapForKind(r.kind, aliases);
     if (!fieldMap) continue;
 
     const resourceLabel = `${r.kind}/${r.metadata.name as string}`;
@@ -260,6 +266,73 @@ export function validateReferences(
       const anchorName = expr.slice(0, slashIdx);
       const jsonPointer = "/" + expr.slice(slashIdx + 1);
 
+      // Aliased absolute kind path — first segment carries a dot, e.g.
+      // "HttpDispatch.Outcomes/$defs/Returns". Resolves the alias through the
+      // *kind owner's* scope (not the consumer's), navigates the JSON Pointer
+      // into the resolved definition's schema, and validates each field value.
+      //
+      // Relative anchors are property names that cannot contain a dot
+      // (CEL-style identifiers), so a dot in anchorName is unambiguous.
+      if (!isAbsolute && anchorName.includes(".")) {
+        const resolvedResourceKind = aliases.resolveKind(r.kind) ?? r.kind;
+        const resourceDef =
+          registry.resolve(r.kind) ?? registry.resolve(resolvedResourceKind);
+        const owningModule = (resourceDef?.metadata as { module?: string } | undefined)?.module;
+        const ownerScope =
+          (owningModule ? aliasesByModule?.get(owningModule) : undefined) ?? aliases;
+
+        const targetKind = ownerScope.resolveKind(anchorName);
+        if (!targetKind) {
+          diagnostics.push({
+            severity: DiagnosticSeverity.Error,
+            code: "SCHEMA_FROM_MISSING_PATH",
+            source: SOURCE,
+            message: `${resourceLabel}: x-telo-schema-from at '${fieldPath}' → cannot resolve alias '${anchorName}'`,
+            data: { resource: resourceData, filePath, path: fieldPath },
+          });
+          continue;
+        }
+
+        const targetDef = registry.resolve(targetKind);
+        if (!targetDef?.schema) {
+          diagnostics.push({
+            severity: DiagnosticSeverity.Error,
+            code: "SCHEMA_FROM_MISSING_PATH",
+            source: SOURCE,
+            message: `${resourceLabel}: x-telo-schema-from at '${fieldPath}' → kind '${targetKind}' has no schema`,
+            data: { resource: resourceData, filePath, path: fieldPath },
+          });
+          continue;
+        }
+
+        const subSchema = navigateJsonPointer(targetDef.schema, jsonPointer);
+        if (subSchema === undefined) {
+          diagnostics.push({
+            severity: DiagnosticSeverity.Error,
+            code: "SCHEMA_FROM_MISSING_PATH",
+            source: SOURCE,
+            message: `${resourceLabel}: x-telo-schema-from at '${fieldPath}' → kind '${targetKind}' has no schema path '${jsonPointer}'`,
+            data: { resource: resourceData, filePath, path: fieldPath },
+          });
+          continue;
+        }
+
+        for (const fieldValue of resolveFieldValues(r, fieldPath)) {
+          if (fieldValue == null) continue;
+          const issues = registry.validateWithRefs(fieldValue, subSchema as Record<string, any>);
+          for (const issue of issues) {
+            diagnostics.push({
+              severity: DiagnosticSeverity.Error,
+              code: "DEPENDENT_SCHEMA_MISMATCH",
+              source: SOURCE,
+              message: `${resourceLabel}: '${fieldPath}' does not match schema from '${anchorName}${jsonPointer}': ${issue}`,
+              data: { resource: resourceData, filePath, path: fieldPath },
+            });
+          }
+        }
+        continue;
+      }
+
       // Derive the anchor path in the resource config.
       let anchorPath: string;
       if (isAbsolute) {