#!/usr/bin/env bun

/**

* Validates the OpenAPI specs in `apps/docs/` against each other and against

* the runtime Zod contracts in `apps/sim/lib/api/contracts/`.

*

* Every document is code-first, carries `x-generated-by`, and is checked for

* staleness by `generate-openapi.ts --check` before this script runs.

*

* 1. Spec integrity (every file): all `$ref`s resolve, operationIds are

* present and unique, every operation documents a success response, no

* orphaned component schemas.

* 2. v2 conventions: every published operation is under `/api/v2/`, documents

* 401, 429, and 503, and resolves every documented 4xx/5xx response to the

* canonical error envelope `{ error: { code, message } }`.

* 3. Contract cross-check: every route contract anywhere under

* `lib/api/contracts/**` whose path is under `/api/v2/` must be documented

* (or listed in `UNDOCUMENTED_V2_ROUTES` with a reason), every documented

* `/api/v2/` operation must have a contract, and for each pair the query

* params, body fields, and response fields are diffed via

* `z.toJSONSchema`. The sweep is recursive and rooted at the whole

* contracts tree, not the flat `v2/` directory — a contract in a

* subdirectory, or one that lives beside its non-v2 siblings, must never

* be able to escape coverage by virtue of where its file sits.

* 4. Examples, against two independent authorities:

* a. The RUNTIME CONTRACT — request examples are parsed with the matching

* contract's Zod body schema and response examples against its Zod

* response schema, so a doc example the running API would reject fails

* the build.

* b. The PUBLISHED SCHEMA — every example node in the serialized document,

* at any depth and on any status, is validated with Ajv against the

* exact JSON Schema readers see, with formats enforced. Zod is not

* consulted, so generator lossiness (a dropped regex flag, a bound

* erased by `.transform()`, a malformed `date-time`) surfaces here

* instead of shipping invisibly.

*

* The two are complementary and their failures name their authority:

* a runtime-contract failure means the example is wrong; a published-schema

* failure means either the example or the generated schema is wrong.

*/

import { readdirSync, readFileSync } from 'node:fs'

import path from 'node:path'

import Ajv2020 from 'ajv/dist/2020'

import { z } from 'zod'

import { OPENAPI_SPEC_FILES } from '../apps/docs/lib/openapi-specs'

const ROOT = path.resolve(import.meta.dir, '..')

const DOCS_DIR = path.join(ROOT, 'apps/docs')

const CONTRACTS_DIR = path.join(ROOT, 'apps/sim/lib/api/contracts')

const SPEC_FILES = OPENAPI_SPEC_FILES

/**

* `/api/v2/` routes that are deliberately absent from the public OpenAPI

* specs, each with the reason it is not public API surface. Anything not

* listed here fails the build, so an undocumented v2 route is always a

* conscious, reviewed decision rather than an accident of file layout.

*

* A stale entry — one whose contract no longer exists, or which has since

* been documented — also fails, so the list cannot rot into a blanket

* exemption.

*/

const UNDOCUMENTED_V2_ROUTES: Readonly<Record<string, string>> = {

'PUT /api/v2/uploads/{uploadId}':

'Local-storage data plane for a signed whole-object upload. Authenticated by the short-lived upload-token minted by the documented session-create operation, not by an API key; carries no v2 feature gate and returns bare error bodies rather than the canonical v2 envelope. The URL is handed to the client by the session response and is never constructed from docs.',

'PUT /api/v2/uploads/{uploadId}/parts/{partNumber}':

'Local-storage data plane for a signed multipart part upload. Authenticated by a per-part signed `token` query param minted by the documented part-URL operation, not by an API key; same non-canonical envelope and self-describing URL as the whole-object PUT above.',

}

/**

* Every operation removed with the unversioned core specification has a

* public v2 replacement. Keeping this mapping executable prevents a future

* docs edit from accidentally dropping a migrated execution, HITL, or usage

* capability.

*/

const LEGACY_CORE_REPLACEMENTS = {

executeWorkflow: 'POST /api/v2/workflows/{id}/execute',

getWorkflowExecution: 'GET /api/v2/workflows/{id}/runs/{runId}',

cancelExecution: 'POST /api/v2/workflows/{id}/runs/{runId}/cancel',

getJobStatus: 'GET /api/v2/workflows/{id}/runs/{runId}',

listPausedExecutions: 'GET /api/v2/workflows/{id}/runs',

getPausedExecution: 'GET /api/v2/workflows/{id}/runs/{runId}',

getPausedExecutionByResumePath: 'GET /api/v2/workflows/{id}/runs/{runId}',

getPauseContext: 'GET /api/v2/workflows/{id}/runs/{runId}',

resumeExecution: 'POST /api/v2/workflows/{id}/runs/{runId}/resume',

getUsageLimits: 'GET /api/v2/billing/status',

} as const

const API_REFERENCE_LOCALES = ['de', 'en', 'es', 'fr', 'ja', 'zh'] as const

const REQUIRED_API_REFERENCE_GROUPS = [

'(generated)/workflows',

'(generated)/workflow-runs',

'(generated)/logs',

'(generated)/audit-logs',

'(generated)/billing',

'(generated)/tables',

'(generated)/files',

'(generated)/knowledge-bases',

'(generated)/workspaces',

'(generated)/mcp-servers',

'(generated)/skills',

'(generated)/custom-tools',

'(generated)/credentials',

'(generated)/secrets',

] as const

const REMOVED_API_REFERENCE_GROUPS = [

'(generated)/execution',

'(generated)/human-in-the-loop',

'(generated)/usage',

] as const

type Json = Record<string, unknown>

const HTTP_METHODS = new Set(['get', 'post', 'put', 'patch', 'delete'])

const errors: string[] = []

const fail = (spec: string, msg: string) => errors.push(`${spec}: ${msg}`)

interface ContractLike {

method: string

path: string

params?: z.ZodType

query?: z.ZodType

body?: z.ZodType

response?: {

mode: string

schema?: z.ZodType

status?: number | readonly number[]

statusSchemas?: Readonly<Record<number, z.ZodType>>

}

}

function isContract(value: unknown): value is ContractLike {

return (

!!value &&

typeof value === 'object' &&

typeof (value as ContractLike).method === 'string' &&

typeof (value as ContractLike).path === 'string' &&

typeof (value as ContractLike).response === 'object'

)

}

/** `[tableId]` (contract) → `{tableId}` (OpenAPI). */

const contractKey = (c: ContractLike) =>

`${c.method.toUpperCase()} ${c.path.replace(/\[([^\]]+)\]/g, '{$1}')}`

/** Every non-test `.ts` file under `dir`, recursively, in stable order. */

function listContractFiles(dir: string): string[] {

const files: string[] = []

for (const entry of readdirSync(dir, { withFileTypes: true }).sort((a, b) =>

a.name.localeCompare(b.name)

)) {

const full = path.join(dir, entry.name)

if (entry.isDirectory()) {

if (entry.name === '__tests__') continue

files.push(...listContractFiles(full))

} else if (entry.name.endsWith('.ts') && !entry.name.endsWith('.test.ts')) {

files.push(full)

}

}

return files

}

/** Every `/api/v2/` route contract exported anywhere in the contracts tree. */

async function loadContracts(): Promise<Map<string, { name: string; contract: ContractLike }>> {

const registry = new Map<string, { name: string; contract: ContractLike }>()

for (const file of listContractFiles(CONTRACTS_DIR)) {

const mod = (await import(file)) as Record<string, unknown>

for (const [name, value] of Object.entries(mod)) {

if (!isContract(value)) continue

if (!value.path.startsWith('/api/v2/')) continue

const key = contractKey(value)

const existing = registry.get(key)

if (existing) {

// A route may expose narrowing variants of one operation (e.g. the

// batch-create alias) — keep the first, they share the wire.

continue

}

registry.set(key, { name, contract: value })

}

}

return registry

}

function resolveRef(ref: string, spec: Json): unknown {

let current: unknown = spec

for (const part of ref.replace('#/', '').split('/')) {

if (!current || typeof current !== 'object') return undefined

current = (current as Json)[part]

}

return current

}

/** Follow at most one level of `$ref` chains until a concrete node. */

function deref(node: unknown, spec: Json): unknown {

let current = node

for (let i = 0; i < 8; i++) {

if (current && typeof current === 'object' && typeof (current as Json).$ref === 'string') {

current = resolveRef((current as Json).$ref as string, spec)

} else {

return current

}

}

return current

}

function walkRefs(node: unknown, visit: (ref: string) => void): void {

if (Array.isArray(node)) {

for (const item of node) walkRefs(item, visit)

} else if (node && typeof node === 'object') {

for (const [key, value] of Object.entries(node)) {

if (key === '$ref' && typeof value === 'string') visit(value)

else walkRefs(value, visit)

}

}

}

/**

* Top-level property names of a documented JSON schema, unioning `oneOf` /

* `anyOf` / `allOf` variants. Returns `null` when the schema is opaque

* (no `properties` anywhere), in which case comparison is skipped.

*/

function docPropertyNames(schema: unknown, spec: Json): Set<string> | null {

const node = deref(schema, spec)

if (!node || typeof node !== 'object') return null

const record = node as Json

const variants = (record.oneOf ?? record.anyOf ?? record.allOf) as unknown[] | undefined

if (variants) {

const names = new Set<string>()

let sawAny = false

for (const variant of variants) {

const sub = docPropertyNames(variant, spec)

if (sub) {

sawAny = true

for (const n of sub) names.add(n)

}

}

return sawAny ? names : null

}

if (record.properties && typeof record.properties === 'object') {

return new Set(Object.keys(record.properties as Json))

}

return null

}

function toJsonSchema(schema: z.ZodType, io: 'input' | 'output'): Json {

return z.toJSONSchema(schema, {

io,

target: 'draft-2020-12',

unrepresentable: 'any',

cycles: 'ref',

}) as Json

}

const outputExampleValidator = new Ajv2020({

strict: false,

allErrors: true,

validateFormats: false,

})

function stripLegacySchemaIds(value: unknown): unknown {

if (Array.isArray(value)) return value.map(stripLegacySchemaIds)

if (!value || typeof value !== 'object') return value

return Object.fromEntries(

Object.entries(value)

.filter(([key, entry]) => key !== 'id' || typeof entry !== 'string')

.map(([key, entry]) => [key, stripLegacySchemaIds(entry)])

)

}

function outputExampleError(schema: z.ZodType, value: unknown): string | null {

const validate = outputExampleValidator.compile(

stripLegacySchemaIds(toJsonSchema(schema, 'output'))

)

if (validate(value)) return null

return outputExampleValidator.errorsText(validate.errors)

}

const DAYS_IN_MONTH = [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31] as const

const RFC3339_DATE_TIME =

/^(\d{4})-(\d{2})-(\d{2})[Tt](\d{2}):(\d{2}):(\d{2})(?:\.\d+)?(?:[Zz]|[+-]\d{2}:\d{2})$/

/**

* Strict RFC 3339 `date-time`. Ajv ships no format implementations of its own,

* so the published-schema pass registers the formats the specs actually use

* rather than depending on a transitive `ajv-formats` copy that resolves

* against a different Ajv build.

*

* `Date.parse` cannot stand in for the day bound: the ECMAScript Date Time

* String Format grammar accepts `DD` up to 31 and `MakeDay` silently rolls the

* overflow forward, so `2025-02-29` and `2025-04-31` both parse to a valid

* instant instead of `NaN`. February therefore carries the proleptic Gregorian

* leap rule explicitly. `:60` is allowed on purpose — RFC 3339 §5.6 permits a

* leap second in the `time-second` position.

*/

function isRfc3339DateTime(value: string): boolean {

const match = RFC3339_DATE_TIME.exec(value)

if (!match) return false

const [, year, month, day, hour, minute, second] = match.map(Number)

if (month < 1 || month > 12) return false

const leapYear = month === 2 && year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0)

if (day < 1 || day > DAYS_IN_MONTH[month - 1] + (leapYear ? 1 : 0)) return false

return hour <= 23 && minute <= 59 && second <= 60

}

const publishedExampleValidator = new Ajv2020({

strict: false,

allErrors: true,

validateFormats: true,

validateSchema: false,

})

publishedExampleValidator.addFormat('date-time', isRfc3339DateTime)

publishedExampleValidator.addFormat('email', /^[^\s@]+@[^\s@.]+(?:\.[^\s@.]+)+$/)

publishedExampleValidator.addFormat('uri', /^[A-Za-z][A-Za-z0-9+\-.]*:\S*$/)

/** OpenAPI content encodings, not JSON Schema assertions — annotation only. */

publishedExampleValidator.addFormat('binary', true)

publishedExampleValidator.addFormat('csv', true)

const pointerToken = (token: string) => token.replace(/~/g, '~0').replace(/\//g, '~1')

/** JSON Schema keywords whose value is a single subschema. */

const SUBSCHEMA_KEYWORDS = [

'items',

'not',

'contains',

'propertyNames',

'if',

'then',

'else',

'additionalProperties',

'unevaluatedItems',

'unevaluatedProperties',

] as const

/** JSON Schema keywords whose value is a name → subschema map. */

const SUBSCHEMA_MAP_KEYWORDS = [

'properties',

'patternProperties',

'$defs',

'definitions',

'dependentSchemas',

] as const

/** JSON Schema keywords whose value is an array of subschemas. */

const SUBSCHEMA_LIST_KEYWORDS = ['allOf', 'anyOf', 'oneOf', 'prefixItems'] as const

interface PublishedExample {

/** Human-readable location, e.g. `POST /api/v2/tables 201 application/json`. */

label: string

/** Name of the example within that location. */

exampleName: string

/** JSON pointer to the schema the example must satisfy. */

schemaPointer: string

value: unknown

}

/**

* Every `example` / `examples` annotation inside a JSON Schema subtree,

* including nested `properties/*`, array items, and composition branches.

* Recursion follows JSON Schema keywords only, so an example's own payload is

* never mistaken for a schema.

*/

function collectSchemaExamples(

node: unknown,

pointer: string,

label: string,

out: PublishedExample[]

): void {

if (!node || typeof node !== 'object' || Array.isArray(node)) return

const record = node as Json

if (record.example !== undefined) {

out.push({

label,

exampleName: 'schema.example',

schemaPointer: pointer,

value: record.example,

})

}

if (Array.isArray(record.examples)) {

for (const [index, value] of record.examples.entries()) {

out.push({

label,

exampleName: `schema.examples[${index}]`,

schemaPointer: pointer,

value,

})

}

}

for (const keyword of SUBSCHEMA_KEYWORDS) {

if (record[keyword] !== undefined) {

collectSchemaExamples(record[keyword], `${pointer}/${keyword}`, `${label}.${keyword}`, out)

}

}

for (const keyword of SUBSCHEMA_MAP_KEYWORDS) {

const map = record[keyword]

if (!map || typeof map !== 'object' || Array.isArray(map)) continue

for (const [name, sub] of Object.entries(map as Json)) {

collectSchemaExamples(

sub,

`${pointer}/${keyword}/${pointerToken(name)}`,

`${label}.${name}`,

out

)

}

}

for (const keyword of SUBSCHEMA_LIST_KEYWORDS) {

const list = record[keyword]

if (!Array.isArray(list)) continue

for (const [index, sub] of list.entries()) {

collectSchemaExamples(

sub,

`${pointer}/${keyword}/${index}`,

`${label}.${keyword}[${index}]`,

out

)

}

}

}

/**

* Examples on a Media Type, Parameter, or Header Object, all of which carry

* `example` / `examples` beside the `schema` those examples must satisfy.

*/

function collectSchemaHolderExamples(

holder: unknown,

pointer: string,

label: string,

spec: Json,

out: PublishedExample[]

): void {

if (!holder || typeof holder !== 'object' || Array.isArray(holder)) return

const record = holder as Json

if (record.schema === undefined) return

const schemaPointer = `${pointer}/schema`

if (record.example !== undefined) {

out.push({ label, exampleName: 'example', schemaPointer, value: record.example })

}

for (const [name, raw] of Object.entries((record.examples as Json) ?? {})) {

const example = deref(raw, spec) as Json | undefined

if (example?.value !== undefined) {

out.push({ label, exampleName: name, schemaPointer, value: example.value })

}

}

collectSchemaExamples(record.schema, schemaPointer, label, out)

}

function collectContentExamples(

content: unknown,

pointer: string,

label: string,

spec: Json,

out: PublishedExample[]

): void {

if (!content || typeof content !== 'object') return

for (const [contentType, media] of Object.entries(content as Json)) {

collectSchemaHolderExamples(

media,

`${pointer}/${pointerToken(contentType)}`,

`${label} ${contentType}`,

spec,

out

)

}

}

function collectParameterExamples(

parameters: unknown,

pointer: string,

label: string,

spec: Json,

out: PublishedExample[]

): void {

if (!Array.isArray(parameters)) return

for (const [index, raw] of parameters.entries()) {

// A `$ref`d parameter is walked once at its definition site instead.

if (!raw || typeof raw !== 'object' || typeof (raw as Json).$ref === 'string') continue

const name = (raw as Json).name

collectSchemaHolderExamples(

raw,

`${pointer}/${index}`,

`${label} parameter "${typeof name === 'string' ? name : index}"`,

spec,

out

)

}

}

/**

* Every example node in the serialized document, reached structurally rather

* than through the contract registry: component schemas at any depth, shared

* responses and their error envelopes, and every operation's parameters,

* request body, and responses at every status — 4xx and 5xx included.

*

* `$ref`d containers are deliberately not followed here; each is walked once

* at its definition site, so no example is validated twice.

*/

function collectPublishedExamples(spec: Json): PublishedExample[] {

const out: PublishedExample[] = []

const components = (spec.components as Json) ?? {}

for (const [name, schema] of Object.entries((components.schemas as Json) ?? {})) {

collectSchemaExamples(

schema,

`/components/schemas/${pointerToken(name)}`,

`components.schemas.${name}`,

out

)

}

for (const section of ['parameters', 'headers'] as const) {

for (const [name, holder] of Object.entries((components[section] as Json) ?? {})) {

collectSchemaHolderExamples(

holder,

`/components/${section}/${pointerToken(name)}`,

`components.${section}.${name}`,

spec,

out

)

}

}

for (const section of ['requestBodies', 'responses'] as const) {

for (const [name, holder] of Object.entries((components[section] as Json) ?? {})) {

collectContentExamples(

(holder as Json)?.content,

`/components/${section}/${pointerToken(name)}/content`,

`components.${section}.${name}`,

spec,

out

)

}

}

for (const [p, rawItem] of Object.entries((spec.paths as Json) ?? {})) {

if (!rawItem || typeof rawItem !== 'object') continue

const item = rawItem as Json

const itemPointer = `/paths/${pointerToken(p)}`

collectParameterExamples(item.parameters, `${itemPointer}/parameters`, p, spec, out)

for (const [method, rawOp] of Object.entries(item)) {

if (!HTTP_METHODS.has(method) || !rawOp || typeof rawOp !== 'object') continue

const op = rawOp as Json

const opPointer = `${itemPointer}/${method}`

const label = `${method.toUpperCase()} ${p}`

collectParameterExamples(op.parameters, `${opPointer}/parameters`, label, spec, out)

if (op.requestBody && typeof (op.requestBody as Json).$ref !== 'string') {

collectContentExamples(

(op.requestBody as Json).content,

`${opPointer}/requestBody/content`,

`${label} request`,

spec,

out

)

}

for (const [status, rawResponse] of Object.entries((op.responses as Json) ?? {})) {

if (!rawResponse || typeof rawResponse !== 'object') continue

if (typeof (rawResponse as Json).$ref === 'string') continue

collectContentExamples(

(rawResponse as Json).content,

`${opPointer}/responses/${pointerToken(status)}/content`,

`${label} ${status}`,

spec,

out

)

}

}

}

return out

}

let publishedExamplesRead = 0

let runtimeExamplesRead = 0

/**

* Validates every collected example against the published document itself.

* The whole spec is registered under a synthetic URI so `$ref` and `$defs`

* resolve exactly as a reader's tooling would resolve them.

*/

function checkPublishedExamples(specFile: string, spec: Json): void {

const specUri = `https://sim.local/openapi/${specFile}`

if (!publishedExampleValidator.getSchema(specUri)) {

publishedExampleValidator.addSchema(spec, specUri)

}

const validators = new Map<string, ReturnType<typeof publishedExampleValidator.compile>>()

for (const example of collectPublishedExamples(spec)) {

publishedExamplesRead++

let validate = validators.get(example.schemaPointer)

if (!validate) {

validate = publishedExampleValidator.compile({ $ref: `${specUri}#${example.schemaPointer}` })

validators.set(example.schemaPointer, validate)

}

if (validate(example.value)) continue

fail(

specFile,

`${example.label}: example "${example.exampleName}" is rejected by the PUBLISHED JSON Schema at #${example.schemaPointer} — ${publishedExampleValidator.errorsText(validate.errors)}. Either the example is wrong or the generated schema is (a lost regex flag, a bound erased by .transform(), a malformed format value).`

)

}

}

interface Operation {

specFile: string

path: string

method: string

op: Json

spec: Json

}

function collectOperations(specFile: string, spec: Json): Operation[] {

const ops: Operation[] = []

for (const [p, methods] of Object.entries((spec.paths as Json) ?? {})) {

if (!methods || typeof methods !== 'object') continue

for (const [method, op] of Object.entries(methods as Json)) {

if (!HTTP_METHODS.has(method)) continue

ops.push({ specFile, path: p, method, op: op as Json, spec })

}

}

return ops

}

function isSuccessStatus(code: string): boolean {

const status = Number(code)

return Number.isInteger(status) && status >= 200 && status < 400

}

function checkIntegrity(specFile: string, spec: Json, ops: Operation[]): void {

walkRefs(spec, (ref) => {

if (resolveRef(ref, spec) === undefined) fail(specFile, `unresolved $ref ${ref}`)

})

const seenIds = new Set<string>()

for (const { path: p, method, op } of ops) {

const label = `${method.toUpperCase()} ${p}`

const id = op.operationId

if (typeof id !== 'string' || !id) {

fail(specFile, `${label}: missing operationId`)

} else if (seenIds.has(id)) {

fail(specFile, `${label}: duplicate operationId "${id}"`)

} else {

seenIds.add(id)

}

const responses = (op.responses as Json) ?? {}

if (!Object.keys(responses).some(isSuccessStatus)) {

fail(specFile, `${label}: no documented success response`)

}

const requestBody = deref(op.requestBody, spec) as Json | undefined

if (requestBody) {

const content = requestBody.content as Json | undefined

if (!content || Object.keys(content).length === 0) {

fail(specFile, `${label}: request body has no content types`)

} else {

for (const [contentType, media] of Object.entries(content)) {

if (!(media as Json)?.schema) {

fail(specFile, `${label}: ${contentType} request body has no schema`)

}

}

}

}

for (const [status, response] of Object.entries(responses)) {

if (!isSuccessStatus(status)) continue

const resolved = deref(response, spec) as Json | undefined

const content = resolved?.content as Json | undefined

if (!content) continue

if (Object.keys(content).length === 0) {

fail(specFile, `${label}: ${status} response has an empty content map`)

continue

}

for (const [contentType, media] of Object.entries(content)) {

if (!(media as Json)?.schema) {

fail(specFile, `${label}: ${status} ${contentType} response has no schema`)

}

}

}

}

const schemas = ((spec.components as Json)?.schemas as Json) ?? {}

const blobWithout = (name: string) =>

JSON.stringify({

...spec,

components: { ...(spec.components as Json), schemas: { ...schemas, [name]: null } },

})

for (const name of Object.keys(schemas)) {

if (!blobWithout(name).includes(`"#/components/schemas/${name}"`)) {

fail(specFile, `orphaned component schema "${name}" (unreferenced)`)

}

}

}

function checkV2Conventions(operation: Operation): void {

const { specFile, path: p, method, op, spec } = operation

const label = `${method.toUpperCase()} ${p}`

const responses = (op.responses as Json) ?? {}

for (const code of ['401', '429', '503']) {

if (!(code in responses)) fail(specFile, `${label}: v2 operation missing ${code} response`)

}

for (const [code, response] of Object.entries(responses)) {

if (!/^[45]/.test(code)) continue

const resolved = deref(response, spec) as Json | undefined

const schema = deref(

((resolved?.content as Json)?.['application/json'] as Json)?.schema,

spec

) as Json | undefined

// A bodyless error (e.g. a bare 413) documents intent without a schema.

if (!schema) continue

const errorProp = deref((schema.properties as Json)?.error, spec) as Json | undefined

const inner = errorProp?.properties as Json | undefined

if (!inner || !('code' in inner) || !('message' in inner)) {

fail(

specFile,

`${label}: ${code} response is not the canonical v2 error envelope { error: { code, message } }`

)

}

}

}

function checkQueryParams(operation: Operation, contract: ContractLike, name: string): void {

const { specFile, path: p, method, op, spec } = operation

const label = `${method.toUpperCase()} ${p}`

if (!contract.query) return

const zodSchema = toJsonSchema(contract.query, 'input')

if (!zodSchema?.properties) return

const docParams = new Map<string, Json>()

for (const raw of (op.parameters as unknown[]) ?? []) {

const param = deref(raw, spec) as Json | undefined

if (param?.in === 'query' && typeof param.name === 'string') docParams.set(param.name, param)

}

const zodProps = Object.keys(zodSchema.properties as Json)

const zodRequired = new Set((zodSchema.required as string[]) ?? [])

for (const prop of zodProps) {

const doc = docParams.get(prop)

if (!doc) {

fail(specFile, `${label}: query param "${prop}" (${name}) is not documented`)

} else if (Boolean(doc.required) !== zodRequired.has(prop)) {

fail(

specFile,

`${label}: query param "${prop}" required mismatch (contract ${zodRequired.has(prop) ? 'required' : 'optional'}, docs ${doc.required ? 'required' : 'optional'})`

)

}

}

for (const docName of docParams.keys()) {

if (!zodProps.includes(docName)) {

fail(specFile, `${label}: documented query param "${docName}" does not exist on ${name}`)

}

}

}

function checkSuccessStatuses(operation: Operation, contract: ContractLike): void {

const { specFile, path: p, method, op } = operation

const label = `${method.toUpperCase()} ${p}`

const configured = contract.response?.status

const expected = (

configured === undefined

? [200]

: typeof configured === 'number'

? [configured]

: [...configured]

).sort((a, b) => a - b)

const documented = Object.keys((op.responses as Json) ?? {})

.filter(isSuccessStatus)

.map(Number)

.sort((a, b) => a - b)

if (JSON.stringify(documented) !== JSON.stringify(expected)) {

fail(

specFile,

`${label}: documented success statuses [${documented.join(', ')}] do not match contract statuses [${expected.join(', ')}]`

)

}

}

/** Property subschema lookup, searching `oneOf`/`anyOf`/`allOf` variants. */

function propertyNode(schema: unknown, root: Json, prop: string): unknown {

const node = deref(schema, root)

if (!node || typeof node !== 'object') return undefined

const record = node as Json

const variants = (record.oneOf ?? record.anyOf ?? record.allOf) as unknown[] | undefined

if (variants) {

for (const variant of variants) {

const found = propertyNode(variant, root, prop)

if (found !== undefined) return found

}

return undefined

}

return (record.properties as Json | undefined)?.[prop]

}

/** Deref + step through array wrappers so item objects compare directly. */

function unwrapArrays(node: unknown, root: Json): unknown {

let current = deref(node, root)

for (let i = 0; i < 3; i++) {

const record = current as Json | null

if (record && typeof record === 'object' && record.type === 'array' && record.items) {

current = deref(record.items, root)

} else {

break

}

}

return current

}

interface DiffContext {

specFile: string

label: string

name: string

where: 'body' | 'response'

}

/**

* Recursively diffs property-name sets between the Zod-derived JSON schema and

* the documented one, descending through matching object properties and array

* items. Comparison happens only where BOTH sides expose a property set — an

* opaque side (records, `additionalProperties`, prose-only docs) ends the

* descent instead of producing false positives. The Zod root doubles as the

* `$defs` resolution context for recursive schemas.

*/

function diffSchemaFields(

zodNode: unknown,

zodRoot: Json,

docNode: unknown,

docRoot: Json,

ctx: DiffContext,

prefix: string,

depth: number

): void {

if (depth > 4) return

const zodObj = unwrapArrays(zodNode, zodRoot)

const docObj = unwrapArrays(docNode, docRoot)

const zodNames = docPropertyNames(zodObj, zodRoot)

const docNames = docPropertyNames(docObj, docRoot)

if (!zodNames || !docNames) return

const fieldPath = (n: string) => (prefix ? `${prefix}.${n}` : n)

/**

* A `.passthrough()` contract deliberately under-declares its fields, so the

* docs are allowed to document more than the Zod side names.

*/

const extra = (zodObj as Json).additionalProperties

const zodIsPassthrough =

extra === true || (!!extra && typeof extra === 'object' && Object.keys(extra).length === 0)

for (const n of zodNames) {

if (!docNames.has(n)) {

fail(

ctx.specFile,

`${ctx.label}: ${ctx.where} field "${fieldPath(n)}" (${ctx.name}) not documented`

)

}

}

for (const n of docNames) {

if (!zodNames.has(n) && !zodIsPassthrough) {

fail(

ctx.specFile,

`${ctx.label}: documented ${ctx.where} field "${fieldPath(n)}" does not exist on ${ctx.name}`

)

}

}

for (const n of zodNames) {

if (!docNames.has(n)) continue

diffSchemaFields(

propertyNode(zodObj, zodRoot, n),

zodRoot,

propertyNode(docObj, docRoot, n),

docRoot,

ctx,

fieldPath(n),

depth + 1

)

}

}

function checkBodyAndResponse(operation: Operation, contract: ContractLike, name: string): void {

const { specFile, path: p, method, op, spec } = operation

const label = `${method.toUpperCase()} ${p}`

const docBodyContent = ((deref(op.requestBody, spec) as Json)?.content as Json) ?? {}

if (contract.body) {

const zodRoot = toJsonSchema(contract.body, 'input')

if (zodRoot) {

for (const media of Object.values(docBodyContent)) {

const docSchema = (media as Json)?.schema

if (!docSchema) continue

diffSchemaFields(

zodRoot,

zodRoot,

docSchema,

spec,

{ specFile, label, name, where: 'body' },

'',

0

)

}

}

}

if (contract.response?.mode === 'json' && contract.response.schema) {

const responses = (op.responses as Json) ?? {}

for (const [status, response] of Object.entries(responses)) {

if (!isSuccessStatus(status)) continue

const docResponse = deref(response, spec) as Json | undefined

const docSchema = ((docResponse?.content as Json)?.['application/json'] as Json)?.schema

if (docSchema) {

const responseSchema =

contract.response.statusSchemas?.[Number(status)] ?? contract.response.schema

const zodRoot = toJsonSchema(responseSchema, 'output')

diffSchemaFields(

zodRoot,

zodRoot,

docSchema,

spec,

{ specFile, label, name, where: 'response' },

'',

0

)

}

}

}

}

function documentedExamples(media: Json, spec: Json): Array<[string, unknown]> {

const candidates: Array<[string, unknown]> = []

if (media.example !== undefined) candidates.push(['example', media.example])

for (const [name, rawExample] of Object.entries((media.examples as Json) ?? {})) {

const example = deref(rawExample, spec) as Json | undefined

if (example?.value !== undefined) candidates.push([name, example.value])

}

const schema = deref(media.schema, spec) as Json | undefined

if (schema?.example !== undefined) candidates.push(['schema.example', schema.example])

if (Array.isArray(schema?.examples)) {

for (const [index, example] of schema.examples.entries()) {

candidates.push([`schema.examples[${index}]`, example])

}

}

return candidates

}

function checkExamples(operation: Operation, contract: ContractLike, name: string): void {

const { specFile, path: p, method, op, spec } = operation

const label = `${method.toUpperCase()} ${p}`

const bodyContent = ((deref(op.requestBody, spec) as Json)?.content as Json) ?? {}

if (contract.body) {

for (const [contentType, rawMedia] of Object.entries(bodyContent)) {

for (const [exampleName, value] of documentedExamples(rawMedia as Json, spec)) {

runtimeExamplesRead++

const parsed = contract.body.safeParse(value)

if (!parsed.success) {

fail(

specFile,

`${label}: ${contentType} request example "${exampleName}" is rejected by the RUNTIME CONTRACT ${name} (Zod) — ${parsed.error.issues[0]?.message}. The running API would reject this request, so fix the example.`

)

}

}

}

}

if (contract.response?.mode === 'json' && contract.response.schema) {

const responses = (op.responses as Json) ?? {}

for (const [status, rawResponse] of Object.entries(responses)) {

if (!isSuccessStatus(status)) continue

const response = deref(rawResponse, spec) as Json | undefined

const content = (response?.content as Json)?.['application/json'] as Json | undefined

if (!content) continue

for (const [exampleName, value] of documentedExamples(content, spec)) {

runtimeExamplesRead++

const responseSchema =

contract.response.statusSchemas?.[Number(status)] ?? contract.response.schema

const validationError = outputExampleError(responseSchema, value)

if (validationError) {

fail(

specFile,

`${label}: ${status} response example "${exampleName}" is rejected by the RUNTIME CONTRACT ${name} (Zod) — ${validationError}. The running API would never emit this body, so fix the example.`

)

}

}

}

}

}

const registry = await loadContracts()

const documentedKeys = new Set<string>()

const globalOperationIds = new Map<string, string>()

const globalOperationTags = new Map<string, readonly string[]>()

for (const specFile of SPEC_FILES) {

const spec = JSON.parse(readFileSync(path.join(DOCS_DIR, specFile), 'utf8')) as Json

if (spec['x-generated-by'] !== 'scripts/generate-openapi.ts') {

fail(specFile, 'generated spec is missing its x-generated-by marker')

}

const ops = collectOperations(specFile, spec)

checkIntegrity(specFile, spec, ops)

checkPublishedExamples(specFile, spec)

for (const operation of ops) {

const key = `${operation.method.toUpperCase()} ${operation.path}`

if (documentedKeys.has(key)) {

fail(specFile, `${key}: operation is documented by more than one spec`)

}

documentedKeys.add(key)

const operationId = operation.op.operationId

if (typeof operationId === 'string') {

const previous = globalOperationIds.get(operationId)

if (previous)