[spec-model] Add toJSONAsync() option to embed errors (Azure#37831)

- Useful when building a large spec model, to process the non-error elements
- Useful for regression-testing changes to spec-model
  - Compare JSON before and after, should match including errors
- Default remains to throw on any error

Author: mikeharder

.github/shared/cmd/spec-model.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-import { ConsoleLogger } from "../src/logger.js";
+import { debugLogger } from "../src/logger.js";
 import { SpecModel } from "../src/spec-model.js";
 
 const USAGE =
@@ -32,8 +32,16 @@ if (args.length > 1) {
 
 const specPath = args[0];
 
-const specModel = new SpecModel(specPath, {
-  logger: new ConsoleLogger(debug),
-});
+// Default to 'undefined' instead of 'defaultLogger', so output is always a valid JSON object (no logging)
+const logger = debug ? debugLogger : undefined;
 
-console.log(JSON.stringify(await specModel.toJSONAsync({ includeRefs, relativePaths }), null, 2));
+const specModel = new SpecModel(specPath, { logger });
+
+console.log(
+  JSON.stringify(
+    // Always embed errors, since we always want to return a valid JSON object instead of throwing
+    await specModel.toJSONAsync({ embedErrors: true, includeRefs, relativePaths }),
+    null,
+    2,
+  ),
+);

.github/shared/src/readme.js

@@ -5,6 +5,7 @@ import yaml from "js-yaml";
 import { marked } from "marked";
 import { dirname, normalize, relative, resolve } from "path";
 import { mapAsync } from "./array.js";
+import { embedError } from "./spec-model.js";
 import { Tag } from "./tag.js";
 
 /**
@@ -207,19 +208,21 @@ export class Readme {
    * @returns {Promise<Object>}
    */
   async toJSONAsync(options) {
-    const tags = await mapAsync(
-      [...(await this.getTags()).values()].sort((a, b) => a.name.localeCompare(b.name)),
-      async (t) => await t.toJSONAsync(options),
-    );
-
-    return {
-      path:
-        options?.relativePaths && this.#specModel
-          ? relative(this.#specModel.folder, this.#path)
-          : this.#path,
-      globalConfig: await this.getGlobalConfig(),
-      tags,
-    };
+    return await embedError(async () => {
+      const tags = await mapAsync(
+        [...(await this.getTags()).values()].sort((a, b) => a.name.localeCompare(b.name)),
+        async (t) => await t.toJSONAsync(options),
+      );
+
+      return {
+        path:
+          options?.relativePaths && this.#specModel
+            ? relative(this.#specModel.folder, this.#path)
+            : this.#path,
+        globalConfig: await this.getGlobalConfig(),
+        tags,
+      };
+    }, options);
   }
 
   /**

.github/shared/src/spec-model.js

@@ -12,6 +12,7 @@ const specModelCache = new Map();
 
 /**
  * @typedef {Object} ToJSONOptions
+ * @prop {boolean} [embedErrors]
  * @prop {boolean} [includeRefs]
  * @prop {boolean} [relativePaths]
  *
@@ -216,15 +217,16 @@ export class SpecModel {
    * @returns {Promise<Object>}
    */
   async toJSONAsync(options) {
-    const readmes = await mapAsync(
-      [...(await this.getReadmes()).values()].sort((a, b) => a.path.localeCompare(b.path)),
-      async (r) => await r.toJSONAsync(options),
-    );
-
-    return {
-      folder: this.#folder,
-      readmes,
-    };
+    return await embedError(async () => {
+      const readmes = await mapAsync(
+        [...(await this.getReadmes()).values()].sort((a, b) => a.path.localeCompare(b.path)),
+        async (r) => await r.toJSONAsync(options),
+      );
+      return {
+        folder: this.#folder,
+        readmes,
+      };
+    }, options);
   }
 
   /**
@@ -234,3 +236,21 @@ export class SpecModel {
     return `SpecModel(${this.#folder}, {logger: ${this.#logger}}})`;
   }
 }
+
+/**
+ * @template T
+ * @param {() => Promise<T>} fn
+ * @param {{embedErrors?: boolean}} [options]
+ * @returns {Promise<T | {error: string}>}
+ */
+export async function embedError(fn, options) {
+  try {
+    return await fn();
+  } catch (error) {
+    if (options?.embedErrors && error instanceof Error) {
+      return { error: error.message };
+    } else {
+      throw error;
+    }
+  }
+}

.github/shared/src/swagger.js

@@ -7,6 +7,7 @@ import { mapAsync } from "./array.js";
 import { example } from "./changed-files.js";
 import { includesFolder } from "./path.js";
 import { SpecModelError } from "./spec-model-error.js";
+import { embedError } from "./spec-model.js";
 
 /**
  * @typedef {import('./spec-model.js').Tag} Tag
@@ -202,20 +203,23 @@ export class Swagger {
    * @returns {Promise<Object>}
    */
   async toJSONAsync(options) {
-    return {
-      path:
-        options?.relativePaths && this.#tag?.readme?.specModel
-          ? relative(this.#tag?.readme?.specModel.folder, this.#path)
-          : this.#path,
-      refs: options?.includeRefs
-        ? await mapAsync(
-            [...(await this.getRefs()).values()].sort((a, b) => a.path.localeCompare(b.path)),
-            async (s) =>
-              // Do not include swagger refs transitively, otherwise we could get in infinite loop
-              await s.toJSONAsync({ ...options, includeRefs: false }),
-          )
-        : undefined,
-    };
+    return await embedError(
+      async () => ({
+        path:
+          options?.relativePaths && this.#tag?.readme?.specModel
+            ? relative(this.#tag?.readme?.specModel.folder, this.#path)
+            : this.#path,
+        refs: options?.includeRefs
+          ? await mapAsync(
+              [...(await this.getRefs()).values()].sort((a, b) => a.path.localeCompare(b.path)),
+              async (s) =>
+                // Do not include swagger refs transitively, otherwise we could get in infinite loop
+                await s.toJSONAsync({ ...options, includeRefs: false }),
+            )
+          : undefined,
+      }),
+      options,
+    );
   }
 
   toString() {

.github/shared/src/tag.js

@@ -1,6 +1,7 @@
 // @ts-check
 
 import { mapAsync } from "./array.js";
+import { embedError } from "./spec-model.js";
 import { Swagger } from "./swagger.js";
 
 /**
@@ -70,13 +71,16 @@ export class Tag {
    * @returns {Promise<Object>}
    */
   async toJSONAsync(options) {
-    return {
-      name: this.#name,
-      inputFiles: await mapAsync(
-        [...this.#inputFiles.values()].sort((a, b) => a.path.localeCompare(b.path)),
-        async (s) => await s.toJSONAsync(options),
-      ),
-    };
+    return await embedError(
+      async () => ({
+        name: this.#name,
+        inputFiles: await mapAsync(
+          [...this.#inputFiles.values()].sort((a, b) => a.path.localeCompare(b.path)),
+          async (s) => await s.toJSONAsync(options),
+        ),
+      }),
+      options,
+    );
   }
 
   toString() {

.github/shared/test/spec-model.test.js

@@ -139,6 +139,16 @@ describe("SpecModel", () => {
     await expect(
       mapAsync([...readmes.values()], async (r) => await r.getTags()),
     ).rejects.toThrowError(/multiple.*tag/i);
+
+    await expect(specModel.toJSONAsync()).rejects.toThrowError(/multiple.*tag/i);
+
+    await expect(specModel.toJSONAsync({ embedErrors: true })).resolves.toMatchObject({
+      readmes: [
+        {
+          error: expect.stringMatching(/multiple.*tag/i),
+        },
+      ],
+    });
   });
 
   describe("getAffectedReadmeTags", () => {
@@ -208,9 +218,32 @@ describe("SpecModel", () => {
       );
       const specModel = new SpecModel(folder, options);
 
-      expect(
+      await expect(
         specModel.getAffectedReadmeTags(resolve(folder, "data-plane/a.json")),
       ).rejects.toThrowError(/is not a valid JSON Schema/i);
+
+      await expect(specModel.toJSONAsync({ includeRefs: true })).rejects.toThrowError(
+        /is not a valid JSON Schema/i,
+      );
+
+      await expect(
+        specModel.toJSONAsync({ embedErrors: true, includeRefs: true }),
+      ).resolves.toMatchObject({
+        readmes: [
+          {
+            tags: [
+              {
+                inputFiles: [
+                  {
+                    error: expect.stringMatching(/is not a valid JSON Schema/i),
+                  },
+                ],
+                name: "package-2021-11-01",
+              },
+            ],
+          },
+        ],
+      });
     });
   });