next-openapi-gen 1.2.0 → 1.2.2

package/README.md

@@ -184,6 +184,23 @@ z.number()
 
 Both work inside `z.object({...})` properties, in drizzle-zod override callbacks, and at the top level of named schemas. See [docs/zod4-support-matrix.md](./docs/zod4-support-matrix.md) for the full supported metadata surface.
 
+### Decouple component names from source identifiers
+
+Use `.meta({ id })` for Zod schemas or `/** @id */` for TypeScript types to set the OpenAPI component name independently of the export name — useful when enforcing PascalCase naming or migrating from another generator without renaming existing exports:
+
+```ts
+// Zod: use .meta({ id }) to decouple the component name from the variable name
+export const audioSchema = z.object({ ... }).meta({ id: "Audio" });
+// → components.schemas.Audio (not: audioSchema)
+
+// TypeScript: use /** @id */ at the declaration level
+/** @id Audio */
+export interface AudioInterface { ... }
+// → components.schemas.Audio (not: AudioInterface)
+```
+
+Existing `@body audioSchema` or `@response audioSchema` references in route handlers continue to work — the generator resolves them transparently to the override name. See [docs/jsdoc-reference.md#component-naming](./docs/jsdoc-reference.md#component-naming) for details.
+
 ### Generate docs from Drizzle schemas
 
 `next-openapi-gen` works well with `drizzle-zod`, so your database schema, validation, and API docs can share the same source of truth.

package/dist/cli.js

@@ -1406,6 +1406,17 @@ function mergeJSDocData(target, source) {
 function cleanComment(commentValue) {
   return commentValue.replace(/\*\s*/g, "").trim();
 }
+function extractSchemaIdFromComments(comments) {
+  if (!comments)
+    return null;
+  for (const comment of comments) {
+    const cleaned = cleanComment(comment.value);
+    const id = extractTokenValue(cleaned, "@id");
+    if (id)
+      return id;
+  }
+  return null;
+}
 function extractLineValue(commentValue, tag) {
   return commentValue.match(new RegExp(`${escapeRegExp(tag)}\\s*(.*)`, "m"))?.[1]?.trim() || "";
 }
@@ -3585,7 +3596,8 @@ var DrizzleZodProcessor = class _DrizzleZodProcessor {
         if (firstArg && !t4.isSpreadElement(firstArg) && !t4.isArgumentPlaceholder(firstArg)) {
           const metadata = _DrizzleZodProcessor.extractStaticObject(firstArg);
           if (metadata) {
-            Object.assign(result, metadata);
+            const { id: _id, ...rest } = metadata;
+            Object.assign(result, rest);
           }
         }
         break;
@@ -11869,8 +11881,11 @@ var ZodRuntimeExporter = class {
       case "deprecated":
         return schema.meta({ deprecated: true });
       case "meta": {
-        const metadata = node.arguments[0] ? this.buildMetadataObject(node.arguments[0]) : null;
-        return metadata ? schema.meta(metadata) : schema;
+        const rawMetadata = node.arguments[0] ? this.buildMetadataObject(node.arguments[0]) : null;
+        if (!rawMetadata)
+          return schema;
+        const { id: _id, ...metadata } = rawMetadata;
+        return Object.keys(metadata).length > 0 ? schema.meta(metadata) : schema;
       }
       case "default":
       case "prefault":
@@ -12106,7 +12121,9 @@ var ZodSchemaConverter = class {
   apiDir;
   zodSchemas = {};
   processingSchemas = /* @__PURE__ */ new Set();
-  processedModules = /* @__PURE__ */ new Set();
+  /** Memoization guard for processFileForZodSchema. Keys: `${filePath}|${schemaName}`.
+   * Prevents infinite recursion when re-export files reference schemas via z.infer<typeof X>. */
+  processedFileSchemaPairs = /* @__PURE__ */ new Set();
   typeToSchemaMapping = {};
   drizzleZodImports = /* @__PURE__ */ new Set();
   factoryCache = /* @__PURE__ */ new Map();
@@ -12320,6 +12337,11 @@ var ZodSchemaConverter = class {
    * Process a file to find Zod schema definitions
    */
   processFileForZodSchema(filePath, schemaName) {
+    const visitKey = `${filePath}|${schemaName}|${this.currentContentType}`;
+    if (this.processedFileSchemaPairs.has(visitKey)) {
+      return;
+    }
+    this.processedFileSchemaPairs.add(visitKey);
     try {
       const content = this.fileAccess.readFileSync(filePath, "utf-8");
       if (!content.includes(schemaName)) {
@@ -12633,7 +12655,9 @@ var ZodSchemaConverter = class {
                 const param = path25.node.typeAnnotation.typeParameters.params[0];
                 if (t10.isTSTypeQuery(param) && t10.isIdentifier(param.exprName)) {
                   const referencedSchemaName = param.exprName.name;
-                  this.processFileForZodSchema(filePath, referencedSchemaName);
+                  if (!this.getStoredSchema(referencedSchemaName)) {
+                    this.processFileForZodSchema(filePath, referencedSchemaName);
+                  }
                 }
               }
             }
@@ -12651,6 +12675,8 @@ var ZodSchemaConverter = class {
     try {
       const content = this.fileAccess.readFileSync(filePath, "utf-8");
       const ast = parseTypeScriptFile(content);
+      this.currentFilePath = filePath;
+      this.currentAST = ast;
       resolvedTraverse(ast, {
         ExportNamedDeclaration: (path25) => {
           if (t10.isVariableDeclaration(path25.node.declaration)) {
@@ -12665,6 +12691,17 @@ var ZodSchemaConverter = class {
                   }
                   this.processingSchemas.delete(schemaName);
                 }
+              } else if (t10.isIdentifier(declaration.id) && declaration.init) {
+                const schemaName = declaration.id.name;
+                const overrideId = this.extractMetaIdFromNode(declaration.init);
+                if (overrideId && !this.getStoredSchema(schemaName) && !this.processingSchemas.has(schemaName)) {
+                  this.processingSchemas.add(schemaName);
+                  const schema = this.processZodNode(declaration.init);
+                  this.processingSchemas.delete(schemaName);
+                  if (schema) {
+                    this.applyMetaIdOverride(schemaName, schema, overrideId, filePath);
+                  }
+                }
               }
             });
           }
@@ -13218,6 +13255,24 @@ var ZodSchemaConverter = class {
     }
     return void 0;
   }
+  extractMetaIdFromNode(node) {
+    if (!t10.isCallExpression(node))
+      return null;
+    if (t10.isMemberExpression(node.callee) && t10.isIdentifier(node.callee.property)) {
+      if (node.callee.property.name === "meta" && node.arguments.length > 0) {
+        const metadata = this.extractStaticJsonValue(node.arguments[0]);
+        if (metadata && typeof metadata === "object" && !Array.isArray(metadata)) {
+          const id = metadata.id;
+          if (typeof id === "string" && id.length > 0)
+            return id;
+        }
+      }
+      if (t10.isCallExpression(node.callee.object)) {
+        return this.extractMetaIdFromNode(node.callee.object);
+      }
+    }
+    return null;
+  }
   shouldUseRuntimeExport(node) {
     if (!t10.isCallExpression(node)) {
       return false;
@@ -13458,7 +13513,8 @@ var ZodSchemaConverter = class {
         if (node.arguments.length > 0) {
           const metadata = this.extractStaticJsonValue(node.arguments[0]);
           if (metadata && typeof metadata === "object" && !Array.isArray(metadata)) {
-            Object.assign(schema, metadata);
+            const { id: _id, ...rest } = metadata;
+            Object.assign(schema, rest);
           }
         }
         break;
@@ -13744,6 +13800,7 @@ var ZodSchemaConverter = class {
       this.currentFilePath = filePath;
       this.currentAST = ast;
       this.currentImports = importedModules;
+      this.preprocessedFiles.add(filePath);
       resolvedTraverse(ast, {
         ExportNamedDeclaration: (path25) => {
           if (t10.isVariableDeclaration(path25.node.declaration)) {
@@ -13751,15 +13808,19 @@ var ZodSchemaConverter = class {
               if (t10.isIdentifier(declaration.id) && declaration.init) {
                 const schemaName = declaration.id.name;
                 if (this.isZodSchema(declaration.init)) {
-                  this.indexSchemaName(schemaName, filePath);
                   if (!this.getStoredSchema(schemaName)) {
                     logger.debug(`Pre-processing Zod schema: ${schemaName}`);
                     this.processingSchemas.add(schemaName);
                     const schema = this.processZodNode(declaration.init);
+                    this.processingSchemas.delete(schemaName);
                     if (schema) {
-                      this.storeResolvedSchema(schemaName, schema);
+                      const overrideId = this.extractMetaIdFromNode(declaration.init);
+                      this.applyMetaIdOverride(schemaName, schema, overrideId, filePath);
+                    } else {
+                      this.indexSchemaName(schemaName, filePath);
                     }
-                    this.processingSchemas.delete(schemaName);
+                  } else {
+                    this.indexSchemaName(schemaName, filePath);
                   }
                 }
               }
@@ -13772,22 +13833,25 @@ var ZodSchemaConverter = class {
             if (t10.isIdentifier(declaration.id) && declaration.init) {
               const schemaName = declaration.id.name;
               if (this.isZodSchema(declaration.init)) {
-                this.indexSchemaName(schemaName, filePath);
                 if (!this.getStoredSchema(schemaName) && !this.processingSchemas.has(schemaName)) {
                   logger.debug(`Pre-processing Zod schema: ${schemaName}`);
                   this.processingSchemas.add(schemaName);
                   const schema = this.processZodNode(declaration.init);
+                  this.processingSchemas.delete(schemaName);
                   if (schema) {
-                    this.storeResolvedSchema(schemaName, schema);
+                    const overrideId = this.extractMetaIdFromNode(declaration.init);
+                    this.applyMetaIdOverride(schemaName, schema, overrideId, filePath);
+                  } else {
+                    this.indexSchemaName(schemaName, filePath);
                   }
-                  this.processingSchemas.delete(schemaName);
+                } else {
+                  this.indexSchemaName(schemaName, filePath);
                 }
               }
             }
           });
         }
       });
-      this.preprocessedFiles.add(filePath);
     } catch (error2) {
       logger.error(`Error pre-processing file ${filePath}: ${error2}`);
     }
@@ -13805,6 +13869,21 @@ var ZodSchemaConverter = class {
     }
     bucket.add(filePath);
   }
+  applyMetaIdOverride(schemaName, schema, overrideId, filePath) {
+    const finalName = overrideId && overrideId !== schemaName ? overrideId : schemaName;
+    this.indexSchemaName(schemaName, filePath);
+    if (finalName !== schemaName) {
+      this.indexSchemaName(finalName, filePath);
+    }
+    if (!this.getStoredSchema(finalName)) {
+      if (overrideId && overrideId !== schemaName) {
+        this.typeToSchemaMapping[schemaName] = overrideId;
+      }
+      this.storeResolvedSchema(finalName, schema);
+    } else {
+      logger.warn(`Schema component name '${overrideId ?? finalName}' conflicts with an existing schema, ignoring .meta({ id }) on '${schemaName}'`);
+    }
+  }
   /**
    * Check if node is Zod schema
    */
@@ -14008,15 +14087,39 @@ function extractKeysFromLiteralType(node) {
   }
   return [];
 }
+function parsePropertyComment(commentValue) {
+  const text = commentValue.split("\n").map((line) => line.replace(/^\s*\*\s?/, "").trim()).filter((line) => line.length > 0).join(" ").trim();
+  const result = {};
+  let remaining = text;
+  const formatMatch = remaining.match(/@format\s+(\S+)/);
+  if (formatMatch?.[1]) {
+    result.format = formatMatch[1];
+    remaining = remaining.replace(formatMatch[0], "").trim();
+  }
+  const exampleMatch = remaining.match(/@example\s+(.+?)(?=\s*@\w|$)/);
+  if (exampleMatch?.[1]) {
+    const raw = exampleMatch[1].trim();
+    try {
+      result.example = JSON.parse(raw);
+    } catch {
+      result.example = raw;
+    }
+    remaining = remaining.replace(exampleMatch[0], "").trim();
+  }
+  remaining = remaining.replace(/@\w+(?:\s+\S+)*/g, "").trim();
+  if (remaining) {
+    result.description = remaining;
+  }
+  return result;
+}
 function getPropertyOptions(node, contentType) {
   const isOptional = !!node.optional;
-  let description = null;
-  if (node.trailingComments && node.trailingComments.length) {
-    description = node.trailingComments[0].value.trim();
-  }
   const options = {};
-  if (description) {
-    options.description = description;
+  const leadingComment = node.leadingComments?.findLast((c) => c.type === "CommentBlock" || !node.trailingComments?.length);
+  const trailingComment = node.trailingComments?.[0];
+  const sourceComment = leadingComment ?? trailingComment;
+  if (sourceComment) {
+    Object.assign(options, parsePropertyComment(sourceComment.value));
   }
   if (contentType === "body") {
     options.nullable = isOptional;
@@ -14415,31 +14518,60 @@ function resolveImportPath(importPath, fromFilePath, fileAccess) {
   }
   return null;
 }
-function collectAllExportedDefinitions(ast, typeDefinitions, currentFile) {
+function collectFirstMemberLeadingComments(interfaceDecl) {
+  const body = interfaceDecl?.body;
+  if (!body)
+    return [];
+  const firstMember = body.body?.[0];
+  return firstMember?.leadingComments ?? [];
+}
+function collectAllExportedDefinitions(ast, typeDefinitions, currentFile, schemaIdAliases) {
+  function registerDefinition(name, entry, allComments) {
+    if (!typeDefinitions[name]) {
+      typeDefinitions[name] = entry;
+    }
+    const overrideId = extractSchemaIdFromComments(allComments);
+    if (overrideId && schemaIdAliases) {
+      schemaIdAliases[name] = overrideId;
+      if (!typeDefinitions[overrideId]) {
+        typeDefinitions[overrideId] = entry;
+      }
+    }
+  }
   resolvedTraverse(ast, {
     TSTypeAliasDeclaration: (path25) => {
       if (path25.node.id && t12.isIdentifier(path25.node.id)) {
         const name = path25.node.id.name;
-        if (!typeDefinitions[name]) {
-          const node = path25.node.typeParameters && path25.node.typeParameters.params.length > 0 ? path25.node : path25.node.typeAnnotation;
-          typeDefinitions[name] = { node, filePath: currentFile };
-        }
+        const node = path25.node.typeParameters && path25.node.typeParameters.params.length > 0 ? path25.node : path25.node.typeAnnotation;
+        const allComments = [
+          ...path25.parentPath?.node?.leadingComments ?? [],
+          ...path25.node.leadingComments ?? [],
+          ...path25.node.trailingComments ?? []
+        ];
+        registerDefinition(name, { node, filePath: currentFile }, allComments);
       }
     },
     TSInterfaceDeclaration: (path25) => {
       if (path25.node.id && t12.isIdentifier(path25.node.id)) {
         const name = path25.node.id.name;
-        if (!typeDefinitions[name]) {
-          typeDefinitions[name] = { node: path25.node, filePath: currentFile };
-        }
+        const allComments = [
+          ...path25.parentPath?.node?.leadingComments ?? [],
+          ...path25.node.leadingComments ?? [],
+          ...path25.node.trailingComments ?? [],
+          ...collectFirstMemberLeadingComments(path25.node)
+        ];
+        registerDefinition(name, { node: path25.node, filePath: currentFile }, allComments);
       }
     },
     TSEnumDeclaration: (path25) => {
       if (path25.node.id && t12.isIdentifier(path25.node.id)) {
         const name = path25.node.id.name;
-        if (!typeDefinitions[name]) {
-          typeDefinitions[name] = { node: path25.node, filePath: currentFile };
-        }
+        const allComments = [
+          ...path25.parentPath?.node?.leadingComments ?? [],
+          ...path25.node.leadingComments ?? [],
+          ...path25.node.trailingComments ?? []
+        ];
+        registerDefinition(name, { node: path25.node, filePath: currentFile }, allComments);
       }
     },
     ExportNamedDeclaration: (path25) => {
@@ -14447,19 +14579,26 @@ function collectAllExportedDefinitions(ast, typeDefinitions, currentFile) {
         const interfaceDecl = path25.node.declaration;
         if (interfaceDecl.id && t12.isIdentifier(interfaceDecl.id)) {
           const name = interfaceDecl.id.name;
-          if (!typeDefinitions[name]) {
-            typeDefinitions[name] = { node: interfaceDecl, filePath: currentFile };
-          }
+          const allComments = [
+            ...path25.node.leadingComments ?? [],
+            ...interfaceDecl.leadingComments ?? [],
+            ...interfaceDecl.trailingComments ?? [],
+            ...collectFirstMemberLeadingComments(interfaceDecl)
+          ];
+          registerDefinition(name, { node: interfaceDecl, filePath: currentFile }, allComments);
         }
       }
       if (t12.isTSTypeAliasDeclaration(path25.node.declaration)) {
         const typeDecl = path25.node.declaration;
         if (typeDecl.id && t12.isIdentifier(typeDecl.id)) {
           const name = typeDecl.id.name;
-          if (!typeDefinitions[name]) {
-            const node = typeDecl.typeParameters && typeDecl.typeParameters.params.length > 0 ? typeDecl : typeDecl.typeAnnotation;
-            typeDefinitions[name] = { node, filePath: currentFile };
-          }
+          const node = typeDecl.typeParameters && typeDecl.typeParameters.params.length > 0 ? typeDecl : typeDecl.typeAnnotation;
+          const allComments = [
+            ...path25.node.leadingComments ?? [],
+            ...typeDecl.leadingComments ?? [],
+            ...typeDecl.trailingComments ?? []
+          ];
+          registerDefinition(name, { node, filePath: currentFile }, allComments);
         }
       }
     }
@@ -14876,6 +15015,7 @@ var SchemaProcessor = class {
   zodSchemaProcessor = null;
   schemaTypes;
   isResolvingPickOmitBase = false;
+  schemaIdAliases = {};
   fileAccess;
   symbolResolver;
   // Track imports per file for resolving ReturnType<typeof func>
@@ -14916,7 +15056,7 @@ var SchemaProcessor = class {
   getDefinedSchemas() {
     const filteredSchemas = {};
     Object.entries(this.openapiDefinitions).forEach(([key, value]) => {
-      if (!this.isGenericTypeParameter(key) && !this.isInvalidSchemaName(key) && !this.isBuiltInUtilityType(key) && !this.isFunctionSchema(key)) {
+      if (!this.schemaIdAliases[key] && !this.isGenericTypeParameter(key) && !this.isInvalidSchemaName(key) && !this.isBuiltInUtilityType(key) && !this.isFunctionSchema(key)) {
         filteredSchemas[key] = value;
       }
     });
@@ -14931,6 +15071,10 @@ var SchemaProcessor = class {
     if (schemaName.includes("<") && schemaName.includes(">")) {
       return this.resolveGenericTypeFromString(schemaName);
     }
+    const overrideId = this.schemaIdAliases[schemaName];
+    if (overrideId) {
+      return this.findSchemaDefinition(overrideId, contentType);
+    }
     if (this.openapiDefinitions[schemaName]) {
       return this.openapiDefinitions[schemaName];
     }
@@ -15012,6 +15156,7 @@ var SchemaProcessor = class {
       return;
     }
     this.collectImports(ast, filePath);
+    const aliasesBeforeFile = new Set(Object.keys(this.schemaIdAliases));
     this.collectAllExportedDefinitions(ast, filePath);
     collectTopLevelDefinitionNames(ast).forEach((name) => {
       const indexedFiles = this.schemaDefinitionIndex[name];
@@ -15023,6 +15168,16 @@ var SchemaProcessor = class {
       }
       this.schemaDefinitionIndex[name] = [filePath];
     });
+    Object.entries(this.schemaIdAliases).forEach(([originalName, aliasName]) => {
+      if (aliasesBeforeFile.has(originalName))
+        return;
+      if (!this.schemaDefinitionIndex[aliasName]) {
+        this.schemaDefinitionIndex[aliasName] = [];
+      }
+      if (!this.schemaDefinitionIndex[aliasName].includes(filePath)) {
+        this.schemaDefinitionIndex[aliasName].push(filePath);
+      }
+    });
   }
   getParsedSchemaFile(filePath) {
     const cachedAst = this.fileASTCache.get(filePath);
@@ -15061,7 +15216,7 @@ var SchemaProcessor = class {
    * Used when processing imported files to ensure all referenced types are available
    */
   collectAllExportedDefinitions(ast, filePath) {
-    collectAllExportedDefinitions(ast, this.typeDefinitions, filePath || this.currentFilePath);
+    collectAllExportedDefinitions(ast, this.typeDefinitions, filePath || this.currentFilePath, this.schemaIdAliases);
   }
   collectTypeDefinitions(ast, schemaName, filePath) {
     collectTypeDefinitions(ast, schemaName, this.typeDefinitions, filePath || this.currentFilePath);
@@ -15658,6 +15813,9 @@ var SchemaProcessor = class {
         logger.debug(`Record<...> used with ${node.typeParameters?.params.length ?? 0} type parameters; expected 2`);
         return { type: "object", additionalProperties: true };
       }
+      if ((!node.typeParameters || node.typeParameters.params.length === 0) && this.schemaIdAliases[typeName] && this.openapiDefinitions[this.schemaIdAliases[typeName]]) {
+        return { $ref: `#/components/schemas/${this.schemaIdAliases[typeName]}` };
+      }
       const utilityType = resolveUtilityTypeReference(node, {
         currentFilePath: this.currentFilePath,
         contentType: this.contentType,
@@ -15833,7 +15991,9 @@ var SchemaProcessor = class {
       };
     }
     if (t15.isTSTypeReference(node) && t15.isIdentifier(node.typeName)) {
-      return { $ref: `#/components/schemas/${node.typeName.name}` };
+      const refName = node.typeName.name;
+      const aliasedName = this.schemaIdAliases[refName] ?? refName;
+      return { $ref: `#/components/schemas/${aliasedName}` };
     }
     logger.debug("Unrecognized TypeScript type node:", node);
     return { type: "object" };
@@ -15974,7 +16134,8 @@ var SchemaProcessor = class {
     if (this.schemaTypes.includes("zod") && this.zodSchemaConverter) {
       return this.zodSchemaConverter.getSchemaReferenceName(baseTypeName, contentType);
     }
-    return baseTypeName;
+    const aliasedName = this.schemaIdAliases[baseTypeName] ?? baseTypeName;
+    return aliasedName;
   }
   /**
    * Parse and resolve a generic type from a string like "MyApiSuccessResponseBody<LLMSResponse>"