@telorun/analyzer 0.42.0 → 0.44.0

package/src/resolve-schema-ref-kinds.ts

@@ -0,0 +1,118 @@
+import type { ResourceManifest } from "@telorun/sdk";
+import type { AliasResolver } from "./alias-resolver.js";
+
+const REF_ANNOTATION = "x-telo-ref";
+
+/** Why an `x-telo-ref` constraint did not canonicalize.
+ *
+ *  - `legacy`  — the deprecated `<namespace>/<module>#<Kind>` identity form,
+ *                still resolved through the identity table.
+ *  - `unknown` — the prefix is not an alias in the declaring module's scope: a
+ *                typo, a missing `imports:` entry — or a value that was already
+ *                canonical, which the caller separates by asking the registry.
+ *  - `gated`   — the alias is known and the target owns the kind, but its
+ *                `exports.kinds` does not list it. */
+export type RefConstraintReason = "legacy" | "unknown" | "gated";
+
+/** An `x-telo-ref` constraint that did not canonicalize. */
+export interface RefConstraintIssue {
+  /** The constraint string exactly as authored. */
+  ref: string;
+  /** Dotted path to the annotated schema node within the doc, e.g.
+   *  `schema.properties.store`. Points the author at the slot, not just the doc. */
+  path: string;
+  /** The `Telo.Definition` / `Telo.Abstract` doc that declares the slot. */
+  manifest: ResourceManifest;
+  reason: RefConstraintReason;
+  /** For `gated`: the target module and the kinds it does export. */
+  gate?: { module: string; exported: string[] };
+  /** Aliases the declaring scope does know — the "did you mean" material for
+   *  an `unknown` prefix. */
+  knownAliases?: string[];
+}
+
+/** True for the legacy identity form, which is split on `#` by the identity table. */
+export function isLegacyRefIdentity(ref: string): boolean {
+  return ref.includes("#");
+}
+
+/**
+ * Rewrites the `x-telo-ref` constraints on one definition doc from the alias
+ * form (`KvStore.Store`, `Self.Store`, `Telo.Invocable`) to the canonical
+ * `<module>.<Kind>` key the definition registry is keyed by.
+ *
+ * `resolver` must be the scope of the module that DECLARES the definition, not
+ * the consumer's: an imported library names its dependencies by its own aliases.
+ * This mirrors how `extends:` and `capability:` are pre-resolved before
+ * registration, so the registry never needs module context to answer a ref query.
+ *
+ * Every constraint that does not canonicalize is returned, tagged with why. That
+ * matters more than it looks: an unresolved constraint leaves a string naming no
+ * registered kind, and the reference check treats an unknown target as partial
+ * context and skips it — so an unreported one would silently let the slot accept
+ * anything. The authored value is left in place either way, so a diagnostic
+ * quotes what the author actually wrote.
+ *
+ * An `unknown` result also covers an already-canonical value (`kv-store.Store`
+ * names a module, not an alias), which is what keeps the rewrite idempotent —
+ * the caller drops those by checking the definition registry once every kind is
+ * registered.
+ *
+ * The walk covers the whole doc rather than a fixed field list: a constraint can
+ * sit in `schema`, `inputType`, `outputType`, or a `$defs` entry nested in any of
+ * them, and rewriting one that appears in a template body's inline schema is
+ * correct too.
+ */
+export function resolveSchemaRefKinds(
+  definition: ResourceManifest,
+  resolver: Pick<AliasResolver, "resolveKindResult" | "knownAliases">,
+): RefConstraintIssue[] {
+  const issues: RefConstraintIssue[] = [];
+
+  const record = (ref: string, path: string): void => {
+    if (isLegacyRefIdentity(ref)) {
+      issues.push({ ref, path, manifest: definition, reason: "legacy" });
+      return;
+    }
+    const result = resolver.resolveKindResult(ref);
+    if (result.status === "ok") return;
+    issues.push(
+      result.status === "gated"
+        ? {
+            ref,
+            path,
+            manifest: definition,
+            reason: "gated",
+            gate: { module: result.module, exported: result.exported },
+          }
+        : {
+            ref,
+            path,
+            manifest: definition,
+            reason: "unknown",
+            knownAliases: resolver.knownAliases(),
+          },
+    );
+  };
+
+  const walk = (value: unknown, path: string): void => {
+    if (value === null || typeof value !== "object") return;
+    if (Array.isArray(value)) {
+      value.forEach((item, i) => walk(item, `${path}[${i}]`));
+      return;
+    }
+    const obj = value as Record<string, unknown>;
+    const ref = obj[REF_ANNOTATION];
+    if (typeof ref === "string" && ref) {
+      const result = isLegacyRefIdentity(ref) ? null : resolver.resolveKindResult(ref);
+      if (result?.status === "ok") obj[REF_ANNOTATION] = result.kind;
+      else record(ref, path);
+    }
+    for (const key of Object.keys(obj)) {
+      walk(obj[key], path ? `${path}.${key}` : key);
+    }
+  };
+
+  walk(definition, "");
+  return issues;
+}

package/src/sources/manifest-cache.ts

@@ -12,12 +12,20 @@ export const MANIFEST_CACHE_BASE_URL = "https://manifests.telo.sh";
  *  stores per version — `{ transport, host, path, version }` — so the tracker's
  *  write key and the editor's read key come from the same function and never
  *  drift. `path` is the slash-separated repo/module path (multi-segment OCI
- *  repos nest as prefixes). */
+ *  repos nest as prefixes), empty for a module addressed at a host's root. */
 export interface ManifestCacheCoords {
   transport: string;
   host: string;
   path: string;
-  version: string;
+  /** Omit only when the ref carries no version to key by — a direct `https://`
+   *  URL addresses exactly one file, so its path alone is already unambiguous.
+   *  Every ref whose grammar has a version segment must supply it, or two
+   *  versions of one module would collide on a single key. */
+  version?: string;
+  /** File within the version directory. Defaults to the module manifest, which
+   *  is the only file the hub's bucket stores; the local install cache also
+   *  holds each `include:` partial, which is named here. */
+  file?: string;
 }
 
 /** True for a segment that would corrupt or escape the cache key space. */
@@ -26,15 +34,25 @@ function invalidSegment(segment: string): boolean {
 }
 
 /** Deterministic cache key for one module version:
- *  `<transport>/<host>/<path…>/<version>/telo.yaml`. Returns `null` when any
- *  coordinate is empty or would traverse out of the key space. */
+ *  `<transport>/<host>/<path…>/<version>/<file>`, where `version` is omitted
+ *  when the coordinates carry none and `file` defaults to the module manifest.
+ *  Returns `null` when any coordinate is empty or would traverse out of the key
+ *  space. */
 export function manifestCacheKey(coords: ManifestCacheCoords): string | null {
-  const { transport, host, path, version } = coords;
-  const segments = [transport, host, ...path.split("/"), version];
-  if (segments.some(invalidSegment) || transport.includes("/") || host.includes("/") || version.includes("/")) {
+  const { transport, host, path, version, file } = coords;
+  const segments = [transport, host, ...(path ? path.split("/") : [])];
+  if (version !== undefined) segments.push(version);
+  segments.push(file ?? DEFAULT_MANIFEST_FILENAME);
+  if (
+    segments.some(invalidSegment) ||
+    transport.includes("/") ||
+    host.includes("/") ||
+    (version !== undefined && version.includes("/")) ||
+    (file !== undefined && file.includes("/"))
+  ) {
     return null;
   }
-  return `${segments.join("/")}/${DEFAULT_MANIFEST_FILENAME}`;
+  return segments.join("/");
 }
 
 /** Cache coordinates for an `oci://host/repo@tag` ref. Returns `null` when the

package/src/validate-nested-inline.ts

@@ -7,6 +7,7 @@ import {
   validateAgainstSchema,
 } from "./schema-compat.js";
 import { DiagnosticSeverity, type AnalysisDiagnostic } from "./types.js";
+import { collectValueSchemaIssues } from "./validate-value-schema.js";
 
 const SOURCE = "telo-analyzer";
 
@@ -39,6 +40,8 @@ export function validateNestedInlineResources(
   manifest: ResourceManifest,
   rootSchema: Record<string, any>,
   lookupDefinition: InlineDefinitionLookup,
+  /** Needed to resolve a `telo#Type` field a value slot is validated against. */
+  allManifests: Record<string, any>[] = [],
 ): AnalysisDiagnostic[] {
   const diagnostics: AnalysisDiagnostic[] = [];
   const resource = { kind: manifest.kind, name: manifest.metadata?.name as string };
@@ -87,7 +90,16 @@ export function validateNestedInlineResources(
         : {};
     const data = { ...inline, metadata: { name: "__inline__", ...existingMeta } };
     const substituted = substituteCelFields(data, effectiveSchema, effectiveSchema);
-    for (const issue of validateAgainstSchema(substituted, effectiveSchema)) {
+    // The same two passes the top-level resource loop runs, so a kind's
+    // guarantees don't depend on whether the author wrote it standalone or
+    // inline (under a step's `invoke:`, or in a `with:` scope). `data` carries
+    // the synthesized metadata; `x-telo-value-schema-from` reads sibling fields
+    // off the resource, which are present either way.
+    const inlineIssues = [
+      ...validateAgainstSchema(substituted, effectiveSchema),
+      ...collectValueSchemaIssues(data, schema, allManifests),
+    ];
+    for (const issue of inlineIssues) {
       diagnostics.push({
         severity: DiagnosticSeverity.Error,
         code: "SCHEMA_VIOLATION",

package/src/validate-value-schema.ts

@@ -0,0 +1,126 @@
+import { substituteCelFields, validateAgainstSchema, type SchemaIssue } from "./schema-compat.js";
+import { resolveTypeFieldToSchema } from "./validate-cel-context.js";
+
+/**
+ * `x-telo-value-schema-from: "<field>"` — the value written at the annotated
+ * node must satisfy the type declared at the resource's `<field>`.
+ *
+ * The motivating shape is a kind with ONE declared output contract and SEVERAL
+ * places that must each produce it — a decision table's rows, a switch's arms.
+ * Only the branch that wins at runtime gets checked there, so a mistyped branch
+ * ships and fails on the one input that selects it. This annotation checks every
+ * branch statically instead.
+ *
+ * Generic and topology-driven: the analyzer hardcodes no kind. Any definition
+ * with a `telo#Type` field and value-producing slots opts in by annotating those
+ * slots. `<field>` is resolved with the same `telo#Type` semantics as
+ * `inputType` / `outputType` everywhere else, so an inline
+ * `{ kind: Type.JsonSchema, schema: … }` and a named type reference both work.
+ *
+ * A field that resolves to no schema — the common case of an optional
+ * `outputType` left undeclared — is skipped, not reported: declaring the
+ * contract is what opts into the check.
+ */
+const ANNOTATION = "x-telo-value-schema-from";
+
+interface Annotation {
+  /** JSONPath-ish scope into the manifest, e.g. `$.choices[*].value`. */
+  scope: string;
+  /** Resource field naming the type to validate against, e.g. `outputType`. */
+  from: string;
+}
+
+/** Walk a definition schema collecting every `x-telo-value-schema-from`, in the
+ *  same scope form the CEL-context walker produces. */
+function collectAnnotations(schema: Record<string, any>, path: string): Annotation[] {
+  if (!schema || typeof schema !== "object") return [];
+  const out: Annotation[] = [];
+
+  const from = schema[ANNOTATION];
+  if (typeof from === "string" && from.length > 0) out.push({ scope: path, from });
+
+  if (schema.properties) {
+    for (const [key, value] of Object.entries(schema.properties as Record<string, any>)) {
+      out.push(...collectAnnotations(value, `${path}.${key}`));
+    }
+  }
+  if (schema.items && typeof schema.items === "object") {
+    out.push(...collectAnnotations(schema.items, `${path}[*]`));
+  }
+  for (const key of ["oneOf", "anyOf", "allOf"] as const) {
+    if (Array.isArray(schema[key])) {
+      for (const sub of schema[key]) out.push(...collectAnnotations(sub, path));
+    }
+  }
+  return out;
+}
+
+/** Expand a scope into the concrete values present in this manifest, carrying
+ *  each one's real path so a diagnostic points at the row the author wrote. */
+function resolveScopeValues(
+  manifest: Record<string, any>,
+  scope: string,
+): Array<{ path: string; value: unknown }> {
+  const stripped = scope.startsWith("$.") ? scope.slice(2) : scope;
+  if (!stripped) return [];
+
+  let frontier: Array<{ path: string; value: unknown }> = [{ path: "", value: manifest }];
+  // Segments look like `choices[*]` or `default` — a name plus optional wildcard.
+  for (const segment of stripped.split(".")) {
+    const wildcard = segment.endsWith("[*]");
+    const name = wildcard ? segment.slice(0, -3) : segment;
+    const next: Array<{ path: string; value: unknown }> = [];
+    for (const entry of frontier) {
+      const container = entry.value as Record<string, unknown> | undefined;
+      if (!container || typeof container !== "object") continue;
+      const child = container[name];
+      if (child === undefined) continue;
+      const childPath = entry.path ? `${entry.path}.${name}` : name;
+      if (!wildcard) {
+        next.push({ path: childPath, value: child });
+        continue;
+      }
+      if (!Array.isArray(child)) continue;
+      child.forEach((item, i) => next.push({ path: `${childPath}[${i}]`, value: item }));
+    }
+    frontier = next;
+    if (frontier.length === 0) break;
+  }
+  return frontier;
+}
+
+/**
+ * Validate every `x-telo-value-schema-from` slot in one resource.
+ *
+ * CEL leaves are replaced with schema-shaped placeholders before AJV runs
+ * (`substituteCelFields`), so an expression is accepted wherever its slot's
+ * declared type would be — a static pass cannot know what it evaluates to. What
+ * this DOES catch is structural disagreement that no runtime value can fix: a
+ * missing required property, an unknown property under
+ * `additionalProperties: false`, or a literal of the wrong type.
+ */
+export function collectValueSchemaIssues(
+  manifest: Record<string, any>,
+  defSchema: Record<string, any> | undefined,
+  allManifests: Record<string, any>[],
+): SchemaIssue[] {
+  if (!defSchema) return [];
+  const annotations = collectAnnotations(defSchema, "$");
+  if (annotations.length === 0) return [];
+
+  const issues: SchemaIssue[] = [];
+  for (const { scope, from } of annotations) {
+    const target = resolveTypeFieldToSchema(manifest[from], allManifests);
+    if (!target || typeof target !== "object") continue;
+
+    for (const { path, value } of resolveScopeValues(manifest, scope)) {
+      for (const issue of validateAgainstSchema(substituteCelFields(value, target), target)) {
+        issues.push({
+          message: `\`${path}\` does not satisfy the type declared at \`${from}\`: ${issue.message}`,
+          path: issue.path ? `${path}.${issue.path}` : path,
+        });
+      }
+    }
+  }
+  return issues;
+}