Merge remote-tracking branch 'origin/main' into keyvault-folder-structure-refactor

Author: v-xuto

.github/shared/eslint.config.js

@@ -6,6 +6,11 @@ import globals from "globals";
 import tseslint from "typescript-eslint";
 
 /** @type {import('eslint').Linter.Config[]} */
-export default defineConfig(eslint.configs.recommended, tseslint.configs.recommended, {
-  languageOptions: { globals: globals.node },
+export default defineConfig(eslint.configs.recommended, tseslint.configs.recommendedTypeChecked, {
+  languageOptions: {
+    // we only run in node, not browser
+    globals: globals.node,
+    // required to use tseslint.configs.recommendedTypeChecked
+    parserOptions: { projectService: true },
+  },
 });

.github/shared/src/readme.js

@@ -2,6 +2,7 @@ import { readFile } from "fs/promises";
 import yaml from "js-yaml";
 import { marked } from "marked";
 import { dirname, normalize, relative, resolve } from "path";
+import { inspect } from "util";
 import * as z from "zod";
 import { mapAsync } from "./array.js";
 import { SpecModelError } from "./spec-model-error.js";
@@ -174,7 +175,7 @@ export class Readme {
           } /* v8 ignore start: defensive rethrow */ else {
             throw error;
           }
-          /* v8 ignore end */
+          /* v8 ignore stop */
         }
 
         if (!parsedObj["input-file"]) {
@@ -274,6 +275,6 @@ export class Readme {
    * @returns {string}
    */
   toString() {
-    return `Readme(${this.#path}, {logger: ${this.#logger}})`;
+    return `Readme(${this.#path}, {logger: ${inspect(this.#logger)}})`;
   }
 }

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

@@ -1,5 +1,6 @@
 import { readdir } from "fs/promises";
 import { resolve } from "path";
+import { inspect } from "util";
 import { flatMapAsync, mapAsync } from "./array.js";
 import { readme } from "./changed-files.js";
 import { Readme } from "./readme.js";
@@ -247,7 +248,7 @@ export class SpecModel {
    * @returns {string}
    */
   toString() {
-    return `SpecModel(${this.#folder}, {logger: ${this.#logger}}})`;
+    return `SpecModel(${this.#folder}, {logger: ${inspect(this.#logger)}}})`;
   }
 }
 

.github/shared/src/swagger.js

@@ -1,9 +1,10 @@
-import $RefParser, { ResolverError } from "@apidevtools/json-schema-ref-parser";
+import $RefParser from "@apidevtools/json-schema-ref-parser";
 import { readFile } from "fs/promises";
 import { dirname, relative, resolve } from "path";
+import { inspect } from "util";
+import { z } from "zod";
 import { mapAsync } from "./array.js";
-import { example } from "./changed-files.js";
-import { includesSegment } from "./path.js";
+import { example, preview } from "./changed-files.js";
 import { SpecModelError } from "./spec-model-error.js";
 import { embedError } from "./spec-model.js";
 
@@ -26,6 +27,42 @@ import { embedError } from "./spec-model.js";
  * @property {Object[]} [refs]
  */
 
+const pathSchema = z.record(z.string(), z.object({ operationId: z.string().optional() }));
+/**
+ * @typedef {import("zod").infer<typeof pathSchema>} PathObject
+ */
+
+const pathsSchema = z.record(z.string(), pathSchema);
+/**
+ * @typedef {import("zod").infer<typeof pathsSchema>} PathsObject
+ */
+
+const swaggerSchema = z.object({
+  paths: pathsSchema.optional(),
+  "x-ms-paths": pathsSchema.optional(),
+});
+/**
+ * @typedef {import("zod").infer<typeof swaggerSchema>} SwaggerObject
+ *
+ * @example
+ * const swagger = {
+ *   "paths": {
+ *     "/foo": {
+ *       "get": {
+ *         "operationId": "Foo_Get"
+ *       },
+ *       "put": {
+ *         "operationId": "Foo_CreateOrUpdate"
+ *       }
+ *     },
+ *     "/bar": { ... }
+ *   },
+ *   "x-ms-paths": {
+ *     "/baz": { ... }
+ *   }
+ * };
+ */
+
 /**
  * @type {import('@apidevtools/json-schema-ref-parser').ResolverOptions}
  */
@@ -44,74 +81,99 @@ const excludeExamples = {
 };
 
 export class Swagger {
+  /**
+   * Content of swagger file, either loaded from `#path` or passed in via `options`.
+   *
+   * Reset to `undefined` after `#data` is loaded to save memory.
+   *
+   * @type {string | undefined}
+   */
+  #content;
+
+  // operations: Map of the operations in this swagger, using `operationId` as key
+  /** @type {{operations: Map<string, Operation>, refs: Map<string, Swagger>} | undefined} */
+  #data;
+
   /** @type {import('./logger.js').ILogger | undefined} */
   #logger;
 
   /** @type {string} absolute path */
   #path;
 
-  /** @type {Map<string, Swagger> | undefined} */
-  #refs;
-
   /** @type {Tag | undefined} Tag that contains this Swagger */
   #tag;
 
-  /** @type {Map<string, Operation> | undefined} map of the operations in this swagger with key as 'operation_id*/
-  #operations;
-
   /**
    * @param {string} path
    * @param {Object} [options]
+   * @param {string} [options.content] If specified, is used instead of reading path from disk
    * @param {import('./logger.js').ILogger} [options.logger]
    * @param {Tag} [options.tag]
    */
   constructor(path, options = {}) {
-    const { logger, tag } = options;
+    const { content, logger, tag } = options;
 
     const rootDir = dirname(tag?.readme?.path ?? "");
     this.#path = resolve(rootDir, path);
+
+    this.#content = content;
     this.#logger = logger;
     this.#tag = tag;
   }
 
-  /**
-   * @returns {Promise<Map<string, Swagger>>}
-   */
-  async getRefs() {
-    const allRefs = await this.#getRefs();
+  async #getData() {
+    if (!this.#data) {
+      const path = this.#path;
 
-    // filter out any paths that are examples
-    const filtered = new Map([...allRefs].filter(([path]) => !example(path)));
+      const content =
+        this.#content ??
+        (await this.#wrapError(
+          async () => await readFile(path, { encoding: "utf8" }),
+          "Failed to read file for swagger",
+        ));
 
-    return filtered;
-  }
+      /** @type {Map<string, Operation>} */
+      const operations = new Map();
 
-  async #getRefs() {
-    if (!this.#refs) {
-      let schema;
-      try {
-        schema = await $RefParser.resolve(this.#path, {
-          resolve: { file: excludeExamples, http: false },
-        });
-      } catch (error) {
-        if (error instanceof ResolverError) {
-          throw new SpecModelError(`Failed to resolve file for swagger: ${this.#path}`, {
-            cause: error,
-            source: error.source,
-            tag: this.#tag?.name,
-            readme: this.#tag?.readme?.path,
-          });
+      const swaggerJson = await this.#wrapError(
+        () => /** @type {unknown} */ (JSON.parse(content)),
+        "Failed to parse JSON for swagger",
+      );
+
+      /** @type {SwaggerObject} */
+      const swagger = await this.#wrapError(
+        () => swaggerSchema.parse(swaggerJson),
+        "Failed to parse schema for swagger",
+      );
+
+      // Process regular paths
+      if (swagger.paths) {
+        for (const [path, pathObject] of Object.entries(swagger.paths)) {
+          this.#addOperations(operations, path, pathObject);
         }
+      }
 
-        throw error;
+      // Process x-ms-paths (Azure extension)
+      if (swagger["x-ms-paths"]) {
+        for (const [path, pathObject] of Object.entries(swagger["x-ms-paths"])) {
+          this.#addOperations(operations, path, pathObject);
+        }
       }
 
+      const schema = await this.#wrapError(
+        async () =>
+          await $RefParser.resolve(this.#path, swaggerJson, {
+            resolve: { file: excludeExamples, http: false },
+          }),
+        "Failed to resolve file for swagger",
+      );
+
       const refPaths = schema
         .paths("file")
         // Exclude ourself
         .filter((p) => resolve(p) !== resolve(this.#path));
 
-      this.#refs = new Map(
+      const refs = new Map(
         refPaths.map((p) => {
           const swagger = new Swagger(p, {
             logger: this.#logger,
@@ -120,13 +182,34 @@ export class Swagger {
           return [swagger.path, swagger];
         }),
       );
+
+      this.#data = { operations, refs };
+
+      // Clear #content to save memory, since it's no longer needed after #data is loaded
+      this.#content = undefined;
     }
 
-    return this.#refs;
+    return this.#data;
+  }
+
+  /**
+   * @returns {Promise<Map<string, Swagger>>} Map of swaggers referenced from this swagger, using `path` as key
+   */
+  async getRefs() {
+    const allRefs = await this.#getRefs();
+
+    // filter out any paths that are examples
+    const filtered = new Map([...allRefs].filter(([path]) => !example(path)));
+
+    return filtered;
+  }
+
+  async #getRefs() {
+    return (await this.#getData()).refs;
   }
 
   /**
-   * @returns {Promise<Map<string, Swagger>>}
+   * @returns {Promise<Map<string, Swagger>>} Map of examples referenced from this swagger, using `path` as key
    */
   async getExamples() {
     const allRefs = await this.#getRefs();
@@ -138,40 +221,22 @@ export class Swagger {
   }
 
   /**
-   * @returns {Promise<Map<string, Operation>>}
+   * @returns {Promise<Map<string, Operation>>} Map of the operations in this swagger, using `operationId` as key
    */
   async getOperations() {
-    if (!this.#operations) {
-      this.#operations = new Map();
-      const content = await readFile(this.#path, "utf8");
-      const swagger = JSON.parse(content);
-      // Process regular paths
-      if (swagger.paths) {
-        for (const [path, pathItem] of Object.entries(swagger.paths)) {
-          this.addOperations(this.#operations, path, pathItem);
-        }
-      }
-
-      // Process x-ms-paths (Azure extension)
-      if (swagger["x-ms-paths"]) {
-        for (const [path, pathItem] of Object.entries(swagger["x-ms-paths"])) {
-          this.addOperations(this.#operations, path, pathItem);
-        }
-      }
-    }
-    return this.#operations;
+    return (await this.#getData()).operations;
   }
 
   /**
    *
    * @param {Map<string, Operation>} operations
    * @param {string} path
-   * @param {any} pathItem
+   * @param {PathObject} pathObject
    * @returns {void}
    */
-  addOperations(operations, path, pathItem) {
-    for (const [method, operation] of Object.entries(pathItem)) {
-      if (typeof operation === "object" && operation.operationId && method !== "parameters") {
+  #addOperations(operations, path, pathObject) {
+    for (const [method, operation] of Object.entries(pathObject)) {
+      if (operation.operationId !== undefined && method !== "parameters") {
         const operationObj = {
           id: operation.operationId,
           httpMethod: method.toUpperCase(),
@@ -200,7 +265,7 @@ export class Swagger {
    * @returns {string} version kind (stable or preview)
    */
   get versionKind() {
-    return includesSegment(this.#path, "preview")
+    return preview(this.#path)
       ? API_VERSION_LIFECYCLE_STAGES.PREVIEW
       : API_VERSION_LIFECYCLE_STAGES.STABLE;
   }
@@ -232,7 +297,34 @@ export class Swagger {
   }
 
   toString() {
-    return `Swagger(${this.#path}, {logger: ${this.#logger}})`;
+    return `Swagger(${this.#path}, {logger: ${inspect(this.#logger)}})`;
+  }
+
+  /**
+   * Returns value of `func()`, wrapping any `Error` in `SpecModelError`
+   *
+   * @template T
+   * @param {() => T | Promise<T>} func
+   * @param {string} message
+   * @returns {Promise<T>}
+   * @throws {SpecModelError}
+   */
+  async #wrapError(func, message) {
+    try {
+      return await func();
+    } catch (error) {
+      if (error instanceof Error) {
+        throw new SpecModelError(`${message}: ${this.#path}`, {
+          cause: error,
+          source: this.#path,
+          tag: this.#tag?.name,
+          readme: this.#tag?.readme?.path,
+        });
+      } /* v8 ignore start: defensive rethrow */ else {
+        throw error;
+      }
+      /* v8 ignore stop */
+    }
   }
 }
 

.github/shared/src/tag.js

@@ -1,3 +1,4 @@
+import { inspect } from "util";
 import { mapAsync } from "./array.js";
 import { embedError } from "./spec-model.js";
 import { Swagger } from "./swagger.js";
@@ -92,6 +93,6 @@ export class Tag {
   }
 
   toString() {
-    return `Tag(${this.#name}, {logger: ${this.#logger}})`;
+    return `Tag(${this.#name}, {logger: ${inspect(this.#logger)}})`;
   }
 }