nestjs-openapi 0.1.0

package/dist/shared/nestjs-openapi.DlNMM8Zq.mjs

@@ -0,0 +1,1831 @@
+import { Schema, Effect, Logger, Layer, LogLevel } from 'effect';
+import { readFileSync, writeFileSync, existsSync, unlinkSync, mkdirSync } from 'node:fs';
+import { join, dirname, resolve } from 'node:path';
+import { Project } from 'ts-morph';
+import { globSync, glob } from 'glob';
+import yaml from 'js-yaml';
+import { C as ConfigNotFoundError, a as ConfigLoadError, b as ConfigValidationError, p as transformMethods, A as extractClassConstraints, B as getRequiredProperties, D as mergeValidationConstraints, E as EntryNotFoundError, g as getModules, o as getControllerMethodInfos } from './nestjs-openapi.B1bBy_tG.mjs';
+import { createGenerator } from 'ts-json-schema-generator';
+import { randomUUID } from 'node:crypto';
+import { pathToFileURL } from 'node:url';
+import { execSync } from 'child_process';
+
+const buildFlow = (flow, includeAuthUrl, includeTokenUrl) => ({
+  ...includeAuthUrl && flow.authorizationUrl && { authorizationUrl: flow.authorizationUrl },
+  ...includeTokenUrl && flow.tokenUrl && { tokenUrl: flow.tokenUrl },
+  ...flow.refreshUrl && { refreshUrl: flow.refreshUrl },
+  scopes: flow.scopes ?? {}
+});
+const buildOAuth2Flows = (flows) => ({
+  ...flows.implicit && { implicit: buildFlow(flows.implicit, true, false) },
+  ...flows.password && { password: buildFlow(flows.password, false, true) },
+  ...flows.clientCredentials && {
+    clientCredentials: buildFlow(flows.clientCredentials, false, true)
+  },
+  ...flows.authorizationCode && {
+    authorizationCode: buildFlow(flows.authorizationCode, true, true)
+  }
+});
+const transformSecurityScheme = (config) => {
+  const scheme = {
+    type: config.type,
+    ...config.description && { description: config.description }
+  };
+  switch (config.type) {
+    case "http":
+      return {
+        ...scheme,
+        ...config.scheme && { scheme: config.scheme },
+        ...config.bearerFormat && { bearerFormat: config.bearerFormat }
+      };
+    case "apiKey":
+      return {
+        ...scheme,
+        ...config.in && { in: config.in },
+        ...config.parameterName && { name: config.parameterName }
+      };
+    case "oauth2":
+      if (!config.flows) return scheme;
+      return { ...scheme, flows: buildOAuth2Flows(config.flows) };
+    case "openIdConnect":
+      return {
+        ...scheme,
+        ...config.openIdConnectUrl && {
+          openIdConnectUrl: config.openIdConnectUrl
+        }
+      };
+    default:
+      return scheme;
+  }
+};
+const buildSecuritySchemes = (configs) => {
+  const schemes = {};
+  for (const config of configs) {
+    schemes[config.name] = transformSecurityScheme(config);
+  }
+  return schemes;
+};
+
+class SchemaGenerationError extends Schema.TaggedError()(
+  "SchemaGenerationError",
+  {
+    message: Schema.String,
+    cause: Schema.optional(Schema.Unknown)
+  }
+) {
+  static fromError(error, context) {
+    const baseMessage = error instanceof Error ? error.message : "Unknown schema generation error";
+    const message = context ? `${baseMessage} (${context})` : baseMessage;
+    return new SchemaGenerationError({
+      message,
+      cause: error
+    });
+  }
+  static noFilesFound(patterns) {
+    return new SchemaGenerationError({
+      message: `No DTO files found matching patterns: ${patterns.join(", ")}`
+    });
+  }
+}
+const generateSchemas = Effect.fn("SchemaGenerator.generate")(function* (options) {
+  yield* Effect.logDebug("Starting schema generation").pipe(
+    Effect.annotateLogs({
+      dtoGlob: options.dtoGlob.join(", "),
+      tsconfig: options.tsconfig
+    })
+  );
+  const patterns = options.dtoGlob.map((pattern) => ({
+    pattern,
+    combinable: !pattern.startsWith("/") && !pattern.includes("..")
+  }));
+  const combinable = patterns.filter((p) => p.combinable);
+  const nonCombinable = patterns.filter((p) => !p.combinable);
+  const groupedPatterns = [];
+  if (combinable.length > 0) {
+    groupedPatterns.push(
+      combinable.length === 1 ? combinable[0].pattern : `{${combinable.map((p) => p.pattern).join(",")}}`
+    );
+  }
+  groupedPatterns.push(...nonCombinable.map((p) => p.pattern));
+  const schemaResults = yield* Effect.all(
+    groupedPatterns.map(
+      (pattern) => generateSchemasFromGlob(pattern, options.tsconfig, options.basePath)
+    ),
+    { concurrency: "unbounded" }
+  );
+  const allDefinitions = schemaResults.reduce(
+    (acc, schemas) => ({ ...acc, ...schemas.definitions }),
+    {}
+  );
+  yield* Effect.logDebug("Schema generation complete").pipe(
+    Effect.annotateLogs({
+      definitionCount: Object.keys(allDefinitions).length
+    })
+  );
+  return { definitions: allDefinitions };
+});
+const generateSchemasFromGlob = Effect.fn("SchemaGenerator.generateFromGlob")(
+  function* (pattern, tsconfig, basePath) {
+    const isBraceAbsolute = pattern.startsWith("{") && pattern.slice(1, -1).split(",").map((entry) => entry.trim()).every((entry) => entry.startsWith("/"));
+    const absolutePattern = pattern.startsWith("/") || isBraceAbsolute ? pattern : join(basePath, pattern);
+    yield* Effect.annotateCurrentSpan("pattern", absolutePattern);
+    const matchedFiles = globSync(absolutePattern);
+    if (matchedFiles.length === 0) {
+      yield* Effect.logDebug("No files matched pattern, skipping").pipe(
+        Effect.annotateLogs({ pattern: absolutePattern })
+      );
+      return { definitions: {} };
+    }
+    return yield* Effect.try({
+      try: () => {
+        const config = {
+          path: absolutePattern,
+          tsconfig,
+          type: "*",
+          // Generate schemas for all exported types
+          skipTypeCheck: true,
+          // Note: topRef must NOT be set to false, as it prevents interface schemas from being generated
+          expose: "export",
+          // Only export explicitly exported types
+          jsDoc: "extended",
+          // Include JSDoc comments
+          sortProps: true,
+          strictTuples: false,
+          encodeRefs: false,
+          additionalProperties: false
+        };
+        const generator = createGenerator(config);
+        const schema = generator.createSchema(config.type);
+        return convertToGeneratedSchemas(schema);
+      },
+      catch: (error) => SchemaGenerationError.fromError(error, `pattern: ${pattern}`)
+    });
+  }
+);
+const convertToGeneratedSchemas = (schema) => {
+  const definitions = {};
+  const defs = schema.$defs ?? schema.definitions ?? {};
+  for (const [name, def] of Object.entries(defs)) {
+    definitions[name] = def;
+  }
+  return { definitions };
+};
+const generateSchemasFromFiles = Effect.fn(
+  "SchemaGenerator.generateFromFiles"
+)(function* (filePaths, tsconfig) {
+  if (filePaths.length === 0) {
+    return { definitions: {} };
+  }
+  yield* Effect.logDebug("Generating schemas from resolved files").pipe(
+    Effect.annotateLogs({
+      fileCount: filePaths.length
+    })
+  );
+  const batchedResult = yield* generateSchemasWithTempTsconfig(
+    filePaths,
+    tsconfig
+  ).pipe(
+    Effect.catchTag(
+      "SchemaGenerationError",
+      () => generateSchemasFromFilesIndividual(filePaths, tsconfig)
+    )
+  );
+  yield* Effect.logDebug("Additional schema generation complete").pipe(
+    Effect.annotateLogs({
+      definitionCount: Object.keys(batchedResult.definitions).length
+    })
+  );
+  return batchedResult;
+});
+const generateSchemasWithTempTsconfig = (filePaths, tsconfig) => Effect.try({
+  try: () => {
+    const originalConfig = JSON.parse(readFileSync(tsconfig, "utf-8"));
+    const tempConfig = {
+      ...originalConfig,
+      compilerOptions: {
+        ...originalConfig.compilerOptions,
+        skipLibCheck: true,
+        skipDefaultLibCheck: true,
+        noEmit: true
+      },
+      files: [...filePaths],
+      // Prevent loading other files from the project
+      include: void 0,
+      exclude: void 0
+    };
+    const tempTsconfigPath = join(
+      dirname(tsconfig),
+      `.tsconfig.schema-gen.${randomUUID()}.json`
+    );
+    try {
+      writeFileSync(tempTsconfigPath, JSON.stringify(tempConfig, null, 2));
+      const pattern = filePaths.length === 1 ? filePaths[0] : `{${filePaths.join(",")}}`;
+      const config = {
+        path: pattern,
+        tsconfig: tempTsconfigPath,
+        type: "*",
+        skipTypeCheck: true,
+        expose: "export",
+        jsDoc: "extended",
+        sortProps: true,
+        strictTuples: false,
+        encodeRefs: false,
+        additionalProperties: false
+      };
+      const generator = createGenerator(config);
+      const schema = generator.createSchema(config.type);
+      return convertToGeneratedSchemas(schema);
+    } finally {
+      if (existsSync(tempTsconfigPath)) {
+        unlinkSync(tempTsconfigPath);
+      }
+    }
+  },
+  catch: (error) => SchemaGenerationError.fromError(
+    error,
+    `files: ${filePaths.slice(0, 3).join(", ")}${filePaths.length > 3 ? ` (+${filePaths.length - 3} more)` : ""}`
+  )
+});
+const generateSchemasFromFilesIndividual = Effect.fn(
+  "SchemaGenerator.generateFromFilesIndividual"
+)(function* (filePaths, tsconfig) {
+  const schemaResults = yield* Effect.all(
+    filePaths.map(
+      (filePath) => generateSchemasFromFile(filePath, tsconfig).pipe(
+        // Intentional: continue even if individual files fail
+        Effect.catchTag(
+          "SchemaGenerationError",
+          () => Effect.succeed({ definitions: {} })
+        )
+      )
+    ),
+    { concurrency: "unbounded" }
+  );
+  const allDefinitions = schemaResults.reduce(
+    (acc, schemas) => ({ ...acc, ...schemas.definitions }),
+    {}
+  );
+  return { definitions: allDefinitions };
+});
+const generateSchemasFromFile = Effect.fn("SchemaGenerator.generateFromFile")(
+  function* (filePath, tsconfig) {
+    return yield* Effect.try({
+      try: () => {
+        const config = {
+          path: filePath,
+          tsconfig,
+          type: "*",
+          skipTypeCheck: true,
+          expose: "export",
+          jsDoc: "extended",
+          sortProps: true,
+          strictTuples: false,
+          encodeRefs: false,
+          additionalProperties: false
+        };
+        const generator = createGenerator(config);
+        const schema = generator.createSchema(config.type);
+        return convertToGeneratedSchemas(schema);
+      },
+      catch: (error) => SchemaGenerationError.fromError(error, `file: ${filePath}`)
+    });
+  }
+);
+
+const UGLY_REF_PATTERN = /^(?:structure|class)-\d+(-\d+)*$/;
+const CONTAINS_UGLY_REF_PATTERN = /(?:structure|class)-\d+(-\d+)*/;
+const STRUCTURE_REF_PATTERN = UGLY_REF_PATTERN;
+const CONTAINS_STRUCTURE_REF_PATTERN = CONTAINS_UGLY_REF_PATTERN;
+const containsUglyStructureRef = (name) => {
+  const decoded = decodeURIComponent(name);
+  return CONTAINS_STRUCTURE_REF_PATTERN.test(decoded);
+};
+const traverseSchema = (schema, transform) => {
+  const updated = { ...transform(schema) };
+  if (schema.properties) {
+    updated.properties = Object.fromEntries(
+      Object.entries(schema.properties).map(([key, value]) => [
+        key,
+        traverseSchema(value, transform)
+      ])
+    );
+  }
+  if (schema.items) {
+    updated.items = traverseSchema(schema.items, transform);
+  }
+  if (schema.oneOf) {
+    updated.oneOf = schema.oneOf.map((s) => traverseSchema(s, transform));
+  }
+  if (schema.anyOf) {
+    updated.anyOf = schema.anyOf.map((s) => traverseSchema(s, transform));
+  }
+  if (schema.allOf) {
+    updated.allOf = schema.allOf.map((s) => traverseSchema(s, transform));
+  }
+  if (schema.additionalProperties && typeof schema.additionalProperties === "object") {
+    updated.additionalProperties = traverseSchema(
+      schema.additionalProperties,
+      transform
+    );
+  }
+  return updated;
+};
+const extractRefName = (ref) => {
+  const match = ref.match(/^#\/(?:definitions|components\/schemas)\/(.+)$/);
+  return match ? match[1] : ref;
+};
+const toPascalCase = (str) => {
+  if (!str) return str;
+  return str.charAt(0).toUpperCase() + str.slice(1);
+};
+const extractStructureRef = (name) => {
+  if (STRUCTURE_REF_PATTERN.test(name)) {
+    return name;
+  }
+  const match = CONTAINS_STRUCTURE_REF_PATTERN.exec(name);
+  return match ? match[0] : null;
+};
+const findStructureUsages = (schemas) => {
+  const usages = /* @__PURE__ */ new Map();
+  const recordUsage = (structureRef, parent, property, fullRef) => {
+    const isWrapped = fullRef !== structureRef;
+    const wrapper = isWrapped ? fullRef.match(/^([^<]+)</)?.[1] : void 0;
+    const usage = {
+      parent,
+      property,
+      fullRef,
+      isWrapped,
+      wrapper
+    };
+    const existing = usages.get(structureRef) ?? [];
+    existing.push(usage);
+    usages.set(structureRef, existing);
+  };
+  for (const [schemaName, schema] of Object.entries(schemas.definitions)) {
+    if (STRUCTURE_REF_PATTERN.test(schemaName)) {
+      continue;
+    }
+    if (schema.properties) {
+      for (const [propName, propSchema] of Object.entries(schema.properties)) {
+        if (propSchema.$ref) {
+          const refName = extractRefName(propSchema.$ref);
+          const structureRef = extractStructureRef(refName);
+          if (structureRef) {
+            recordUsage(structureRef, schemaName, propName, refName);
+          }
+        }
+        if (propSchema.items?.$ref) {
+          const refName = extractRefName(propSchema.items.$ref);
+          const structureRef = extractStructureRef(refName);
+          if (structureRef) {
+            recordUsage(structureRef, schemaName, propName, refName);
+          }
+        }
+      }
+    }
+  }
+  return usages;
+};
+const replaceStructureInName = (name, structureRef, newName) => {
+  return name.replace(structureRef, newName);
+};
+const updateRefsWithMapping = (schema, structureMapping) => traverseSchema(schema, (s) => {
+  if (!s.$ref) return s;
+  let refName = extractRefName(s.$ref);
+  for (const [structureRef, newName] of structureMapping) {
+    if (refName.includes(structureRef)) {
+      refName = replaceStructureInName(refName, structureRef, newName);
+    }
+  }
+  return { ...s, $ref: `#/components/schemas/${refName}` };
+});
+const findUniqueName = (propertyName, parentName, usedNames) => {
+  if (!usedNames.has(propertyName)) return propertyName;
+  const withParent = `${parentName}${propertyName}`;
+  if (!usedNames.has(withParent)) return withParent;
+  let suffix = 1;
+  while (usedNames.has(`${withParent}_${suffix}`)) {
+    suffix++;
+  }
+  return `${withParent}_${suffix}`;
+};
+const normalizeStructureRefs = (schemas) => {
+  const reservedNames = /* @__PURE__ */ new Set();
+  for (const name of Object.keys(schemas.definitions)) {
+    if (!STRUCTURE_REF_PATTERN.test(name) && !containsUglyStructureRef(name)) {
+      reservedNames.add(name);
+    }
+  }
+  const structureUsages = findStructureUsages(schemas);
+  const structureMapping = /* @__PURE__ */ new Map();
+  const usedNames = new Set(reservedNames);
+  for (const [structureRef, usages] of structureUsages) {
+    if (usages.length === 0) continue;
+    const { parent, property } = usages[0];
+    const propertyPascal = toPascalCase(property);
+    const newName = findUniqueName(propertyPascal, parent, usedNames);
+    structureMapping.set(structureRef, newName);
+    usedNames.add(newName);
+  }
+  const normalizedDefinitions = {};
+  for (const [originalName, schema] of Object.entries(schemas.definitions)) {
+    const newName = resolveNewSchemaName(originalName, structureMapping);
+    if (newName === null) continue;
+    const updatedSchema = updateRefsWithMapping(schema, structureMapping);
+    normalizedDefinitions[newName] = updatedSchema;
+  }
+  return { definitions: normalizedDefinitions };
+};
+const resolveNewSchemaName = (originalName, structureMapping) => {
+  if (STRUCTURE_REF_PATTERN.test(originalName)) {
+    return structureMapping.get(originalName) ?? null;
+  }
+  if (containsUglyStructureRef(originalName)) {
+    for (const [structureRef, mappedName] of structureMapping) {
+      if (originalName.includes(structureRef)) {
+        return replaceStructureInName(originalName, structureRef, mappedName);
+      }
+    }
+  }
+  return originalName;
+};
+
+const extractReferencedSchemas = (paths) => {
+  const refs = /* @__PURE__ */ new Set();
+  const extractFromSchema = (schema) => {
+    if (!schema) return;
+    if (schema.$ref) {
+      const match = schema.$ref.match(/^#\/components\/schemas\/(.+)$/);
+      if (match) {
+        refs.add(match[1]);
+      }
+    }
+    if (schema.items) {
+      extractFromSchema(schema.items);
+    }
+    if (schema.oneOf) {
+      schema.oneOf.forEach(extractFromSchema);
+    }
+    if (schema.properties) {
+      Object.values(schema.properties).forEach(extractFromSchema);
+    }
+  };
+  for (const pathMethods of Object.values(paths)) {
+    for (const operation of Object.values(pathMethods)) {
+      operation.parameters?.forEach((param) => {
+        extractFromSchema(param.schema);
+      });
+      if (operation.requestBody?.content) {
+        Object.values(operation.requestBody.content).forEach((content) => {
+          extractFromSchema(content.schema);
+        });
+      }
+      Object.values(operation.responses).forEach((response) => {
+        if (response.content) {
+          Object.values(response.content).forEach((content) => {
+            extractFromSchema(content.schema);
+          });
+        }
+      });
+    }
+  }
+  return refs;
+};
+const extractNestedReferences = (schemas, knownSchemas) => {
+  const refs = /* @__PURE__ */ new Set();
+  const extractFromSchema = (schema) => {
+    if (!schema) return;
+    if (schema.$ref) {
+      const match = schema.$ref.match(
+        /^#\/(?:components\/schemas|definitions)\/(.+)$/
+      );
+      if (match && !knownSchemas.has(match[1])) {
+        refs.add(match[1]);
+      }
+    }
+    if (schema.items) {
+      extractFromSchema(schema.items);
+    }
+    if (schema.oneOf) {
+      schema.oneOf.forEach(extractFromSchema);
+    }
+    if (schema.anyOf) {
+      schema.anyOf.forEach(extractFromSchema);
+    }
+    if (schema.allOf) {
+      schema.allOf.forEach(extractFromSchema);
+    }
+    if (schema.properties) {
+      Object.values(schema.properties).forEach(extractFromSchema);
+    }
+    if (schema.additionalProperties && typeof schema.additionalProperties === "object") {
+      extractFromSchema(schema.additionalProperties);
+    }
+  };
+  for (const schema of Object.values(schemas)) {
+    extractFromSchema(schema);
+  }
+  return refs;
+};
+const convertToOpenApiSchema = (schema) => {
+  const result = {};
+  if (schema.type) result["type"] = schema.type;
+  if (schema.format) result["format"] = schema.format;
+  if (schema.$ref) {
+    result["$ref"] = schema.$ref.replace(
+      "#/definitions/",
+      "#/components/schemas/"
+    );
+  }
+  if (schema.description) result["description"] = schema.description;
+  if (schema.enum) result["enum"] = schema.enum;
+  if (schema.const !== void 0) result["const"] = schema.const;
+  if (schema.minLength !== void 0) result["minLength"] = schema.minLength;
+  if (schema.maxLength !== void 0) result["maxLength"] = schema.maxLength;
+  if (schema.pattern !== void 0) result["pattern"] = schema.pattern;
+  if (schema.minimum !== void 0) result["minimum"] = schema.minimum;
+  if (schema.maximum !== void 0) result["maximum"] = schema.maximum;
+  if (schema.exclusiveMinimum !== void 0)
+    result["exclusiveMinimum"] = schema.exclusiveMinimum;
+  if (schema.exclusiveMaximum !== void 0)
+    result["exclusiveMaximum"] = schema.exclusiveMaximum;
+  if (schema.minItems !== void 0) result["minItems"] = schema.minItems;
+  if (schema.maxItems !== void 0) result["maxItems"] = schema.maxItems;
+  if (schema.default !== void 0) result["default"] = schema.default;
+  if (schema.items) {
+    result["items"] = convertToOpenApiSchema(schema.items);
+  }
+  if (schema.oneOf) {
+    result["oneOf"] = schema.oneOf.map(convertToOpenApiSchema);
+  }
+  if (schema.anyOf) {
+    result["anyOf"] = schema.anyOf.map(convertToOpenApiSchema);
+  }
+  if (schema.allOf) {
+    result["allOf"] = schema.allOf.map(convertToOpenApiSchema);
+  }
+  if (schema.properties) {
+    result["properties"] = Object.fromEntries(
+      Object.entries(schema.properties).map(([key, value]) => [
+        key,
+        convertToOpenApiSchema(value)
+      ])
+    );
+    if (schema.additionalProperties === void 0) {
+      result["additionalProperties"] = false;
+    }
+  }
+  if (schema.additionalProperties !== void 0) {
+    if (typeof schema.additionalProperties === "boolean") {
+      result["additionalProperties"] = schema.additionalProperties;
+    } else {
+      result["additionalProperties"] = convertToOpenApiSchema(
+        schema.additionalProperties
+      );
+    }
+  }
+  if (schema.required) {
+    result["required"] = [...schema.required];
+  }
+  return result;
+};
+const mergeSchemas = (paths, generatedSchemas) => {
+  const referencedSchemas = extractReferencedSchemas(paths);
+  const schemas = {};
+  const processedSchemas = /* @__PURE__ */ new Set();
+  const toProcess = [...referencedSchemas];
+  while (toProcess.length > 0) {
+    const schemaName = toProcess.pop();
+    if (processedSchemas.has(schemaName)) {
+      continue;
+    }
+    processedSchemas.add(schemaName);
+    const jsonSchema = generatedSchemas.definitions[schemaName];
+    if (jsonSchema) {
+      schemas[schemaName] = convertToOpenApiSchema(jsonSchema);
+      const nestedRefs = extractNestedReferences(
+        { [schemaName]: jsonSchema },
+        processedSchemas
+      );
+      for (const ref of nestedRefs) {
+        if (!processedSchemas.has(ref)) {
+          toProcess.push(ref);
+        }
+      }
+    }
+  }
+  return { paths, schemas };
+};
+
+const createDecoratorFilter = (excludeDecorators) => {
+  if (excludeDecorators.length === 0) {
+    return () => true;
+  }
+  const excludeSet = new Set(excludeDecorators);
+  return (method) => {
+    const hasExcludedDecorator = method.decorators.some(
+      (decorator) => excludeSet.has(decorator)
+    );
+    return !hasExcludedDecorator;
+  };
+};
+const createPathFilter = (pathFilter) => {
+  if (typeof pathFilter === "function") {
+    return (method) => pathFilter(method.path);
+  }
+  return (method) => pathFilter.test(method.path);
+};
+const combineFilters = (filters) => {
+  if (filters.length === 0) {
+    return () => true;
+  }
+  if (filters.length === 1) {
+    return filters[0];
+  }
+  return (method) => filters.every((filter) => filter(method));
+};
+const createFilterPipeline = (options) => {
+  const filters = [];
+  if (options.excludeDecorators && options.excludeDecorators.length > 0) {
+    filters.push(createDecoratorFilter(options.excludeDecorators));
+  }
+  if (options.pathFilter) {
+    filters.push(createPathFilter(options.pathFilter));
+  }
+  if (filters.length === 0) {
+    return void 0;
+  }
+  return combineFilters(filters);
+};
+const filterMethods = (methods, options) => {
+  const filter = createFilterPipeline(options);
+  if (!filter) {
+    return methods;
+  }
+  return methods.filter(filter);
+};
+
+const transformSchemaToV31 = (schema) => {
+  const transformedOneOf = schema.oneOf?.map(transformSchemaToV31);
+  const transformedAnyOf = schema.anyOf?.map(transformSchemaToV31);
+  const transformedAllOf = schema.allOf?.map(transformSchemaToV31);
+  const transformedItems = schema.items ? transformSchemaToV31(schema.items) : void 0;
+  const transformedProperties = schema.properties ? Object.fromEntries(
+    Object.entries(schema.properties).map(([key, value]) => [
+      key,
+      transformSchemaToV31(value)
+    ])
+  ) : void 0;
+  const hasNullable = schema.nullable && schema.type && typeof schema.type === "string";
+  const transformedType = hasNullable ? [schema.type, "null"] : schema.type;
+  const { nullable: _nullable, ...restWithoutNullable } = schema;
+  return {
+    ...restWithoutNullable,
+    type: transformedType,
+    ...transformedOneOf && { oneOf: transformedOneOf },
+    ...transformedAnyOf && { anyOf: transformedAnyOf },
+    ...transformedAllOf && { allOf: transformedAllOf },
+    ...transformedItems && { items: transformedItems },
+    ...transformedProperties && { properties: transformedProperties }
+  };
+};
+const transformSchemasForVersion = (schemas, version) => {
+  if (version === "3.0.3") {
+    return schemas;
+  }
+  return Object.fromEntries(
+    Object.entries(schemas).map(([key, schema]) => [
+      key,
+      transformSchemaToV31(schema)
+    ])
+  );
+};
+const transformSpecForVersion = (spec, version) => {
+  if (version === "3.0.3") {
+    return { ...spec, openapi: version };
+  }
+  const transformedSchemas = spec.components?.schemas ? transformSchemasForVersion(spec.components.schemas, version) : void 0;
+  return {
+    ...spec,
+    openapi: version,
+    ...transformedSchemas && {
+      components: {
+        ...spec.components,
+        schemas: transformedSchemas
+      }
+    }
+  };
+};
+
+const ParameterLocation = Schema.Literal(
+  "path",
+  "query",
+  "header",
+  "cookie",
+  "body"
+);
+const ResolvedParameter = Schema.Struct({
+  name: Schema.String,
+  location: ParameterLocation,
+  tsType: Schema.String,
+  required: Schema.Boolean,
+  description: Schema.OptionFromNullOr(Schema.String)
+  // Note: constraints uses plain interface to avoid Schema initialization overhead
+});
+const ReturnTypeInfo = Schema.Struct({
+  type: Schema.OptionFromNullOr(Schema.String),
+  inline: Schema.OptionFromNullOr(Schema.String),
+  container: Schema.OptionFromNullOr(Schema.Literal("array")),
+  filePath: Schema.OptionFromNullOr(Schema.String)
+});
+const HttpMethod = Schema.Literal(
+  "GET",
+  "POST",
+  "PUT",
+  "PATCH",
+  "DELETE",
+  "OPTIONS",
+  "HEAD",
+  "ALL"
+);
+const OperationMetadata = Schema.Struct({
+  /** Custom summary from @ApiOperation({ summary: '...' }) */
+  summary: Schema.OptionFromNullOr(Schema.String),
+  /** Description from @ApiOperation({ description: '...' }) */
+  description: Schema.OptionFromNullOr(Schema.String),
+  /** Custom operationId from @ApiOperation({ operationId: '...' }) */
+  operationId: Schema.OptionFromNullOr(Schema.String),
+  /** Deprecated flag from @ApiOperation({ deprecated: true }) */
+  deprecated: Schema.OptionFromNullOr(Schema.Boolean)
+});
+const ResponseMetadata = Schema.Struct({
+  /** HTTP status code (e.g., 200, 201, 400, 404) */
+  statusCode: Schema.Number,
+  /** Response description */
+  description: Schema.OptionFromNullOr(Schema.String),
+  /** Response type name (e.g., "UserDto") */
+  type: Schema.OptionFromNullOr(Schema.String),
+  /** Whether the response type is an array */
+  isArray: Schema.Boolean
+});
+const MethodSecurityRequirement = Schema.Struct({
+  /** Security scheme name (e.g., 'bearer', 'jwt', 'oauth2') */
+  schemeName: Schema.String,
+  /** Required scopes (empty array for schemes without scopes) */
+  scopes: Schema.Array(Schema.String)
+});
+Schema.Struct({
+  httpMethod: HttpMethod,
+  path: Schema.String,
+  methodName: Schema.String,
+  controllerName: Schema.String,
+  controllerTags: Schema.Array(Schema.String),
+  returnType: ReturnTypeInfo,
+  parameters: Schema.Array(ResolvedParameter),
+  /** All decorator names on the method (for filtering) */
+  decorators: Schema.Array(Schema.String),
+  /** Metadata from @ApiOperation decorator */
+  operation: OperationMetadata,
+  /** Response metadata from @ApiResponse decorators */
+  responses: Schema.Array(ResponseMetadata),
+  /** Custom HTTP code from @HttpCode decorator */
+  httpCode: Schema.OptionFromNullOr(Schema.Number),
+  /** Content types from @ApiConsumes decorator (request body content types) */
+  consumes: Schema.Array(Schema.String),
+  /** Content types from @ApiProduces decorator (response content types) */
+  produces: Schema.Array(Schema.String),
+  /**
+   * Security requirements from decorators (@ApiBearerAuth, @ApiSecurity, etc.)
+   * Combines controller-level and method-level security.
+   * Multiple requirements = AND logic (all required).
+   * Empty array = no security decorators found (inherits global security).
+   */
+  security: Schema.Array(MethodSecurityRequirement)
+});
+const OpenApiSchemaObject = Schema.suspend(
+  () => Schema.Struct({
+    type: Schema.optional(Schema.String),
+    format: Schema.optional(Schema.String),
+    $ref: Schema.optional(Schema.String),
+    oneOf: Schema.optional(Schema.Array(OpenApiSchemaObject)),
+    items: Schema.optional(OpenApiSchemaObject),
+    properties: Schema.optional(
+      Schema.Record({ key: Schema.String, value: OpenApiSchemaObject })
+    ),
+    required: Schema.optional(Schema.Array(Schema.String))
+  })
+);
+const OpenApiParameter = Schema.Struct({
+  name: Schema.String,
+  in: Schema.Literal("path", "query", "header", "cookie"),
+  description: Schema.optional(Schema.String),
+  required: Schema.Boolean,
+  schema: OpenApiSchemaObject
+});
+const OpenApiRequestBody = Schema.Struct({
+  description: Schema.optional(Schema.String),
+  required: Schema.optional(Schema.Boolean),
+  content: Schema.Record({
+    key: Schema.String,
+    value: Schema.Struct({
+      schema: Schema.Unknown
+    })
+  })
+});
+const OpenApiResponse = Schema.Struct({
+  description: Schema.String,
+  content: Schema.optional(
+    Schema.Record({
+      key: Schema.String,
+      value: Schema.Struct({
+        schema: Schema.Unknown
+      })
+    })
+  )
+});
+Schema.Struct({
+  operationId: Schema.String,
+  summary: Schema.optional(Schema.String),
+  description: Schema.optional(Schema.String),
+  deprecated: Schema.optional(Schema.Boolean),
+  parameters: Schema.optional(Schema.Array(OpenApiParameter)),
+  requestBody: Schema.optional(OpenApiRequestBody),
+  responses: Schema.Record({
+    key: Schema.String,
+    value: OpenApiResponse
+  }),
+  tags: Schema.optional(Schema.Array(Schema.String)),
+  /** Per-operation security requirements */
+  security: Schema.optional(
+    Schema.Array(
+      Schema.Record({ key: Schema.String, value: Schema.Array(Schema.String) })
+    )
+  )
+});
+const OpenApiContactConfig = Schema.Struct({
+  name: Schema.optional(Schema.String),
+  email: Schema.optional(Schema.String),
+  url: Schema.optional(Schema.String)
+});
+const OpenApiLicenseConfig = Schema.Struct({
+  name: Schema.String,
+  url: Schema.optional(Schema.String)
+});
+const OpenApiInfoConfig = Schema.Struct({
+  title: Schema.String,
+  version: Schema.String,
+  description: Schema.optional(Schema.String),
+  contact: Schema.optional(OpenApiContactConfig),
+  license: Schema.optional(OpenApiLicenseConfig)
+});
+const OpenApiServerConfig = Schema.Struct({
+  url: Schema.String,
+  description: Schema.optional(Schema.String)
+});
+const OpenApiTagConfig = Schema.Struct({
+  name: Schema.String,
+  description: Schema.optional(Schema.String)
+});
+const SecuritySchemeType = Schema.Literal(
+  "apiKey",
+  "http",
+  "oauth2",
+  "openIdConnect"
+);
+const SecuritySchemeIn = Schema.Literal("query", "header", "cookie");
+const SecuritySchemeConfig = Schema.Struct({
+  name: Schema.String,
+  type: SecuritySchemeType,
+  scheme: Schema.optional(Schema.String),
+  bearerFormat: Schema.optional(Schema.String),
+  in: Schema.optional(SecuritySchemeIn),
+  parameterName: Schema.optional(Schema.String),
+  description: Schema.optional(Schema.String)
+});
+const SecurityRequirement = Schema.Record({
+  key: Schema.String,
+  value: Schema.Array(Schema.String)
+});
+const OutputFormat = Schema.Literal("json", "yaml");
+const FilesConfig = Schema.Struct({
+  entry: Schema.optional(
+    Schema.Union(Schema.String, Schema.Array(Schema.String))
+  ),
+  tsconfig: Schema.optional(Schema.String),
+  dtoGlob: Schema.optional(
+    Schema.Union(Schema.String, Schema.Array(Schema.String))
+  ),
+  include: Schema.optional(Schema.Array(Schema.String)),
+  exclude: Schema.optional(Schema.Array(Schema.String))
+});
+const SecurityConfig = Schema.Struct({
+  schemes: Schema.optional(Schema.Array(SecuritySchemeConfig)),
+  global: Schema.optional(Schema.Array(SecurityRequirement))
+});
+const OpenApiVersion = Schema.Literal("3.0.3", "3.1.0", "3.2.0");
+const OpenApiConfig = Schema.Struct({
+  version: Schema.optional(OpenApiVersion),
+  info: OpenApiInfoConfig,
+  servers: Schema.optional(Schema.Array(OpenApiServerConfig)),
+  tags: Schema.optional(Schema.Array(OpenApiTagConfig)),
+  security: Schema.optional(SecurityConfig)
+});
+const QueryOptionsConfig = Schema.Struct({
+  style: Schema.optional(Schema.Literal("inline", "ref"))
+});
+const PathFilterFunction = Schema.declare(
+  (input) => typeof input === "function",
+  {
+    identifier: "PathFilterFunction",
+    description: "A function that takes a path string and returns a boolean"
+  }
+);
+const PathFilter = Schema.Union(
+  Schema.instanceOf(RegExp),
+  PathFilterFunction
+);
+const OptionsConfig = Schema.Struct({
+  basePath: Schema.optional(Schema.String),
+  extractValidation: Schema.optional(Schema.Boolean),
+  excludeDecorators: Schema.optional(Schema.Array(Schema.String)),
+  query: Schema.optional(QueryOptionsConfig),
+  pathFilter: Schema.optional(PathFilter)
+});
+const OpenApiGeneratorConfig = Schema.Struct({
+  extends: Schema.optional(Schema.String),
+  files: Schema.optional(FilesConfig),
+  output: Schema.String,
+  format: Schema.optional(OutputFormat),
+  openapi: OpenApiConfig,
+  options: Schema.optional(OptionsConfig)
+});
+Schema.Struct({
+  tsconfig: Schema.String,
+  entry: Schema.Array(Schema.String),
+  include: Schema.Array(Schema.String),
+  exclude: Schema.Array(Schema.String),
+  excludeDecorators: Schema.Array(Schema.String),
+  dtoGlob: Schema.Array(Schema.String),
+  extractValidation: Schema.Boolean,
+  basePath: Schema.optional(Schema.String),
+  pathFilter: Schema.optional(PathFilter),
+  version: Schema.optional(Schema.String),
+  info: OpenApiInfoConfig,
+  servers: Schema.Array(OpenApiServerConfig),
+  securitySchemes: Schema.Array(SecuritySchemeConfig),
+  securityRequirements: Schema.Array(SecurityRequirement),
+  tags: Schema.Array(OpenApiTagConfig),
+  output: Schema.String,
+  format: OutputFormat
+});
+
+const deepMerge = (parent, child) => {
+  const result = { ...parent };
+  for (const key of Object.keys(child)) {
+    const childValue = child[key];
+    const parentValue = parent[key];
+    if (childValue === void 0) {
+      continue;
+    }
+    if (childValue !== null && typeof childValue === "object" && !Array.isArray(childValue) && parentValue !== null && typeof parentValue === "object" && !Array.isArray(parentValue)) {
+      result[key] = deepMerge(
+        parentValue,
+        childValue
+      );
+    } else {
+      result[key] = childValue;
+    }
+  }
+  return result;
+};
+function defineConfig(config) {
+  return config;
+}
+const CONFIG_FILE_NAMES = [
+  "openapi.config.ts",
+  "openapi.config.js",
+  "openapi.config.mjs",
+  "openapi.config.cjs"
+];
+const DEFAULT_ENTRY$1 = "src/app.module.ts";
+const DEFAULT_DTO_GLOB = [
+  "**/*.dto.ts",
+  "**/*.entity.ts",
+  "**/*.model.ts",
+  "**/*.schema.ts"
+];
+const DEFAULT_CONFIG = {
+  files: {
+    include: [],
+    exclude: ["**/*.spec.ts", "**/*.test.ts", "**/node_modules/**"]
+  },
+  options: {
+    excludeDecorators: ["ApiExcludeEndpoint", "ApiExcludeController"],
+    extractValidation: true
+  },
+  format: "json",
+  openapi: {
+    servers: [],
+    tags: [],
+    security: {
+      schemes: [],
+      global: []
+    }
+  }
+};
+const findConfigFile = (startDir = process.cwd()) => Effect.gen(function* () {
+  let currentDir = resolve(startDir);
+  const root = dirname(currentDir);
+  while (currentDir !== root) {
+    for (const fileName of CONFIG_FILE_NAMES) {
+      const configPath = resolve(currentDir, fileName);
+      if (existsSync(configPath)) {
+        return configPath;
+      }
+    }
+    const parentDir = dirname(currentDir);
+    if (parentDir === currentDir) break;
+    currentDir = parentDir;
+  }
+  return yield* ConfigNotFoundError.notFound(startDir);
+});
+const validateConfig = (config, filePath) => Schema.decodeUnknown(OpenApiGeneratorConfig)(config).pipe(
+  Effect.mapError((parseError) => {
+    const issues = parseError.message.split("\n").filter((line) => line.trim());
+    return ConfigValidationError.fromIssues(filePath, issues);
+  })
+);
+const unwrapTsxDoubleDefault = (value) => value && typeof value === "object" && "default" in value && Object.keys(value).length === 1 ? value.default : value;
+const loadRawConfigFromFile = (configPath) => Effect.gen(function* () {
+  const absolutePath = resolve(configPath);
+  if (!existsSync(absolutePath)) {
+    return yield* ConfigNotFoundError.pathNotFound(absolutePath);
+  }
+  yield* Effect.logDebug("Loading config file").pipe(
+    Effect.annotateLogs({ path: absolutePath })
+  );
+  const module = yield* Effect.tryPromise({
+    try: async () => {
+      const fileUrl = pathToFileURL(absolutePath).href;
+      const cacheBustUrl = `${fileUrl}?t=${Date.now()}-${Math.random().toString(36).slice(2)}`;
+      return await import(cacheBustUrl);
+    },
+    catch: (error) => ConfigLoadError.importFailed(absolutePath, error)
+  });
+  const rawConfig = unwrapTsxDoubleDefault(module.default ?? module.config);
+  if (!rawConfig) {
+    return yield* ConfigLoadError.noExport(absolutePath);
+  }
+  return rawConfig;
+});
+const resolveConfigExtends = (rawConfig, configPath, visited = /* @__PURE__ */ new Set()) => Effect.gen(function* () {
+  const absolutePath = resolve(configPath);
+  if (visited.has(absolutePath)) {
+    return yield* ConfigLoadError.importFailed(
+      absolutePath,
+      new Error(`Circular extends detected: ${absolutePath}`)
+    );
+  }
+  visited.add(absolutePath);
+  const extendsPath = rawConfig.extends;
+  if (!extendsPath) {
+    return rawConfig;
+  }
+  const parentConfigPath = resolve(dirname(absolutePath), extendsPath);
+  yield* Effect.logDebug("Resolving config extends").pipe(
+    Effect.annotateLogs({ parent: parentConfigPath })
+  );
+  const parentRawConfig = yield* loadRawConfigFromFile(parentConfigPath);
+  const resolvedParent = yield* resolveConfigExtends(
+    parentRawConfig,
+    parentConfigPath,
+    visited
+  );
+  const { extends: _, ...childWithoutExtends } = rawConfig;
+  return deepMerge(
+    resolvedParent,
+    childWithoutExtends
+  );
+});
+const loadConfigFromFile = (configPath) => Effect.gen(function* () {
+  const rawConfig = yield* loadRawConfigFromFile(configPath);
+  const mergedConfig = yield* resolveConfigExtends(rawConfig, configPath);
+  return yield* validateConfig(mergedConfig, configPath);
+});
+const loadConfig = (configPath, cwd = process.cwd()) => Effect.gen(function* () {
+  const resolvedPath = configPath ? Effect.succeed(configPath) : findConfigFile(cwd);
+  const path = yield* resolvedPath;
+  return yield* loadConfigFromFile(path);
+});
+const resolveConfig = (config) => {
+  const files = config.files ?? {};
+  const options = config.options ?? {};
+  const openapi = config.openapi;
+  const security = openapi.security ?? {};
+  const rawEntry = files.entry ?? DEFAULT_ENTRY$1;
+  const entry = Array.isArray(rawEntry) ? rawEntry : [rawEntry];
+  const rawDtoGlob = files.dtoGlob;
+  const dtoGlob = rawDtoGlob ? Array.isArray(rawDtoGlob) ? rawDtoGlob : [rawDtoGlob] : [...DEFAULT_DTO_GLOB];
+  const tsconfig = files.tsconfig;
+  if (!tsconfig) {
+    throw new Error("tsconfig is required in files configuration");
+  }
+  return {
+    tsconfig,
+    entry,
+    include: files.include ?? DEFAULT_CONFIG.files.include,
+    exclude: files.exclude ?? DEFAULT_CONFIG.files.exclude,
+    excludeDecorators: options.excludeDecorators ?? DEFAULT_CONFIG.options.excludeDecorators,
+    dtoGlob,
+    extractValidation: options.extractValidation ?? DEFAULT_CONFIG.options.extractValidation,
+    basePath: options.basePath,
+    version: openapi.version,
+    info: openapi.info,
+    servers: openapi.servers ?? DEFAULT_CONFIG.openapi.servers,
+    securitySchemes: security.schemes ?? DEFAULT_CONFIG.openapi.security.schemes,
+    securityRequirements: security.global ?? DEFAULT_CONFIG.openapi.security.global,
+    tags: openapi.tags ?? DEFAULT_CONFIG.openapi.tags,
+    output: config.output,
+    format: config.format ?? DEFAULT_CONFIG.format
+  };
+};
+const loadAndResolveConfig = (configPath, cwd = process.cwd()) => Effect.gen(function* () {
+  const config = yield* loadConfig(configPath, cwd);
+  return yield* Effect.try({
+    try: () => resolveConfig(config),
+    catch: (error) => ConfigValidationError.fromIssues(configPath ?? "unknown", [
+      error instanceof Error ? error.message : String(error)
+    ])
+  });
+});
+
+function findRefs(obj, path = "") {
+  const refs = [];
+  if (!obj || typeof obj !== "object") {
+    return refs;
+  }
+  const record = obj;
+  if (typeof record.$ref === "string") {
+    refs.push({ ref: record.$ref, path });
+  }
+  for (const [key, value] of Object.entries(record)) {
+    const newPath = path ? `${path}.${key}` : key;
+    refs.push(...findRefs(value, newPath));
+  }
+  return refs;
+}
+function validateSpec(spec) {
+  const definedSchemas = new Set(Object.keys(spec.components?.schemas ?? {}));
+  const allRefs = findRefs(spec);
+  const schemaRefs = allRefs.filter(
+    (r) => r.ref.startsWith("#/components/schemas/")
+  );
+  const brokenRefs = [];
+  const missingSchemas = /* @__PURE__ */ new Map();
+  for (const { ref, path } of schemaRefs) {
+    const schemaName = ref.replace("#/components/schemas/", "");
+    if (!definedSchemas.has(schemaName)) {
+      brokenRefs.push({
+        ref,
+        path,
+        missingSchema: schemaName
+      });
+      missingSchemas.set(schemaName, (missingSchemas.get(schemaName) ?? 0) + 1);
+    }
+  }
+  return {
+    valid: brokenRefs.length === 0,
+    totalRefs: schemaRefs.length,
+    brokenRefCount: brokenRefs.length,
+    brokenRefs,
+    missingSchemas
+  };
+}
+function categorizeBrokenRefs(missingSchemas) {
+  const primitives = [];
+  const unionTypes = [];
+  const queryParams = [];
+  const other = [];
+  const primitiveTypes = /* @__PURE__ */ new Set([
+    "string",
+    "number",
+    "boolean",
+    "object",
+    "null",
+    "undefined",
+    "void",
+    "any",
+    "unknown",
+    "never"
+  ]);
+  for (const schema of missingSchemas.keys()) {
+    if (primitiveTypes.has(schema.toLowerCase())) {
+      primitives.push(schema);
+      continue;
+    }
+    if (schema.includes(" | ") || schema.includes("|")) {
+      unionTypes.push(schema);
+      continue;
+    }
+    if (schema.endsWith("QueryParams") || schema.endsWith("PathParams") || schema.endsWith("Params")) {
+      queryParams.push(schema);
+      continue;
+    }
+    other.push(schema);
+  }
+  return {
+    primitives,
+    unionTypes,
+    queryParams,
+    other
+  };
+}
+function formatValidationResult(result) {
+  if (result.valid) {
+    return `Spec is valid: ${result.totalRefs} schema refs, all resolved`;
+  }
+  const lines = [
+    `Found ${result.brokenRefCount} broken refs (${result.missingSchemas.size} missing schemas):`
+  ];
+  const categories = categorizeBrokenRefs(result.missingSchemas);
+  if (categories.primitives.length > 0) {
+    lines.push(`
+  Primitive types (should not be $refs):`);
+    for (const name of categories.primitives) {
+      const count = result.missingSchemas.get(name) ?? 0;
+      lines.push(`    - ${name} (${count} usages)`);
+    }
+  }
+  if (categories.unionTypes.length > 0) {
+    lines.push(`
+  Union types (need special handling):`);
+    for (const name of categories.unionTypes) {
+      const count = result.missingSchemas.get(name) ?? 0;
+      lines.push(`    - ${name} (${count} usages)`);
+    }
+  }
+  if (categories.queryParams.length > 0) {
+    lines.push(`
+  Query/Path params (may need dtoGlob coverage):`);
+    for (const name of categories.queryParams) {
+      const count = result.missingSchemas.get(name) ?? 0;
+      lines.push(`    - ${name} (${count} usages)`);
+    }
+  }
+  if (categories.other.length > 0) {
+    lines.push(`
+  Other missing schemas (check dtoGlob patterns):`);
+    for (const name of categories.other.slice(0, 20)) {
+      const count = result.missingSchemas.get(name) ?? 0;
+      lines.push(`    - ${name} (${count} usages)`);
+    }
+    if (categories.other.length > 20) {
+      lines.push(`    ... and ${categories.other.length - 20} more`);
+    }
+  }
+  return lines.join("\n");
+}
+
+function resolveTypeLocations(project, missingTypes) {
+  const resolved = /* @__PURE__ */ new Map();
+  const typeIndex = buildTypeIndex(project);
+  for (const typeName of missingTypes) {
+    const baseTypeName = typeName.replace(/<.*>$/, "");
+    const filePath = typeIndex.get(baseTypeName);
+    if (filePath && !filePath.includes("node_modules")) {
+      resolved.set(typeName, filePath);
+    }
+  }
+  return resolved;
+}
+function buildTypeIndex(project) {
+  const index = /* @__PURE__ */ new Map();
+  for (const sourceFile of project.getSourceFiles()) {
+    const filePath = sourceFile.getFilePath();
+    if (filePath.includes("node_modules")) continue;
+    for (const cls of sourceFile.getClasses()) {
+      if (cls.isExported()) {
+        const name = cls.getName();
+        if (name) {
+          index.set(name, filePath);
+        }
+      }
+    }
+    for (const iface of sourceFile.getInterfaces()) {
+      if (iface.isExported()) {
+        const name = iface.getName();
+        index.set(name, filePath);
+      }
+    }
+    for (const typeAlias of sourceFile.getTypeAliases()) {
+      if (typeAlias.isExported()) {
+        const name = typeAlias.getName();
+        index.set(name, filePath);
+      }
+    }
+    for (const enumDecl of sourceFile.getEnums()) {
+      if (enumDecl.isExported()) {
+        const name = enumDecl.getName();
+        index.set(name, filePath);
+      }
+    }
+  }
+  return index;
+}
+function createTypeResolverProject(tsconfig) {
+  return new Project({
+    tsConfigFilePath: tsconfig,
+    skipAddingFilesFromTsConfig: false,
+    // Need all files for type resolution
+    compilerOptions: {
+      skipLibCheck: true,
+      skipDefaultLibCheck: true,
+      declaration: false,
+      noEmit: true
+    }
+  });
+}
+function hasRipgrep() {
+  try {
+    execSync("rg --version", { encoding: "utf-8", stdio: "pipe" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function resolveTypeLocationsFast(baseDir, missingTypes) {
+  const resolved = /* @__PURE__ */ new Map();
+  const typeNames = [...missingTypes].map((t) => t.replace(/<.*>$/, ""));
+  const typePattern = typeNames.join("|");
+  const pattern = `export\\s+(class|interface|type|enum)\\s+(${typePattern})\\b`;
+  const excludeDirs = [
+    "node_modules",
+    "dist",
+    ".git",
+    "coverage",
+    "__snapshots__",
+    ".turbo",
+    ".next",
+    "build"
+  ];
+  try {
+    let result;
+    if (hasRipgrep()) {
+      const excludeArgs = excludeDirs.map((d) => `-g '!${d}/'`).join(" ");
+      result = execSync(
+        `rg -H --no-heading -t ts ${excludeArgs} '${pattern}' "${baseDir}" 2>/dev/null`,
+        { encoding: "utf-8", timeout: 3e4, maxBuffer: 10 * 1024 * 1024 }
+      );
+    } else {
+      const excludeArgs = excludeDirs.map((d) => `--exclude-dir=${d}`).join(" ");
+      result = execSync(
+        `grep -r -H -E "${pattern}" --include="*.ts" ${excludeArgs} "${baseDir}" 2>/dev/null`,
+        { encoding: "utf-8", timeout: 3e4, maxBuffer: 10 * 1024 * 1024 }
+      );
+    }
+    for (const line of result.split("\n")) {
+      if (!line.trim()) continue;
+      const colonIdx = line.indexOf(":");
+      if (colonIdx === -1) continue;
+      const filePath = line.substring(0, colonIdx);
+      if (filePath.includes("node_modules")) continue;
+      for (const typeName of typeNames) {
+        const typeRegex = new RegExp(
+          `export\\s+(class|interface|type|enum)\\s+${typeName}\\b`
+        );
+        if (typeRegex.test(line) && !resolved.has(typeName)) {
+          resolved.set(typeName, filePath);
+        }
+      }
+    }
+  } catch {
+  }
+  return resolved;
+}
+
+const DEFAULT_ENTRY = "src/app.module.ts";
+const mergeSecurityWithGlobal = (paths, globalSecurity) => {
+  if (!globalSecurity || globalSecurity.length === 0) {
+    return paths;
+  }
+  const mergedPaths = {};
+  for (const [path, methods] of Object.entries(paths)) {
+    const mergedMethods = {};
+    for (const [method, operation] of Object.entries(methods)) {
+      if (operation.security && operation.security.length > 0) {
+        const merged = {};
+        for (const globalReq of globalSecurity) {
+          for (const [scheme, scopes] of Object.entries(globalReq)) {
+            merged[scheme] = [...merged[scheme] ?? [], ...scopes];
+          }
+        }
+        for (const decoratorReq of operation.security) {
+          for (const [scheme, scopes] of Object.entries(decoratorReq)) {
+            merged[scheme] = [...merged[scheme] ?? [], ...scopes];
+          }
+        }
+        for (const scheme of Object.keys(merged)) {
+          merged[scheme] = [...new Set(merged[scheme])];
+        }
+        mergedMethods[method] = {
+          ...operation,
+          security: [merged]
+        };
+      } else {
+        mergedMethods[method] = operation;
+      }
+    }
+    mergedPaths[path] = mergedMethods;
+  }
+  return mergedPaths;
+};
+const OPENAPI_FIELD_ORDER = [
+  "openapi",
+  "info",
+  "servers",
+  "paths",
+  "components",
+  "tags",
+  "security"
+];
+const sortObjectKeysDeep = (obj, isTopLevel = false) => {
+  if (obj === null || typeof obj !== "object") {
+    return obj;
+  }
+  if (Array.isArray(obj)) {
+    return obj.map((item) => sortObjectKeysDeep(item, false));
+  }
+  const sorted = {};
+  const objRecord = obj;
+  const keys = Object.keys(objRecord);
+  const sortedKeys = isTopLevel ? keys.sort((a, b) => {
+    const aIndex = OPENAPI_FIELD_ORDER.indexOf(a);
+    const bIndex = OPENAPI_FIELD_ORDER.indexOf(b);
+    if (aIndex !== -1 && bIndex !== -1) return aIndex - bIndex;
+    if (aIndex !== -1) return -1;
+    if (bIndex !== -1) return 1;
+    return a.localeCompare(b);
+  }) : keys.sort();
+  for (const key of sortedKeys) {
+    sorted[key] = sortObjectKeysDeep(objRecord[key], false);
+  }
+  return sorted;
+};
+const findMissingSchemaRefs = (paths, schemas) => {
+  const defined = new Set(Object.keys(schemas));
+  const missing = /* @__PURE__ */ new Set();
+  const findRefs = (obj) => {
+    if (!obj || typeof obj !== "object") return;
+    const record = obj;
+    if (typeof record.$ref === "string") {
+      const ref = record.$ref;
+      if (ref.startsWith("#/components/schemas/")) {
+        const schemaName = ref.replace("#/components/schemas/", "");
+        if (!defined.has(schemaName)) {
+          missing.add(schemaName);
+        }
+      }
+    }
+    for (const value of Object.values(record)) {
+      findRefs(value);
+    }
+  };
+  findRefs(paths);
+  return missing;
+};
+const extractValidationConstraints = async (dtoGlobPatterns, basePath, tsconfig, schemas) => {
+  const absolutePatterns = dtoGlobPatterns.map(
+    (pattern) => pattern.startsWith("/") ? pattern : join(basePath, pattern)
+  );
+  const fileArrays = await Promise.all(
+    absolutePatterns.map(
+      (pattern) => glob(pattern, { absolute: true, nodir: true })
+    )
+  );
+  const dtoFiles = fileArrays.flat();
+  if (dtoFiles.length === 0) {
+    return schemas;
+  }
+  const project = new Project({
+    tsConfigFilePath: tsconfig,
+    skipAddingFilesFromTsConfig: true,
+    compilerOptions: {
+      // Skip type checking for performance - we only need AST structure
+      skipLibCheck: true,
+      skipDefaultLibCheck: true,
+      allowJs: false,
+      declaration: false,
+      noEmit: true
+    }
+  });
+  project.addSourceFilesAtPaths(dtoFiles);
+  const classConstraints = /* @__PURE__ */ new Map();
+  const classRequired = /* @__PURE__ */ new Map();
+  for (const sourceFile of project.getSourceFiles()) {
+    for (const classDecl of sourceFile.getClasses()) {
+      const className = classDecl.getName();
+      if (!className) continue;
+      const constraints = extractClassConstraints(classDecl);
+      const required = getRequiredProperties(classDecl);
+      if (Object.keys(constraints).length > 0) {
+        classConstraints.set(className, constraints);
+      }
+      if (required.length > 0) {
+        classRequired.set(className, required);
+      }
+    }
+  }
+  return mergeValidationConstraints(schemas, classConstraints, classRequired);
+};
+const findTsConfig = (startDir) => {
+  let currentDir = resolve(startDir);
+  const root = dirname(currentDir);
+  while (currentDir !== root) {
+    const tsconfigPath = join(currentDir, "tsconfig.json");
+    if (existsSync(tsconfigPath)) {
+      return tsconfigPath;
+    }
+    const parentDir = dirname(currentDir);
+    if (parentDir === currentDir) break;
+    currentDir = parentDir;
+  }
+  return void 0;
+};
+const extractMethodInfosFromEntry = (tsconfig, entry, extractOptions = {}) => Effect.gen(function* () {
+  const project = new Project({
+    tsConfigFilePath: tsconfig,
+    skipAddingFilesFromTsConfig: true,
+    compilerOptions: {
+      skipLibCheck: true,
+      skipDefaultLibCheck: true,
+      allowJs: false,
+      declaration: false,
+      noEmit: true
+    }
+  });
+  project.addSourceFilesAtPaths(entry);
+  const entrySourceFile = project.getSourceFile(entry);
+  if (!entrySourceFile) {
+    return yield* EntryNotFoundError.fileNotFound(entry);
+  }
+  let entryClass = entrySourceFile.getClass("AppModule");
+  if (!entryClass) {
+    for (const cls of entrySourceFile.getClasses()) {
+      const hasModuleDecorator = cls.getDecorators().some((d) => d.getName() === "Module");
+      if (hasModuleDecorator) {
+        entryClass = cls;
+        break;
+      }
+    }
+  }
+  if (!entryClass) {
+    return yield* EntryNotFoundError.classNotFound(entry, "Module");
+  }
+  const modules = yield* getModules(entryClass);
+  const methodInfos = modules.flatMap(
+    (mod) => mod.controllers.flatMap(
+      (controller) => getControllerMethodInfos(controller, extractOptions)
+    )
+  );
+  return methodInfos;
+});
+const extractMethodInfosEffect = (tsconfig, entries, extractOptions = {}) => Effect.gen(function* () {
+  const allMethodInfos = yield* Effect.forEach(
+    entries,
+    (entry) => extractMethodInfosFromEntry(tsconfig, entry, extractOptions),
+    { concurrency: "unbounded" }
+  );
+  const seen = /* @__PURE__ */ new Set();
+  const deduped = [];
+  for (const methodInfos of allMethodInfos) {
+    for (const info of methodInfos) {
+      const key = `${info.httpMethod}:${info.path}`;
+      if (!seen.has(key)) {
+        seen.add(key);
+        deduped.push(info);
+      }
+    }
+  }
+  return deduped;
+});
+const generate = async (configPath, overrides) => {
+  const debug = overrides?.debug ?? false;
+  const loggerLayer = debug ? Logger.replace(Logger.defaultLogger, Logger.prettyLoggerDefault).pipe(
+    Layer.merge(Logger.minimumLogLevel(LogLevel.Debug))
+  ) : Logger.minimumLogLevel(LogLevel.Info);
+  const runEffect = (effect) => Effect.runPromise(effect.pipe(Effect.provide(loggerLayer)));
+  const absoluteConfigPath = resolve(configPath);
+  const configDir = dirname(absoluteConfigPath);
+  const config = await runEffect(
+    loadConfigFromFile(absoluteConfigPath).pipe(
+      Effect.tap(
+        () => Effect.logDebug("Config loaded").pipe(
+          Effect.annotateLogs({ configPath: absoluteConfigPath })
+        )
+      ),
+      Effect.mapError((e) => new Error(e.message))
+    )
+  );
+  const files = config.files ?? {};
+  const options = config.options ?? {};
+  const openapi = config.openapi;
+  const security = openapi.security ?? {};
+  const rawEntry = files.entry ?? DEFAULT_ENTRY;
+  const entries = (Array.isArray(rawEntry) ? rawEntry : [rawEntry]).map(
+    (e) => resolve(configDir, e)
+  );
+  const output = resolve(configDir, config.output);
+  const tsconfig = files.tsconfig ? resolve(configDir, files.tsconfig) : findTsConfig(dirname(entries[0]));
+  if (!tsconfig) {
+    throw new Error(
+      `Could not find tsconfig.json. Please specify files.tsconfig in your config file.`
+    );
+  }
+  if (!existsSync(tsconfig)) {
+    throw new Error(`tsconfig.json not found at: ${tsconfig}`);
+  }
+  const extractOptions = {
+    query: options.query
+  };
+  const dtoGlobArray = files.dtoGlob ? Array.isArray(files.dtoGlob) ? files.dtoGlob : [files.dtoGlob] : null;
+  const [extractedMethodInfos, initialSchemas] = await Promise.all([
+    runEffect(
+      extractMethodInfosEffect(tsconfig, entries, extractOptions).pipe(
+        Effect.tap(
+          (methods) => Effect.logDebug("Method extraction complete").pipe(
+            Effect.annotateLogs({ methodCount: methods.length, entries })
+          )
+        ),
+        Effect.mapError((error) => new Error(error.message))
+      )
+    ),
+    dtoGlobArray ? runEffect(
+      generateSchemas({
+        dtoGlob: dtoGlobArray,
+        tsconfig,
+        basePath: configDir
+      }).pipe(
+        Effect.tap(
+          (schemas2) => Effect.logDebug("Schema generation complete").pipe(
+            Effect.annotateLogs({
+              schemaCount: Object.keys(schemas2.definitions).length,
+              dtoGlob: dtoGlobArray
+            })
+          )
+        ),
+        Effect.mapError((error) => new Error(error.message))
+      )
+    ) : Promise.resolve(null)
+  ]);
+  const filteredMethodInfos = filterMethods(extractedMethodInfos, {
+    excludeDecorators: options.excludeDecorators,
+    pathFilter: options.pathFilter
+  });
+  let paths = transformMethods(filteredMethodInfos);
+  if (options.basePath) {
+    const prefix = options.basePath.startsWith("/") ? options.basePath : `/${options.basePath}`;
+    const prefixedPaths = {};
+    for (const [path, methods] of Object.entries(paths)) {
+      const prefixedPath = path.startsWith("/") ? `${prefix}${path}` : `${prefix}/${path}`;
+      prefixedPaths[prefixedPath] = methods;
+    }
+    paths = prefixedPaths;
+  }
+  paths = mergeSecurityWithGlobal(
+    paths,
+    security.global
+  );
+  let schemas = {};
+  if (initialSchemas && dtoGlobArray) {
+    let generatedSchemas = initialSchemas;
+    const shouldExtractValidation = options.extractValidation !== false;
+    if (shouldExtractValidation) {
+      generatedSchemas = await extractValidationConstraints(
+        dtoGlobArray,
+        configDir,
+        tsconfig,
+        generatedSchemas
+      );
+    }
+    generatedSchemas = normalizeStructureRefs(generatedSchemas);
+    let mergeResult = mergeSchemas(
+      paths,
+      generatedSchemas
+    );
+    schemas = mergeResult.schemas;
+    const missingRefs = findMissingSchemaRefs(
+      paths,
+      schemas
+    );
+    if (missingRefs.size > 0) {
+      const tsconfigDir = dirname(tsconfig);
+      const resolvedLocations = resolveTypeLocationsFast(
+        tsconfigDir,
+        missingRefs
+      );
+      const unresolvedTypes = new Set(
+        [...missingRefs].filter(
+          (t) => !resolvedLocations.has(t.replace(/<.*>$/, ""))
+        )
+      );
+      if (unresolvedTypes.size > 0) {
+        const project = createTypeResolverProject(tsconfig);
+        const morphResolved = resolveTypeLocations(project, unresolvedTypes);
+        for (const [type, path] of morphResolved) {
+          resolvedLocations.set(type, path);
+        }
+      }
+      if (resolvedLocations.size > 0) {
+        const additionalFiles = [...new Set(resolvedLocations.values())];
+        const additionalSchemas = await runEffect(
+          generateSchemasFromFiles(additionalFiles, tsconfig)
+        );
+        if (Object.keys(additionalSchemas.definitions).length > 0) {
+          const normalizedAdditional = normalizeStructureRefs(additionalSchemas);
+          const combinedSchemas = {
+            definitions: {
+              ...generatedSchemas.definitions,
+              ...normalizedAdditional.definitions
+            }
+          };
+          mergeResult = mergeSchemas(
+            paths,
+            combinedSchemas
+          );
+          schemas = mergeResult.schemas;
+        }
+      }
+    }
+  }
+  const securitySchemes = security.schemes && security.schemes.length > 0 ? buildSecuritySchemes(security.schemes) : void 0;
+  const hasSchemas = Object.keys(schemas).length > 0;
+  const hasSecuritySchemes = securitySchemes && Object.keys(securitySchemes).length > 0;
+  const components = hasSchemas || hasSecuritySchemes ? {
+    ...hasSchemas && { schemas },
+    ...hasSecuritySchemes && { securitySchemes }
+  } : void 0;
+  const openApiVersion = openapi.version ?? "3.0.3";
+  let spec = {
+    openapi: openApiVersion,
+    info: {
+      title: openapi.info.title,
+      version: openapi.info.version,
+      ...openapi.info.description && {
+        description: openapi.info.description
+      },
+      ...openapi.info.contact && { contact: openapi.info.contact },
+      ...openapi.info.license && { license: openapi.info.license }
+    },
+    servers: openapi.servers ?? [],
+    paths,
+    ...components && { components },
+    tags: openapi.tags ?? [],
+    ...security.global && security.global.length > 0 && {
+      security: security.global
+    }
+  };
+  if (openApiVersion !== "3.0.3") {
+    spec = transformSpecForVersion(spec, openApiVersion);
+  }
+  const sortedSpec = sortObjectKeysDeep(spec, true);
+  const outputDir = dirname(output);
+  if (!existsSync(outputDir)) {
+    mkdirSync(outputDir, { recursive: true });
+  }
+  const format = overrides?.format ?? config.format ?? "json";
+  if (format === "json") {
+    writeFileSync(output, JSON.stringify(sortedSpec, null, 2), "utf-8");
+  } else {
+    writeFileSync(
+      output,
+      yaml.dump(sortedSpec, {
+        indent: 2,
+        lineWidth: -1,
+        // Disable line wrapping
+        noRefs: true,
+        // Disable anchor/alias references
+        quotingType: '"',
+        // Use double quotes for strings
+        forceQuotes: false
+        // Only quote when necessary
+      }),
+      "utf-8"
+    );
+  }
+  const pathCount = Object.keys(paths).length;
+  const operationCount = Object.values(paths).reduce(
+    (acc, methods) => acc + Object.keys(methods).length,
+    0
+  );
+  const schemaCount = Object.keys(schemas).length;
+  const validation = validateSpec(sortedSpec);
+  return {
+    outputPath: output,
+    pathCount,
+    operationCount,
+    schemaCount,
+    validation
+  };
+};
+
+export { loadConfig as a, loadAndResolveConfig as b, categorizeBrokenRefs as c, defineConfig as d, formatValidationResult as e, findConfigFile as f, generate as g, loadConfigFromFile as l, resolveConfig as r, validateSpec as v };