next-openapi-gen 1.2.1 → 1.2.3

package/dist/vite/index.js

@@ -756,6 +756,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() || "";
 }
@@ -3172,7 +3183,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;
@@ -11456,8 +11468,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":
@@ -11714,6 +11729,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;
@@ -11740,7 +11758,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;
@@ -11790,7 +11815,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);
@@ -12247,6 +12272,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: (path17) => {
           if (t10.isVariableDeclaration(path17.node.declaration)) {
@@ -12261,6 +12288,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);
+                  }
+                }
               }
             });
           }
@@ -12814,6 +12852,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;
@@ -13054,7 +13110,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;
@@ -13340,6 +13397,7 @@ var ZodSchemaConverter = class {
       this.currentFilePath = filePath;
       this.currentAST = ast;
       this.currentImports = importedModules;
+      this.preprocessedFiles.add(filePath);
       resolvedTraverse(ast, {
         ExportNamedDeclaration: (path17) => {
           if (t10.isVariableDeclaration(path17.node.declaration)) {
@@ -13347,15 +13405,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);
                   }
                 }
               }
@@ -13368,22 +13430,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}`);
     }
@@ -13401,6 +13466,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
    */
@@ -13632,7 +13754,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) {
@@ -14035,31 +14157,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: (path17) => {
       if (path17.node.id && t12.isIdentifier(path17.node.id)) {
         const name = path17.node.id.name;
-        if (!typeDefinitions[name]) {
-          const node = path17.node.typeParameters && path17.node.typeParameters.params.length > 0 ? path17.node : path17.node.typeAnnotation;
-          typeDefinitions[name] = { node, filePath: currentFile };
-        }
+        const node = path17.node.typeParameters && path17.node.typeParameters.params.length > 0 ? path17.node : path17.node.typeAnnotation;
+        const allComments = [
+          ...path17.parentPath?.node?.leadingComments ?? [],
+          ...path17.node.leadingComments ?? [],
+          ...path17.node.trailingComments ?? []
+        ];
+        registerDefinition(name, { node, filePath: currentFile }, allComments);
       }
     },
     TSInterfaceDeclaration: (path17) => {
       if (path17.node.id && t12.isIdentifier(path17.node.id)) {
         const name = path17.node.id.name;
-        if (!typeDefinitions[name]) {
-          typeDefinitions[name] = { node: path17.node, filePath: currentFile };
-        }
+        const allComments = [
+          ...path17.parentPath?.node?.leadingComments ?? [],
+          ...path17.node.leadingComments ?? [],
+          ...path17.node.trailingComments ?? [],
+          ...collectFirstMemberLeadingComments(path17.node)
+        ];
+        registerDefinition(name, { node: path17.node, filePath: currentFile }, allComments);
       }
     },
     TSEnumDeclaration: (path17) => {
       if (path17.node.id && t12.isIdentifier(path17.node.id)) {
         const name = path17.node.id.name;
-        if (!typeDefinitions[name]) {
-          typeDefinitions[name] = { node: path17.node, filePath: currentFile };
-        }
+        const allComments = [
+          ...path17.parentPath?.node?.leadingComments ?? [],
+          ...path17.node.leadingComments ?? [],
+          ...path17.node.trailingComments ?? []
+        ];
+        registerDefinition(name, { node: path17.node, filePath: currentFile }, allComments);
       }
     },
     ExportNamedDeclaration: (path17) => {
@@ -14067,19 +14218,26 @@ function collectAllExportedDefinitions(ast, typeDefinitions, currentFile) {
         const interfaceDecl = path17.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 = [
+            ...path17.node.leadingComments ?? [],
+            ...interfaceDecl.leadingComments ?? [],
+            ...interfaceDecl.trailingComments ?? [],
+            ...collectFirstMemberLeadingComments(interfaceDecl)
+          ];
+          registerDefinition(name, { node: interfaceDecl, filePath: currentFile }, allComments);
         }
       }
       if (t12.isTSTypeAliasDeclaration(path17.node.declaration)) {
         const typeDecl = path17.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 = [
+            ...path17.node.leadingComments ?? [],
+            ...typeDecl.leadingComments ?? [],
+            ...typeDecl.trailingComments ?? []
+          ];
+          registerDefinition(name, { node, filePath: currentFile }, allComments);
         }
       }
     }
@@ -14496,6 +14654,7 @@ var SchemaProcessor = class {
   zodSchemaProcessor = null;
   schemaTypes;
   isResolvingPickOmitBase = false;
+  schemaIdAliases = {};
   fileAccess;
   symbolResolver;
   // Track imports per file for resolving ReturnType<typeof func>
@@ -14536,7 +14695,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;
       }
     });
@@ -14551,6 +14710,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];
     }
@@ -14632,6 +14795,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];
@@ -14643,6 +14807,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);
@@ -14681,7 +14855,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);
@@ -15278,6 +15452,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,
@@ -15453,7 +15630,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" };
@@ -15594,7 +15773,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>"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "next-openapi-gen",
-  "version": "1.2.1",
+  "version": "1.2.3",
   "description": "Automatically generate OpenAPI 3.0, 3.1, and 3.2 documentation from Next.js projects, with support for Zod schemas, TypeScript types, and reusable OpenAPI fragments.",
   "keywords": [
     "api",