@enzopita/adonisjs-openapi 0.0.0-stage → 0.2.0

package/build/src/docs/routes.js

@@ -0,0 +1,81 @@
+import { readFile } from 'node:fs/promises';
+import { basename } from 'node:path/posix';
+import app from '@adonisjs/core/services/app';
+import router from '@adonisjs/core/services/router';
+import { createError } from '@adonisjs/core/exceptions';
+import { defineConfig } from "../define_config.js";
+import { renderPage } from "./ui.js";
+const E_OPENAPI_DOCUMENT_MISSING = createError('Cannot find the OpenAPI document at "%s". Run "node ace openapi:generate", or register the "@enzopita/adonisjs-openapi/build_hook" build hook so "node ace build" writes it', 'E_OPENAPI_DOCUMENT_MISSING', 500);
+function openapiConfig() {
+    return app.config.get('openapi') ?? defineConfig();
+}
+/**
+ * The page is served at `<prefix>` and the document at `<prefix>/openapi.json`, so the
+ * document URL only depends on the last segment of the URL the page was requested with.
+ */
+function documentUrl(pagePath) {
+    return pagePath.endsWith('/') ? 'openapi.json' : `${basename(pagePath)}/openapi.json`;
+}
+/**
+ * Shield sets the nonce when CSP is enabled. This package does not depend on Shield, so its type is not augmented here.
+ */
+function cspNonce(response) {
+    return 'nonce' in response ? String(response.nonce) : undefined;
+}
+async function generateLive() {
+    // Loaded on demand: it pulls in the assembler, a dev dependency that a production install leaves out.
+    const { generateDocument } = await import("../generate.js");
+    const { document } = await generateDocument(app, router, openapiConfig());
+    return document;
+}
+async function readGenerated(file) {
+    const path = app.makePath(file);
+    try {
+        return JSON.parse(await readFile(path, 'utf8'));
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+            throw new E_OPENAPI_DOCUMENT_MISSING([app.relativePath(path)], { cause: error });
+        }
+        throw error;
+    }
+}
+function documentSource(options) {
+    const source = options.source ?? (app.inProduction ? 'file' : 'live');
+    if (source === 'live')
+        return generateLive;
+    const file = () => options.file ?? openapiConfig().output;
+    if (!app.inProduction)
+        return () => readGenerated(file());
+    let cached;
+    return async () => (cached ??= await readGenerated(file()));
+}
+/**
+ * Registers the docs page and the document it renders, as closure routes so the
+ * generator leaves them out of the document.
+ */
+export function openapiRoutes(options = {}) {
+    const loadDocument = documentSource(options);
+    return router
+        .group(() => {
+        router
+            .get('/', ({ request, response }) => {
+            const page = renderPage(options, {
+                title: options.title ?? openapiConfig().info.title,
+                documentUrl: documentUrl(request.url()),
+                nonce: cspNonce(response),
+            });
+            response.header('content-type', 'text/html; charset=utf-8');
+            return page;
+        })
+            .as('openapi.ui');
+        router
+            .get('/openapi.json', async (ctx) => {
+            const document = await loadDocument();
+            // A copy, so a transform that edits the document in place cannot leak into the cached one.
+            return options.transform ? options.transform(structuredClone(document), ctx) : document;
+        })
+            .as('openapi.document');
+    })
+        .prefix(options.prefix ?? '/docs');
+}

package/build/src/docs/scalar.d.ts

@@ -0,0 +1,11 @@
+import type { DocsPage, UiOptions } from '../types.ts';
+declare const cdn: {
+    script: string;
+};
+export declare const scalar: {
+    cdn: {
+        script: string;
+    };
+    render(page: DocsPage, assets: typeof cdn, uiOptions: UiOptions): string;
+};
+export {};

package/build/src/docs/scalar.js

@@ -0,0 +1,15 @@
+import { escapeHtml, htmlPage, script, scriptJson } from "./html.js";
+const cdn = {
+    script: 'https://cdn.jsdelivr.net/npm/@scalar/api-reference@1/dist/browser/standalone.js',
+};
+export const scalar = {
+    cdn,
+    render(page, assets, uiOptions) {
+        const config = scriptJson({ url: page.documentUrl, ...uiOptions });
+        return htmlPage(page, [], [
+            '<div id="app"></div>',
+            script(page, ` src="${escapeHtml(assets.script)}"`),
+            script(page, '', `Scalar.createApiReference('#app', ${config})`),
+        ]);
+    },
+};

package/build/src/docs/swagger_ui.d.ts

@@ -0,0 +1,13 @@
+import type { DocsPage, UiOptions } from '../types.ts';
+declare const cdn: {
+    script: string;
+    style: string;
+};
+export declare const swaggerUi: {
+    cdn: {
+        script: string;
+        style: string;
+    };
+    render(page: DocsPage, assets: typeof cdn, uiOptions: UiOptions): string;
+};
+export {};

package/build/src/docs/swagger_ui.js

@@ -0,0 +1,16 @@
+import { escapeHtml, htmlPage, script, scriptJson } from "./html.js";
+const cdn = {
+    script: 'https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui-bundle.js',
+    style: 'https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui.css',
+};
+export const swaggerUi = {
+    cdn,
+    render(page, assets, uiOptions) {
+        const config = scriptJson({ url: page.documentUrl, dom_id: '#swagger-ui', ...uiOptions });
+        return htmlPage(page, [`<link rel="stylesheet" href="${escapeHtml(assets.style)}" />`], [
+            '<div id="swagger-ui"></div>',
+            script(page, ` src="${escapeHtml(assets.script)}"`),
+            script(page, '', `window.ui = SwaggerUIBundle(${config})`),
+        ]);
+    },
+};

package/build/src/docs/ui.d.ts

@@ -0,0 +1,2 @@
+import type { DocsPage, DocsUi } from '../types.ts';
+export declare function renderPage(options: DocsUi, page: DocsPage): string;

package/build/src/docs/ui.js

@@ -0,0 +1,13 @@
+import { redoc } from "./redoc.js";
+import { scalar } from "./scalar.js";
+import { swaggerUi } from "./swagger_ui.js";
+const renderers = { scalar, 'swagger-ui': swaggerUi, redoc };
+function renderBuiltIn(ui, page, cdn, uiOptions) {
+    const renderer = renderers[ui];
+    return renderer.render(page, { ...renderer.cdn, ...cdn }, uiOptions);
+}
+export function renderPage(options, page) {
+    if (options.ui instanceof Function)
+        return options.ui(page);
+    return renderBuiltIn(options.ui ?? 'scalar', page, options.cdn, options.uiOptions ?? {});
+}

package/build/src/generate.d.ts

@@ -0,0 +1,8 @@
+import type { ApplicationService } from '@adonisjs/core/types';
+import type { Router } from '@adonisjs/core/http';
+import type { OpenApiConfig, OpenApiDocument } from './types.ts';
+export interface GeneratedDocument {
+    document: OpenApiDocument;
+    warnings: string[];
+}
+export declare function generateDocument(app: ApplicationService, router: Router, config: OpenApiConfig): Promise<GeneratedDocument>;

package/build/src/generate.js

@@ -0,0 +1,159 @@
+import { STATUS_CODES } from 'node:http';
+import { fileURLToPath } from 'node:url';
+import ts from 'typescript';
+import { collectRoutes } from "./collect_routes.js";
+import { RouteTypes } from "./route_types.js";
+const NOT_IN_BODY = new Set(['query', 'params', 'headers', 'cookies']);
+/**
+ * Vine knows the constraints (formats, bounds, enums) but has no JSON Schema for
+ * files or custom rules and emits `{}` there: the TypeScript shape fills those gaps.
+ */
+function mergeSchemas(vine, typed) {
+    if (!vine || !Object.keys(vine).length)
+        return typed;
+    if (!vine.properties || !typed.properties)
+        return vine;
+    const typedProperties = typed.properties;
+    const properties = Object.fromEntries(Object.entries(vine.properties).map(([key, schema]) => [
+        key,
+        mergeSchemas(schema, typedProperties[key] ?? {}),
+    ]));
+    return { ...vine, properties };
+}
+function pick(schema, keep) {
+    const properties = Object.entries(schema.properties ?? {}).filter(([key]) => keep(key));
+    if (!properties.length)
+        return undefined;
+    const { required = [], ...rest } = schema;
+    const kept = required.filter(keep);
+    return kept.length
+        ? { ...rest, properties: Object.fromEntries(properties), required: kept }
+        : { ...rest, properties: Object.fromEntries(properties) };
+}
+async function validatorSchemas(app, routes, warnings) {
+    const schemas = new Map();
+    for (const route of routes) {
+        if (!route.validator)
+            continue;
+        const { specifier, exportName } = route.validator;
+        try {
+            // SAFETY: the routes scanner only reports values passed to `request.validateUsing()`, which are Vine validators.
+            const module = (await app.import(specifier));
+            const validator = module[exportName];
+            if (validator)
+                schemas.set(route.name, validator.toJSONSchema());
+        }
+        catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            warnings.push(`${route.name}: cannot read the JSON Schema of ${specifier}#${exportName} (${reason})`);
+        }
+    }
+    return schemas;
+}
+const EMPTY_STATUSES = new Set(['204', '205', '304']);
+const WITHOUT_BODY = ts.TypeFlags.Any | ts.TypeFlags.Unknown | ts.TypeFlags.Void | ts.TypeFlags.Undefined;
+function responsesFor(route, types, response, thrown, secured, warnings) {
+    const responses = {};
+    const describe = (code, payload) => {
+        const description = STATUS_CODES[Number(code)] ?? 'Response';
+        const empty = !payload || EMPTY_STATUSES.has(code) || payload.flags & WITHOUT_BODY;
+        responses[code] = empty
+            ? { description }
+            : { description, content: { 'application/json': { schema: types.schemas.convert(payload) } } };
+    };
+    const members = response?.isUnion() ? response.types : response ? [response] : [];
+    for (const member of members) {
+        const status = types.property(member, '__status');
+        const payload = types.property(member, '__response');
+        if (status && payload) {
+            describe(status.isNumberLiteral() ? String(status.value) : 'default', payload);
+        }
+        else if (!(member.flags & (ts.TypeFlags.Any | ts.TypeFlags.Unknown))) {
+            describe('200', member);
+        }
+    }
+    for (const [code, description] of Object.entries(thrown))
+        responses[code] ??= { description };
+    const validationError = route.validator && types.validationError();
+    if (validationError && !responses['422'])
+        describe('422', validationError);
+    if (secured && !responses['401'])
+        describe('401');
+    if (!Object.keys(responses).some(code => code.startsWith('2') || code === 'default')) {
+        warnings.push(`${route.name}: the handler's return type is unknown, returning serialize(...) makes it typed`);
+        responses['200'] = { description: 'OK' };
+    }
+    return responses;
+}
+function parametersFor(route, query, params) {
+    const path = route.pathParams.map((name) => ({
+        name,
+        in: 'path',
+        required: true,
+        schema: params?.properties?.[name] ?? { type: 'string' },
+    }));
+    const search = Object.entries(query?.properties ?? {}).map(([name, schema]) => ({
+        name,
+        in: 'query',
+        required: query?.required?.includes(name) ?? false,
+        schema,
+    }));
+    return [...path, ...search];
+}
+export async function generateDocument(app, router, config) {
+    const warnings = [];
+    const appRoot = fileURLToPath(app.appRoot);
+    const routes = await collectRoutes(appRoot, router, config);
+    const types = new RouteTypes(appRoot, routes);
+    const vine = await validatorSchemas(app, routes, warnings);
+    const paths = {};
+    for (const route of routes) {
+        const { request, response } = types.get(route.name);
+        const input = request && mergeSchemas(vine.get(route.name), types.schemas.convert(request));
+        const readsQueryOnly = route.methods.every(method => method === 'get' || method === 'options');
+        const fields = input && pick(input, key => !NOT_IN_BODY.has(key));
+        const body = readsQueryOnly ? undefined : fields;
+        const query = readsQueryOnly ? fields : input?.properties?.query;
+        const parameters = parametersFor(route, query, input?.properties?.params);
+        const security = route.middleware.flatMap(name => {
+            const scheme = config.middlewareSecurity[name];
+            return scheme ? [{ [scheme]: [] }] : [];
+        });
+        const { responses: thrown, ...docs } = types.docs(route);
+        const operation = {
+            ...docs,
+            tags: docs.tags ?? [route.name.split('.')[0] ?? route.name],
+            responses: responsesFor(route, types, response, thrown, security.length > 0, warnings),
+        };
+        if (parameters.length)
+            operation.parameters = parameters;
+        if (security.length)
+            operation.security = security;
+        if (body) {
+            const mediaType = JSON.stringify(body).includes('"format":"binary"')
+                ? 'multipart/form-data'
+                : 'application/json';
+            operation.requestBody = { required: true, content: { [mediaType]: { schema: body } } };
+        }
+        const methods = paths[route.path] ?? {};
+        paths[route.path] = methods;
+        for (const method of route.methods) {
+            const operationId = route.methods.length > 1 ? `${route.name}.${method}` : route.name;
+            methods[method] = { operationId, ...operation };
+        }
+    }
+    for (const type of types.schemas.unsupported) {
+        warnings.push(`no JSON Schema for the type ${type}, emitted {}`);
+    }
+    const document = {
+        openapi: '3.1.0',
+        info: config.info,
+        paths,
+        components: { schemas: types.schemas.components, securitySchemes: config.securitySchemes },
+    };
+    if (config.servers.length)
+        document.servers = config.servers;
+    if (config.tags.length)
+        document.tags = config.tags;
+    return { document, warnings };
+}

package/build/src/operation_docs.d.ts

@@ -0,0 +1,12 @@
+import ts from 'typescript';
+export interface OperationDocs {
+    summary?: string;
+    description?: string;
+    tags?: string[];
+    deprecated?: true;
+    /**
+     * Status code to description, from `@throws {404} User not found`.
+     */
+    responses: Record<string, string>;
+}
+export declare function operationDocs(controller: ts.ClassDeclaration, method: ts.MethodDeclaration): OperationDocs;

package/build/src/operation_docs.js

@@ -0,0 +1,51 @@
+import { STATUS_CODES } from 'node:http';
+import ts from 'typescript';
+function jsDoc(node) {
+    return ts.getJSDocCommentsAndTags(node).filter(ts.isJSDoc).at(-1);
+}
+function tagText(tag) {
+    return ts.getTextOfJSDocComment(tag.comment)?.trim() ?? '';
+}
+function tagsOf(doc) {
+    const tag = doc?.tags?.find(candidate => candidate.tagName.text === 'tags');
+    return (tag &&
+        tagText(tag)
+            .split(',')
+            .map(name => name.trim())
+            .filter(Boolean));
+}
+/**
+ * `@throws {404}` parses as a JSDoc type expression holding the literal type `404`.
+ */
+function thrownStatus(tag) {
+    const type = ts.isJSDocThrowsTag(tag) ? tag.typeExpression?.type : undefined;
+    if (!type || !ts.isLiteralTypeNode(type) || !ts.isNumericLiteral(type.literal))
+        return undefined;
+    return /^\d{3}$/.test(type.literal.text) ? type.literal.text : undefined;
+}
+export function operationDocs(controller, method) {
+    const doc = jsDoc(method);
+    const responses = {};
+    const tags = tagsOf(doc) ?? tagsOf(jsDoc(controller));
+    let deprecated = false;
+    const [summary, ...paragraphs] = (ts.getTextOfJSDocComment(doc?.comment) ?? '')
+        .split(/\n\s*\n/)
+        .map(paragraph => paragraph.trim())
+        .filter(Boolean);
+    for (const tag of doc?.tags ?? []) {
+        const status = thrownStatus(tag);
+        if (status)
+            responses[status] = tagText(tag) || (STATUS_CODES[Number(status)] ?? status);
+        else if (ts.isJSDocDeprecatedTag(tag))
+            deprecated = true;
+        else if (tag.tagName.text === 'remarks' && tagText(tag))
+            paragraphs.push(tagText(tag));
+    }
+    return {
+        ...(summary && { summary }),
+        ...(paragraphs.length > 0 && { description: paragraphs.join('\n\n') }),
+        ...(tags?.length && { tags }),
+        ...(deprecated && { deprecated: true }),
+        responses,
+    };
+}

package/build/src/route_types.d.ts

@@ -0,0 +1,30 @@
+import ts from 'typescript';
+import { type OperationDocs } from './operation_docs.ts';
+import { TypeToSchema } from './type_to_schema.ts';
+import type { RouteOperation } from './types.ts';
+/**
+ * Resolves the request and response types of every route with the app's own
+ * tsconfig, through one in-memory module that names them all.
+ */
+export declare class RouteTypes {
+    #private;
+    readonly checker: ts.TypeChecker;
+    readonly schemas: TypeToSchema;
+    constructor(appRoot: string, routes: RouteOperation[]);
+    /**
+     * The types of one route's `request` and `response` members.
+     */
+    get(routeName: string): {
+        request?: undefined;
+        response?: undefined;
+    } | {
+        request: ts.Type | undefined;
+        response: ts.Type | undefined;
+    };
+    validationError(): ts.Type | undefined;
+    /**
+     * The doc comments on the handler, read from the controller class the file exports by default.
+     */
+    docs({ controller }: RouteOperation): OperationDocs;
+    property(type: ts.Type, name: string): ts.Type | undefined;
+}

package/build/src/route_types.js

@@ -0,0 +1,169 @@
+import ts from 'typescript';
+import { existsSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { operationDocs } from "./operation_docs.js";
+import { TypeToSchema } from "./type_to_schema.js";
+/**
+ * The `HttpResponse` helpers that set a status code, as Tuyau types them minus the
+ * informational and redirect ones. Declared here as well so apps without Tuyau get them.
+ */
+const RESPONSE_HELPERS = {
+    ok: 200,
+    json: 200,
+    created: 201,
+    accepted: 202,
+    nonAuthoritativeInformation: 203,
+    noContent: 204,
+    resetContent: 205,
+    partialContent: 206,
+    badRequest: 400,
+    unauthorized: 401,
+    paymentRequired: 402,
+    forbidden: 403,
+    notFound: 404,
+    methodNotAllowed: 405,
+    notAcceptable: 406,
+    proxyAuthenticationRequired: 407,
+    requestTimeout: 408,
+    conflict: 409,
+    gone: 410,
+    lengthRequired: 411,
+    preconditionFailed: 412,
+    requestEntityTooLarge: 413,
+    requestUriTooLong: 414,
+    unsupportedMediaType: 415,
+    requestedRangeNotSatisfiable: 416,
+    expectationFailed: 417,
+    unprocessableEntity: 422,
+    tooManyRequests: 429,
+    internalServerError: 500,
+    notImplemented: 501,
+    badGateway: 502,
+    serviceUnavailable: 503,
+    gatewayTimeout: 504,
+    httpVersionNotSupported: 505,
+};
+/**
+ * Resolves the request and response types of every route with the app's own
+ * tsconfig, through one in-memory module that names them all.
+ */
+export class RouteTypes {
+    checker;
+    schemas;
+    #program;
+    #routes;
+    #validationError;
+    constructor(appRoot, routes) {
+        const entryFile = join(appRoot, '.adonisjs/openapi/routes.ts');
+        const dataFile = join(appRoot, '.adonisjs/client/data.d.ts');
+        const config = ts.getParsedCommandLineOfConfigFile(join(appRoot, 'tsconfig.json'), {}, {
+            ...ts.sys,
+            onUnRecoverableConfigFileDiagnostic: diagnostic => {
+                throw new Error(ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n'));
+            },
+        });
+        if (!config)
+            throw new Error(`openapi: cannot read ${join(appRoot, 'tsconfig.json')}`);
+        const source = renderEntry(entryFile, appRoot, routes);
+        const host = ts.createCompilerHost(config.options);
+        const getSourceFile = host.getSourceFile.bind(host);
+        host.getSourceFile = (fileName, languageVersion, ...rest) => fileName === entryFile
+            ? ts.createSourceFile(fileName, source, languageVersion)
+            : getSourceFile(fileName, languageVersion, ...rest);
+        const fileExists = host.fileExists.bind(host);
+        host.fileExists = fileName => fileName === entryFile || fileExists(fileName);
+        // The app's own files carry the module augmentations (container bindings, auth guards) the types depend on.
+        const program = ts.createProgram({
+            rootNames: [...config.fileNames, entryFile, ...(existsSync(dataFile) ? [dataFile] : [])],
+            options: { ...config.options, noEmit: true },
+            host,
+        });
+        this.#program = program;
+        this.checker = program.getTypeChecker();
+        const entry = program.getSourceFile(entryFile);
+        this.#routes = entry.statements.find(ts.isInterfaceDeclaration);
+        this.#validationError = entry.statements.find(ts.isTypeAliasDeclaration);
+        const validationError = this.validationError();
+        const named = new Map(this.#transformerTypes(program.getSourceFile(dataFile)));
+        if (validationError)
+            named.set(validationError, 'ValidationError');
+        this.schemas = new TypeToSchema(this.checker, named);
+    }
+    /**
+     * The types `node ace codegen` names in `Data`, keyed by their path below it (`Admin.User`).
+     */
+    #transformerTypes(dataFile) {
+        const module = dataFile && this.checker.getSymbolAtLocation(dataFile);
+        const data = module && this.checker.tryGetMemberInModuleExports('Data', module);
+        const walk = (namespace, path) => this.checker.getExportsOfModule(namespace).flatMap(symbol => {
+            if (symbol.name === 'Variants')
+                return [];
+            const name = [...path, symbol.name];
+            const nested = symbol.flags & ts.SymbolFlags.Namespace ? walk(symbol, name) : [];
+            if (!(symbol.flags & ts.SymbolFlags.TypeAlias))
+                return nested;
+            return [[this.checker.getDeclaredTypeOfSymbol(symbol), name.join('.')], ...nested];
+        });
+        return data ? walk(data, []) : [];
+    }
+    /**
+     * The types of one route's `request` and `response` members.
+     */
+    get(routeName) {
+        const member = this.#routes.members.find((candidate) => ts.isPropertySignature(candidate) &&
+            ts.isStringLiteral(candidate.name) &&
+            candidate.name.text === routeName);
+        if (!member)
+            return {};
+        const type = this.checker.getTypeAtLocation(member);
+        return { request: this.property(type, 'request'), response: this.property(type, 'response') };
+    }
+    validationError() {
+        return this.#validationError && this.checker.getTypeAtLocation(this.#validationError);
+    }
+    /**
+     * The doc comments on the handler, read from the controller class the file exports by default.
+     */
+    docs({ controller }) {
+        const file = controller && this.#program.getSourceFile(controller.path);
+        const module = file && this.checker.getSymbolAtLocation(file);
+        const exported = module && this.checker.tryGetMemberInModuleExports('default', module);
+        const symbol = exported && exported.flags & ts.SymbolFlags.Alias
+            ? this.checker.getAliasedSymbol(exported)
+            : exported;
+        const declaration = symbol?.declarations?.find(ts.isClassDeclaration);
+        const method = declaration?.members.find((member) => ts.isMethodDeclaration(member) &&
+            ts.isIdentifier(member.name) &&
+            member.name.text === controller?.method);
+        return declaration && method ? operationDocs(declaration, method) : { responses: {} };
+    }
+    property(type, name) {
+        const symbol = this.checker.getPropertyOfType(type, name);
+        return symbol && this.checker.getTypeOfSymbol(symbol);
+    }
+}
+function renderEntry(entryFile, appRoot, routes) {
+    const toRelative = (expression) => expression.replace(/import\('(app\/[^']+?)(\.ts)?'\)/g, (_, path) => {
+        const target = relative(join(entryFile, '..'), join(appRoot, path));
+        return `import('${target}.js')`;
+    });
+    const imports = new Set(routes.flatMap(route => route.imports));
+    const members = routes.map(route => {
+        const request = route.requestType ? `request: ${toRelative(route.requestType)}; ` : '';
+        const response = route.responseType
+            ? `response: Awaited<${toRelative(route.responseType)}>`
+            : '';
+        return `  ${JSON.stringify(route.name)}: { ${request}${response} }`;
+    });
+    const validationError = routes.some(route => route.validator)
+        ? `import type { SimpleError } from '@vinejs/vine/types'\nexport type ValidationError = { errors: SimpleError[] }`
+        : '';
+    const helpers = Object.entries(RESPONSE_HELPERS).map(([name, status]) => `    ${name}<T>(body?: T, etag?: boolean): { __response: T; __status: ${status} }`);
+    const augmentation = `declare module '@adonisjs/core/http' {\n  interface HttpResponse {\n${helpers.join('\n')}\n  }\n}`;
+    return [
+        ...imports,
+        validationError,
+        augmentation,
+        `export interface Routes {\n${members.join('\n')}\n}`,
+    ].join('\n');
+}

package/build/src/type_to_schema.d.ts

@@ -0,0 +1,21 @@
+import ts from 'typescript';
+import type { JsonSchema } from './types.ts';
+/**
+ * Converts a type the checker resolved into JSON Schema (draft 2020-12, as OpenAPI 3.1 uses).
+ * Serialized output types are plain data, so methods are dropped and dates become strings.
+ */
+export declare class TypeToSchema {
+    #private;
+    readonly components: Record<string, JsonSchema>;
+    readonly unsupported: Set<string>;
+    /**
+     * Every named type becomes a component up front: a transformer nested in another
+     * resolves to a different type than its `Data` alias, and is matched by its schema.
+     */
+    constructor(checker: ts.TypeChecker, named?: Map<ts.Type, string>);
+    convert(type: ts.Type, stack?: ts.Type[]): JsonSchema;
+    /**
+     * Whether `undefined` is one of the members, which makes an object property optional.
+     */
+    acceptsUndefined(type: ts.Type): boolean;
+}