@telorun/analyzer 0.72.0 → 0.74.0

package/src/validate-scope-reach.ts

@@ -0,0 +1,213 @@
+import type { ResourceDefinition, ResourceManifest } from "@telorun/sdk";
+import { walkCelExpressions } from "@telorun/templating";
+import type { AliasResolver } from "./alias-resolver.js";
+import type { DefinitionRegistry } from "./definition-registry.js";
+import { isForwardedDeclaration } from "./forwarded-declaration.js";
+import { definitionInScope } from "./module-alias-scope.js";
+import { isRefEntry, resolveFieldEntries } from "./reference-field-map.js";
+import {
+  declaredScopes,
+  isScopeMember,
+  outsideScopesOf,
+  scopeEncloses,
+  type DeclaredScope,
+  type OutsideScope,
+} from "./scope-declarations.js";
+import { forEachStep, stepBodiesOf } from "./step-bodies.js";
+import { DiagnosticSeverity, type AnalysisDiagnostic } from "./types.js";
+
+const SOURCE = "telo-analyzer";
+
+const DECLARATION_KINDS = new Set([
+  "Telo.Definition",
+  "Telo.Abstract",
+  "Telo.Application",
+  "Telo.Library",
+  "Telo.Import",
+]);
+
+/**
+ * `SCOPED_NAME_OUT_OF_REACH` — a declaration written inside a scope's region but
+ * created outside the scope (see {@link OutsideScope}) naming one of the scope's
+ * resources.
+ *
+ * Written there, the name reads as reachable — the scope's names shadow the
+ * module's in its regions — while at run time it resolves to nothing, or to a
+ * module-level resource that merely shares it. Reported at the reference, in
+ * each spelling a name can be read in:
+ *
+ *  - a `!ref` sentinel, anywhere — the tag is unambiguous;
+ *  - a resolved `{kind, name}`, but ONLY where the declaring kind says a
+ *    reference is: a reference slot of its field map, or a step's dispatch slot.
+ *    An object that merely has those keys is data;
+ *  - `resources.<name>` in a CEL expression.
+ *
+ * Lexical: a scope declared on the way from the out-of-reach declaration down to
+ * the reference — found through the kinds' own scope slots — shadows the name
+ * again, since that one IS created around it. Entry-module-scoped: a
+ * dependency's code is its own analysis's to report.
+ *
+ * Browser-safe.
+ */
+export function validateScopedNameReach(
+  manifests: ResourceManifest[],
+  registry: DefinitionRegistry,
+  aliases: AliasResolver,
+  aliasesByModule: Map<string, AliasResolver>,
+  rootModules: ReadonlySet<string>,
+  /** Member-access chains of a CEL expression — the analyzer's own parse. */
+  accessChains: (expression: string) => string[][],
+): AnalysisDiagnostic[] {
+  const out: AnalysisDiagnostic[] = [];
+
+  for (const root of manifests) {
+    if (!root.kind || DECLARATION_KINDS.has(root.kind) || isForwardedDeclaration(root)) continue;
+    const meta = root.metadata as { name?: unknown; module?: unknown; source?: unknown } | undefined;
+    if (typeof meta?.name !== "string") continue;
+    const module = typeof meta.module === "string" ? meta.module : undefined;
+    if (module && !rootModules.has(module)) continue;
+
+    const resource = { kind: root.kind, name: meta.name };
+    const filePath = typeof meta.source === "string" ? meta.source : undefined;
+    const report = (path: string, name: string, scope: OutsideScope) =>
+      out.push({
+        severity: DiagnosticSeverity.Error,
+        code: "SCOPED_NAME_OUT_OF_REACH",
+        source: SOURCE,
+        message:
+          `${scope.ownerKind}/${scope.ownerName}: '${name}' is declared in '${scope.field}:', but ` +
+          `the inline declaration referencing it is created where '${scope.ownerName}' is ` +
+          `declared, outside that scope, so the reference cannot reach it. Declare the ` +
+          `referencing resource under '${scope.field}:' with a name of its own and point at it ` +
+          `with '!ref'.`,
+        data: { resource, filePath, path },
+      });
+
+    /** A declaration's kind, field map and scopes, read in its module's aliases. */
+    const shape = (declaration: ResourceManifest) => {
+      const view =
+        module !== undefined && typeof declaration.metadata?.module !== "string"
+          ? ({ ...declaration, metadata: { ...declaration.metadata, module } } as ResourceManifest)
+          : declaration;
+      const fieldMap = registry.expandedFieldMapForResource(view, aliases, aliasesByModule);
+      const definition = definitionInScope<ResourceDefinition>(
+        registry,
+        view.kind,
+        view.metadata,
+        aliases,
+        aliasesByModule,
+      );
+      return {
+        fieldMap,
+        scopes: declaredScopes(declaration as Record<string, unknown>, fieldMap),
+        schema: registry.effectiveSchemaOf(definition) as Record<string, any> | undefined,
+      };
+    };
+
+    const check = (
+      declaration: ResourceManifest,
+      prefix: string,
+      reach: ReadonlyMap<string, OutsideScope>,
+      shadowed: ReadonlySet<string>,
+    ): void => {
+      const stamped = outsideScopesOf(declaration);
+      const nextReach = new Map(reach);
+      const nextShadowed = new Set(shadowed);
+      for (const scope of stamped) {
+        for (const name of scope.names) {
+          nextReach.set(name, scope);
+          nextShadowed.delete(name);
+        }
+      }
+      const { fieldMap, scopes, schema } = shape(declaration);
+      for (const scope of scopes) {
+        for (const member of scope.declarations) {
+          if (isScopeMember(member)) nextShadowed.add(member.metadata.name);
+        }
+      }
+
+      const at = (path: string) => (prefix ? (path ? `${prefix}.${path}` : prefix) : path);
+      const test = (name: string | undefined, path: string) => {
+        if (name === undefined || nextShadowed.has(name)) return;
+        const scope = nextReach.get(name);
+        if (scope) report(at(path), name, scope);
+      };
+      const inScopeArray = (path: string) =>
+        scopes.some((scope: DeclaredScope) => scopeEncloses({ ...scope, regions: [scope.path] }, path));
+
+      // Tagged `!ref`s and CEL, anywhere but the declaration's own metadata and
+      // scope arrays (their members are checked below, with their own shadowing).
+      walkCelExpressions(declaration, "", (source, path, engine) => {
+        if (path === "metadata" || path.startsWith("metadata.") || inScopeArray(path)) return;
+        if (engine === "ref") {
+          test(localName(source), path);
+        } else if (engine === "cel") {
+          for (const chain of accessChains(source)) {
+            if (chain[0] === "resources" && chain.length > 1) test(chain[1], path);
+          }
+        }
+      });
+
+      // A resolved reference, where the kind declares one.
+      if (fieldMap) {
+        for (const [fieldPath, entry] of fieldMap) {
+          if (!isRefEntry(entry)) continue;
+          for (const { value, path } of resolveFieldEntries(declaration, fieldPath)) {
+            if (inScopeArray(path)) continue;
+            test(resolvedLocalName(value), path);
+          }
+        }
+      }
+      if (schema) {
+        for (const body of stepBodiesOf(declaration as Record<string, unknown>, schema)) {
+          forEachStep(body, schema, (step, stepPath) =>
+            test(resolvedLocalName(step[body.invokeField]), `${stepPath}.${body.invokeField}`),
+          );
+        }
+      }
+
+      for (const scope of scopes) {
+        scope.declarations.forEach((member, i) => {
+          if (isScopeMember(member)) {
+            check(member, at(`${scope.path}[${i}]`), nextReach, nextShadowed);
+          }
+        });
+      }
+    };
+
+    /** Only a stamped declaration can hold an out-of-reach reference; the rest
+     *  is searched through the scope arrays that can hold one. */
+    const visit = (declaration: ResourceManifest, prefix: string): void => {
+      if (outsideScopesOf(declaration).length > 0) {
+        check(declaration, prefix, new Map(), new Set());
+        return;
+      }
+      for (const scope of shape(declaration).scopes) {
+        scope.declarations.forEach((member, i) => {
+          if (!isScopeMember(member)) return;
+          visit(member, `${prefix ? `${prefix}.` : ""}${scope.path}[${i}]`);
+        });
+      }
+    };
+
+    visit(root, "");
+  }
+
+  return out;
+}
+
+/** The local name a `!ref` source names, or undefined for a cross-module one. */
+function localName(source: string): string | undefined {
+  const dot = source.indexOf(".");
+  if (dot === -1) return source;
+  return source.slice(0, dot) === "Self" ? source.slice(dot + 1) : undefined;
+}
+
+/** The local name a resolved `{kind, name, alias?}` reference names. */
+function resolvedLocalName(value: unknown): string | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+  const ref = value as { kind?: unknown; name?: unknown; alias?: unknown };
+  if (typeof ref.kind !== "string" || typeof ref.name !== "string") return undefined;
+  if (typeof ref.alias === "string" && ref.alias !== "Self") return undefined;
+  return ref.name;
+}

package/src/validate-source-entries.ts

@@ -0,0 +1,120 @@
+import type { ResourceManifest } from "@telorun/sdk";
+
+import { moduleDocumentClaims } from "./module-file-claims.js";
+import {
+  crossLayerSourceLinks,
+  stageableFiles,
+  unclaimedSourceEntries,
+} from "./module-named-files.js";
+import { normalizeNativePath, readNativeEntries } from "./native-entries.js";
+import { readModuleSources } from "./source-entries.js";
+import { DiagnosticSeverity, type AnalysisDiagnostic } from "./types.js";
+
+const SOURCE = "telo-analyzer";
+
+/**
+ * The strict half of `source-entries.ts`: what `telo check` reports about a
+ * module doc's `sources:` block.
+ *
+ * Every rule the block alone decides is a reader problem, reported here under
+ * its own code. This adds the rules that need the rest of the module or that
+ * only publish enforces: an entry must stage a file the manifest names, a link
+ * ships in its target's layer, and every file entry and every build carries its
+ * pin. Shape errors are left to the owner doc's JSON Schema.
+ *
+ * Entry-module-scoped: a dependency's block is not the consumer's to fix.
+ */
+export function validateSourceEntries(
+  manifests: ResourceManifest[],
+  entryModules?: ReadonlySet<string>,
+): AnalysisDiagnostic[] {
+  const out: AnalysisDiagnostic[] = [];
+  for (const manifest of manifests) {
+    if (manifest.kind !== "Telo.Application" && manifest.kind !== "Telo.Library") continue;
+    const metadata = (manifest.metadata ?? {}) as Record<string, unknown>;
+    const name = typeof metadata.name === "string" ? metadata.name : undefined;
+    const owned =
+      entryModules === undefined ||
+      (typeof metadata.module === "string"
+        ? entryModules.has(metadata.module)
+        : name === undefined || entryModules.has(name));
+    if (!owned) continue;
+
+    const label = `${manifest.kind}/${name ?? "(unnamed)"}`;
+    const report = (code: string, path: string, message: string) =>
+      out.push({
+        severity: DiagnosticSeverity.Error,
+        code,
+        source: SOURCE,
+        message: `${label}: ${message}`,
+        data: {
+          resource: { kind: manifest.kind, name },
+          filePath: typeof metadata.source === "string" ? metadata.source : undefined,
+          path,
+        },
+      });
+
+    const { sources, problems } = readModuleSources(manifest);
+    for (const problem of problems) {
+      if (problem.code === "SHAPE") continue;
+      report(problem.code, problem.path, problem.message);
+    }
+    if (sources.length === 0) continue;
+
+    for (const source of sources) {
+      if (source.build && source.build.inputs === undefined) {
+        report(
+          "SOURCE_BUILD_UNPINNED",
+          `sources.${source.name}.build`,
+          `source '${source.name}' names the crate its files are built from but records no build ` +
+            `inputs, so a later edit to that crate cannot be caught — run \`telo release stage ` +
+            `--pin\` after building its files. \`telo release check\` and publish refuse it.`,
+        );
+      }
+      for (const entry of source.entries) {
+        if (entry.kind !== "file" || entry.pin) continue;
+        report(
+          "SOURCE_ENTRY_UNPINNED",
+          `sources.${source.name}.entries.${entry.key}`,
+          `source '${source.name}' entry '${entry.key}' carries no pin (sha256 and executable), so ` +
+            `nothing can verify the file it stages: a kernel refuses to read it and publish refuses ` +
+            `to ship it — run \`telo release stage --pin\`.`,
+        );
+      }
+    }
+
+    const moduleName = typeof metadata.module === "string" ? metadata.module : name;
+    const stageable = stageableFiles(
+      readNativeEntries(manifest).entries,
+      moduleDocumentClaims(manifests, moduleName),
+    );
+    for (const { source, entry, layer, targetLayer } of crossLayerSourceLinks(sources, stageable)) {
+      report(
+        "SOURCE_LINK_TARGET_UNRESOLVED",
+        `sources.${source.name}.entries.${entry.key}.target`,
+        `source '${source.name}' entry '${entry.key}': the link ships in the ${layer} layer, but ` +
+          `its target '${entry.resolved}' ships in the ${targetLayer} layer. A runtime extracts ` +
+          `only the layers it needs, so the link would dangle — point it at a file of its own layer.`,
+      );
+    }
+    // A `native:` entry with an unrelated problem still names its path; reported
+    // once, as that problem, rather than again as an unclaimed source entry.
+    const unreadNative = new Set<string>();
+    const native = (manifest as { native?: unknown }).native;
+    for (const entry of Array.isArray(native) ? native : []) {
+      const path = (entry as { path?: unknown } | null)?.path;
+      const verdict = typeof path === "string" ? normalizeNativePath(path.trim()) : undefined;
+      if (verdict && "path" in verdict) unreadNative.add(verdict.path);
+    }
+    for (const { source, entry } of unclaimedSourceEntries(sources, stageable, unreadNative)) {
+      report(
+        "SOURCE_ENTRY_UNCLAIMED",
+        `sources.${source.name}.entries.${entry.key}`,
+        `source '${source.name}' entry '${entry.key}': nothing in the module names '${entry.path}' ` +
+          `— no native: entry's path, no platform-qualified controller candidate's path=, and ` +
+          `none of the source's notices. Name the file where it is used, or remove the entry.`,
+      );
+    }
+  }
+  return out;
+}

package/src/validate-template-body.ts

@@ -0,0 +1,274 @@
+import { nearestName } from "./nearest-name.js";
+import type { ResourceManifest } from "@telorun/sdk";
+import { isRefSentinel, isTaggedSentinel } from "@telorun/templating";
+import type { AliasResolver, ModuleScopes } from "./alias-resolver.js";
+import type { DefinitionRegistry } from "./definition-registry.js";
+import { refSentinelTarget } from "./ref-sentinel-target.js";
+import { isRefEntry, resolveFieldEntries, satisfiesValueBranch } from "./reference-field-map.js";
+import { templateBodies } from "./template-body.js";
+import { DiagnosticSeverity, DiagnosticTag, type AnalysisDiagnostic } from "./types.js";
+
+const SOURCE = "telo-analyzer";
+
+/** The four slots a `Telo.Definition` names its dispatch target in.
+ *
+ *  WHAT THE TARGET'S CAPABILITY IS IS DELIBERATELY NOT CHECKED. The kernel tests
+ *  METHOD PRESENCE at dispatch (`entry.instance?.invoke`), so a declared
+ *  capability says nothing about whether a dispatch works — the same structural
+ *  -versus-nominal split that keeps `use` uncross-constrained against a slot's
+ *  target. A check here read `Run.Sequence`'s `capability: Telo.Runnable` and
+ *  rejected `Ai.Buffered`, a shipping module whose sequence implements `invoke()`
+ *  over an inputs/outputs contract and dispatches correctly. Trimming the refused
+ *  set would only move that: any controller may expose a method its capability
+ *  does not name, and a template body is exactly where that is done on purpose. */
+const DISPATCH_SLOTS = ["invoke", "run", "provide", "mount"] as const;
+
+/**
+ * A TEMPLATE BODY IS WRITTEN LIKE EVERY OTHER MANIFEST, AND CHECKED LIKE ONE.
+ *
+ * A `Telo.Definition` is in both reference skip sets — its body holds
+ * declarations of OTHER kinds, and its dispatch slots carry no `x-telo-ref` — so
+ * no reference pass reached it, and each rule about it was added per construct:
+ * `provide:` and `mount:` had a target check for the `{ kind, name }` object
+ * form, `!ref` had one that switched itself off for any definition with a
+ * CEL-named entry, and `invoke:` / `run:` had none. What was tagged was caught
+ * and what was a plain name was resolved by the kernel alone. This pass is the
+ * one reader of a body's reference surface, and it rests on one spelling:
+ *
+ *  - every `resources:` entry is named by a LITERAL (`TEMPLATE_ENTRY_NAME_DYNAMIC`).
+ *    Each instance of a template owns its children in a child context of its
+ *    own, so a per-instance suffix (`self.name + '-query'`) buys nothing — and a
+ *    `!ref` is looked up verbatim, so a CEL-named sibling is one nothing can name;
+ *  - a dispatch slot is `!ref <entry>` naming an entry
+ *    (`TEMPLATE_DISPATCH_UNKNOWN`); the legacy spellings are deprecated rather
+ *    than refused, since published artifacts carry them. What the target's
+ *    CAPABILITY is stays unchecked — see `DISPATCH_SLOTS`;
+ *  - a reference slot INSIDE an entry follows the rule every other slot does —
+ *    `!ref` or an inline declaration, never `{ kind, name }` or a bare string
+ *    (`INVALID_REFERENCE_FORM`) — and a bare `!ref` names a sibling or a
+ *    resource of the defining module (`TEMPLATE_REF_UNKNOWN`). Slots are found
+ *    through the nested kind's own field map, resolved in the DEFINING module's
+ *    alias scope, since that is where the body's kinds are written.
+ *
+ * Entry-module-scoped, like every other declaration check: a published
+ * dependency's template body is not the consumer's to fix. Browser-safe.
+ */
+export function validateTemplateBody(
+  manifests: ResourceManifest[],
+  registry: DefinitionRegistry,
+  aliases: AliasResolver,
+  aliasesByModule: Map<string, AliasResolver>,
+  rootModules: ReadonlySet<string>,
+): AnalysisDiagnostic[] {
+  const out: AnalysisDiagnostic[] = [];
+  const scopes: ModuleScopes = { aliasesByModule, rootModules };
+
+  // A definition forwarded from an imported library is that library's to fix;
+  // the imports name them (the `validate-extends` rule).
+  const importedModules = new Set<string>();
+  // Every named instance, by declaring module — what a body's bare `!ref` may
+  // reach beside its siblings. A manifest with no stamp belongs to the entry.
+  const instancesByModule = new Map<string | undefined, Set<string>>();
+  for (const m of manifests) {
+    const name = m.metadata?.name;
+    if (typeof name !== "string") continue;
+    if (m.kind === "Telo.Import") {
+      const resolved = (m.metadata as { resolvedModuleName?: string }).resolvedModuleName;
+      if (resolved) importedModules.add(resolved);
+      continue;
+    }
+    if (m.kind === "Telo.Definition" || m.kind === "Telo.Abstract") continue;
+    if (m.kind === "Telo.Library" || m.kind === "Telo.Application") continue;
+    const mod = (m.metadata as { module?: string } | undefined)?.module;
+    let set = instancesByModule.get(mod);
+    if (!set) instancesByModule.set(mod, (set = new Set()));
+    set.add(name);
+  }
+
+  for (const m of manifests) {
+    if (m.kind !== "Telo.Definition") continue;
+    const meta = m.metadata as { name?: string; module?: string; source?: string } | undefined;
+    const name = meta?.name;
+    if (!name) continue;
+    if (meta?.module && importedModules.has(meta.module)) continue;
+
+    const bodies = (m as Record<string, unknown>).resources;
+    const resourceRef = { kind: m.kind, name };
+    const filePath = meta?.source;
+    const label = `${m.kind}/${name}`;
+    const report = (code: string, path: string, message: string, fix?: string) =>
+      out.push({
+        severity: DiagnosticSeverity.Error,
+        code,
+        source: SOURCE,
+        message: `${label}: ${message}`,
+        data: {
+          resource: resourceRef,
+          filePath,
+          path,
+          ...(fix ? { fix: { replacement: fix } } : {}),
+        },
+      });
+
+    /** A spelling the kernel still READS. Warning-grade because refusing it
+     *  would break every app pinning a version that carries it, and tagged so an
+     *  editor strikes it through rather than merely colouring it — the
+     *  `DEPRECATED_KIND` shape, for the same reason. */
+    const deprecate = (code: string, path: string, message: string) =>
+      out.push({
+        severity: DiagnosticSeverity.Warning,
+        code,
+        source: SOURCE,
+        message: `${label}: ${message}`,
+        tags: [DiagnosticTag.Deprecated],
+        data: { resource: resourceRef, filePath, path },
+      });
+
+    const entries = Array.isArray(bodies) ? bodies : [];
+    const siblings: string[] = [];
+    let anyDynamic = false;
+    entries.forEach((entry, i) => {
+      const entryName = (entry as { metadata?: { name?: unknown } } | undefined)?.metadata?.name;
+      if (typeof entryName === "string" && !entryName.includes("${{")) {
+        siblings.push(entryName);
+        return;
+      }
+      if (entryName === undefined) return;
+      anyDynamic = true;
+      deprecate(
+        "DEPRECATED_TEMPLATE_ENTRY_NAME",
+        `resources[${i}].metadata.name`,
+        `a 'resources:' entry named by ${describeDynamic(entryName)} is deprecated — name it ` +
+          `with a literal and dispatch to it with '!ref'. Each instance of a template owns its ` +
+          `children in a child context of its own, so a per-instance suffix buys nothing, and a ` +
+          `'!ref' is looked up verbatim, so nothing can name a computed entry. While one is ` +
+          `present the target checks below are switched off for this kind.`,
+      );
+    });
+
+    // Siblings PLUS the declaring module's own resources, because that is what
+    // the runtime resolves at a reference slot: a body's `!ref` is stamped
+    // `{kind, name}` with an empty kind for a non-sibling, and Phase-5 injection
+    // dispatches by NAME and recovers the kind from the instance it finds — so
+    // `client: !ref moduleClient` in a body reaches the module-level client and
+    // works. (A step's `invoke:` is a different path that does NOT: see the
+    // `resources` note in `validate-template-body`'s own tests.)
+    const reachable = new Set([
+      ...siblings,
+      ...(instancesByModule.get(meta?.module) ?? []),
+    ]);
+
+    // --- dispatch slots ---
+    for (const slot of DISPATCH_SLOTS) {
+      const value = (m as Record<string, unknown>)[slot];
+      if (value == null) continue;
+      if (!isRefSentinel(value)) {
+        deprecate(
+          "DEPRECATED_TEMPLATE_DISPATCH_FORM",
+          slot,
+          `'${slot}:' written as ${describeDispatchValue(value)} is deprecated — ` +
+            `write '!ref <entry>', the spelling every other reference uses. ` +
+            `Available: ${siblings.join(", ") || "(none)"}.`,
+        );
+        continue;
+      }
+      const source = value.source;
+      const target = source.startsWith("Self.") ? source.slice("Self.".length) : source;
+      if (siblings.includes(target)) continue;
+      // A dynamic sibling has already been reported, and might be the one
+      // meant — a second diagnostic about the same line would be noise.
+      if (anyDynamic) continue;
+      const suggestion = nearestName(target, siblings);
+      report(
+        "TEMPLATE_DISPATCH_UNKNOWN",
+        slot,
+        `'${slot}: !ref ${source}' names no entry in 'resources:'. ` +
+          `Available: ${siblings.join(", ") || "(none)"}.` +
+          (suggestion ? ` Did you mean '${suggestion}'?` : ""),
+        suggestion,
+      );
+    }
+
+    // --- reference slots inside each entry ---
+    for (const body of templateBodies(m, registry, aliases, scopes)) {
+      const kind = body.manifest.kind;
+      const fieldMap = registry.expandedFieldMapForResource(
+        { ...body.manifest, metadata: { ...(body.manifest.metadata ?? {}), module: meta?.module } },
+        aliases,
+        aliasesByModule,
+      );
+      if (!fieldMap) continue;
+      for (const [fieldPath, entry] of fieldMap) {
+        if (!isRefEntry(entry)) continue;
+        for (const site of resolveFieldEntries(body.manifest, fieldPath)) {
+          const value = site.value;
+          if (value == null) continue;
+          const path = `${body.prefix}.${site.path}`;
+          if (isTaggedSentinel(value)) {
+            const target = refSentinelTarget(value);
+            if (!target) continue;
+            const { alias, name: refName } = target;
+            if (alias && alias !== "Self") continue;
+            if (reachable.has(refName)) continue;
+            const suggestion = nearestName(refName, [...reachable]);
+            report(
+              "TEMPLATE_REF_UNKNOWN",
+              path,
+              `'${site.path}: !ref ${value.source}' on the ${kind} entry names no sibling ` +
+                `'resources:' entry and no resource of this module. ` +
+                `Siblings: ${siblings.filter((s) => s !== body.manifest.metadata?.name).join(", ") || "(none)"}.` +
+                (suggestion ? ` Did you mean '${suggestion}'?` : ""),
+              suggestion,
+            );
+            continue;
+          }
+          const hasValueBranch = (entry.valueBranches?.length ?? 0) > 0;
+          if (hasValueBranch && typeof value !== "object") continue;
+          if (satisfiesValueBranch(value, entry.valueBranches, registry)) continue;
+          if (typeof value === "string") {
+            if (value.includes("${{")) continue;
+            report(
+              "INVALID_REFERENCE_FORM",
+              path,
+              `string reference at '${site.path}' on the ${kind} entry → '${value}' is not ` +
+                `supported; write it as '!ref ${value}'`,
+            );
+            continue;
+          }
+          if (value && typeof value === "object" && !Array.isArray(value)) {
+            const obj = value as Record<string, unknown>;
+            if (typeof obj.kind === "string" && obj.name !== undefined) {
+              report(
+                "INVALID_REFERENCE_FORM",
+                path,
+                `object reference '{ kind, name }' at '${site.path}' on the ${kind} entry is ` +
+                  `not supported; write it as '!ref ${describeRefName(obj.name)}'`,
+              );
+            }
+          }
+        }
+      }
+    }
+  }
+
+  return out;
+}
+
+function describeDynamic(name: unknown): string {
+  if (isTaggedSentinel(name)) return `the expression '${name.source}'`;
+  if (typeof name === "string") return `the template '${name}'`;
+  return `a ${typeof name}`;
+}
+
+function describeDispatchValue(value: unknown): string {
+  if (isTaggedSentinel(value)) return `a '!${value.engine}' expression`;
+  if (typeof value === "string") return `the string '${value}'`;
+  if (value && typeof value === "object" && "name" in value) return "the '{ kind, name }' object form";
+  return `a ${typeof value}`;
+}
+
+function describeRefName(name: unknown): string {
+  if (typeof name === "string") return name;
+  if (isTaggedSentinel(name)) return "<entry>";
+  return String(name);
+}