@specbook/codegen 0.8.1 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specbook/codegen",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "description": "Turns an OpenAPI or Swagger document into types, examples, schemas and metadata, in Node or in a browser.",
   "keywords": [
     "specbook",
@@ -32,6 +32,10 @@
     "./browser": {
       "types": "./src/browser.ts",
       "default": "./src/browser.ts"
+    },
+    "./union": {
+      "types": "./src/union.ts",
+      "default": "./src/union.ts"
     }
   },
   "dependencies": {
@@ -40,7 +44,7 @@
     "swagger2openapi": "7.0.8"
   },
   "devDependencies": {
-    "@specbook/core": "0.8.1",
+    "@specbook/core": "0.9.0",
     "@types/node": "24.19.2",
     "@types/swagger2openapi": "7.0.4",
     "typescript": "7.0.2"

package/src/build.ts

@@ -4,13 +4,16 @@ import {
   jsdoc,
   objectType,
   pascal,
+  propKey,
   type Schema,
   safeIdent,
   sanitizeExample,
   synthesize,
+  synthesizeVariant,
   toJsonSchema,
   tsType,
 } from './schema'
+import { flatProps, nameOf, pinnedValue, subtypeTag, unionOf } from './union'
 
 export interface GenerateOptions {
   /** Path/URL to the spec, or an already-parsed object. */
@@ -78,6 +81,11 @@ export interface ManifestOperation {
   description?: string
   tags: string[]
   statuses: number[]
+  /**
+   * The answers a status's example file holds, when there are several: a `oneOf` response (one per branch) or a
+   * response with named `examples`. Keyed by status; the file is `{ "$variants": [...] }` (see core's `mock-variants`).
+   */
+  mockVariants?: Record<string, { name: string; title?: string; tag?: string }[]>
   examples: ManifestExample[]
   /** the spec requires credentials for this operation */
   secured?: boolean
@@ -110,6 +118,7 @@ const BODY_ENCODINGS: [string, string][] = [
   ['text/plain', 'text'],
 ]
 const BINARY_MIME = /^(application\/(octet-stream|pdf|zip|gzip)|(image|audio|video)\/)/
+const WILDCARD_MIME = /^(\*|application)\/\*$/
 
 function findJsonLike(content: Record<string, any> | undefined) {
   if (!content) return undefined
@@ -136,6 +145,19 @@ function findJsonLike(content: Record<string, any> | undefined) {
       media: content[binary],
       mediaType: binary,
     }
+  // A wildcard stands for whatever the server sends, and a framework that is not told what it produces
+  // declares every response that way (springdoc's `*/*`). It is JSON, unless the schema is a file.
+  const any = Object.keys(content).find((m) => WILDCARD_MIME.test(m))
+  if (any) {
+    const schema = content[any].schema as Schema | undefined
+    const file = schema?.format === 'binary'
+    return {
+      schema,
+      encoding: file ? 'binary' : 'json',
+      media: content[any],
+      ...(file ? { mediaType: any } : {}),
+    }
+  }
   return undefined
 }
 
@@ -274,20 +296,97 @@ function generateAll(
   // what the spec says about a field elsewhere in the document; read on first use
   const index = makeValueIndex(doc)
   /**
-   * The response example the spec gives, when it has one. The one `example` is shown as written; a named one only
-   * when it satisfies the response schema, since specs' own examples often leave out a required field.
+   * What the example file of a response holds: a bare body, or when the spec gives several answers for the status, a
+   * `{ "$variants": [...] }` envelope that the mock reads (core's `mock-variants`). Several named `examples` are those
+   * answers; a union response has one per branch (found on the document's own schema, not the one written for the
+   * browser, where `nullable` wraps a reference in an `anyOf`).
    */
-  const specExample = (media: any, schema: Schema, status: number): unknown => {
-    if (media?.example !== undefined) return sanitizeExample(media.example, '', undefined, status)
-    const named = firstExample(media?.examples)
-    if (named === undefined) return undefined
-    const value = sanitizeExample(named, '', undefined, status)
-    return conforms(schema, value, resolve) ? value : undefined
+  const responseExample = (
+    media: any,
+    schema: Schema,
+    status: number,
+  ): { file: unknown; variants?: { name: string; title?: string; tag?: string }[] } => {
+    const used = new Set<string>()
+    const unique = (name: string) => {
+      let n = name
+      while (used.has(n)) n += '-2'
+      used.add(n)
+      return n
+    }
+    const wrap = (list: { name: string; title?: string; tag?: string; body: unknown }[]) =>
+      list.length < 2
+        ? undefined
+        : {
+            file: { $variants: list },
+            variants: list.map(({ body: _b, ...rest }) => rest),
+          }
+    if (media?.example !== undefined)
+      return { file: sanitizeExample(media.example, '', undefined, status) }
+    const fitting: { name: string; title?: string; body: unknown }[] = []
+    for (const [key, raw] of Object.entries<any>(media?.examples ?? {})) {
+      const ex = resolveAny<any>(raw)
+      if (ex?.value === undefined) continue
+      const body = sanitizeExample(ex.value, '', undefined, status)
+      if (!conforms(schema, body, resolve)) continue
+      fitting.push({
+        name: unique(key),
+        ...(typeof ex.summary === 'string' ? { title: ex.summary } : {}),
+        body,
+      })
+    }
+    const several = wrap(fitting)
+    if (several) return several
+    const root = schema.$ref ? resolve(schema.$ref) : schema
+    const union = unionOf(root, { resolve })
+    if (union && union.branches.length >= 2 && root) {
+      used.clear()
+      const list = union.branches.map((b, i) => {
+        const target = b.schema.$ref ? resolve(b.schema.$ref) : b.schema
+        const title = typeof target?.title === 'string' ? target.title : undefined
+        return {
+          name: unique(b.name ?? b.tag ?? `variant-${i + 1}`),
+          ...(title && title !== b.name ? { title } : {}),
+          ...(b.tag !== undefined ? { tag: b.tag } : {}),
+          body: synthesizeVariant(root, union, i, resolve, status, false, index),
+        }
+      })
+      // the spec's one example stands for the variant it names, not for all of them
+      const only = fitting[0]
+      if (only) {
+        const at = union.tagProp
+          ? list.findIndex(
+              (v) =>
+                v.tag !== undefined &&
+                (only.body as Record<string, unknown>)?.[union.tagProp as string] === v.tag,
+            )
+          : -1
+        const into = list[at >= 0 ? at : 0]
+        if (into) into.body = only.body
+      }
+      return wrap(list) as ReturnType<typeof responseExample>
+    }
+    if (fitting[0]) return { file: fitting[0].body }
+    return { file: synthesize(schema, resolve, 0, [], '', status, false, index) }
   }
 
   const files: GeneratedFile[] = []
   const operations: ManifestOperation[] = []
 
+  // The value that tells a variant apart is its type, so a flow can narrow on it (`item.kind === 'album'`): a base
+  // holds the `discriminator` and the variants only extend it, and a union can hold its own.
+  const tags = new Map<string, { prop: string; value: string }>()
+  if (ts) {
+    const ctx = { resolve }
+    for (const [name, schema] of Object.entries(schemas)) {
+      const own = subtypeTag(`#/components/schemas/${name}`, ctx)
+      if (own) tags.set(pascal(name), own)
+      const union = unionOf(schema, ctx)
+      if (union?.tagSource === 'discriminator' && union.tagProp)
+        for (const b of union.branches)
+          if (b.schema.$ref && b.tag !== undefined)
+            tags.set(pascal(nameOf(b.schema.$ref)), { prop: union.tagProp, value: b.tag })
+    }
+  }
   const typeBlocks: string[] = []
   for (const [name, schema] of ts ? Object.entries(schemas) : []) {
     const id = pascal(name)
@@ -300,6 +399,18 @@ function generateAll(
       (schema.type === 'object' || (!schema.type && schema.properties)) &&
       schema.properties
     const body = isObj ? objectType(schema) : undefined
+    const tag = tags.get(id)
+    // a variant that already pins the property itself (an `enum` of one value) says it
+    const pinned =
+      tag && pinnedValue(flatProps({ $ref: `#/components/schemas/${name}` }, { resolve })[tag.prop])
+    if (tag && pinned === undefined) {
+      const base = body ?? tsType(schema)
+      const whole = schema.oneOf || schema.anyOf ? `(${base})` : base
+      typeBlocks.push(
+        `${jsdoc(schema)}export type ${id} = ${whole} & { ${propKey(tag.prop)}: ${JSON.stringify(tag.value)} }`,
+      )
+      continue
+    }
     typeBlocks.push(
       body?.startsWith('{')
         ? `${jsdoc(schema)}export interface ${id} ${body}`
@@ -385,6 +496,12 @@ function generateAll(
       let hasDefault = false
       let defaultSchema: Schema | undefined
       const responseSchemas: Record<string, Schema> = {}
+      const mockVariants: NonNullable<ManifestOperation['mockVariants']> = {}
+      let defaultVariants: ManifestOperation['mockVariants'] extends infer M
+        ? M extends Record<string, infer V>
+          ? V | undefined
+          : never
+        : never
       for (const [code, rawRes] of Object.entries<any>(op.responses ?? {})) {
         if (code === 'default') {
           const found = findJsonLike(resolveAny<any>(rawRes)?.content)
@@ -392,12 +509,11 @@ function generateAll(
             hasDefault = true
             if (ts) defaultType = tsType(found.schema, '  ', 'T.')
             defaultSchema = toJsonSchema(found.schema, `${defsId}#/$defs/`)
-            const example =
-              specExample(found.media, found.schema, -1) ??
-              synthesize(found.schema, resolve, 0, [], '', -1, false, index)
+            const example = responseExample(found.media, found.schema, -1)
+            defaultVariants = example.variants
             exampleFiles.push({
               path: `examples/${id}/default.response.json`,
-              content: `${JSON.stringify(example, null, 2)}\n`,
+              content: `${JSON.stringify(example.file, null, 2)}\n`,
             })
           }
           continue
@@ -412,12 +528,11 @@ function generateAll(
             `${code}: ${found?.schema ? tsType(found.schema, '  ', 'T.') : 'unknown'}`,
           )
         if (found?.schema) {
-          const example =
-            specExample(found.media, found.schema, Number(code)) ??
-            synthesize(found.schema, resolve, 0, [], '', Number(code), false, index)
+          const example = responseExample(found.media, found.schema, Number(code))
+          if (example.variants) mockVariants[code] = example.variants
           exampleFiles.push({
             path: `examples/${id}/${code}.response.json`,
-            content: `${JSON.stringify(example, null, 2)}\n`,
+            content: `${JSON.stringify(example.file, null, 2)}\n`,
           })
         }
       }
@@ -426,6 +541,7 @@ function generateAll(
           if (statuses.includes(st)) continue
           statuses.push(st)
           if (defaultSchema) responseSchemas[String(st)] = defaultSchema
+          if (defaultVariants) mockVariants[String(st)] = defaultVariants
           if (defaultType) responseTypes.push(`${st}: ${defaultType}`)
         }
       }
@@ -590,6 +706,7 @@ ${jsdoc({ description: [...new Set([op.summary, op.description].filter(Boolean))
         ...(op.description && op.description !== summary ? { description: op.description } : {}),
         tags,
         statuses,
+        ...(Object.keys(mockVariants).length ? { mockVariants } : {}),
         examples: docs.map((d) => ({ name: d.name, title: d.title, source: d.source })),
         ...(secured ? { secured: true } : {}),
         file: `operations/${id}.ts`,

package/src/hints.ts

@@ -120,7 +120,7 @@ export function conforms(
   if (value === null) return nullable(schema, resolve)
   if (schema.allOf && !schema.allOf.every((b: Schema) => conforms(b, value, resolve, d + 1)))
     return false
-  // the viewer checks a value against the first branch of its own kind, so that is the branch it has to fit
+  // a value fits a union when it fits any branch of its own kind (a spec's example for the second variant is as good)
   const alts: Schema[] | undefined = schema.oneOf ?? schema.anyOf
   if (alts?.length) {
     const want = Array.isArray(value) ? 'array' : typeof value
@@ -128,7 +128,13 @@ export function conforms(
       const k = kindOf(b, resolve)
       return k === want || (k === 'integer' && want === 'number')
     }
-    if (!conforms(alts.find(same) ?? alts[0], value, resolve, d + 1)) return false
+    const ofKind = alts.filter(same)
+    if (
+      !(ofKind.length ? ofKind : [alts[0] as Schema]).some((b) =>
+        conforms(b, value, resolve, d + 1),
+      )
+    )
+      return false
   }
   if (!fits(schema, value)) return false
   if (Array.isArray(value))

package/src/schema.ts

@@ -8,6 +8,7 @@ import {
   PLACEHOLDER_VALUE,
   type ValueIndex,
 } from './hints'
+import { flatProps, subtypeTag, type UnionContext, type UnionInfo, unionOf } from './union'
 
 export type Schema = Record<string, any>
 
@@ -61,6 +62,8 @@ export function tsType(schema: Schema | undefined, indent = '', p = ''): string
   let base: string
   if (schema.enum) {
     base = schema.enum.map((v: unknown) => JSON.stringify(v)).join(' | ') || 'never'
+  } else if (schema.const !== undefined) {
+    base = JSON.stringify(schema.const)
   } else if (schema.allOf) {
     base = schema.allOf.map((s: Schema) => paren(tsType(s, indent, p))).join(' & ')
   } else if (schema.oneOf || schema.anyOf) {
@@ -456,6 +459,63 @@ export function sanitizeExample(
 /** A hard stop for chains of *required* objects, which is all an example follows past MAX_DEPTH. */
 const HARD_DEPTH = 14
 
+/** How many items of a list of variants a success response shows: one of each kind, up to this many. */
+const FANOUT = 3
+
+const isPlainObject = (v: unknown): v is Record<string, unknown> =>
+  !!v && typeof v === 'object' && !Array.isArray(v)
+
+/**
+ * Writes the value that tells a variant apart (`kind: "album"`) into its example. The tag is the document's
+ * `discriminator` value, not the name heuristic's guess; a property declared with other values keeps what it has.
+ */
+function applyTag(
+  out: unknown,
+  prop: string,
+  value: string,
+  ref: string,
+  ctx: UnionContext,
+): unknown {
+  if (!isPlainObject(out)) return out
+  const declared = flatProps(ctx.resolve(ref), ctx)[prop]
+  if (declared?.enum && !declared.enum.includes(value)) return out
+  if (declared?.const !== undefined && declared.const !== value) return out
+  out[prop] = value
+  return out
+}
+
+/**
+ * The example of one alternative of a union (`u.branches[i]`), tagged with the value that tells it apart from the
+ * others when the union says how. `synthesize` shows the first; a response with several variants writes each.
+ */
+export function synthesizeVariant(
+  union: Schema,
+  u: UnionInfo,
+  i: number,
+  resolve: (ref: string) => Schema | undefined,
+  status?: number,
+  sparse = false,
+  index?: ValueIndex,
+  depth = 0,
+  seen: string[] = [],
+  key = '',
+): unknown {
+  const b = u.branches[i] as UnionInfo['branches'][number]
+  const out = synthesize(
+    describedAs(b.schema, union),
+    resolve,
+    depth,
+    seen,
+    key,
+    status,
+    sparse,
+    index,
+  )
+  return u.tagSource === 'discriminator' && u.tagProp && b.tag !== undefined && b.schema.$ref
+    ? applyTag(out, u.tagProp, b.tag, b.schema.$ref, { resolve })
+    : out
+}
+
 /**
  * Deterministic, human-readable example: example > default > enum[0] > heuristics by name/format.
  * With `fake`, free-form string leaves become `{{faker.*}}` placeholders so every play is fresh.
@@ -475,12 +535,20 @@ export function synthesize(
   if (!schema) return null
   const again = (s: Schema | undefined, k = key, d = depth, sn = seen) =>
     synthesize(s, resolve, d, sn, k, status, sparse, index)
+  const ctx: UnionContext = { resolve }
   if (schema.$ref) {
     const target = resolve(schema.$ref)
     // a reference back into itself carries on as "required fields only", which the depth rules then end
-    if (seen.includes(schema.$ref)) return again(target, key, Math.max(depth, MAX_DEPTH), [])
-    return again(target, key, depth, [...seen, schema.$ref])
+    const out = seen.includes(schema.$ref)
+      ? again(target, key, Math.max(depth, MAX_DEPTH), [])
+      : again(target, key, depth, [...seen, schema.$ref])
+    // a variant of a family whose base holds the discriminator says which one it is
+    const tag = subtypeTag(schema.$ref, ctx)
+    return tag ? applyTag(out, tag.prop, tag.value, schema.$ref, ctx) : out
   }
+  /** One alternative of a union, tagged when the union says how its alternatives are told apart. */
+  const variant = (union: Schema, u: UnionInfo, i: number, k: string, d: number, sn: string[]) =>
+    synthesizeVariant(union, u, i, resolve, status, sparse, index, d, sn, k)
   // a spec example that contradicts its own schema (a string field whose example is an array) is ignored
   const given = exampleOf(schema)
   if (given !== undefined && fits(schema, given))
@@ -502,18 +570,11 @@ export function synthesize(
   // OpenAPI 3.1 writes an optional field as `anyOf: [{ type: 'null' }, ...]`: the first real branch shows the field
   const pick = branches?.find((b) => b.type !== 'null') ?? branches?.[0]
   if (pick) {
-    const out = again(describedAs(pick, schema))
-    const prop = schema.discriminator?.propertyName
-    if (prop && pick.$ref && out && typeof out === 'object' && !Array.isArray(out)) {
-      const mapped = Object.entries<string>(schema.discriminator.mapping ?? {}).find(
-        ([, ref]) => ref === pick.$ref,
-      )?.[0]
-      const value = mapped ?? (pick.$ref as string).split('/').pop()
-      const declared = resolve(pick.$ref)?.properties?.[prop]
-      if (!declared?.enum || declared.enum.includes(value))
-        (out as Record<string, unknown>)[prop] = value
-    }
-    return out
+    const u = unionOf(schema, ctx)
+    const at = u?.branches.findIndex((b) => b.schema === pick) ?? -1
+    return u && at >= 0
+      ? variant(schema, u, at, key, depth, seen)
+      : again(describedAs(pick, schema))
   }
   const type = Array.isArray(schema.type)
     ? schema.type.find((t: string) => t !== 'null')
@@ -529,6 +590,30 @@ export function synthesize(
       return exampleBoolean(key)
     case 'array': {
       if (depth >= MAX_DEPTH || schema.maxItems === 0) return []
+      // a success response lists one of each kind when its items are a union (a request keeps one to edit)
+      const items = schema.items as Schema | undefined
+      const kinds =
+        status !== undefined &&
+        status >= 200 &&
+        status < 400 &&
+        !(items?.$ref && seen.includes(items.$ref))
+          ? unionOf(items?.$ref ? resolve(items.$ref) : items, ctx)
+          : undefined
+      if (kinds) {
+        const into = items?.$ref ? [...seen, items.$ref] : seen
+        const union = (items?.$ref ? resolve(items.$ref) : items) as Schema
+        const count = Math.max(
+          1,
+          Math.min(
+            Math.max(Math.min(kinds.branches.length, FANOUT), schema.minItems ?? 0),
+            schema.maxItems ?? 5,
+            5,
+          ),
+        )
+        return Array.from({ length: count }, (_, i) =>
+          variant(union, kinds, i % kinds.branches.length, singular(key), depth + 1, into),
+        )
+      }
       // as many items as the schema asks for, distinct when it says they must be
       const first = again(schema.items, singular(key), depth + 1)
       const count = Math.min(Math.max(1, schema.minItems ?? 1), 5)
@@ -671,6 +756,20 @@ function convertSchema(schema: Schema | undefined, refPrefix: string): Schema {
   if (schema.deprecated) meta.deprecated = true
   if (schema.default !== undefined) meta.default = schema.default
   if (schema.example !== undefined) meta.examples = [schema.example]
+  // which branch a value is: kept, with its targets as the definition names the browser resolves
+  if (typeof schema.discriminator?.propertyName === 'string')
+    meta.discriminator = {
+      propertyName: schema.discriminator.propertyName,
+      ...(schema.discriminator.mapping
+        ? {
+            mapping: Object.fromEntries(
+              Object.entries<unknown>(schema.discriminator.mapping)
+                .filter(([, target]) => typeof target === 'string')
+                .map(([key, target]) => [key, refName(target as string)]),
+            ),
+          }
+        : {}),
+    }
 
   const rec = (s: Schema) => toJsonSchema(s, refPrefix)
   const withPlaceholder = (body: Schema): Schema => ({ ...meta, anyOf: [body, PLACEHOLDER] })

package/src/union.ts

@@ -0,0 +1,175 @@
+/**
+ * Polymorphism: what a `oneOf`/`anyOf` is made of and how its branches are told apart. Pure and free of
+ * imports, so the example generator (raw OpenAPI, `#/components/schemas/X`) and the browser UI (generated
+ * definitions, `…#/$defs/X`) share one answer. `$ref`s are compared by their last path segment.
+ *
+ * Two ways a family says which branch a value is, both common in Spring/Jackson documents:
+ * - a `discriminator`, on the union itself or on a base the branches extend through `allOf`
+ *   (`mapping` keys are the values; a branch with no entry is named by its schema);
+ * - a property every branch pins to its own single value with `enum`/`const` (`error: ["OUT_OF_STOCK"]`).
+ */
+export type Schema = Record<string, any>
+export type Resolve = (ref: string) => Schema | undefined
+
+export interface UnionContext {
+  resolve: Resolve
+  /** a branch that is not a real alternative (the UI's `"{{variable}}"` placeholder) */
+  ignore?: (branch: Schema) => boolean
+}
+
+export interface UnionBranch {
+  schema: Schema
+  /** the schema's name when the branch is a `$ref`, else its `title` */
+  name?: string
+  /** the value of the union's tag property that selects this branch */
+  tag?: string
+}
+
+export interface UnionInfo {
+  /** the real alternatives, in the document's order (`null` and placeholder branches left out) */
+  branches: UnionBranch[]
+  tagProp?: string
+  tagSource?: 'discriminator' | 'enum'
+}
+
+/** The name a `$ref` ends in. */
+export const nameOf = (ref: string): string => ref.slice(ref.lastIndexOf('/') + 1)
+
+const DEPTH = 8
+/** Properties that usually tell the variants of a family apart, tried first. */
+const TAG_NAMES = ['type', 'kind', 'error', 'code', 'status', 'title']
+
+function mappedTag(discriminator: Schema, name: string): string {
+  for (const [key, target] of Object.entries<unknown>(discriminator.mapping ?? {}))
+    if (typeof target === 'string' && nameOf(target) === name) return key
+  // OpenAPI: a schema with no mapping entry is named by itself
+  return name
+}
+
+/**
+ * The discriminator value a schema gets from the base it extends: `Album` is `allOf [Media, {…}]`, `Media`
+ * holds `discriminator { propertyName, mapping }`, so `Album` is `{ prop, value }`. Looks through nested bases.
+ */
+export function subtypeTag(
+  ref: string,
+  ctx: UnionContext,
+): { prop: string; value: string } | undefined {
+  const name = nameOf(ref)
+  type Found = { prop: string; value: string } | undefined
+  const walk = (schema: Schema | undefined, depth: number, seen: Set<Schema>): Found => {
+    if (!schema || depth > DEPTH || seen.has(schema)) return undefined
+    seen.add(schema)
+    for (const part of (schema.allOf as Schema[] | undefined) ?? []) {
+      const base = part.$ref ? ctx.resolve(part.$ref) : part
+      if (!base) continue
+      if (base.discriminator?.propertyName)
+        return {
+          prop: base.discriminator.propertyName as string,
+          value: mappedTag(base.discriminator, name),
+        }
+      const deeper = walk(base, depth + 1, seen)
+      if (deeper) return deeper
+    }
+    return undefined
+  }
+  return walk(ctx.resolve(ref), 0, new Set())
+}
+
+/** A schema's properties with its `allOf` parts and bases folded in (the subtype's own win). */
+export function flatProps(
+  schema: Schema | undefined,
+  ctx: UnionContext,
+  depth = 0,
+  seen = new Set<Schema>(),
+): Record<string, Schema> {
+  if (!schema || depth > DEPTH || seen.has(schema)) return {}
+  seen.add(schema)
+  const base = schema.$ref ? ctx.resolve(schema.$ref) : schema
+  if (!base) return {}
+  const out: Record<string, Schema> = {}
+  for (const part of (base.allOf as Schema[] | undefined) ?? [])
+    Object.assign(out, flatProps(part, ctx, depth + 1, seen))
+  return Object.assign(out, base.properties ?? {})
+}
+
+/**
+ * The one value a property is pinned to, if it is pinned. A string enum may arrive as `anyOf [enum, placeholder]`
+ * (the browser's definitions let a request hold a `"{{variable}}"` there): the placeholder is not an alternative.
+ */
+export function pinnedValue(prop: Schema | undefined, ctx?: UnionContext): string | undefined {
+  let p = prop
+  if (Array.isArray(p?.anyOf)) {
+    const real = p.anyOf.filter((b: Schema) => b.type !== 'null' && !ctx?.ignore?.(b))
+    if (real.length === 1) p = real[0]
+  }
+  if (!p) return undefined
+  const v = p.const !== undefined ? p.const : p.enum?.length === 1 ? p.enum[0] : undefined
+  return typeof v === 'string' ? v : undefined
+}
+
+const memo = new WeakMap<object, UnionInfo | null>()
+
+/** The union a schema is, or undefined when it is not one (fewer than two real alternatives is a wrapper, not a union). */
+export function unionOf(schema: Schema | undefined, ctx: UnionContext): UnionInfo | undefined {
+  if (!schema || typeof schema !== 'object') return undefined
+  const known = memo.get(schema)
+  if (known !== undefined) return known ?? undefined
+  const info = classify(schema, ctx)
+  memo.set(schema, info ?? null)
+  return info
+}
+
+function classify(schema: Schema, ctx: UnionContext): UnionInfo | undefined {
+  const raw: Schema[] | undefined = Array.isArray(schema.oneOf)
+    ? schema.oneOf
+    : Array.isArray(schema.anyOf)
+      ? schema.anyOf
+      : undefined
+  if (!raw) return undefined
+  const real = raw.filter((b) => b && b.type !== 'null' && !ctx.ignore?.(b))
+  // fewer than two alternatives is a wrapper (`anyOf [x, null]`), unless the union says how to tell them apart
+  if (real.length < 2 && !schema.discriminator?.propertyName) return undefined
+  const branches: UnionBranch[] = real.map((b) => ({
+    schema: b,
+    name: b.$ref ? nameOf(b.$ref) : typeof b.title === 'string' ? b.title : undefined,
+  }))
+  const done = (tagProp: string, tagSource: 'discriminator' | 'enum'): UnionInfo => ({
+    branches,
+    tagProp,
+    tagSource,
+  })
+
+  // 1. a discriminator on the union itself
+  if (schema.discriminator?.propertyName) {
+    for (const b of branches)
+      if (b.name && b.schema.$ref) b.tag = mappedTag(schema.discriminator, b.name)
+    return done(schema.discriminator.propertyName, 'discriminator')
+  }
+
+  // 2. a discriminator on a base the branches extend
+  if (branches.every((b) => b.schema.$ref)) {
+    const found = branches.map((b) => subtypeTag(b.schema.$ref, ctx))
+    const prop = found[0]?.prop
+    if (prop && found.every((f) => f?.prop === prop)) {
+      branches.forEach((b, i) => {
+        b.tag = found[i]?.value
+      })
+      return done(prop, 'discriminator')
+    }
+  }
+
+  // 3. a property each branch pins to its own value
+  const props = branches.map((b) => flatProps(b.schema, ctx))
+  const first = Object.keys(props[0] ?? {})
+  const candidates = [...TAG_NAMES.filter((n) => first.includes(n)), ...first]
+  for (const prop of candidates) {
+    const values = props.map((p) => pinnedValue(p[prop], ctx))
+    if (values.every((v) => v !== undefined) && new Set(values).size === values.length) {
+      branches.forEach((b, i) => {
+        b.tag = values[i]
+      })
+      return done(prop, 'enum')
+    }
+  }
+  return { branches }
+}