@telorun/analyzer 1.1.0 → 1.3.0

package/src/reference-field-map.ts

@@ -142,7 +142,7 @@ export function buildReferenceFieldMap(schema: Record<string, any>): ReferenceFi
   const map: ReferenceFieldMap = new Map();
   if (schema.properties) {
     for (const [key, propSchema] of Object.entries(schema.properties)) {
-      traverseNode(propSchema as Record<string, any>, key, map);
+      traverseNode(propSchema as Record<string, any>, key, map, schema);
     }
   }
   return map;
@@ -172,11 +172,29 @@ export function buildFieldMapAtPath(
   pathPrefix: string,
 ): ReferenceFieldMap {
   const map: ReferenceFieldMap = new Map();
-  traverseNode(schema, pathPrefix, map);
+  traverseNode(schema, pathPrefix, map, schema);
   return map;
 }
 
-function traverseNode(node: Record<string, any>, path: string, map: ReferenceFieldMap): void {
+function traverseNode(
+  node: Record<string, any>,
+  path: string,
+  map: ReferenceFieldMap,
+  root?: Record<string, any>,
+  visitedRefs: Set<string> = new Set(),
+): void {
+  // Local `$ref` is intentionally NOT followed. Descending into shared
+  // `$defs` (notably `Run.Sequence`'s `step` definition) would surface
+  // ref slots like `steps[].invoke` that Phase 5 then injects live
+  // instances into; today's `Run.Sequence` controller calls
+  // `instance.invoke()` directly when handed an instance, bypassing
+  // the kernel's `runInvoke` emit-Invoked path. The walker fix and the
+  // dispatcher fix need to land together — see the follow-up in
+  // [kernel/nodejs/plans/reference-syntax-unification.md] and the
+  // stopgap in `resource-context.ts:resolveChildren`. `visitedRefs`
+  // stays as a parameter so the recursive calls below thread the right
+  // signature; turning the descent back on is a single-branch change.
+  if (typeof node?.$ref === "string") return;
   // Scope slot — record and stop; do not recurse into scope contents
   if ("x-telo-scope" in node) {
     map.set(path, { scope: node["x-telo-scope"] });
@@ -200,13 +218,32 @@ function traverseNode(node: Record<string, any>, path: string, map: ReferenceFie
 
   // Array — recurse into items
   if (node.type === "array" && node.items) {
-    traverseNode(node.items as Record<string, any>, path + "[]", map);
+    traverseNode(node.items as Record<string, any>, path + "[]", map, root, visitedRefs);
   }
 
   // Object — recurse into properties
   if (node.properties) {
     for (const [key, propSchema] of Object.entries(node.properties)) {
-      traverseNode(propSchema as Record<string, any>, `${path}.${key}`, map);
+      traverseNode(propSchema as Record<string, any>, `${path}.${key}`, map, root, visitedRefs);
+    }
+  }
+
+  // Variant branches — descend into every alternative's properties / items.
+  // Schemas that discriminate on shape (Run.Sequence's step kinds:
+  // `oneOf: [{properties: {invoke}}, {properties: {try}}, ...]`) hide ref
+  // slots inside the branch. Walking each branch surfaces those slots into
+  // the field map so downstream passes (ref validation, sentinel
+  // resolution, dependency graph) cover them without a runtime fallback.
+  // The same field path may be added by multiple branches; the later
+  // assignment wins, which is fine — branches with the same field path
+  // share the same ref/context configuration (any divergence is already
+  // a schema bug).
+  for (const variantKey of ["oneOf", "anyOf", "allOf"] as const) {
+    const variants = node[variantKey];
+    if (!Array.isArray(variants)) continue;
+    for (const variant of variants) {
+      if (!variant || typeof variant !== "object") continue;
+      traverseVariant(variant as Record<string, any>, path, map, root, visitedRefs);
     }
   }
 
@@ -218,6 +255,46 @@ function traverseNode(node: Record<string, any>, path: string, map: ReferenceFie
     typeof node.additionalProperties === "object" &&
     !Array.isArray(node.additionalProperties)
   ) {
-    traverseNode(node.additionalProperties as Record<string, any>, `${path}.{}`, map);
+    traverseNode(
+      node.additionalProperties as Record<string, any>,
+      `${path}.{}`,
+      map,
+      root,
+      visitedRefs,
+    );
+  }
+}
+
+/** Walk a single variant of a `oneOf` / `anyOf` / `allOf` branch. Only
+ *  the properties / items / map slots are followed — collectRefs at the
+ *  variant root is handled by the parent's `collectRefs(node)` already
+ *  (anyOf of x-telo-ref branches is the canonical multi-ref shape). */
+function traverseVariant(
+  variant: Record<string, any>,
+  path: string,
+  map: ReferenceFieldMap,
+  root?: Record<string, any>,
+  visitedRefs: Set<string> = new Set(),
+): void {
+  if (variant.properties) {
+    for (const [key, propSchema] of Object.entries(variant.properties)) {
+      traverseNode(propSchema as Record<string, any>, `${path}.${key}`, map, root, visitedRefs);
+    }
+  }
+  if (variant.type === "array" && variant.items) {
+    traverseNode(variant.items as Record<string, any>, path + "[]", map, root, visitedRefs);
+  }
+  if (
+    variant.additionalProperties &&
+    typeof variant.additionalProperties === "object" &&
+    !Array.isArray(variant.additionalProperties)
+  ) {
+    traverseNode(
+      variant.additionalProperties as Record<string, any>,
+      `${path}.{}`,
+      map,
+      root,
+      visitedRefs,
+    );
   }
 }

package/src/resolve-ref-sentinels.ts

@@ -0,0 +1,127 @@
+import type { ResourceManifest } from "@telorun/sdk";
+import { isRefSentinel } from "@telorun/templating";
+import type { AliasResolver } from "./alias-resolver.js";
+import type { DefinitionRegistry } from "./definition-registry.js";
+import { isRefEntry } from "./reference-field-map.js";
+import { REF_RESOLUTION_SKIP_KINDS as SYSTEM_KINDS } from "./system-kinds.js";
+
+/**
+ * Walks every `x-telo-ref` slot in every non-system resource and rewrites
+ * `!ref <name>` sentinels in-place to `{kind: <resolved-kind>, name}`.
+ *
+ * The downstream pipeline (inline normalization, dependency graph, kernel
+ * controllers) expects every ref-slot value to be either a `{kind, name}`
+ * object, an inline-definition object, or a legacy bare string — resolving
+ * sentinels here keeps that contract intact so each consumer doesn't need
+ * its own sentinel branch.
+ *
+ * The walker assigns `kind` by name lookup (resource names are unique
+ * within a manifest scope). When the name doesn't resolve in the local
+ * `byName` map, the sentinel is left in place so `validateReferences`
+ * can emit the `UNRESOLVED_REFERENCE` diagnostic with full context.
+ *
+ * Mutation strategy: the field-path walker descends the resource tree
+ * directly and replaces the sentinel on its parent container. Re-parsing
+ * a string-encoded concrete path (the earlier shape) coupled the writer
+ * to the path-encoding rules of `resolveFieldEntries` — any new path
+ * marker would silently break this writer. Descending directly avoids
+ * that coupling.
+ */
+export function resolveRefSentinels(
+  resources: ResourceManifest[],
+  registry: DefinitionRegistry,
+  aliases?: AliasResolver,
+  aliasesByModule?: Map<string, AliasResolver>,
+): void {
+  const byName = new Map<string, ResourceManifest>();
+  for (const r of resources) {
+    if (r.metadata?.name && !SYSTEM_KINDS.has(r.kind)) {
+      byName.set(r.metadata.name as string, r);
+    }
+  }
+
+  for (const r of resources) {
+    if (!r.metadata?.name || !r.kind || SYSTEM_KINDS.has(r.kind)) continue;
+
+    const fieldMap =
+      aliases && aliasesByModule
+        ? registry.expandedFieldMapForResource(r, aliases, aliasesByModule)
+        : registry.getFieldMapForKind(r.kind, aliases);
+    if (!fieldMap) continue;
+
+    for (const [fieldPath, entry] of fieldMap) {
+      if (!isRefEntry(entry)) continue;
+      replaceSentinelsAtPath(r as Record<string, unknown>, fieldPath, byName);
+    }
+  }
+}
+
+/** Walks `obj` along `fieldPath` (dot notation with `[]` for arrays and
+ *  `{}` for additionalProperties-typed maps) and replaces any `!ref`
+ *  sentinel value at the terminal slot with `{kind, name}` looked up
+ *  via `byName`. Mutates the parent container in place; no string-path
+ *  round-trip. */
+function replaceSentinelsAtPath(
+  obj: Record<string, unknown>,
+  fieldPath: string,
+  byName: Map<string, ResourceManifest>,
+): void {
+  const parts = fieldPath.split(".");
+  descend(obj, parts, byName);
+}
+
+function descend(
+  obj: unknown,
+  parts: string[],
+  byName: Map<string, ResourceManifest>,
+): void {
+  if (obj == null || typeof obj !== "object" || parts.length === 0) return;
+  const [head, ...rest] = parts;
+
+  // Map iteration: descend into every value of the current object.
+  if (head === "{}") {
+    const container = obj as Record<string, unknown>;
+    for (const key of Object.keys(container)) {
+      const child = container[key];
+      if (rest.length === 0) {
+        if (isRefSentinel(child)) {
+          const target = byName.get(child.source);
+          if (target) container[key] = { kind: target.kind as string, name: child.source };
+        }
+      } else {
+        descend(child, rest, byName);
+      }
+    }
+    return;
+  }
+
+  const isArr = head.endsWith("[]");
+  const key = isArr ? head.slice(0, -2) : head;
+  const container = obj as Record<string, unknown>;
+  const val = container[key];
+  if (val == null) return;
+
+  if (isArr) {
+    if (!Array.isArray(val)) return;
+    for (let i = 0; i < val.length; i++) {
+      if (rest.length === 0) {
+        const elem = val[i];
+        if (isRefSentinel(elem)) {
+          const target = byName.get(elem.source);
+          if (target) val[i] = { kind: target.kind as string, name: elem.source };
+        }
+      } else {
+        descend(val[i], rest, byName);
+      }
+    }
+  } else {
+    if (rest.length === 0) {
+      if (isRefSentinel(val)) {
+        const target = byName.get(val.source);
+        if (target) container[key] = { kind: target.kind as string, name: val.source };
+      }
+    } else {
+      descend(val, rest, byName);
+    }
+  }
+}

package/src/schema-compat.ts

@@ -1,16 +1,23 @@
 import AjvModule from "ajv";
 import addFormats from "ajv-formats";
-import { isTaggedSentinel } from "@telorun/templating";
+import { isRefSentinel, isTaggedSentinel, ManifestRootSchema } from "@telorun/templating";
 
 const Ajv = (AjvModule as any).default ?? AjvModule;
 
 /** Creates a configured AJV instance (allErrors, strict: false, with formats).
- *  Called once for the module-level instance and once per DefinitionRegistry instance. */
+ *  Also registers the kernel manifest root schema under `telo://manifest` so
+ *  module YAMLs can `$ref` into the shared `$defs/ResourceRef` (and any future
+ *  shared fragments) from this analyzer's AJV without each module having to
+ *  bundle its own copy.
+ *
+ *  Called once for the module-level instance and once per
+ *  DefinitionRegistry instance. */
 export function createAjv(): InstanceType<typeof Ajv> {
   const instance = new Ajv({ allErrors: true, strict: false });
   (addFormats as any).default
     ? (addFormats as any).default(instance)
     : (addFormats as any)(instance);
+  instance.addSchema(ManifestRootSchema);
   return instance;
 }
 
@@ -301,6 +308,16 @@ export function substituteCelFields(
   if (typeof data === "string" && CEL_PURE_RE.test(data)) {
     return celPlaceholderForSchema(resolved);
   }
+  // `!ref <name>` sentinels are identity markers, not runtime values —
+  // schemas that opt into `$ref: "telo://manifest#/$defs/ResourceRef"`
+  // (or `anyOf` it alongside other shapes) need the actual sentinel
+  // object so AJV validates it against ResourceRefSchema. Collapsing it
+  // to a CEL placeholder would either fail the schema (when the slot
+  // expects the ResourceRef shape) or mask validation errors (when the
+  // slot expects something else entirely).
+  if (isRefSentinel(data)) {
+    return data;
+  }
   if (isTaggedSentinel(data)) {
     return celPlaceholderForSchema(resolved);
   }

package/src/system-kinds.ts

@@ -0,0 +1,37 @@
+/** Resource-kind sets used by analysis passes to decide what counts as a
+ *  user-defined instance vs. a system-level blueprint. Pulled into one
+ *  place so the three passes (reference validation, dependency graph,
+ *  ref-sentinel resolution) don't drift; each pass exports its own
+ *  scoped view with a comment explaining what's in and what's out. */
+
+/** Skipped by reference validation: type blueprints whose own ref slots
+ *  belong to a different phase (definition schema validation rather than
+ *  per-resource validation). Telo.Application and Telo.Library
+ *  intentionally fall through — Application has `targets` (real refs) and
+ *  Library is harmless (no ref-bearing fields). Telo.Import is also
+ *  intentionally not skipped — its `source` is not an x-telo-ref slot, so
+ *  walking it is cheap and consistent. */
+export const REF_VALIDATION_SKIP_KINDS: ReadonlySet<string> = new Set([
+  "Telo.Definition",
+  "Telo.Abstract",
+]);
+
+/** Excluded from the dependency graph: kinds that are not runtime nodes.
+ *  Telo.Abstract is intentionally not in this set today — abstracts have
+ *  no resource manifests, so they never reach graph construction; if
+ *  that ever changes, add it explicitly. */
+export const DEPENDENCY_GRAPH_SKIP_KINDS: ReadonlySet<string> = new Set([
+  "Telo.Definition",
+  "Telo.Import",
+]);
+
+/** Skipped by `!ref` sentinel resolution: kinds whose bodies are
+ *  blueprints or import-time metadata, not resource instances with
+ *  user-referenced ref slots. Mirrors `REF_VALIDATION_SKIP_KINDS` but
+ *  also drops Telo.Import (its `source` isn't a ref slot, and walking
+ *  the field map on it is pointless since there's no registered kind). */
+export const REF_RESOLUTION_SKIP_KINDS: ReadonlySet<string> = new Set([
+  "Telo.Definition",
+  "Telo.Abstract",
+  "Telo.Import",
+]);

package/src/types.ts

@@ -81,6 +81,18 @@ export interface LoaderInitOptions {
 
 export interface AnalysisOptions {
   strictContexts?: boolean;
+  /** When true, `analyze()` runs the state-mutating setup (module identity /
+   *  alias / definition registration plus `normalizeInlineResources`) but
+   *  skips every diagnostic-producing pass — per-resource validation, the
+   *  Library `env:` check, `validateExtends`, `validateProviderCoherence`,
+   *  and `validateThrowsCoverage`. Used by the kernel when a previous load
+   *  has already stamped the manifest set as valid (by content hash), so
+   *  the registry still gets populated without paying the validation walk
+   *  on every cold start. The caller takes responsibility for the
+   *  correctness guarantee — pass this only when something durable
+   *  (on-disk stamp) attests that the manifests passed a real analyze
+   *  pass at the same analyzer / kernel version. */
+  skipValidation?: boolean;
 }
 
 /** Pre-seeded state for incremental analysis. Passed to StaticAnalyzer.analyze() so it does

package/src/validate-references.ts

@@ -1,17 +1,13 @@
 import type { ResourceManifest } from "@telorun/sdk";
+import { isRefSentinel } from "@telorun/templating";
 import { isRefEntry, isScopeEntry, isSchemaFromEntry, isInlineResource, resolveFieldEntries, resolveFieldValues, type RefFieldEntry } from "./reference-field-map.js";
 import { navigateJsonPointer } from "./schema-compat.js";
+import { REF_VALIDATION_SKIP_KINDS as SYSTEM_KINDS } from "./system-kinds.js";
 import { DiagnosticSeverity, type AnalysisDiagnostic, type AnalysisContext } from "./types.js";
 import type { AliasResolver } from "./alias-resolver.js";
 import type { DefinitionRegistry } from "./definition-registry.js";
 
 const SOURCE = "telo-analyzer";
-/** Kinds skipped by reference validation. Telo.Application and Telo.Library
- *  are intentionally not here: Application has `targets` with x-telo-ref that
- *  must be validated, and Library has no ref-bearing fields so flows through
- *  harmlessly. Telo.Import is also not here for the same reason — its
- *  `source` field isn't x-telo-ref, so nothing gets checked. */
-const SYSTEM_KINDS = new Set(["Telo.Definition", "Telo.Abstract"]);
 
 /**
  * Checks whether `kind` satisfies the ref constraint in `entry`.
@@ -145,6 +141,38 @@ export function validateReferences(
       for (const { value: val, path: concretePath } of resolveFieldEntries(r, fieldPath)) {
         if (!val) continue;
 
+        // `!ref <name>` sentinel — bare resource name marked at parse time as a
+        // reference. Look it up against the slot's x-telo-ref constraint exactly
+        // like the legacy bare-string path; the only difference is the value's
+        // shape (a TaggedSentinel rather than a raw string), which removed the
+        // string/inline ambiguity at the source.
+        if (isRefSentinel(val)) {
+          const refName = val.source;
+          const target =
+            byName.get(refName) ?? visibleScopeManifests.find((m) => m.metadata?.name === refName);
+          if (!target) {
+            diagnostics.push({
+              severity: DiagnosticSeverity.Error,
+              code: "UNRESOLVED_REFERENCE",
+              source: SOURCE,
+              message: `${resourceLabel}: reference at '${concretePath}' → resource '${refName}' not found`,
+              data: { resource: resourceData, filePath, path: concretePath },
+            });
+            continue;
+          }
+          const kindErrors = checkKind(target.kind as string, entry, registry, aliases);
+          if (kindErrors.length > 0) {
+            diagnostics.push({
+              severity: DiagnosticSeverity.Error,
+              code: "REFERENCE_KIND_MISMATCH",
+              source: SOURCE,
+              message: `${resourceLabel}: reference at '${concretePath}' → ${kindErrors.join("; ")}`,
+              data: { resource: resourceData, filePath, path: concretePath },
+            });
+          }
+          continue;
+        }
+
         // Name-only reference (plain string) — look up by name to validate.
         // Qualified references use "Kind.Name" format (e.g. "Http.Api.PaymentApi");
         // extract the resource name from the last dot segment.