@telorun/analyzer 0.62.0 → 0.63.0

package/src/resolve-zone-requirements.ts

@@ -50,6 +50,11 @@ export interface ZoneRequirementSpec {
    *  check compares against `exports.resources`. */
   correlationName?: string;
   reason?: string;
+  /** Attributes the satisfying zone must declare. Carried across the export
+   *  boundary with the rest of the requirement: a consumer discharging a
+   *  library's open requirement must meet the same guarantee the library's own
+   *  internals would have. */
+  attributes?: string[];
   /** Label of the requiring resource (`sql.Command 'charge'`). */
   origin: string;
   /** Resource names on the propagation path so far, origin first. */
@@ -78,6 +83,9 @@ interface Requirement {
   zone: string;
   /** Kinds that discharge it: the zone kind plus everything extending it. */
   accepted: ReadonlySet<string>;
+  /** Attributes the discharging zone must declare — the GUARANTEE half of the
+   *  requirement, checked at the slot that would otherwise discharge it. */
+  attributes: string[];
   correlation?: string;
   correlationLabel?: string;
   correlationName?: string;
@@ -368,6 +376,7 @@ export function projectZoneRequirements(args: ProjectionArgs): ProjectionResult
       if (!bucket.some((r) => `${r.zone}\0${r.correlation ?? ""}` === req.key)) {
         bucket.push({
           zone: req.zone,
+          ...(req.attributes.length > 0 ? { attributes: req.attributes } : {}),
           correlation: req.correlation,
           correlationLabel: req.correlationLabel,
           correlationName: req.correlationName,
@@ -392,19 +401,57 @@ export function projectZoneRequirements(args: ProjectionArgs): ProjectionResult
       // site. Checked BEFORE termination, so a terminating provider slot
       // (a detached durable body) still discharges its own zone.
       const callerDef = resolveDef(caller.kind, moduleOf(caller));
+      // WHICH slot establishes the zone depends on the body's SHAPE, and both
+      // shapes are real. A ref body annotates the slot the edge itself names
+      // (`Sql.Transaction.steps`, holding a `!ref` to an executable). A NATIVE
+      // body annotates the step ARRAY, while the edge comes from a step inside
+      // it and names that step's own `invoke:` — so looking only at `edge.slot`
+      // finds no annotation and the enclosing zone never discharges anything.
+      // Handling one shape would make every requirement inside a natively-bodied
+      // zone unsatisfiable, which is exactly what a durable workflow's body is.
+      const bodySlot =
+        from.type === "step" ? from.array.replace(/\[\d+\].*$/, "") : edge.slot;
       const slotSchema = schemaNodeAt(
         callerDef?.schema as Record<string, any> | undefined,
-        edge.slot,
+        bodySlot,
       );
       const provides = readProvidesZone(slotSchema);
       if (provides && callerDef && req.accepted.has(canonicalOf(callerDef))) {
+        // A native body's annotation sits on the array, whose enclosing object
+        // IS the resource root — so its correlation pointer anchors there,
+        // rather than at the step item the edge happens to come from.
         const providerKey = provides.key
-          ? resolveProviderKey(caller, edge, provides.key, resolveName)
+          ? from.type === "step"
+            ? resolveStaticKey(caller, [provides.key], resolveName)
+            : resolveProviderKey(caller, edge, provides.key, resolveName)
           : undefined;
         const discharged =
           req.correlation === undefined ||
           (providerKey !== undefined && correlationIdOf(providerKey) === req.correlation);
-        if (discharged) continue;
+        if (discharged) {
+          // The zone is the right KIND but may not make the promise the
+          // requirement is built on. Reported here rather than at the providing
+          // module, because this is the only point where both halves are in
+          // hand: the requirement's demanded attributes and the slot that would
+          // satisfy it. The requirement still discharges — the zone IS open, so
+          // reporting it unsatisfied as well would name the same defect twice
+          // with opposite words.
+          const missing = req.attributes.filter((a) => !(a in provides.attributes));
+          if (missing.length > 0) {
+            emit(
+              DiagnosticSeverity.Error,
+              "ZONE_ATTRIBUTE_MISSING",
+              edge,
+              caller,
+              req,
+              via,
+              `reaches a ${canonicalOf(callerDef)} zone that does not declare ` +
+                `${missing.join(", ")}, so the guarantee this requirement is built on ` +
+                `does not hold inside it`,
+            );
+          }
+          continue;
+        }
       }
 
       // A dynamic selector is already a hard diagnostic (validate-ref-slots);
@@ -567,13 +614,24 @@ export function projectZoneRequirements(args: ProjectionArgs): ProjectionResult
     if (meta?.forwardedExport) continue;
     const def = resolveDef(node.kind, meta?.module);
     const schema = def?.schema as Record<string, any> | undefined;
-    if (!def || !schema?.properties) continue;
+    if (!def || !schema) continue;
+    // A requirement at the SCHEMA ROOT is unconditional: every instance of the
+    // kind must be inside the zone, whatever it is configured with. A parking
+    // kind is exactly that shape — it has no option that turns the requirement
+    // on — and a field-level annotation would have to be attached to some
+    // arbitrary property and would then read "…when you set this one".
+    const slots: [Record<string, any>, string | undefined][] = [[schema, undefined]];
     for (const [field, propSchema] of Object.entries(
-      schema.properties as Record<string, Record<string, any>>,
+      (schema.properties ?? {}) as Record<string, Record<string, any>>,
     )) {
-      const requires = readRequiresZone(propSchema);
+      slots.push([propSchema, field]);
+    }
+    for (const [slotSchema, field] of slots) {
+      const requires = readRequiresZone(slotSchema);
       if (!requires) continue;
-      if ((node.manifest as Record<string, unknown>)[field] === undefined) continue;
+      if (field !== undefined && (node.manifest as Record<string, unknown>)[field] === undefined) {
+        continue;
+      }
       const zoneDef = resolveDef(requires.zone, def.metadata.module);
       if (!zoneDef) continue; // ZONE_PROVIDER_UNRESOLVED is reported at registration
       const zone = canonicalOf(zoneDef);
@@ -581,6 +639,7 @@ export function projectZoneRequirements(args: ProjectionArgs): ProjectionResult
       const req: Requirement = {
         zone,
         accepted: acceptedFor(zone),
+        attributes: requires.attributes,
         correlation: target ? correlationIdOf(target) : undefined,
         correlationLabel: target ? labelOf(target) : undefined,
         correlationName: target?.name,
@@ -609,6 +668,7 @@ export function projectZoneRequirements(args: ProjectionArgs): ProjectionResult
         const req: Requirement = {
           zone: spec.zone,
           accepted: zoneDef ? acceptedFor(spec.zone) : new Set([spec.zone]),
+          attributes: spec.attributes ?? [],
           correlation: spec.correlation,
           correlationLabel: spec.correlationLabel,
           correlationName: spec.correlationName,

package/src/resource-rule.ts

@@ -0,0 +1,252 @@
+/**
+ * The single reader for `x-telo-resource-rules` — a kind declaring, as data,
+ * relationships between the fields of one resource that JSON Schema cannot
+ * state: an index naming a column its table does not declare, a foreign key
+ * whose two sides differ in length, a rename whose source is still declared.
+ *
+ * The predicate is CEL over `self` (the whole resource) and `this` (the element
+ * under test), so correlating two collections is a comprehension closure rather
+ * than a path language with wildcard bindings to design. `in:` names the
+ * collection to iterate and IS the diagnostic anchor: iterating what the pointer
+ * names is what makes a reported path exist by construction.
+ *
+ * Vocabulary borrowed from `Telo.JsonSchema.rules` — `condition` true when the
+ * rule HOLDS, the subject bound as `this`, plus `code` and `message` — because
+ * two CEL rule vocabularies with opposite polarity is a trap an author falls
+ * into once per rule. The two mechanisms stay separate: a `Telo.JsonSchema` rule
+ * runs at dispatch against a value, this one at `telo check` against a manifest.
+ *
+ * Lenient by design, the `ref-slot.ts` precedent: anything unreadable here reads
+ * as absent, and `validate-resource-rules.ts` is the strict half that reports it.
+ *
+ * Browser-safe: no Node built-ins.
+ */
+
+export const RESOURCE_RULES_ANNOTATION = "x-telo-resource-rules";
+
+export type ResourceRuleSeverity = "error" | "warning";
+
+export interface ResourceRule {
+  /** JSON Pointer to the collection to iterate. Absent = the whole-resource
+   *  form, which reports at the resource rather than at an element. */
+  readonly in?: string;
+  /** CEL source. TRUE when the rule holds. */
+  readonly condition: string;
+  /** The rule's own name, carried in `data.rule`. Never a diagnostic code —
+   *  every violation reports under the analyzer-owned envelope. */
+  readonly code: string;
+  readonly message: string;
+  readonly severity: ResourceRuleSeverity;
+  /** Position in the annotation array — the anchor for a declaration defect. */
+  readonly index: number;
+}
+
+/** One element a rule is evaluated against. */
+export interface RuleSubject {
+  /** Dotted/bracketed path from the resource root, for `data.path`. */
+  readonly path: string;
+  readonly value: unknown;
+  /** Present when the collection is a map: the entry's key. */
+  readonly key?: string;
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+/** True for a node the loader produced from a `!cel` tag or a `${{ }}` string.
+ *  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. */
+function isCelNode(value: unknown): value is { source?: unknown } {
+  return isObject(value) && (value.__compiled === true || value.__tagged === true);
+}
+
+/** A precompiled `!cel` node keeps its author-written text on `source`; a plain
+ *  string is taken verbatim so a rule reads the same however the loader was
+ *  configured (a round-trip view runs with `compile` off). */
+export function celSourceOf(value: unknown): string | undefined {
+  if (typeof value === "string") return value;
+  if (isCelNode(value) && typeof value.source === "string") return value.source;
+  return undefined;
+}
+
+/** The annotation exactly as written, for the strict half. `undefined` when the
+ *  kind declares none; a non-array is returned as-is so the shape can be
+ *  reported rather than silently skipped. */
+export function readRawResourceRules(schema: unknown): unknown {
+  if (!isObject(schema)) return undefined;
+  return schema[RESOURCE_RULES_ANNOTATION];
+}
+
+/** Every rule this kind declares that is well-formed enough to run. */
+export function readResourceRules(schema: unknown): ResourceRule[] {
+  const raw = readRawResourceRules(schema);
+  if (!Array.isArray(raw)) return [];
+  const rules: ResourceRule[] = [];
+  raw.forEach((entry, index) => {
+    if (!isObject(entry)) return;
+    const condition = celSourceOf(entry.condition);
+    const { code, message } = entry;
+    if (!condition || typeof code !== "string" || typeof message !== "string") return;
+    if (code.length === 0 || message.length === 0) return;
+    const severity = entry.severity === "warning" ? "warning" : "error";
+    if (entry.severity !== undefined && entry.severity !== "warning" && entry.severity !== "error") {
+      return;
+    }
+    const pointer = entry.in;
+    if (pointer !== undefined && typeof pointer !== "string") return;
+    rules.push({
+      ...(pointer === undefined ? {} : { in: pointer }),
+      condition,
+      code,
+      message,
+      severity,
+      index,
+    });
+  });
+  return rules;
+}
+
+/** Split a JSON Pointer into its unescaped segments. `/` alone is the root. */
+export function pointerSegments(pointer: string): string[] | undefined {
+  if (pointer === "" || pointer === "/") return [];
+  if (!pointer.startsWith("/")) return undefined;
+  return pointer
+    .slice(1)
+    .split("/")
+    .map((segment) => segment.replace(/~1/g, "/").replace(/~0/g, "~"));
+}
+
+/** Navigate a pointer within a value, stopping at anything that is not a plain
+ *  container. Returns `undefined` for a pointer that does not resolve — which a
+ *  resource legitimately produces by omitting an optional collection. */
+export function resolvePointer(value: unknown, pointer: string): unknown {
+  const segments = pointerSegments(pointer);
+  if (!segments) return undefined;
+  let current: unknown = value;
+  for (const segment of segments) {
+    if (Array.isArray(current)) {
+      const index = Number(segment);
+      if (!Number.isInteger(index)) return undefined;
+      current = current[index];
+    } else if (isObject(current)) {
+      current = current[segment];
+    } else {
+      return undefined;
+    }
+    if (current === undefined) return undefined;
+  }
+  return current;
+}
+
+/** Path prefix for a pointer, in the dotted/bracketed spelling diagnostics use
+ *  (`foreignKeys[0].references`), so `data.path` is one grammar throughout. */
+export function pointerToPath(pointer: string): string {
+  const segments = pointerSegments(pointer) ?? [];
+  return segments.reduce<string>((acc, segment) => {
+    if (/^\d+$/.test(segment)) return `${acc}[${segment}]`;
+    return acc === "" ? segment : `${acc}.${segment}`;
+  }, "");
+}
+
+/**
+ * The elements a rule iterates. An array yields one subject per item, a map one
+ * per entry with its key bound; a collection that is absent yields none, which
+ * is a rule that had nothing to say rather than a rule that failed.
+ *
+ * A scalar at the pointer is `undefined` — not an empty list — because that is a
+ * declaration defect the strict half reports, and an empty list would hide it.
+ */
+export function resolveRuleSubjects(
+  config: unknown,
+  pointer: string,
+): RuleSubject[] | undefined {
+  const collection = resolvePointer(config, pointer);
+  if (collection === undefined || collection === null) return [];
+  const base = pointerToPath(pointer);
+  if (Array.isArray(collection)) {
+    return collection.map((value, index) => ({ path: `${base}[${index}]`, value }));
+  }
+  if (isObject(collection)) {
+    return Object.entries(collection).map(([key, value]) => ({
+      path: `${base}.${key}`,
+      value,
+      key,
+    }));
+  }
+  return 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.
+ *
+ * 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 {
+  if (isObject(value)) {
+    if (isCelNode(value)) return base || "(value)";
+    if (typeof value.kind === "string" && base !== "") return undefined;
+    for (const [key, child] of Object.entries(value)) {
+      const found = findDynamicLeaf(child, base === "" ? key : `${base}.${key}`);
+      if (found) return found;
+    }
+    return undefined;
+  }
+  if (Array.isArray(value)) {
+    for (let i = 0; i < value.length; i++) {
+      const found = findDynamicLeaf(value[i], `${base}[${i}]`);
+      if (found) return found;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * The nodes a condition actually READS, resolved against the resource and the
+ * element under test — the input to the dynamic-leaf check.
+ *
+ * Scanning the whole subject instead would make the check useless in exactly
+ * the shape it matters most: a resource-wide rule takes the whole resource as
+ * its subject, so one unrelated `!cel` anywhere (a `version:` read from
+ * `module.version`, which is the conventional spelling) would switch off every
+ * such rule. Chains are the same primitive the binding-order derivation uses:
+ * parsed, never lexed, so a name inside a string literal reads nothing.
+ *
+ * A chain stops at a computed index (`INDEX_SEGMENT`): what it selects is not
+ * known statically, so the node reached so far is what gets checked — the
+ * over-approximating direction, which errs toward skipping rather than toward
+ * evaluating a placeholder.
+ */
+export function readNodes(
+  chains: readonly (readonly string[])[],
+  /** The bindings in scope, by name — `self`/`this`/`key` for a resource rule,
+   *  `self`/`referrer` for a referrer rule. A chain rooted at a name that is not
+   *  bound reads nothing. */
+  roots: Record<string, unknown>,
+): unknown[] {
+  const nodes: unknown[] = [];
+  for (const chain of chains) {
+    const root = chain[0];
+    let current: unknown = root !== undefined && root in roots ? roots[root] : undefined;
+    if (current === undefined) continue;
+    for (const segment of chain.slice(1)) {
+      if (segment === "[*]") break;
+      if (Array.isArray(current)) {
+        const index = Number(segment);
+        current = Number.isInteger(index) ? current[index] : undefined;
+      } else if (isObject(current)) {
+        current = current[segment];
+      } else {
+        current = undefined;
+      }
+      if (current === undefined) break;
+    }
+    if (current !== undefined) nodes.push(current);
+  }
+  return nodes;
+}

package/src/rule-condition.ts

@@ -0,0 +1,126 @@
+/**
+ * A rule's CEL condition: compiling it once, and refusing the ones that cannot
+ * be checks.
+ *
+ * Shared by `x-telo-resource-rules` (fields of one resource) and
+ * `x-telo-referrer-rules` (a requirement on whoever references it). The two
+ * families differ in what they bind — `this` and `key` versus `referrer` — and
+ * in nothing else: same polarity, same cache, same refusals, same budget. Two
+ * copies would eventually disagree about which functions a rule may call, which
+ * is a soundness property rather than a style one.
+ *
+ * Browser-safe: no Node built-ins.
+ */
+import {
+  CEL_FUNCTIONS,
+  buildCelEnvironment,
+  celEngine,
+  extractAccessChains,
+} from "@telorun/templating";
+
+/**
+ * Wall-clock ceiling for one rule over one resource. The rules run on the
+ * kernel's boot path and at the editor's keystroke-time analysis, and the
+ * comprehension nesting is the RULE AUTHOR's — a dependency's quadratic rule
+ * must not be able to hang a consumer's `telo check`.
+ *
+ * It bounds the SUBJECT LOOP, not one expression: cel-js offers no step limit,
+ * so a single pathological expression over one huge element still runs to
+ * completion. Stated rather than hidden — the budget catches the shape that
+ * actually occurs (a cheap expression over many subjects) and reports the rule
+ * as defective rather than truncating coverage silently.
+ */
+export const RULE_BUDGET_MS = 50;
+
+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),
+);
+
+let sharedEnv: ReturnType<typeof buildCelEnvironment> | undefined;
+/** The analyzer's own environment — no host handlers, so every `hostBacked`
+ *  entry is a throwing stub. Built once; it is stateless. */
+export function ruleEnv(): ReturnType<typeof buildCelEnvironment> {
+  sharedEnv ??= buildCelEnvironment();
+  return sharedEnv;
+}
+
+export type CompiledRule =
+  | { parsed: (ctx: Record<string, unknown>) => unknown; chains: readonly (readonly string[])[] }
+  | { reason: string };
+
+/**
+ * A rule's condition, parsed once per process rather than once per resource.
+ *
+ * The pass runs over every resource of a kind and at the editor's
+ * keystroke-time analysis, so a workspace with fifty tables parsed the same
+ * six conditions fifty times each. The source string is the whole key: the
+ * environment is stateless and shared, so two identical conditions genuinely
+ * compile to the same program. A parse FAILURE is cached too — it is a property
+ * of the condition, and re-deriving it per resource costs the same as the
+ * success it replaced.
+ *
+ * BOUNDED, because the editor analyses on every keystroke: a kind author editing
+ * a `condition:` interns one entry per character typed, and every one of those
+ * intermediate strings is dead the moment the next arrives. Insertion-ordered
+ * eviction is enough — the working set is the conditions a workspace actually
+ * declares, and a stale entry costs one re-parse.
+ */
+const RULE_CACHE_LIMIT = 512;
+const compiledRules = new Map<string, CompiledRule>();
+
+export function compileRuleCondition(
+  condition: string,
+  /** Chain roots to assume when the parse yields no AST — "unknown", not
+   *  "reads nothing", so the caller checks the whole of every binding. */
+  fallbackRoots: readonly string[],
+): CompiledRule {
+  const cached = compiledRules.get(condition);
+  if (cached) return cached;
+  let result: CompiledRule;
+  try {
+    const parsed = ruleEnv().parse(condition) as (ctx: Record<string, unknown>) => unknown;
+    const ast = (parsed as unknown as { ast?: unknown }).ast;
+    result = {
+      parsed,
+      chains: ast ? extractAccessChains(ast as never) : fallbackRoots.map((root) => [root]),
+    };
+  } catch (err) {
+    result = { reason: err instanceof Error ? err.message : String(err) };
+  }
+  if (compiledRules.size >= RULE_CACHE_LIMIT) {
+    const oldest = compiledRules.keys().next();
+    if (!oldest.done) compiledRules.delete(oldest.value);
+  }
+  compiledRules.set(condition, result);
+  return result;
+}
+
+/**
+ * Why a condition cannot serve as a check, as messages for the declaring kind.
+ *
+ * Two refusals beyond the CEL diagnostics themselves: a function the kernel
+ * supplies at boot (a throwing stub here, so the rule could never run at
+ * `telo check`), and a non-deterministic one (a verdict that depends on when it
+ * ran is not a verdict).
+ */
+export function conditionRefusals(condition: string): string[] {
+  const out: string[] = [];
+  const result = celEngine.analyze(condition, { celEnv: ruleEnv(), contextSchema: null });
+  for (const diagnostic of result.diagnostics) out.push(`Rule condition: ${diagnostic.message}`);
+  for (const call of result.calls) {
+    if (HOST_BACKED.has(call.name)) {
+      out.push(
+        `Rule condition calls '${call.name}()', which the kernel supplies at boot ` +
+          "(it needs Node crypto / Buffer). The analyzer registers a throwing stub, so " +
+          "the rule cannot run at telo check.",
+      );
+    } else if (NON_DETERMINISTIC.has(call.name) || call.deterministic === false) {
+      out.push(
+        `Rule condition calls '${call.name}()', which re-evaluates per call. A check ` +
+          "whose verdict depends on when it ran is not a check.",
+      );
+    }
+  }
+  return out;
+}

package/src/schema-keywords.ts

@@ -276,6 +276,30 @@ export const TELO_SCHEMA_ANNOTATIONS: Record<
     description: "Derive this field's validation schema from a sibling ref's definition schema.",
     type: "string",
   },
+  "x-telo-schema-map": {
+    title: "Schema map",
+    description:
+      "On the field a projection keys on: the JSON Schema node each of its values means. A lookup, never a computed expression.",
+    type: "object",
+  },
+  "x-telo-schema-projection": {
+    title: "Schema projection",
+    description:
+      "How a collection of typed entries projects to a JSON Schema object — which collection, which field keys it, and which fields modify it. Belongs on the kind DOCUMENT, beside 'schema:' rather than inside it, because it describes the whole declaration and not one field; written here it still works and is reported so it can be moved.",
+    type: "object",
+  },
+  "x-telo-resource-rules": {
+    title: "Resource rules",
+    description:
+      "Relationships between this kind's own fields that JSON Schema cannot state, as CEL over `self` (the resource) and `this` (the element `in:` iterates). `condition` is TRUE when the rule holds.",
+    type: "array",
+  },
+  "x-telo-schema-projection-from": {
+    title: "Schema projection from",
+    description:
+      "Replace this node with the projection of the entry collection declared by the kind referenced at the named field.",
+    type: "string",
+  },
   "x-telo-value-schema-from": {
     title: "Value schema from",
     description: