Skip to content

armgit / spree

Public Imported from GitHub
0

Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.

3.9 KB
Raw Blame
import { existsSync, readFileSync } from 'node:fs'
import path from 'node:path'
import { fileURLToPath } from 'node:url'
import { parse } from 'yaml'
import type { ZodType } from 'zod'

interface OpenApiExample {
  /** `GET /api/v3/admin/products` — where the example was recorded. */
  endpoint: string
  /** The component schema the response declares for this record. */
  schemaName: string
  record: unknown
}

type SchemaReference = { $ref?: string }
type ResponseSchema = SchemaReference & {
  properties?: { data?: SchemaReference & { items?: SchemaReference } }
}

const referencedName = (reference?: string) => reference?.split('/').pop()

/**
 * Collects every successful response example recorded in an API reference
 * (`docs/api-reference/<api>.yaml`) together with the schema it declares, one
 * entry per record — list responses contribute each item of `data`.
 *
 * The examples are real responses captured by the integration specs, so
 * validating them against the generated Zod schemas proves the schemas accept
 * what the API actually returns.
 */
function openApiExamples(api: 'store' | 'admin' | 'seller'): OpenApiExample[] {
  const specPath = path.resolve(
    path.dirname(fileURLToPath(import.meta.url)),
    `../../../docs/api-reference/${api}.yaml`,
  )
  const spec = parse(readFileSync(specPath, 'utf8'))
  const examples: OpenApiExample[] = []

  for (const [route, operations] of Object.entries<Record<string, unknown>>(spec.paths)) {
    for (const [method, operation] of Object.entries(operations)) {
      const responses = (operation as { responses?: Record<string, unknown> })?.responses ?? {}

      for (const [status, response] of Object.entries(responses)) {
        if (!status.startsWith('2')) continue

        const content = (
          response as { content?: Record<string, { example?: unknown; schema?: ResponseSchema }> }
        ).content?.['application/json']
        if (!content?.example) continue

        const endpoint = `${method.toUpperCase()} ${route}`
        const schema = content.schema ?? {}
        const data = schema.properties?.data
        const example = content.example as { data?: unknown }

        if (schema.$ref) {
          examples.push({ endpoint, schemaName: referencedName(schema.$ref)!, record: example })
        } else if (data?.$ref) {
          examples.push({ endpoint, schemaName: referencedName(data.$ref)!, record: example.data })
        } else if (data?.items?.$ref && Array.isArray(example.data)) {
          for (const record of example.data) {
            examples.push({ endpoint, schemaName: referencedName(data.items.$ref)!, record })
          }
        }
      }
    }
  }

  return examples
}

/**
 * Validates every recorded API reference example against the matching generated
 * schema and returns a readable line per rejection (empty when all pass), plus
 * how many examples were checked so a spec can guard against checking nothing.
 */
export function rejectedExamples(
  api: 'store' | 'admin' | 'seller',
  schemas: Record<string, unknown>,
): { checked: number; rejections: string[] } {
  let checked = 0
  const rejections: string[] = []

  for (const { endpoint, schemaName, record } of openApiExamples(api)) {
    const schema = schemas[`${schemaName}Schema`] as ZodType | undefined
    if (!schema) {
      // Response wrappers that exist only in the API reference have no generated
      // type; a record that does have one must have a schema too.
      const typePath = path.resolve(process.cwd(), `src/types/generated/${schemaName}.ts`)
      if (existsSync(typePath)) rejections.push(`${endpoint} → ${schemaName}: no generated schema`)
      continue
    }

    checked++
    const result = schema.safeParse(record)
    if (!result.success) {
      const issues = result.error.issues.map((issue) => `${issue.path.join('.')}: ${issue.message}`)
      rejections.push(`${endpoint} → ${schemaName}: ${issues.join('; ')}`)
    }
  }

  return { checked, rejections }
}