@telorun/analyzer 0.65.0 → 0.67.0

package/src/validate-cel-context.ts

@@ -6,8 +6,37 @@ import {
   parseCanonicalTypeSchemaId,
 } from "@telorun/sdk";
 import { KERNEL_BUILTINS } from "./builtins.js";
-import { isStepSlot } from "./step-slot.js";
 import { withRefSlotsAsReadings } from "./ref-slot-reading.js";
+// Where CEL is evaluated is one reader (`eval-paths.ts`), and the region half of
+// it moved there so the scope walk and the `x-telo-eval` walk answer the same
+// question in one place. Re-exported: this module is where every existing
+// consumer imports them from.
+export { extractCelRegionScopes, pathMatchesScope } from "./eval-paths.js";
+import { pathMatchesScope } from "./eval-paths.js";
+
+/** True when a node's value is decided at load or dispatch rather than written
+ *  — a tagged sentinel (`!cel`, `!sql`, an embed) or an already-compiled value.
+ *  A schema position holding one declares a shape nothing static can read. */
+function isDynamicNode(value: unknown): boolean {
+  if (!value || typeof value !== "object") return false;
+  const node = value as Record<string, unknown>;
+  return node.__tagged === true || node.__compiled !== undefined;
+}
+
+/** Replace every dynamically-valued property with an OPEN schema, so the name is
+ *  in scope with its members unconstrained. */
+function openDynamicProperties(
+  props: Record<string, any> | undefined,
+): Record<string, any> | undefined {
+  if (!props || typeof props !== "object") return props;
+  let out: Record<string, any> | undefined;
+  for (const [key, value] of Object.entries(props)) {
+    if (!isDynamicNode(value)) continue;
+    out ??= { ...props };
+    out[key] = {};
+  }
+  return out ?? props;
+}
 
 export interface ContextResolveOpts {
   /** When provided, used to resolve `x-telo-context-from-root` annotations against the
@@ -282,35 +311,6 @@ function collectionBindingWithheld(
   return isLiveSlot(resolveCollectionSchema(manifestRoot, from, allManifests));
 }
 
-/**
- * Returns true when a CEL expression path (from walkCelExpressions, e.g. "routes[0].inputs.q")
- * falls within the scope of a context (e.g. "$.routes[*].inputs").
- *
- * The scope is matched directly (no sibling sharing): a context at "$.routes[*].inputs" only
- * applies to expressions whose path starts with "routes[N].inputs", not to other sibling fields.
- */
-export function pathMatchesScope(exprPath: string, scope: string): boolean {
-  const stripped = scope.startsWith("$.") ? scope.slice(2) : scope;
-  if (!stripped) return false;
-
-  // Split on wildcard array segments; each [*] must match a concrete [N] in exprPath
-  const parts = stripped.split("[*]");
-  let remaining = exprPath;
-  for (let i = 0; i < parts.length; i++) {
-    const part = parts[i]!;
-    if (!remaining.startsWith(part)) return false;
-    remaining = remaining.slice(part.length);
-    if (i < parts.length - 1) {
-      // Expect a concrete array index like [0], [12], ...
-      const m = remaining.match(/^\[\d+\]/);
-      if (!m) return false;
-      remaining = remaining.slice(m[0].length);
-    }
-  }
-  // Expression must end here or continue into a child path
-  return remaining === "" || remaining[0] === "." || remaining[0] === "[";
-}
-
 /**
  * Resolves `x-telo-context-*` annotations in a context schema using the concrete
  * manifest item (per-scope) and the manifest root.
@@ -381,8 +381,19 @@ export function resolveContextAnnotations(
     // to be resolved first: the standard library writes it as the inline
     // `{ kind: Type.JsonSchema, schema: … }` wrapper, so merging it verbatim
     // would type the variable as `{ kind, schema }` instead of its properties.
+    // The navigated node — or one of the properties in it — may itself be an
+    // expression: a route whose `request.schema.body` is `!cel "self.model.schema"`
+    // declares a body whose SHAPE is only known once the template is
+    // instantiated. Such a name types as OPEN rather than as nothing, and a
+    // wholly dynamic map leaves the whole node open. Resolving it to nothing
+    // reports `request.body` as undefined, which blames the reader for the
+    // writer's dynamism — the same posture a rule takes when a value it reads
+    // is dynamic: skip the judgement, never invert it.
+    if (isDynamicNode(navigated)) {
+      return { ...schema, properties: { ...(schema.properties ?? {}) }, additionalProperties: true };
+    }
     const asType = resolveTypeFieldToSchema(navigated, allManifests ?? []);
-    const resolved = asType?.properties ?? navigated;
+    const resolved = openDynamicProperties(asType?.properties ?? navigated);
     const required = Array.isArray(asType?.required) ? asType.required : undefined;
     return {
       ...schema,
@@ -544,12 +555,37 @@ export function getManifestItem(
   manifest: Record<string, any>,
 ): Record<string, any> {
   const stripped = scope.startsWith("$.") ? scope.slice(2) : scope;
-  const wildcardIdx = stripped.indexOf("[*]");
-  if (wildcardIdx === -1) return manifest;
-  const arrayProp = stripped.slice(0, wildcardIdx); // e.g. "routes"
-  const m = exprPath.match(new RegExp(`^${arrayProp}\\[(\\d+)\\]`));
-  if (!m) return manifest;
-  return (manifest as any)[arrayProp]?.[Number(m[1])] ?? manifest;
+  const parts = stripped.split("[*]");
+  if (parts.length === 1) return manifest;
+  // Resolve each `[*]` against the concrete index the expression path carries at
+  // the same position, accumulating up to the LAST wildcard: that node is the
+  // per-scope item (`routes[2]`), which is what `x-telo-context-from` navigates
+  // from. Built by walking the pattern rather than by a regex over the scope —
+  // a scope is a path, not a pattern, and its own `[4]` segments are regex
+  // character classes, which is what silently made every nested scope resolve
+  // to the whole document instead of the item.
+  let remaining = exprPath;
+  let concrete = "";
+  for (let i = 0; i < parts.length - 1; i++) {
+    const part = parts[i]!;
+    if (!remaining.startsWith(part)) return manifest;
+    remaining = remaining.slice(part.length);
+    const index = remaining.match(/^\[(\d+)\]/);
+    if (!index) return manifest;
+    remaining = remaining.slice(index[0].length);
+    concrete += `${part}${index[0]}`;
+  }
+  return (navigateConcretePath(manifest, concrete) as Record<string, any> | undefined) ?? manifest;
+}
+
+/** Walk a concrete dotted path with `[N]` indices (`resources[4].routes[2]`). */
+function navigateConcretePath(root: unknown, path: string): unknown {
+  let cur: unknown = root;
+  for (const segment of path.match(/[^.[\]]+/g) ?? []) {
+    if (cur === null || typeof cur !== "object") return undefined;
+    cur = (cur as Record<string, unknown>)[segment];
+  }
+  return cur;
 }
 
 function navigatePath(obj: unknown, segments: string[]): unknown {
@@ -579,47 +615,6 @@ export function extractContextsFromSchema(
   return all.sort((a, b) => b.scope.length - a.scope.length);
 }
 
-/** Schema keys that declare a CEL-bearing region: a field carrying any of these
- *  is evaluated at runtime, so a `!cel` inside it (or a descendant) is live. A
- *  STEP BODY is one too, and says so through the grammar its items point at
- *  rather than through a key — {@link isStepSlot} reads either spelling. */
-const CEL_REGION_KEYS = [
-  "x-telo-context",
-  "x-telo-step-context",
-  "x-telo-error-context",
-] as const;
-
-/**
- * Walk a JSON Schema tree and collect the JSONPath scopes of every field that
- * declares a CEL-bearing region (`x-telo-context` / `x-telo-step-context` /
- * `x-telo-error-context`). Used — alongside `x-telo-eval` paths — to decide
- * whether a `!cel` expression sits in a slot the runtime actually evaluates.
- * Scopes use the same `$.a.b[*]` form as `extractContextsFromSchema`, matched
- * against expression paths with `pathMatchesScope`.
- */
-export function extractCelRegionScopes(schema: Record<string, any>, path = "$"): string[] {
-  if (!schema || typeof schema !== "object") return [];
-  const out: string[] = [];
-
-  if (CEL_REGION_KEYS.some((k) => schema[k]) || isStepSlot(schema)) out.push(path);
-
-  if (schema.properties) {
-    for (const [key, value] of Object.entries(schema.properties as Record<string, any>)) {
-      out.push(...extractCelRegionScopes(value, `${path}.${key}`));
-    }
-  }
-  if (schema.items && typeof schema.items === "object") {
-    out.push(...extractCelRegionScopes(schema.items, `${path}[*]`));
-  }
-  for (const key of ["oneOf", "anyOf", "allOf"] as const) {
-    if (Array.isArray(schema[key])) {
-      for (const subschema of schema[key]) out.push(...extractCelRegionScopes(subschema, path));
-    }
-  }
-
-  return out;
-}
-
 function collectContexts(
   schema: Record<string, any>,
   path: string,

package/src/validate-identifier-names.ts

@@ -9,6 +9,7 @@ import {
   type NameLevel,
   type NameViolation,
 } from "./identifier-name.js";
+import { isInjectedDeclaration } from "./resource-input.js";
 import { type AnalysisDiagnostic } from "./types.js";
 
 const SOURCE = "telo-analyzer";
@@ -56,6 +57,11 @@ export function validateIdentifierNames(
     // would blame them for a spelling this pass's own pipeline chose.
     if (metadata?.xTeloOrigin) continue;
 
+    // A kind-only stand-in for a `resources:` entry carries the name the author
+    // wrote in that block, and the block's own keys are checked below — on the
+    // module doc, where the name is written and a squiggle can land.
+    if (isInjectedDeclaration(manifest)) continue;
+
     const ownModule = metadata?.module as string | undefined;
     if (ownModule && !rootModules.has(ownModule)) continue;
 
@@ -74,7 +80,10 @@ export function validateIdentifierNames(
     // keys are the imported library's declarations, so a violation there is
     // the library author's, reported when their module is analyzed as a root.
     if (manifest.kind === "Telo.Application" || manifest.kind === "Telo.Library") {
-      for (const field of ["variables", "secrets", "ports"] as const) {
+      // `resources:` joins them: a library's resource inputs are named in the
+      // same identifier space (`!ref connection`, `resources.connection`) and
+      // break the same way.
+      for (const field of ["variables", "secrets", "ports", "resources"] as const) {
         const block = (manifest as Record<string, unknown>)[field];
         if (!block || typeof block !== "object" || Array.isArray(block)) continue;
         for (const key of Object.keys(block as Record<string, unknown>)) {
@@ -149,8 +158,14 @@ function surfaceFor(kind: string): string {
   }
 }
 
-function singular(field: "variables" | "secrets" | "ports"): string {
-  return field === "variables" ? "variable" : field === "secrets" ? "secret" : "port";
+function singular(field: "variables" | "secrets" | "ports" | "resources"): string {
+  return field === "variables"
+    ? "variable"
+    : field === "secrets"
+      ? "secret"
+      : field === "ports"
+        ? "port"
+        : "resource input";
 }
 
 function push(

package/src/validate-reference-forms.ts

@@ -3,6 +3,7 @@ import { isTaggedSentinel } from "@telorun/templating";
 import type { AliasResolver } from "./alias-resolver.js";
 import type { DefinitionRegistry } from "./definition-registry.js";
 import { visitManifest } from "./manifest-visitor.js";
+import { satisfiesValueBranch } from "./reference-field-map.js";
 import { REF_VALIDATION_SKIP_KINDS as SYSTEM_KINDS } from "./system-kinds.js";
 import { DiagnosticSeverity, type AnalysisDiagnostic } from "./types.js";
 
@@ -29,6 +30,16 @@ const SOURCE = "telo-analyzer";
  * Rejected, each with an actionable diagnostic pointing at `!ref`:
  *   - the object form `{ kind, name }` (the old reference object), and
  *   - a bare string (the old name / dotted-FQN reference).
+ *
+ * **A value-or-reference union slot is the one exception**, and it is decided by
+ * the value rather than by a new spelling: where the reference constraint is a
+ * *branch* of a union (`type:` on a column, holding either a storage class or a
+ * `!ref` to a declared enum), a SCALAR is a value and is left to that branch,
+ * while an object is still checked for the removed `{kind, name}` form unless a
+ * branch describes it. The rule guards a REMOVED spelling — a bare string is
+ * simply not a reference in Telo — so admitting one takes nothing away: what it
+ * costs is the answer when an author meant a reference and wrote a bare name,
+ * which against a closed branch AJV reports as an unknown value.
  */
 export function validateReferenceForms(
   resources: ResourceManifest[],
@@ -52,6 +63,17 @@ export function validateReferenceForms(
         // `!ref` and `!cel`/`${{ }}` sentinels are the supported shapes.
         if (isTaggedSentinel(value)) return;
 
+        // A SCALAR at a slot whose union has a value branch is a value, and the
+        // value branch is what judges it. Reporting a mistyped storage class as
+        // a malformed reference — "write it as '!ref txt'" — instructs the author
+        // to convert a typo into a reference, and AJV has already said what the
+        // value must be one of. The object form below is not ambiguous the same
+        // way: `{kind, name}` is the removed reference object, so it is still
+        // reported unless a branch genuinely describes that shape.
+        const hasValueBranch = (e.entry.valueBranches?.length ?? 0) > 0;
+        if (hasValueBranch && typeof value !== "object") return;
+        if (satisfiesValueBranch(value, e.entry.valueBranches, registry)) return;
+
         const r = e.source;
         const resourceLabel = `${r.kind}/${r.metadata!.name as string}`;
         const resourceData = { kind: r.kind, name: r.metadata!.name as string };

package/src/validate-references.ts

@@ -1,7 +1,13 @@
 import type { ResourceManifest } from "@telorun/sdk";
 import { isRefSentinel } from "@telorun/templating";
 import { visitManifest } from "./manifest-visitor.js";
-import { isInlineResource, resolveFieldEntries, resolveFieldValues, type RefFieldEntry } from "./reference-field-map.js";
+import {
+  isInlineResource,
+  resolveFieldEntries,
+  resolveFieldValues,
+  satisfiesValueBranch,
+  type RefFieldEntry,
+} from "./reference-field-map.js";
 import { navigateJsonPointer, substituteCelFields } from "./schema-compat.js";
 import { REF_VALIDATION_SKIP_KINDS as SYSTEM_KINDS } from "./system-kinds.js";
 import { resolveTypeFieldToSchema } from "./validate-cel-context.js";
@@ -12,11 +18,53 @@ import type { DefinitionRegistry } from "./definition-registry.js";
 const SOURCE = "telo-analyzer";
 
 /**
- * Checks whether `kind` satisfies the ref constraint in `entry`.
- * Returns an empty array when valid, or mismatch error strings when not.
- * Returns an empty array immediately when the ref identity is not registered
- * (partial context — skip check rather than false-positive).
+ * Liskov substitutability at a kind constraint: is `resolved` (a canonical
+ * `<module>.<Kind>`) accepted where `targetKind` is required?
+ *
+ * THE one implementation — `checkKind` below builds a MESSAGE from it and adds
+ * nothing to the rule, so a resource input's injection site and an ordinary ref
+ * slot cannot come to disagree about what satisfies a constraint.
+ *
+ * A value satisfies the slot when it transitively extends the target kind, or —
+ * for a CONCRETE target — IS that kind; `getByExtends` is the same transitive
+ * subtype index for both, and an abstract is satisfied only by an implementer,
+ * never by the abstract itself (which is non-instantiable). Accepts a constraint
+ * that resolves to nothing, and an abstract with no loaded implementations:
+ * partial context, where a rejection would be a guess.
  */
+export function kindSatisfies(
+  resolved: string,
+  targetKind: string,
+  registry: DefinitionRegistry,
+): boolean {
+  const canonical = registry.resolveRef(targetKind) ?? targetKind;
+  const targetDef = registry.resolve(canonical);
+  if (!targetDef) return true;
+  if (targetDef.kind !== "Telo.Abstract" && resolved === canonical) return true;
+  const subtypes = registry.getByExtends(canonical);
+  if (subtypes.some((d) => `${d.metadata.module}.${d.metadata.name}` === resolved)) return true;
+  // Leniency is about the CANDIDATE, not about the population, and it is the
+  // same question for an abstract target and a concrete one. Accepting whenever
+  // no subtype happened to be loaded silenced the check exactly where it was
+  // needed: an app whose imports declare no `Telo.Runnable` is an app whose boot
+  // targets are all wrong, and every one of them passed.
+  //
+  // An UNREGISTERED candidate is not partial context, and the distinction is
+  // load-bearing: a kind nobody declared is an unknown kind or an unimported
+  // alias prefix (`NotAnAlias.Script`), which is precisely what this check
+  // exists to report. Only a kind that IS declared, whose ancestry reaches
+  // something this analysis never saw, is undecidable — there the missing hop is
+  // where the target it appears not to reach could have been declared.
+  // A candidate the registry never saw cannot be judged on what it implements —
+  // the analysis simply does not hold it. Whether its NAME is resolvable is a
+  // different question, asked of the alias scope by the caller.
+  if (!registry.resolve(resolved)) return true;
+  return !registry.ancestryResolved(resolved);
+}
+
+/** {@link kindSatisfies} at every kind a slot accepts, rendered as messages.
+ *  The acceptance rule is not restated here — only what to say when it fails,
+ *  which needs the slot's alternatives and the target's flavour. */
 function checkKind(
   kind: string,
   entry: RefFieldEntry,
@@ -24,23 +72,30 @@ function checkKind(
   aliases: AliasResolver,
 ): string[] {
   const resolved = aliases.resolveKind(kind) ?? kind;
+  // A qualified kind whose prefix names no import in this scope is a bad NAME
+  // rather than a bad type — `{kind: NotAnAlias.Script}` where only `Lib` is
+  // imported — and this check is the only place it surfaces, so it is never
+  // waved through as partial context. Asked of the resolver, which reports
+  // `unknown` for exactly that case: a kind reached through a DECLARED alias
+  // resolves (`ok`) even when the target's definitions are not loaded, and a
+  // gated one says so separately.
+  const unknownAlias =
+    kind.includes(".") &&
+    aliases.resolveKindResult(kind).status === "unknown" &&
+    // …and the registry does not hold it under the name as written either. A
+    // manifest may carry a canonical `<module>.<Kind>`, which no alias resolves
+    // and which is nonetheless perfectly identified.
+    registry.resolve(resolved) === undefined;
   const errors: string[] = [];
   for (const refStr of entry.refs) {
     const targetKind = registry.resolveRef(refStr);
     if (!targetKind) return [];
     const targetDef = registry.resolve(targetKind);
     if (!targetDef) return [];
-    // Liskov substitutability: a value satisfies the slot when it transitively
-    // extends the target kind, or — for a CONCRETE target — IS that kind.
-    // `getByExtends` is the same transitive subtype index for abstract and
-    // concrete targets alike; an abstract is satisfied only by an implementer,
-    // never by the abstract kind itself (which is non-instantiable).
-    if (targetDef.kind !== "Telo.Abstract" && resolved === targetKind) return [];
+    if (!unknownAlias && kindSatisfies(resolved, targetKind, registry)) return [];
     const subtypes = registry.getByExtends(targetKind);
     const subtypeKinds = new Set(subtypes.map((d) => `${d.metadata.module}.${d.metadata.name}`));
-    if (subtypeKinds.has(resolved)) return [];
     if (targetDef.kind === "Telo.Abstract") {
-      if (subtypes.length === 0) return []; // partial context — no implementations loaded yet
       // Suggest only what an author can actually wire: with abstract-extends-
       // abstract real (Telo.Executable over Invocable/Runnable), the transitive
       // subtype list contains abstracts, which are non-instantiable and would
@@ -48,9 +103,16 @@ function checkKind(
       const concrete = subtypes
         .filter((d) => d.kind !== "Telo.Abstract")
         .map((d) => `${d.metadata.module}.${d.metadata.name}`);
-      const options = (concrete.length > 0 ? concrete : [...subtypeKinds]).join(", ");
+      const options = concrete.length > 0 ? concrete : [...subtypeKinds];
+      // With nothing loaded that implements the target there is no list to
+      // offer, so the message says what this kind IS instead — which is the
+      // half the author can act on ("it declares 'Telo.Invocable'" points
+      // straight at a boot target that should have been an invoke step).
+      const declared = registry.resolve(resolved)?.capability;
       errors.push(
-        `'${kind}' does not implement '${targetKind}' (known implementations: ${options})`,
+        options.length > 0
+          ? `'${kind}' does not implement '${targetKind}' (known implementations: ${options.join(", ")})`
+          : `'${kind}' does not implement '${targetKind}'${declared ? ` — it declares '${declared}'` : ""}`,
       );
     } else {
       const options = subtypeKinds.size > 0 ? ` or a subtype (${[...subtypeKinds].join(", ")})` : "";
@@ -101,7 +163,7 @@ export function validateReferences(
   // Group manifests by name to detect collisions. Two subtleties:
   //
   //   1. Some analyzer hosts emit the SAME physical document twice through
-  //      their pipeline — e.g. the telo-editor's `toAnalysisManifests` walks
+  //      their pipeline — e.g. telo studio's `toAnalysisManifests` walks
   //      each workspace module's documents independently, and a file
   //      reachable from two angles (entry module + `include:` partial)
   //      shows up twice. The fingerprint includes `sourceLine` so identical
@@ -293,6 +355,13 @@ export function validateReferences(
         if (typeof val !== "object") return;
         const refVal = val as Record<string, unknown>;
 
+        // A value the slot's own union describes is a value, not a reference —
+        // the same narrowing `validateReferenceForms` applies, through the same
+        // function, because it has to be applied here too: an OBJECT-shaped value
+        // branch would otherwise reach the structural check below and be reported
+        // as a reference missing 'kind' and 'name'.
+        if (satisfiesValueBranch(val, entry.valueBranches, registry)) return;
+
         // Skip inline resources — Phase 2 normalization hasn't run yet.
         if (isInlineResource(refVal)) return;