@figulus/schema 0.4.0-alpha-dev → 0.5.0-alpha-dev-1

package/scripts/fix-openapi-3.1.ts

@@ -0,0 +1,183 @@
+import { parse, stringify } from "yaml";
+import { readFileSync, writeFileSync } from "fs";
+
+const inputPath = process.argv[2];
+const outputPath = process.argv[3] ?? inputPath;
+
+if (!inputPath) {
+  console.error("Usage: npx tsx fix-nullable.ts <input.yaml> [output.yaml]");
+  process.exit(1);
+}
+
+/**
+ * Recursively walks a parsed YAML/JSON object and fixes OpenAPI 3.1 schema issues
+ * produced by @asteasolutions/zod-to-openapi when generating from Zod schemas.
+ *
+ * Fixes:
+ *
+ * 1. Standalone nullable member in anyOf/oneOf/allOf:
+ *    { anyOf: [..., { nullable: true }] }
+ *    → { anyOf: [..., { type: "null" }] }
+ *
+ * 2. Sibling nullable on a schema object:
+ *    { type: "string", nullable: true }
+ *    → { anyOf: [{ type: "string" }, { type: "null" }] }
+ *
+ * 3. OpenAPI 3.0-style exclusiveMinimum as boolean:
+ *    { minimum: 0, exclusiveMinimum: true }
+ *    → { exclusiveMinimum: 0 }
+ *
+ * 4. Zod unions generated as anyOf when they should be oneOf:
+ *    { anyOf: [{ $ref: ... }, { $ref: ... }, { type: "string" }] }
+ *    → { oneOf: [{ $ref: ... }, { $ref: ... }, { type: "string" }] }
+ *    (when items are mutually exclusive: all have different types, or all are refs, etc)
+ *
+ * All are produced by @asteasolutions/zod-to-openapi when handling z.null(),
+ * z.nullable(), z.union(), or numeric constraints in Zod schemas.
+ */
+function fixNullable(node: unknown): unknown {
+  if (Array.isArray(node)) {
+    const fixed = node.map(fixNullable);
+
+    // Pattern 1: replace { nullable: true } entries in anyOf/oneOf/allOf arrays
+    // with { type: "null" }
+    return fixed.map((item) => {
+      if (
+        item !== null &&
+        typeof item === "object" &&
+        !Array.isArray(item) &&
+        (item as Record<string, unknown>)["nullable"] === true &&
+        Object.keys(item as object).length === 1
+      ) {
+        return { type: "null" };
+      }
+      return item;
+    });
+  }
+
+  if (node !== null && typeof node === "object") {
+    const obj = node as Record<string, unknown>;
+
+    // Recurse into all child values first
+    const result: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(obj)) {
+      result[key] = fixNullable(value);
+    }
+
+    // Pattern 2: sibling nullable: true on a schema with a type field
+    // { type: "string", nullable: true, ...rest }
+    // → { anyOf: [{ type: "string", ...rest }, { type: "null" }] }
+    if (result["nullable"] === true && result["type"] !== undefined) {
+      const { nullable, ...rest } = result;
+      void nullable; // consumed
+      return {
+        anyOf: [rest, { type: "null" }],
+      };
+    }
+
+    // Pattern 3: standalone nullable: true with no type (already handled in
+    // array case above, but catch any that appear as object values directly)
+    if (result["nullable"] === true && result["type"] === undefined) {
+      return { type: "null" };
+    }
+
+    // Pattern 4: OpenAPI 3.0-style exclusiveMinimum as boolean (should be numeric in 3.1)
+    // { minimum: 0, exclusiveMinimum: true } → { exclusiveMinimum: 0 }
+    if (result["exclusiveMinimum"] === true && result["minimum"] !== undefined) {
+      const { minimum, exclusiveMinimum, ...rest } = result;
+      void exclusiveMinimum; // consumed
+      return {
+        ...rest,
+        exclusiveMinimum: minimum,
+      };
+    }
+
+    // Pattern 5: Zod unions become anyOf but should be oneOf
+    // Heuristic: if anyOf items have mutually exclusive types or are all $refs, use oneOf
+    // anyOf [{ type: string }, { type: array }, { $ref: ... }] → oneOf (discriminated union)
+    if (Array.isArray(result["anyOf"]) && (result["anyOf"] as any[]).length > 0) {
+      const items = result["anyOf"] as any[];
+      let shouldBeOneOf = false;
+
+      // Check if all items have different `type` values (mutually exclusive)
+      const types = new Set<string>();
+      const allHaveType = items.every((item) => item.type !== undefined);
+      if (allHaveType) {
+        items.forEach((item) => types.add(item.type));
+        // If all items have different types, they're mutually exclusive
+        if (types.size === items.length && items.length > 1) {
+          shouldBeOneOf = true;
+        }
+      }
+
+      // Check if all items are schema references ($ref)
+      const allRefs = items.every((item) => item.$ref !== undefined);
+      if (allRefs && items.length > 1) {
+        shouldBeOneOf = true;
+      }
+
+      // Check if items are refs mixed with other types (e.g., string, array)
+      const refCount = items.filter((item) => item.$ref).length;
+      const otherCount = items.filter((item) => !item.$ref && item.type).length;
+      if (refCount > 0 && otherCount > 0) {
+        shouldBeOneOf = true;
+      }
+
+      if (shouldBeOneOf && !result["oneOf"]) {
+        const { anyOf, ...rest } = result;
+        return {
+          ...rest,
+          oneOf: anyOf,
+        };
+      }
+    }
+
+    return result;
+  }
+
+  return node;
+}
+
+const raw = readFileSync(inputPath, "utf-8");
+const parsed = parse(raw);
+const fixed = fixNullable(parsed);
+const output = stringify(fixed, { lineWidth: 0 });
+
+writeFileSync(outputPath, output, "utf-8");
+
+const inputLines = raw.split("\n").length;
+const outputLines = output.split("\n").length;
+
+// Count how many replacements were made by diffing nullable occurrences
+const nullableCountBefore = (raw.match(/nullable:\s*true/g) ?? []).length;
+const nullableCountAfter = (output.match(/nullable:\s*true/g) ?? []).length;
+const fixed_count = nullableCountBefore - nullableCountAfter;
+
+const exclusiveMinBefore = (raw.match(/exclusiveMinimum:\s*true/g) ?? []).length;
+const exclusiveMinAfter = (output.match(/exclusiveMinimum:\s*true/g) ?? []).length;
+const exclusiveMinFixed = exclusiveMinBefore - exclusiveMinAfter;
+
+const anyOfBefore = (raw.match(/anyOf:/g) ?? []).length;
+const anyOfAfter = (output.match(/anyOf:/g) ?? []).length;
+const anyOfToOneOfFixed = anyOfBefore - anyOfAfter;
+
+console.log(`Input:   ${inputPath} (${inputLines} lines)`);
+console.log(`Output:  ${outputPath} (${outputLines} lines)`);
+console.log(`Fixed:   ${fixed_count} nullable: true → type: "null" replacements`);
+console.log(`Fixed:   ${exclusiveMinFixed} exclusiveMinimum: true → numeric replacements`);
+console.log(`Fixed:   ${anyOfToOneOfFixed} anyOf → oneOf conversions`);
+if (nullableCountAfter > 0) {
+  console.warn(
+    `Warning: ${nullableCountAfter} nullable: true occurrences remain — manual review needed`
+  );
+}
+if (exclusiveMinAfter > 0) {
+  console.warn(
+    `Warning: ${exclusiveMinAfter} exclusiveMinimum: true occurrences remain — manual review needed`
+  );
+}
+if (anyOfAfter > 0) {
+  console.log(
+    `ℹ️  ${anyOfAfter} anyOf schemas remain (may be intentional for overlapping unions)`
+  );
+}

package/scripts/generate-openapi-data.ts

@@ -0,0 +1,51 @@
+import { OpenApiGeneratorV3, OpenAPIRegistry } from "@asteasolutions/zod-to-openapi";
+import { OpenAPIObjectConfig } from "@asteasolutions/zod-to-openapi/dist/v3.0/openapi-generator.js";
+import fs, { readFileSync } from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import YAML from "yaml";
+import z from "zod";
+import { registerAll } from "../.openapi-meta/index.js";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const inputDir = path.join(__dirname, "..", ".openapi-meta", "generated");
+const inputFile = path.join(inputDir, "data.json");
+
+const metadata = z.object({
+    fileName: z.string(),
+    document: z.custom<OpenAPIObjectConfig>(),
+}).parse(
+  JSON.parse(readFileSync(inputFile).toString())
+);
+
+const outputDir = path.join(__dirname, "..", "..", "..", "api");
+const outputFile = path.join(outputDir, `${metadata.fileName}.yaml`);
+
+// Create output directory if it doesn't exist
+if (!fs.existsSync(outputDir)) {
+  fs.mkdirSync(outputDir, { recursive: true });
+}
+
+try {
+  const registry = registerAll(new OpenAPIRegistry());
+
+  const generator = new OpenApiGeneratorV3(registry.definitions);
+
+  const openApiDoc = generator.generateDocument(metadata.document);
+
+  // Sort components.schemas alphabetically for stable output independent of source file organization
+  if (openApiDoc.components?.schemas) {
+    openApiDoc.components.schemas = Object.fromEntries(
+      Object.entries(openApiDoc.components.schemas).sort(([a], [b]) => a.localeCompare(b))
+    );
+  }
+
+  const yamlContent = YAML.stringify(openApiDoc);
+  fs.writeFileSync(outputFile, yamlContent);
+
+  console.log(`✅ Generated OpenAPI spec at: ${outputFile}`);
+} catch (error) {
+  console.error("❌ Failed to generate OpenAPI spec:", error);
+  process.exit(1);
+}