@olivervea/pipelines 2.0.0-beta.27 → 2.0.0-beta.29

package/src/describe/failure-handlers.ts

@@ -0,0 +1,34 @@
+import { isStep, type AnyStep } from '../core/steps.ts';
+import type { FailureHandlerNode } from '../builder/pipeline.ts';
+import type { ManifestT } from './manifest-schema.ts';
+import type { DescribeContext } from './context.ts';
+import { describeStep } from './step.ts';
+
+/** Describes the `onFailure` handlers; call after the stages, so their scopes can name the stage steps. */
+export function describeFailureHandlers(
+  ctx: DescribeContext,
+  handlers: readonly FailureHandlerNode[],
+): ManifestT['failureHandlers'] {
+  const stageStepNames = new Set(ctx.steps.keys());
+  const seen = new Map<string, AnyStep>();
+  return handlers
+    .map((fh) => {
+      if (!isStep(fh.step)) {
+        ctx.problems.push('onFailure: handler is not a step');
+        return undefined;
+      }
+      if (seen.get(fh.step.name) !== fh.step) ctx.registerStep(fh.step, 'onFailure');
+      seen.set(fh.step.name, fh.step);
+      const scope = fh.steps === null ? null : fh.steps.map((x) => x.name);
+      for (const n of scope ?? [])
+        if (!stageStepNames.has(n))
+          ctx.problems.push(
+            `onFailure(${fh.step.name}): '${n}' is not a step of this pipeline`,
+          );
+      return {
+        step: describeStep(ctx, { step: fh.step }, new Map(), true),
+        steps: scope,
+      };
+    })
+    .filter((x) => x !== undefined);
+}

package/src/describe/schemas.ts

@@ -0,0 +1,71 @@
+import { z } from 'zod';
+import { canonicalize } from '../util/canonical.ts';
+import type { ModelSchemasT } from './manifest-schema.ts';
+
+export type JsonSchema = Record<string, unknown>;
+
+function stripStrict(v: unknown): unknown {
+  if (Array.isArray(v)) return v.map(stripStrict);
+  if (v !== null && typeof v === 'object') {
+    const out: Record<string, unknown> = {};
+    for (const [k, x] of Object.entries(v))
+      if (!(k === 'additionalProperties' && x === false)) out[k] = stripStrict(x);
+    return out;
+  }
+  return v;
+}
+
+/** JSON Schema views of a zod schema. Throws if it is not representable (dates, transforms, …). */
+export function schemaViews(schema: z.ZodType): ModelSchemasT {
+  const view = (io: 'input' | 'output') => {
+    const js = z.toJSONSchema(schema, { io, target: 'draft-2020-12' }) as JsonSchema;
+    delete js.$schema; // constant noise; apiVersion pins the dialect
+    return canonicalize(js) as JsonSchema;
+  };
+  const output = view('output');
+  const input = view('input');
+  const same = JSON.stringify(stripStrict(output)) === JSON.stringify(input);
+  return same ? { output } : { output, input };
+}
+
+/** Whether `segments` lead to a field of a JSON Schema. */
+export function resolveField(
+  schema: JsonSchema | undefined,
+  segments: readonly string[],
+): boolean {
+  if (!schema) return false;
+  if (segments.length === 0) return true;
+  const [seg, ...rest] = segments as [string, ...string[]];
+  if (Array.isArray(schema.anyOf))
+    return (schema.anyOf as JsonSchema[]).some((b) => resolveField(b, segments));
+  if (Array.isArray(schema.oneOf))
+    return (schema.oneOf as JsonSchema[]).some((b) => resolveField(b, segments));
+  if (Array.isArray(schema.allOf))
+    return (schema.allOf as JsonSchema[]).some((b) => resolveField(b, segments));
+  const props = schema.properties as Record<string, JsonSchema> | undefined;
+  if (props && Object.hasOwn(props, seg)) return resolveField(props[seg], rest);
+  const extra = schema.additionalProperties;
+  if (extra && typeof extra === 'object') return resolveField(extra as JsonSchema, rest);
+  // A schema without type/properties/anyOf accepts anything (z.unknown / z.any).
+  return Object.keys(schema).every(
+    (k) => k === 'description' || k === 'title' || k === 'default',
+  );
+}
+
+export function literalValues(field: JsonSchema | undefined): unknown[] | undefined {
+  if (!field) return undefined;
+  if (Array.isArray(field.enum)) return field.enum as unknown[];
+  if (field.const !== undefined) return [field.const];
+  if (field.type === 'boolean') return [true, false];
+  const alts = (field.anyOf ?? field.oneOf) as JsonSchema[] | undefined;
+  if (Array.isArray(alts)) {
+    const all: unknown[] = [];
+    for (const a of alts) {
+      const l = literalValues(a);
+      if (!l) return undefined;
+      all.push(...l);
+    }
+    return all;
+  }
+  return undefined;
+}

package/src/describe/stages.ts

@@ -0,0 +1,165 @@
+import { configRefPath, configRefTarget, isConfigRef, unionAt } from '../core/config.ts';
+import { isStep } from '../core/steps.ts';
+import type { StageNode } from '../builder/pipeline.ts';
+import type { Stage, StepDescriptorT } from './manifest-schema.ts';
+import { literalValues, type JsonSchema } from './schemas.ts';
+import type { Avail, CaseOf, DescribeContext } from './context.ts';
+import { describeStep } from './step.ts';
+
+type StageGroup = Extract<StageNode, { kind: 'stage' }>;
+type WhenNode = Extract<StageNode, { kind: 'when' }>;
+type SelectNode = Extract<StageNode, { kind: 'select' }>;
+
+/** Describes stages, `when` blocks and selects in order, adding what each makes available to `avail`. */
+export function describeStages(
+  ctx: DescribeContext,
+  input: { name: string },
+  nodes: readonly StageNode[],
+  avail: Map<string, Avail>,
+  cases: readonly CaseOf[] = [],
+): Stage[] {
+  const out: Stage[] = [];
+  for (const n of nodes) {
+    if (n.kind === 'select') {
+      out.push(describeSelect(ctx, input, n, avail, cases, ctx.nextSelectId()));
+      continue;
+    }
+    if (n.kind === 'stage') {
+      const stage = describeStage(ctx, n, avail, cases);
+      if (stage) out.push(stage);
+    } else out.push(describeWhen(ctx, input, n, avail, cases));
+  }
+  return out;
+}
+
+function describeStage(
+  ctx: DescribeContext,
+  n: StageGroup,
+  avail: Map<string, Avail>,
+  cases: readonly CaseOf[],
+): Stage | undefined {
+  const descs = n.steps
+    .map((ss) => {
+      if (!isStep(ss.step)) {
+        ctx.problems.push('a stage entry is not a step');
+        return undefined;
+      }
+      ctx.registerStep(ss.step, 'stage', cases);
+      return describeStep(ctx, ss, avail, false, cases);
+    })
+    .filter((d): d is StepDescriptorT => d !== undefined);
+  // Outputs become available only after the barrier (same-stage siblings can't see each other).
+  for (const ss of n.steps)
+    if (isStep(ss.step))
+      avail.set(ss.step.name, {
+        model: ss.step.output?.name ?? null,
+        maybe: false,
+      });
+  return descs.length ? { steps: descs } : undefined;
+}
+
+function describeWhen(
+  ctx: DescribeContext,
+  input: { name: string },
+  n: WhenNode,
+  avail: Map<string, Avail>,
+  cases: readonly CaseOf[],
+): Stage {
+  const problems = ctx.problems;
+  const when: Record<string, (string | number | boolean)[]> = {};
+  const props = (ctx.models.get(input.name)?.schemas.output.properties ?? {}) as Record<
+    string,
+    JsonSchema
+  >;
+  for (const [field, raw] of Object.entries(n.cond)) {
+    const values = (Array.isArray(raw) ? raw : [raw]) as (string | number | boolean)[];
+    if (!Object.hasOwn(props, field))
+      problems.push(
+        `when: '${field}' is not a field of the pipeline input ${input.name}`,
+      );
+    else {
+      const literals = literalValues(props[field]);
+      if (!literals)
+        problems.push(
+          `when: '${field}' is not a literal-like field (enum, boolean or literal)`,
+        );
+      else
+        for (const v of values)
+          if (!literals.includes(v))
+            problems.push(
+              `when: ${JSON.stringify(v)} is not a valid value of '${field}' (${literals.map((l) => JSON.stringify(l)).join(', ')})`,
+            );
+    }
+    if (values.length === 0) problems.push(`when: '${field}' has no values`);
+    when[field] = values;
+  }
+  const inner = new Map(avail);
+  const stages = describeStages(ctx, input, n.nodes, inner, cases);
+  for (const [name, a] of inner)
+    if (!avail.has(name)) avail.set(name, { model: a.model, maybe: true });
+  return { when, stages };
+}
+
+function describeSelect(
+  ctx: DescribeContext,
+  input: { name: string },
+  n: SelectNode,
+  avail: Map<string, Avail>,
+  cases: readonly CaseOf[],
+  id: number,
+): Stage {
+  const problems = ctx.problems;
+  if (!isConfigRef(n.on)) {
+    problems.push('select: the first argument must be a config reference');
+    return { select: '', discriminator: '', cases: {} };
+  }
+  const ref = configRefPath(n.on);
+  const { entry, case: kase } = configRefTarget(n.on);
+  ctx.useConfig(entry, `select '${ref}'`);
+  if (kase !== undefined && !cases.some((c) => c.cond === kase))
+    problems.push(
+      `select '${ref}': the reference is narrowed to the case '${kase}' and can only be used inside it`,
+    );
+  const union = unionAt(n.on);
+  if (!union)
+    problems.push(
+      `select '${ref}': it must reference a z.discriminatedUnion in config '${entry.name}'`,
+    );
+  else {
+    for (const v of union.values)
+      if (!Object.hasOwn(n.cases, v))
+        problems.push(`select '${ref}': no case for ${union.discriminator} '${v}'`);
+    for (const v of Object.keys(n.cases))
+      if (!union.values.includes(v))
+        problems.push(
+          `select '${ref}': '${v}' is not a value of ${union.discriminator} (${union.values.join(', ')})`,
+        );
+  }
+  const discriminator = union?.discriminator ?? '';
+  const branches = Object.entries(n.cases).map(([value, nodes]) => {
+    const inner = new Map(avail);
+    const stages = describeStages(ctx, input, nodes, inner, [
+      ...cases,
+      { select: id, value, cond: `${ref}.${discriminator}=${value}` },
+    ]);
+    return { value, inner, stages };
+  });
+  // A step every case has is as available as in its cases; one only some cases have is maybe-available.
+  const added = new Set(
+    branches.flatMap((b) => [...b.inner.keys()].filter((k) => !avail.has(k))),
+  );
+  for (const name of added) {
+    const present = branches
+      .map((b) => b.inner.get(name))
+      .filter((a): a is Avail => a !== undefined);
+    avail.set(name, {
+      model: present[0]!.model,
+      maybe: present.length < branches.length || present.some((a) => a.maybe),
+    });
+  }
+  return {
+    select: ref,
+    discriminator,
+    cases: Object.fromEntries(branches.map((b) => [b.value, b.stages])),
+  };
+}

package/src/describe/step.ts

@@ -0,0 +1,395 @@
+import { z } from 'zod';
+import { isModel, isOptional } from '../core/models.ts';
+import { isExternal } from '../core/external.ts';
+import type { AnyStep } from '../core/steps.ts';
+import { isImplementation } from '../core/handlers.ts';
+import { recordConfigRefs } from '../core/config-refs.ts';
+import type { MapperFunction, StageStepNode } from '../builder/pipeline.ts';
+import { FailureContext } from '../library/models.ts';
+import { canonicalize } from '../util/canonical.ts';
+import { analyzeMapperSource } from './mapper-source.ts';
+import { MapperError, recordMapper, type Mapping } from './record.ts';
+import type { StepDescriptorT } from './manifest-schema.ts';
+import { recordedConfigRefs, secretRefsOf, subSchemas } from './config-schema.ts';
+import { resolveField, schemaViews } from './schemas.ts';
+import {
+  FAILURE_ROOT,
+  type Avail,
+  type CaseOf,
+  type DescribeContext,
+} from './context.ts';
+
+type InputTypes = StepDescriptorT['inputTypes'];
+type ExternalInputs = NonNullable<StepDescriptorT['externalInputs']>;
+type InputEntries = [string, unknown][];
+
+export function describeStep(
+  ctx: DescribeContext,
+  node: StageStepNode,
+  avail: Map<string, Avail>,
+  failureHandler: boolean,
+  cases: readonly CaseOf[] = [],
+): StepDescriptorT {
+  const problems = ctx.problems;
+  const s = node.step;
+  const at = `step '${s.name}'`;
+  if (typeof s.image !== 'string' || s.image.trim() === '')
+    problems.push(`${at}: image must be a non-empty string`);
+
+  const allEntries = Object.entries(s.input as Record<string, unknown>);
+  const externalInputs = describeExternalInputs(ctx, at, allEntries, failureHandler);
+  const entries = allEntries.filter(([, e]) => !isExternal(e));
+  const inputTypes = describeInputTypes(ctx, at, entries);
+
+  let input: Record<string, Mapping>;
+  if (failureHandler) input = failureHandlerInput(ctx, at, entries, node);
+  else if (node.mapper) input = mapStep(ctx, at, s, node.mapper, avail);
+  else input = matchInputsByModel(ctx, at, entries, avail);
+
+  for (const key of Object.keys(s.input as Record<string, unknown>))
+    if (key.startsWith('$'))
+      problems.push(`${at}: input '${key}': keys starting with '$' are reserved`);
+  const secretNames = s.secrets.map((x) => ctx.useSecret(x, at)).sort();
+  const configNames = [
+    ...new Set(
+      (s.config ?? [])
+        .map((c) => ctx.useConfig(c, at))
+        .filter((n): n is string => n !== undefined),
+    ),
+  ].sort();
+  const carried = isImplementation(s);
+  const { settings, settingsProblem } = recordSettings(s, carried);
+  const refs = settings ? recordedConfigRefs(settings) : [];
+  checkConfigSecrets(ctx, at, configNames, refs, secretNames);
+  if (settingsProblem !== undefined)
+    problems.push(`${at}: invalid ${s.kind} settings (${settingsProblem})`);
+  if (typeof s.kind !== 'string' || s.kind === '')
+    problems.push(`${at}: kind must be a non-empty string`);
+  checkConfigRefs(ctx, at, refs, configNames, cases);
+  if (!carried)
+    problems.push(`${at} has no implementation (stage implement(step({...}), fn))`);
+  if (typeof s.description !== 'string')
+    problems.push(`${at}: description must be a string (it may be empty)`);
+  if (
+    s.timeoutSeconds !== undefined &&
+    !(Number.isInteger(s.timeoutSeconds) && s.timeoutSeconds > 0)
+  )
+    problems.push(`${at}: timeoutSeconds must be a positive integer`);
+  if (s.retries !== undefined && !(Number.isInteger(s.retries) && s.retries >= 0))
+    problems.push(`${at}: retries must be a non-negative integer`);
+
+  const out: StepDescriptorT = {
+    name: s.name,
+    description: typeof s.description === 'string' ? s.description : '',
+    kind: s.kind,
+    image: s.image,
+    inputTypes,
+    input,
+    output: s.output ? ctx.useModel(s.output, `${at} output`) : null,
+    secrets: secretNames,
+    ...(s.timeoutSeconds !== undefined ? { timeoutSeconds: s.timeoutSeconds } : {}),
+    ...(s.retries !== undefined ? { retries: s.retries } : {}),
+    ...(settings !== undefined
+      ? { config: settings as Record<string, z.core.util.JSONType> }
+      : {}),
+    ...(configNames.length ? { configEntries: configNames } : {}),
+    ...(s.clusterAccess === true ? { clusterAccess: true as const } : {}),
+    ...(Object.keys(externalInputs).length ? { externalInputs } : {}),
+  };
+  if (s.clusterAccess !== undefined && typeof s.clusterAccess !== 'boolean')
+    problems.push(`${at}: clusterAccess must be a boolean`);
+  if (s.output && !isModel(s.output)) problems.push(`${at}: output must be a model`);
+  return out;
+}
+
+function describeExternalInputs(
+  ctx: DescribeContext,
+  at: string,
+  allEntries: InputEntries,
+  failureHandler: boolean,
+): ExternalInputs {
+  const problems = ctx.problems;
+  const externalInputs: ExternalInputs = {};
+  for (const [key, e] of allEntries) {
+    if (!isExternal(e)) continue;
+    if (failureHandler)
+      problems.push(
+        `${at}: failure handlers run unattended and cannot wait for input ('${key}')`,
+      );
+    if (typeof e.title !== 'string' || e.title.trim() === '')
+      problems.push(`${at} external input '${key}': title must not be empty`);
+    if (e.from.length === 0)
+      problems.push(`${at} external input '${key}': from must list at least one source`);
+    if (new Set(e.from.map((f) => f.kind)).size !== e.from.length)
+      problems.push(`${at} external input '${key}': each source kind may be listed once`);
+    if (e.from.some((f) => f.kind === 'callback') && !/^[A-Za-z0-9_-]+$/.test(key))
+      problems.push(
+        `${at} external input '${key}': a callback input's key must be letters, digits, '_' or '-' (it is part of the URL)`,
+      );
+    for (const f of e.from) {
+      if (f.kind !== 'poll') continue;
+      if (!/^https?:\/\//.test(f.url))
+        problems.push(
+          `${at} external input '${key}': poll url must be an absolute http(s) URL`,
+        );
+      if (!Number.isInteger(f.intervalSeconds) || f.intervalSeconds < 10)
+        problems.push(
+          `${at} external input '${key}': poll intervalSeconds must be an integer of at least 10`,
+        );
+      if (f.valuePath.trim() === '')
+        problems.push(`${at} external input '${key}': poll valuePath must not be empty`);
+    }
+    externalInputs[key] = {
+      model: ctx.useModel(e.model, `${at} external input '${key}'`),
+      title: e.title,
+      description: e.description,
+      from: e.from.map((f) => ({ ...f })),
+    };
+  }
+  return externalInputs;
+}
+
+function describeInputTypes(
+  ctx: DescribeContext,
+  at: string,
+  entries: InputEntries,
+): InputTypes {
+  const inputTypes: InputTypes = {};
+  for (const [key, e] of entries) {
+    if (isOptional(e))
+      inputTypes[key] = {
+        model: ctx.useModel(e.model, `${at} input '${key}'`),
+        optional: true,
+      };
+    else if (isModel(e))
+      inputTypes[key] = {
+        model: ctx.useModel(e, `${at} input '${key}'`),
+        optional: false,
+      };
+    else if (e instanceof z.ZodType) {
+      try {
+        inputTypes[key] = { schema: schemaViews(e) };
+      } catch (err) {
+        ctx.problems.push(
+          `${at} input '${key}': schema is not representable as JSON Schema (${(err as Error).message})`,
+        );
+      }
+    } else
+      ctx.problems.push(
+        `${at} input '${key}': must be a model, optional(model) or a zod schema`,
+      );
+  }
+  return inputTypes;
+}
+
+function failureHandlerInput(
+  ctx: DescribeContext,
+  at: string,
+  entries: InputEntries,
+  node: StageStepNode,
+): Record<string, Mapping> {
+  const input: Record<string, Mapping> = {};
+  for (const [key, e] of entries) {
+    if (e !== FailureContext && !(isModel(e) && e.name === FailureContext.name))
+      ctx.problems.push(
+        `${at}: a failure handler's inputs must all be FailureContext (input '${key}' is not)`,
+      );
+    input[key] = { ref: FAILURE_ROOT };
+  }
+  if (node.mapper) ctx.problems.push(`${at}: failure handlers take no mapper`);
+  return input;
+}
+
+function matchInputsByModel(
+  ctx: DescribeContext,
+  at: string,
+  entries: InputEntries,
+  avail: Map<string, Avail>,
+): Record<string, Mapping> {
+  const problems = ctx.problems;
+  const input: Record<string, Mapping> = {};
+  for (const [key, e] of entries) {
+    const optional = isOptional(e);
+    const m = optional ? e.model : isModel(e) ? e : undefined;
+    if (!m) {
+      problems.push(
+        `${at}: input '${key}' is a plain schema, not a model, so it cannot be matched by model; add a mapper ([step, from => ({ ... })])`,
+      );
+      continue;
+    }
+    const producers = [...avail].filter(([, a]) => a.model === m.name);
+    if (producers.length === 0) {
+      problems.push(
+        `${at}: ${m.name} (input '${key}') is not available at this stage${optional ? ' (optional() means maybe-skipped; there must still be an earlier producer)' : ''}`,
+      );
+    } else if (producers.length > 1) {
+      problems.push(
+        `${at}: ${m.name} (input '${key}') has several producers (${producers
+          .map(([n]) => n)
+          .sort()
+          .join(', ')}); use a mapper to pick one`,
+      );
+    } else {
+      const [producer, a] = producers[0]!;
+      if (a.maybe && !optional)
+        problems.push(
+          `${at}: ${m.name} (input '${key}') is only maybe-available (produced inside a when block); declare it optional(${m.name})`,
+        );
+      input[key] = { ref: producer };
+    }
+  }
+  return input;
+}
+
+function mapStep(
+  ctx: DescribeContext,
+  at: string,
+  s: AnyStep,
+  mapper: MapperFunction,
+  avail: Map<string, Avail>,
+): Record<string, Mapping> {
+  const problems = ctx.problems;
+  try {
+    analyzeMapperSource(Function.prototype.toString.call(mapper));
+  } catch (e) {
+    if (e instanceof MapperError) problems.push(`${at}: ${e.message}`);
+    else throw e;
+    return {};
+  }
+  const roots = new Set([...avail].filter(([, a]) => a.model !== null).map(([n]) => n));
+  let recorded: Record<string, Mapping>;
+  try {
+    recorded = recordMapper(mapper, roots);
+  } catch (e) {
+    if (e instanceof MapperError) problems.push(`${at}: ${e.message}`);
+    else problems.push(`${at}: mapper threw: ${(e as Error)?.message ?? String(e)}`);
+    return {};
+  }
+  const declared = Object.fromEntries(
+    Object.entries(s.input as Record<string, unknown>).filter(([, e]) => !isExternal(e)),
+  );
+  for (const k of Object.keys(declared))
+    if (!(k in recorded)) problems.push(`${at}: mapper does not provide input '${k}'`);
+  for (const k of Object.keys(recorded))
+    if (!(k in declared))
+      problems.push(`${at}: mapper provides '${k}', which is not an input of the step`);
+  for (const [k, m] of Object.entries(recorded))
+    checkMapping(ctx, `${at} input '${k}'`, m, avail, isOptional(declared[k]), true);
+  return recorded;
+}
+
+function checkMapping(
+  ctx: DescribeContext,
+  at: string,
+  m: Mapping,
+  avail: Map<string, Avail>,
+  optionalTarget: boolean,
+  topLevel: boolean,
+): void {
+  const problems = ctx.problems;
+  const keys = Object.keys(m);
+  if (
+    keys.length === 1 &&
+    keys[0] === 'ref' &&
+    typeof (m as { ref: unknown }).ref === 'string'
+  ) {
+    const [root, ...path] = (m as { ref: string }).ref.split('.') as [
+      string,
+      ...string[],
+    ];
+    const a = avail.get(root);
+    if (!a) return void problems.push(`${at}: '${root}' is not available at this stage`);
+    if (!resolveField(ctx.outputViewOf(a.model), path))
+      problems.push(
+        `${at}: '${(m as { ref: string }).ref}' — model ${a.model} has no field '${path.join('.')}'`,
+      );
+    if (a.maybe && !(optionalTarget && topLevel))
+      problems.push(
+        `${at}: '${(m as { ref: string }).ref}' is only maybe-available (produced inside a when block); map it whole into an optional(...) input`,
+      );
+    return;
+  }
+  if (keys.length === 1 && keys[0] === 'const') return;
+  for (const [k, x] of Object.entries(m as Record<string, Mapping>))
+    checkMapping(ctx, `${at}.${k}`, x, avail, optionalTarget, false);
+}
+
+function recordSettings(
+  s: AnyStep,
+  carried: boolean,
+): { settings?: Record<string, unknown>; settingsProblem?: string } {
+  if (s.settings === undefined && !carried) return {};
+  try {
+    return {
+      settings: canonicalize(recordConfigRefs(s.settings ?? {})) as Record<
+        string,
+        unknown
+      >,
+    };
+  } catch (e) {
+    return { settings: {}, settingsProblem: (e as Error).message };
+  }
+}
+
+type ConfigRefUse = { ref: string; case?: string };
+
+// A step whose settings reference parts of an entry needs the secrets those parts name; any other
+// step receiving an entry needs every secret the entry names.
+function checkConfigSecrets(
+  ctx: DescribeContext,
+  at: string,
+  configNames: readonly string[],
+  refs: readonly ConfigRefUse[],
+  secretNames: readonly string[],
+): void {
+  for (const name of configNames) {
+    const into = refs.filter((r) => r.ref.split('.')[0] === name);
+    const needed =
+      into.length === 0
+        ? (ctx.configs.get(name)?.secretRefs ?? [])
+        : [
+            ...new Set(
+              into.flatMap((r) =>
+                secretRefsOf(
+                  subSchemas(
+                    ctx.configs.get(name)?.schema,
+                    r.ref.split('.').slice(1),
+                    r.case,
+                    name,
+                  ),
+                ),
+              ),
+            ),
+          ].sort();
+    for (const ref of needed)
+      if (!secretNames.includes(ref))
+        ctx.problems.push(
+          `${at}: config '${name}' references secret '${ref}' (secretRef), so the step must declare it in secrets`,
+        );
+  }
+}
+
+function checkConfigRefs(
+  ctx: DescribeContext,
+  at: string,
+  refs: readonly ConfigRefUse[],
+  configNames: readonly string[],
+  cases: readonly CaseOf[],
+): void {
+  const problems = ctx.problems;
+  for (const { ref, case: kase } of refs) {
+    const [entry, ...path] = ref.split('.') as [string, ...string[]];
+    if (kase !== undefined && !cases.some((c) => c.cond === kase))
+      problems.push(
+        `${at}: config reference '${ref}' is narrowed to the select case '${kase}' and can only be used inside it`,
+      );
+    if (!configNames.includes(entry))
+      problems.push(
+        `${at}: config reference '${ref}': the step does not receive config entry '${entry}'`,
+      );
+    else if (!resolveField(ctx.configs.get(entry)?.schema, path))
+      problems.push(
+        `${at}: config reference '${ref}': config '${entry}' has no field '${path.join('.')}'`,
+      );
+  }
+}