@telorun/analyzer 0.64.0 → 0.66.0

package/src/reference-field-map.ts

@@ -19,6 +19,10 @@ export interface RefFieldEntry {
   inputs?: string;
   /** True when the field path traversed through at least one array (path contains "[]"). */
   isArray: boolean;
+  /** The slot's non-reference branches, when the reference constraint is a
+   *  branch of a union — see {@link RefSlot.valueBranches}. A value satisfying
+   *  one of these is a value, not a malformed reference. */
+  valueBranches?: Record<string, any>[];
   /** x-telo-context schema declared on this ref slot, if any. Describes the CEL invocation
    *  context available to resources placed in this slot. */
   context?: Record<string, any>;
@@ -62,6 +66,43 @@ export function isRefEntry(entry: FieldMapEntry): entry is RefFieldEntry {
   return "refs" in entry;
 }
 
+/** The half of a definition registry this question needs — structural, so the
+ *  field map keeps depending on nothing. */
+export interface ValueBranchValidator {
+  schemaCompileError(schema: Record<string, any>): string | undefined;
+  validateWithRefs(data: unknown, schema: Record<string, any>): string[];
+}
+
+/**
+ * True when a value at a ref slot satisfies one of the slot's VALUE branches —
+ * a storage class beside a `!ref`, so it is a value and not a malformed
+ * reference.
+ *
+ * One implementation, because BOTH reference passes have to narrow the same way:
+ * `validateReferenceForms` would otherwise call it a removed string reference,
+ * and `validateReferences` a reference missing `kind` and `name`. Two copies of
+ * the rule would eventually disagree about which of the two reported a value.
+ *
+ * A branch AJV cannot COMPILE is not a branch the value satisfies.
+ * `validateWithRefs` returns no issues for one — it swallows the compile failure
+ * by design, so one bad schema does not abort the pass — and reading that as
+ * "no issues, therefore a value" would switch the reference-form rule off for
+ * the slot silently. The uncompilable schema is reported on its own definition
+ * by `schemaCompileError`.
+ */
+export function satisfiesValueBranch(
+  value: unknown,
+  branches: readonly Record<string, any>[] | undefined,
+  registry: ValueBranchValidator,
+): boolean {
+  if (!branches?.length) return false;
+  return branches.some(
+    (branch) =>
+      registry.schemaCompileError(branch) === undefined &&
+      registry.validateWithRefs(value, branch).length === 0,
+  );
+}
+
 export function isScopeEntry(entry: FieldMapEntry): entry is ScopeFieldEntry {
   return "scope" in entry;
 }
@@ -234,6 +275,7 @@ function traverseNode(
     };
     if (slot.useCases) entry.useCases = slot.useCases;
     if (slot.inputs !== undefined) entry.inputs = slot.inputs;
+    if (slot.valueBranches.length > 0) entry.valueBranches = slot.valueBranches;
     if (node["x-telo-context"]) entry.context = node["x-telo-context"] as Record<string, any>;
     if (slot.inline) entry.inline = true;
     map.set(path, entry);

package/src/referrer-rule.ts

@@ -37,6 +37,23 @@ export interface ReferrerRule {
    * relation the rule is about, so a kind should write it.
    */
   readonly referrer?: string;
+  /**
+   * JSON Pointer to a collection OF THE REFERRER to resolve — the binding that
+   * lets a rule state a relation between SIBLING declarations, which neither a
+   * resource rule (one resource) nor a plain referrer rule (a pair joined by one
+   * reference) can reach.
+   *
+   * Declaring it binds `peers` (the collection's OTHER entries) and `entry` (my
+   * own), and makes the rule evaluate once per entry rather than once per
+   * referrer: a rule reading `entry` is about the entry, and a resource listed
+   * twice has two entries to answer for.
+   *
+   * Entries bind AS WRITTEN with the references *inside them* resolved one level
+   * — `p` is the declaration where the entry is a bare `!ref`, `p.mount` is the
+   * declaration with `p.prefix` beside it where it is not. Nothing is guessed
+   * from the item schema and there is no second pointer to write.
+   */
+  readonly peers?: string;
   /** CEL source. TRUE when the rule holds. */
   readonly condition: string;
   /** The rule's own name, carried in `data.rule`. Never a diagnostic code —
@@ -68,15 +85,17 @@ export function readReferrerRules(schema: unknown): ReferrerRule[] {
   raw.forEach((entry, index) => {
     if (!isObject(entry)) return;
     const condition = celSourceOf(entry.condition);
-    const { code, message, referrer } = entry;
+    const { code, message, referrer, peers } = entry;
     if (!condition || typeof code !== "string" || typeof message !== "string") return;
     if (code.length === 0 || message.length === 0) return;
     if (referrer !== undefined && typeof referrer !== "string") return;
+    if (peers !== undefined && typeof peers !== "string") return;
     if (entry.severity !== undefined && entry.severity !== "warning" && entry.severity !== "error") {
       return;
     }
     rules.push({
       ...(referrer === undefined ? {} : { referrer }),
+      ...(peers === undefined ? {} : { peers }),
       condition,
       code,
       message,

package/src/release/index.ts

@@ -2,7 +2,7 @@
  * The release model: module identity, fragments, the ledger, the edge graph,
  * level propagation and version planning.
  *
- * Browser-safe by construction — pure data in, plan out — so the telo editor can
+ * Browser-safe by construction — pure data in, plan out — so telo studio can
  * answer "what does changing this library bump?" from the same model the CLI
  * releases from. Everything Node-shaped (finding the workspace, running the
  * controller builder, building payloads, reading git, writing files) is

package/src/resource-rule.ts

@@ -21,6 +21,7 @@
  *
  * Browser-safe: no Node built-ins.
  */
+import { CEL_ENGINE, isRefSentinel, isTaggedSentinel } from "@telorun/templating";
 
 export const RESOURCE_RULES_ANNOTATION = "x-telo-resource-rules";
 
@@ -58,9 +59,42 @@ function isObject(value: unknown): value is Record<string, unknown> {
  *  Both markers are tested because they are not always both present: a
  *  registered definition's schema reaches the analyzer with `call` and
  *  `__compiled` dropped, keeping only `__tagged` + `source`. Testing one would
- *  make a rule readable on some paths and invisible on others. */
+ *  make a rule readable on some paths and invisible on others.
+ *
+ *  A tagged sentinel of ANOTHER engine is not one. `__tagged` marks every tag
+ *  the loader parses — `!ref` above all — so testing it alone read a reference
+ *  as an expression: a column whose `type:` holds a `!ref` skipped every rule
+ *  that touched `self.columns`, and said "the value holds a CEL expression" about
+ *  a manifest containing none. A reference names a declaration and is a
+ *  perfectly comparable value; what a rule cannot compare is a value COMPUTED at
+ *  create time, which is what this predicate exists to find. */
 function isCelNode(value: unknown): value is { source?: unknown } {
-  return isObject(value) && (value.__compiled === true || value.__tagged === true);
+  if (!isObject(value)) return false;
+  if (value.__compiled === true) return true;
+  return value.__tagged === true && value.engine === CEL_ENGINE;
+}
+
+/** The engine of a non-CEL tagged sentinel — a `!ref`, an `!include-*` — or
+ *  `undefined`. A reference is comparable and never blocks a rule; the other
+ *  tags hold a value only known once the resource is created, so they do, and
+ *  the diagnostic has to name the tag rather than claim CEL. */
+export function deferredTagOf(value: unknown): string | undefined {
+  if (!isTaggedSentinel(value) || isRefSentinel(value)) return undefined;
+  return value.engine === CEL_ENGINE ? undefined : value.engine;
+}
+
+/**
+ * True when a condition was written with the `!cel` tag.
+ *
+ * The readers stay lenient and take a bare string — a rule still runs either
+ * way. What an untagged condition loses is everything outside evaluation: to the
+ * editor's colouring, completion and hover it is a plain string, so a rule author
+ * writes CEL with no help and gets none of the checks a `!cel` scalar gets.
+ * Losing that silently is exactly what a strict half exists to move earlier, so
+ * the tag is reported by the strict halves and never enforced by the readers.
+ */
+export function isTaggedCondition(value: unknown): boolean {
+  return isCelNode(value);
 }
 
 /** A precompiled `!cel` node keeps its author-written text on `source`; a plain
@@ -179,17 +213,45 @@ export function resolveRuleSubjects(
   return undefined;
 }
 
+/** The first leaf a rule cannot compare, and what it is. `what` is a noun
+ *  phrase the diagnostic quotes verbatim, because "a CEL expression" printed
+ *  over an `!include-bytes` embed sends its author looking for an expression
+ *  that is not there. */
+export interface DynamicLeaf {
+  readonly path: string;
+  readonly what: string;
+}
+
+/** Classify ONE node, without descending. Exported because a caller that draws
+ *  its own bound on how far to look (`peer-binding`'s top-level-scalar scan)
+ *  must classify by the same rule as the recursive walk, or a `!ref` is a
+ *  reference to one of them and an expression to the other. */
+export function dynamicNode(value: unknown, path: string): DynamicLeaf | undefined {
+  const at = path || "(value)";
+  if (isCelNode(value)) return { path: at, what: "a CEL expression" };
+  const tag = deferredTagOf(value);
+  return tag ? { path: at, what: `an !${tag} embed` } : undefined;
+}
+
 /**
- * Path of the first CEL leaf inside a value, or `undefined` when every leaf is
- * literal. A rule reading an expression would be evaluating a placeholder, so
- * the subject is skipped — and the skip is reported, never silent.
+ * The first leaf inside a value whose contents are not known until the resource
+ * is created, or `undefined` when every leaf is literal. A rule reading one
+ * would be comparing against a placeholder, so the subject is skipped — and the
+ * skip is reported, never silent.
+ *
+ * A `!ref` is NOT one of them. It is a tagged sentinel like `!cel`, and testing
+ * `__tagged` alone read every reference as an expression: a column whose `type:`
+ * holds a `!ref` switched off every rule touching `self.columns` and reported a
+ * CEL expression in a manifest containing none. A reference names a declaration
+ * — a value a rule compares perfectly well, and the one peer rules are built on.
  *
  * Stops at nested inline `{ kind }` declarations for the reason every other walk
  * does: that CEL belongs to the nested kind, evaluated in its own scope.
  */
-export function findDynamicLeaf(value: unknown, base = ""): string | undefined {
+export function findDynamicLeaf(value: unknown, base = ""): DynamicLeaf | undefined {
   if (isObject(value)) {
-    if (isCelNode(value)) return base || "(value)";
+    const own = dynamicNode(value, base);
+    if (own) return own;
     if (typeof value.kind === "string" && base !== "") return undefined;
     for (const [key, child] of Object.entries(value)) {
       const found = findDynamicLeaf(child, base === "" ? key : `${base}.${key}`);

package/src/rule-condition.ts

@@ -32,6 +32,21 @@ import {
  */
 export const RULE_BUDGET_MS = 50;
 
+/**
+ * The one message for an untagged `condition:`, shared by every rule family so
+ * all of them say the same thing about the same defect.
+ *
+ * The readers stay lenient and a bare string still runs. What it loses is
+ * everything outside evaluation — to the editor's colouring, completion and
+ * hover an untagged condition is a plain string, so its author writes CEL with
+ * no help and none of the checks a `!cel` scalar gets. Losing that silently is
+ * the failure a strict half exists to move earlier.
+ */
+export const UNTAGGED_CONDITION =
+  "Write 'condition' with the !cel tag. The reader is lenient and a bare string still " +
+  "runs, but untagged the expression is not CEL to the editor's colouring, completion " +
+  "or hover, so a rule silently stops being CEL to every surface but this one.";
+
 const HOST_BACKED = new Set(CEL_FUNCTIONS.filter((f) => f.hostBacked).map((f) => f.name));
 const NON_DETERMINISTIC = new Set(
   CEL_FUNCTIONS.filter((f) => !f.deterministic).map((f) => f.name),

package/src/schema-compat.ts

@@ -14,6 +14,7 @@ import {
   valueTypePlaceholder,
 } from "@telorun/sdk";
 import { ManifestRootSchema } from "./manifest-schemas.js";
+import { schemaIssues, type SchemaIssue } from "./schema-error-report.js";
 import { registerTeloKeywords } from "./value-type-keyword.js";
 
 const Ajv = (AjvModule as any).default ?? AjvModule;
@@ -255,55 +256,8 @@ function compare(
   }
 }
 
-export function formatSingleError(err: any): string {
-  const p = err.instancePath || "/";
-  const params = err.params ?? {};
-  switch (err.keyword) {
-    case "additionalProperties":
-      return `${p} must NOT have additional properties ('${params.additionalProperty}' is not allowed)`;
-    case "required":
-      return `${p} is missing required property '${params.missingProperty}'`;
-    case "enum":
-      return `${p} ${err.message ?? "is invalid"} (${(params.allowedValues as unknown[])?.join(" | ")})`;
-    case "type":
-      return `${p} must be ${params.type} (got ${typeof err.data})`;
-    default:
-      return `${p} ${err.message ?? "is invalid"}`;
-  }
-}
-
-export function formatAjvErrors(errors: any[] | null | undefined): string {
-  if (!errors || errors.length === 0) return "Unknown schema error";
-  return errors.map(formatSingleError).join("; ");
-}
-
-/** Converts an AJV error object to a dotted path string compatible with PositionIndex keys.
- *  e.g. instancePath "/config/routes/0/handler" → "config.routes[0].handler"
- *  For "required" keyword errors, appends the missing property to the parent path. */
-function ajvErrorToPath(err: any): string {
-  const instancePath = (err.instancePath ?? "") as string;
-  const parts = instancePath.split("/").filter((p) => p !== "");
-  let result = "";
-  for (const part of parts) {
-    if (/^\d+$/.test(part)) {
-      result += `[${part}]`;
-    } else {
-      result += result ? `.${part}` : part;
-    }
-  }
-  if (err.keyword === "required" && err.params?.missingProperty) {
-    const missing = err.params.missingProperty as string;
-    result += result ? `.${missing}` : missing;
-  }
-  return result;
-}
-
-/** A schema validation issue with a dotted-path pointer to the offending field. */
-export interface SchemaIssue {
-  message: string;
-  /** Dotted path to the field (e.g. "config.handler"). Empty string means root. */
-  path: string;
-}
+export { formatAjvErrors, formatSingleError } from "./schema-error-report.js";
+export type { SchemaIssue } from "./schema-error-report.js";
 
 /** Does `schema` compile as-authored? Used to tell a malformed module schema
  *  (the author's problem) apart from a fault we introduced while normalizing it. */
@@ -335,10 +289,7 @@ export function validateAgainstSchema(data: unknown, schema: Record<string, any>
     compiledSchemaValidators.set(schema, validate);
   }
   if (validate(data)) return [];
-  return (validate.errors ?? []).map((err: any) => ({
-    message: formatSingleError(err),
-    path: ajvErrorToPath(err),
-  }));
+  return schemaIssues(validate.errors);
 }
 
 /** Resolves a JSON Pointer (RFC 6901, must start with "/") into a schema object.
@@ -640,16 +591,55 @@ function objectPlaceholder(schema: Record<string, any>): Record<string, unknown>
 
 const CEL_PURE_RE = /^\s*\$\{\{[^}]*\}\}\s*$/;
 
-/** Resolve a `$ref` (only `#/$defs/...` form) against the root schema. */
-export function resolveRef(schema: Record<string, any>, root: Record<string, any>): Record<string, any> {
-  if (schema.$ref && typeof schema.$ref === "string" && schema.$ref.startsWith("#/$defs/")) {
-    const defName = schema.$ref.slice("#/$defs/".length);
-    const resolved = root.$defs?.[defName];
-    if (resolved) return resolved;
-  }
-  return schema;
+/**
+ * Resolve a `$ref` — the document-local `#/$defs/...` form against `root`, and
+ * anything else through `external` when a caller supplies one.
+ *
+ * A named shape is addressed by a registered id (`telo:<module>/<Type>`), which
+ * lives in a schema store rather than in this document, so without the hook a
+ * walk stops at the reference and treats a described value as undescribed:
+ * every CEL leaf under it is handed the schema-unaware `""` placeholder and
+ * then rejected against a branch it was never measured against. The caller
+ * supplies the store because only the caller has one.
+ */
+export function resolveRef(
+  schema: Record<string, any>,
+  root: Record<string, any>,
+  external?: ExternalSchemaResolver,
+): Record<string, any> {
+  return resolveRefIn(schema, root, external).schema;
+}
+
+/**
+ * {@link resolveRef}, reporting the ROOT the result's own `#/...` references
+ * resolve against.
+ *
+ * Following an external reference enters another document, and a `$ref` inside
+ * it is relative to THAT document — which is the whole of how a shape declares
+ * its own vocabulary (`anyOf: [{$ref: "#/$defs/Text"}, …]`). Resolving those
+ * against the referring document finds nothing, and a walker that then treats
+ * the branches as unconstrained accepts every one of them, resolves the union
+ * to nothing, and hands the values underneath an untyped stand-in. So the base
+ * travels with the schema.
+ */
+export function resolveRefIn(
+  schema: Record<string, any>,
+  root: Record<string, any>,
+  external?: ExternalSchemaResolver,
+): { schema: Record<string, any>; root: Record<string, any> } {
+  if (!schema.$ref || typeof schema.$ref !== "string") return { schema, root };
+  if (schema.$ref === "#") return { schema: root, root };
+  if (schema.$ref.startsWith("#/$defs/")) {
+    const resolved = root.$defs?.[schema.$ref.slice("#/$defs/".length)];
+    return resolved ? { schema: resolved, root } : { schema, root };
+  }
+  const target = external?.(schema.$ref);
+  return target ? { schema: target, root: target } : { schema, root };
 }
 
+/** Looks a registered schema up by its `$id`. */
+export type ExternalSchemaResolver = (ref: string) => Record<string, any> | undefined;
+
 /** Collect property schemas from top-level `properties` and all `oneOf`/`anyOf` sub-schemas. */
 /**
  * The `oneOf` / `anyOf` branch a value is written against, when exactly one fits.
@@ -671,6 +661,7 @@ export function selectUnionBranch(
   schema: Record<string, any>,
   data: unknown,
   root: Record<string, any>,
+  external?: ExternalSchemaResolver,
 ): Record<string, any> {
   const branches = (schema.oneOf ?? schema.anyOf) as Record<string, any>[] | undefined;
   if (!Array.isArray(branches) || branches.length === 0) return schema;
@@ -692,7 +683,7 @@ export function selectUnionBranch(
   if (!kind) return schema;
 
   const fits = branches
-    .map((b) => resolveRef(b, root))
+    .map((b) => resolveRef(b, root, external))
     .filter((b) => {
       const types = Array.isArray(b.type) ? b.type : b.type ? [b.type] : [];
       if (types.length > 0 && !types.includes(kind)) return false;
@@ -733,10 +724,13 @@ export function collectProperties(schema: Record<string, any>): Record<string, a
 
 /** Deep-clone `data`, replacing every pure CEL template string (`${{ expr }}`) with a
  *  schema-appropriate placeholder so AJV can validate non-CEL fields without false positives. */
-export function substituteCelFields(
-  data: unknown,
-  schema: Record<string, any>,
-  rootSchema?: Record<string, any>,
+/** Everything {@link substituteCelFields} does beyond walking the value.
+ *
+ *  One object rather than trailing positionals: the resolver is the parameter a
+ *  caller most needs and was the LAST of six, so reaching it meant counting
+ *  `undefined`s — and a caller that stopped counting one short simply got the
+ *  old blind behaviour, silently. Two of them did. */
+export interface SubstituteOptions {
   /** Called with the dotted path of every value replaced by a placeholder.
    *
    *  A placeholder is a stand-in for something only known at runtime, so its
@@ -746,11 +740,28 @@ export function substituteCelFields(
    *  so making every placeholder acceptable is not achievable in general —
    *  knowing where not to look is. Structural findings survive because they are
    *  located at the CONTAINER, not at the substituted leaf. */
-  onSubstitute?: (path: string) => void,
-  path = "",
+  onSubstitute?: (path: string) => void;
+  /** Dotted path of `data` within the resource, for `onSubstitute`. */
+  path?: string;
+  /** Resolves a named shape (`telo:<module>/<Type>`) to its schema. Without it
+   *  a slot described by one reads as undescribed and every CEL leaf beneath it
+   *  is handed the typeless `""` stand-in — which the shape then rejects, so a
+   *  perfectly valid expression is reported as a violation. */
+  external?: ExternalSchemaResolver;
+}
+
+export function substituteCelFields(
+  data: unknown,
+  schema: Record<string, any>,
+  rootSchema?: Record<string, any>,
+  options: SubstituteOptions = {},
 ): unknown {
-  const root = rootSchema ?? schema;
-  const resolved = selectUnionBranch(resolveRef(schema, root), data, root);
+  const { onSubstitute, external } = options;
+  const path = options.path ?? "";
+  const base = rootSchema ?? schema;
+  const entered = resolveRefIn(schema, base, external);
+  const root = entered.root;
+  const resolved = selectUnionBranch(entered.schema, data, root, external);
   const mark = () => onSubstitute?.(path);
 
   if (typeof data === "string" && CEL_PURE_RE.test(data)) {
@@ -789,9 +800,13 @@ export function substituteCelFields(
     return celPlaceholderForSchema(resolved);
   }
   if (Array.isArray(data)) {
-    const itemSchema = resolveRef((resolved.items ?? {}) as Record<string, any>, root);
-    return data.map((item, i) =>
-      substituteCelFields(item, itemSchema, root, onSubstitute, `${path}[${i}]`),
+    const item = resolveRefIn((resolved.items ?? {}) as Record<string, any>, root, external);
+    return data.map((element, i) =>
+      substituteCelFields(element, item.schema, item.root, {
+        onSubstitute,
+        path: `${path}[${i}]`,
+        external,
+      }),
     );
   }
   if (data !== null && typeof data === "object") {
@@ -802,13 +817,11 @@ export function substituteCelFields(
         : undefined;
     const result: Record<string, unknown> = {};
     for (const [k, v] of Object.entries(data as Record<string, unknown>)) {
-      result[k] = substituteCelFields(
-        v,
-        (props[k] ?? addlProps ?? {}) as Record<string, any>,
-        root,
+      result[k] = substituteCelFields(v, (props[k] ?? addlProps ?? {}) as Record<string, any>, root, {
         onSubstitute,
-        path ? `${path}.${k}` : k,
-      );
+        path: path ? `${path}.${k}` : k,
+        external,
+      });
     }
     return result;
   }