rapidoc 11.0.1 → 12.1.0

package/src/utils/arazzo/graph.js

@@ -0,0 +1,269 @@
+/**
+ * Turns one Arazzo workflow into the graph the diagram draws: steps in order, the values passed
+ * between them, and each step's success and failure actions.
+ */
+import { collectRefs } from "./refs.js";
+import { resolveComponentRef } from "./parse.js";
+import { resolveOperation } from "./operations.js";
+
+function normalizeCriteria(list) {
+  return (Array.isArray(list) ? list : [])
+    .filter((c) => c && typeof c.condition === "string")
+    .map((c) => ({
+      condition: c.condition,
+      context: c.context || "",
+      type: typeof c.type === "string" ? c.type : c.type?.type || "simple",
+    }));
+}
+
+function normalizeActions(doc, list, kind, outcome, inherited) {
+  return (Array.isArray(list) ? list : [])
+    .map((raw) => resolveComponentRef(doc, raw, kind))
+    .filter((a) => a && ["end", "goto", "retry"].includes(a.type))
+    .map((a) => {
+      const criteria = normalizeCriteria(a.criteria);
+      return {
+        outcome,
+        type: a.type,
+        name: a.name || "",
+        stepId: a.stepId || "",
+        workflowId: a.workflowId || "",
+        retryAfter: a.retryAfter,
+        retryLimit: a.retryLimit,
+        criteria,
+        conditional: criteria.length > 0,
+        inherited,
+      };
+    });
+}
+
+/**
+ * A step's own actions, then the workflow's, minus those the step overrides by name. A runner
+ * takes the first action whose criteria match, so every action after one without criteria is
+ * marked `shadowed`: it can never run.
+ */
+function mergeActions(own, inherited) {
+  const names = new Set(own.map((a) => a.name).filter(Boolean));
+  const merged = [...own, ...inherited.filter((a) => !a.name || !names.has(a.name))];
+  const first = merged.findIndex((a) => !a.conditional);
+  return merged.map((a, i) => ({ ...a, shadowed: first >= 0 && i > first }));
+}
+
+/** The workflow's `inputs` JSON Schema (or a `$ref` to `#/components/inputs/<name>`) as rows. */
+function describeInputs(doc, schema) {
+  const ref =
+    typeof schema?.$ref === "string" && schema.$ref.match(/^#\/components\/inputs\/(.+)$/);
+  const resolved = ref ? doc?.components?.inputs?.[ref[1]] : schema;
+  const required = new Set(Array.isArray(resolved?.required) ? resolved.required : []);
+  return Object.entries(resolved?.properties || {}).map(([name, prop]) => ({
+    name,
+    type: prop?.type ? [].concat(prop.type).join(" | ") : prop?.enum ? "enum" : "",
+    format: prop?.format || "",
+    required: required.has(name),
+    default: prop?.default,
+    enum: Array.isArray(prop?.enum) ? prop.enum : undefined,
+    description: prop?.description || "",
+  }));
+}
+
+function describeParameters(doc, list) {
+  return (Array.isArray(list) ? list : [])
+    .map((raw) => resolveComponentRef(doc, raw, "parameters"))
+    .filter((p) => p && p.name)
+    .map((p) => ({ name: p.name, in: p.in || "", value: p.value }));
+}
+
+/**
+ * Where a value comes from, for one line in a step box: a workflow input, a step output, another
+ * runtime expression, or a fixed value.
+ */
+function describeSource(value) {
+  if (typeof value === "string") {
+    const text = value.trim();
+    let m = text.match(/^\$inputs\.([A-Za-z0-9_-]+)$/);
+    if (m) return { kind: "input", name: m[1], text: m[1] };
+    m = text.match(/^\$steps\.([A-Za-z0-9_-]+)\.outputs\.([A-Za-z0-9_-]+)$/);
+    if (m) return { kind: "step", stepId: m[1], name: m[2], text: `${m[1]}.${m[2]}` };
+    if (text.includes("$")) return { kind: "expression", text };
+    return { kind: "value", text };
+  }
+  return { kind: "value", text: value === undefined ? "" : JSON.stringify(value) };
+}
+
+function flattenPayload(obj, prefix, rows) {
+  for (const [key, value] of Object.entries(obj)) {
+    const name = `${prefix}.${key}`;
+    if (value && typeof value === "object" && !Array.isArray(value) && Object.keys(value).length) {
+      flattenPayload(value, name, rows);
+    } else rows.push({ name, in: "body", value });
+  }
+}
+
+/** A step's parameters and request body fields, one row per value it sends. */
+function describeBindings(parameters, requestBody) {
+  const rows = parameters.map((p) => ({ name: p.name, in: p.in, value: p.value }));
+  const payload = requestBody?.payload;
+  if (payload && typeof payload === "object" && !Array.isArray(payload)) {
+    flattenPayload(payload, "body", rows);
+  } else if (payload !== undefined && payload !== null) {
+    rows.push({ name: "body", in: "body", value: payload });
+  }
+  for (const r of requestBody?.replacements || []) {
+    if (r?.target) rows.push({ name: `body ${r.target}`, in: "body", value: r.value });
+  }
+  return rows.map((r) => {
+    const stepRefs = collectRefs(r.value).filter((x) => x.kind === "step");
+    return {
+      ...r,
+      source: describeSource(r.value),
+      fromSteps: [...new Set(stepRefs.map((x) => x.stepId))],
+      fromOutputs: stepRefs.filter((x) => x.name).map((x) => ({ stepId: x.stepId, name: x.name })),
+    };
+  });
+}
+
+const listOf = (names) =>
+  names.length > 1 ? `${names.slice(0, -1).join(", ")} and ${names.at(-1)}` : names[0];
+
+/**
+ * One warning per step and outcome whose actions include some that can never run, because an
+ * earlier action without criteria always matches first.
+ */
+function shadowWarnings(steps, workflowIndex) {
+  const warnings = [];
+  steps.forEach((step, si) => {
+    for (const outcome of ["success", "failure"]) {
+      const actions = step.actions.filter((a) => a.outcome === outcome);
+      const never = actions.filter((a) => a.shadowed);
+      if (!never.length) continue;
+      const catchAll = actions.find((a) => !a.conditional);
+      const names = never.map((a) => a.name || `an unnamed ${a.type}`);
+      const whose = never.every((a) => a.inherited) ? "the workflow's " : "";
+      const verb = never.length > 1 ? "never run" : "never runs";
+      warnings.push({
+        level: "warning",
+        path: `workflows[${workflowIndex}].steps[${si}].${outcome === "failure" ? "onFailure" : "onSuccess"}`,
+        message: `${step.stepId}: ${whose}${listOf(names)} ${verb}, because ${catchAll?.name || "an action"} has no criteria and always matches first`,
+      });
+    }
+  });
+  return warnings;
+}
+
+function pushEdge(edges, from, to, label) {
+  const edge = edges.find((e) => e.from === from && e.to === to);
+  if (!edge) edges.push({ from, to, labels: [label] });
+  else if (!edge.labels.includes(label)) edge.labels.push(label);
+}
+
+/**
+ * @param {object} doc Parsed Arazzo document
+ * @param {string} [workflowId] Defaults to the first workflow
+ * @param {object} [options]
+ * @param {Map<string, {byId: Map, byPath: Map}>} [options.sources] operation indexes by source name
+ * Each step's `bindings` list the values it sends (`{ name, in, value, source, fromSteps }`, with
+ * body fields named `body.<path>`; `fromOutputs` the `{ stepId, name }` step outputs they read);
+ * `usedOutputs` are the step's own outputs that a later step or the workflow reads; `source` is `{ kind: 'input'|'step'|'expression'|'value', text }`.
+ *
+ * @returns {object|null} `{ workflowId, summary, description, inputs, inputDetails, workflowActions,
+ *   operationsKnown, outputs, steps, dataEdges, warnings }`,
+ *   or null when there is no such workflow. Data edges go from a step id to a later step id or
+ *   to "outputs"; `labels` are the output names passed.
+ */
+export function buildFlowGraph(doc, workflowId, options = {}) {
+  const workflows = Array.isArray(doc?.workflows) ? doc.workflows : [];
+  const workflow = workflowId ? workflows.find((w) => w?.workflowId === workflowId) : workflows[0];
+  if (!workflow) return null;
+
+  const rawSteps = Array.isArray(workflow.steps) ? workflow.steps : [];
+  const stepIds = new Set(rawSteps.map((s) => s?.stepId).filter(Boolean));
+  const workflowSuccess = normalizeActions(
+    doc,
+    workflow.successActions,
+    "successActions",
+    "success",
+    true,
+  );
+  const workflowFailure = normalizeActions(
+    doc,
+    workflow.failureActions,
+    "failureActions",
+    "failure",
+    true,
+  );
+  const dataEdges = [];
+
+  const steps = rawSteps.map((s) => {
+    const onSuccess = normalizeActions(doc, s.onSuccess, "successActions", "success", false);
+    const onFailure = normalizeActions(doc, s.onFailure, "failureActions", "failure", false);
+    const operation = s.workflowId ? null : resolveOperation(s, options.sources);
+    const refs = collectRefs([s.parameters, s.requestBody]);
+    for (const ref of refs) {
+      if (ref.kind === "step" && ref.name && ref.stepId !== s.stepId && stepIds.has(ref.stepId)) {
+        pushEdge(dataEdges, ref.stepId, s.stepId, ref.name);
+      }
+    }
+    const criteria = normalizeCriteria(s.successCriteria);
+    const parameters = describeParameters(doc, s.parameters);
+    return {
+      stepId: s.stepId || "",
+      description: s.description || "",
+      kind: s.workflowId ? "workflow" : "operation",
+      workflowId: s.workflowId || "",
+      operationRef: s.operationId || s.operationPath || "",
+      operation,
+      inputs: refs.filter((r) => r.kind === "input").map((r) => r.name),
+      outputs: Object.keys(s.outputs || {}),
+      outputExprs: Object.entries(s.outputs || {}).map(([name, expr]) => ({ name, expr })),
+      parameters,
+      requestBody: s.requestBody || null,
+      bindings: describeBindings(parameters, s.requestBody),
+      criteria,
+      successCriteria: criteria.length,
+      actions: [
+        ...mergeActions(onSuccess, workflowSuccess),
+        ...mergeActions(onFailure, workflowFailure),
+      ],
+    };
+  });
+
+  const inputDetails = describeInputs(doc, workflow.inputs);
+  const outputs = Object.entries(workflow.outputs || {}).map(([name, expr]) => {
+    const ref = collectRefs(expr).find((r) => r.kind === "step");
+    if (ref && stepIds.has(ref.stepId)) pushEdge(dataEdges, ref.stepId, "outputs", name);
+    return {
+      name,
+      stepId: ref?.stepId || "",
+      output: ref?.name || "",
+      source: describeSource(expr),
+      expr: typeof expr === "string" ? expr : JSON.stringify(expr),
+    };
+  });
+
+  // Each step output something else reads: later steps' values and the workflow's outputs
+  const used = new Map();
+  const markUsed = (stepId, name) => {
+    if (stepId && name) used.set(stepId, (used.get(stepId) || new Set()).add(name));
+  };
+  for (const s of steps)
+    for (const b of s.bindings) for (const r of b.fromOutputs) markUsed(r.stepId, r.name);
+  for (const o of outputs) markUsed(o.stepId, o.output);
+  for (const s of steps) {
+    const names = used.get(s.stepId) || new Set();
+    s.usedOutputs = s.outputExprs.filter((o) => names.has(o.name));
+  }
+
+  return {
+    workflowId: workflow.workflowId || "",
+    summary: workflow.summary || "",
+    description: workflow.description || "",
+    inputs: inputDetails.map((i) => i.name),
+    inputDetails,
+    workflowActions: [...workflowSuccess, ...workflowFailure],
+    operationsKnown: Boolean(options.sources?.size),
+    outputs,
+    steps,
+    dataEdges,
+    warnings: shadowWarnings(steps, workflows.indexOf(workflow)),
+  };
+}

package/src/utils/arazzo/index.js

@@ -0,0 +1,52 @@
+/**
+ * Arazzo support shared by <rapi-flow> and the build-time renderer (@rapidoc/prerender).
+ */
+import { parseDocument, validateArazzo } from "./parse.js";
+import { indexOperations } from "./operations.js";
+import { buildFlowGraph } from "./graph.js";
+import { renderFlowDiagram } from "./svg.js";
+
+export { parseDocument, validateArazzo, resolveComponentRef } from "./parse.js";
+export { collectRefs } from "./refs.js";
+export { indexOperations, indexResolvedSpec, resolveOperation } from "./operations.js";
+export { buildFlowGraph } from "./graph.js";
+export {
+  renderFlowDiagram,
+  renderFlowSvg,
+  escapeXml,
+  actionLabel,
+  actionSentence,
+  describeAction,
+} from "./svg.js";
+
+/**
+ * One call from documents to SVG.
+ *
+ * @param {string|object} arazzo Arazzo text or object
+ * @param {object} [options]
+ * @param {string} [options.workflowId] defaults to the first workflow
+ * @param {Record<string, string|object>} [options.sources] OpenAPI documents (text or object) by
+ *   source description name; operations are looked up in them
+ * @param {'expanded'|'compact'} [options.view] defaults to expanded
+ * @param {string} [options.idPrefix]
+ * @param {boolean} [options.interactive]
+ * @returns {{ svg: string, legend: string[], graph: object|null, problems: object[],
+ *   workflowIds: string[] }} `legend` names the kinds of lines drawn (see renderFlowDiagram)
+ */
+export function renderArazzoWorkflow(arazzo, options = {}) {
+  const doc = parseDocument(arazzo);
+  const problems = validateArazzo(doc);
+  const sources = new Map();
+  for (const [name, openapi] of Object.entries(options.sources || {})) {
+    sources.set(name, indexOperations(parseDocument(openapi)));
+  }
+  const graph = buildFlowGraph(doc, options.workflowId, { sources });
+  const { svg, legend } = renderFlowDiagram(graph, options);
+  return {
+    svg,
+    legend,
+    graph,
+    problems,
+    workflowIds: (doc.workflows || []).map((w) => w?.workflowId).filter(Boolean),
+  };
+}

package/src/utils/arazzo/operations.js

@@ -0,0 +1,106 @@
+/**
+ * Looks up the OpenAPI operation an Arazzo step calls, without dereferencing the OpenAPI document.
+ */
+
+const METHODS = ["get", "put", "post", "delete", "options", "head", "patch", "trace", "query"];
+
+/**
+ * Indexes an OpenAPI document's operations by operationId and by "<method> <path>".
+ *
+ * @param {object} openapi Raw OpenAPI 2.0, 3.x object
+ * @returns {{ byId: Map<string, object>, byPath: Map<string, object> }} values are
+ *   `{ operationId, method, path, summary, security }`, method lower-case; `security` is the
+ *   operation's requirement, else the document's
+ */
+export function indexOperations(openapi) {
+  const byId = new Map();
+  const byPath = new Map();
+  for (const [path, item] of Object.entries(openapi?.paths || {})) {
+    if (!item || typeof item !== "object") continue;
+    for (const method of METHODS) {
+      const op = item[method];
+      if (!op || typeof op !== "object") continue;
+      const entry = {
+        operationId: op.operationId || "",
+        method,
+        path,
+        summary: op.summary || "",
+      };
+      const security = op.security ?? openapi.security;
+      if (security !== undefined) entry.security = security;
+      if (op.operationId) byId.set(op.operationId, entry);
+      byPath.set(`${method} ${path}`, entry);
+    }
+  }
+  return { byId, byPath };
+}
+
+/**
+ * The same index from a spec <rapi-doc> has already processed (its `resolvedSpec`), whose
+ * operations are listed under `tags[].paths[]`. Webhooks are skipped. An operation without an
+ * operationId in the document gets one generated by <rapi-doc>, which no Arazzo step can name,
+ * so it only matters for lookup by method and path.
+ *
+ * @param {{ tags?: { paths?: object[] }[] }} resolvedSpec
+ * @returns {{ byId: Map<string, object>, byPath: Map<string, object> }}
+ */
+export function indexResolvedSpec(resolvedSpec) {
+  const byId = new Map();
+  const byPath = new Map();
+  for (const tag of resolvedSpec?.tags || []) {
+    for (const p of tag?.paths || []) {
+      if (!p?.method || !p.path || p.isWebhook) continue;
+      const method = p.method.toLowerCase();
+      const entry = {
+        operationId: p.operationId || "",
+        method,
+        path: p.path,
+        summary: p.summary || "",
+      };
+      if (p.security !== undefined) entry.security = p.security;
+      // An operation with several tags is listed once per tag; the first entry is kept
+      const key = `${method} ${p.path}`;
+      if (byPath.has(key)) continue;
+      if (p.operationId) byId.set(p.operationId, entry);
+      byPath.set(key, entry);
+    }
+  }
+  return { byId, byPath };
+}
+
+function unescapePointer(segment) {
+  return decodeURIComponent(segment).replace(/~1/g, "/").replace(/~0/g, "~");
+}
+
+/**
+ * Resolves a step's operationId or operationPath.
+ *
+ * @param {object} step Arazzo step
+ * @param {Map<string, {byId: Map, byPath: Map}>} sources indexes by source description name
+ * @returns {{ source: string, operationId: string, method: string, path: string, summary: string } | null}
+ */
+export function resolveOperation(step, sources) {
+  if (!sources?.size) return null;
+  if (step.operationId) {
+    let source = "";
+    let id = step.operationId;
+    const qualified = id.match(/^\$sourceDescriptions\.([A-Za-z0-9_-]+)\.(.+)$/);
+    if (qualified) [, source, id] = qualified;
+    for (const [name, index] of sources) {
+      if (source && name !== source) continue;
+      const op = index.byId.get(id);
+      if (op) return { source: name, ...op };
+    }
+    return null;
+  }
+  if (step.operationPath) {
+    const m = step.operationPath.match(/^\{\$sourceDescriptions\.([A-Za-z0-9_-]+)\.url\}#(.*)$/);
+    if (!m) return null;
+    const [, source, pointer] = m;
+    const parts = pointer.split("/").slice(1).map(unescapePointer);
+    if (parts.length !== 3 || parts[0] !== "paths") return null;
+    const op = sources.get(source)?.byPath.get(`${parts[2].toLowerCase()} ${parts[1]}`);
+    return op ? { source, ...op } : null;
+  }
+  return null;
+}

package/src/utils/arazzo/parse.js

@@ -0,0 +1,196 @@
+/**
+ * Arazzo document parsing and structural validation.
+ */
+import { parse as parseYaml } from "yaml";
+import { collectRefs } from "./refs.js";
+import { resolveComponentRef } from "./components.js";
+
+export { resolveComponentRef };
+
+const ACTION_TYPES = new Set(["end", "goto", "retry"]);
+const SOURCE_TYPES = new Set(["openapi", "arazzo", "asyncapi"]);
+
+/**
+ * Parses Arazzo (or OpenAPI) text as JSON or YAML. An object is returned as is.
+ *
+ * @param {string|object} input
+ * @returns {object}
+ */
+export function parseDocument(input) {
+  if (input && typeof input === "object") return input;
+  const text = String(input ?? "").trim();
+  if (!text) throw new Error("The document is empty");
+  const doc = text.startsWith("{") ? JSON.parse(text) : parseYaml(text);
+  if (!doc || typeof doc !== "object") throw new Error("The document is not an object");
+  return doc;
+}
+
+function problem(level, path, message) {
+  return { level, path, message };
+}
+
+function checkActions(doc, list, kind, path, stepIds, workflowIds, problems) {
+  if (list === undefined) return;
+  if (!Array.isArray(list)) {
+    problems.push(problem("error", path, "must be a list of actions"));
+    return;
+  }
+  list.forEach((raw, i) => {
+    const p = `${path}[${i}]`;
+    const action = resolveComponentRef(doc, raw, kind);
+    if (!action) {
+      problems.push(problem("error", p, `unresolved reference ${raw?.reference}`));
+      return;
+    }
+    if (!ACTION_TYPES.has(action.type)) {
+      problems.push(problem("error", `${p}.type`, "must be end, goto or retry"));
+      return;
+    }
+    if (action.type === "retry" && kind === "successActions") {
+      problems.push(problem("error", `${p}.type`, "retry is only allowed on failure"));
+    }
+    if (action.stepId && action.workflowId) {
+      problems.push(problem("error", p, "has both stepId and workflowId"));
+    }
+    if (action.type === "goto" && !action.stepId && !action.workflowId) {
+      problems.push(problem("error", p, "goto needs a stepId or a workflowId"));
+    }
+    if (action.stepId && !stepIds.has(action.stepId)) {
+      problems.push(problem("error", `${p}.stepId`, `no step "${action.stepId}"`));
+    }
+    if (
+      action.workflowId &&
+      !action.workflowId.startsWith("$") &&
+      !workflowIds.has(action.workflowId)
+    ) {
+      problems.push(problem("error", `${p}.workflowId`, `no workflow "${action.workflowId}"`));
+    }
+  });
+}
+
+/**
+ * Checks the structure the visualizer relies on. Returns problems; an empty list means valid.
+ * Expression syntax and JSON Schema of `inputs` are not checked.
+ *
+ * @param {object} doc
+ * @returns {{ level: 'error'|'warning', path: string, message: string }[]}
+ */
+export function validateArazzo(doc) {
+  const problems = [];
+  if (!doc || typeof doc !== "object") return [problem("error", "", "not an object")];
+
+  if (typeof doc.arazzo !== "string" || !/^1\.\d+(\.\d+)?/.test(doc.arazzo)) {
+    problems.push(problem("error", "arazzo", "must be an Arazzo 1.x version string"));
+  }
+  if (!doc.info?.title) problems.push(problem("error", "info.title", "is required"));
+  if (!doc.info?.version) problems.push(problem("error", "info.version", "is required"));
+
+  const sources = Array.isArray(doc.sourceDescriptions) ? doc.sourceDescriptions : [];
+  if (!sources.length) {
+    problems.push(problem("error", "sourceDescriptions", "needs at least one source"));
+  }
+  const sourceNames = new Set();
+  sources.forEach((s, i) => {
+    const p = `sourceDescriptions[${i}]`;
+    if (!s?.name) problems.push(problem("error", `${p}.name`, "is required"));
+    else if (sourceNames.has(s.name))
+      problems.push(problem("error", `${p}.name`, "is a duplicate"));
+    else sourceNames.add(s.name);
+    if (!s?.url) problems.push(problem("error", `${p}.url`, "is required"));
+    if (s?.type && !SOURCE_TYPES.has(s.type)) {
+      problems.push(problem("warning", `${p}.type`, `unknown type "${s.type}"`));
+    }
+  });
+
+  const workflows = Array.isArray(doc.workflows) ? doc.workflows : [];
+  if (!workflows.length)
+    problems.push(problem("error", "workflows", "needs at least one workflow"));
+  const workflowIds = new Set();
+  workflows.forEach((w, i) => {
+    if (!w?.workflowId)
+      problems.push(problem("error", `workflows[${i}].workflowId`, "is required"));
+    else if (workflowIds.has(w.workflowId)) {
+      problems.push(problem("error", `workflows[${i}].workflowId`, "is a duplicate"));
+    } else workflowIds.add(w.workflowId);
+  });
+
+  workflows.forEach((w, wi) => {
+    const wp = `workflows[${wi}]`;
+    const steps = Array.isArray(w?.steps) ? w.steps : [];
+    if (!steps.length) problems.push(problem("error", `${wp}.steps`, "needs at least one step"));
+    const stepIds = new Set();
+    steps.forEach((s, si) => {
+      const sp = `${wp}.steps[${si}]`;
+      if (!s?.stepId) problems.push(problem("error", `${sp}.stepId`, "is required"));
+      else if (stepIds.has(s.stepId))
+        problems.push(problem("error", `${sp}.stepId`, "is a duplicate"));
+      else stepIds.add(s.stepId);
+      const targets = ["operationId", "operationPath", "workflowId"].filter((k) => s?.[k]);
+      if (targets.length !== 1) {
+        problems.push(
+          problem("error", sp, "needs exactly one of operationId, operationPath or workflowId"),
+        );
+      }
+      if (s?.workflowId && !s.workflowId.startsWith("$") && !workflowIds.has(s.workflowId)) {
+        problems.push(problem("error", `${sp}.workflowId`, `no workflow "${s.workflowId}"`));
+      }
+    });
+    (w?.dependsOn || []).forEach((id, di) => {
+      if (!String(id).startsWith("$") && !workflowIds.has(id)) {
+        problems.push(problem("error", `${wp}.dependsOn[${di}]`, `no workflow "${id}"`));
+      }
+    });
+
+    checkActions(
+      doc,
+      w?.successActions,
+      "successActions",
+      `${wp}.successActions`,
+      stepIds,
+      workflowIds,
+      problems,
+    );
+    checkActions(
+      doc,
+      w?.failureActions,
+      "failureActions",
+      `${wp}.failureActions`,
+      stepIds,
+      workflowIds,
+      problems,
+    );
+    steps.forEach((s, si) => {
+      const sp = `${wp}.steps[${si}]`;
+      checkActions(
+        doc,
+        s?.onSuccess,
+        "successActions",
+        `${sp}.onSuccess`,
+        stepIds,
+        workflowIds,
+        problems,
+      );
+      checkActions(
+        doc,
+        s?.onFailure,
+        "failureActions",
+        `${sp}.onFailure`,
+        stepIds,
+        workflowIds,
+        problems,
+      );
+      for (const ref of collectRefs([s?.parameters, s?.requestBody])) {
+        if (ref.kind === "step" && !stepIds.has(ref.stepId)) {
+          problems.push(problem("error", sp, `refers to unknown step "${ref.stepId}"`));
+        }
+      }
+    });
+    for (const ref of collectRefs(w?.outputs)) {
+      if (ref.kind === "step" && !stepIds.has(ref.stepId)) {
+        problems.push(problem("error", `${wp}.outputs`, `refers to unknown step "${ref.stepId}"`));
+      }
+    }
+  });
+
+  return problems;
+}

package/src/utils/arazzo/refs.js

@@ -0,0 +1,40 @@
+/**
+ * Finds Arazzo runtime expressions ($inputs, $steps, $workflows) inside any value.
+ */
+
+const EXPRESSION =
+  /\$(inputs|steps|workflows)\.([A-Za-z0-9_-]+)(?:\.([A-Za-z0-9_-]+)(?:\.([A-Za-z0-9_-]+))?)?/g;
+
+function scan(value, out, seen) {
+  if (typeof value === "string") {
+    for (const m of value.matchAll(EXPRESSION)) {
+      const [expr, root, a, b, c] = m;
+      let ref;
+      if (root === "inputs") ref = { kind: "input", name: a, expr };
+      else if (root === "steps" && b === "outputs" && c)
+        ref = { kind: "step", stepId: a, name: c, expr };
+      else if (root === "steps") ref = { kind: "step", stepId: a, name: "", expr };
+      else if (b === "outputs" && c) ref = { kind: "workflow", workflowId: a, name: c, expr };
+      else ref = { kind: "workflow", workflowId: a, name: "", expr };
+      if (!seen.has(expr)) {
+        seen.add(expr);
+        out.push(ref);
+      }
+    }
+  } else if (Array.isArray(value)) {
+    for (const v of value) scan(v, out, seen);
+  } else if (value && typeof value === "object") {
+    for (const v of Object.values(value)) scan(v, out, seen);
+  }
+}
+
+/**
+ * @param {*} value Any JSON value: parameters, a request body, outputs
+ * @returns {{ kind: 'input'|'step'|'workflow', name: string, stepId?: string, workflowId?: string, expr: string }[]}
+ *   distinct references in the order they first appear
+ */
+export function collectRefs(value) {
+  const out = [];
+  scan(value, out, new Set());
+  return out;
+}