[spec-model] Add Swagger.getTypeSpecGenerated() (Azure#38866)

- Ensure all data is analyzed lazily
- Preparing to enable tseslint.configs.recommendedTypeChecked

Author: mikeharder

.github/shared/eslint.config.js

@@ -14,7 +14,12 @@ export default defineConfig(
       // we only run in node, not browser
       globals: globals.node,
       // required to use tseslint.configs.recommendedTypeChecked
-      parserOptions: { projectService: true },
+      parserOptions: {
+        projectService: true,
+        // ensures the tsconfig path resolves relative to this file
+        // default is process.cwd() when running eslint, which may be incorrect
+        tsconfigRootDir: import.meta.dirname,
+      },
     },
   },
   {

.github/shared/src/swagger.js

@@ -28,6 +28,13 @@ import { embedError } from "./spec-model.js";
  * @property {Object[]} [refs]
  */
 
+const infoSchema = z.object({
+  "x-typespec-generated": z.array(z.object({ emitter: z.string().optional() })).optional(),
+});
+/**
+ * @typedef {import("zod").infer<typeof infoSchema>} InfoObject
+ */
+
 // https://swagger.io/specification/v2/#operation-object
 const operationSchema = z.object({ operationId: z.string().optional() });
 /**
@@ -53,6 +60,7 @@ const pathsSchema = z.record(z.string(), pathSchema);
 
 // https://swagger.io/specification/v2/#swagger-object
 const swaggerSchema = z.object({
+  info: infoSchema.optional(),
   paths: pathsSchema.optional(),
   "x-ms-paths": pathsSchema.optional(),
 });
@@ -100,22 +108,42 @@ 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;
+  /**
+   * Content of swagger file, represented as an untyped JSON object
+   *
+   *  @type {unknown | undefined}
+   */
+  #contentJSON;
+
+  /**
+   * Content of swagger file, represented as a typed object
+   *
+   * @type {SwaggerObject | undefined}
+   * */
+  #contentObject;
 
   /** @type {import('./logger.js').ILogger | undefined} */
   #logger;
 
+  /**
+   * Map of the operations in this swagger, using `operationId` as key
+   *
+   * @type {Map<string, Operation> | undefined}
+   */
+  #operations;
+
   /** @type {string} absolute path */
   #path;
 
+  /**
+   * @type {Map<string, Swagger> | undefined}
+   */
+  #refs;
+
   /** @type {Tag | undefined} Tag that contains this Swagger */
   #tag;
 
@@ -137,48 +165,77 @@ export class Swagger {
     this.#tag = tag;
   }
 
-  async #getData() {
-    if (!this.#data) {
+  /**
+   * @returns {Promise<string>} Content of swagger file, represented as a string, either loaded from `#path` or passed in via `options`
+   * @throws {SpecModelError}
+   */
+  async #getContent() {
+    if (this.#content === undefined) {
       const path = this.#path;
 
-      const content =
-        this.#content ??
-        (await this.#wrapError(
-          async () => await readFile(path, { encoding: "utf8" }),
-          "Failed to read file for swagger",
-        ));
+      this.#content = await this.#wrapError(
+        async () => await readFile(path, { encoding: "utf8" }),
+        "Failed to read file for swagger",
+      );
+    }
+
+    return this.#content;
+  }
 
-      /** @type {Map<string, Operation>} */
-      const operations = new Map();
+  /**
+   * @returns {Promise<unknown>} Content of swagger file, represented as an untyped JSON object
+   * @throws {SpecModelError}
+   */
+  async #getContentJSON() {
+    if (this.#contentJSON === undefined) {
+      const content = await this.#getContent();
 
-      const swaggerJson = await this.#wrapError(
+      this.#contentJSON = await this.#wrapError(
         () => /** @type {unknown} */ (JSON.parse(content)),
         "Failed to parse JSON for swagger",
       );
+    }
+
+    return this.#contentJSON;
+  }
+
+  /**
+   * @returns {Promise<SwaggerObject>} Content of swagger file, represented as a typed object
+   * @throws {SpecModelError}
+   */
+  async #getContentObject() {
+    if (this.#contentObject === undefined) {
+      const contentJSON = await this.#getContentJSON();
 
-      /** @type {SwaggerObject} */
-      const swagger = await this.#wrapError(
-        () => swaggerSchema.parse(swaggerJson),
+      this.#contentObject = await this.#wrapError(
+        () => swaggerSchema.parse(contentJSON),
         "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);
-        }
-      }
+    return this.#contentObject;
+  }
 
-      // 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);
-        }
-      }
+  /**
+   * @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() {
+    if (this.#refs === undefined) {
+      const path = this.#path;
+      const contentJSON = await this.#getContentJSON();
 
       const schema = await this.#wrapError(
         async () =>
-          await $RefParser.resolve(this.#path, swaggerJson, {
+          await $RefParser.resolve(path, contentJSON, {
             resolve: { file: excludeExamples, http: false },
           }),
         "Failed to resolve file for swagger",
@@ -189,7 +246,7 @@ export class Swagger {
         // Exclude ourself
         .filter((p) => resolve(p) !== resolve(this.#path));
 
-      const refs = new Map(
+      this.#refs = new Map(
         refPaths.map((p) => {
           const swagger = new Swagger(p, {
             logger: this.#logger,
@@ -198,49 +255,56 @@ 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.#data;
+    return this.#refs;
   }
 
   /**
-   * @returns {Promise<Map<string, Swagger>>} Map of swaggers referenced from this swagger, using `path` as key
+   * @returns {Promise<Map<string, Swagger>>} Map of examples referenced from this swagger, using `path` as key
    */
-  async getRefs() {
+  async getExamples() {
     const allRefs = await this.#getRefs();
 
     // filter out any paths that are examples
-    const filtered = new Map([...allRefs].filter(([path]) => !example(path)));
+    const filtered = new Map([...allRefs].filter(([path]) => example(path)));
 
     return filtered;
   }
 
-  async #getRefs() {
-    return (await this.#getData()).refs;
-  }
-
   /**
-   * @returns {Promise<Map<string, Swagger>>} Map of examples referenced from this swagger, using `path` as key
+   * @returns {Promise<Map<string, Operation>>} Map of the operations in this swagger, using `operationId` as key
    */
-  async getExamples() {
-    const allRefs = await this.#getRefs();
+  async getOperations() {
+    if (this.#operations === undefined) {
+      const contentObject = await this.#getContentObject();
 
-    // filter out any paths that are examples
-    const filtered = new Map([...allRefs].filter(([path]) => example(path)));
+      this.#operations = new Map();
 
-    return filtered;
+      // Process regular paths
+      if (contentObject.paths) {
+        for (const [path, pathObject] of Object.entries(contentObject.paths)) {
+          this.#addOperations(this.#operations, path, pathObject);
+        }
+      }
+
+      // Process x-ms-paths (Azure extension)
+      if (contentObject["x-ms-paths"]) {
+        for (const [path, pathObject] of Object.entries(contentObject["x-ms-paths"])) {
+          this.#addOperations(this.#operations, path, pathObject);
+        }
+      }
+    }
+
+    return this.#operations;
   }
 
   /**
-   * @returns {Promise<Map<string, Operation>>} Map of the operations in this swagger, using `operationId` as key
+   * @returns {Promise<boolean>} True if the spec was generated from TypeSpec
    */
-  async getOperations() {
-    return (await this.#getData()).operations;
+  async getTypeSpecGenerated() {
+    const contentObject = await this.#getContentObject();
+    return contentObject.info?.["x-typespec-generated"] !== undefined;
   }
 
   /**

.github/shared/test/swagger.test.js

@@ -7,6 +7,7 @@ import { ConsoleLogger } from "../src/logger.js";
 import { Readme } from "../src/readme.js";
 import { SpecModel } from "../src/spec-model.js";
 import { Tag } from "../src/tag.js";
+import { swaggerTypeSpecGenerated } from "./examples.js";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -41,6 +42,26 @@ describe("Swagger", () => {
 
     const refs = await swagger.getRefs();
     expect(new Set(refs.keys())).toEqual(new Set());
+
+    expect(await swagger.getTypeSpecGenerated()).toEqual(false);
+  });
+
+  it("can be created with typespec-generated string content", async () => {
+    const folder = "/fake";
+    const swagger = new Swagger(resolve(folder, "empty.json"), {
+      content: swaggerTypeSpecGenerated,
+    });
+
+    const operations = await swagger.getOperations();
+    expect(new Set(operations.keys())).toEqual(new Set());
+
+    const examples = await swagger.getExamples();
+    expect(new Set(examples.keys())).toEqual(new Set());
+
+    const refs = await swagger.getRefs();
+    expect(new Set(refs.keys())).toEqual(new Set());
+
+    expect(await swagger.getTypeSpecGenerated()).toEqual(true);
   });
 
   it("can be created with sample string content", async () => {
@@ -112,7 +133,12 @@ describe("Swagger", () => {
       tag: new Tag("test-tag", [], { readme: new Readme("/fake/readme.md") }),
     });
 
-    await expect(swagger.getRefs()).rejects.toThrowErrorMatchingInlineSnapshot(`
+    // getRefs() shouldn't throw, since it doesn't care about the zod schema
+    // ensures we are evaluating each data method lazily
+    await expect(swagger.getRefs().then((m) => new Set(m.keys()))).resolves.toEqual(new Set());
+
+    // getOperations() should throw, since the input wasn't valid per the zod schema
+    await expect(swagger.getOperations()).rejects.toThrowErrorMatchingInlineSnapshot(`
       [SpecModelError: Failed to parse schema for swagger: ${resolve("/fake/invalid.json")}
         Problem File: ${resolve("/fake/invalid.json")}
         Readme: ${resolve("/fake/readme.md")}