@znight/openapi 0.0.0-stage → 0.1.0

package/src/compiler/validate.ts

@@ -0,0 +1,102 @@
+/**
+ * `validate`: builds the whole OpenAPI model once per compile (document options, security schemes,
+ * operations, components, Standard Schema slots), reports its diagnostics and keeps it for
+ * `generate` (keyed by the application graph).
+ */
+import type { ApplicationGraph, Location, ValidateContext } from '@znight/compiler'
+import type { JsonSchema, JsonValue, SecuritySchemeObject } from '../types.ts'
+import type { OpenApiStored, SlotData } from './model.ts'
+import type { OperationModel } from './operations.ts'
+
+import { compareStrings, ERROR_COMPONENTS } from '../shared.ts'
+import { documentTemplate, readDocument, SchemeRegistry } from './document.ts'
+import { buildOperations } from './operations.ts'
+import { Schemas, Slots } from './schemas.ts'
+
+/** Everything `generate` emits. */
+export interface OpenApiModel {
+  readonly document: Record<string, JsonValue>
+  readonly operations: readonly OperationModel[]
+  readonly components: Readonly<Record<string, JsonSchema>>
+  readonly securitySchemes: Readonly<Record<string, SecuritySchemeObject>>
+  readonly slots: readonly SlotData[]
+  readonly errors: { readonly contentType: string; readonly schema?: string } | undefined
+  readonly tagDescriptions: Readonly<Record<string, string>>
+  /** Root of the project (relative `source` locations). */
+  readonly root: string
+}
+
+/**
+ * Models by compile. The key is `graph.extensions`: the validate and generate contexts of one
+ * compile get different graph objects (diagnostics, pruning) sharing this array.
+ */
+const models = new WeakMap<object, OpenApiModel>()
+
+/** `validate` of the extension. */
+export function validateOpenApi(ctx: ValidateContext<OpenApiStored>): void {
+  models.set(ctx.graph.extensions, buildModel(ctx))
+}
+
+/** The model built by `validate` for the compile of `graph`. */
+export function modelOf(graph: ApplicationGraph): OpenApiModel | undefined {
+  return models.get(graph.extensions)
+}
+
+function buildModel(ctx: ValidateContext<OpenApiStored>): OpenApiModel {
+  const schemes = new SchemeRegistry(ctx)
+  const document = readDocument(ctx, schemes)
+  const reserved = new Set<string>(
+    document.errors === false ? [] : [ERROR_COMPONENTS.body, ERROR_COMPONENTS.validation],
+  )
+  const slots = new Slots(
+    diagnostic => ctx.report(diagnostic),
+    () => reserved,
+    ref => declarationOf(ctx, ref.identity),
+  )
+  const schemas = new Schemas(ctx, { jsdoc: document.jsdoc, strict: document.strict, reserved }, slots)
+  const errorsSlot =
+    document.errors === false || document.errors.schema === undefined
+      ? undefined
+      : slots.use(document.errors.schema, 'output')
+  const { operations, tagDescriptions } = buildOperations({ ctx, document, schemes, schemas, slots })
+  schemas.settle()
+  const rootSecurity = document.security === undefined ? undefined : schemes.objects(document.security)
+  const securitySchemes: Record<string, SecuritySchemeObject> = {}
+  for (const name of [...schemes.used.keys()].sort(compareStrings)) {
+    securitySchemes[name] = schemes.used.get(name)?.definition as SecuritySchemeObject
+  }
+  return {
+    document: documentTemplate(document, rootSecurity),
+    operations,
+    components: schemas.components(),
+    securitySchemes,
+    slots: slots.list(),
+    errors: errorsOf(document.errors, errorsSlot?.name),
+    tagDescriptions,
+    root: ctx.options.root,
+  }
+}
+
+function errorsOf(
+  errors: false | { readonly contentType: string },
+  schema: string | undefined,
+): OpenApiModel['errors'] {
+  if (errors === false) return undefined
+  return schema === undefined ? { contentType: errors.contentType } : { contentType: errors.contentType, schema }
+}
+
+/** Location of the declaration of an identity (`export const CreateBook = ...`). */
+function declarationOf(ctx: ValidateContext<OpenApiStored>, identity: string | undefined): Location | undefined {
+  if (identity === undefined) return undefined
+  const symbol = ctx.project.lookupIdentity(identity)
+  if (symbol.kind !== 'declaration') return undefined
+  const declaration = symbol.declarations[0]
+  if (declaration === undefined) return undefined
+  return ctx.project.getFile(declaration.file)?.location(declaration.span)
+}
+
+/** `{ file, line, column }` of a location, the file relative to `root`. */
+export function sourceOf(location: Location, root: string): { file: string; line: number; column: number } {
+  const file = location.file.startsWith(`${root}/`) ? location.file.slice(root.length + 1) : location.file
+  return { file, line: location.line, column: location.column }
+}

package/src/compiler/values.ts

@@ -0,0 +1,81 @@
+/**
+ * Reading statically evaluated values (`StaticValue`) without importing the compiler: references
+ * to exported bindings (`ValueRef`) are recognised structurally.
+ */
+import type { StaticValue, ValueRef } from '@znight/compiler'
+import type { JsonValue } from '../types.ts'
+
+/** `true` for a `ValueRef` (a reference to an exported binding, nested in an evaluated value). */
+export function isRef(value: unknown): value is ValueRef {
+  if (typeof value !== 'object' || value === null) return false
+  const prototype = Object.getPrototypeOf(value)
+  return prototype !== Object.prototype && prototype !== null && (value as { kind?: unknown }).kind === 'ref'
+}
+
+/** `true` for an evaluated object literal (not an array, not a reference). */
+export function isRecord(value: unknown): value is Readonly<Record<string, StaticValue>> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value) && !isRef(value)
+}
+
+/** The value when it is JSON (no `undefined` inside objects is kept, no bigint, no reference). */
+export function toJson(value: StaticValue): JsonValue | undefined {
+  if (value === null || typeof value === 'string' || typeof value === 'boolean') return value
+  if (typeof value === 'number') return Number.isFinite(value) ? value : undefined
+  if (value === undefined || typeof value === 'bigint' || isRef(value)) return undefined
+  if (Array.isArray(value)) {
+    const items: JsonValue[] = []
+    for (const item of value as readonly StaticValue[]) {
+      const json = toJson(item)
+      if (json === undefined) return undefined
+      items.push(json)
+    }
+    return items
+  }
+  const result: Record<string, JsonValue> = {}
+  for (const [key, item] of Object.entries(value as Readonly<Record<string, StaticValue>>)) {
+    if (item === undefined) continue
+    const json = toJson(item)
+    if (json === undefined) return undefined
+    result[key] = json
+  }
+  return result
+}
+
+/** The first `$znight` key found in a value (reserved), as a path (`info.x.$znight`). */
+export function findReservedKey(value: StaticValue, path = ''): string | undefined {
+  if (Array.isArray(value)) {
+    for (const [index, item] of (value as readonly StaticValue[]).entries()) {
+      const found = findReservedKey(item, `${path}[${index}]`)
+      if (found !== undefined) return found
+    }
+    return undefined
+  }
+  if (!isRecord(value)) return undefined
+  for (const [key, item] of Object.entries(value)) {
+    const where = path === '' ? key : `${path}.${key}`
+    if (key === '$znight') return where
+    const found = findReservedKey(item, where)
+    if (found !== undefined) return found
+  }
+  return undefined
+}
+
+/** A short description for messages. */
+export function describe(value: StaticValue): string {
+  if (value === null) return 'null'
+  if (Array.isArray(value)) return 'an array'
+  if (isRef(value)) return `a reference to '${value.text}'`
+  if (typeof value === 'object') return 'an object'
+  if (typeof value === 'string') return JSON.stringify(value)
+  return String(value)
+}
+
+/** Absolute URL (`https://...`, `mailto:`...). */
+export function isAbsoluteUrl(value: string): boolean {
+  return URL.canParse(value)
+}
+
+/** Absolute or relative URL (servers: `/api`, `https://api.example.com/v1`). */
+export function isUrlReference(value: string): boolean {
+  return value !== '' && !/\s/.test(value) && (URL.canParse(value) || URL.canParse(value, 'https://example.com'))
+}

package/src/converters.ts

@@ -0,0 +1,137 @@
+/**
+ * Standard Schema → JSON Schema converters (§7.3 of RFC 0002). The library that defines a schema is
+ * the only one that knows its JSON Schema: Zod, ArkType and the libraries implementing Standard
+ * JSON Schema convert their own schemas; Valibot goes through `@valibot/to-json-schema`.
+ */
+import type { StandardSchemaV1 } from '@znight/http'
+import type { JsonSchema } from './types.ts'
+
+/** What a converter receives next to the schema. */
+export interface SchemaConverterContext {
+  /** `input` for requests (what clients send), `output` for responses (what the server sends). */
+  readonly io: 'input' | 'output'
+  readonly target: 'draft-2020-12'
+  /** Retry after a failure with `unrepresentable: 'warn'`: approximate instead of throwing. */
+  readonly lenient: boolean
+}
+
+/** Converts Standard Schemas of one library to JSON Schema 2020-12. */
+export interface SchemaConverter {
+  readonly name: string
+  /** `undefined`: not supported, the next converter is tried. Throwing reports ZNIGHT037. */
+  convert(
+    schema: StandardSchemaV1,
+    context: SchemaConverterContext,
+  ): JsonSchema | undefined | Promise<JsonSchema | undefined>
+}
+
+/** The Standard JSON Schema interface (`~standard.jsonSchema`). */
+interface StandardJsonSchemaProps {
+  readonly vendor?: unknown
+  readonly jsonSchema?: {
+    readonly input?: (options: { target: string; libraryOptions?: Record<string, unknown> }) => unknown
+    readonly output?: (options: { target: string; libraryOptions?: Record<string, unknown> }) => unknown
+  }
+}
+
+function propsOf(schema: StandardSchemaV1): StandardJsonSchemaProps | undefined {
+  const props = (schema as unknown as { '~standard'?: unknown })['~standard']
+  return typeof props === 'object' && props !== null ? (props as StandardJsonSchemaProps) : undefined
+}
+
+/** `vendor` of a Standard Schema (`zod`, `valibot`, `arktype`...). */
+export function vendorOf(schema: StandardSchemaV1): string {
+  const vendor = propsOf(schema)?.vendor
+  return typeof vendor === 'string' ? vendor : 'unknown'
+}
+
+/** How a date travels in JSON: an ISO 8601 string. */
+const DATE_TIME: JsonSchema = Object.freeze({ type: 'string', format: 'date-time' })
+
+/**
+ * Zod dates are serialised with `Date.prototype.toJSON`: in responses they are ISO strings. A
+ * coerced date (`z.coerce.date()`) reads a string in requests (query, path, body). Other
+ * unrepresentable parts throw (or become `{}` when lenient).
+ */
+function zodOptions(context: SchemaConverterContext): Record<string, unknown> {
+  return {
+    unrepresentable: (site: { zodSchema?: { _zod?: { def?: { type?: unknown; coerce?: unknown } } } }) => {
+      const def = site.zodSchema?._zod?.def
+      if (def?.type === 'date' && (context.io === 'output' || def.coerce === true)) return { ...DATE_TIME }
+      return context.lenient ? 'any' : 'throw'
+    },
+  }
+}
+
+/**
+ * `@valibot/to-json-schema` options: dates of responses are ISO strings (`Date.prototype.toJSON`),
+ * other unrepresentable parts throw (or are left out when lenient).
+ */
+function valibotOptions(context: SchemaConverterContext): Record<string, unknown> {
+  return {
+    ...(context.lenient ? { errorMode: 'ignore' } : {}),
+    overrideSchema: (site: { valibotSchema?: { type?: unknown } }) =>
+      context.io === 'output' && site.valibotSchema?.type === 'date' ? { ...DATE_TIME } : undefined,
+  }
+}
+
+function callStandard(
+  props: StandardJsonSchemaProps | undefined,
+  context: SchemaConverterContext,
+  libraryOptions?: Record<string, unknown>,
+): unknown {
+  const convert = props?.jsonSchema?.[context.io]
+  if (typeof convert !== 'function') return undefined
+  return convert.call(props?.jsonSchema, {
+    target: context.target,
+    ...(libraryOptions === undefined ? {} : { libraryOptions }),
+  })
+}
+
+/**
+ * Standard JSON Schema (`schema['~standard'].jsonSchema[io]({ target: 'draft-2020-12' })`): Zod ≥ 4.2,
+ * ArkType ≥ 2.1.28 and every library implementing the interface.
+ */
+export const standardJsonSchemaConverter: SchemaConverter = Object.freeze({
+  name: 'standard-json-schema',
+  convert(schema: StandardSchemaV1, context: SchemaConverterContext): JsonSchema | undefined {
+    const props = propsOf(schema)
+    if (typeof props?.jsonSchema?.[context.io] !== 'function') return undefined
+    const result = callStandard(props, context, props.vendor === 'zod' ? zodOptions(context) : undefined)
+    return result as JsonSchema | undefined
+  },
+})
+
+/** Valibot schemas (no `~standard.jsonSchema`) through `toStandardJsonSchema()` of `@valibot/to-json-schema`. */
+export const valibotConverter: SchemaConverter = Object.freeze({
+  name: 'valibot',
+  async convert(schema: StandardSchemaV1, context: SchemaConverterContext): Promise<JsonSchema | undefined> {
+    const props = propsOf(schema)
+    if (props?.vendor !== 'valibot' || props.jsonSchema !== undefined) return undefined
+    let module: { toStandardJsonSchema?: (schema: unknown) => unknown }
+    try {
+      module = (await import('@valibot/to-json-schema')) as typeof module
+    } catch (error) {
+      throw new Error(
+        'Valibot schemas need the optional peer @valibot/to-json-schema (npm install @valibot/to-json-schema)',
+        {
+          cause: error,
+        },
+      )
+    }
+    if (typeof module.toStandardJsonSchema !== 'function') {
+      throw new Error('@valibot/to-json-schema has no toStandardJsonSchema(): install version 1.5 or later')
+    }
+    // options go through `libraryOptions` (toStandardJsonSchema takes the schema only)
+    const standard = module.toStandardJsonSchema(schema)
+    return callStandard(propsOf(standard as StandardSchemaV1), context, valibotOptions(context)) as
+      | JsonSchema
+      | undefined
+  },
+})
+
+/** Built-in converters, tried after the user's. */
+export const BUILT_IN_CONVERTERS: readonly SchemaConverter[] = Object.freeze([
+  standardJsonSchemaConverter,
+  valibotConverter,
+])

package/src/decorators.ts

@@ -0,0 +1,187 @@
+/**
+ * Decorators of `@znight/openapi`. Like every Znight decorator they do nothing at runtime: the
+ * compiler extension (`@znight/openapi/compiler`) reads them, type arguments included
+ * (`@ApiResponse<Book[]>(200)`), and the Vite plugin strips them from the bundle.
+ */
+import type { ClassMarker, MethodMarker } from '@znight/core'
+import type { RouteDecorator, StandardSchemaV1 } from '@znight/http'
+import type {
+  ExternalDocumentationObject,
+  HeaderObject,
+  InfoObject,
+  JsonValue,
+  SecuritySchemeObject,
+  ServerObject,
+  TagObject,
+} from './types.ts'
+
+function marker(): void {
+  // intentionally empty: decorators are compile-time markers
+}
+
+const classMarker: ClassMarker = marker
+const methodMarker: MethodMarker = marker
+const classOrMethodMarker: ClassMarker & MethodMarker = marker
+
+/** A security scheme declared with {@link securityScheme}. */
+export interface SecurityScheme {
+  /** Key of the scheme in `components.securitySchemes`. */
+  readonly name: string
+  readonly definition: SecuritySchemeObject
+}
+
+/** One scheme, several schemes that all apply (AND), or a scheme with scopes. */
+export type SecurityRequirementInput =
+  | SecurityScheme
+  | readonly SecurityScheme[]
+  | { readonly scheme: SecurityScheme; readonly scopes: readonly string[] }
+
+/** Security of the routes carrying a route decorator (§5.5 of RFC 0002). */
+export interface SecurityDecision {
+  /** A route decorator (`createRouteDecorator`) found in the route's effective metadata. */
+  // biome-ignore lint/suspicious/noExplicitAny: any route decorator value type is accepted
+  readonly when: RouteDecorator<any>
+  /** Requirements of the matching routes; `[]` means public. */
+  readonly security: readonly SecurityRequirementInput[]
+  /** `'value'`: the decorator value (a static string array) becomes the scopes of every requirement. */
+  readonly scopes?: 'value'
+}
+
+/** Style of the default operation ids. */
+export type OperationIdStyle = 'controller.handler' | 'handler' | 'Controller_handler'
+
+/** Options of {@link OpenApiDocument}. */
+export interface OpenApiDocumentOptions {
+  /** Title, version, description... (defaults: the JSDoc of the class, then `package.json`). */
+  readonly info?: Partial<InfoObject>
+  readonly servers?: readonly ServerObject[]
+  /** Declared tags first, in this order; used tags are added, sorted. */
+  readonly tags?: readonly TagObject[]
+  readonly externalDocs?: ExternalDocumentationObject
+  /** Default requirements of every operation: entries are alternatives (OR). Default: none. */
+  readonly security?: readonly SecurityRequirementInput[]
+  /** Security derived from route decorators; the first matching entry wins. */
+  readonly decisions?: readonly SecurityDecision[]
+  /** Ids of operations without `@ApiOperation({ operationId })`. Default `'controller.handler'`. */
+  readonly operationIds?: OperationIdStyle
+  /** Standard error responses (400, 413, 415, declared 4XX/5XX). Default `true`. */
+  readonly errors?: boolean | { readonly schema: StandardSchemaV1; readonly contentType?: string }
+  /** ZNIGHT031 and ZNIGHT032 become errors. Default `false`. */
+  readonly strict?: boolean
+  /** Read the JSDoc of controllers, handlers and types. Default `true`. */
+  readonly jsdoc?: boolean
+  /** `x-*` fields of the root object. */
+  readonly extensions?: Readonly<Record<`x-${string}`, JsonValue>>
+}
+
+/**
+ * Options of the document (one per application, optional). The class is never instantiated nor
+ * registered as a provider; its JSDoc gives the title (first line) and the description (the rest).
+ *
+ * ```ts
+ * /** Bookshelf API *\/
+ * @OpenApiDocument({ servers: [{ url: '/api' }], security: [ApiKey], decisions: [{ when: Public, security: [] }] })
+ * export class BookshelfApi {}
+ * ```
+ */
+export function OpenApiDocument(_options?: OpenApiDocumentOptions): ClassMarker {
+  return classMarker
+}
+
+/**
+ * Declares a security scheme, read statically by the compiler. At runtime it returns a frozen
+ * `{ name, definition }`.
+ *
+ * ```ts
+ * export const ApiKey = securityScheme('apiKey', { type: 'apiKey', in: 'header', name: 'x-api-key' })
+ * ```
+ */
+export function securityScheme(name: string, definition: SecuritySchemeObject): SecurityScheme {
+  return Object.freeze({ name, definition })
+}
+
+/** Options of {@link ApiOperation}. */
+export interface ApiOperationOptions {
+  readonly summary?: string
+  readonly description?: string
+  readonly operationId?: string
+  readonly deprecated?: boolean
+  readonly externalDocs?: ExternalDocumentationObject
+  readonly extensions?: Readonly<Record<`x-${string}`, JsonValue>>
+}
+
+/** Overrides the JSDoc and the defaults of an operation. */
+export function ApiOperation(_options: ApiOperationOptions): MethodMarker {
+  return methodMarker
+}
+
+/** Tags of the operations (class and method tags are merged, class tags first). */
+export function ApiTags(..._names: [string, ...string[]]): ClassMarker & MethodMarker {
+  return classOrMethodMarker
+}
+
+/** A response status: a code, `'2XX'`-like ranges, or `'default'`. */
+export type ApiResponseStatus = number | `${1 | 2 | 3 | 4 | 5}XX` | 'default'
+
+/** Options of {@link ApiResponse}. */
+export interface ApiResponseOptions {
+  readonly description?: string
+  /** Body schema (a Standard Schema, documented with its output JSON Schema). */
+  readonly schema?: StandardSchemaV1
+  /** Media type(s) of the body. Default `application/json` (when the body has a schema). */
+  readonly contentType?: string | readonly string[]
+  readonly headers?: Readonly<Record<string, Partial<HeaderObject>>>
+  readonly example?: JsonValue
+}
+
+/**
+ * Declares or overrides a response (repeatable). The body type comes from `T`
+ * (`@ApiResponse<Book>(200)`) or from a Standard Schema in `schema`.
+ */
+export function ApiResponse<_T = never>(_status: ApiResponseStatus, _options?: ApiResponseOptions): MethodMarker {
+  return methodMarker
+}
+
+/** Options of {@link ApiBody}. */
+export interface ApiBodyOptions {
+  readonly description?: string
+  readonly required?: boolean
+  readonly contentType?: string | readonly string[]
+  readonly schema?: StandardSchemaV1
+}
+
+/** The body of a route that reads it itself (`ctx.parseBody()`, `ctx.bodyStream()`). */
+export function ApiBody<_T = never>(_options?: ApiBodyOptions): MethodMarker {
+  return methodMarker
+}
+
+/** Options of {@link ApiQuery} and {@link ApiHeader}. */
+export interface ApiParameterOptions {
+  readonly description?: string
+  readonly required?: boolean
+  readonly deprecated?: boolean
+  readonly example?: JsonValue
+}
+
+/** A query parameter read outside the signature (`ctx.query`); its type is `T` (default `string`). */
+export function ApiQuery<_T = string>(_name: string, _options?: ApiParameterOptions): MethodMarker {
+  return methodMarker
+}
+
+/** A header read by a guard or an interceptor (`x-tenant`); its type is `T` (default `string`). */
+export function ApiHeader<_T = string>(_name: string, _options?: ApiParameterOptions): ClassMarker & MethodMarker {
+  return classOrMethodMarker
+}
+
+/**
+ * Security of the operations: the route's wins over the class's. Several arguments are
+ * alternatives (OR); no argument means public (`security: []`).
+ */
+export function ApiSecurity(..._requirements: SecurityRequirementInput[]): ClassMarker & MethodMarker {
+  return classOrMethodMarker
+}
+
+/** The controller or route is not documented. */
+export function ApiExclude(): ClassMarker & MethodMarker {
+  return classOrMethodMarker
+}

package/src/emit/child.ts

@@ -0,0 +1,144 @@
+/**
+ * The child process of `emitOpenApi()` (§7.5 of RFC 0002): loads the generated module of the
+ * application (nothing is instantiated: no container, no plugin, no port), builds the document and
+ * writes the result as JSON. Module side effects and globals stay in this process.
+ *
+ * - Bun: the compiler's preload serves the generated module and blanks the decorators.
+ * - Node.js: a Vite server in middleware mode runs the module with the project config (the
+ *   `znight()` plugin serves the generated module from memory).
+ *
+ * Usage: `<runtime> child <payload.json>` (the payload says where to write the result).
+ */
+import type { ZnightMetadata } from '@znight/core'
+import type { SchemaConverter } from '../converters.ts'
+import type { ChildPayload, ChildResult } from './protocol.ts'
+
+import { readFileSync, writeFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+import { buildOpenApiDocument } from '../build.ts'
+
+const payload = JSON.parse(readFileSync(process.argv[2] ?? '', 'utf8')) as ChildPayload
+
+/** Imports a package as installed in the project (falls back to `@znight/openapi`'s resolution). */
+function importFromProject(specifier: string): Promise<unknown> {
+  let resolved: string | undefined
+  try {
+    resolved = createRequire(join(payload.root, 'package.json')).resolve(specifier)
+  } catch {
+    resolved = undefined
+  }
+  return import(resolved === undefined ? specifier : pathToFileURL(resolved).href)
+}
+
+function convertersOf(module: unknown, file: string): SchemaConverter[] {
+  const value = (module as { default?: unknown } | undefined)?.default
+  if (!Array.isArray(value) || value.some(converter => typeof (converter as SchemaConverter)?.convert !== 'function')) {
+    throw new Error(`${file} must export an array of SchemaConverter as default export`)
+  }
+  return value as SchemaConverter[]
+}
+
+interface Loaded {
+  readonly metadata: ZnightMetadata
+  readonly converters: SchemaConverter[]
+  close(): Promise<void>
+}
+
+async function loadWithBun(): Promise<Loaded> {
+  const compiler = (await importFromProject('@znight/compiler')) as {
+    createPreload(options: Record<string, unknown>): Promise<unknown>
+    loadZnightConfig(cwd: string): Promise<{ file: string | undefined; options: Record<string, unknown> }>
+  }
+  const config = await compiler.loadZnightConfig(payload.root)
+  const options = config.file === undefined ? payload.compilerOptions : config.options
+  await compiler.createPreload({ ...options, root: payload.root, mode: 'serve', logLevel: 'silent' })
+  const module = (await import(pathToFileURL(payload.outFile).href)) as { __ZNIGHT_METADATA__: ZnightMetadata }
+  const converters =
+    payload.converters === undefined
+      ? []
+      : convertersOf(await import(pathToFileURL(payload.converters).href), payload.converters)
+  return { metadata: module.__ZNIGHT_METADATA__, converters, close: async () => {} }
+}
+
+interface ViteLike {
+  createServer(config: Record<string, unknown>): Promise<{
+    readonly environments: Record<string, unknown>
+    close(): Promise<void>
+  }>
+  isRunnableDevEnvironment?(environment: unknown): boolean
+}
+
+async function loadWithVite(): Promise<Loaded> {
+  const vite = (await importFromProject('vite')) as ViteLike
+  const plugins: unknown[] = []
+  if (payload.viteConfig === false) {
+    const compiler = (await importFromProject('@znight/compiler')) as { znight(options: unknown): unknown }
+    plugins.push(compiler.znight({ ...payload.compilerOptions, root: payload.root }))
+  }
+  const server = await vite.createServer({
+    root: payload.root,
+    configFile: payload.viteConfig,
+    ...(payload.configLoader === undefined ? {} : { configLoader: payload.configLoader }),
+    appType: 'custom',
+    logLevel: 'error',
+    clearScreen: false,
+    server: { middlewareMode: true, hmr: false, watch: null, ws: false },
+    plugins,
+    ...(payload.sourceConditions === true
+      ? {
+          environments: {
+            ssr: {
+              resolve: {
+                conditions: ['@znight/source', 'module', 'node', 'development|production'],
+                externalConditions: ['@znight/source', 'node'],
+              },
+            },
+          },
+        }
+      : {}),
+  })
+  try {
+    const environment = server.environments['ssr'] as { runner?: { import(url: string): Promise<unknown> } }
+    if (typeof vite.isRunnableDevEnvironment === 'function' && !vite.isRunnableDevEnvironment(environment)) {
+      throw new Error('the ssr environment of the Vite config cannot run modules (isRunnableDevEnvironment)')
+    }
+    const runner = environment.runner
+    if (runner === undefined) throw new Error('the ssr environment of the Vite config has no module runner')
+    const module = (await runner.import(payload.outFile)) as { __ZNIGHT_METADATA__: ZnightMetadata }
+    const converters =
+      payload.converters === undefined ? [] : convertersOf(await runner.import(payload.converters), payload.converters)
+    return { metadata: module.__ZNIGHT_METADATA__, converters, close: () => server.close() }
+  } catch (error) {
+    await server.close()
+    throw error
+  }
+}
+
+let result: ChildResult
+try {
+  const loaded = payload.runtime === 'bun' ? await loadWithBun() : await loadWithVite()
+  try {
+    const built = await buildOpenApiDocument(loaded.metadata, {
+      ...(payload.prefix === undefined ? {} : { prefix: payload.prefix }),
+      converters: loaded.converters,
+    })
+    result = { ok: true, json: built.json, warnings: built.warnings, stats: built.stats }
+  } finally {
+    await loaded.close()
+  }
+} catch (error) {
+  const details = error as { code?: unknown; hints?: unknown; message?: unknown }
+  result = {
+    ok: false,
+    error: {
+      code: typeof details.code === 'string' ? details.code : undefined,
+      message: error instanceof Error ? error.message : String(error),
+      hints: Array.isArray(details.hints) ? (details.hints as string[]) : [],
+    },
+  }
+}
+writeFileSync(payload.result, JSON.stringify(result))
+process.exit(0)