@zuplo/openapi-tools 6.65.9 → 6.66.2

package/dist/url-utils.spec.js

@@ -0,0 +1,93 @@
+import assert from "node:assert";
+import { describe, it } from "node:test";
+import { guessFileNameFromUrl, isUrl } from "./url-utils.js";
+describe("OpenAPI Utils", () => {
+    describe("isUrl", () => {
+        it("should return true for valid HTTP URLs", () => {
+            assert.strictEqual(isUrl("http://example.com"), true);
+            assert.strictEqual(isUrl("http://example.com/api.json"), true);
+            assert.strictEqual(isUrl("http://api.example.com/v1/openapi.yaml"), true);
+        });
+        it("should return true for valid HTTPS URLs", () => {
+            assert.strictEqual(isUrl("https://example.com"), true);
+            assert.strictEqual(isUrl("https://example.com/api.json"), true);
+            assert.strictEqual(isUrl("https://api.example.com/v1/openapi.yaml"), true);
+        });
+        it("should return true for URLs with query parameters", () => {
+            assert.strictEqual(isUrl("https://example.com/api?version=1.0"), true);
+            assert.strictEqual(isUrl("https://example.com/api?format=json&version=2"), true);
+        });
+        it("should return true for URLs with fragments", () => {
+            assert.strictEqual(isUrl("https://example.com/api#section"), true);
+            assert.strictEqual(isUrl("https://example.com/api.json#definitions"), true);
+        });
+        it("should return true for URLs with ports", () => {
+            assert.strictEqual(isUrl("https://example.com:8080/api"), true);
+            assert.strictEqual(isUrl("http://localhost:3000/openapi.json"), true);
+        });
+        it("should return false for relative file paths", () => {
+            assert.strictEqual(isUrl("./api.json"), false);
+            assert.strictEqual(isUrl("../specs/openapi.yaml"), false);
+            assert.strictEqual(isUrl("docs/api.json"), false);
+        });
+        it("should return false for absolute file paths", () => {
+            assert.strictEqual(isUrl("/path/to/api.json"), false);
+            assert.strictEqual(isUrl("/Users/name/docs/openapi.yaml"), false);
+            // Windows absolute paths with drive letters may be interpreted as URLs with protocol
+            // This is expected behavior from the URL constructor
+        });
+        it("should return false for filenames without paths", () => {
+            assert.strictEqual(isUrl("api.json"), false);
+            assert.strictEqual(isUrl("openapi.yaml"), false);
+        });
+        it("should return false for empty strings", () => {
+            assert.strictEqual(isUrl(""), false);
+        });
+    });
+    describe("guessFileNameFromUrl", () => {
+        it("should extract filename from URL path", () => {
+            assert.strictEqual(guessFileNameFromUrl("https://example.com/api.json"), "api");
+            assert.strictEqual(guessFileNameFromUrl("https://example.com/openapi.yaml"), "openapi");
+        });
+        it("should extract filename from URL with multiple path segments", () => {
+            assert.strictEqual(guessFileNameFromUrl("https://example.com/v1/specs/api.json"), "api");
+            assert.strictEqual(guessFileNameFromUrl("https://api.example.com/docs/v2/openapi.yaml"), "openapi");
+        });
+        it("should extract filename from URL with query parameters", () => {
+            assert.strictEqual(guessFileNameFromUrl("https://example.com/api.json?version=1"), "api");
+            assert.strictEqual(guessFileNameFromUrl("https://example.com/openapi.yaml?format=json&v=2"), "openapi");
+        });
+        it("should extract filename from URL with fragments", () => {
+            assert.strictEqual(guessFileNameFromUrl("https://example.com/api.json#section"), "api");
+            assert.strictEqual(guessFileNameFromUrl("https://example.com/spec.yaml#definitions"), "spec");
+        });
+        it("should handle URLs with no file extension", () => {
+            assert.strictEqual(guessFileNameFromUrl("https://example.com/api"), "api");
+            assert.strictEqual(guessFileNameFromUrl("https://example.com/v1/openapi"), "openapi");
+        });
+        it("should handle URLs ending with slash", () => {
+            // When URL ends with slash, pop() returns empty string, should use base64
+            const result = guessFileNameFromUrl("https://example.com/api/");
+            assert.strictEqual(result.startsWith("imported-"), true);
+        });
+        it("should generate base64 name for root URLs", () => {
+            const result = guessFileNameFromUrl("https://example.com/");
+            assert.strictEqual(result.startsWith("imported-"), true);
+            assert.strictEqual(result.length > 9, true); // "imported-" is 9 chars
+        });
+        it("should handle filenames with multiple dots", () => {
+            assert.strictEqual(guessFileNameFromUrl("https://example.com/api.v1.0.json"), "api.v1.0");
+            assert.strictEqual(guessFileNameFromUrl("https://example.com/my.api.spec.yaml"), "my.api.spec");
+        });
+        it("should handle complex URLs", () => {
+            assert.strictEqual(guessFileNameFromUrl("https://api.example.com:8080/v2/specs/openapi.json?auth=token#info"), "openapi");
+        });
+        it("should generate consistent base64 names for same URL", () => {
+            const url = "https://example.com/";
+            const name1 = guessFileNameFromUrl(url);
+            const name2 = guessFileNameFromUrl(url);
+            assert.strictEqual(name1, name2);
+        });
+    });
+});
+//# sourceMappingURL=url-utils.spec.js.map

package/dist/url-utils.spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"url-utils.spec.js","sourceRoot":"","sources":["../src/url-utils.spec.ts"],"names":[],"mappings":"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"}

package/dist/validation.d.ts

@@ -0,0 +1,210 @@
+/**
+ * Validation schemas for OpenAPI documents and overlays
+ * Using Zod for runtime validation with actionable error messages
+ */
+import { z } from "zod";
+/**
+ * Schema for remove condition - used for conditional removal of elements
+ */
+declare const RemoveConditionSchema: z.ZodEffects<z.ZodObject<{
+    empty: z.ZodOptional<z.ZodBoolean>;
+    missing: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    empty?: boolean | undefined;
+    missing?: string | undefined;
+}, {
+    empty?: boolean | undefined;
+    missing?: string | undefined;
+}>, {
+    empty?: boolean | undefined;
+    missing?: string | undefined;
+}, {
+    empty?: boolean | undefined;
+    missing?: string | undefined;
+}>;
+/**
+ * Schema for overlay action - defines a single modification to apply
+ */
+declare const OverlayActionSchema: z.ZodEffects<z.ZodObject<{
+    target: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    update: z.ZodOptional<z.ZodUnknown>;
+    remove: z.ZodOptional<z.ZodUnion<[z.ZodBoolean, z.ZodEffects<z.ZodObject<{
+        empty: z.ZodOptional<z.ZodBoolean>;
+        missing: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        empty?: boolean | undefined;
+        missing?: string | undefined;
+    }, {
+        empty?: boolean | undefined;
+        missing?: string | undefined;
+    }>, {
+        empty?: boolean | undefined;
+        missing?: string | undefined;
+    }, {
+        empty?: boolean | undefined;
+        missing?: string | undefined;
+    }>]>>;
+}, "strict", z.ZodTypeAny, {
+    target: string;
+    description?: string | undefined;
+    update?: unknown;
+    remove?: boolean | {
+        empty?: boolean | undefined;
+        missing?: string | undefined;
+    } | undefined;
+}, {
+    target: string;
+    description?: string | undefined;
+    update?: unknown;
+    remove?: boolean | {
+        empty?: boolean | undefined;
+        missing?: string | undefined;
+    } | undefined;
+}>, {
+    target: string;
+    description?: string | undefined;
+    update?: unknown;
+    remove?: boolean | {
+        empty?: boolean | undefined;
+        missing?: string | undefined;
+    } | undefined;
+}, {
+    target: string;
+    description?: string | undefined;
+    update?: unknown;
+    remove?: boolean | {
+        empty?: boolean | undefined;
+        missing?: string | undefined;
+    } | undefined;
+}>;
+/**
+ * Schema for OpenAPI Overlay document
+ * Based on: https://github.com/OAI/Overlay-Specification v1.0.0
+ */
+export declare const OverlayDocumentSchema: z.ZodObject<{
+    overlay: z.ZodEffects<z.ZodString, string, string>;
+    info: z.ZodObject<{
+        title: z.ZodString;
+        version: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        title: string;
+        version: string;
+    }, {
+        title: string;
+        version: string;
+    }>;
+    actions: z.ZodArray<z.ZodEffects<z.ZodObject<{
+        target: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        update: z.ZodOptional<z.ZodUnknown>;
+        remove: z.ZodOptional<z.ZodUnion<[z.ZodBoolean, z.ZodEffects<z.ZodObject<{
+            empty: z.ZodOptional<z.ZodBoolean>;
+            missing: z.ZodOptional<z.ZodString>;
+        }, "strict", z.ZodTypeAny, {
+            empty?: boolean | undefined;
+            missing?: string | undefined;
+        }, {
+            empty?: boolean | undefined;
+            missing?: string | undefined;
+        }>, {
+            empty?: boolean | undefined;
+            missing?: string | undefined;
+        }, {
+            empty?: boolean | undefined;
+            missing?: string | undefined;
+        }>]>>;
+    }, "strict", z.ZodTypeAny, {
+        target: string;
+        description?: string | undefined;
+        update?: unknown;
+        remove?: boolean | {
+            empty?: boolean | undefined;
+            missing?: string | undefined;
+        } | undefined;
+    }, {
+        target: string;
+        description?: string | undefined;
+        update?: unknown;
+        remove?: boolean | {
+            empty?: boolean | undefined;
+            missing?: string | undefined;
+        } | undefined;
+    }>, {
+        target: string;
+        description?: string | undefined;
+        update?: unknown;
+        remove?: boolean | {
+            empty?: boolean | undefined;
+            missing?: string | undefined;
+        } | undefined;
+    }, {
+        target: string;
+        description?: string | undefined;
+        update?: unknown;
+        remove?: boolean | {
+            empty?: boolean | undefined;
+            missing?: string | undefined;
+        } | undefined;
+    }>, "many">;
+    extends: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    info: {
+        title: string;
+        version: string;
+    };
+    overlay: string;
+    actions: {
+        target: string;
+        description?: string | undefined;
+        update?: unknown;
+        remove?: boolean | {
+            empty?: boolean | undefined;
+            missing?: string | undefined;
+        } | undefined;
+    }[];
+    extends?: string | undefined;
+}, {
+    info: {
+        title: string;
+        version: string;
+    };
+    overlay: string;
+    actions: {
+        target: string;
+        description?: string | undefined;
+        update?: unknown;
+        remove?: boolean | {
+            empty?: boolean | undefined;
+            missing?: string | undefined;
+        } | undefined;
+    }[];
+    extends?: string | undefined;
+}>;
+/**
+ * Schema for OpenAPI document structure
+ * This is intentionally lenient to work with imperfect/incomplete OpenAPI files.
+ * The overlay tool is often used to fix incomplete specs, so we shouldn't be too strict.
+ */
+export declare const OpenApiDocumentSchema: z.ZodObject<{}, "passthrough", z.ZodTypeAny, z.objectOutputType<{}, z.ZodTypeAny, "passthrough">, z.objectInputType<{}, z.ZodTypeAny, "passthrough">>;
+/**
+ * Type exports matching Zod schemas
+ */
+export type OverlayDocument = z.infer<typeof OverlayDocumentSchema>;
+export type OverlayAction = z.infer<typeof OverlayActionSchema>;
+export type RemoveCondition = z.infer<typeof RemoveConditionSchema>;
+export type OpenApiDocument = z.infer<typeof OpenApiDocumentSchema>;
+/**
+ * Validate an OpenAPI Overlay document
+ * @throws {Error} with actionable error message if validation fails
+ */
+export declare function validateOverlayDocument(value: unknown): OverlayDocument;
+/**
+ * Validate an OpenAPI document
+ * This validation is intentionally lenient - we only check that it's a valid object.
+ * The overlay tool should work with imperfect OpenAPI files.
+ * @throws {Error} if the document is not a valid object
+ */
+export declare function validateOpenApiDocument(value: unknown): OpenApiDocument;
+export {};
+//# sourceMappingURL=validation.d.ts.map

package/dist/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;GAEG;AACH,QAAA,MAAM,qBAAqB;;;;;;;;;;;;;;;EAYvB,CAAC;AAEL;;GAEG;AACH,QAAA,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAiCtB,CAAC;AAEJ;;;GAGG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAyBvB,CAAC;AAEZ;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,uJAKkB,CAAC;AAErD;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AACpE,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAChE,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AACpE,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,eAAe,CAcvE;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,eAAe,CASvE"}

package/dist/validation.js

@@ -0,0 +1,119 @@
+/**
+ * Validation schemas for OpenAPI documents and overlays
+ * Using Zod for runtime validation with actionable error messages
+ */
+import semver from "semver";
+import { z } from "zod";
+/**
+ * Schema for remove condition - used for conditional removal of elements
+ */
+const RemoveConditionSchema = z
+    .object({
+    empty: z.boolean().optional().describe("Remove if object/array is empty"),
+    missing: z
+        .string()
+        .optional()
+        .describe("Remove if specified property path is missing"),
+})
+    .strict()
+    .refine((data) => data.empty !== undefined || data.missing !== undefined, {
+    message: "Remove condition must specify either 'empty' or 'missing' property",
+});
+/**
+ * Schema for overlay action - defines a single modification to apply
+ */
+const OverlayActionSchema = z
+    .object({
+    target: z
+        .string()
+        .min(1, "Action target cannot be empty")
+        .startsWith("$", "Action target must be a valid JSONPath starting with '$'")
+        .describe("JSONPath expression pointing to the target element(s) in the OpenAPI document"),
+    description: z
+        .string()
+        .optional()
+        .describe("Human-readable description of what this action does"),
+    update: z
+        .unknown()
+        .optional()
+        .describe("Value to merge/add at the target location"),
+    remove: z
+        .union([z.boolean(), RemoveConditionSchema])
+        .optional()
+        .describe("If true or condition met, remove the target element(s)"),
+})
+    .strict()
+    .refine((data) => (data.update !== undefined) !== (data.remove !== undefined), {
+    message: "Action must specify exactly one of 'update' or 'remove' (not both, not neither)",
+    path: ["update", "remove"],
+});
+/**
+ * Schema for OpenAPI Overlay document
+ * Based on: https://github.com/OAI/Overlay-Specification v1.0.0
+ */
+export const OverlayDocumentSchema = z
+    .object({
+    overlay: z
+        .string()
+        .refine((value) => semver.valid(value) !== null, "Overlay version must be a valid semver version (e.g., '1.0.0', '1.0.0-alpha.1', '1.0.0+build.123')")
+        .describe("Version of the OpenAPI Overlay specification being used"),
+    info: z
+        .object({
+        title: z.string().min(1, "Overlay title cannot be empty"),
+        version: z.string().min(1, "Overlay version cannot be empty"),
+    })
+        .strict()
+        .describe("Metadata about this overlay"),
+    actions: z
+        .array(OverlayActionSchema)
+        .min(1, "Overlay must contain at least one action")
+        .describe("Array of modifications to apply to the OpenAPI document"),
+    extends: z
+        .string()
+        .optional()
+        .describe("URL or path to another overlay to extend"),
+})
+    .strict();
+/**
+ * Schema for OpenAPI document structure
+ * This is intentionally lenient to work with imperfect/incomplete OpenAPI files.
+ * The overlay tool is often used to fix incomplete specs, so we shouldn't be too strict.
+ */
+export const OpenApiDocumentSchema = z
+    .object({
+// Accept any object - we just need it to be valid JSON/YAML that we can manipulate
+})
+    .passthrough()
+    .describe("OpenAPI document (lenient validation)");
+/**
+ * Validate an OpenAPI Overlay document
+ * @throws {Error} with actionable error message if validation fails
+ */
+export function validateOverlayDocument(value) {
+    const result = OverlayDocumentSchema.safeParse(value);
+    if (!result.success) {
+        const errors = result.error.errors
+            .map((err) => {
+            const path = err.path.length > 0 ? ` at '${err.path.join(".")}'` : "";
+            return `  • ${err.message}${path}`;
+        })
+            .join("\n");
+        throw new Error(`Invalid OpenAPI Overlay document:\n${errors}\n\nThe overlay must conform to the OpenAPI Overlay Specification v1.0.0`);
+    }
+    return result.data;
+}
+/**
+ * Validate an OpenAPI document
+ * This validation is intentionally lenient - we only check that it's a valid object.
+ * The overlay tool should work with imperfect OpenAPI files.
+ * @throws {Error} if the document is not a valid object
+ */
+export function validateOpenApiDocument(value) {
+    const result = OpenApiDocumentSchema.safeParse(value);
+    if (!result.success) {
+        throw new Error(`OpenAPI document must be a valid JSON or YAML object. ` +
+            `The file appears to be empty or contains invalid data.`);
+    }
+    return result.data;
+}
+//# sourceMappingURL=validation.js.map

package/dist/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -2,7 +2,7 @@
   "name": "@zuplo/openapi-tools",
   "type": "module",
   "sideEffects": false,
-  "version": "6.65.9",
+  "version": "6.66.2",
   "description": "Tooling for OpenAPI files",
   "repository": {
     "type": "git",
@@ -23,22 +23,21 @@
   "license": "Copyright 2021",
   "scripts": {
     "build": "tsc --build",
-    "test": "mocha",
-    "test:debug": "mocha --timeout 0 --parallel=false"
+    "test": "node --test dist/**/*.spec.js",
+    "test:debug": "node --test --test-timeout 0 dist/**/*.spec.js"
   },
   "dependencies": {
-    "@zuplo/runtime": "6.65.9",
-    "ajv": "^8.17.1",
     "js-yaml": "^4.1.0",
+    "jsonpath-plus": "^10.3.0",
     "openapi-types": "^12.1.3",
-    "uuid": "^11.1.0"
+    "semver": "^7.6.3",
+    "uuid": "^11.1.0",
+    "zod": "^3.24.1"
   },
   "devDependencies": {
-    "@types/chai": "^5.0.0",
-    "@types/mocha": "^10.0.7",
+    "@types/js-yaml": "^4.0.9",
     "@types/node": "^20.14.8",
-    "chai": "^5.1.1",
-    "mocha": "^10.7.3",
+    "@types/semver": "^7.5.8",
     "typescript": "^5.6.2"
   }
 }

package/dist/index.spec.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=index.spec.d.ts.map

package/dist/index.spec.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.spec.d.ts","sourceRoot":"","sources":["../src/index.spec.ts"],"names":[],"mappings":""}