nestjs-openapi-parser 0.0.1

package/README.md

@@ -0,0 +1,213 @@
+# nestjs-openapi-parser
+
+Generate an OpenAPI 3.x document from a NestJS project by **pure static analysis** of the TypeScript source. No app boot, no `reflect-metadata`, no runtime dependency on `@nestjs/*`. Just [ts-morph](https://ts-morph.com/) reading your `.ts` files.
+
+Ships a CLI (`nestparser`) and a programmatic API.
+
+## Why
+
+`@nestjs/swagger` is excellent but requires booting the application and sprinkling `@Api*` decorators everywhere.
+`nestjs-openapi-parser` takes a different trade-off: it reads your existing code (controllers, DTOs, entities, JSDoc) and
+produces a spec without running anything. That makes it cheap to plug into CI
+and ergonomic when your codebase already follows clear conventions (TypeORM entities, `class-validator` DTOs, JSDoc descriptions).
+
+### Features
+
+- **Zero runtime coupling** — no `@nestjs/*` deps, no `reflect-metadata`, the parser doesn't import your code.
+- **JSDoc-driven descriptions** — class, method and property comments become OpenAPI `description` fields.
+- **Reachability-only schemas** — only classes reached from an endpoint end up in `components.schemas`; orphans don't leak.
+- **Nest mapped types** — `PartialType / PickType / OmitType / IntersectionType` are resolved structurally.
+- **`@Query() dto: DTO`** is expanded into individual query parameters.
+- **`class-validator` constraints** — `@Min/@Max/@MinLength/@IsEmail/@IsUUID/@Matches/@IsInt`… become `minimum/maximum/minLength/format/pattern`…
+- **Self-validating output** — every generated document is checked against the OpenAPI 3.x JSON Schema; an invalid spec throws instead of being emitted.
+- **Pluggable hooks** for response envelopes, security resolution, and tag conventions.
+- **Documentation variants via custom `@Scope` tag in JSDoc** — emit `public`, `internal`, `admin`… flavors of the same spec from a single source.
+- **Tiny config surface** with sane defaults.
+
+## Requirements
+
+- Node.js **>= 18**
+- A NestJS (or NestJS-shaped) project with a `tsconfig.json`
+
+## Install
+
+One-off via `npx`:
+
+```sh
+npx nestjs-openapi-parser --project ./apps/api --out openapi.json
+```
+
+As a dev dependency:
+
+```sh
+npm install --save-dev nestjs-openapi-parser
+# or
+yarn add -D nestjs-openapi-parser
+# or
+pnpm add -D nestjs-openapi-parser
+```
+
+Or install globally:
+
+```sh
+npm install -g nestjs-openapi-parser
+nestparser --help
+```
+
+## Quick start
+
+1. Drop a config file at your project root:
+
+```ts
+// nestparser.config.ts
+import { defineConfig } from 'nestjs-openapi-parser';
+
+export default defineConfig({
+  openapi: {
+    title: 'My API', // Default to `package.json` name
+    version: '1.0.0', // Default to `package.json` version
+    servers: [{ url: 'http://localhost:3000' }],
+    securitySchemes: {
+      bearerAuth: { type: 'http', scheme: 'bearer', bearerFormat: 'JWT' },
+    },
+  },
+  project: {
+    globalPrefix: 'v1',
+  },
+});
+```
+
+2. Run the CLI:
+
+```sh
+npx nestparser --out openapi.json
+```
+
+That's it. You should see something like:
+
+```
+Project root: /path/to/your/api
+Config file:  /path/to/your/api/nestparser.config.ts
+Wrote /path/to/your/api/openapi.json (42 routes, 58 operations, 31 schemas).
+```
+
+## CLI usage
+
+```
+nestparser [options]
+
+Options:
+  -V, --version           output the version number
+  -p, --project <path>    path to the NestJS project root (default: cwd)
+  -o, --out <path>        path to the OpenAPI JSON output file (default: ./openapi.json)
+  -c, --config <path>     path to the nestparser config file (default: auto-discover)
+  -s, --scope <list>      active scopes (comma-separated; repeatable)
+  -h, --help              display help
+```
+
+### Config file discovery
+
+The CLI looks for the first file matching, inside `--project`:
+
+```
+nestparser.config.ts
+nestparser.config.mts
+nestparser.config.cts
+nestparser.config.mjs
+nestparser.config.cjs
+nestparser.config.js
+nestparser.config.json
+```
+
+`.ts` / `.mts` / `.cts` files are loaded via [`tsx`](https://github.com/privatenumber/tsx) (registered lazily — JSON-only users don't pay for it). Use `--config <path>` to point at an explicit file.
+
+**Config is optional.** If auto-discovery finds nothing, the parser emits a warning and falls back to a default config — `openapi.title`/`version` come from the project's `package.json` (`name`/`version`), with everything else on engine defaults (`rootDir: src`, `tsConfigFilePath: tsconfig.json`, no hooks). This lets you run against a vanilla NestJS project with zero setup.
+
+## Library usage
+
+```ts
+import { parseNestProject, loadConfig } from 'nestjs-openapi-parser';
+import { writeFileSync } from 'node:fs';
+
+const projectRoot = process.cwd();
+const { config } = await loadConfig({ projectRoot });
+const document = await parseNestProject({ projectRoot, config });
+
+writeFileSync('openapi.json', JSON.stringify(document, null, 2));
+```
+
+See more in [Library Usage](docs/library-usage.md).
+
+## How to use in NestJS
+
+Write plain NestJS — the parser reads your controllers and models as-is. No config and no
+extra decorators are required; JSDoc comments simply carry over as descriptions.
+
+```ts
+/** A registered user. */
+export class User {
+  id!: string; // → { type: 'string' }, required
+
+  /** Display name. */
+  name!: string; // property JSDoc → schema description
+
+  email?: string; // optional (`?`) → omitted from `required`
+}
+```
+
+```ts
+import { Controller, Delete, Get, Param } from '@nestjs/common';
+import { User } from './user.entity';
+
+/** Manage users. */ // class JSDoc → `Users` tag description
+@Controller('users')
+export class UsersController {
+  /** Fetch a single user by id. */ // method JSDoc → operation description
+  @Get(':id') // `:id` → required path param; summary "Find One"
+  findOne(@Param('id') id: string): Promise<User> {
+    // return type `User` → 200 response body + `User` schema
+  }
+
+  /**
+   * Permanently delete a user.
+   *
+   * @Scope admin   // emitted only when built with --scope admin
+   * @Tag Admin     // groups this operation under the `Admin` tag
+   * @Name Delete user // overrides the auto summary
+   */
+  @Delete(':id')
+  remove(@Param('id') id: string): Promise<void> {}
+}
+```
+
+Run `npx nestparser --out openapi.json` — that's it. See [What it parses](docs/parser.md) for
+every supported construct (DTOs, `class-validator` constraints, enums, `@Scope`, `@Tag`, hooks…).
+
+## What it parses
+
+See [Parser Documentation](docs/parser.md)
+
+## Configuration
+
+See [Configuration Documentation](docs/configuration.md)
+
+## Examples
+
+A complete fixture lives under [`tests/fixtures/example-app/`](tests/fixtures/example-app/) — a self-contained NestJS app with controllers, DTOs, entities, mapped types, scopes and the envelope hook. The corresponding generated OpenAPI documents are snapshotted at [`tests/__snapshots__/`](tests/__snapshots__/) (one file per scope variant).
+
+You can browse any snapshot in a [Scalar](https://github.com/scalar/scalar) UI:
+
+```sh
+yarn snapshot:serve                            # interactive picker (uses prompts)
+yarn snapshot:serve openapi.admin.snap.json    # basename relative to tests/__snapshots__/
+yarn snapshot:serve /tmp/some-spec.json        # any absolute path
+SCALAR_PORT=9000 yarn snapshot:serve           # override the default port (8088)
+```
+
+## Limitations
+
+- Decorators are matched by **local identifier name**. Aliased imports (`import { Post as HttpPost }`) won't be detected — keep them un-aliased or extend via a hook.
+- Pipe detection in `@Param` is textual (`ParseUUIDPipe` / `ParseIntPipe` / `ParseBoolPipe`). Custom pipes fall back to the parameter type.
+- No support yet for `@nestjs/swagger`'s `@ApiProperty(...)` runtime overrides — describe properties via JSDoc instead.
+- Module-level filtering (e.g. emit only routes from one Nest module) is not built in — control it at the `rootDir` / `excludeSuffixes` / `@Scope` level.
+- Route patterns OpenAPI can't represent — inline regex (`:id(\d+)`), wildcards (`*`, `:splat*`), `+`/`*` modifiers, and more than one optional param in a route — are **skipped with a warning**. Optional params (`:id?`) are supported via path splitting.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const node_fs_1 = require("node:fs");
+const node_path_1 = __importDefault(require("node:path"));
+const loader_1 = require("./config/loader");
+const parser_1 = require("./parser");
+const tags_1 = require("./parser/tags");
+function readPackageVersion() {
+    const pkgPath = node_path_1.default.resolve(__dirname, '..', 'package.json');
+    const pkg = JSON.parse((0, node_fs_1.readFileSync)(pkgPath, 'utf-8'));
+    return pkg.version;
+}
+async function run(options) {
+    const projectRoot = node_path_1.default.resolve(options.project);
+    const outPath = node_path_1.default.resolve(options.out);
+    const { config, filePath } = await (0, loader_1.loadConfig)({
+        projectRoot,
+        configPath: options.config,
+    });
+    // CLI --scope overrides config.scopes when present (even empty).
+    const effectiveConfig = options.scope !== undefined ? { ...config, scopes: (0, tags_1.parseScopeList)(options.scope) } : config;
+    console.log(`Project root: ${projectRoot}`);
+    console.log(`Config file:  ${filePath ?? '(none — using defaults)'}`);
+    if (effectiveConfig.scopes && effectiveConfig.scopes.length > 0) {
+        console.log(`Active scopes: ${effectiveConfig.scopes.join(', ')}`);
+    }
+    const document = await (0, parser_1.parseNestProject)({ projectRoot, config: effectiveConfig });
+    (0, node_fs_1.mkdirSync)(node_path_1.default.dirname(outPath), { recursive: true });
+    (0, node_fs_1.writeFileSync)(outPath, JSON.stringify(document, null, 2));
+    const routeCount = Object.keys(document.paths).length;
+    const operationCount = Object.values(document.paths).reduce((acc, ops) => acc + Object.keys(ops).length, 0);
+    const schemaCount = Object.keys(document.components?.schemas ?? {}).length;
+    console.log(`Wrote ${outPath} (${routeCount} routes, ${operationCount} operations, ${schemaCount} schemas).`);
+}
+const program = new commander_1.Command();
+program
+    .name('nestparser')
+    .description('Parse a NestJS project and emit an OpenAPI document.')
+    .version(readPackageVersion())
+    .option('-p, --project <path>', 'path to the NestJS project root', process.cwd())
+    .option('-o, --out <path>', 'path to the OpenAPI JSON output file', node_path_1.default.resolve(process.cwd(), 'openapi.json'))
+    .option('-c, --config <path>', 'path to the nestparser config file (defaults to auto-discovery in the project root)')
+    .option('-s, --scope <list>', 'active scopes (comma-separated; repeatable). Items tagged with @Scope are emitted only when at least one matches; untagged items are always emitted.', (value, prior = []) => [...prior, value])
+    .action(run);
+program.parseAsync(process.argv).catch((err) => {
+    console.error(err instanceof Error ? err.message : err);
+    process.exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/config/defaults.d.ts

@@ -0,0 +1,5 @@
+import type { ConventionsConfig, ProjectConfig } from './types';
+export declare const DEFAULT_PROJECT: Required<Omit<ProjectConfig, 'excludeSuffixes'>> & {
+    excludeSuffixes: string[];
+};
+export declare const DEFAULT_CONVENTIONS: Required<ConventionsConfig>;

package/dist/config/defaults.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_CONVENTIONS = exports.DEFAULT_PROJECT = void 0;
+exports.DEFAULT_PROJECT = {
+    tsConfigFilePath: 'tsconfig.json',
+    rootDir: 'src',
+    globalPrefix: '',
+    excludeSuffixes: ['.spec.ts', '.test.ts', '.d.ts'],
+};
+exports.DEFAULT_CONVENTIONS = {
+    excludeDecorator: 'Exclude',
+    optionalDecorator: 'IsOptional',
+};
+//# sourceMappingURL=defaults.js.map

package/dist/config/defaults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.js","sourceRoot":"","sources":["../../src/config/defaults.ts"],"names":[],"mappings":";;;AAEa,QAAA,eAAe,GAExB;IACF,gBAAgB,EAAE,eAAe;IACjC,OAAO,EAAE,KAAK;IACd,YAAY,EAAE,EAAE;IAChB,eAAe,EAAE,CAAC,UAAU,EAAE,UAAU,EAAE,OAAO,CAAC;CACnD,CAAC;AAEW,QAAA,mBAAmB,GAAgC;IAC9D,gBAAgB,EAAE,SAAS;IAC3B,iBAAiB,EAAE,YAAY;CAChC,CAAC"}

package/dist/config/index.d.ts

@@ -0,0 +1,4 @@
+export * from './types';
+export { DEFAULT_PROJECT, DEFAULT_CONVENTIONS } from './defaults';
+export { loadConfig } from './loader';
+export type { LoadConfigOptions, LoadedConfig } from './loader';

package/dist/config/index.js

@@ -0,0 +1,24 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadConfig = exports.DEFAULT_CONVENTIONS = exports.DEFAULT_PROJECT = void 0;
+__exportStar(require("./types"), exports);
+var defaults_1 = require("./defaults");
+Object.defineProperty(exports, "DEFAULT_PROJECT", { enumerable: true, get: function () { return defaults_1.DEFAULT_PROJECT; } });
+Object.defineProperty(exports, "DEFAULT_CONVENTIONS", { enumerable: true, get: function () { return defaults_1.DEFAULT_CONVENTIONS; } });
+var loader_1 = require("./loader");
+Object.defineProperty(exports, "loadConfig", { enumerable: true, get: function () { return loader_1.loadConfig; } });
+//# sourceMappingURL=index.js.map

package/dist/config/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/config/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,0CAAwB;AACxB,uCAAkE;AAAzD,2GAAA,eAAe,OAAA;AAAE,+GAAA,mBAAmB,OAAA;AAC7C,mCAAsC;AAA7B,oGAAA,UAAU,OAAA"}

package/dist/config/loader.d.ts

@@ -0,0 +1,11 @@
+import type { NestParserConfig } from './types';
+export interface LoadConfigOptions {
+    projectRoot: string;
+    /** Explicit path to a config file, overriding auto-discovery. */
+    configPath?: string;
+}
+export interface LoadedConfig {
+    config: NestParserConfig;
+    filePath: string | undefined;
+}
+export declare function loadConfig(options: LoadConfigOptions): Promise<LoadedConfig>;

package/dist/config/loader.js

@@ -0,0 +1,160 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadConfig = loadConfig;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_url_1 = require("node:url");
+const CANDIDATE_NAMES = [
+    'nestparser.config.ts',
+    'nestparser.config.mts',
+    'nestparser.config.cts',
+    'nestparser.config.mjs',
+    'nestparser.config.cjs',
+    'nestparser.config.js',
+    'nestparser.config.json',
+];
+let tsxRegistered = false;
+function ensureTsxRegistered() {
+    if (tsxRegistered)
+        return;
+    // Register tsx's CommonJS require hook so we can `require('./foo.ts')`.
+    // Imported lazily so JSON-only users don't pay for it.
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    require('tsx/cjs');
+    tsxRegistered = true;
+}
+function findConfigFile(projectRoot, explicit) {
+    if (explicit) {
+        const resolved = node_path_1.default.isAbsolute(explicit) ? explicit : node_path_1.default.resolve(projectRoot, explicit);
+        if (!node_fs_1.default.existsSync(resolved)) {
+            throw new Error(`Config file not found: ${resolved}`);
+        }
+        return resolved;
+    }
+    for (const name of CANDIDATE_NAMES) {
+        const candidate = node_path_1.default.join(projectRoot, name);
+        if (node_fs_1.default.existsSync(candidate))
+            return candidate;
+    }
+    return undefined;
+}
+async function importConfig(filePath) {
+    const ext = node_path_1.default.extname(filePath);
+    if (ext === '.json') {
+        return JSON.parse(node_fs_1.default.readFileSync(filePath, 'utf-8'));
+    }
+    if (ext === '.ts' || ext === '.mts' || ext === '.cts') {
+        ensureTsxRegistered();
+    }
+    if (ext === '.mjs' || ext === '.mts') {
+        const mod = (await Promise.resolve(`${(0, node_url_1.pathToFileURL)(filePath).href}`).then(s => __importStar(require(s))));
+        return mod.default ?? mod;
+    }
+    // .ts / .cts / .cjs / .js — CommonJS path (tsx's require hook covers .ts/.cts)
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const mod = require(filePath);
+    return mod.default ?? mod;
+}
+function isConfigShape(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'openapi' in value &&
+        typeof value.openapi === 'object' &&
+        value.openapi !== null);
+}
+function nonEmptyString(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+/**
+ * Default `openapi.title`/`version` for a project — from its `package.json`
+ * (`name`/`version`) when available, else generic fallbacks. Used both when no
+ * config file exists and to fill in either field a config file leaves out.
+ */
+function resolveOpenApiDefaults(projectRoot) {
+    let title = 'API';
+    let version = '1.0.0';
+    const pkgPath = node_path_1.default.join(projectRoot, 'package.json');
+    if (node_fs_1.default.existsSync(pkgPath)) {
+        try {
+            const pkg = JSON.parse(node_fs_1.default.readFileSync(pkgPath, 'utf-8'));
+            if (nonEmptyString(pkg.name))
+                title = pkg.name;
+            if (nonEmptyString(pkg.version))
+                version = pkg.version;
+        }
+        catch {
+            // Malformed package.json — keep the generic fallbacks.
+        }
+    }
+    return { title, version };
+}
+async function loadConfig(options) {
+    const filePath = findConfigFile(options.projectRoot, options.configPath);
+    if (!filePath) {
+        // Auto-discovery found nothing (an explicit --config miss already threw):
+        // fall back to a default config so the doc can still be generated.
+        const { title, version } = resolveOpenApiDefaults(options.projectRoot);
+        console.warn(`[nestparser] No config file found in ${options.projectRoot}; ` +
+            `using defaults (title="${title}", version="${version}"). ` +
+            `Add one of ${CANDIDATE_NAMES.join(', ')} to customize.`);
+        return { config: { openapi: { title, version } }, filePath: undefined };
+    }
+    const raw = await importConfig(filePath);
+    if (!isConfigShape(raw)) {
+        throw new Error(`Config at ${filePath} does not export a valid NestParserConfig (missing 'openapi').`);
+    }
+    // Fill in `title`/`version` from package.json (or generic defaults) when the
+    // config omits either, rather than failing — same fallback as the no-config path.
+    const missing = [];
+    if (!nonEmptyString(raw.openapi.title))
+        missing.push('title');
+    if (!nonEmptyString(raw.openapi.version))
+        missing.push('version');
+    if (missing.length) {
+        const defaults = resolveOpenApiDefaults(options.projectRoot);
+        if (!nonEmptyString(raw.openapi.title))
+            raw.openapi.title = defaults.title;
+        if (!nonEmptyString(raw.openapi.version))
+            raw.openapi.version = defaults.version;
+        console.warn(`[nestparser] Config at ${filePath} is missing ${missing.map((m) => `openapi.${m}`).join(', ')}; ` +
+            `using defaults (title="${raw.openapi.title}", version="${raw.openapi.version}").`);
+    }
+    return { config: raw, filePath };
+}
+//# sourceMappingURL=loader.js.map

package/dist/config/loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.js","sourceRoot":"","sources":["../../src/config/loader.ts"],"names":[],"mappings":"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"}

package/dist/config/types.d.ts

@@ -0,0 +1,139 @@
+import type { ClassDeclaration, MethodDeclaration, Type } from 'ts-morph';
+import type { OpenApiInfo, OpenApiSchema, OpenApiSecurityRequirement, OpenApiSecurityScheme, OpenApiServer } from '../types/openapi';
+/**
+ * Context passed to the `buildResponseSchema` hook for a single controller method.
+ * The hook decides what the final response body schema looks like — including any
+ * project-specific envelope (e.g. `{ success, data }`) or pagination wrapping.
+ */
+export interface ResponseSchemaContext {
+    method: MethodDeclaration;
+    /** Method return type with `Promise<T>` already unwrapped to `T`. */
+    returnType: Type;
+    /** Symbol name of `returnType`, if any (e.g. `PaginatedResponse`, `User`, `Date`). */
+    returnTypeName: string | undefined;
+    /** Generic type arguments of `returnType` (e.g. `[User]` for `PaginatedResponse<User>`). */
+    returnTypeArgs: Type[];
+    /**
+     * Lazily compute the schema for the bare return type (no envelope/wrapper).
+     * Calling this registers a `$ref` to `components.schemas` if the return type
+     * is a class — only call when you actually need it.
+     */
+    defaultSchema: () => OpenApiSchema;
+    /** Convert any ts-morph `Type` to an OpenAPI schema fragment (registers refs). */
+    typeToSchema: (type: Type) => OpenApiSchema;
+}
+/**
+ * Context passed to the `resolveSecurity` hook for a single controller method.
+ * Return `undefined` to keep the default (apply every registered security scheme),
+ * `[]` to mark the endpoint public, or an explicit array of requirements.
+ */
+export interface SecurityContext {
+    controller: ClassDeclaration;
+    method: MethodDeclaration;
+    /** Names of all security schemes declared under `openapi.securitySchemes`. */
+    registeredSchemes: string[];
+}
+/**
+ * Context passed to the `endpointSummary` hook for a single controller method.
+ * Return a string to use as the operation `summary`, or `null`/`undefined` to
+ * fall back to `defaultSummary`. A method-level `@Name` JSDoc tag overrides both.
+ */
+export interface EndpointSummaryContext {
+    controller: ClassDeclaration;
+    method: MethodDeclaration;
+    /** Lowercase HTTP verb (`get`, `post`, `put`, `delete`, `patch`). */
+    httpMethod: string;
+    /** The default summary: the method name humanized (PascalCase split + capitalized). */
+    defaultSummary: string;
+}
+export interface NestParserHooks {
+    /**
+     * Decide the schema of the response body for an endpoint. If not provided, the
+     * response body is the method's return type schema directly (no envelope).
+     */
+    buildResponseSchema?: (ctx: ResponseSchemaContext) => OpenApiSchema;
+    /**
+     * Decide which security requirements apply to an endpoint. Default behavior:
+     * if any security schemes are registered, all of them apply (logical OR); else
+     * no security entries are emitted.
+     */
+    resolveSecurity?: (ctx: SecurityContext) => OpenApiSecurityRequirement[] | undefined;
+    /**
+     * Override the default tag derivation (strip `Controller` suffix from class name).
+     */
+    controllerTag?: (clazz: ClassDeclaration) => string;
+    /**
+     * Build the `summary` for an endpoint. Return `null`/`undefined` to fall back
+     * to the default (the method name humanized). A method-level `@Name` JSDoc tag
+     * overrides both this hook and the default.
+     */
+    endpointSummary?: (ctx: EndpointSummaryContext) => string | null | undefined;
+}
+export interface OpenApiConfig {
+    title: string;
+    version: string;
+    description?: string;
+    servers?: OpenApiServer[];
+    securitySchemes?: Record<string, OpenApiSecurityScheme>;
+    /** Document-level extras spliced onto `info`. */
+    info?: Partial<OpenApiInfo>;
+}
+export interface ProjectConfig {
+    /**
+     * Path to the project's tsconfig (relative to the project root or absolute).
+     * Defaults to `tsconfig.json`.
+     */
+    tsConfigFilePath?: string;
+    /**
+     * Directory containing the project's source files, relative to the project root.
+     * Defaults to `src`.
+     */
+    rootDir?: string;
+    /**
+     * Global route prefix mirroring `app.setGlobalPrefix(...)`. Prepended to every
+     * controller route. Defaults to empty (no prefix).
+     */
+    globalPrefix?: string;
+    /**
+     * Glob-ish suffixes to skip when scanning the source tree. Files matching any
+     * of these are not indexed. Defaults to `['.spec.ts', '.test.ts', '.d.ts']`.
+     */
+    excludeSuffixes?: string[];
+}
+export interface ConventionsConfig {
+    /** Decorator name marking a property as excluded from serialization. Defaults to `Exclude`. */
+    excludeDecorator?: string;
+    /** Decorator name marking a property as optional. Defaults to `IsOptional`. */
+    optionalDecorator?: string;
+}
+/**
+ * A class reference (concrete or abstract) — anything assignable to a class
+ * constructor. Looked up against the project's AST index by `klass.name`.
+ */
+export type ModelConstructor = abstract new (...args: any[]) => unknown;
+export interface NestParserConfig {
+    openapi: OpenApiConfig;
+    project?: ProjectConfig;
+    conventions?: ConventionsConfig;
+    hooks?: NestParserHooks;
+    /**
+     * Class references to force-include in `components.schemas`, even when no
+     * endpoint reaches them. Pass the class itself (not its name) — we resolve
+     * via `klass.name` against the project's AST index. Throws at build time if
+     * any name cannot be matched, to surface typos and out-of-tree classes early.
+     *
+     * Transitive references of each entry are also pulled in (same reachability
+     * walk as if an endpoint had returned the class).
+     */
+    additionalModels?: ModelConstructor[];
+    /**
+     * Active scopes for this build. Items annotated with `@Scope` are emitted
+     * only when their scope set intersects this list. Untagged items are always
+     * emitted. Empty/undefined means "only untagged items".
+     *
+     * The CLI flag `--scope a,b` overrides this when given.
+     */
+    scopes?: string[];
+}
+/** Helper for `nestparser.config.ts` so users get full type-checking. */
+export declare function defineConfig(config: NestParserConfig): NestParserConfig;