fix(cli): deep merge provided OpenAPI paths

Author: freakyfelt

package-lock.json

@@ -19,5 +19,8 @@
     "@typescript-eslint/parser": "^5.59.6",
     "eslint": "^8.40.0",
     "openapi-types": "^12.1.0"
+  },
+  "dependencies": {
+    "just-intersect": "^4.3.0"
   }
 }

package.json

@@ -119,7 +119,7 @@ export const mutations = {
 	createWidget,
 };
 
-export const paths = {
+export const widgetPaths = {
 	"/mutations/createWidget": {
 		post: createWidgetOAS,
 	},

packages/cli/src/__fixtures__/widgets.fixtures.ts

@@ -3,8 +3,8 @@ import test from "node:test";
 import {
 	components,
 	mutations,
-	paths,
 	queries,
+	widgetPaths,
 } from "./__fixtures__/widgets.fixtures.js";
 import { DocumentTransformer } from "./document-transformer.js";
 import { OASDocument, RPCDocument } from "./types";
@@ -23,6 +23,23 @@ const healthCheck = {
 	},
 };
 
+const conflictingPathName = Object.keys(
+	widgetPaths
+)[0] as keyof typeof widgetPaths;
+const conflictingPathMethod = Object.keys(widgetPaths[conflictingPathName])[0];
+
+const conflictingPathOperation = {
+	operationId: "conflictingPathOperation",
+	responses: {
+		200: {
+			description: "OK",
+		},
+		409: {
+			description: "CONFLICT",
+		},
+	},
+};
+
 const rpcDocument: RPCDocument = {
 	yarpc: "1.0.0",
 	info: {
@@ -44,7 +61,7 @@ const oasDocument: OASDocument = {
 	info: rpcDocument.info,
 	paths: {
 		...healthCheck,
-		...paths,
+		...widgetPaths,
 	},
 	components: rpcDocument.components,
 };
@@ -56,4 +73,71 @@ test("DocumentTransformer#transform", async (t) => {
 		const actual = await transformer.transform();
 		assert.deepStrictEqual(actual, oasDocument);
 	});
+
+	await t.test("throws an error if the YARPC version is missing", async () => {
+		const doc = { ...rpcDocument };
+		// @ts-expect-error Missing required yarpc version
+		delete doc.yarpc;
+		const transformer = new DocumentTransformer(doc);
+		await assert.rejects(transformer.transform(), {
+			message: "Missing required yarpc version",
+		});
+	});
+
+	await t.test(
+		"throws an error if the YARPC version is not supported",
+		async () => {
+			const doc = { ...rpcDocument };
+			// @ts-expect-error incorrect yarpc version
+			doc.yarpc = "2.0.0";
+			const transformer = new DocumentTransformer(doc);
+			await assert.rejects(transformer.transform(), {
+				message: "Unsupported YARPC version: 2.0.0",
+			});
+		}
+	);
+
+	await t.test("merge same path different HTTP method", async () => {
+		const doc = {
+			...rpcDocument,
+			paths: {
+				...rpcDocument.paths,
+				[conflictingPathName]: {
+					patch: conflictingPathOperation,
+				},
+			},
+		};
+
+		const expected = {
+			...oasDocument,
+			paths: {
+				...oasDocument.paths,
+				[conflictingPathName]: {
+					// eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+					...oasDocument.paths![conflictingPathName],
+					patch: conflictingPathOperation,
+				},
+			},
+		};
+
+		const transformer = new DocumentTransformer(doc);
+		const actual = await transformer.transform();
+		assert.deepStrictEqual(actual, expected);
+	});
+
+	await t.test("merge same path+HTTP method", async () => {
+		const doc = {
+			...rpcDocument,
+			paths: {
+				...rpcDocument.paths,
+				[conflictingPathName]: {
+					[conflictingPathMethod]: conflictingPathOperation,
+				},
+			},
+		};
+
+		const transformer = new DocumentTransformer(doc);
+		const actual = await transformer.transform();
+		assert.deepStrictEqual(actual, oasDocument);
+	});
 });

packages/cli/src/document-transformer.test.ts

@@ -1,23 +1,31 @@
+import intersect from "just-intersect";
 import { OperationTransformer } from "./operation-transformer.js";
 import { getDefaultResolver } from "./resolver.js";
-import { OASDocument, RPCDocument } from "./types/index.js";
+import {
+	Logger,
+	OASDocument,
+	PathsObject,
+	RPCDocument,
+} from "./types/index.js";
 
 /**
  * Transforms an RPC document into an OAS document
  */
 export class DocumentTransformer {
 	private doc: RPCDocument;
 	private transformer: OperationTransformer;
+	private logger: Logger;
 
 	constructor(doc: RPCDocument) {
 		this.doc = doc;
 		this.transformer = new OperationTransformer({
 			resolver: getDefaultResolver(doc),
 		});
+		this.logger = console;
 	}
 
 	async transform(): Promise<OASDocument> {
-		const { info, paths: oasPaths, operations, yarpc, ...rest } = this.doc;
+		const { info, paths: oasPaths = {}, operations, yarpc, ...rest } = this.doc;
 
 		if (typeof yarpc !== "string") {
 			throw new Error("Missing required yarpc version");
@@ -27,23 +35,20 @@ export class DocumentTransformer {
 			throw new Error(`Unsupported YARPC version: ${String(yarpc)}`);
 		}
 
-		const paths = await this.rpcToPaths(operations);
+		const rpcPaths = await this.rpcToPaths(operations);
+
+		const paths = this.deepMergePaths(oasPaths, rpcPaths);
 
 		return {
 			openapi: "3.1.0",
 			info,
-			paths: {
-				...oasPaths,
-				...paths,
-			},
+			paths,
 			...rest,
 		};
 	}
 
-	async rpcToPaths(
-		rpc: RPCDocument["operations"]
-	): Promise<OASDocument["paths"]> {
-		const paths: OASDocument["paths"] = {};
+	async rpcToPaths(rpc: RPCDocument["operations"]): Promise<PathsObject> {
+		const paths: PathsObject = {};
 
 		for (const [operationId, operation] of Object.entries(rpc.queries)) {
 			paths[`/queries/${operationId}`] = {
@@ -65,4 +70,37 @@ export class DocumentTransformer {
 
 		return paths;
 	}
+
+	deepMergePaths(paths: PathsObject, otherPaths: PathsObject): PathsObject {
+		const mergedPaths: PathsObject = {
+			...paths,
+		};
+
+		Object.entries(otherPaths).forEach(([path, httpOperations]) => {
+			// case 1: non-overlapping paths
+			if (typeof mergedPaths[path] === "undefined") {
+				mergedPaths[path] = httpOperations;
+				return;
+			}
+
+			// detect and report overlapping path+method
+			const duplicate = intersect(
+				Object.keys(httpOperations),
+				Object.keys(mergedPaths[path])
+			);
+			if (duplicate.length > 0) {
+				this.logger.warn(
+					{ path, duplicate },
+					"Duplicate operation(s) will be overwritten"
+				);
+			}
+
+			mergedPaths[path] = {
+				...mergedPaths[path],
+				...httpOperations,
+			};
+		});
+
+		return mergedPaths;
+	}
 }

packages/cli/src/document-transformer.ts

@@ -1,3 +1,8 @@
 export * from "./oas.js";
 export * from "./operations.js";
 export * from "./service.js";
+
+export type Logger = {
+	debug: (...args: unknown[]) => void;
+	warn: (...args: unknown[]) => void;
+};

packages/cli/src/types/index.ts

@@ -9,6 +9,7 @@ export type {
 	MediaTypeObject,
 	OperationObject,
 	ParameterObject,
+	PathsObject,
 	ReferenceObject,
 	ResponseObject,
 	ResponsesObject,