adorn-api 1.0.12 → 1.0.13

package/dist/cli.cjs

@@ -103,7 +103,7 @@ function analyzeClass(node, sourceFile, checker) {
     produces
   };
 }
-function extractClassConsumes(node, checker) {
+function extractClassConsumes(node, _checker) {
   const decorator = findDecorator(node, "Consumes");
   if (!decorator) return void 0;
   const callExpr = decorator.expression;
@@ -119,7 +119,7 @@ function extractClassConsumes(node, checker) {
   }
   return void 0;
 }
-function extractClassProduces(node, checker) {
+function extractClassProduces(node, _checker) {
   const decorator = findDecorator(node, "Produces");
   if (!decorator) return void 0;
   const callExpr = decorator.expression;
@@ -301,7 +301,7 @@ function extractDecoratorStringArg(decorator) {
   }
   return null;
 }
-function unwrapPromise(type, checker) {
+function unwrapPromise(type, _checker) {
   const symbol = type.getSymbol();
   if (symbol?.getName() === "Promise") {
     const typeArgs = type.typeArguments;
@@ -322,12 +322,15 @@ function unwrapPromiseTypeNode(typeNode) {
 }
 
 // src/compiler/schema/openapi.ts
-var import_typescript5 = __toESM(require("typescript"), 1);
+var import_typescript9 = __toESM(require("typescript"), 1);
 
 // src/compiler/schema/typeToJsonSchema.ts
+var import_typescript7 = __toESM(require("typescript"), 1);
+
+// src/compiler/schema/primitives.ts
 var import_typescript3 = __toESM(require("typescript"), 1);
-function typeToJsonSchema(type, ctx, typeNode) {
-  const { checker } = ctx;
+function handlePrimitiveType(type, ctx, typeNode) {
+  const { checker, propertyName } = ctx;
   if (type.flags & import_typescript3.default.TypeFlags.Undefined) {
     return {};
   }
@@ -341,7 +344,7 @@ function typeToJsonSchema(type, ctx, typeNode) {
     return { type: "string" };
   }
   if (type.flags & import_typescript3.default.TypeFlags.Number) {
-    return normalizeNumericType(type, checker, typeNode);
+    return normalizeNumericType(type, checker, typeNode, propertyName);
   }
   if (type.flags & import_typescript3.default.TypeFlags.Boolean) {
     return { type: "boolean" };
@@ -365,26 +368,7 @@ function typeToJsonSchema(type, ctx, typeNode) {
     const intrinsic = type.intrinsicName;
     return { type: "boolean", enum: [intrinsic === "true"] };
   }
-  if (type.isUnion()) {
-    return handleUnion(type, ctx, typeNode);
-  }
-  if (type.isIntersection()) {
-    return handleIntersection(type, ctx, typeNode);
-  }
-  if (checker.isArrayType(type)) {
-    const typeArgs = type.typeArguments;
-    const itemType = typeArgs?.[0];
-    const items = itemType ? typeToJsonSchema(itemType, ctx) : {};
-    return {
-      type: "array",
-      items,
-      uniqueItems: isSetType(type, checker) ? true : void 0
-    };
-  }
-  if (type.flags & import_typescript3.default.TypeFlags.Object) {
-    return handleObjectType(type, ctx, typeNode);
-  }
-  return {};
+  return null;
 }
 function isDateType(type, checker) {
   const symbol = type.getSymbol();
@@ -399,53 +383,51 @@ function isDateType(type, checker) {
   }
   return symbol?.getName() === "Date";
 }
-function isSetType(type, checker) {
-  const symbol = type.getSymbol();
-  if (!symbol) return false;
-  const name = symbol.getName();
-  if (name === "Set") return true;
-  return false;
-}
-function getSchemaName(type, typeNode) {
-  const aliasSymbol = type.aliasSymbol ?? type.aliasSymbol;
-  const aliasName = aliasSymbol?.getName();
-  if (aliasName && aliasName !== "__type") {
-    return aliasName;
+function normalizeNumericType(type, checker, typeNode, propertyName) {
+  const typeName = getExplicitTypeNameFromNode(typeNode) ?? null;
+  const symbol = getEffectiveSymbol(type, checker);
+  const symbolName = symbol?.getName() ?? null;
+  if (shouldBeIntegerType(typeName) || shouldBeIntegerType(symbolName) || shouldBeIntegerType(propertyName ?? null)) {
+    return { type: "integer" };
   }
-  const symbol = type.getSymbol();
-  const symbolName = symbol?.getName?.();
-  if (symbolName && symbolName !== "__type") {
-    return symbolName;
+  return { type: "number" };
+}
+function shouldBeIntegerType(typeName) {
+  if (!typeName) return false;
+  const lower = typeName.toLowerCase();
+  return lower === "id" || lower.endsWith("id") || lower === "primarykey" || lower === "pk" || lower === "page" || lower === "pagesize" || lower === "totalitems" || lower === "limit" || lower === "offset";
+}
+function getExplicitTypeNameFromNode(typeNode) {
+  if (!typeNode) return null;
+  if (import_typescript3.default.isTypeReferenceNode(typeNode)) {
+    if (import_typescript3.default.isIdentifier(typeNode.typeName)) {
+      return typeNode.typeName.text;
+    }
   }
-  const nodeName = getExplicitTypeNameFromNode(typeNode);
-  if (nodeName && nodeName !== "__type") {
-    return nodeName;
+  if (import_typescript3.default.isTypeAliasDeclaration(typeNode.parent)) {
+    if (import_typescript3.default.isIdentifier(typeNode.parent.name)) {
+      return typeNode.parent.name.text;
+    }
   }
   return null;
 }
-function buildNamedSchema(type, ctx, typeNode, build) {
-  const name = getSchemaName(type, typeNode);
-  if (!name) {
-    return build();
-  }
-  const { components, typeStack } = ctx;
-  if (components.has(name) || typeStack.has(type)) {
-    return { $ref: `#/components/schemas/${name}` };
-  }
-  typeStack.add(type);
-  const schema = build();
-  typeStack.delete(type);
-  if (!components.has(name)) {
-    components.set(name, schema);
+function getEffectiveSymbol(type, checker) {
+  const aliasSymbol = type.aliasSymbol ?? type.aliasSymbol;
+  if (aliasSymbol && aliasSymbol.flags & import_typescript3.default.SymbolFlags.Alias) {
+    return checker.getAliasedSymbol(aliasSymbol);
   }
-  return { $ref: `#/components/schemas/${name}` };
+  return type.getSymbol() ?? null;
 }
+
+// src/compiler/schema/unionHandler.ts
+var import_typescript4 = __toESM(require("typescript"), 1);
 function handleUnion(type, ctx, typeNode) {
   return buildNamedSchema(type, ctx, typeNode, () => {
     const types = type.types;
-    const nullType = types.find((t) => t.flags & import_typescript3.default.TypeFlags.Null);
-    const otherTypes = types.filter((t) => !(t.flags & import_typescript3.default.TypeFlags.Null) && !(t.flags & import_typescript3.default.TypeFlags.Undefined));
-    const allStringLiterals = otherTypes.every((t) => t.flags & import_typescript3.default.TypeFlags.StringLiteral);
+    const nullType = types.find((t) => t.flags & import_typescript4.default.TypeFlags.Null);
+    const undefinedType = types.find((t) => t.flags & import_typescript4.default.TypeFlags.Undefined);
+    const otherTypes = types.filter((t) => !(t.flags & import_typescript4.default.TypeFlags.Null) && !(t.flags & import_typescript4.default.TypeFlags.Undefined));
+    const allStringLiterals = otherTypes.every((t) => t.flags & import_typescript4.default.TypeFlags.StringLiteral);
     if (allStringLiterals && otherTypes.length > 0) {
       const enumValues = otherTypes.map((t) => t.value);
       const schema = { type: "string", enum: enumValues };
@@ -454,6 +436,14 @@ function handleUnion(type, ctx, typeNode) {
       }
       return schema;
     }
+    const allBooleanLiterals = otherTypes.length > 0 && otherTypes.every((t) => t.flags & import_typescript4.default.TypeFlags.BooleanLiteral);
+    if (allBooleanLiterals) {
+      const schema = { type: "boolean" };
+      if (nullType || undefinedType) {
+        schema.type = ["boolean", "null"];
+      }
+      return schema;
+    }
     if (otherTypes.length === 1 && nullType) {
       const innerSchema = typeToJsonSchema(otherTypes[0], ctx);
       if (typeof innerSchema.type === "string") {
@@ -483,49 +473,7 @@ function handleUnion(type, ctx, typeNode) {
     return {};
   });
 }
-function handleIntersection(type, ctx, typeNode) {
-  return buildNamedSchema(type, ctx, typeNode, () => {
-    const types = type.types;
-    const brandCollapsed = tryCollapseBrandedIntersection(types, ctx, typeNode);
-    if (brandCollapsed) {
-      return brandCollapsed;
-    }
-    const allOf = [];
-    for (const t of types) {
-      allOf.push(typeToJsonSchema(t, ctx));
-    }
-    return { allOf };
-  });
-}
-function tryCollapseBrandedIntersection(types, ctx, typeNode) {
-  const { checker } = ctx;
-  const parts = [...types];
-  const prim = parts.find(isPrimitiveLike);
-  if (!prim) return null;
-  const rest = parts.filter((p) => p !== prim);
-  if (rest.every((r) => isBrandObject(checker, r, ctx))) {
-    return typeToJsonSchema(prim, ctx);
-  }
-  return null;
-}
-function isPrimitiveLike(t) {
-  return (t.flags & (import_typescript3.default.TypeFlags.String | import_typescript3.default.TypeFlags.Number | import_typescript3.default.TypeFlags.Boolean | import_typescript3.default.TypeFlags.BigInt)) !== 0 || (t.flags & import_typescript3.default.TypeFlags.StringLiteral) !== 0 || (t.flags & import_typescript3.default.TypeFlags.NumberLiteral) !== 0;
-}
-function isBrandObject(checker, t, ctx) {
-  if (!(t.flags & import_typescript3.default.TypeFlags.Object)) return false;
-  const props = t.getProperties();
-  if (props.length === 0) return false;
-  const allowed = /* @__PURE__ */ new Set(["__brand", "__type", "__tag", "brand"]);
-  for (const p of props) {
-    if (!allowed.has(p.getName())) return false;
-  }
-  const callSigs = t.getCallSignatures?.();
-  if (callSigs && callSigs.length > 0) return false;
-  const constructSigs = t.getConstructSignatures?.();
-  if (constructSigs && constructSigs.length > 0) return false;
-  return true;
-}
-function detectDiscriminatedUnion(types, ctx, branches) {
+function detectDiscriminatedUnion(types, ctx, _branches) {
   if (types.length < 2) return null;
   const candidates = findCommonPropertyNames(ctx.checker, types);
   for (const propName of candidates) {
@@ -556,10 +504,10 @@ function findCommonPropertyNames(checker, types) {
 function isRequiredProperty(checker, type, propName) {
   const sym = checker.getPropertyOfType(type, propName);
   if (!sym) return false;
-  if (sym.flags & import_typescript3.default.SymbolFlags.Optional) return false;
+  if (sym.flags & import_typescript4.default.SymbolFlags.Optional) return false;
   const propType = checker.getTypeOfSymbol(sym);
   if (propType.isUnion?.()) {
-    const hasUndefined = propType.types.some((t) => (t.flags & import_typescript3.default.TypeFlags.Undefined) !== 0);
+    const hasUndefined = propType.types.some((t) => (t.flags & import_typescript4.default.TypeFlags.Undefined) !== 0);
     if (hasUndefined) return false;
   }
   return true;
@@ -602,14 +550,187 @@ function getBranchSchemaName(type, ctx) {
   }
   return `Anonymous_${ctx.typeNameStack.length}`;
 }
+function buildNamedSchema(type, ctx, typeNode, build) {
+  const name = getSchemaName(type, typeNode);
+  if (!name) {
+    return build();
+  }
+  const { components, typeStack } = ctx;
+  if (components.has(name) || typeStack.has(type)) {
+    return { $ref: `#/components/schemas/${name}` };
+  }
+  typeStack.add(type);
+  const schema = build();
+  typeStack.delete(type);
+  if (!components.has(name)) {
+    components.set(name, schema);
+  }
+  return { $ref: `#/components/schemas/${name}` };
+}
+function getSchemaName(type, typeNode) {
+  const aliasSymbol = type.aliasSymbol ?? type.aliasSymbol;
+  const aliasName = aliasSymbol?.getName();
+  if (aliasName && aliasName !== "__type") {
+    return aliasName;
+  }
+  const symbol = type.getSymbol();
+  const symbolName = symbol?.getName?.();
+  if (symbolName && symbolName !== "__type") {
+    return symbolName;
+  }
+  const nodeName = getExplicitTypeNameFromNode2(typeNode);
+  if (nodeName && nodeName !== "__type") {
+    return nodeName;
+  }
+  return null;
+}
+function getExplicitTypeNameFromNode2(typeNode) {
+  if (!typeNode) return null;
+  if (import_typescript4.default.isTypeReferenceNode(typeNode)) {
+    if (import_typescript4.default.isIdentifier(typeNode.typeName)) {
+      return typeNode.typeName.text;
+    }
+  }
+  if (import_typescript4.default.isTypeAliasDeclaration(typeNode.parent)) {
+    if (import_typescript4.default.isIdentifier(typeNode.parent.name)) {
+      return typeNode.parent.name.text;
+    }
+  }
+  return null;
+}
+
+// src/compiler/schema/intersectionHandler.ts
+var import_typescript5 = __toESM(require("typescript"), 1);
+function handleIntersection(type, ctx, typeNode) {
+  return buildNamedSchema2(type, ctx, typeNode, () => {
+    const types = type.types;
+    const brandCollapsed = tryCollapseBrandedIntersection(types, ctx, typeNode);
+    if (brandCollapsed) {
+      return brandCollapsed;
+    }
+    const allOf = [];
+    for (const t of types) {
+      const schema = typeToJsonSchema(t, ctx);
+      if (Object.keys(schema).length > 0) {
+        if (isEmptyObjectSchema(schema)) {
+          continue;
+        }
+        allOf.push(schema);
+      }
+    }
+    if (allOf.length === 0) {
+      return {};
+    }
+    if (allOf.length === 1) {
+      return allOf[0];
+    }
+    return { allOf };
+  });
+}
+function tryCollapseBrandedIntersection(types, ctx, _typeNode) {
+  const { checker } = ctx;
+  const parts = [...types];
+  const prim = parts.find(isPrimitiveLike);
+  if (!prim) return null;
+  const rest = parts.filter((p) => p !== prim);
+  if (rest.every((r) => isBrandObject(checker, r, ctx))) {
+    return typeToJsonSchema(prim, ctx);
+  }
+  return null;
+}
+function isPrimitiveLike(t) {
+  return (t.flags & (import_typescript5.default.TypeFlags.String | import_typescript5.default.TypeFlags.Number | import_typescript5.default.TypeFlags.Boolean | import_typescript5.default.TypeFlags.BigInt)) !== 0 || (t.flags & import_typescript5.default.TypeFlags.StringLiteral) !== 0 || (t.flags & import_typescript5.default.TypeFlags.NumberLiteral) !== 0;
+}
+function isBrandObject(checker, t, _ctx) {
+  if (!(t.flags & import_typescript5.default.TypeFlags.Object)) return false;
+  const props = t.getProperties();
+  if (props.length === 0) return false;
+  const allowed = /* @__PURE__ */ new Set(["__brand", "__type", "__tag", "brand"]);
+  for (const p of props) {
+    if (!allowed.has(p.getName())) return false;
+  }
+  const callSigs = t.getCallSignatures?.();
+  if (callSigs && callSigs.length > 0) return false;
+  const constructSigs = t.getConstructSignatures?.();
+  if (constructSigs && constructSigs.length > 0) return false;
+  return true;
+}
+function isEmptyObjectSchema(schema) {
+  if (schema.type !== "object") {
+    return false;
+  }
+  if (!schema.properties || Object.keys(schema.properties).length === 0) {
+    if (!schema.additionalProperties) {
+      return true;
+    }
+  }
+  return false;
+}
+function buildNamedSchema2(type, ctx, typeNode, build) {
+  const name = getSchemaName2(type, typeNode);
+  if (!name) {
+    return build();
+  }
+  const { components, typeStack } = ctx;
+  if (components.has(name) || typeStack.has(type)) {
+    return { $ref: `#/components/schemas/${name}` };
+  }
+  typeStack.add(type);
+  const schema = build();
+  typeStack.delete(type);
+  if (!components.has(name)) {
+    components.set(name, schema);
+  }
+  return { $ref: `#/components/schemas/${name}` };
+}
+function getSchemaName2(type, typeNode) {
+  const aliasSymbol = type.aliasSymbol ?? type.aliasSymbol;
+  const aliasName = aliasSymbol?.getName();
+  if (aliasName && aliasName !== "__type") {
+    return aliasName;
+  }
+  const symbol = type.getSymbol();
+  const symbolName = symbol?.getName?.();
+  if (symbolName && symbolName !== "__type") {
+    return symbolName;
+  }
+  const nodeName = getExplicitTypeNameFromNode3(typeNode);
+  if (nodeName && nodeName !== "__type") {
+    return nodeName;
+  }
+  return null;
+}
+function getExplicitTypeNameFromNode3(typeNode) {
+  if (!typeNode) return null;
+  if (import_typescript5.default.isTypeReferenceNode(typeNode)) {
+    if (import_typescript5.default.isIdentifier(typeNode.typeName)) {
+      return typeNode.typeName.text;
+    }
+  }
+  if (import_typescript5.default.isTypeAliasDeclaration(typeNode.parent)) {
+    if (import_typescript5.default.isIdentifier(typeNode.parent.name)) {
+      return typeNode.parent.name.text;
+    }
+  }
+  return null;
+}
+
+// src/compiler/schema/objectHandler.ts
+var import_typescript6 = __toESM(require("typescript"), 1);
 function handleObjectType(type, ctx, typeNode) {
-  const { checker, components, typeStack, mode } = ctx;
+  const { checker, components, typeStack } = ctx;
   const symbol = type.getSymbol();
   const typeName = symbol?.getName?.() ?? getTypeNameFromNode(typeNode, ctx);
   if (isMetalOrmWrapperType(type, checker)) {
     return handleMetalOrmWrapper(type, ctx);
   }
   if (typeName && typeName !== "__type") {
+    const isMetalOrmGeneric = METAL_ORM_WRAPPER_NAMES.some(
+      (name) => typeName === name || typeName.endsWith("Api")
+    );
+    if (isMetalOrmGeneric) {
+      return {};
+    }
     if (components.has(typeName)) {
       return { $ref: `#/components/schemas/${typeName}` };
     }
@@ -630,40 +751,7 @@ function handleObjectType(type, ctx, typeNode) {
   typeStack.delete(type);
   return schema;
 }
-function getExplicitTypeNameFromNode(typeNode) {
-  if (!typeNode) return null;
-  if (import_typescript3.default.isTypeReferenceNode(typeNode)) {
-    if (import_typescript3.default.isIdentifier(typeNode.typeName)) {
-      return typeNode.typeName.text;
-    }
-  }
-  if (import_typescript3.default.isTypeAliasDeclaration(typeNode.parent)) {
-    if (import_typescript3.default.isIdentifier(typeNode.parent.name)) {
-      return typeNode.parent.name.text;
-    }
-  }
-  return null;
-}
-function shouldBeIntegerType(typeName) {
-  if (!typeName) return false;
-  const lower = typeName.toLowerCase();
-  return lower === "id" || lower.endsWith("id") || lower === "primarykey" || lower === "pk";
-}
-function normalizeNumericType(type, checker, typeNode) {
-  const typeName = getExplicitTypeNameFromNode(typeNode) ?? null;
-  const symbol = getEffectiveSymbol(type, checker);
-  const symbolName = symbol?.getName() ?? null;
-  if (shouldBeIntegerType(typeName) || shouldBeIntegerType(symbolName)) {
-    return { type: "integer" };
-  }
-  return { type: "number" };
-}
-function getTypeNameFromNode(typeNode, ctx) {
-  const explicitName = getExplicitTypeNameFromNode(typeNode);
-  if (explicitName) return explicitName;
-  return `Anonymous_${ctx.typeNameStack.length}`;
-}
-function buildObjectSchema(type, ctx, typeNode) {
+function buildObjectSchema(type, ctx, _typeNode) {
   const { checker, mode } = ctx;
   const properties = {};
   const required = [];
@@ -677,9 +765,10 @@ function buildObjectSchema(type, ctx, typeNode) {
     if (isMethodLike(propType)) {
       continue;
     }
-    const isOptional = !!(prop.flags & import_typescript3.default.SymbolFlags.Optional);
+    const isOptional = !!(prop.flags & import_typescript6.default.SymbolFlags.Optional);
     const isRelation = isMetalOrmWrapperType(propType, checker);
-    properties[propName] = typeToJsonSchema(propType, ctx);
+    const propCtx = { ...ctx, propertyName: propName };
+    properties[propName] = typeToJsonSchema(propType, propCtx);
     const shouldRequire = mode === "response" ? !isRelation && !isOptional : !isOptional;
     if (shouldRequire) {
       required.push(propName);
@@ -700,14 +789,14 @@ function buildObjectSchema(type, ctx, typeNode) {
   }
   return schema;
 }
-function isRecordType(type, checker) {
+function isRecordType(type, _checker) {
   const symbol = type.getSymbol();
   if (!symbol) return false;
   const name = symbol.getName();
   if (name === "Record") return true;
   return false;
 }
-function getRecordValueType(type, checker) {
+function getRecordValueType(type, _checker) {
   const symbol = type.getSymbol();
   if (!symbol) return null;
   const name = symbol.getName();
@@ -720,24 +809,8 @@ function getRecordValueType(type, checker) {
   }
   return null;
 }
-var METAL_ORM_WRAPPER_NAMES = ["HasManyCollection", "ManyToManyCollection", "BelongsToReference", "HasOneReference"];
 function isMetalOrmWrapperType(type, checker) {
-  const aliasSymbol = type.aliasSymbol || type.symbol;
-  if (!aliasSymbol) return false;
-  return METAL_ORM_WRAPPER_NAMES.includes(aliasSymbol.getName());
-}
-function getWrapperTypeName(type, checker) {
-  const symbol = getEffectiveSymbol(type, checker);
-  if (!symbol) return null;
-  const name = symbol.getName();
-  return METAL_ORM_WRAPPER_NAMES.includes(name) ? name : null;
-}
-function getEffectiveSymbol(type, checker) {
-  const aliasSymbol = type.aliasSymbol ?? type.aliasSymbol;
-  if (aliasSymbol && aliasSymbol.flags & import_typescript3.default.SymbolFlags.Alias) {
-    return checker.getAliasedSymbol(aliasSymbol);
-  }
-  return type.getSymbol() ?? null;
+  return !!findMetalOrmWrapper(type, checker);
 }
 function isMethodLike(type) {
   const callSigs = type.getCallSignatures?.();
@@ -746,6 +819,69 @@ function isMethodLike(type) {
 function isIteratorOrSymbolProperty(propName) {
   return propName.startsWith("__@") || propName.startsWith("[") || propName === Symbol.iterator.toString();
 }
+function getTypeNameFromNode(typeNode, _ctx) {
+  const explicitName = getExplicitTypeNameFromNode4(typeNode);
+  if (explicitName) return explicitName;
+  return "Anonymous_${ctx.typeNameStack.length}";
+}
+function getExplicitTypeNameFromNode4(typeNode) {
+  if (!typeNode) return null;
+  if (import_typescript6.default.isTypeReferenceNode(typeNode)) {
+    if (import_typescript6.default.isIdentifier(typeNode.typeName)) {
+      return typeNode.typeName.text;
+    }
+  }
+  if (import_typescript6.default.isTypeAliasDeclaration(typeNode.parent)) {
+    if (import_typescript6.default.isIdentifier(typeNode.parent.name)) {
+      return typeNode.parent.name.text;
+    }
+  }
+  return null;
+}
+var METAL_ORM_WRAPPER_NAMES = ["HasManyCollection", "ManyToManyCollection", "BelongsToReference", "HasOneReference"];
+function findMetalOrmWrapper(type, checker) {
+  if (type.isIntersection()) {
+    let wrapperInfo = null;
+    let hasReadonlyArray = false;
+    for (const constituent of type.types) {
+      const result = findWrapperInType(constituent, checker);
+      if (result) {
+        wrapperInfo = result;
+      }
+      if (!(constituent.flags & import_typescript6.default.TypeFlags.Object)) continue;
+      const symbol = constituent.getSymbol();
+      if (symbol?.getName() === "ReadonlyArray") {
+        hasReadonlyArray = true;
+      }
+    }
+    if (wrapperInfo) {
+      return { ...wrapperInfo, isReadonlyArray: hasReadonlyArray };
+    }
+    return null;
+  }
+  return findWrapperInType(type, checker);
+}
+function findWrapperInType(type, checker) {
+  const aliasSymbol = type.aliasSymbol ?? type.aliasSymbol;
+  const symbol = type.getSymbol();
+  const effectiveSymbol = aliasSymbol && aliasSymbol.flags & import_typescript6.default.SymbolFlags.Alias ? checker.getAliasedSymbol(aliasSymbol) : symbol;
+  if (!effectiveSymbol) return null;
+  const name = effectiveSymbol.getName();
+  if (!METAL_ORM_WRAPPER_NAMES.includes(name)) return null;
+  const typeRef = type;
+  const typeArgs = typeRef.typeArguments || [];
+  return {
+    wrapperName: name,
+    targetTypeArgs: typeArgs,
+    isReadonlyArray: false
+  };
+}
+function getWrapperTypeName(type, _checker) {
+  const symbol = type.getSymbol();
+  if (!symbol) return null;
+  const name = symbol.getName();
+  return METAL_ORM_WRAPPER_NAMES.includes(name) ? name : null;
+}
 function handleMetalOrmWrapper(type, ctx) {
   const typeRef = type;
   const typeArgs = typeRef.typeArguments;
@@ -764,30 +900,138 @@ function handleMetalOrmWrapper(type, ctx) {
       "x-metal-orm-rel": wrapperRel
     };
   }
-  const targetSchema = targetType ? typeToJsonSchema(targetType, ctx) : {};
+  if (!targetType) {
+    return { "x-metal-orm-rel": wrapperRel };
+  }
+  if (wrapperName === "BelongsToReference" || wrapperName === "HasOneReference") {
+    return handleBelongsToReference(targetType, ctx, wrapperRel);
+  }
+  const targetSchema = typeToJsonSchema(targetType, ctx);
   return {
     ...targetSchema,
     "x-metal-orm-rel": wrapperRel
   };
 }
+function handleBelongsToReference(targetType, ctx, wrapperRel) {
+  const { components } = ctx;
+  const targetSymbol = targetType.getSymbol();
+  const typeName = targetSymbol?.getName();
+  if (!typeName) {
+    return {
+      type: "object",
+      properties: {},
+      "x-metal-orm-rel": wrapperRel
+    };
+  }
+  const refSchemaName = `${typeName}Ref`;
+  if (components.has(refSchemaName)) {
+    return {
+      $ref: `#/components/schemas/${refSchemaName}`,
+      "x-metal-orm-rel": wrapperRel
+    };
+  }
+  const refSchema = buildRefSchema(targetType, ctx);
+  components.set(refSchemaName, refSchema);
+  return {
+    $ref: `#/components/schemas/${refSchemaName}`,
+    "x-metal-orm-rel": wrapperRel
+  };
+}
+function buildRefSchema(type, ctx) {
+  const { checker } = ctx;
+  if (!(type.flags & import_typescript6.default.TypeFlags.Object)) {
+    return { type: "object", properties: {} };
+  }
+  const objectType = type;
+  const properties = {};
+  const required = [];
+  const props = checker.getPropertiesOfType(objectType);
+  for (const prop of props) {
+    const propName = prop.getName();
+    if (isIteratorOrSymbolProperty(propName)) {
+      continue;
+    }
+    const propType = checker.getTypeOfSymbol(prop);
+    if (isMethodLike(propType)) {
+      continue;
+    }
+    const isOptional = !!(prop.flags & import_typescript6.default.SymbolFlags.Optional);
+    const isRelation = isMetalOrmWrapperType(propType, checker);
+    if (isRelation) {
+      continue;
+    }
+    const propCtx = { ...ctx, propertyName: propName };
+    properties[propName] = typeToJsonSchema(propType, propCtx);
+    if (!isOptional) {
+      required.push(propName);
+    }
+  }
+  const schema = {
+    type: "object",
+    properties
+  };
+  if (required.length > 0) {
+    schema.required = required;
+  }
+  return schema;
+}
+
+// src/compiler/schema/typeToJsonSchema.ts
+function typeToJsonSchema(type, ctx, typeNode) {
+  const primitiveResult = handlePrimitiveType(type, ctx, typeNode);
+  if (primitiveResult) {
+    return primitiveResult;
+  }
+  if (type.isUnion()) {
+    return handleUnion(type, ctx, typeNode);
+  }
+  if (type.isIntersection()) {
+    return handleIntersection(type, ctx, typeNode);
+  }
+  if (ctx.checker.isArrayType(type)) {
+    const typeArgs = type.typeArguments;
+    const itemType = typeArgs?.[0];
+    const items = itemType ? typeToJsonSchema(itemType, ctx) : {};
+    return {
+      type: "array",
+      items,
+      uniqueItems: isSetType(type, ctx.checker) ? true : void 0
+    };
+  }
+  if (type.flags & import_typescript7.default.TypeFlags.Object) {
+    const objectType = type;
+    if (isMetalOrmWrapperType(type, ctx.checker)) {
+      return handleMetalOrmWrapper(objectType, ctx);
+    }
+    return handleObjectType(objectType, ctx, typeNode);
+  }
+  return {};
+}
+function isSetType(type, _checker) {
+  const symbol = type.getSymbol();
+  if (!symbol) return false;
+  const name = symbol.getName();
+  if (name === "Set") return true;
+  return false;
+}
 
 // src/compiler/schema/extractAnnotations.ts
-var import_typescript4 = __toESM(require("typescript"), 1);
+var import_typescript8 = __toESM(require("typescript"), 1);
 function extractPropertySchemaFragments(checker, prop) {
-  if (!import_typescript4.default.canHaveDecorators(prop)) return [];
-  const decs = import_typescript4.default.getDecorators(prop);
+  if (!import_typescript8.default.canHaveDecorators(prop)) return [];
+  const decs = import_typescript8.default.getDecorators(prop);
   if (!decs || decs.length === 0) return [];
   const frags = [];
   for (const d of decs) {
     const expr = d.expression;
     let callee;
     let args;
-    if (import_typescript4.default.isCallExpression(expr)) {
+    if (import_typescript8.default.isCallExpression(expr)) {
       callee = expr.expression;
       args = expr.arguments;
     } else {
       callee = expr;
-      args = import_typescript4.default.factory.createNodeArray([]);
+      args = import_typescript8.default.factory.createNodeArray([]);
     }
     const sym = checker.getSymbolAtLocation(callee);
     if (!sym) continue;
@@ -796,7 +1040,7 @@ function extractPropertySchemaFragments(checker, prop) {
     const name = resolved.name;
     if (name === "Schema") {
       const obj = args[0];
-      if (obj && import_typescript4.default.isObjectLiteralExpression(obj)) {
+      if (obj && import_typescript8.default.isObjectLiteralExpression(obj)) {
         const frag = objectLiteralToJson(obj);
         if (frag) frags.push(frag);
       }
@@ -818,7 +1062,7 @@ function extractPropertySchemaFragments(checker, prop) {
       frags.push({ format: args[0].text });
     } else if (name === "Pattern") {
       const arg = args[0];
-      if (arg && import_typescript4.default.isRegularExpressionLiteral(arg)) {
+      if (arg && import_typescript8.default.isRegularExpressionLiteral(arg)) {
         frags.push({ pattern: extractRegexPattern(arg.text) });
       } else if (isStringLiteral(arg)) {
         frags.push({ pattern: arg.text });
@@ -835,11 +1079,11 @@ function extractPropertySchemaFragments(checker, prop) {
       frags.push({ multipleOf: Number(args[0].text) });
     } else if (name === "Example") {
       frags.push({ example: literalToJson(args[0]) });
-    } else if (name === "Examples" && import_typescript4.default.isArrayLiteralExpression(args[0])) {
+    } else if (name === "Examples" && import_typescript8.default.isArrayLiteralExpression(args[0])) {
       frags.push({ examples: args[0].elements.map((e) => literalToJson(e)) });
     } else if (name === "Description" && isStringLiteral(args[0])) {
       frags.push({ description: args[0].text });
-    } else if (name === "Enum" && import_typescript4.default.isArrayLiteralExpression(args[0])) {
+    } else if (name === "Enum" && import_typescript8.default.isArrayLiteralExpression(args[0])) {
       frags.push({ enum: args[0].elements.map((e) => literalToJson(e)) });
     } else if (name === "Const") {
       frags.push({ const: literalToJson(args[0]) });
@@ -847,9 +1091,9 @@ function extractPropertySchemaFragments(checker, prop) {
       frags.push({ default: literalToJson(args[0]) });
     } else if (name === "AdditionalProperties") {
       const arg = args[0];
-      if (arg && (arg.kind === import_typescript4.default.SyntaxKind.FalseKeyword || arg.kind === import_typescript4.default.SyntaxKind.TrueKeyword)) {
-        frags.push({ additionalProperties: arg.kind === import_typescript4.default.SyntaxKind.TrueKeyword });
-      } else if (arg && import_typescript4.default.isObjectLiteralExpression(arg)) {
+      if (arg && (arg.kind === import_typescript8.default.SyntaxKind.FalseKeyword || arg.kind === import_typescript8.default.SyntaxKind.TrueKeyword)) {
+        frags.push({ additionalProperties: arg.kind === import_typescript8.default.SyntaxKind.TrueKeyword });
+      } else if (arg && import_typescript8.default.isObjectLiteralExpression(arg)) {
         const obj = objectLiteralToJson(arg);
         if (obj) frags.push({ additionalProperties: obj });
       }
@@ -862,7 +1106,7 @@ function extractPropertySchemaFragments(checker, prop) {
   return frags;
 }
 function resolveImportedDecorator(checker, sym) {
-  const target = sym.flags & import_typescript4.default.SymbolFlags.Alias ? checker.getAliasedSymbol(sym) : sym;
+  const target = sym.flags & import_typescript8.default.SymbolFlags.Alias ? checker.getAliasedSymbol(sym) : sym;
   const name = target.getName();
   const decl = target.declarations?.[0];
   if (!decl) return null;
@@ -873,10 +1117,10 @@ function resolveImportedDecorator(checker, sym) {
   return null;
 }
 function isNumberLiteral(node) {
-  return !!node && import_typescript4.default.isNumericLiteral(node);
+  return !!node && import_typescript8.default.isNumericLiteral(node);
 }
 function isStringLiteral(node) {
-  return !!node && import_typescript4.default.isStringLiteral(node);
+  return !!node && import_typescript8.default.isStringLiteral(node);
 }
 function extractRegexPattern(text) {
   const match = text.match(/^\/(.+)\/[gimsuy]*$/);
@@ -885,12 +1129,12 @@ function extractRegexPattern(text) {
 function objectLiteralToJson(obj) {
   const out = {};
   for (const prop of obj.properties) {
-    if (!import_typescript4.default.isPropertyAssignment(prop)) continue;
+    if (!import_typescript8.default.isPropertyAssignment(prop)) continue;
     const name = prop.name;
     let key;
-    if (import_typescript4.default.isIdentifier(name)) {
+    if (import_typescript8.default.isIdentifier(name)) {
       key = name.text;
-    } else if (import_typescript4.default.isStringLiteral(name)) {
+    } else if (import_typescript8.default.isStringLiteral(name)) {
       key = name.text;
     } else {
       continue;
@@ -900,13 +1144,13 @@ function objectLiteralToJson(obj) {
   return out;
 }
 function literalToJson(node) {
-  if (import_typescript4.default.isStringLiteral(node)) return node.text;
-  if (import_typescript4.default.isNumericLiteral(node)) return Number(node.text);
-  if (node.kind === import_typescript4.default.SyntaxKind.TrueKeyword) return true;
-  if (node.kind === import_typescript4.default.SyntaxKind.FalseKeyword) return false;
-  if (node.kind === import_typescript4.default.SyntaxKind.NullKeyword) return null;
-  if (import_typescript4.default.isObjectLiteralExpression(node)) return objectLiteralToJson(node);
-  if (import_typescript4.default.isArrayLiteralExpression(node)) return node.elements.map((e) => literalToJson(e));
+  if (import_typescript8.default.isStringLiteral(node)) return node.text;
+  if (import_typescript8.default.isNumericLiteral(node)) return Number(node.text);
+  if (node.kind === import_typescript8.default.SyntaxKind.TrueKeyword) return true;
+  if (node.kind === import_typescript8.default.SyntaxKind.FalseKeyword) return false;
+  if (node.kind === import_typescript8.default.SyntaxKind.NullKeyword) return null;
+  if (import_typescript8.default.isObjectLiteralExpression(node)) return objectLiteralToJson(node);
+  if (import_typescript8.default.isArrayLiteralExpression(node)) return node.elements.map((e) => literalToJson(e));
   return void 0;
 }
 function mergeFragments(base, ...frags) {
@@ -917,120 +1161,7 @@ function mergeFragments(base, ...frags) {
   return result;
 }
 
-// src/compiler/schema/openapi.ts
-function generateOpenAPI(controllers, checker, options = {}) {
-  const components = /* @__PURE__ */ new Map();
-  const ctx = {
-    checker,
-    components,
-    typeStack: /* @__PURE__ */ new Set(),
-    typeNameStack: [],
-    mode: "response"
-  };
-  const paths = {};
-  for (const controller of controllers) {
-    for (const operation of controller.operations) {
-      const fullPath = convertToOpenApiPath(controller.basePath, operation.path);
-      if (!paths[fullPath]) {
-        paths[fullPath] = {};
-      }
-      const method = operation.httpMethod.toLowerCase();
-      paths[fullPath][method] = buildOperation(operation, ctx, controller.consumes);
-    }
-  }
-  return {
-    openapi: "3.1.0",
-    info: {
-      title: options.title ?? "API",
-      version: options.version ?? "1.0.0"
-    },
-    components: {
-      schemas: Object.fromEntries(components)
-    },
-    paths
-  };
-}
-function convertToOpenApiPath(basePath, path4) {
-  const base = basePath.endsWith("/") ? basePath.slice(0, -1) : basePath;
-  const converted = path4.replace(/:([^/]+)/g, "{$1}");
-  let fullPath = base + converted || "/";
-  if (fullPath.endsWith("/") && fullPath !== "/") {
-    fullPath = fullPath.slice(0, -1);
-  }
-  return fullPath;
-}
-function buildOperation(operation, ctx, controllerConsumes) {
-  const op = {
-    operationId: operation.operationId,
-    responses: {}
-  };
-  const parameters = [];
-  buildPathParameters(operation, ctx, parameters);
-  buildQueryParameters(operation, ctx, parameters);
-  buildHeaderParameters(operation, ctx, parameters);
-  buildCookieParameters(operation, ctx, parameters);
-  if (parameters.length > 0) {
-    op.parameters = parameters;
-  }
-  const responseCtx = { ...ctx, mode: "response" };
-  const responseSchema = typeToJsonSchema(operation.returnType, responseCtx, operation.returnTypeNode);
-  const status = operation.httpMethod === "POST" ? 201 : 200;
-  op.responses[status] = {
-    description: status === 201 ? "Created" : "OK",
-    content: {
-      "application/json": {
-        schema: responseSchema
-      }
-    }
-  };
-  if (["POST", "PUT", "PATCH"].includes(operation.httpMethod) && operation.bodyParamIndex !== null) {
-    const bodyParam = operation.parameters[operation.bodyParamIndex];
-    if (bodyParam) {
-      const requestCtx = { ...ctx, mode: "request" };
-      let bodySchema = typeToJsonSchema(bodyParam.type, requestCtx);
-      bodySchema = mergeBodySchemaAnnotations(bodyParam, requestCtx, bodySchema);
-      const contentType = operation.bodyContentType ?? controllerConsumes?.[0] ?? "application/json";
-      const requestBody = {
-        required: !bodyParam.isOptional,
-        content: {}
-      };
-      if (contentType === "multipart/form-data") {
-        requestBody.content["multipart/form-data"] = {
-          schema: bodySchema
-        };
-      } else {
-        requestBody.content[contentType] = {
-          schema: bodySchema
-        };
-      }
-      op.requestBody = requestBody;
-    }
-  }
-  return op;
-}
-function mergeBodySchemaAnnotations(bodyParam, ctx, schema) {
-  if (!schema.properties) return schema;
-  const typeSymbol = bodyParam.type.getSymbol();
-  if (!typeSymbol) return schema;
-  const declarations = typeSymbol.getDeclarations();
-  if (!declarations || declarations.length === 0) return schema;
-  const classDecl = declarations[0];
-  if (!import_typescript5.default.isClassDeclaration(classDecl)) return schema;
-  const result = { ...schema };
-  const props = { ...result.properties };
-  for (const member of classDecl.members) {
-    if (!import_typescript5.default.isPropertyDeclaration(member) || !member.name) continue;
-    const propName = import_typescript5.default.isIdentifier(member.name) ? member.name.text : null;
-    if (!propName) continue;
-    if (!props[propName]) continue;
-    const frags = extractPropertySchemaFragments(ctx.checker, member);
-    if (frags.length > 0) {
-      props[propName] = mergeFragments(props[propName], ...frags);
-    }
-  }
-  result.properties = props;
-  return result;
-}
+// src/compiler/schema/parameters.ts
 function buildPathParameters(operation, ctx, parameters) {
   for (const paramIndex of operation.pathParamIndices) {
     const param = operation.parameters[paramIndex];
@@ -1043,71 +1174,22 @@ function buildPathParameters(operation, ctx, parameters) {
         }
       }
       const schema = paramSchema.$ref ? { $ref: paramSchema.$ref } : paramSchema;
-      parameters.push({
-        name: param.name,
-        in: "path",
-        required: !param.isOptional,
-        schema
-      });
-    }
-  }
-}
-function isObjectLikeSchema(schema, ctx) {
-  const resolved = resolveSchemaRef(schema, ctx.components);
-  if (resolved.type === "object" || resolved.properties || resolved.additionalProperties) {
-    return true;
-  }
-  if (resolved.allOf) {
-    for (const branch of resolved.allOf) {
-      if (isObjectLikeSchema(branch, ctx)) {
-        return true;
-      }
-    }
-  }
-  if (resolved.type === "array" && resolved.items) {
-    const itemsSchema = resolveSchemaRef(resolved.items, ctx.components);
-    return isObjectLikeSchema(itemsSchema, ctx);
-  }
-  return false;
-}
-function resolveSchemaRef(schema, components) {
-  const ref = schema.$ref;
-  if (typeof ref !== "string" || !ref.startsWith("#/components/schemas/")) {
-    return schema;
-  }
-  const name = ref.replace("#/components/schemas/", "");
-  const next = components.get(name);
-  if (!next) return schema;
-  return resolveSchemaRef(next, components);
-}
-function resolveAndCollectObjectProps(schema, components) {
-  const resolved = resolveSchemaRef(schema, components);
-  const properties = {};
-  const required = [];
-  const processSchema = (s) => {
-    const current = resolveSchemaRef(s, components);
-    if (current.properties) {
-      for (const [key, val] of Object.entries(current.properties)) {
-        if (!properties[key]) {
-          properties[key] = val;
-        }
-      }
-    }
-    if (current.required) {
-      for (const req of current.required) {
-        if (!required.includes(req)) {
-          required.push(req);
+      const paramName = param.name.toLowerCase();
+      const isIdParam = paramName === "id" || paramName.endsWith("id");
+      if (!schema.$ref && schema.type === "number" && isIdParam) {
+        schema.type = "integer";
+        if (!schema.minimum) {
+          schema.minimum = 1;
         }
       }
+      parameters.push({
+        name: param.name,
+        in: "path",
+        required: !param.isOptional,
+        schema
+      });
     }
-    if (current.allOf) {
-      for (const branch of current.allOf) {
-        processSchema(branch);
-      }
-    }
-  };
-  processSchema(resolved);
-  return { properties, required };
+  }
 }
 function buildQueryParameters(operation, ctx, parameters) {
   if (operation.queryObjectParamIndex !== null) {
@@ -1116,20 +1198,22 @@ function buildQueryParameters(operation, ctx, parameters) {
     const querySchema = typeToJsonSchema(queryParam.type, ctx);
     const { properties: queryObjProps, required: queryRequired } = resolveAndCollectObjectProps(querySchema, ctx.components);
     for (const [propName, propSchema] of Object.entries(queryObjProps)) {
-      const isRequired = queryRequired.includes(propName) ?? false;
+      const isRequired = queryRequired.includes(propName);
       const isObjectLike = isObjectLikeSchema(propSchema, ctx);
       const serialization = determineQuerySerialization(propSchema.type);
+      const exampleValue = generateExampleValue(propSchema, propName);
       if (isObjectLike) {
+        const schemaRef = propSchema.$ref || "#/components/schemas/InlineQueryParam";
         parameters.push({
           name: propName,
           in: "query",
           required: isRequired,
-          content: {
-            "application/json": {
-              schema: propSchema.$ref ? { $ref: propSchema.$ref } : propSchema
-            }
+          schema: { type: "string" },
+          description: `JSON-encoded object. ${exampleValue}`,
+          examples: {
+            default: { value: parseExampleValue(exampleValue) }
           },
-          description: `URL-encoded JSON. Example: ${propName}=${encodeURIComponent(JSON.stringify({ example: "value" }))}`
+          "x-adorn-jsonSchemaRef": schemaRef
         });
       } else {
         const paramDef = {
@@ -1175,15 +1259,18 @@ function buildQueryParameters(operation, ctx, parameters) {
       }
       const isObjectLike = isObjectLikeSchema(paramSchema, ctx);
       if (isObjectLike) {
+        const schemaRef = paramSchema.$ref || "#/components/schemas/InlineQueryParam";
+        const exampleValue = generateExampleValue(paramSchema, param.name);
         parameters.push({
           name: param.name,
           in: "query",
           required: !param.isOptional,
-          content: {
-            "application/json": {
-              schema: paramSchema.$ref ? { $ref: paramSchema.$ref } : paramSchema
-            }
-          }
+          schema: { type: "string" },
+          description: `JSON-encoded object. ${exampleValue}`,
+          examples: {
+            default: { value: parseExampleValue(exampleValue) }
+          },
+          "x-adorn-jsonSchemaRef": schemaRef
         });
       } else {
         const serialization = determineQuerySerialization(paramSchema.type);
@@ -1198,14 +1285,6 @@ function buildQueryParameters(operation, ctx, parameters) {
     }
   }
 }
-function determineQuerySerialization(schemaType) {
-  const typeArray = Array.isArray(schemaType) ? schemaType : schemaType ? [schemaType] : [];
-  const isArray = typeArray.includes("array");
-  if (isArray) {
-    return { style: "form", explode: true };
-  }
-  return {};
-}
 function buildHeaderParameters(operation, ctx, parameters) {
   if (operation.headerObjectParamIndex === null) return;
   const headerParam = operation.parameters[operation.headerObjectParamIndex];
@@ -1242,9 +1321,324 @@ function buildCookieParameters(operation, ctx, parameters) {
     });
   }
 }
+function determineQuerySerialization(schemaType) {
+  const typeArray = Array.isArray(schemaType) ? schemaType : schemaType ? [schemaType] : [];
+  const isArray = typeArray.includes("array");
+  if (isArray) {
+    return { style: "form", explode: true };
+  }
+  return {};
+}
+function generateExampleValue(schema, propName) {
+  const resolved = resolveSchemaRef(schema, /* @__PURE__ */ new Map());
+  if (resolved.type === "object" && resolved.properties) {
+    const example = {};
+    for (const [key, prop] of Object.entries(resolved.properties)) {
+      const propResolved = resolveSchemaRef(prop, /* @__PURE__ */ new Map());
+      if (propResolved.type === "string") {
+        example[key] = "value";
+      } else if (propResolved.type === "number" || propResolved.type === "integer") {
+        example[key] = 1;
+      } else if (propResolved.type === "boolean") {
+        example[key] = true;
+      } else if (Array.isArray(propResolved.type) && propResolved.type.includes("null")) {
+        example[key] = null;
+      } else if (propResolved.enum) {
+        example[key] = propResolved.enum[0];
+      } else {
+        example[key] = "value";
+      }
+    }
+    return `Example: ${propName}=${JSON.stringify(example)}`;
+  }
+  return `Example: ${propName}=${JSON.stringify({ key: "value" })}`;
+}
+function parseExampleValue(description) {
+  const match = description.match(/Example:\s*\w+=(\{[^}]+\})/);
+  if (match) {
+    return match[1];
+  }
+  return JSON.stringify({ key: "value" });
+}
+function isObjectLikeSchema(schema, ctx) {
+  const resolved = resolveSchemaRef(schema, ctx.components);
+  if (resolved.type === "object" || resolved.properties || resolved.additionalProperties) {
+    return true;
+  }
+  if (resolved.allOf) {
+    for (const branch of resolved.allOf) {
+      if (isObjectLikeSchema(branch, ctx)) {
+        return true;
+      }
+    }
+  }
+  if (resolved.type === "array" && resolved.items) {
+    const itemsSchema = resolveSchemaRef(resolved.items, ctx.components);
+    return isObjectLikeSchema(itemsSchema, ctx);
+  }
+  return false;
+}
+function resolveSchemaRef(schema, components) {
+  const ref = schema.$ref;
+  if (typeof ref !== "string" || !ref.startsWith("#/components/schemas/")) {
+    return schema;
+  }
+  const name = ref.replace("#/components/schemas/", "");
+  const next = components.get(name);
+  if (!next) return schema;
+  return resolveSchemaRef(next, components);
+}
+function resolveAndCollectObjectProps(schema, components) {
+  const resolved = resolveSchemaRef(schema, components);
+  const properties = {};
+  const required = [];
+  const processSchema = (s) => {
+    const current = resolveSchemaRef(s, components);
+    if (current.properties) {
+      for (const [key, val] of Object.entries(current.properties)) {
+        if (!properties[key]) {
+          properties[key] = val;
+        }
+      }
+    }
+    if (current.required) {
+      for (const req of current.required) {
+        if (!required.includes(req)) {
+          required.push(req);
+        }
+      }
+    }
+    if (current.allOf) {
+      for (const branch of current.allOf) {
+        processSchema(branch);
+      }
+    }
+  };
+  processSchema(resolved);
+  return { properties, required };
+}
+
+// src/compiler/schema/openapi.ts
+var METAL_ORM_WRAPPER_NAMES2 = ["BelongsToReference", "HasOneReference", "HasManyCollection", "ManyToManyCollection"];
+function generateOpenAPI(controllers, checker, options = {}) {
+  const components = /* @__PURE__ */ new Map();
+  const ctx = {
+    checker,
+    components,
+    typeStack: /* @__PURE__ */ new Set(),
+    typeNameStack: [],
+    mode: "response"
+  };
+  const paths = {};
+  for (const controller of controllers) {
+    for (const operation of controller.operations) {
+      const fullPath = convertToOpenApiPath(controller.basePath, operation.path);
+      if (!paths[fullPath]) {
+        paths[fullPath] = {};
+      }
+      const method = operation.httpMethod.toLowerCase();
+      paths[fullPath][method] = buildOperation(operation, ctx, controller.consumes);
+    }
+  }
+  const schemas = Object.fromEntries(components);
+  cleanupMetalOrmWrappers(schemas, paths);
+  return {
+    openapi: "3.1.0",
+    info: {
+      title: options.title ?? "API",
+      version: options.version ?? "1.0.0"
+    },
+    components: {
+      schemas
+    },
+    paths
+  };
+}
+function cleanupMetalOrmWrappers(schemas, paths) {
+  const schemasToDelete = /* @__PURE__ */ new Set();
+  for (const wrapperName of METAL_ORM_WRAPPER_NAMES2) {
+    if (schemas[wrapperName]) {
+      schemasToDelete.add(wrapperName);
+    }
+    if (schemas[`${wrapperName}Api`]) {
+      schemasToDelete.add(`${wrapperName}Api`);
+    }
+  }
+  for (const schema of Object.values(schemas)) {
+    cleanupSchemaRefs(schema, schemasToDelete);
+  }
+  for (const pathItem of Object.values(paths)) {
+    cleanupPathItemRefs(pathItem, schemasToDelete);
+  }
+  for (const schemaName of schemasToDelete) {
+    delete schemas[schemaName];
+  }
+}
+function cleanupSchemaRefs(schema, schemasToDelete) {
+  if (typeof schema !== "object" || schema === null) {
+    return;
+  }
+  if (schema.properties) {
+    for (const propName of Object.keys(schema.properties)) {
+      const propSchema = schema.properties[propName];
+      if (propSchema.$ref && typeof propSchema.$ref === "string") {
+        const refName = propSchema.$ref.replace("#/components/schemas/", "");
+        if (schemasToDelete.has(refName)) {
+          delete schema.properties[propName];
+          if (schema.required && Array.isArray(schema.required)) {
+            schema.required = schema.required.filter((r) => r !== propName);
+          }
+        }
+      } else {
+        cleanupSchemaRefs(propSchema, schemasToDelete);
+      }
+    }
+  }
+  if (schema.items) {
+    cleanupSchemaRefs(schema.items, schemasToDelete);
+  }
+  if (schema.allOf) {
+    for (const item of schema.allOf) {
+      cleanupSchemaRefs(item, schemasToDelete);
+    }
+  }
+}
+function cleanupPathItemRefs(pathItem, schemasToDelete) {
+  if (typeof pathItem !== "object" || pathItem === null) {
+    return;
+  }
+  for (const method of Object.keys(pathItem)) {
+    const operation = pathItem[method];
+    if (typeof operation !== "object" || operation === null) continue;
+    if (operation.requestBody) {
+      cleanupRequestBodyRefs(operation.requestBody, schemasToDelete);
+    }
+    if (operation.responses) {
+      const responses = Object.values(operation.responses);
+      for (const response of responses) {
+        if (response.content) {
+          const contentTypes = Object.values(response.content);
+          for (const contentType of contentTypes) {
+            if (contentType.schema) {
+              cleanupSchemaRefs(contentType.schema, schemasToDelete);
+            }
+          }
+        }
+      }
+    }
+  }
+}
+function cleanupRequestBodyRefs(requestBody, schemasToDelete) {
+  if (typeof requestBody !== "object" || requestBody === null) return;
+  if (requestBody.content) {
+    const contentTypes = Object.values(requestBody.content);
+    for (const contentType of contentTypes) {
+      if (contentType.schema) {
+        cleanupSchemaRefs(contentType.schema, schemasToDelete);
+      }
+    }
+  }
+  if (requestBody.properties) {
+    for (const propName of Object.keys(requestBody.properties)) {
+      const propSchema = requestBody.properties[propName];
+      if (propSchema.$ref && typeof propSchema.$ref === "string") {
+        const refName = propSchema.$ref.replace("#/components/schemas/", "");
+        if (schemasToDelete.has(refName)) {
+          delete requestBody.properties[propName];
+          if (requestBody.required && Array.isArray(requestBody.required)) {
+            requestBody.required = requestBody.required.filter((r) => r !== propName);
+          }
+        }
+      } else {
+        cleanupSchemaRefs(propSchema, schemasToDelete);
+      }
+    }
+  }
+}
+function convertToOpenApiPath(basePath, path4) {
+  const base = basePath.endsWith("/") ? basePath.slice(0, -1) : basePath;
+  const converted = path4.replace(/:([^/]+)/g, "{$1}");
+  let fullPath = base + converted || "/";
+  if (fullPath.endsWith("/") && fullPath !== "/") {
+    fullPath = fullPath.slice(0, -1);
+  }
+  return fullPath;
+}
+function buildOperation(operation, ctx, controllerConsumes) {
+  const op = {
+    operationId: operation.operationId,
+    responses: {}
+  };
+  const parameters = [];
+  buildPathParameters(operation, ctx, parameters);
+  buildQueryParameters(operation, ctx, parameters);
+  buildHeaderParameters(operation, ctx, parameters);
+  buildCookieParameters(operation, ctx, parameters);
+  if (parameters.length > 0) {
+    op.parameters = parameters;
+  }
+  const responseCtx = { ...ctx, mode: "response" };
+  const responseSchema = typeToJsonSchema(operation.returnType, responseCtx, operation.returnTypeNode);
+  const status = operation.httpMethod === "POST" ? 201 : 200;
+  op.responses[status] = {
+    description: status === 201 ? "Created" : "OK",
+    content: {
+      "application/json": {
+        schema: responseSchema
+      }
+    }
+  };
+  if (["POST", "PUT", "PATCH"].includes(operation.httpMethod) && operation.bodyParamIndex !== null) {
+    const bodyParam = operation.parameters[operation.bodyParamIndex];
+    if (bodyParam) {
+      const requestCtx = { ...ctx, mode: "request" };
+      let bodySchema = typeToJsonSchema(bodyParam.type, requestCtx);
+      bodySchema = mergeBodySchemaAnnotations(bodyParam, requestCtx, bodySchema);
+      const contentType = operation.bodyContentType ?? controllerConsumes?.[0] ?? "application/json";
+      const requestBody = {
+        required: !bodyParam.isOptional,
+        content: {}
+      };
+      if (contentType === "multipart/form-data") {
+        requestBody.content["multipart/form-data"] = {
+          schema: bodySchema
+        };
+      } else {
+        requestBody.content[contentType] = {
+          schema: bodySchema
+        };
+      }
+      op.requestBody = requestBody;
+    }
+  }
+  return op;
+}
+function mergeBodySchemaAnnotations(bodyParam, ctx, schema) {
+  if (!schema.properties) return schema;
+  const typeSymbol = bodyParam.type.getSymbol();
+  if (!typeSymbol) return schema;
+  const declarations = typeSymbol.getDeclarations();
+  if (!declarations || declarations.length === 0) return schema;
+  const classDecl = declarations[0];
+  if (!import_typescript9.default.isClassDeclaration(classDecl)) return schema;
+  const result = { ...schema };
+  const props = { ...result.properties };
+  for (const member of classDecl.members) {
+    if (!import_typescript9.default.isPropertyDeclaration(member) || !member.name) continue;
+    const propName = import_typescript9.default.isIdentifier(member.name) ? member.name.text : null;
+    if (!propName) continue;
+    if (!props[propName]) continue;
+    const frags = extractPropertySchemaFragments(ctx.checker, member);
+    if (frags.length > 0) {
+      props[propName] = mergeFragments(props[propName], ...frags);
+    }
+  }
+  result.properties = props;
+  return result;
+}
 
 // src/compiler/manifest/emit.ts
-var import_typescript6 = __toESM(require("typescript"), 1);
+var import_typescript10 = __toESM(require("typescript"), 1);
 function generateManifest(controllers, checker, version, validationMode = "ajv-runtime") {
   const components = /* @__PURE__ */ new Map();
   const ctx = {
@@ -1266,7 +1660,7 @@ function generateManifest(controllers, checker, version, validationMode = "ajv-r
     generator: {
       name: "adorn-api",
       version,
-      typescript: import_typescript6.default.version
+      typescript: import_typescript10.default.version
     },
     schemas: {
       kind: "openapi-3.1",
@@ -1420,7 +1814,7 @@ function buildQueryArgs(op, ctx, args) {
       args.query.push({
         name: propName,
         index: queryParam.index,
-        required: !isRequired,
+        required: isRequired,
         schemaRef,
         schemaType: propSchema.type,
         content: isObjectLike ? "application/json" : void 0
@@ -1459,7 +1853,7 @@ function buildHeaderArgs(op, ctx, args) {
     args.headers.push({
       name: propName,
       index: headerParam.index,
-      required: !isRequired,
+      required: isRequired,
       schemaRef,
       schemaType: propSchema.type
     });
@@ -1480,7 +1874,7 @@ function buildCookieArgs(op, ctx, args) {
     args.cookies.push({
       name: propName,
       index: cookieParam.index,
-      required: !isRequired,
+      required: isRequired,
       schemaRef,
       schemaType: propSchema.type,
       serialization: { style: "form", explode: true }
@@ -1496,7 +1890,7 @@ var import_ajv = __toESM(require("ajv"), 1);
 var import_ajv_formats = __toESM(require("ajv-formats"), 1);
 var OAS_SCHEMA_ONLY = /* @__PURE__ */ new Set(["discriminator", "xml", "externalDocs", "example"]);
 function sanitizeSchemaForAjv(schema) {
-  if (schema == null || typeof schema !== "object") return schema;
+  if (schema === null || typeof schema !== "object") return schema;
   if (Array.isArray(schema)) return schema.map(sanitizeSchemaForAjv);
   const out = {};
   for (const [k, v] of Object.entries(schema)) {
@@ -1507,7 +1901,7 @@ function sanitizeSchemaForAjv(schema) {
   return out;
 }
 function rewriteComponentRefs(schema) {
-  if (schema == null || typeof schema !== "object") return schema;
+  if (schema === null || typeof schema !== "object") return schema;
   if (Array.isArray(schema)) return schema.map(rewriteComponentRefs);
   if (typeof schema.$ref === "string") {
     const ref = schema.$ref;
@@ -1584,16 +1978,13 @@ async function emitPrecompiledValidators(opts) {
 `;
     cjs += `    body: ${v.body ? `exports[${JSON.stringify(v.body)}]` : "undefined"},
 `;
-    cjs += `    response: {
-`;
+    cjs += "    response: {\n";
     for (const [key, id] of Object.entries(v.response)) {
       cjs += `      ${JSON.stringify(key)}: exports[${JSON.stringify(id)}],
 `;
     }
-    cjs += `    }
-`;
-    cjs += `  },
-`;
+    cjs += "    }\n";
+    cjs += "  },\n";
   }
   cjs += "};\n";
   import_node_fs2.default.writeFileSync(cjsPath, cjs, "utf8");
@@ -1628,7 +2019,6 @@ export function validateResponse(operationId, status, contentType, data) {
 // src/compiler/cache/isStale.ts
 var import_node_fs3 = __toESM(require("fs"), 1);
 var import_node_path3 = __toESM(require("path"), 1);
-var import_typescript7 = require("typescript");
 var import_meta = {};
 function readJson(p) {
   try {
@@ -1686,7 +2076,7 @@ function findLockfile(startDir) {
     for (const n of names) {
       const p = import_node_path3.default.join(dir, n);
       const mt = statMtimeMs(p);
-      if (mt != null) return { path: p, mtimeMs: mt };
+      if (mt !== null) return { path: p, mtimeMs: mt };
     }
     const parent = import_node_path3.default.dirname(dir);
     if (parent === dir) break;
@@ -1711,22 +2101,22 @@ async function isStale(params) {
   const chain = collectTsconfigChain(tsconfigAbs);
   for (const cfg of chain) {
     const mt = statMtimeMs(cfg);
-    if (mt == null) return { stale: true, reason: "config-missing", detail: cfg };
+    if (mt === null) return { stale: true, reason: "config-missing", detail: cfg };
     const cachedMt = cache.project.configFiles[cfg];
-    if (cachedMt == null || Math.abs(cachedMt - mt) > 1e-4) {
+    if (cachedMt === null || Math.abs(cachedMt - mt) > 1e-4) {
       return { stale: true, reason: "config-updated", detail: cfg };
     }
   }
   if (cache.project.lockfile?.path) {
     const mt = statMtimeMs(cache.project.lockfile.path);
-    if (mt == null) return { stale: true, reason: "lockfile-missing", detail: cache.project.lockfile.path };
+    if (mt === null) return { stale: true, reason: "lockfile-missing", detail: cache.project.lockfile.path };
     if (Math.abs(cache.project.lockfile.mtimeMs - mt) > 1e-4) {
       return { stale: true, reason: "lockfile-updated", detail: cache.project.lockfile.path };
     }
   }
   for (const [file, cachedMt] of Object.entries(cache.inputs)) {
     const mt = statMtimeMs(file);
-    if (mt == null) return { stale: true, reason: "input-missing", detail: file };
+    if (mt === null) return { stale: true, reason: "input-missing", detail: file };
     if (Math.abs(cachedMt - mt) > 1e-4) return { stale: true, reason: "input-updated", detail: file };
   }
   return { stale: false, reason: "up-to-date" };
@@ -1735,7 +2125,7 @@ async function isStale(params) {
 // src/compiler/cache/writeCache.ts
 var import_node_fs4 = __toESM(require("fs"), 1);
 var import_node_path4 = __toESM(require("path"), 1);
-var import_typescript8 = __toESM(require("typescript"), 1);
+var import_typescript11 = __toESM(require("typescript"), 1);
 function statMtimeMs2(p) {
   return import_node_fs4.default.statSync(p).mtimeMs;
 }
@@ -1768,7 +2158,7 @@ function writeCache(params) {
     generator: {
       name: "adorn-api",
       version: params.adornVersion,
-      typescript: import_typescript8.default.version
+      typescript: import_typescript11.default.version
     },
     project: {
       tsconfigPath: params.tsconfigAbs,
@@ -1781,7 +2171,7 @@ function writeCache(params) {
 }
 
 // src/cli.ts
-var import_typescript9 = __toESM(require("typescript"), 1);
+var import_typescript12 = __toESM(require("typescript"), 1);
 var import_node_process = __toESM(require("process"), 1);
 var ADORN_VERSION = "0.1.0";
 function log(msg) {
@@ -1829,7 +2219,7 @@ async function buildCommand(args) {
       outDir: outputDir,
       project: projectPath,
       adornVersion: ADORN_VERSION,
-      typescriptVersion: import_typescript9.default.version
+      typescriptVersion: import_typescript12.default.version
     });
     if (!stale.stale) {
       log("adorn-api: artifacts up-to-date");