@capagents/forgeqe 0.0.0-stage → 1.0.1

package/src/api/scenario.ts

@@ -0,0 +1,502 @@
+import { mkdirSync, writeFileSync } from "node:fs"
+import path from "node:path"
+
+import { callContract, xmlEscape, type RunOptions } from "./run.ts"
+import { getPath } from "./schema.ts"
+import { groupCall, parseJson, type NetworkCall } from "./traffic.ts"
+import type { Contract, ContractSet, JsonSchema, Scenario, ScenarioResult, ScenarioRun, ScenarioStep, StepResult } from "./types.ts"
+
+/**
+ * End-to-end API scenarios: calls in order, each later call using values earlier answers gave. They come from a
+ * browser run (the calls the application made, with the values that flowed from one answer into a later request found
+ * and turned into variables), from an API description (each resource's lifecycle, browsing from a list to an item,
+ * the description's links, and negative cases), or from a test case or plain English (planned by the agent: plan.ts).
+ * ForgeQE runs them itself: no browser, no model.
+ */
+
+const TEMPLATE = /\{\{\s*(\$?\w+)\s*\}\}/g
+const WHOLE = /^\{\{\s*(\$?\w+)\s*\}\}$/
+export const BUILTINS = ["$unique", "$uuid", "$now", "$randomInt"]
+
+class MissingVar extends Error {}
+
+function lookup(name: string, vars: Record<string, unknown>): unknown {
+  if (name in vars) return vars[name]
+  throw new MissingVar(`uses {{${name}}}, which no earlier step saved`)
+}
+
+/** A value with {{name}} filled in. A string that is only {{name}} becomes the value itself, keeping its type. */
+export function fill(v: unknown, vars: Record<string, unknown>): unknown {
+  if (typeof v === "string") {
+    const whole = v.match(WHOLE)
+    if (whole) return lookup(whole[1], vars)
+    return v.replace(TEMPLATE, (_, n) => String(lookup(n, vars)))
+  }
+  if (Array.isArray(v)) return v.map((x) => fill(x, vars))
+  if (v && typeof v === "object") return Object.fromEntries(Object.entries(v).map(([k, x]) => [k, fill(x, vars)]))
+  return v
+}
+
+/** The variables a step uses. */
+export function usedVars(step: Pick<ScenarioStep, "path" | "query" | "headers" | "body">): string[] {
+  const text = JSON.stringify([step.path, step.query || {}, step.headers || {}, step.body ?? null])
+  return [...new Set([...text.matchAll(TEMPLATE)].map((m) => m[1]))]
+}
+
+/** What is wrong with a scenario before it runs: variables used before any step saves them. */
+export function scenarioProblems(s: Scenario): string[] {
+  const known = new Set(BUILTINS)
+  const out: string[] = []
+  for (const step of s.steps) {
+    for (const v of usedVars(step)) if (!known.has(v)) out.push(`${step.name} uses {{${v}}}, which no earlier step saves`)
+    for (const v of Object.keys(step.save || {})) known.add(v)
+  }
+  return out
+}
+
+function freshVars(): Record<string, unknown> {
+  return { $unique: `${Date.now().toString(36)}${Math.random().toString(36).slice(2, 6)}`, $uuid: crypto.randomUUID(), $now: new Date().toISOString(), $randomInt: Math.floor(Math.random() * 1_000_000) }
+}
+
+function stepContract(step: ScenarioStep, vars: Record<string, unknown>, ops: Map<string, Contract>): Contract {
+  const op = step.operation ? ops.get(step.operation) : undefined
+  const pathFilled = step.path.replace(TEMPLATE, (_, n) => encodeURIComponent(String(lookup(n, vars))))
+  return {
+    id: step.name,
+    protocol: step.protocol,
+    name: step.name,
+    method: step.method,
+    path: step.path,
+    example: {
+      path: pathFilled,
+      ...(step.query ? { query: fill(step.query, vars) as Record<string, string> } : {}),
+      ...(step.headers ? { headers: fill(step.headers, vars) as Record<string, string> } : {}),
+      ...(step.body !== undefined ? { body: fill(step.body, vars) } : {}),
+    },
+    expect: step.expect,
+    ...(op?.auth ? { auth: op.auth } : {}),
+    writes: false,
+    source: { kind: "run", ref: "" },
+  }
+}
+
+async function runSteps(steps: ScenarioStep[], vars: Record<string, unknown>, base: string, headers: Record<string, string>, ops: Map<string, Contract>, opts: RunOptions): Promise<{ results: StepResult[]; ok: boolean; error?: string }> {
+  const results: StepResult[] = []
+  let failed = false
+  let error: string | undefined
+  for (const step of steps) {
+    if (failed || opts.signal?.aborted) {
+      results.push({ id: step.name, name: step.name, status: "skipped", checks: [], reason: opts.signal?.aborted ? "stopped" : "an earlier step failed" })
+      continue
+    }
+    try {
+      const c = stepContract(step, vars, ops)
+      const { result, body } = await callContract(c, base, step.noAuth ? {} : headers, opts)
+      for (const [name, p] of Object.entries(step.save || {})) {
+        const v = getPath(body, p)
+        if (v === undefined || v === null) result.checks.push({ name: `save ${name}`, ok: false, detail: `nothing at ${p} in the answer` })
+        else vars[name] = v
+      }
+      if (result.checks.some((x) => !x.ok)) result.status = "failed"
+      results.push({ ...result, name: step.name })
+      if (result.status !== "passed") failed = true
+    } catch (err) {
+      const msg = err instanceof Error ? (err.name === "TimeoutError" ? `no answer in ${opts.timeoutSeconds || 30}s` : err.message) : String(err)
+      results.push({ id: step.name, name: step.name, status: "error", checks: [], reason: msg })
+      failed = true
+      error = msg
+    }
+  }
+  return { results, ok: !failed, error }
+}
+
+/** Run each scenario: its steps in order, values passed on, and its cleanup when it fails part-way. */
+export async function runScenarios(set: ContractSet, opts: RunOptions): Promise<ScenarioRun> {
+  const base = (opts.baseUrl || set.baseUrl || "").replace(/\/+$/, "")
+  const headers = opts.headers || {}
+  const ops = new Map(set.contracts.map((c) => [c.id, c]))
+  const only = (opts.only || []).map((s) => s.toLowerCase()).filter(Boolean)
+  const results: ScenarioResult[] = []
+  for (const s of set.scenarios || []) {
+    if (only.length && !only.some((o) => `${s.id} ${s.name} ${s.caseId || ""}`.toLowerCase().includes(o))) continue
+    if (opts.signal?.aborted) break
+    const started = Date.now()
+    const problems = scenarioProblems(s)
+    let r: ScenarioResult
+    if (s.writes && !opts.allowWrites) r = { id: s.id, name: s.name, status: "skipped", steps: [], reason: "changes data: run with allow_writes on a test environment", ms: 0 }
+    else if (problems.length) r = { id: s.id, name: s.name, status: "error", steps: [], reason: problems.join("; "), ms: 0 }
+    else if (!base && !s.steps.every((x) => /^https?:\/\//.test(x.path))) r = { id: s.id, name: s.name, status: "skipped", steps: [], reason: "no base URL: pass base_url or set api.base_url", ms: 0 }
+    else {
+      const vars = freshVars()
+      const run = await runSteps(s.steps, vars, base, headers, ops, opts)
+      let cleanup: StepResult[] | undefined
+      if (!run.ok && s.cleanup?.length) {
+        // Only the cleanup steps whose values exist: what the scenario did not create, it does not delete.
+        const ready = s.cleanup.filter((c) => usedVars(c).every((v) => v in vars))
+        if (ready.length) cleanup = (await runSteps(ready, vars, base, headers, ops, { ...opts, signal: undefined })).results
+      }
+      r = { id: s.id, name: s.name, status: run.error ? "error" : run.ok ? "passed" : "failed", steps: run.results, ...(cleanup ? { cleanup } : {}), ms: Date.now() - started }
+    }
+    results.push(r)
+  }
+  const counts = { passed: 0, failed: 0, skipped: 0, error: 0 }
+  for (const r of results) counts[r.status]++
+  const run: ScenarioRun = { set: set.id, baseUrl: base, at: new Date().toISOString(), results, counts, dir: opts.dir }
+  mkdirSync(opts.dir, { recursive: true })
+  writeFileSync(path.join(opts.dir, "scenario-results.json"), JSON.stringify(run, null, 2))
+  writeFileSync(path.join(opts.dir, "scenarios-junit.xml"), scenarioJunit(run))
+  return run
+}
+
+export function scenarioJunit(run: ScenarioRun): string {
+  const suites = run.results.map((r) => {
+    const cases = r.steps.length
+      ? r.steps.map((st) => {
+          const head = `    <testcase classname="${xmlEscape(r.name)}" name="${xmlEscape(st.name)}" time="${((st.ms || 0) / 1000).toFixed(3)}"`
+          if (st.status === "passed") return `${head}/>`
+          if (st.status === "skipped") return `${head}><skipped message="${xmlEscape(st.reason || "")}"/></testcase>`
+          const msg = st.reason || st.checks.filter((c) => !c.ok).map((c) => `${c.name}: ${c.detail || "failed"}`).join("; ")
+          return `${head}><${st.status === "error" ? "error" : "failure"} message="${xmlEscape(msg)}"/></testcase>`
+        })
+      : [`    <testcase classname="${xmlEscape(r.name)}" name="${xmlEscape(r.name)}">${r.status === "skipped" ? `<skipped message="${xmlEscape(r.reason || "")}"/>` : `<error message="${xmlEscape(r.reason || "")}"/>`}</testcase>`]
+    const failures = r.steps.filter((s) => s.status === "failed").length
+    return `  <testsuite name="${xmlEscape(r.name)}" tests="${cases.length}" failures="${failures}" time="${(r.ms / 1000).toFixed(3)}">\n${cases.join("\n")}\n  </testsuite>`
+  })
+  return `<?xml version="1.0" encoding="UTF-8"?>\n<testsuites>\n${suites.join("\n")}\n</testsuites>\n`
+}
+
+// -- helpers --------------------------------------------------------------------------------------
+
+export function slug(s: string): string {
+  return s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 60) || "scenario"
+}
+
+function uniqueIds(scenarios: Scenario[], taken: string[] = []): Scenario[] {
+  const seen = new Set(taken)
+  for (const s of scenarios) {
+    let id = s.id
+    for (let n = 2; seen.has(id); n++) id = `${s.id}-${n}`
+    s.id = id
+    seen.add(id)
+  }
+  return scenarios
+}
+
+const camel = (s: string) => s.replace(/[-_\s]+(\w)/g, (_, c: string) => c.toUpperCase()).replace(/^\w/, (c) => c.toLowerCase())
+
+const singular = (w: string) => (/ies$/.test(w) ? w.replace(/ies$/, "y") : /(ss|us)$/.test(w) ? w : w.replace(/s$/, ""))
+
+/** The resource a path names: its last segment that is not a parameter or a version. */
+function resourceOf(p: string): string {
+  const segs = p.split("/").filter((x) => x && !x.includes("{") && !/^(api|v\d+(\.\d+)?|rest|graphql)$/i.test(x) && !/\d/.test(x))
+  return segs[segs.length - 1] || "item"
+}
+
+/** Unique data for a create: an email or username that would clash on the next run gets {{$unique}} in it. */
+function uniqueData(body: unknown): unknown {
+  if (Array.isArray(body)) return body.map(uniqueData)
+  if (!body || typeof body !== "object") return body
+  return Object.fromEntries(
+    Object.entries(body).map(([k, v]) => {
+      if (typeof v === "string" && !v.includes("{{")) {
+        if (/^e?-?mail(address)?$/i.test(k.replace(/_/g, "")) && v.includes("@")) return [k, v.replace("@", "+{{$unique}}@")]
+        if (/^(user_?name|login|handle)$/i.test(k)) return [k, `${v}-{{$unique}}`]
+      }
+      return [k, uniqueData(v)]
+    }),
+  )
+}
+
+// -- from a browser run ---------------------------------------------------------------------------
+
+const ID_LEAF = /(^|[_-]|[a-z])(id|Id|ID|key|Key|uuid|Uuid|UUID|token|code|Code|number|Number|no|No|ref|Ref|slug)$/
+const ID_SHAPED = (s: string) =>
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(s) || /^[0-9a-f]{16,}$/i.test(s) || (/\d/.test(s) && /[A-Za-z]/.test(s) && /^[\w-]{6,}$/.test(s))
+
+type Produced = { step: number; path: string; leaf: string; value: string; name?: string }
+
+/** Every scalar in an answer with its path (all array elements, up to 20 each). */
+function scalarsOf(v: unknown, at = "", depth = 0, out: [string, unknown][] = []): [string, unknown][] {
+  if (depth > 5 || out.length > 400) return out
+  if (Array.isArray(v)) v.slice(0, 20).forEach((x, i) => scalarsOf(x, `${at}[${i}]`, depth + 1, out))
+  else if (v && typeof v === "object") for (const [k, x] of Object.entries(v)) scalarsOf(x, at ? `${at}.${k}` : k, depth + 1, out)
+  else if (at && (typeof v === "string" || typeof v === "number")) out.push([at, v])
+  return out
+}
+
+const leafOf = (p: string) => p.split(/[.[]/).pop()!.replace(/]$/, "")
+
+function candidate(leaf: string, value: unknown): boolean {
+  if (typeof value === "number") return Number.isInteger(value) && value > 1 && ID_LEAF.test(leaf)
+  if (typeof value !== "string" || !value || value === "<redacted>" || value.length > 200) return false
+  return ID_SHAPED(value) || (ID_LEAF.test(leaf) && /^[\w.:-]{1,80}$/.test(value) && /\d/.test(value))
+}
+
+/** A request field may take a produced value: an id-like field, the same field name, or a value that can only be an id. */
+const accepts = (leaf: string, p: Produced) => ID_LEAF.test(leaf) || leaf === p.leaf || ID_SHAPED(p.value)
+
+/**
+ * One scenario from a run's calls, in the order the application made them. A value an answer gave that a later
+ * request sends (in its path, query, or body) becomes a variable: saved from that answer, used in that request. The
+ * same GET made again (polling, refreshes) is kept once; at most 40 steps.
+ */
+export function scenarioFromRun(calls: NetworkCall[], set: ContractSet, opts: { goal?: string; runId?: string; thirdParty?: boolean } = {}): Scenario | null {
+  const base = set.baseUrl
+  const ordered = calls
+    .filter((c) => !c.failed && c.response?.status && (opts.thirdParty || !c.third_party))
+    .sort((a, b) => a.t - b.t)
+  const steps: ScenarioStep[] = []
+  const producers = new Map<string, Produced>()
+  const names = new Map<string, string>()
+  const flows: string[] = []
+  const seenGets = new Set<string>()
+  let dropped = 0
+  const varFor = (p: Produced): string => {
+    if (p.name) return p.name
+    const key = `${p.step}:${p.path}`
+    const have = names.get(key)
+    if (have) return (p.name = have)
+    let name = /^id$/i.test(p.leaf) ? `${camel(singular(resourceOf(steps[p.step].path)))}Id` : camel(p.leaf)
+    const taken = new Set(names.values())
+    for (let n = 2; taken.has(name); n++) name = `${name.replace(/\d+$/, "")}${n}`
+    names.set(key, name)
+    steps[p.step].save = { ...(steps[p.step].save || {}), [name]: p.path }
+    flows.push(`${name}: from step ${p.step + 1} (${steps[p.step].name})`)
+    return (p.name = name)
+  }
+  const replaceIn = (value: unknown, at: string): unknown => {
+    if (Array.isArray(value)) return value.map((x, i) => replaceIn(x, `${at}[${i}]`))
+    if (value && typeof value === "object") return Object.fromEntries(Object.entries(value).map(([k, x]) => [k, replaceIn(x, at ? `${at}.${k}` : k)]))
+    if (typeof value !== "string" && typeof value !== "number") return value
+    const p = producers.get(String(value))
+    return p && accepts(leafOf(at), p) ? `{{${varFor(p)}}}` : value
+  }
+  for (const c of ordered) {
+    let u: URL
+    try {
+      u = new URL(c.url)
+    } catch {
+      continue
+    }
+    const g = groupCall(c)
+    if (!g) continue
+    if (c.method === "GET" && seenGets.has(c.url)) continue
+    if (steps.length >= 40) {
+      dropped++
+      continue
+    }
+    if (c.method === "GET") seenGets.add(c.url)
+    const contract = set.contracts.find((x) => x.id === g.key)
+    const segs = u.pathname.split("/").map((seg) => {
+      const p = producers.get(decodeURIComponent(seg))
+      return p && seg ? `{{${varFor(p)}}}` : seg
+    })
+    const pathname = segs.join("/")
+    const query: Record<string, string> = {}
+    for (const [k, v] of u.searchParams) query[k] = String(replaceIn(v, k))
+    let body: unknown = c.request.body === undefined ? undefined : (parseJson(c.request.body) ?? c.request.body)
+    if (typeof body === "string") {
+      let text = body
+      for (const [value, p] of producers) if (ID_SHAPED(value) && text.includes(value)) text = text.split(value).join(`{{${varFor(p)}}}`)
+      body = text
+    } else if (body !== undefined) body = replaceIn(body, "")
+    if (c.method === "POST" && /regist|sign-?up|users?$|accounts?$|customers?$/i.test(u.pathname)) body = uniqueData(body)
+    const headers = contract?.example.headers
+    const status = c.response.status
+    const expect: Contract["expect"] = contract && contract.expect.status === status ? { ...contract.expect } : { status }
+    const origin = u.origin === base ? "" : u.origin
+    steps.push({
+      name: g.protocol === "rest" ? `${c.method} ${g.path}` : g.key,
+      ...(contract ? { operation: contract.id } : {}),
+      protocol: g.protocol,
+      method: c.method,
+      path: `${origin}${pathname}`,
+      ...(Object.keys(query).length ? { query } : {}),
+      ...(headers ? { headers } : {}),
+      ...(body !== undefined ? { body } : {}),
+      expect,
+    })
+    const answer = parseJson(c.response.body)
+    for (const [p, v] of scalarsOf(answer)) {
+      const leaf = leafOf(p)
+      // The first answer that gave a value owns it: a later answer that echoes it (a GET of the same cart) is not a new source.
+      if (candidate(leaf, v) && !producers.has(String(v))) producers.set(String(v), { step: steps.length - 1, path: p, leaf, value: String(v) })
+    }
+  }
+  if (!steps.length) return null
+  const notes = [...new Set(flows)]
+  if (dropped) notes.push(`${dropped} more calls left out: scenarios keep the first 40`)
+  if (steps.some((s) => JSON.stringify(s.body ?? "").includes("{{$unique}}"))) notes.push("Emails and usernames sent to sign-up endpoints get {{$unique}}, so each run creates a new one.")
+  return {
+    id: "flow",
+    name: opts.goal ? `API flow: ${opts.goal.slice(0, 80)}` : "API flow of the browser run",
+    kind: "flow",
+    source: { kind: "run", ref: opts.runId || "" },
+    steps,
+    writes: steps.some((s) => !["GET", "HEAD", "OPTIONS"].includes(s.method) || (s.operation ? set.contracts.find((x) => x.id === s.operation)?.writes : false)),
+    ...(notes.length ? { notes } : {}),
+  }
+}
+
+// -- from an API description ----------------------------------------------------------------------
+
+function stepOf(c: Contract, over: Partial<ScenarioStep> = {}): ScenarioStep {
+  return {
+    name: c.id,
+    operation: c.id,
+    protocol: c.protocol,
+    method: c.method,
+    path: c.example.path,
+    ...(c.example.query ? { query: c.example.query } : {}),
+    ...(c.example.headers ? { headers: c.example.headers } : {}),
+    ...(c.example.body !== undefined ? { body: c.example.body } : {}),
+    expect: c.expect,
+    ...over,
+  }
+}
+
+/** The contract's example path with the segment of {param} in its template replaced by {{param}}. */
+function pathWithVar(c: Contract, param: string, value = `{{${param}}}`): string {
+  const tpl = c.path.split("/")
+  const concrete = c.example.path.split("/")
+  if (tpl.length !== concrete.length) return c.path.replace(`{${param}}`, value)
+  return concrete.map((seg, i) => (tpl[i] === `{${param}}` ? value : seg)).join("/")
+}
+
+const props = (s: JsonSchema | undefined): Record<string, JsonSchema> => s?.properties || s?.allOf?.reduce((a, x) => ({ ...a, ...(x.properties || {}) }), {} as Record<string, JsonSchema>) || {}
+
+/** Where an item's id is in an answer: the path parameter's own name, else id, else <resource>Id. */
+function idField(schema: JsonSchema | undefined, param: string, resource: string): string | null {
+  const p = props(schema)
+  for (const k of [param, "id", `${singular(resource)}Id`, `${singular(resource)}_id`]) if (k in p) return k
+  return Object.keys(p).find((k) => /(^|_)id$/i.test(k)) || null
+}
+
+/** The path in a list answer to its first item's id: [0].id, or items[0].id when the list is in a field. */
+function firstItemId(schema: JsonSchema | undefined, param: string, resource: string): string | null {
+  if (!schema) return null
+  if (schema.items) {
+    const f = idField(schema.items, param, resource)
+    return f ? `[0].${f}` : null
+  }
+  for (const [k, s] of Object.entries(props(schema))) {
+    if (s.items) {
+      const f = idField(s.items, param, resource)
+      if (f) return `${k}[0].${f}`
+    }
+  }
+  return null
+}
+
+const bodyPath = (expr: string): string | null => {
+  const m = expr.match(/^\$response\.body#\/(.*)$/)
+  return m ? m[1].split("/").map((s) => (/^\d+$/.test(s) ? `[${s}]` : s)).join(".").replace(/\.\[/g, "[") : null
+}
+
+/**
+ * Scenarios from a description's REST operations, with no model: for each resource with an item path
+ * (/pets and /pets/{petId}), its lifecycle (create, read, update, read, delete, read gives 404) and browsing (the list,
+ * then its first item); the description's links (an answer's value into the next operation); and negative cases: an
+ * id that does not exist gives 404, no credentials give 401 or 403, an empty body gives 400 or 422.
+ */
+export function scenariosFromSpec(set: ContractSet, opts: { negative?: boolean } = {}): { scenarios: Scenario[]; notes: string[] } {
+  const rest = set.contracts.filter((c) => c.protocol === "rest")
+  const notes: string[] = []
+  if (set.contracts.length > rest.length) notes.push("Scenarios from a description cover REST operations; GraphQL, SOAP and gRPC scenarios come from a browser run, a test case, or plain English.")
+  const by = new Map<string, Map<string, Contract>>()
+  for (const c of rest) {
+    const m = by.get(c.path) || new Map<string, Contract>()
+    m.set(c.method, c)
+    by.set(c.path, m)
+  }
+  const out: Scenario[] = []
+  const covered = new Set<string>()
+  const src = { kind: set.source.kind, ref: set.source.ref }
+  for (const [item, ops] of by) {
+    const m = item.match(/^(.*)\/\{(\w+)\}$/)
+    if (!m) continue
+    const [, collection, param] = m
+    const coll = by.get(collection) || new Map<string, Contract>()
+    const resource = resourceOf(collection)
+    const label = singular(resource)
+    const create = coll.get("POST")
+    const list = coll.get("GET")
+    const read = ops.get("GET")
+    const update = ops.get("PUT") || ops.get("PATCH")
+    const del = ops.get("DELETE")
+    const at = (c: Contract) => pathWithVar(c, param)
+    if (create && (read || update || del)) {
+      const link = create.links?.map((l) => l.parameters[param]).map((e) => (e ? bodyPath(e) : null)).find(Boolean)
+      const idPath = link || idField(create.expect.schema, param, resource)
+      if (!idPath) notes.push(`${create.id}: its answer has no id field ForgeQE can tell, so the ${label} lifecycle is not made`)
+      else {
+        const steps: ScenarioStep[] = [stepOf(create, { name: `Create a ${label}`, body: uniqueData(create.example.body), save: { [param]: idPath } })]
+        if (read) steps.push(stepOf(read, { name: `Read the ${label}`, path: at(read) }))
+        if (update) {
+          const body = update.example.body && typeof update.example.body === "object" && !Array.isArray(update.example.body) ? Object.fromEntries(Object.entries(update.example.body as Record<string, unknown>).map(([k, v]) => [k, k === idPath || k === param ? `{{${param}}}` : v])) : update.example.body
+          steps.push(stepOf(update, { name: `Update the ${label}`, path: at(update), ...(body !== undefined ? { body } : {}) }))
+          if (read) steps.push(stepOf(read, { name: `Read the ${label} after the update`, path: at(read) }))
+        }
+        if (del) {
+          steps.push(stepOf(del, { name: `Delete the ${label}`, path: at(del) }))
+          if (read) steps.push(stepOf(read, { name: `The deleted ${label} is gone`, path: at(read), expect: { status: 404, statusIn: [404, 410] } }))
+        }
+        const made = create.needsData?.some((n) => n.startsWith("request body")) ? [`The create body is made from the schema: give real values in scenarios in contracts.json if the API rejects it.`] : []
+        out.push({ id: `${slug(label)}-lifecycle`, name: `${label} lifecycle: create, read${update ? ", update" : ""}${del ? ", delete" : ""}`, kind: "lifecycle", source: src, steps, ...(del ? { cleanup: [stepOf(del, { name: `Clean up: delete the ${label}`, path: at(del), expect: { status: del.expect.status, statusIn: [del.expect.status, 200, 202, 204, 404] } })] } : {}), writes: true, ...(made.length ? { notes: made } : {}) })
+        for (const c of [create, read, update, del]) if (c) covered.add(c.id)
+      }
+    }
+    if (list && read) {
+      const first = firstItemId(list.expect.schema, param, resource)
+      if (first)
+        out.push({
+          id: `${slug(label)}-browse`,
+          name: `Browse ${resource}: the list, then its first ${label}`,
+          kind: "browse",
+          source: src,
+          steps: [stepOf(list, { name: `List ${resource}`, save: { [param]: first } }), stepOf(read, { name: `Open the first ${label}`, path: at(read) })],
+          writes: false,
+          notes: [`Needs at least one ${label} in the list.`, ...(list.needsData?.length ? [`The list needs real values for ${list.needsData.join(", ")}.`] : [])],
+        })
+    }
+    if (opts.negative !== false) {
+      if (read) {
+        const sample = read.example.path.split("/")[read.path.split("/").indexOf(`{${param}}`)] || ""
+        const missing = /^[0-9a-f-]{36}$/i.test(sample) ? "00000000-0000-4000-8000-000000000000" : /^\d+$/.test(sample) || !sample ? "999999999" : `does-not-exist-{{$unique}}`
+        out.push({ id: `${slug(label)}-not-found`, name: `A ${label} that does not exist gives 404`, kind: "negative", source: src, steps: [stepOf(read, { name: `Read a ${label} that does not exist`, path: pathWithVar(read, param, missing), expect: { status: 404, statusIn: [404, 410] } })], writes: false })
+      }
+      const guarded = [list, read].find((c) => c?.auth && !c.needsData?.length)
+      if (guarded)
+        out.push({ id: `${slug(label)}-no-auth`, name: `${guarded.id} without credentials is refused`, kind: "negative", source: src, steps: [stepOf(guarded, { name: `${guarded.id} without credentials`, noAuth: true, expect: { status: 401, statusIn: [401, 403] } })], writes: false })
+      if (create?.requestRequired?.length)
+        out.push({ id: `${slug(label)}-invalid-body`, name: `Creating a ${label} without its required fields is refused`, kind: "negative", source: src, steps: [stepOf(create, { name: `Create a ${label} with an empty body`, body: {}, expect: { status: 400, statusIn: [400, 422] } })], writes: true, notes: [`Required: ${create.requestRequired.join(", ")}. If the API accepts the empty body, this creates a ${label}.`] })
+    }
+  }
+  // The description's links: an answer's value into the next operation.
+  const byOpId = new Map(rest.filter((c) => c.operationId).map((c) => [c.operationId!, c]))
+  for (const a of rest) {
+    for (const l of a.links || []) {
+      const b = byOpId.get(l.operationId)
+      if (!b || (covered.has(a.id) && covered.has(b.id))) continue
+      const save: Record<string, string> = {}
+      let p = b.example.path
+      const query = { ...(b.example.query || {}) }
+      for (const [param, expr] of Object.entries(l.parameters)) {
+        const from = bodyPath(expr)
+        if (!from) continue
+        save[param] = from
+        if (b.path.includes(`{${param}}`)) p = pathWithVar({ ...b, example: { ...b.example, path: p } }, param)
+        else query[param] = `{{${param}}}`
+      }
+      if (!Object.keys(save).length) continue
+      out.push({ id: `${slug(a.operationId || a.id)}-then-${slug(l.operationId)}`, name: `${a.operationId || a.id}, then ${l.operationId} with its answer`, kind: "linked", source: src, steps: [stepOf(a, { save, ...(a.writes ? { body: uniqueData(a.example.body) } : {}) }), stepOf(b, { path: p, ...(Object.keys(query).length ? { query } : {}) })], writes: a.writes || b.writes })
+    }
+  }
+  return { scenarios: uniqueIds(out), notes }
+}
+
+/** Add scenarios to a set, with ids unique in it. */
+export function addScenarios(set: ContractSet, scenarios: Scenario[], replaceKinds: string[] = []): ContractSet {
+  const kept = (set.scenarios || []).filter((s) => !replaceKinds.includes(s.kind))
+  return { ...set, scenarios: [...kept, ...uniqueIds(scenarios, kept.map((s) => s.id))] }
+}