refactor: schema-builders use ISchemaProvider instead of Input (#420)

(following on from #419)

- schema builders no longer depend on `Input`, but rather use
`ISchemaProvider` to make testing easier
- reworks the schema builder unit tests to use the IRModel fixtures

Author: mnahkies

packages/openapi-code-generator/src/core/dependency-graph.ts

@@ -1,4 +1,4 @@
-import type {Input} from "./input"
+import type {ISchemaProvider} from "./input"
 import {logger} from "./logger"
 import type {Reference} from "./openapi-types"
 import type {MaybeIRModel} from "./openapi-types-normalized"
@@ -94,11 +94,11 @@ export type DependencyGraph = {order: string[]; circular: Set<string>}
  *
  * It's not perfect though:
  * - doesn't discover schemas declared in external specifications (eg: shared definition files)
- * @param input
+ * @param schemaProvider
  * @param getNameForRef
  */
 export function buildDependencyGraph(
-  input: Input,
+  schemaProvider: ISchemaProvider,
   getNameForRef: (reference: Reference) => string,
 ): DependencyGraph {
   logger.time("calculate schema dependency graph")
@@ -110,7 +110,7 @@ export function buildDependencyGraph(
   const order: string[] = []
 
   // TODO: this may miss extracted in-line schemas
-  for (const [name, schema] of Object.entries(input.allSchemas())) {
+  for (const [name, schema] of Object.entries(schemaProvider.allSchemas())) {
     remaining.set(
       getNameForRef({$ref: name}),
       getDependenciesFromSchema(schema, getNameForRef),

packages/openapi-code-generator/src/core/input.ts

@@ -38,7 +38,9 @@ export type InputConfig = {
 }
 
 export interface ISchemaProvider {
-  schema(maybeRef: MaybeIRModel): IRModel
+  schema(maybeRef: MaybeIRModel | Reference): IRModel
+  allSchemas(): Record<string, MaybeIRModel>
+  preprocess(maybePreprocess: Reference | xInternalPreproccess): IRPreprocess
 }
 
 export class Input implements ISchemaProvider {

packages/openapi-code-generator/src/core/normalization/parameter-normalizer.spec.ts

@@ -86,15 +86,14 @@ describe("ParameterNormalizer", () => {
       })
 
       it("throws on unsupported style", () => {
-        const param = {
-          name: "id",
-          in: "path",
-          style: "form",
-          schema: {type: "string"},
-        } as any
-        expect(() => parameterNormalizer.normalizeParameter(param)).toThrow(
-          "unsupported parameter style: 'form' for in: 'path'",
-        )
+        expect(() =>
+          parameterNormalizer.normalizeParameter({
+            name: "id",
+            in: "path",
+            style: "form",
+            schema: {type: "string"},
+          }),
+        ).toThrow("unsupported parameter style: 'form' for in: 'path'")
       })
     })
 
@@ -226,7 +225,7 @@ describe("ParameterNormalizer", () => {
       }
 
       loader.parameter.mockImplementation((it) => it as Parameter)
-      loader.schema.mockImplementation((it) => it as any)
+      loader.schema.mockImplementation((it) => it)
       loader.addVirtualType.mockImplementation((_opId, name) =>
         ir.ref(name, "virtual"),
       )
@@ -300,7 +299,7 @@ describe("ParameterNormalizer", () => {
       }
 
       loader.parameter.mockReturnValue(queryParam)
-      loader.schema.mockReturnValue({type: "string"} as any)
+      loader.schema.mockReturnValue({type: "string"})
       loader.addVirtualType.mockImplementation((_operationId, name) =>
         ir.ref(name, "virtual"),
       )
@@ -328,7 +327,7 @@ describe("ParameterNormalizer", () => {
       loader.schema.mockReturnValue({
         type: "array",
         items: {type: "string"},
-      } as any)
+      })
       loader.addVirtualType.mockImplementation((_opId, name) =>
         ir.ref(name, "virtual"),
       )

packages/openapi-code-generator/src/core/openapi-utils.spec.ts

@@ -1,5 +1,10 @@
 import {describe, expect, it} from "@jest/globals"
-import {extractPlaceholders, getNameFromRef, isRef} from "./openapi-utils"
+import {
+  extractPlaceholders,
+  getNameFromRef,
+  getRawNameFromRef,
+  isRef,
+} from "./openapi-utils"
 
 describe("core/openapi-utils", () => {
   describe("#isRef", () => {
@@ -17,6 +22,20 @@ describe("core/openapi-utils", () => {
     })
   })
 
+  describe("#getRawNameFromRef", () => {
+    it("returns the raw name", () => {
+      expect(
+        getRawNameFromRef({$ref: "#/components/schemas/Something"}),
+      ).toEqual("Something")
+    })
+
+    it("throws on an invalid $ref", () => {
+      expect(() => getRawNameFromRef({$ref: "#/"})).toThrow(
+        "no name found in $ref: '#/'",
+      )
+    })
+  })
+
   describe("#getNameFromRef", () => {
     it("includes the given prefix", () => {
       expect(getNameFromRef({$ref: "#/components/schemas/Foo"}, "t_")).toBe(

packages/openapi-code-generator/src/core/openapi-utils.ts

@@ -7,13 +7,18 @@ export function isRef(it: unknown | Reference): it is Reference {
   return Reflect.has(it, "$ref")
 }
 
-export function getNameFromRef({$ref}: Reference, prefix: string): string {
+export function getRawNameFromRef({$ref}: Reference): string {
   const name = $ref.split("/").pop()
 
   if (!name) {
     throw new Error(`no name found in $ref: '${$ref}'`)
   }
 
+  return name
+}
+
+export function getNameFromRef({$ref}: Reference, prefix: string): string {
+  const name = getRawNameFromRef({$ref})
   // todo: this is a hack to workaround reserved words being used as names
   //       can likely improve to selectively apply when a reserved word is used.
   return prefix + name.replace(/[-.]+/g, "_")

packages/openapi-code-generator/src/test/fake-schema-provider.ts

@@ -0,0 +1,44 @@
+import type {ISchemaProvider} from "../core/input"
+import type {
+  IRModel,
+  IRPreprocess,
+  IRRef,
+  MaybeIRModel,
+} from "../core/openapi-types-normalized"
+import {getRawNameFromRef, isRef} from "../core/openapi-utils"
+
+export class FakeSchemaProvider implements ISchemaProvider {
+  private readonly testRefs: Record<string, IRModel> = {}
+
+  registerTestRef(ref: IRRef, model: IRModel) {
+    this.testRefs[ref.$ref] = model
+  }
+
+  schema(maybeRef: MaybeIRModel): IRModel {
+    if (isRef(maybeRef)) {
+      const result = this.testRefs[maybeRef.$ref]
+
+      if (!result) {
+        throw new Error(
+          `FakeSchemaProvider: $ref '${maybeRef.$ref}' is not registered`,
+        )
+      }
+
+      return result
+    }
+
+    return maybeRef
+  }
+
+  allSchemas(): Record<string, MaybeIRModel> {
+    return Object.fromEntries(
+      Object.entries(this.testRefs).map(([$ref, value]) => {
+        return [getRawNameFromRef({$ref}), value]
+      }),
+    )
+  }
+
+  preprocess(): IRPreprocess {
+    return {}
+  }
+}

packages/openapi-code-generator/src/test/input.test-utils.ts

@@ -7,7 +7,6 @@ import {GenericLoader} from "../core/loaders/generic.loader"
 import {OpenapiLoader} from "../core/loaders/openapi-loader"
 import {TypespecLoader} from "../core/loaders/typespec.loader"
 import {logger} from "../core/logger"
-import {SchemaNormalizer} from "../core/normalization/schema-normalizer"
 import {OpenapiValidator} from "../core/openapi-validator"
 
 export type OpenApiVersion = "3.0.x" | "3.1.x"
@@ -59,7 +58,6 @@ export async function unitTestInput(
 
   return {
     input: new Input(loader, config),
-    schemaNormalizer: new SchemaNormalizer(config),
     file,
   }
 }

packages/openapi-code-generator/src/typescript/common/schema-builders/abstract-schema-builder.ts

@@ -2,7 +2,7 @@ import {
   buildDependencyGraph,
   type DependencyGraph,
 } from "../../../core/dependency-graph"
-import type {Input} from "../../../core/input"
+import type {ISchemaProvider} from "../../../core/input"
 import {logger} from "../../../core/logger"
 import type {Reference} from "../../../core/openapi-types"
 import type {
@@ -38,7 +38,7 @@ export abstract class AbstractSchemaBuilder<
 
   protected constructor(
     public readonly filename: string,
-    protected readonly input: Input,
+    protected readonly schemaProvider: ISchemaProvider,
     protected readonly config: SchemaBuilderConfig,
     protected readonly schemaBuilderImports: ImportBuilder,
     typeBuilder: TypeBuilder,
@@ -50,7 +50,9 @@ export abstract class AbstractSchemaBuilder<
   ) {
     this.graph =
       parent?.graph ??
-      buildDependencyGraph(this.input, (it) => this.getSchemaNameFromRef(it))
+      buildDependencyGraph(this.schemaProvider, (it) =>
+        this.getSchemaNameFromRef(it),
+      )
     this.importHelpers(this.schemaBuilderImports)
     this.typeBuilder = typeBuilder.withImports(this.schemaBuilderImports)
   }
@@ -123,6 +125,7 @@ export abstract class AbstractSchemaBuilder<
               })
             }
 
+            /* istanbul ignore next */
             throw new Error("unreachable")
           })
       )
@@ -184,7 +187,7 @@ export abstract class AbstractSchemaBuilder<
       }
 
       if (maybeModel["x-internal-preprocess"]) {
-        const dereferenced = this.input.preprocess(
+        const dereferenced = this.schemaProvider.preprocess(
           maybeModel["x-internal-preprocess"],
         )
         if (dereferenced.deserialize) {
@@ -211,6 +214,7 @@ export abstract class AbstractSchemaBuilder<
         // todo: byte is base64 encoded string, https://spec.openapis.org/registry/format/byte.html
         // model.format === "byte"
         if (model.format === "binary") {
+          // todo: check instanceof Blob?
           result = this.any()
         } else {
           result = this.string(model)
@@ -234,7 +238,7 @@ export abstract class AbstractSchemaBuilder<
         // Note: for zod in particular it's desirable to use merge over intersection
         //       where possible, as it returns a more malleable schema
         const isMergable = model.schemas
-          .map((it) => this.input.schema(it))
+          .map((it) => this.schemaProvider.schema(it))
           .every((it) => it.type === "object" && !it.additionalProperties)
 
         result = isMergable ? this.merge(schemas) : this.intersect(schemas)
@@ -304,7 +308,9 @@ export abstract class AbstractSchemaBuilder<
     }
 
     if (model["x-internal-preprocess"]) {
-      const dereferenced = this.input.preprocess(model["x-internal-preprocess"])
+      const dereferenced = this.schemaProvider.preprocess(
+        model["x-internal-preprocess"],
+      )
       if (dereferenced.deserialize) {
         result = this.preprocess(result, dereferenced.deserialize.fn)
       }

packages/openapi-code-generator/src/typescript/common/schema-builders/joi-schema-builder.integration.spec.ts

@@ -1,19 +1,10 @@
 import vm from "node:vm"
-import {describe, expect, it} from "@jest/globals"
-import type {
-  SchemaArray,
-  SchemaBoolean,
-  SchemaNumber,
-  SchemaObject,
-  SchemaString,
-} from "../../../core/openapi-types"
+import {beforeAll, describe, expect, it} from "@jest/globals"
 import {testVersions} from "../../../test/input.test-utils"
-import type {SchemaBuilderConfig} from "./abstract-schema-builder"
+import {TypescriptFormatterBiome} from "../typescript-formatter.biome"
 import {
-  schemaBuilderTestHarness,
-  schemaNumber,
-  schemaObject,
-  schemaString,
+  type SchemaBuilderIntegrationTestHarness,
+  schemaBuilderIntegrationTestHarness,
 } from "./schema-builder.test-utils"
 
 describe.each(
@@ -32,11 +23,19 @@ describe.each(
     )
   }
 
-  const {getActual, getActualFromModel} = schemaBuilderTestHarness(
-    "joi",
-    version,
-    executeParseSchema,
-  )
+  let getActual: SchemaBuilderIntegrationTestHarness["getActual"]
+
+  beforeAll(async () => {
+    const formatter = await TypescriptFormatterBiome.createNodeFormatter()
+    const harness = schemaBuilderIntegrationTestHarness(
+      "joi",
+      formatter,
+      version,
+      executeParseSchema,
+    )
+
+    getActual = harness.getActual
+  })
 
   it("supports the SimpleObject", async () => {
     const {code, schemas} = await getActual("components/schemas/SimpleObject")

packages/openapi-code-generator/src/typescript/common/schema-builders/joi-schema-builder.ts

@@ -1,4 +1,4 @@
-import type {Input} from "../../../core/input"
+import type {ISchemaProvider} from "../../../core/input"
 import type {Reference} from "../../../core/openapi-types"
 import type {
   IRModel,
@@ -34,16 +34,16 @@ export class JoiBuilder extends AbstractSchemaBuilder<
 
   private includeIntersectHelper = false
 
-  static async fromInput(
+  static async fromSchemaProvider(
     filename: string,
-    input: Input,
+    schemaProvider: ISchemaProvider,
     schemaBuilderConfig: SchemaBuilderConfig,
     schemaBuilderImports: ImportBuilder,
     typeBuilder: TypeBuilder,
   ): Promise<JoiBuilder> {
     return new JoiBuilder(
       filename,
-      input,
+      schemaProvider,
       schemaBuilderConfig,
       schemaBuilderImports,
       typeBuilder,
@@ -54,7 +54,7 @@ export class JoiBuilder extends AbstractSchemaBuilder<
   override withImports(imports: ImportBuilder): JoiBuilder {
     return new JoiBuilder(
       this.filename,
-      this.input,
+      this.schemaProvider,
       this.config,
       this.schemaBuilderImports,
       this.typeBuilder,
@@ -89,7 +89,7 @@ export class JoiBuilder extends AbstractSchemaBuilder<
 
   protected schemaFromRef(reference: Reference): ExportDefinition {
     const name = this.getSchemaNameFromRef(reference)
-    const schemaObject = this.input.schema(reference)
+    const schemaObject = this.schemaProvider.schema(reference)
 
     const value = this.fromModel(schemaObject, true)