refactor: inject a proper logger

Author: freakyfelt

package-lock.json

@@ -20,7 +20,7 @@
   "main": "dist/index.cjs",
   "module": "dist/index.js",
   "bin": {
-    "yarpc": "./bin/yarpc-cli.mjs"
+    "yarpc-cli": "./bin/yarpc-cli.mjs"
   },
   "exports": {
     "types": "./dist/index.d.ts",
@@ -33,6 +33,9 @@
   "scripts": {
     "build": "tsup-node src/index.ts",
     "build:check": "tsc --noEmit",
+    "build:examples": "npm run build && npm run build:examples:yaml && npm run build:examples:json",
+    "build:examples:yaml": "bin/yarpc-cli.mjs -i examples/widgets.rpc.yaml -o examples/widgets.oas.yaml -f yaml",
+    "build:examples:json": "bin/yarpc-cli.mjs -i examples/widgets.rpc.yaml -o examples/widgets.oas.json -f json",
     "ci": "npm run build:check && npm run lint:check && npm run test:node && npm run format:check",
     "clean": "rm -rf dist",
     "format": "prettier --write .",
@@ -43,7 +46,7 @@
     "pretest": "npm run lint && tsc --noEmit",
     "test": "npm run build:check && npm run test:node",
     "test:node": "node --loader ts-node/esm --test src/*.test.ts",
-    "posttest": "npm run format"
+    "posttest": "npm run format && npm run build:examples"
   },
   "devDependencies": {
     "@sinclair/typebox": "^0.28.14",
@@ -68,6 +71,8 @@
   },
   "dependencies": {
     "just-intersect": "^4.3.0",
+    "pino": "^8.14.1",
+    "pino-pretty": "^10.0.0",
     "yaml": "^2.3.1"
   }
 }

packages/cli/examples/widgets.oas.yml renamed to packages/cli/examples/widgets.oas.yaml

@@ -1,8 +1,9 @@
 import { readFile, writeFile } from "node:fs/promises";
 import { parseArgs } from "node:util";
+import pino from "pino";
 import YAML from "yaml";
 import { DocumentTransformer } from "./transformers";
-import { RPCDocument } from "./types";
+import { Logger, RPCDocument } from "./types";
 
 const DEFAULT_OUT_PATH = "openapi.json";
 const SUPPORTED_FORMATS = ["json", "yaml"] as const;
@@ -27,14 +28,15 @@ type EmitOpenAPIParams = {
 	input: string;
 	output: string;
 	format: SupportedFormat;
+	logger: Logger;
 };
 
 async function emitOpenAPI(params: EmitOpenAPIParams) {
-	const { input, output, format } = params;
+	const { input, output, format, logger } = params;
 
 	const source = YAML.parse(await readFile(input, "utf8")) as RPCDocument;
 
-	const transformed = await DocumentTransformer.transform(source);
+	const transformed = await DocumentTransformer.transform(source, { logger });
 	let contents;
 
 	if (format === "yaml") {
@@ -51,12 +53,19 @@ async function emitOpenAPI(params: EmitOpenAPIParams) {
 export async function main() {
 	const args = parseArgs({
 		options: {
-			help: { type: "boolean", alias: "h" },
-			version: { type: "boolean", alias: "v" },
-			verbose: { type: "boolean", alias: "V" },
-			input: { type: "string", alias: "i" },
-			output: { type: "string", alias: "o", default: "openapi.json" },
-			format: { type: "string", alias: "f", default: "json" },
+			help: { type: "boolean", short: "h" },
+			version: { type: "boolean", short: "v" },
+			verbose: { type: "boolean", short: "V" },
+			input: { type: "string", short: "i" },
+			output: { type: "string", short: "o", default: "openapi.json" },
+			format: { type: "string", short: "f", default: "json" },
+		},
+	});
+
+	const logger = pino({
+		level: args.values.verbose ? "debug" : "info",
+		transport: {
+			target: "pino-pretty",
 		},
 	});
 
@@ -82,5 +91,10 @@ export async function main() {
 		return;
 	}
 
-	await emitOpenAPI({ format: format as SupportedFormat, input, output });
+	await emitOpenAPI({
+		input,
+		output,
+		format: format as SupportedFormat,
+		logger,
+	});
 }

packages/cli/examples/widgets.rpc.yml renamed to packages/cli/examples/widgets.rpc.yaml

@@ -1,11 +1,11 @@
 import safeGet from "just-safe-get";
 import { RPCDocument, ReferenceObject, SchemaObject } from "./types/index.js";
 
-export type IResolver = {
+export type IRefResolver = {
 	resolve(ref: ReferenceObject): SchemaObject | PromiseLike<SchemaObject>;
 };
 
-export const getDefaultResolver = (doc: RPCDocument): IResolver => ({
+export const getDefaultRefResolver = (doc: RPCDocument): IRefResolver => ({
 	resolve: (ref: ReferenceObject) => {
 		if (!ref.$ref.startsWith("#/components/")) {
 			throw new Error(`Unsupported reference ${ref.$ref}`);

packages/cli/package.json

@@ -1,5 +1,6 @@
 import assert from "node:assert";
 import test from "node:test";
+import pino from "pino";
 import {
 	components,
 	mutations,
@@ -9,6 +10,8 @@ import {
 import { OASDocument, RPCDocument } from "../types/index.js";
 import { DocumentTransformer } from "./document-transformer.js";
 
+const logger = pino({ level: "silent" });
+
 const healthCheck = {
 	"/health": {
 		get: {
@@ -66,20 +69,17 @@ const oasDocument: OASDocument = {
 	components: rpcDocument.components,
 };
 
-const transformer = new DocumentTransformer(rpcDocument);
-
 test("DocumentTransformer#transform", async (t) => {
 	await t.test("transforms an RPC document into an OAS document", async () => {
-		const actual = await transformer.transform();
+		const actual = await DocumentTransformer.transform(rpcDocument, { logger });
 		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(), {
+		await assert.rejects(DocumentTransformer.transform(doc, { logger }), {
 			message: "Missing required yarpc version",
 		});
 	});
@@ -90,8 +90,7 @@ test("DocumentTransformer#transform", async (t) => {
 			const doc = { ...rpcDocument };
 			// @ts-expect-error incorrect yarpc version
 			doc.yarpc = "2.0.0";
-			const transformer = new DocumentTransformer(doc);
-			await assert.rejects(transformer.transform(), {
+			await assert.rejects(DocumentTransformer.transform(doc, { logger }), {
 				message: "Unsupported YARPC version: 2.0.0",
 			});
 		}
@@ -120,8 +119,7 @@ test("DocumentTransformer#transform", async (t) => {
 			},
 		};
 
-		const transformer = new DocumentTransformer(doc);
-		const actual = await transformer.transform();
+		const actual = await DocumentTransformer.transform(doc, { logger });
 		assert.deepStrictEqual(actual, expected);
 	});
 
@@ -136,8 +134,7 @@ test("DocumentTransformer#transform", async (t) => {
 			},
 		};
 
-		const transformer = new DocumentTransformer(doc);
-		const actual = await transformer.transform();
+		const actual = await DocumentTransformer.transform(doc, { logger });
 		assert.deepStrictEqual(actual, oasDocument);
 	});
 
@@ -174,8 +171,7 @@ test("DocumentTransformer#transform", async (t) => {
 			},
 		};
 
-		const transformer = new DocumentTransformer(doc);
-		const actual = await transformer.transform();
+		const actual = await DocumentTransformer.transform(doc, { logger });
 		assert.deepStrictEqual(actual, expected);
 	});
 });

packages/cli/src/cli.ts

@@ -1,5 +1,5 @@
 import intersect from "just-intersect";
-import { getDefaultResolver } from "../resolver.js";
+import { IRefResolver, getDefaultRefResolver } from "../resolver.js";
 import {
 	Logger,
 	OASDocument,
@@ -8,26 +8,39 @@ import {
 } from "../types/index.js";
 import { OperationTransformer } from "./operation-transformer.js";
 
+type TransformerOptions = {
+	logger?: Logger;
+	/** specify a different schema $ref resolver */
+	refResolver?: IRefResolver;
+	/** use this operation transformer instead */
+	operationTransformer?: OperationTransformer;
+};
+
 /**
  * Transforms an RPC document into an OAS document
  */
 export class DocumentTransformer {
-	static transform(doc: RPCDocument): Promise<OASDocument> {
-		return new DocumentTransformer(doc).transform();
+	static transform(
+		doc: RPCDocument,
+		opts: TransformerOptions = {}
+	): Promise<OASDocument> {
+		return new DocumentTransformer(doc, opts).transform();
 	}
 
 	private doc: RPCDocument;
-	private transformer: OperationTransformer;
-	private logger: Logger;
+	private operationTransformer: OperationTransformer;
+	private logger?: Logger;
 
-	constructor(doc: RPCDocument) {
+	constructor(doc: RPCDocument, opts: TransformerOptions = {}) {
 		this.doc = doc;
-		this.logger = console;
-
-		this.transformer = new OperationTransformer({
-			logger: this.logger,
-			resolver: getDefaultResolver(doc),
-		});
+		this.logger = opts.logger;
+
+		this.operationTransformer =
+			opts.operationTransformer ??
+			new OperationTransformer({
+				logger: this.logger ?? console,
+				resolver: opts.refResolver ?? getDefaultRefResolver(doc),
+			});
 	}
 
 	async transform(): Promise<OASDocument> {
@@ -53,14 +66,21 @@ export class DocumentTransformer {
 		};
 	}
 
-	async rpcToPaths(rpc: RPCDocument["operations"]): Promise<PathsObject> {
+	private async rpcToPaths(
+		rpc: RPCDocument["operations"]
+	): Promise<PathsObject> {
 		const paths: PathsObject = {};
 
 		for (const [operationId, operation] of Object.entries(rpc.queries ?? {})) {
 			const httpMethod = operation.method ?? "get";
+			const path = operation.path ?? `/queries/${operationId}`;
+			this.logger?.debug(
+				{ operationId, httpMethod, operation, path },
+				"Transforming query"
+			);
 
-			paths[operation.path ?? `/queries/${operationId}`] = {
-				[httpMethod]: await this.transformer.transformQueryOperation(
+			paths[path] = {
+				[httpMethod]: await this.operationTransformer.transformQueryOperation(
 					operationId,
 					operation
 				),
@@ -71,19 +91,30 @@ export class DocumentTransformer {
 			rpc.mutations ?? {}
 		)) {
 			const httpMethod = operation.method ?? "post";
+			const path = operation.path ?? `/mutations/${operationId}`;
+			this.logger?.debug(
+				{ operationId, httpMethod, operation, path },
+				"Transforming mutation"
+			);
 
-			paths[operation.path ?? `/mutations/${operationId}`] = {
-				[httpMethod]: await this.transformer.transformMutationOperation(
-					operationId,
-					operation
-				),
+			paths[path] = {
+				[httpMethod]:
+					await this.operationTransformer.transformMutationOperation(
+						operationId,
+						operation
+					),
 			};
 		}
 
 		return paths;
 	}
 
-	deepMergePaths(paths: PathsObject, otherPaths: PathsObject): PathsObject {
+	private deepMergePaths(
+		paths: PathsObject,
+		otherPaths: PathsObject
+	): PathsObject {
+		this.logger?.debug({ paths, otherPaths }, "Merging paths");
+
 		const mergedPaths: PathsObject = {
 			...paths,
 		};
@@ -101,7 +132,7 @@ export class DocumentTransformer {
 				Object.keys(mergedPaths[path])
 			);
 			if (duplicate.length > 0) {
-				this.logger.warn(
+				this.logger?.warn(
 					{ path, duplicate },
 					"Duplicate operation(s) will be overwritten"
 				);

packages/cli/src/resolver.ts

@@ -1,5 +1,5 @@
 import assert from "node:assert";
-import { IResolver } from "../resolver.js";
+import { IRefResolver } from "../resolver.js";
 import {
 	Logger,
 	MutationOperationObject,
@@ -23,13 +23,13 @@ const DEFAULT_RESPONSE: ResponseObject = {
 };
 
 type TransformerDeps = {
-	logger: Logger;
-	resolver: IResolver;
+	resolver: IRefResolver;
+	logger?: Logger;
 };
 
 export class OperationTransformer {
-	resolver: IResolver;
-	logger: Logger;
+	resolver: IRefResolver;
+	logger?: Logger;
 
 	constructor({ logger, resolver }: TransformerDeps) {
 		this.logger = logger;
@@ -96,7 +96,7 @@ export class OperationTransformer {
 		operation: RPCOperationObject,
 		parameterDefaults: ParameterDefaults
 	): Promise<OperationObject> {
-		this.logger.debug(
+		this.logger?.debug(
 			{ operationId, operation, parameterDefaults },
 			`Transforming operation "${operationId}"`
 		);
@@ -138,7 +138,7 @@ export class OperationTransformer {
 		input: RPCInputObject,
 		defaults: ParameterDefaults
 	): Promise<TransformOutput> {
-		this.logger.debug({ input, defaults }, "Transforming input");
+		this.logger?.debug({ input, defaults }, "Transforming input");
 
 		const { schema: schemaOrRef, parameters: parameterOverrides = {} } = input;
 		assert(

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

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