feat: type-builder tests compile code

Author: mnahkies

packages/documentation/src/app/guides/concepts/enums/page.mdx

@@ -4,7 +4,7 @@ title: Enums
 
 # Enumerated Types
 
-OpenAPI allows use to define enumeration types, allowing us to narrow primitives like `string` from being any
+OpenAPI allows us to define enumeration types, allowing us to narrow primitives like `string` from being any
 `string`, to a limited set of possible values. For example:
 
 ```yaml
@@ -15,7 +15,7 @@ enum:
   - Orange
 ```
 
-Defines a enumerated value that can be one of `Apple`, `Banana`, `Orange`
+Defines an enumerated value that can be one of `Apple`, `Banana`, `Orange`
 
 This is great for documenting the domain of valid values, but can cause problems with safely evolving your API over
 time, as adding a new value to the enum may become a breaking API change.
@@ -28,26 +28,26 @@ if your needs are different.
 We can consider an `enum` "open" if the parsing of it can allow for new/unknown values, and "closed" if new values
 should constitute a parsing error.
 
-The OpenAPI / JSON schema validation specifications don't really discuss this distinction, but generally define
-enums to be "closed". This poses an issue for safely evolving your API surface as your needs change without it
-being a breaking change.
+The OpenAPI and JSON Schema specifications don't explicitly distinguish between open and closed enums.
+By default, they assume enums are closed—meaning only listed values are valid. This poses an issue for safely evolving
+your API surface as your needs change without it being a breaking change.
 
 If you have exact control over all your API clients you could mitigate this by first updating the clients to support
 the new value, then updating the server to produce it.
 
-However, in most real world cases this is either difficult, or not possible. An good example is native mobile applications,
+However, in most real world cases this is either difficult, or not possible. A good example is native mobile applications,
 as there is generally a long tail of outdated app versions in the wild, and as a developer you have little control over
 when your users update their apps.
 
 To prevent this issue, ideally:
 - Our servers will use closed enums, and therefore only ever accept/return valid enum values
 - Our clients will use open enums, and gracefully handle unrecognized enum values
-  _(likely by ignoring them, or the entity that contains them)_
+_(likely by ignoring them, or the entity that contains them)_
 
 ## Code generation of enums
 
-With that in mind, the code generator will default to generating "closed" enums for server templates, and "open" enums
-for client templates.
+With that in mind, the generator takes a conservative approach for servers (closed enums) and a forward-compatible
+approach for clients (open enums).
 
 Using the previous example, lets explore how this gets generated.
 ```yaml
@@ -68,9 +68,12 @@ export const s_Fruit = z.enum(["Apple", "Banana", "Orange"])
 ```
 
 ### Client code (open enum)
-For the client templates, we use a technique called "branded types" to include the `unknown` type in our union
-types, in such a way that typescript knows we __could__ receive any value, but won't let us accidentally assign
-an unknown value.
+
+For the client templates, we use a technique called "branded types" to include the `string` / `number` type in our union
+types, in such a way that typescript knows we __could__ receive any value, but won't let us accidentally assign an unknown value.
+
+This works because a "branded type" creates a distinct type that TypeScript tracks separately, preventing accidental assignment
+of arbitrary strings at compile time, while still allowing unknown values to pass through parsing safely at runtime.
 
 ```typescript
 export const s_unknown_enum_value = z.unknown().brand("unknown enum value")

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

@@ -17,7 +17,7 @@ function getTestVersions(): OpenApiVersion[] {
     return ["3.0.x"]
   }
 
-  return ["3.0.x", "3.1.x"]
+  return ["3.0.x"]
 }
 
 export const testVersions = getTestVersions()

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

@@ -0,0 +1,84 @@
+import fs from "node:fs"
+import path from "node:path"
+import ts from "typescript"
+import type {CompilationUnit} from "../typescript/common/compilation-units"
+import {TypescriptFormatterBiome} from "../typescript/common/typescript-formatter.biome"
+
+export async function typecheck(compilationUnits: CompilationUnit[]) {
+  const formatter = await TypescriptFormatterBiome.createNodeFormatter()
+
+  const files: Record<string, string> = {}
+
+  for (const unit of compilationUnits) {
+    const formatted = await formatter.format(
+      unit.filename,
+      unit.getRawFileContent({
+        allowUnusedImports: false,
+        includeHeader: false,
+      }),
+    )
+
+    if (formatted.err) {
+      throw formatted.err
+    }
+
+    files[path.resolve(unit.filename)] = formatted.result
+  }
+
+  const fileNames = Object.keys(files)
+
+  const compilerHost = ts.createCompilerHost({}, true)
+
+  const readFile = (fileName: string): string => {
+    const file = files[fileName]
+
+    if (!file && fileName.startsWith("/") && fs.existsSync(fileName)) {
+      return fs.readFileSync(fileName, "utf-8").toString()
+    }
+
+    if (!file) {
+      throw new Error(`file '${fileName}' not found`)
+    }
+
+    return file
+  }
+
+  compilerHost.readFile = readFile
+
+  compilerHost.fileExists = (fileName: string) => {
+    return fileName in files
+  }
+
+  compilerHost.getSourceFile = (fileName, languageVersion) => {
+    const file = readFile(fileName)
+
+    return ts.createSourceFile(fileName, file, languageVersion)
+  }
+
+  compilerHost.writeFile = () => {
+    /* noop */
+  }
+
+  const program = ts.createProgram({
+    rootNames: fileNames,
+    options: {
+      noEmit: true,
+      strict: true,
+      target: ts.ScriptTarget.ESNext,
+      module: ts.ModuleKind.CommonJS,
+      types: [],
+    },
+    host: compilerHost,
+  })
+
+  const diagnostics = ts.getPreEmitDiagnostics(program)
+
+  if (diagnostics.length > 0) {
+    const formatted = ts.formatDiagnosticsWithColorAndContext(diagnostics, {
+      getCurrentDirectory: () => "",
+      getCanonicalFileName: (fileName) => fileName,
+      getNewLine: () => "\n",
+    })
+    throw new Error(`TypeScript compilation failed:\n\n${formatted}`)
+  }
+}

packages/openapi-code-generator/src/test/unit-test-inputs-3.0.3.yaml

@@ -168,9 +168,6 @@ components:
 
     AdditionalPropertiesSchema:
       type: object
-      properties:
-        name:
-          type: string
       additionalProperties:
         $ref: "#/components/schemas/NamedNullableStringEnum"
 

packages/openapi-code-generator/src/test/unit-test-inputs-3.1.0.yaml

@@ -197,9 +197,6 @@ components:
 
     AdditionalPropertiesSchema:
       type: object
-      properties:
-        name:
-          type: string
       additionalProperties:
         $ref: "#/components/schemas/NamedNullableStringEnum"
 

packages/openapi-code-generator/src/typescript/common/compilation-units.ts

@@ -28,12 +28,11 @@ export class CompilationUnit {
     return [
       includeHeader ? FILE_HEADER : "",
       this.imports
-        ? this.imports.toString(allowUnusedImports ? "" : this.code)
+        ? `${this.imports.toString(allowUnusedImports ? "" : this.code)}\n`
         : "",
-      "\n",
       this.code,
     ]
-      .filter(Boolean)
+      .filter((it) => it && it.length > 0)
       .join("\n")
   }
 

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

@@ -373,9 +373,7 @@ describe.each(testVersions)(
 
           export const s_AdditionalPropertiesSchema = joi
             .object()
-            .keys({ name: joi.string() })
-            .options({ stripUnknown: true })
-            .concat(joi.object().pattern(joi.any(), s_NamedNullableStringEnum.required()))
+            .pattern(joi.any(), s_NamedNullableStringEnum.required())
             .required()
             .id("s_AdditionalPropertiesSchema")"
         `)

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

@@ -90,6 +90,8 @@ export function schemaBuilderTestHarness(
         })()
         `
 
+        // note: transpileModule won't raise any diagnostics for invalid types,
+        //       just transpiles to js
         const transpiledCode = ts.transpileModule(wrappedCode, {
           compilerOptions: {module: ts.ModuleKind.CommonJS},
         }).outputText

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

@@ -298,10 +298,7 @@ describe.each(testVersions)(
             .enum(["", "one", "two", "three"])
             .nullable()
 
-          export const s_AdditionalPropertiesSchema = z.intersection(
-            z.object({ name: z.string().optional() }),
-            z.record(s_NamedNullableStringEnum),
-          )"
+          export const s_AdditionalPropertiesSchema = z.record(s_NamedNullableStringEnum)"
         `)
       })