next-openapi-gen 1.2.1 → 1.2.3

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":
@@ -12127,6 +12142,9 @@ var ZodSchemaConverter = class {
   schemaNameToFiles = /* @__PURE__ */ new Map();
   /** Per-file import alias for the `zod` module (`import { z as zod }` sets this to `"zod"`). */
   zodImportAlias = /* @__PURE__ */ new Map();
+  /** Schema variable names whose component name was overridden via .meta({ id }). These must
+   *  NOT be copied back under the original variable name in the OpenAPI components object. */
+  metaIdSchemaNames = /* @__PURE__ */ new Set();
   // Current processing context (set during file processing)
   currentFilePath;
   currentAST;
@@ -12153,7 +12171,14 @@ var ZodSchemaConverter = class {
     }
     logger.debug(`Looking for Zod schema: ${schemaName}`);
     const requestedSchemaName = schemaName;
-    const mappedSchemaName = this.typeToSchemaMapping[schemaName];
+    let mappedSchemaName = this.typeToSchemaMapping[schemaName];
+    if (!mappedSchemaName) {
+      const candidate = this.deriveSchemaNameByConvention(schemaName);
+      if (candidate && this.locateSchemaByConvention(candidate)) {
+        this.typeToSchemaMapping[schemaName] = candidate;
+        mappedSchemaName = candidate;
+      }
+    }
     if (mappedSchemaName) {
       logger.debug(`Type '${schemaName}' is mapped to schema '${mappedSchemaName}'`);
       schemaName = mappedSchemaName;
@@ -12203,7 +12228,7 @@ var ZodSchemaConverter = class {
       this.processingSchemas.delete(schemaName);
       if (mappedSchemaName && requestedSchemaName !== schemaName) {
         const resolvedReference = this.getSchemaReferenceName(schemaName, this.currentContentType);
-        if (this.zodSchemas[resolvedReference] && !this.zodSchemas[requestedSchemaName]) {
+        if (!this.metaIdSchemaNames.has(requestedSchemaName) && this.zodSchemas[resolvedReference] && !this.zodSchemas[requestedSchemaName]) {
           this.zodSchemas[requestedSchemaName] = this.zodSchemas[resolvedReference];
         }
         this.schemaVariantRefs.set(this.getVariantKey(requestedSchemaName, this.currentContentType), this.zodSchemas[requestedSchemaName] ? requestedSchemaName : resolvedReference);
@@ -12660,6 +12685,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)) {
@@ -12674,6 +12701,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);
+                  }
+                }
               }
             });
           }
@@ -13227,6 +13265,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;
@@ -13467,7 +13523,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;
@@ -13753,6 +13810,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)) {
@@ -13760,15 +13818,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);
                   }
                 }
               }
@@ -13781,22 +13843,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}`);
     }
@@ -13814,6 +13879,63 @@ 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.zodSchemas[finalName]) {
+      if (overrideId && overrideId !== schemaName) {
+        this.typeToSchemaMapping[schemaName] = overrideId;
+        this.metaIdSchemaNames.add(schemaName);
+        if (this.typeToSchemaMapping[overrideId] === schemaName) {
+          delete this.typeToSchemaMapping[overrideId];
+        }
+      }
+      const variantKey = this.getVariantKey(finalName, this.currentContentType);
+      this.zodSchemas[finalName] = schema;
+      this.schemaVariantRefs.set(variantKey, finalName);
+    } else {
+      logger.warn(`Schema component name '${overrideId ?? finalName}' conflicts with an existing schema, ignoring .meta({ id }) on '${schemaName}'`);
+    }
+  }
+  /**
+   * Derives the conventional Zod schema name from a TypeScript type name.
+   * e.g. "Slider" → "sliderSchema", "SliderItem" → "sliderItemSchema".
+   * Returns null when the input is already a schema name or is not PascalCase.
+   */
+  deriveSchemaNameByConvention(typeName) {
+    if (!typeName || !/^[A-Z]/.test(typeName) || typeName.endsWith("Schema")) {
+      return null;
+    }
+    return typeName[0].toLowerCase() + typeName.slice(1) + "Schema";
+  }
+  /**
+   * Checks whether a Zod schema with the given name is present in schemaDirs
+   * WITHOUT populating the processed-schema cache. A file-content substring check
+   * (the same heuristic used by processFileForZodSchema) is sufficient here: we
+   * only want to know whether the candidate *might* live in schemaDirs so that the
+   * convention mapping can be registered; the actual processing happens later in
+   * the normal convertZodSchemaToOpenApi lookup flow.
+   */
+  locateSchemaByConvention(candidate) {
+    if (this.schemaNameToFiles.has(candidate)) {
+      return true;
+    }
+    for (const dir of this.schemaDirs) {
+      for (const filePath of this.getSchemaFiles(dir)) {
+        try {
+          const content = this.fileAccess.readFileSync(filePath, "utf-8");
+          if (content.includes(candidate)) {
+            return true;
+          }
+        } catch {
+        }
+      }
+    }
+    return false;
+  }
   /**
    * Check if node is Zod schema
    */
@@ -14045,7 +14167,7 @@ function parsePropertyComment(commentValue) {
 function getPropertyOptions(node, contentType) {
   const isOptional = !!node.optional;
   const options = {};
-  const leadingComment = node.leadingComments?.[node.leadingComments.length - 1];
+  const leadingComment = node.leadingComments?.findLast((c) => c.type === "CommentBlock" || !node.trailingComments?.length);
   const trailingComment = node.trailingComments?.[0];
   const sourceComment = leadingComment ?? trailingComment;
   if (sourceComment) {
@@ -14448,31 +14570,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) => {
@@ -14480,19 +14631,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);
         }
       }
     }
@@ -14909,6 +15067,7 @@ var SchemaProcessor = class {
   zodSchemaProcessor = null;
   schemaTypes;
   isResolvingPickOmitBase = false;
+  schemaIdAliases = {};
   fileAccess;
   symbolResolver;
   // Track imports per file for resolving ReturnType<typeof func>
@@ -14949,7 +15108,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;
       }
     });
@@ -14964,6 +15123,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];
     }
@@ -15045,6 +15208,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];
@@ -15056,6 +15220,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);
@@ -15094,7 +15268,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);
@@ -15691,6 +15865,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,
@@ -15866,7 +16043,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" };
@@ -16007,7 +16186,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>"