adorn-api 1.0.12 → 1.0.14

package/dist/cli.js

@@ -86,7 +86,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;
@@ -102,7 +102,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;
@@ -284,7 +284,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;
@@ -305,12 +305,15 @@ function unwrapPromiseTypeNode(typeNode) {
 }
 
 // src/compiler/schema/openapi.ts
-import ts5 from "typescript";
+import ts9 from "typescript";
 
 // src/compiler/schema/typeToJsonSchema.ts
+import ts7 from "typescript";
+
+// src/compiler/schema/primitives.ts
 import ts3 from "typescript";
-function typeToJsonSchema(type, ctx, typeNode) {
-  const { checker } = ctx;
+function handlePrimitiveType(type, ctx, typeNode) {
+  const { checker, propertyName } = ctx;
   if (type.flags & ts3.TypeFlags.Undefined) {
     return {};
   }
@@ -324,7 +327,7 @@ function typeToJsonSchema(type, ctx, typeNode) {
     return { type: "string" };
   }
   if (type.flags & ts3.TypeFlags.Number) {
-    return normalizeNumericType(type, checker, typeNode);
+    return normalizeNumericType(type, checker, typeNode, propertyName);
   }
   if (type.flags & ts3.TypeFlags.Boolean) {
     return { type: "boolean" };
@@ -348,26 +351,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 & ts3.TypeFlags.Object) {
-    return handleObjectType(type, ctx, typeNode);
-  }
-  return {};
+  return null;
 }
 function isDateType(type, checker) {
   const symbol = type.getSymbol();
@@ -382,53 +366,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 (ts3.isTypeReferenceNode(typeNode)) {
+    if (ts3.isIdentifier(typeNode.typeName)) {
+      return typeNode.typeName.text;
+    }
   }
-  const nodeName = getExplicitTypeNameFromNode(typeNode);
-  if (nodeName && nodeName !== "__type") {
-    return nodeName;
+  if (ts3.isTypeAliasDeclaration(typeNode.parent)) {
+    if (ts3.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 & ts3.SymbolFlags.Alias) {
+    return checker.getAliasedSymbol(aliasSymbol);
   }
-  return { $ref: `#/components/schemas/${name}` };
+  return type.getSymbol() ?? null;
 }
+
+// src/compiler/schema/unionHandler.ts
+import ts4 from "typescript";
 function handleUnion(type, ctx, typeNode) {
   return buildNamedSchema(type, ctx, typeNode, () => {
     const types = type.types;
-    const nullType = types.find((t) => t.flags & ts3.TypeFlags.Null);
-    const otherTypes = types.filter((t) => !(t.flags & ts3.TypeFlags.Null) && !(t.flags & ts3.TypeFlags.Undefined));
-    const allStringLiterals = otherTypes.every((t) => t.flags & ts3.TypeFlags.StringLiteral);
+    const nullType = types.find((t) => t.flags & ts4.TypeFlags.Null);
+    const undefinedType = types.find((t) => t.flags & ts4.TypeFlags.Undefined);
+    const otherTypes = types.filter((t) => !(t.flags & ts4.TypeFlags.Null) && !(t.flags & ts4.TypeFlags.Undefined));
+    const allStringLiterals = otherTypes.every((t) => t.flags & ts4.TypeFlags.StringLiteral);
     if (allStringLiterals && otherTypes.length > 0) {
       const enumValues = otherTypes.map((t) => t.value);
       const schema = { type: "string", enum: enumValues };
@@ -437,6 +419,14 @@ function handleUnion(type, ctx, typeNode) {
       }
       return schema;
     }
+    const allBooleanLiterals = otherTypes.length > 0 && otherTypes.every((t) => t.flags & ts4.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") {
@@ -466,49 +456,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 & (ts3.TypeFlags.String | ts3.TypeFlags.Number | ts3.TypeFlags.Boolean | ts3.TypeFlags.BigInt)) !== 0 || (t.flags & ts3.TypeFlags.StringLiteral) !== 0 || (t.flags & ts3.TypeFlags.NumberLiteral) !== 0;
-}
-function isBrandObject(checker, t, ctx) {
-  if (!(t.flags & ts3.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) {
@@ -539,10 +487,10 @@ function findCommonPropertyNames(checker, types) {
 function isRequiredProperty(checker, type, propName) {
   const sym = checker.getPropertyOfType(type, propName);
   if (!sym) return false;
-  if (sym.flags & ts3.SymbolFlags.Optional) return false;
+  if (sym.flags & ts4.SymbolFlags.Optional) return false;
   const propType = checker.getTypeOfSymbol(sym);
   if (propType.isUnion?.()) {
-    const hasUndefined = propType.types.some((t) => (t.flags & ts3.TypeFlags.Undefined) !== 0);
+    const hasUndefined = propType.types.some((t) => (t.flags & ts4.TypeFlags.Undefined) !== 0);
     if (hasUndefined) return false;
   }
   return true;
@@ -585,16 +533,186 @@ 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 (ts4.isTypeReferenceNode(typeNode)) {
+    if (ts4.isIdentifier(typeNode.typeName)) {
+      return typeNode.typeName.text;
+    }
+  }
+  if (ts4.isTypeAliasDeclaration(typeNode.parent)) {
+    if (ts4.isIdentifier(typeNode.parent.name)) {
+      return typeNode.parent.name.text;
+    }
+  }
+  return null;
+}
+
+// src/compiler/schema/intersectionHandler.ts
+import ts5 from "typescript";
+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 & (ts5.TypeFlags.String | ts5.TypeFlags.Number | ts5.TypeFlags.Boolean | ts5.TypeFlags.BigInt)) !== 0 || (t.flags & ts5.TypeFlags.StringLiteral) !== 0 || (t.flags & ts5.TypeFlags.NumberLiteral) !== 0;
+}
+function isBrandObject(checker, t, _ctx) {
+  if (!(t.flags & ts5.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 (ts5.isTypeReferenceNode(typeNode)) {
+    if (ts5.isIdentifier(typeNode.typeName)) {
+      return typeNode.typeName.text;
+    }
+  }
+  if (ts5.isTypeAliasDeclaration(typeNode.parent)) {
+    if (ts5.isIdentifier(typeNode.parent.name)) {
+      return typeNode.parent.name.text;
+    }
+  }
+  return null;
+}
+
+// src/compiler/schema/objectHandler.ts
+import ts6 from "typescript";
 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") {
-    if (components.has(typeName)) {
-      return { $ref: `#/components/schemas/${typeName}` };
+    const isMetalOrmGeneric = METAL_ORM_WRAPPER_NAMES.some(
+      (name) => typeName === name || typeName.endsWith("Api")
+    );
+    if (isMetalOrmGeneric) {
+      return {};
     }
     if (typeStack.has(type)) {
       return { $ref: `#/components/schemas/${typeName}` };
@@ -607,46 +725,18 @@ function handleObjectType(type, ctx, typeNode) {
     const existing = components.get(typeName);
     if (!existing) {
       components.set(typeName, schema);
+    } else {
+      const merged = mergeSchemasIfNeeded(existing, schema);
+      if (merged !== existing) {
+        components.set(typeName, merged);
+      }
     }
     return { $ref: `#/components/schemas/${typeName}` };
   }
   typeStack.delete(type);
   return schema;
 }
-function getExplicitTypeNameFromNode(typeNode) {
-  if (!typeNode) return null;
-  if (ts3.isTypeReferenceNode(typeNode)) {
-    if (ts3.isIdentifier(typeNode.typeName)) {
-      return typeNode.typeName.text;
-    }
-  }
-  if (ts3.isTypeAliasDeclaration(typeNode.parent)) {
-    if (ts3.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 = [];
@@ -660,9 +750,10 @@ function buildObjectSchema(type, ctx, typeNode) {
     if (isMethodLike(propType)) {
       continue;
     }
-    const isOptional = !!(prop.flags & ts3.SymbolFlags.Optional);
+    const isOptional = !!(prop.flags & ts6.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);
@@ -683,14 +774,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();
@@ -703,24 +794,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 & ts3.SymbolFlags.Alias) {
-    return checker.getAliasedSymbol(aliasSymbol);
-  }
-  return type.getSymbol() ?? null;
+  return !!findMetalOrmWrapper(type, checker);
 }
 function isMethodLike(type) {
   const callSigs = type.getCallSignatures?.();
@@ -729,6 +804,159 @@ 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 (ts6.isTypeReferenceNode(typeNode)) {
+    if (ts6.isIdentifier(typeNode.typeName)) {
+      return typeNode.typeName.text;
+    }
+  }
+  if (ts6.isTypeAliasDeclaration(typeNode.parent)) {
+    if (ts6.isIdentifier(typeNode.parent.name)) {
+      return typeNode.parent.name.text;
+    }
+  }
+  return null;
+}
+function mergeSchemasIfNeeded(existing, newSchema) {
+  if (existing.type === "array" && newSchema.type === "array") {
+    return mergeArraySchemas(existing, newSchema);
+  }
+  const result = { ...existing };
+  for (const [key, newValue] of Object.entries(newSchema)) {
+    if (key === "properties" && newValue) {
+      result.properties = mergePropertiesIfNeeded(existing.properties || {}, newValue);
+    } else if (key === "required" && newValue) {
+      result.required = mergeRequiredFields(existing.required || [], newValue);
+    } else if (!deepEqual(existing[key], newValue)) {
+      result[key] = newValue;
+    }
+  }
+  return result;
+}
+function mergePropertiesIfNeeded(existing, newProps) {
+  const result = { ...existing };
+  for (const [propName, newPropSchema] of Object.entries(newProps)) {
+    const existingProp = existing[propName];
+    if (!existingProp) {
+      result[propName] = newPropSchema;
+    } else if (deepEqual(existingProp, newPropSchema)) {
+      continue;
+    } else {
+      result[propName] = mergePropertySchemas(existingProp, newPropSchema);
+    }
+  }
+  return result;
+}
+function mergePropertySchemas(schema1, schema2) {
+  if (deepEqual(schema1, schema2)) {
+    return schema1;
+  }
+  if (schema1.type === "array" && schema2.type === "array") {
+    return mergeArraySchemas(schema1, schema2);
+  }
+  const existingOneOf = schema1.oneOf || schema1.anyOf;
+  const newOneOf = schema2.oneOf || schema2.anyOf;
+  if (existingOneOf) {
+    const mergedOneOf = [...existingOneOf];
+    if (newOneOf) {
+      for (const newItem of newOneOf) {
+        if (!mergedOneOf.some((item) => deepEqual(item, newItem))) {
+          mergedOneOf.push(newItem);
+        }
+      }
+    } else if (!mergedOneOf.some((item) => deepEqual(item, schema2))) {
+      mergedOneOf.push(schema2);
+    }
+    return { ...schema1, oneOf: mergedOneOf };
+  }
+  return {
+    oneOf: [schema1, schema2]
+  };
+}
+function mergeArraySchemas(schema1, schema2) {
+  const result = { type: "array" };
+  if (schema1.uniqueItems || schema2.uniqueItems) {
+    result.uniqueItems = true;
+  }
+  if (schema1.items && schema2.items) {
+    result.items = mergePropertySchemas(schema1.items, schema2.items);
+  } else if (schema1.items) {
+    result.items = schema1.items;
+  } else if (schema2.items) {
+    result.items = schema2.items;
+  }
+  return result;
+}
+function mergeRequiredFields(existing, newFields) {
+  const merged = /* @__PURE__ */ new Set([...existing, ...newFields]);
+  return Array.from(merged);
+}
+function deepEqual(a, b) {
+  if (a === b) return true;
+  if (a == null || b == null) return false;
+  if (typeof a !== typeof b) return false;
+  if (typeof a === "object") {
+    const aKeys = Object.keys(a);
+    const bKeys = Object.keys(b);
+    if (aKeys.length !== bKeys.length) return false;
+    for (const key of aKeys) {
+      if (!bKeys.includes(key)) return false;
+      if (!deepEqual(a[key], b[key])) return false;
+    }
+    return true;
+  }
+  return false;
+}
+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 & ts6.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 & ts6.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;
@@ -736,7 +964,27 @@ function handleMetalOrmWrapper(type, ctx) {
   const wrapperName = getWrapperTypeName(type, ctx.checker);
   if (!wrapperName) return {};
   const wrapperRel = { wrapper: wrapperName };
+  if (!targetType) {
+    return { "x-metal-orm-rel": wrapperRel };
+  }
   if (wrapperName === "HasManyCollection" || wrapperName === "ManyToManyCollection") {
+    if (ctx.typeStack.has(targetType)) {
+      const items2 = {
+        type: "object",
+        properties: {
+          id: { type: "integer" }
+        },
+        required: ["id"]
+      };
+      if (wrapperName === "ManyToManyCollection" && typeArgs?.[1]) {
+        wrapperRel.pivot = typeArgs[1];
+      }
+      return {
+        type: "array",
+        items: items2,
+        "x-metal-orm-rel": wrapperRel
+      };
+    }
     const items = targetType ? typeToJsonSchema(targetType, ctx) : {};
     if (wrapperName === "ManyToManyCollection" && typeArgs?.[1]) {
       wrapperRel.pivot = typeArgs[1];
@@ -747,30 +995,149 @@ function handleMetalOrmWrapper(type, ctx) {
       "x-metal-orm-rel": wrapperRel
     };
   }
-  const targetSchema = targetType ? typeToJsonSchema(targetType, ctx) : {};
+  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, typeStack } = 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
+    };
+  }
+  if (typeStack.has(targetType)) {
+    const circularRefSchema = {
+      type: "object",
+      properties: {
+        id: { type: "integer" }
+      },
+      required: ["id"]
+    };
+    components.set(refSchemaName, circularRefSchema);
+    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 & ts6.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 & ts6.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 & ts7.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
-import ts4 from "typescript";
+import ts8 from "typescript";
 function extractPropertySchemaFragments(checker, prop) {
-  if (!ts4.canHaveDecorators(prop)) return [];
-  const decs = ts4.getDecorators(prop);
+  if (!ts8.canHaveDecorators(prop)) return [];
+  const decs = ts8.getDecorators(prop);
   if (!decs || decs.length === 0) return [];
   const frags = [];
   for (const d of decs) {
     const expr = d.expression;
     let callee;
     let args;
-    if (ts4.isCallExpression(expr)) {
+    if (ts8.isCallExpression(expr)) {
       callee = expr.expression;
       args = expr.arguments;
     } else {
       callee = expr;
-      args = ts4.factory.createNodeArray([]);
+      args = ts8.factory.createNodeArray([]);
     }
     const sym = checker.getSymbolAtLocation(callee);
     if (!sym) continue;
@@ -779,7 +1146,7 @@ function extractPropertySchemaFragments(checker, prop) {
     const name = resolved.name;
     if (name === "Schema") {
       const obj = args[0];
-      if (obj && ts4.isObjectLiteralExpression(obj)) {
+      if (obj && ts8.isObjectLiteralExpression(obj)) {
         const frag = objectLiteralToJson(obj);
         if (frag) frags.push(frag);
       }
@@ -801,7 +1168,7 @@ function extractPropertySchemaFragments(checker, prop) {
       frags.push({ format: args[0].text });
     } else if (name === "Pattern") {
       const arg = args[0];
-      if (arg && ts4.isRegularExpressionLiteral(arg)) {
+      if (arg && ts8.isRegularExpressionLiteral(arg)) {
         frags.push({ pattern: extractRegexPattern(arg.text) });
       } else if (isStringLiteral(arg)) {
         frags.push({ pattern: arg.text });
@@ -818,11 +1185,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" && ts4.isArrayLiteralExpression(args[0])) {
+    } else if (name === "Examples" && ts8.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" && ts4.isArrayLiteralExpression(args[0])) {
+    } else if (name === "Enum" && ts8.isArrayLiteralExpression(args[0])) {
       frags.push({ enum: args[0].elements.map((e) => literalToJson(e)) });
     } else if (name === "Const") {
       frags.push({ const: literalToJson(args[0]) });
@@ -830,9 +1197,9 @@ function extractPropertySchemaFragments(checker, prop) {
       frags.push({ default: literalToJson(args[0]) });
     } else if (name === "AdditionalProperties") {
       const arg = args[0];
-      if (arg && (arg.kind === ts4.SyntaxKind.FalseKeyword || arg.kind === ts4.SyntaxKind.TrueKeyword)) {
-        frags.push({ additionalProperties: arg.kind === ts4.SyntaxKind.TrueKeyword });
-      } else if (arg && ts4.isObjectLiteralExpression(arg)) {
+      if (arg && (arg.kind === ts8.SyntaxKind.FalseKeyword || arg.kind === ts8.SyntaxKind.TrueKeyword)) {
+        frags.push({ additionalProperties: arg.kind === ts8.SyntaxKind.TrueKeyword });
+      } else if (arg && ts8.isObjectLiteralExpression(arg)) {
         const obj = objectLiteralToJson(arg);
         if (obj) frags.push({ additionalProperties: obj });
       }
@@ -845,7 +1212,7 @@ function extractPropertySchemaFragments(checker, prop) {
   return frags;
 }
 function resolveImportedDecorator(checker, sym) {
-  const target = sym.flags & ts4.SymbolFlags.Alias ? checker.getAliasedSymbol(sym) : sym;
+  const target = sym.flags & ts8.SymbolFlags.Alias ? checker.getAliasedSymbol(sym) : sym;
   const name = target.getName();
   const decl = target.declarations?.[0];
   if (!decl) return null;
@@ -856,10 +1223,10 @@ function resolveImportedDecorator(checker, sym) {
   return null;
 }
 function isNumberLiteral(node) {
-  return !!node && ts4.isNumericLiteral(node);
+  return !!node && ts8.isNumericLiteral(node);
 }
 function isStringLiteral(node) {
-  return !!node && ts4.isStringLiteral(node);
+  return !!node && ts8.isStringLiteral(node);
 }
 function extractRegexPattern(text) {
   const match = text.match(/^\/(.+)\/[gimsuy]*$/);
@@ -868,12 +1235,12 @@ function extractRegexPattern(text) {
 function objectLiteralToJson(obj) {
   const out = {};
   for (const prop of obj.properties) {
-    if (!ts4.isPropertyAssignment(prop)) continue;
+    if (!ts8.isPropertyAssignment(prop)) continue;
     const name = prop.name;
     let key;
-    if (ts4.isIdentifier(name)) {
+    if (ts8.isIdentifier(name)) {
       key = name.text;
-    } else if (ts4.isStringLiteral(name)) {
+    } else if (ts8.isStringLiteral(name)) {
       key = name.text;
     } else {
       continue;
@@ -883,13 +1250,13 @@ function objectLiteralToJson(obj) {
   return out;
 }
 function literalToJson(node) {
-  if (ts4.isStringLiteral(node)) return node.text;
-  if (ts4.isNumericLiteral(node)) return Number(node.text);
-  if (node.kind === ts4.SyntaxKind.TrueKeyword) return true;
-  if (node.kind === ts4.SyntaxKind.FalseKeyword) return false;
-  if (node.kind === ts4.SyntaxKind.NullKeyword) return null;
-  if (ts4.isObjectLiteralExpression(node)) return objectLiteralToJson(node);
-  if (ts4.isArrayLiteralExpression(node)) return node.elements.map((e) => literalToJson(e));
+  if (ts8.isStringLiteral(node)) return node.text;
+  if (ts8.isNumericLiteral(node)) return Number(node.text);
+  if (node.kind === ts8.SyntaxKind.TrueKeyword) return true;
+  if (node.kind === ts8.SyntaxKind.FalseKeyword) return false;
+  if (node.kind === ts8.SyntaxKind.NullKeyword) return null;
+  if (ts8.isObjectLiteralExpression(node)) return objectLiteralToJson(node);
+  if (ts8.isArrayLiteralExpression(node)) return node.elements.map((e) => literalToJson(e));
   return void 0;
 }
 function mergeFragments(base, ...frags) {
@@ -900,7 +1267,302 @@ function mergeFragments(base, ...frags) {
   return result;
 }
 
+// src/compiler/schema/parameters.ts
+function buildPathParameters(operation, ctx, parameters) {
+  for (const paramIndex of operation.pathParamIndices) {
+    const param = operation.parameters[paramIndex];
+    if (param) {
+      let paramSchema = typeToJsonSchema(param.type, ctx);
+      if (param.paramNode) {
+        const frags = extractPropertySchemaFragments(ctx.checker, param.paramNode);
+        if (frags.length > 0) {
+          paramSchema = mergeFragments(paramSchema, ...frags);
+        }
+      }
+      const schema = paramSchema.$ref ? { $ref: paramSchema.$ref } : paramSchema;
+      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
+      });
+    }
+  }
+}
+function buildQueryParameters(operation, ctx, parameters) {
+  if (operation.queryObjectParamIndex !== null) {
+    const queryParam = operation.parameters[operation.queryObjectParamIndex];
+    if (!queryParam) return;
+    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);
+      const isDeepObject = isDeepObjectSchema(propSchema, ctx);
+      const isObjectLike = isObjectLikeSchema(propSchema, ctx);
+      const serialization = determineQuerySerialization(propSchema.type);
+      const exampleValue = generateExampleValue(propSchema, propName);
+      if (isDeepObject) {
+        parameters.push({
+          name: propName,
+          in: "query",
+          required: isRequired,
+          style: "deepObject",
+          explode: true,
+          schema: propSchema.$ref ? { $ref: propSchema.$ref } : propSchema
+        });
+      } else if (isObjectLike) {
+        const schemaRef = propSchema.$ref || "#/components/schemas/InlineQueryParam";
+        parameters.push({
+          name: propName,
+          in: "query",
+          required: isRequired,
+          schema: { type: "string" },
+          description: `JSON-encoded object. ${exampleValue}`,
+          examples: {
+            default: { value: parseExampleValue(exampleValue) }
+          },
+          "x-adorn-jsonSchemaRef": schemaRef
+        });
+      } else {
+        const paramDef = {
+          name: propName,
+          in: "query",
+          required: isRequired,
+          schema: propSchema.$ref ? { $ref: propSchema.$ref } : propSchema
+        };
+        if (propName === "page") {
+          paramDef.schema = { type: "integer", default: 1, minimum: 1 };
+        } else if (propName === "pageSize") {
+          paramDef.schema = { type: "integer", default: 10, minimum: 1 };
+        } else if (propName === "totalItems") {
+          paramDef.schema = { type: "integer", minimum: 0 };
+        } else if (propName === "sort") {
+          paramDef.schema = {
+            oneOf: [
+              { type: "string" },
+              { type: "array", items: { type: "string" } }
+            ]
+          };
+        } else if (propName === "q") {
+          paramDef.schema = { type: "string" };
+        } else if (propName === "hasComments") {
+          paramDef.schema = { type: "boolean" };
+        }
+        if (Object.keys(serialization).length > 0) {
+          Object.assign(paramDef, serialization);
+        }
+        parameters.push(paramDef);
+      }
+    }
+  }
+  for (const paramIndex of operation.queryParamIndices) {
+    const param = operation.parameters[paramIndex];
+    if (param) {
+      let paramSchema = typeToJsonSchema(param.type, ctx);
+      if (param.paramNode) {
+        const frags = extractPropertySchemaFragments(ctx.checker, param.paramNode);
+        if (frags.length > 0) {
+          paramSchema = mergeFragments(paramSchema, ...frags);
+        }
+      }
+      const isDeepObject = isDeepObjectSchema(paramSchema, ctx);
+      const isObjectLike = isObjectLikeSchema(paramSchema, ctx);
+      if (isDeepObject) {
+        parameters.push({
+          name: param.name,
+          in: "query",
+          required: !param.isOptional,
+          style: "deepObject",
+          explode: true,
+          schema: paramSchema.$ref ? { $ref: paramSchema.$ref } : paramSchema
+        });
+      } else 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,
+          schema: { type: "string" },
+          description: `JSON-encoded object. ${exampleValue}`,
+          examples: {
+            default: { value: parseExampleValue(exampleValue) }
+          },
+          "x-adorn-jsonSchemaRef": schemaRef
+        });
+      } else {
+        const serialization = determineQuerySerialization(paramSchema.type);
+        parameters.push({
+          name: param.name,
+          in: "query",
+          required: !param.isOptional,
+          schema: paramSchema.$ref ? { $ref: paramSchema.$ref } : paramSchema,
+          ...Object.keys(serialization).length > 0 ? serialization : {}
+        });
+      }
+    }
+  }
+}
+function buildHeaderParameters(operation, ctx, parameters) {
+  if (operation.headerObjectParamIndex === null) return;
+  const headerParam = operation.parameters[operation.headerObjectParamIndex];
+  if (!headerParam) return;
+  const headerSchema = typeToJsonSchema(headerParam.type, ctx);
+  if (!headerSchema.properties) return;
+  const headerObjProps = headerSchema.properties;
+  for (const [propName, propSchema] of Object.entries(headerObjProps)) {
+    const isRequired = headerSchema.required?.includes(propName) ?? false;
+    parameters.push({
+      name: propName,
+      in: "header",
+      required: isRequired,
+      schema: propSchema
+    });
+  }
+}
+function buildCookieParameters(operation, ctx, parameters) {
+  if (operation.cookieObjectParamIndex === null) return;
+  const cookieParam = operation.parameters[operation.cookieObjectParamIndex];
+  if (!cookieParam) return;
+  const cookieSchema = typeToJsonSchema(cookieParam.type, ctx);
+  if (!cookieSchema.properties) return;
+  const cookieObjProps = cookieSchema.properties;
+  for (const [propName, propSchema] of Object.entries(cookieObjProps)) {
+    const isRequired = cookieSchema.required?.includes(propName) ?? false;
+    parameters.push({
+      name: propName,
+      in: "cookie",
+      required: isRequired,
+      schema: propSchema,
+      style: "form",
+      explode: true
+    });
+  }
+}
+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 isDeepObjectSchema(schema, ctx) {
+  const resolved = resolveSchemaRef(schema, ctx.components);
+  if (resolved.type === "array") {
+    return false;
+  }
+  if (resolved.type === "object" || resolved.properties || resolved.additionalProperties) {
+    return true;
+  }
+  if (resolved.allOf) {
+    for (const branch of resolved.allOf) {
+      if (isDeepObjectSchema(branch, ctx)) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+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 = {
@@ -917,21 +1579,124 @@ function generateOpenAPI(controllers, checker, options = {}) {
       if (!paths[fullPath]) {
         paths[fullPath] = {};
       }
-      const method = operation.httpMethod.toLowerCase();
-      paths[fullPath][method] = buildOperation(operation, ctx, controller.consumes);
+      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);
+      }
     }
   }
-  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;
@@ -998,12 +1763,12 @@ function mergeBodySchemaAnnotations(bodyParam, ctx, schema) {
   const declarations = typeSymbol.getDeclarations();
   if (!declarations || declarations.length === 0) return schema;
   const classDecl = declarations[0];
-  if (!ts5.isClassDeclaration(classDecl)) return schema;
+  if (!ts9.isClassDeclaration(classDecl)) return schema;
   const result = { ...schema };
   const props = { ...result.properties };
   for (const member of classDecl.members) {
-    if (!ts5.isPropertyDeclaration(member) || !member.name) continue;
-    const propName = ts5.isIdentifier(member.name) ? member.name.text : null;
+    if (!ts9.isPropertyDeclaration(member) || !member.name) continue;
+    const propName = ts9.isIdentifier(member.name) ? member.name.text : null;
     if (!propName) continue;
     if (!props[propName]) continue;
     const frags = extractPropertySchemaFragments(ctx.checker, member);
@@ -1014,220 +1779,9 @@ function mergeBodySchemaAnnotations(bodyParam, ctx, schema) {
   result.properties = props;
   return result;
 }
-function buildPathParameters(operation, ctx, parameters) {
-  for (const paramIndex of operation.pathParamIndices) {
-    const param = operation.parameters[paramIndex];
-    if (param) {
-      let paramSchema = typeToJsonSchema(param.type, ctx);
-      if (param.paramNode) {
-        const frags = extractPropertySchemaFragments(ctx.checker, param.paramNode);
-        if (frags.length > 0) {
-          paramSchema = mergeFragments(paramSchema, ...frags);
-        }
-      }
-      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);
-        }
-      }
-    }
-    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) {
-    const queryParam = operation.parameters[operation.queryObjectParamIndex];
-    if (!queryParam) return;
-    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 isObjectLike = isObjectLikeSchema(propSchema, ctx);
-      const serialization = determineQuerySerialization(propSchema.type);
-      if (isObjectLike) {
-        parameters.push({
-          name: propName,
-          in: "query",
-          required: isRequired,
-          content: {
-            "application/json": {
-              schema: propSchema.$ref ? { $ref: propSchema.$ref } : propSchema
-            }
-          },
-          description: `URL-encoded JSON. Example: ${propName}=${encodeURIComponent(JSON.stringify({ example: "value" }))}`
-        });
-      } else {
-        const paramDef = {
-          name: propName,
-          in: "query",
-          required: isRequired,
-          schema: propSchema.$ref ? { $ref: propSchema.$ref } : propSchema
-        };
-        if (propName === "page") {
-          paramDef.schema = { type: "integer", default: 1, minimum: 1 };
-        } else if (propName === "pageSize") {
-          paramDef.schema = { type: "integer", default: 10, minimum: 1 };
-        } else if (propName === "totalItems") {
-          paramDef.schema = { type: "integer", minimum: 0 };
-        } else if (propName === "sort") {
-          paramDef.schema = {
-            oneOf: [
-              { type: "string" },
-              { type: "array", items: { type: "string" } }
-            ]
-          };
-        } else if (propName === "q") {
-          paramDef.schema = { type: "string" };
-        } else if (propName === "hasComments") {
-          paramDef.schema = { type: "boolean" };
-        }
-        if (Object.keys(serialization).length > 0) {
-          Object.assign(paramDef, serialization);
-        }
-        parameters.push(paramDef);
-      }
-    }
-  }
-  for (const paramIndex of operation.queryParamIndices) {
-    const param = operation.parameters[paramIndex];
-    if (param) {
-      let paramSchema = typeToJsonSchema(param.type, ctx);
-      if (param.paramNode) {
-        const frags = extractPropertySchemaFragments(ctx.checker, param.paramNode);
-        if (frags.length > 0) {
-          paramSchema = mergeFragments(paramSchema, ...frags);
-        }
-      }
-      const isObjectLike = isObjectLikeSchema(paramSchema, ctx);
-      if (isObjectLike) {
-        parameters.push({
-          name: param.name,
-          in: "query",
-          required: !param.isOptional,
-          content: {
-            "application/json": {
-              schema: paramSchema.$ref ? { $ref: paramSchema.$ref } : paramSchema
-            }
-          }
-        });
-      } else {
-        const serialization = determineQuerySerialization(paramSchema.type);
-        parameters.push({
-          name: param.name,
-          in: "query",
-          required: !param.isOptional,
-          schema: paramSchema.$ref ? { $ref: paramSchema.$ref } : paramSchema,
-          ...Object.keys(serialization).length > 0 ? serialization : {}
-        });
-      }
-    }
-  }
-}
-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];
-  if (!headerParam) return;
-  const headerSchema = typeToJsonSchema(headerParam.type, ctx);
-  if (!headerSchema.properties) return;
-  const headerObjProps = headerSchema.properties;
-  for (const [propName, propSchema] of Object.entries(headerObjProps)) {
-    const isRequired = headerSchema.required?.includes(propName) ?? false;
-    parameters.push({
-      name: propName,
-      in: "header",
-      required: isRequired,
-      schema: propSchema
-    });
-  }
-}
-function buildCookieParameters(operation, ctx, parameters) {
-  if (operation.cookieObjectParamIndex === null) return;
-  const cookieParam = operation.parameters[operation.cookieObjectParamIndex];
-  if (!cookieParam) return;
-  const cookieSchema = typeToJsonSchema(cookieParam.type, ctx);
-  if (!cookieSchema.properties) return;
-  const cookieObjProps = cookieSchema.properties;
-  for (const [propName, propSchema] of Object.entries(cookieObjProps)) {
-    const isRequired = cookieSchema.required?.includes(propName) ?? false;
-    parameters.push({
-      name: propName,
-      in: "cookie",
-      required: isRequired,
-      schema: propSchema,
-      style: "form",
-      explode: true
-    });
-  }
-}
 
 // src/compiler/manifest/emit.ts
-import ts6 from "typescript";
+import ts10 from "typescript";
 function generateManifest(controllers, checker, version, validationMode = "ajv-runtime") {
   const components = /* @__PURE__ */ new Map();
   const ctx = {
@@ -1249,7 +1803,7 @@ function generateManifest(controllers, checker, version, validationMode = "ajv-r
     generator: {
       name: "adorn-api",
       version,
-      typescript: ts6.version
+      typescript: ts10.version
     },
     schemas: {
       kind: "openapi-3.1",
@@ -1299,6 +1853,23 @@ function resolveAndCollectObjectProps2(schema, components) {
   processSchema(resolved);
   return { properties, required };
 }
+function isDeepObjectSchema2(schema, components) {
+  const resolved = resolveSchemaRef2(schema, components);
+  if (resolved.type === "array") {
+    return false;
+  }
+  if (resolved.type === "object" || resolved.properties || resolved.additionalProperties) {
+    return true;
+  }
+  if (resolved.allOf) {
+    for (const branch of resolved.allOf) {
+      if (isDeepObjectSchema2(branch, components)) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
 function isObjectLikeSchema2(schema, components) {
   const resolved = resolveSchemaRef2(schema, components);
   if (resolved.type === "object" || resolved.properties || resolved.additionalProperties) {
@@ -1395,6 +1966,7 @@ function buildQueryArgs(op, ctx, args) {
     const { properties: queryObjProps, required: queryRequired } = resolveAndCollectObjectProps2(querySchema, ctx.components);
     for (const [propName, propSchema] of Object.entries(queryObjProps)) {
       const isRequired = queryRequired.includes(propName) ?? false;
+      const isDeepObject = isDeepObjectSchema2(propSchema, ctx.components);
       const isObjectLike = isObjectLikeSchema2(propSchema, ctx.components);
       let schemaRef = propSchema.$ref;
       if (!schemaRef) {
@@ -1403,10 +1975,11 @@ 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
+        serialization: isDeepObject ? { style: "deepObject", explode: true } : void 0,
+        content: !isDeepObject && isObjectLike ? "application/json" : void 0
       });
     }
   }
@@ -1414,6 +1987,7 @@ function buildQueryArgs(op, ctx, args) {
     const param = op.parameters[paramIndex];
     if (param) {
       const paramSchema = typeToJsonSchema(param.type, ctx);
+      const isDeepObject = isDeepObjectSchema2(paramSchema, ctx.components);
       const isObjectLike = isObjectLikeSchema2(paramSchema, ctx.components);
       const schemaRef = paramSchema.$ref ?? "#/components/schemas/InlineQueryParam";
       args.query.push({
@@ -1422,7 +1996,8 @@ function buildQueryArgs(op, ctx, args) {
         required: !param.isOptional,
         schemaRef,
         schemaType: paramSchema.type,
-        content: isObjectLike ? "application/json" : void 0
+        serialization: isDeepObject ? { style: "deepObject", explode: true } : void 0,
+        content: !isDeepObject && isObjectLike ? "application/json" : void 0
       });
     }
   }
@@ -1442,7 +2017,7 @@ function buildHeaderArgs(op, ctx, args) {
     args.headers.push({
       name: propName,
       index: headerParam.index,
-      required: !isRequired,
+      required: isRequired,
       schemaRef,
       schemaType: propSchema.type
     });
@@ -1463,7 +2038,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 }
@@ -1479,7 +2054,7 @@ import Ajv from "ajv";
 import addFormats from "ajv-formats";
 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)) {
@@ -1490,7 +2065,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;
@@ -1567,16 +2142,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";
   fs.writeFileSync(cjsPath, cjs, "utf8");
@@ -1611,7 +2183,6 @@ export function validateResponse(operationId, status, contentType, data) {
 // src/compiler/cache/isStale.ts
 import fs2 from "fs";
 import path2 from "path";
-import "typescript";
 function readJson(p) {
   try {
     return JSON.parse(fs2.readFileSync(p, "utf8"));
@@ -1668,7 +2239,7 @@ function findLockfile(startDir) {
     for (const n of names) {
       const p = path2.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 = path2.dirname(dir);
     if (parent === dir) break;
@@ -1693,22 +2264,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" };
@@ -1717,7 +2288,7 @@ async function isStale(params) {
 // src/compiler/cache/writeCache.ts
 import fs3 from "fs";
 import path3 from "path";
-import ts8 from "typescript";
+import ts11 from "typescript";
 function statMtimeMs2(p) {
   return fs3.statSync(p).mtimeMs;
 }
@@ -1750,7 +2321,7 @@ function writeCache(params) {
     generator: {
       name: "adorn-api",
       version: params.adornVersion,
-      typescript: ts8.version
+      typescript: ts11.version
     },
     project: {
       tsconfigPath: params.tsconfigAbs,
@@ -1763,7 +2334,7 @@ function writeCache(params) {
 }
 
 // src/cli.ts
-import ts9 from "typescript";
+import ts12 from "typescript";
 import process from "process";
 var ADORN_VERSION = "0.1.0";
 function log(msg) {
@@ -1811,7 +2382,7 @@ async function buildCommand(args) {
       outDir: outputDir,
       project: projectPath,
       adornVersion: ADORN_VERSION,
-      typescriptVersion: ts9.version
+      typescriptVersion: ts12.version
     });
     if (!stale.stale) {
       log("adorn-api: artifacts up-to-date");