nestjs-openapi 0.1.4 → 0.2.1

package/dist/index.d.mts

@@ -1,696 +1,8 @@
-import { Effect, Context, Layer, Option } from 'effect';
-import { C as ConfigNotFoundError, O as OpenApiGeneratorConfig, a as ConfigError, R as ResolvedConfig, P as ProjectError, b as ProjectInitError, E as EntryNotFoundError, M as MethodInfo, c as OpenApiPaths$1 } from './shared/nestjs-openapi.ClTIhsb-.mjs';
-export { A as AnalysisError, i as ConfigLoadError, j as ConfigValidationError, G as GenerateOptions, k as GeneratorError, H as HttpMethod, I as InvalidMethodError, e as ParameterLocation, f as ResolvedParameter, h as ReturnTypeInfo, d as generateAsync, g as generateEffect } from './shared/nestjs-openapi.ClTIhsb-.mjs';
+import { O as OpenApiSpec, S as SpecFileNotFoundError, a as SpecFileReadError, b as SpecFileParseError, M as MethodInfo, c as OpenApiPaths, d as OpenApiOperation, e as OpenApiPaths$1, G as GeneratedSchemas, f as OpenApiSchema, C as ConfigService, P as ProjectService, g as ModuleTraversalService, h as MethodExtractionService, i as SchemaService, V as ValidationService, j as OutputService } from './shared/nestjs-openapi.C1csrdEX.mjs';
+export { a4 as AnalysisError, aJ as BrokenRef, aK as BrokenRefCategories, az as ClassValidationInfo, n as Config, a3 as ConfigError, X as ConfigLoadError, W as ConfigNotFoundError, Y as ConfigValidationError, o as ContactConfig, Z as DtoGlobResolutionError, U as EntryNotFoundError, E as GenerateOptions, s as GenerateOverrides, l as GenerateResult, a5 as GeneratorError, J as HttpMethod, I as InfoConfig, _ as InvalidMethodError, am as JsonSchema, L as LicenseConfig, $ as MissingGenericSchemaTempFileCleanupError, a0 as MissingGenericSchemaTempFileWriteError, ac as ModuleWithControllers, K as OpenApiGeneratorConfig, t as OpenApiOperation, u as OpenApiParameter, v as OpenApiRequestBody, w as OpenApiResponse, q as OutputFormat, F as ParameterLocation, a8 as ProjectContext, a2 as ProjectError, Q as ProjectInitError, a9 as ProjectOptions, a6 as ProjectServiceLive, ay as PropertyValidationInfo, a1 as PublicApiError, N as ResolvedConfig, R as ResolvedParameter, H as ReturnTypeInfo, ak as SchemaError, aj as SchemaGenerationError, al as SchemaGeneratorOptions, p as ServerConfig, T as TagConfig, r as TelemetryConfig, ax as ValidationConstraints, aI as ValidationResult, au as applyConstraintsToSchema, aG as categorizeBrokenRefs, m as defineConfig, as as extractClassConstraints, aq as extractClassValidationInfo, ar as extractClassValidationInfoEffect, an as extractPropertyConstraints, ap as extractPropertyValidationInfo, aA as findConfigFile, aH as formatValidationResult, k as generate, y as generateAsync, x as generateEffect, D as generateFromConfigAsync, B as generateFromConfigEffect, A as generatePathsAsync, z as generatePathsEffect, ah as generateSchemas, ai as generateSchemasFromFiles, ab as getAllControllers, af as getControllerMethodInfos, ag as getControllerMethodInfosEffect, ad as getMethodInfo, ae as getMethodInfoEffect, aa as getModules, at as getRequiredProperties, ao as isPropertyOptional, aE as loadAndResolveConfig, aC as loadConfig, aB as loadConfigFromFile, a7 as makeProjectContext, av as mergeValidationConstraints, aw as mergeValidationConstraintsEffect, aD as resolveConfig, aF as validateSpec } from './shared/nestjs-openapi.C1csrdEX.mjs';
 import { DynamicModule } from '@nestjs/common';
-import { Project, SourceFile, ClassDeclaration, MethodDeclaration, Decorator, Symbol, ObjectLiteralExpression, Expression } from 'ts-morph';
-
-/**
- * Public types for nestjs-openapi
- *
- * These types are exposed to consumers of the library. Internal types
- * should be kept in domain.ts.
- */
-/**
- * Contact information for the API
- */
-interface ContactConfig {
-    readonly name?: string;
-    readonly email?: string;
-    readonly url?: string;
-}
-/**
- * License information for the API
- */
-interface LicenseConfig {
-    readonly name: string;
-    readonly url?: string;
-}
-/**
- * API metadata for the OpenAPI info section
- */
-interface InfoConfig {
-    readonly title: string;
-    readonly version: string;
-    readonly description?: string;
-    readonly contact?: ContactConfig;
-    readonly license?: LicenseConfig;
-}
-/**
- * Server configuration for the OpenAPI servers section
- */
-interface ServerConfig {
-    readonly url: string;
-    readonly description?: string;
-}
-/**
- * Tag configuration for organizing API endpoints
- */
-interface TagConfig {
-    readonly name: string;
-    readonly description?: string;
-}
-/**
- * Security scheme type for OpenAPI 3.0
- */
-type SecuritySchemeType = 'apiKey' | 'http' | 'oauth2' | 'openIdConnect';
-/**
- * Location for apiKey security schemes
- */
-type SecuritySchemeIn = 'query' | 'header' | 'cookie';
-/**
- * OAuth2 flow configuration
- */
-interface OAuth2FlowConfig {
-    readonly authorizationUrl?: string;
-    readonly tokenUrl?: string;
-    readonly refreshUrl?: string;
-    readonly scopes?: Record<string, string>;
-}
-/**
- * OAuth2 flows configuration
- */
-interface OAuth2FlowsConfig {
-    readonly implicit?: OAuth2FlowConfig;
-    readonly password?: OAuth2FlowConfig;
-    readonly clientCredentials?: OAuth2FlowConfig;
-    readonly authorizationCode?: OAuth2FlowConfig;
-}
-/**
- * Security scheme configuration for OpenAPI 3.0
- *
- * @example
- * ```typescript
- * // Bearer token (JWT)
- * {
- *   name: 'bearerAuth',
- *   type: 'http',
- *   scheme: 'bearer',
- *   bearerFormat: 'JWT',
- * }
- *
- * // API Key in header
- * {
- *   name: 'apiKey',
- *   type: 'apiKey',
- *   in: 'header',
- *   parameterName: 'X-API-Key',
- * }
- *
- * // OAuth2
- * {
- *   name: 'oauth2',
- *   type: 'oauth2',
- *   flows: {
- *     authorizationCode: {
- *       authorizationUrl: 'https://example.com/oauth/authorize',
- *       tokenUrl: 'https://example.com/oauth/token',
- *       scopes: { 'read:users': 'Read user data' },
- *     },
- *   },
- * }
- * ```
- */
-interface SecuritySchemeConfig {
-    /** Unique name for this security scheme (used as key in securitySchemes) */
-    readonly name: string;
-    /** The type of the security scheme */
-    readonly type: SecuritySchemeType;
-    /** Description of the security scheme */
-    readonly description?: string;
-    /** The name of the HTTP Authorization scheme (for type: 'http') */
-    readonly scheme?: string;
-    /** A hint for the format of the token (for type: 'http' with scheme: 'bearer') */
-    readonly bearerFormat?: string;
-    /** The location of the API key (for type: 'apiKey') */
-    readonly in?: SecuritySchemeIn;
-    /** The name of the header, query, or cookie parameter (for type: 'apiKey') */
-    readonly parameterName?: string;
-    /** OAuth2 flows configuration (for type: 'oauth2') */
-    readonly flows?: OAuth2FlowsConfig;
-    /** OpenID Connect URL to discover OAuth2 config (for type: 'openIdConnect') */
-    readonly openIdConnectUrl?: string;
-}
-/**
- * Security requirement - maps security scheme names to required scopes
- *
- * @example
- * ```typescript
- * // Require bearerAuth with no specific scopes
- * { bearerAuth: [] }
- *
- * // Require oauth2 with specific scopes
- * { oauth2: ['read:users', 'write:users'] }
- * ```
- */
-type SecurityRequirement = Record<string, readonly string[]>;
-/**
- * Output format for the generated OpenAPI specification
- */
-type OutputFormat = 'json' | 'yaml';
-/**
- * OpenAPI specification version
- * - '3.0.3': OpenAPI 3.0.3 (default, widely supported)
- * - '3.1.0': OpenAPI 3.1.0 (full JSON Schema 2020-12 alignment, type arrays for nullable)
- * - '3.2.0': OpenAPI 3.2.0 (when released, will include webhooks and other new features)
- */
-type OpenApiVersion = '3.0.3' | '3.1.0' | '3.2.0';
-/**
- * Input file configuration for nestjs-openapi.
- * All paths are relative to the config file location.
- */
-interface FilesConfig {
-    /**
-     * Entry module file(s).
-     * @default "src/app.module.ts"
-     */
-    readonly entry?: string | readonly string[];
-    /**
-     * Path to tsconfig.json. Auto-detected if not specified.
-     */
-    readonly tsconfig?: string;
-    /**
-     * Glob pattern(s) for DTO files to generate schemas from.
-     * @example "src/**\/*.dto.ts"
-     */
-    readonly dtoGlob?: string | readonly string[];
-    /**
-     * Glob patterns to include.
-     */
-    readonly include?: readonly string[];
-    /**
-     * Glob patterns to exclude.
-     * @default ["**\/*.spec.ts", "**\/*.test.ts", "**\/node_modules/**"]
-     */
-    readonly exclude?: readonly string[];
-}
-/**
- * Security configuration for OpenAPI spec.
- */
-interface SecurityConfig {
-    /**
-     * Security schemes available for the API.
-     * Defines authentication methods (bearer, apiKey, oauth2, etc.)
-     */
-    readonly schemes?: readonly SecuritySchemeConfig[];
-    /**
-     * Global security requirements applied to all operations.
-     * Can be overridden at the operation level.
-     * Each object in the array represents an alternative (OR logic).
-     * Within each object, all schemes must be satisfied (AND logic).
-     *
-     * @example
-     * ```typescript
-     * // Require bearerAuth for all operations
-     * global: [{ bearerAuth: [] }]
-     *
-     * // Allow either bearerAuth OR apiKey
-     * global: [{ bearerAuth: [] }, { apiKey: [] }]
-     * ```
-     */
-    readonly global?: readonly SecurityRequirement[];
-}
-/**
- * OpenAPI specification metadata configuration.
- * Maps directly to the OpenAPI spec structure.
- */
-interface OpenApiConfig {
-    /**
-     * OpenAPI specification version.
-     * @default "3.0.3"
-     */
-    readonly version?: OpenApiVersion;
-    /**
-     * API metadata for the info section.
-     * @required
-     */
-    readonly info: InfoConfig;
-    /**
-     * Server URLs for the API.
-     */
-    readonly servers?: readonly ServerConfig[];
-    /**
-     * Tags for organizing API endpoints.
-     */
-    readonly tags?: readonly TagConfig[];
-    /**
-     * Security configuration.
-     */
-    readonly security?: SecurityConfig;
-}
-/**
- * Generation behavior options.
- */
-interface OptionsConfig {
-    /**
-     * Base path prefix for all routes.
-     * Equivalent to NestJS's app.setGlobalPrefix().
-     * @example "/api/v1"
-     */
-    readonly basePath?: string;
-    /**
-     * Extract validation constraints from class-validator decorators.
-     * @default true
-     */
-    readonly extractValidation?: boolean;
-    /**
-     * Decorator names that exclude endpoints from the spec.
-     * @default ["ApiExcludeEndpoint", "ApiExcludeController"]
-     */
-    readonly excludeDecorators?: readonly string[];
-    /**
-     * Filter paths by regex or predicate function.
-     * Paths matching the regex (or returning true) are INCLUDED.
-     *
-     * @example
-     * ```typescript
-     * // Exclude internal and versioned paths
-     * pathFilter: /^(?!.*(\/internal\/|\/v[\d.]+\/)).* /
-     *
-     * // Using a function
-     * pathFilter: (path) => !path.includes('/internal/')
-     * ```
-     */
-    readonly pathFilter?: RegExp | ((path: string) => boolean);
-    /**
-     * Query parameter handling options.
-     */
-    readonly query?: QueryOptions;
-    /**
-     * Schema generation and normalization options.
-     */
-    readonly schemas?: SchemaOptions;
-}
-/**
- * Schema generation and normalization options.
- */
-interface SchemaOptions {
-    /**
-     * How to handle schema aliases that only redirect via `$ref`.
-     * - `"collapse"`: Rewrite refs to the final target schema and remove alias entries
-     * - `"preserve"`: Keep alias schemas as-is
-     *
-     * @default "collapse"
-     */
-    readonly aliasRefs?: 'collapse' | 'preserve';
-}
-/**
- * Query parameter handling options.
- */
-interface QueryOptions {
-    /**
-     * How to represent query object DTOs (e.g., `@Query() dto: PaginationDto`).
-     * - `"inline"` (default): Expand DTO properties as individual query parameters
-     * - `"ref"`: Keep as a single parameter with a schema reference
-     *
-     * @default "inline"
-     *
-     * @example
-     * ```typescript
-     * // With style: "inline" (default)
-     * // @Query() dto: PaginationDto becomes:
-     * // - page: integer (query)
-     * // - limit: integer (query)
-     *
-     * // With style: "ref"
-     * // @Query() dto: PaginationDto becomes:
-     * // - dto: $ref to PaginationDto schema (query)
-     * ```
-     */
-    readonly style?: 'inline' | 'ref';
-}
-/**
- * Configuration for nestjs-openapi.
- * Inspired by tsconfig.json and vite.config.ts patterns.
- *
- * @example
- * ```typescript
- * import { defineConfig } from 'nestjs-openapi';
- *
- * export default defineConfig({
- *   output: 'src/openapi/openapi.generated.json',
- *
- *   files: {
- *     entry: 'src/app.module.ts',
- *     dtoGlob: 'src/**\/*.dto.ts',
- *   },
- *
- *   openapi: {
- *     info: {
- *       title: 'My API',
- *       version: '1.0.0',
- *     },
- *   },
- *
- *   options: {
- *     basePath: '/api',
- *     extractValidation: true,
- *   },
- * });
- * ```
- */
-interface Config {
-    /**
-     * Extend another config file. Paths are relative to this config file.
-     * Extended config values are deeply merged, with this config taking precedence.
-     * @example extends: './configs/base-openapi.config.ts'
-     */
-    readonly extends?: string;
-    /**
-     * Input file configuration.
-     * All paths are relative to the config file location.
-     */
-    readonly files?: FilesConfig;
-    /**
-     * Output path for the generated OpenAPI specification.
-     * Path is relative to the config file location.
-     * @required
-     */
-    readonly output: string;
-    /**
-     * Output format for the specification.
-     * @default "json"
-     */
-    readonly format?: OutputFormat;
-    /**
-     * OpenAPI specification metadata.
-     * Maps directly to the OpenAPI spec structure.
-     * @required
-     */
-    readonly openapi: OpenApiConfig;
-    /**
-     * Generation behavior options.
-     */
-    readonly options?: OptionsConfig;
-}
-/**
- * Options for the generate function to override config values.
- * Useful for CLI overrides.
- */
-interface GenerateOverrides {
-    /**
-     * Override the output format.
-     * Takes precedence over config.format.
-     */
-    readonly format?: OutputFormat;
-    /**
-     * Enable debug mode for verbose logging and full stack traces.
-     */
-    readonly debug?: boolean;
-}
-/**
- * OpenAPI 3.0/3.1/3.2 specification schema object
- * Type can be a string or array of strings (for nullable in 3.1+)
- */
-interface OpenApiSchema {
-    /** Schema type - string or array for 3.1+ nullable (e.g., ['string', 'null']) */
-    readonly type?: string | readonly string[];
-    readonly format?: string;
-    readonly $ref?: string;
-    readonly oneOf?: readonly OpenApiSchema[];
-    readonly anyOf?: readonly OpenApiSchema[];
-    readonly allOf?: readonly OpenApiSchema[];
-    readonly items?: OpenApiSchema;
-    readonly properties?: Record<string, OpenApiSchema>;
-    readonly required?: readonly string[];
-    readonly enum?: readonly unknown[];
-    readonly description?: string;
-    /** OpenAPI 3.0 only - use type: [T, 'null'] in 3.1+ instead */
-    readonly nullable?: boolean;
-    /** Examples array for 3.1+ (replaces single 'example' field) */
-    readonly examples?: readonly unknown[];
-    readonly minLength?: number;
-    readonly maxLength?: number;
-    readonly pattern?: string;
-    readonly minimum?: number;
-    readonly maximum?: number;
-    readonly exclusiveMinimum?: number;
-    readonly exclusiveMaximum?: number;
-    readonly minItems?: number;
-    readonly maxItems?: number;
-    readonly default?: unknown;
-    readonly additionalProperties?: boolean | OpenApiSchema;
-}
-/**
- * OpenAPI 3.0 parameter object
- */
-interface OpenApiParameter {
-    readonly name: string;
-    readonly in: 'path' | 'query' | 'header' | 'cookie';
-    readonly description?: string;
-    readonly required: boolean;
-    readonly schema: OpenApiSchema;
-}
-/**
- * OpenAPI 3.0 request body object
- */
-interface OpenApiRequestBody {
-    readonly description?: string;
-    readonly required?: boolean;
-    readonly content: Record<string, {
-        readonly schema: OpenApiSchema;
-    }>;
-}
-/**
- * OpenAPI 3.0 response object
- */
-interface OpenApiResponse {
-    readonly description: string;
-    readonly content?: Record<string, {
-        readonly schema: OpenApiSchema;
-    }>;
-}
-/**
- * OpenAPI 3.0 operation object
- */
-interface OpenApiOperation {
-    readonly operationId: string;
-    readonly summary?: string;
-    readonly description?: string;
-    readonly deprecated?: boolean;
-    readonly tags?: readonly string[];
-    readonly parameters?: readonly OpenApiParameter[];
-    readonly requestBody?: OpenApiRequestBody;
-    readonly responses: Record<string, OpenApiResponse>;
-    /** Per-operation security requirements (overrides global security) */
-    readonly security?: readonly SecurityRequirement[];
-}
-/**
- * OpenAPI 3.0 paths object
- * Maps path patterns to HTTP method operations
- */
-interface OpenApiPaths {
-    readonly [path: string]: {
-        readonly [method: string]: OpenApiOperation;
-    };
-}
-/**
- * OpenAPI 3.0 OAuth2 flow object
- */
-interface OpenApiOAuth2Flow {
-    readonly authorizationUrl?: string;
-    readonly tokenUrl?: string;
-    readonly refreshUrl?: string;
-    readonly scopes: Record<string, string>;
-}
-/**
- * OpenAPI 3.0 OAuth2 flows object
- */
-interface OpenApiOAuth2Flows {
-    readonly implicit?: OpenApiOAuth2Flow;
-    readonly password?: OpenApiOAuth2Flow;
-    readonly clientCredentials?: OpenApiOAuth2Flow;
-    readonly authorizationCode?: OpenApiOAuth2Flow;
-}
-/**
- * OpenAPI 3.0 security scheme object
- */
-interface OpenApiSecurityScheme {
-    readonly type: SecuritySchemeType;
-    readonly description?: string;
-    /** The name of the HTTP Authorization scheme (for type: 'http') */
-    readonly scheme?: string;
-    /** A hint for the format of the token (for type: 'http' with scheme: 'bearer') */
-    readonly bearerFormat?: string;
-    /** The location of the API key (for type: 'apiKey') */
-    readonly in?: SecuritySchemeIn;
-    /** The name of the header, query, or cookie parameter (for type: 'apiKey') */
-    readonly name?: string;
-    /** OAuth2 flows (for type: 'oauth2') */
-    readonly flows?: OpenApiOAuth2Flows;
-    /** OpenID Connect URL (for type: 'openIdConnect') */
-    readonly openIdConnectUrl?: string;
-}
-/**
- * Webhook operation for OpenAPI 3.1+
- * Similar to regular operations but accessed via events rather than HTTP methods
- */
-interface OpenApiWebhookOperation {
-    readonly post?: OpenApiOperation;
-    readonly put?: OpenApiOperation;
-    readonly patch?: OpenApiOperation;
-    readonly delete?: OpenApiOperation;
-    readonly get?: OpenApiOperation;
-}
-/**
- * Complete OpenAPI 3.0/3.1/3.2 specification
- */
-interface OpenApiSpec {
-    readonly openapi: OpenApiVersion;
-    readonly info: {
-        readonly title: string;
-        readonly version: string;
-        readonly description?: string;
-        readonly contact?: ContactConfig;
-        readonly license?: LicenseConfig;
-    };
-    readonly servers?: readonly ServerConfig[];
-    readonly tags?: readonly TagConfig[];
-    readonly paths: OpenApiPaths;
-    /** Webhooks for OpenAPI 3.1+ - event-driven operations */
-    readonly webhooks?: Record<string, OpenApiWebhookOperation>;
-    readonly components?: {
-        readonly schemas?: Record<string, OpenApiSchema>;
-        readonly securitySchemes?: Record<string, OpenApiSecurityScheme>;
-    };
-    /** Global security requirements */
-    readonly security?: readonly SecurityRequirement[];
-}
-
-/**
- * OpenAPI spec validation utilities.
- *
- * Validates that generated specs don't have broken $ref references
- * or other common issues.
- */
-
-/**
- * A broken reference found during validation
- */
-interface BrokenRef {
-    /** The $ref value that couldn't be resolved */
-    readonly ref: string;
-    /** The JSON path where this reference was found */
-    readonly path: string;
-    /** The schema name that's missing (extracted from $ref) */
-    readonly missingSchema: string;
-}
-/**
- * Result of spec validation
- */
-interface ValidationResult {
-    /** Whether the spec is valid (no broken refs) */
-    readonly valid: boolean;
-    /** Total number of schema refs found */
-    readonly totalRefs: number;
-    /** Number of broken refs */
-    readonly brokenRefCount: number;
-    /** Details of each broken ref */
-    readonly brokenRefs: readonly BrokenRef[];
-    /** Missing schema names grouped with their usage count */
-    readonly missingSchemas: ReadonlyMap<string, number>;
-}
-/**
- * Validates an OpenAPI spec for broken $ref references.
- *
- * @param spec - The OpenAPI specification to validate
- * @returns Validation result with details about any broken refs
- *
- * @example
- * ```typescript
- * const result = validateSpec(spec);
- * if (!result.valid) {
- *   console.error(`Found ${result.brokenRefCount} broken refs:`);
- *   for (const [schema, count] of result.missingSchemas) {
- *     console.error(`  - ${schema} (${count} usages)`);
- *   }
- * }
- * ```
- */
-declare function validateSpec(spec: OpenApiSpec): ValidationResult;
-/**
- * Categorizes broken refs by likely cause
- */
-interface BrokenRefCategories {
-    /** Primitive types that shouldn't be refs (string, number, boolean) */
-    readonly primitives: readonly string[];
-    /** Union types (Type | null, void | Type) */
-    readonly unionTypes: readonly string[];
-    /** Query/Path parameter DTOs */
-    readonly queryParams: readonly string[];
-    /** Other missing schemas (likely from different glob patterns) */
-    readonly other: readonly string[];
-}
-/**
- * Categorize broken refs to help diagnose the root cause.
- *
- * @param missingSchemas - Map of missing schema names to usage count
- * @returns Categorized broken refs
- */
-declare function categorizeBrokenRefs(missingSchemas: ReadonlyMap<string, number>): BrokenRefCategories;
-/**
- * Formats validation result as a human-readable string for CLI output.
- *
- * @param result - Validation result from validateSpec
- * @returns Formatted string describing the validation issues
- */
-declare function formatValidationResult(result: ValidationResult): string;
-
-/**
- * Promise-based entry point for generating OpenAPI specifications.
- *
- * This module provides a clean, Promise-based API that hides the internal
- * Effect-TS implementation from consumers.
- */
-
-interface GenerateResult {
-    /** Path where the OpenAPI spec was written */
-    readonly outputPath: string;
-    /** Number of paths in the generated spec */
-    readonly pathCount: number;
-    /** Number of operations in the generated spec */
-    readonly operationCount: number;
-    /** Number of schemas in the generated spec */
-    readonly schemaCount: number;
-    /** Validation result checking for broken refs */
-    readonly validation: ValidationResult;
-}
-/**
- * Generates an OpenAPI specification from a NestJS application.
- *
- * @param configPath - Path to the configuration file (openapi.config.ts)
- * @param options - Optional overrides for config values (e.g., format)
- * @returns Promise that resolves with generation result when complete
- *
- * @example
- * ```typescript
- * import { generate } from 'nestjs-openapi';
- *
- * await generate('apps/backend-api/openapi.config.ts');
- *
- * // Override format from CLI
- * await generate('apps/backend-api/openapi.config.ts', { format: 'yaml' });
- * ```
- */
-declare const generate: (configPath: string, overrides?: GenerateOverrides) => Promise<GenerateResult>;
-
-/**
- * Define configuration for OpenAPI generation.
- *
- * @example
- * ```typescript
- * export default defineConfig({
- *   output: 'openapi.json',
- *   files: { entry: 'src/app.module.ts' },
- *   openapi: { info: { title: 'My API', version: '1.0.0' } },
- * });
- * ```
- */
-declare function defineConfig(config: Config): Config;
-declare const findConfigFile: (startDir?: string) => Effect.Effect<string, ConfigNotFoundError>;
-declare const loadConfigFromFile: (configPath: string) => Effect.Effect<typeof OpenApiGeneratorConfig.Type, ConfigError>;
-declare const loadConfig: (configPath?: string, cwd?: string) => Effect.Effect<typeof OpenApiGeneratorConfig.Type, ConfigError>;
-declare const resolveConfig: (config: typeof OpenApiGeneratorConfig.Type) => typeof ResolvedConfig.Type;
-declare const loadAndResolveConfig: (configPath?: string, cwd?: string) => Effect.Effect<typeof ResolvedConfig.Type, ConfigError>;
+import { Effect, Option, Layer } from 'effect';
+import { ClassDeclaration, MethodDeclaration, Decorator, Symbol, ObjectLiteralExpression, Expression } from 'ts-morph';
 
 /**
  * NestJS Module for serving generated OpenAPI specifications at runtime.
@@ -783,6 +95,7 @@ declare function generateSwaggerUiHtml(title: string, jsonPath: string): string;
 /**
  * Load the OpenAPI spec file from disk
  */
+declare const loadSpecFileEffect: (filePath: string) => Effect.Effect<OpenApiSpec, SpecFileNotFoundError | SpecFileReadError | SpecFileParseError, never>;
 declare function loadSpecFile(filePath: string): OpenApiSpec;
 /**
  * Resolve options with defaults
@@ -832,39 +145,6 @@ declare class OpenApiModule {
     static forRoot(options: OpenApiModuleOptions): DynamicModule;
 }
 
-interface ProjectContext {
-    readonly project: Project;
-    readonly entrySourceFile: SourceFile;
-    readonly entryClass: ClassDeclaration;
-}
-interface ProjectOptions {
-    readonly tsconfig: string;
-    readonly entry: string;
-}
-declare const ProjectService_base: Context.TagClass<ProjectService, "ProjectService", {
-    readonly context: ProjectContext;
-}>;
-/**
- * ProjectService is an infrastructure context holder.
- * Context.Tag is appropriate here as it holds externally-provided resources.
- */
-declare class ProjectService extends ProjectService_base {
-}
-declare const makeProjectContext: (options: ProjectOptions) => Effect.Effect<{
-    project: Project;
-    entrySourceFile: SourceFile;
-    entryClass: ClassDeclaration;
-}, ProjectInitError | EntryNotFoundError, never>;
-declare const ProjectServiceLive: (options: ProjectOptions) => Layer.Layer<ProjectService, ProjectError>;
-
-interface ModuleWithControllers {
-    readonly declaration: ClassDeclaration;
-    readonly controllers: readonly ClassDeclaration[];
-}
-/** Iterative BFS to avoid stack overflow on deep module graphs */
-declare const getModules: (root: ClassDeclaration) => Effect.Effect<readonly ModuleWithControllers[], never, never>;
-declare const getAllControllers: (root: ClassDeclaration) => Effect.Effect<ClassDeclaration[], never, never>;
-
 declare const normalizePath: (path: string) => string;
 declare const getControllerPrefix: (controller: ClassDeclaration) => string;
 declare const getControllerName: (controller: ClassDeclaration) => string;
@@ -877,20 +157,159 @@ declare const getControllerTags: (controller: ClassDeclaration) => readonly stri
 declare const isHttpDecorator: (decorator: Decorator) => boolean;
 declare const getHttpDecorator: (method: MethodDeclaration) => Decorator | undefined;
 
-/** Configuration options for parameter extraction */
-interface ExtractParametersOptions {
-    /** Query parameter handling options */
-    readonly query?: {
-        /** How to represent query DTOs: "inline" (default) or "ref" */
-        readonly style?: 'inline' | 'ref';
+declare const transformMethod: (methodInfo: MethodInfo) => OpenApiPaths;
+declare const transformMethodEffect: (methodInfo: {
+    readonly security: readonly {
+        readonly scopes: readonly string[];
+        readonly schemeName: string;
+    }[];
+    readonly httpMethod: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS" | "HEAD" | "ALL";
+    readonly path: string;
+    readonly methodName: string;
+    readonly controllerName: string;
+    readonly controllerTags: readonly string[];
+    readonly returnType: {
+        readonly type: Option.Option<string>;
+        readonly inline: Option.Option<string>;
+        readonly container: Option.Option<"array">;
+        readonly filePath: Option.Option<string>;
+    };
+    readonly parameters: readonly {
+        readonly name: string;
+        readonly description: Option.Option<string>;
+        readonly location: "query" | "header" | "cookie" | "path" | "body";
+        readonly tsType: string;
+        readonly required: boolean;
+    }[];
+    readonly decorators: readonly string[];
+    readonly operation: {
+        readonly description: Option.Option<string>;
+        readonly summary: Option.Option<string>;
+        readonly operationId: Option.Option<string>;
+        readonly deprecated: Option.Option<boolean>;
+    };
+    readonly responses: readonly {
+        readonly description: Option.Option<string>;
+        readonly type: Option.Option<string>;
+        readonly statusCode: number;
+        readonly isArray: boolean;
+    }[];
+    readonly httpCode: Option.Option<number>;
+    readonly consumes: readonly string[];
+    readonly produces: readonly string[];
+}) => Effect.Effect<OpenApiPaths, never, never>;
+type MutableOpenApiPaths = {
+    [path: string]: {
+        [method: string]: OpenApiOperation;
+    };
+};
+declare const transformMethods: (methodInfos: readonly MethodInfo[]) => OpenApiPaths;
+declare const transformMethodsEffect: (methodInfos: readonly {
+    readonly security: readonly {
+        readonly scopes: readonly string[];
+        readonly schemeName: string;
+    }[];
+    readonly httpMethod: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS" | "HEAD" | "ALL";
+    readonly path: string;
+    readonly methodName: string;
+    readonly controllerName: string;
+    readonly controllerTags: readonly string[];
+    readonly returnType: {
+        readonly type: Option.Option<string>;
+        readonly inline: Option.Option<string>;
+        readonly container: Option.Option<"array">;
+        readonly filePath: Option.Option<string>;
+    };
+    readonly parameters: readonly {
+        readonly name: string;
+        readonly description: Option.Option<string>;
+        readonly location: "query" | "header" | "cookie" | "path" | "body";
+        readonly tsType: string;
+        readonly required: boolean;
+    }[];
+    readonly decorators: readonly string[];
+    readonly operation: {
+        readonly description: Option.Option<string>;
+        readonly summary: Option.Option<string>;
+        readonly operationId: Option.Option<string>;
+        readonly deprecated: Option.Option<boolean>;
     };
+    readonly responses: readonly {
+        readonly description: Option.Option<string>;
+        readonly type: Option.Option<string>;
+        readonly statusCode: number;
+        readonly isArray: boolean;
+    }[];
+    readonly httpCode: Option.Option<number>;
+    readonly consumes: readonly string[];
+    readonly produces: readonly string[];
+}[]) => Effect.Effect<MutableOpenApiPaths, never, never>;
+
+/**
+ * Schema Merger - Combines DTO schemas with path-referenced schemas
+ *
+ * This module merges generated DTO schemas into the final OpenAPI specification,
+ * ensuring all referenced schemas are included in components/schemas.
+ */
+
+/**
+ * Result of schema merging
+ */
+interface MergedResult {
+    /** The paths with updated $ref values */
+    readonly paths: OpenApiPaths$1;
+    /** All schemas to include in components/schemas */
+    readonly schemas: Record<string, OpenApiSchema>;
+}
+declare const mergeSchemas: (paths: OpenApiPaths$1, generatedSchemas: GeneratedSchemas) => MergedResult;
+declare const mergeSchemasEffect: (paths: OpenApiPaths$1, generatedSchemas: GeneratedSchemas) => Effect.Effect<MergedResult, never, never>;
+declare const mergeGeneratedSchemas: (...schemas: GeneratedSchemas[]) => GeneratedSchemas;
+declare const mergeGeneratedSchemasEffect: (...args: GeneratedSchemas[]) => Effect.Effect<GeneratedSchemas, never, never>;
+declare const filterSchemas: (schemas: GeneratedSchemas, include?: readonly string[], exclude?: readonly string[]) => GeneratedSchemas;
+declare const filterSchemasEffect: (schemas: GeneratedSchemas, include?: readonly string[] | undefined, exclude?: readonly string[] | undefined) => Effect.Effect<GeneratedSchemas, never, never>;
+
+/**
+ * Schema Name Normalizer
+ *
+ * Transforms ugly generic type names into clean, readable names.
+ * For example: `SelectRule<structure-1949804971-...>` → `SelectRule`
+ */
+
+interface NormalizerOptions {
+    /**
+     * Whether to preserve the base name when stripping generics
+     * @default true
+     */
+    readonly preserveBaseName?: boolean;
+    /**
+     * Whether to deduplicate names with numeric suffixes
+     * @default false
+     */
+    readonly deduplicateSuffixes?: boolean;
+    /**
+     * Custom name mapping for specific types
+     */
+    readonly customNames?: Record<string, string>;
 }
-/** Returns None if the method has no HTTP decorator */
-declare const getMethodInfo: (controller: ClassDeclaration, method: MethodDeclaration, options?: ExtractParametersOptions) => Option.Option<MethodInfo>;
-declare const getControllerMethodInfos: (controller: ClassDeclaration, options?: ExtractParametersOptions) => readonly MethodInfo[];
+declare const normalizeSchemas: (schemas: GeneratedSchemas, options?: NormalizerOptions) => GeneratedSchemas;
+declare const normalizeSchemasEffect: (schemas: GeneratedSchemas, options?: NormalizerOptions | undefined) => Effect.Effect<GeneratedSchemas, never, never>;
+declare const filterInternalSchemas: (schemas: GeneratedSchemas) => GeneratedSchemas;
+declare const filterInternalSchemasEffect: (schemas: GeneratedSchemas) => Effect.Effect<GeneratedSchemas, never, never>;
+/**
+ * Convert a string to PascalCase
+ * Examples:
+ * - `namespaceLabels` → `NamespaceLabels`
+ * - `k8sLabels` → `K8sLabels`
+ * - `NamespaceLabels` → `NamespaceLabels` (unchanged)
+ */
+declare const toPascalCase: (str: string) => string;
+declare const normalizeStructureRefs: (schemas: GeneratedSchemas) => GeneratedSchemas;
+declare const normalizeStructureRefsEffect: (schemas: GeneratedSchemas) => Effect.Effect<GeneratedSchemas, never, never>;
 
-declare const transformMethod: (methodInfo: MethodInfo) => OpenApiPaths$1;
-declare const transformMethods: (methodInfos: readonly MethodInfo[]) => OpenApiPaths$1;
+/**
+ * Shared service dependency graph for generation pipelines.
+ */
+declare const generatorServicesLayer: Layer.Layer<ConfigService | ProjectService | ModuleTraversalService | MethodExtractionService | SchemaService | ValidationService | OutputService, never, never>;
 
 /** Handles aliased symbols (re-exports) */
 declare const resolveClassFromSymbol: (sym: Symbol) => Option.Option<ClassDeclaration>;
@@ -909,5 +328,5 @@ interface ModuleMetadata {
 }
 declare const getModuleMetadata: (mod: ClassDeclaration) => ModuleMetadata;
 
-export { ConfigError, ConfigNotFoundError, EntryNotFoundError, MethodInfo, OPENAPI_MODULE_OPTIONS, OPENAPI_SPEC, OpenApiGeneratorConfig, OpenApiModule, ProjectError, ProjectInitError, ProjectService, ProjectServiceLive, ResolvedConfig, categorizeBrokenRefs, defineConfig, findConfigFile, formatValidationResult, generate, generateSwaggerUiHtml, getAllControllers, getArrayInitializer, getControllerMethodInfos, getControllerName, getControllerPrefix, getControllerTags, getDecoratorName, getHttpDecorator, getHttpMethods, getMethodInfo, getModuleDecoratorArg, getModuleMetadata, getModules, getStringLiteralValue, getSymbolFromIdentifier, isHttpDecorator, isHttpMethod, isModuleClass, loadAndResolveConfig, loadConfig, loadConfigFromFile, loadSpecFile, makeProjectContext, normalizePath, resolveArrayOfClasses, resolveClassFromExpression, resolveClassFromSymbol, resolveConfig, resolveOptions, transformMethod, transformMethods, validateSpec };
-export type { BrokenRef, BrokenRefCategories, Config, ContactConfig, GenerateOverrides, GenerateResult, InfoConfig, LicenseConfig, ModuleMetadata, ModuleWithControllers, OpenApiModuleOptions, OpenApiOperation, OpenApiParameter, OpenApiPaths, OpenApiRequestBody, OpenApiResponse, OpenApiSchema, OpenApiSpec, OutputFormat, ProjectContext, ProjectOptions, ResolvedOpenApiModuleOptions, ServerConfig, SwaggerOptions, TagConfig, ValidationResult };
+export { ConfigService, GeneratedSchemas, MethodExtractionService, MethodInfo, ModuleTraversalService, OPENAPI_MODULE_OPTIONS, OPENAPI_SPEC, OpenApiModule, OpenApiPaths$1 as OpenApiPaths, OpenApiSchema, OpenApiSpec, OutputService, ProjectService, SchemaService, SpecFileNotFoundError, SpecFileParseError, SpecFileReadError, ValidationService, filterInternalSchemas, filterInternalSchemasEffect, filterSchemas, filterSchemasEffect, generateSwaggerUiHtml, generatorServicesLayer, getArrayInitializer, getControllerName, getControllerPrefix, getControllerTags, getDecoratorName, getHttpDecorator, getHttpMethods, getModuleDecoratorArg, getModuleMetadata, getStringLiteralValue, getSymbolFromIdentifier, isHttpDecorator, isHttpMethod, isModuleClass, loadSpecFile, loadSpecFileEffect, mergeGeneratedSchemas, mergeGeneratedSchemasEffect, mergeSchemas, mergeSchemasEffect, normalizePath, normalizeSchemas, normalizeSchemasEffect, normalizeStructureRefs, normalizeStructureRefsEffect, resolveArrayOfClasses, resolveClassFromExpression, resolveClassFromSymbol, resolveOptions, toPascalCase, transformMethod, transformMethodEffect, transformMethods, transformMethodsEffect };
+export type { MergedResult, ModuleMetadata, NormalizerOptions, OpenApiModuleOptions, ResolvedOpenApiModuleOptions, SwaggerOptions };