api 7.0.0-alpha.2 → 7.0.0-alpha.5

package/src/codegen/languages/{typescript.ts → typescript/index.ts}

@@ -1,19 +1,20 @@
-import type Storage from '../../storage';
-import type { InstallerOptions } from '../language';
+import type Storage from '../../../storage.js';
+import type { InstallerOptions } from '../../codegenerator.js';
 import type Oas from 'oas';
 import type Operation from 'oas/operation';
 import type { HttpMethods, SchemaObject } from 'oas/rmoas.types';
 import type { SemVer } from 'semver';
 import type {
   ClassDeclaration,
+  Directory,
   JSDocStructure,
   JSDocTagStructure,
   OptionalKind,
   ParameterDeclarationStructure,
 } from 'ts-morph';
-import type { PackageJson } from 'type-fest';
+import type { Options } from 'tsup';
+import type { JsonObject, PackageJson, TsConfigJson } from 'type-fest';
 
-import fs from 'node:fs';
 import path from 'node:path';
 
 import execa from 'execa';
@@ -21,15 +22,10 @@ import setWith from 'lodash.setwith';
 import semver from 'semver';
 import { IndentationText, Project, QuoteKind, ScriptTarget, VariableDeclarationKind } from 'ts-morph';
 
-import logger from '../../logger';
-import CodeGeneratorLanguage from '../language';
+import logger from '../../../logger.js';
+import CodeGenerator from '../../codegenerator.js';
 
-import { docblockEscape, generateTypeName, wordWrap } from './typescript/util';
-
-export interface TSGeneratorOptions {
-  compilerTarget?: 'cjs' | 'esm';
-  outputJS?: boolean;
-}
+import { docblockEscape, generateTypeName, wordWrap } from './util.js';
 
 interface OperationTypeHousing {
   operation: Operation;
@@ -45,13 +41,24 @@ interface OperationTypeHousing {
   };
 }
 
-export default class TSGenerator extends CodeGeneratorLanguage {
+/**
+ * This is the conversion prefix that we add to all `$ref` pointers we find in generated JSON
+ * Schema.
+ *
+ * Because the pointer name is a string we want to have it reference the schema constant we're
+ * adding into the codegen'd schema file. As there's no way, not even using `eval()` in this case,
+ * to convert a string to a constant we're prefixing them with this so we can later remove it and
+ * rewrite the value to a literal. eg. `'Pet'` becomes `Pet`.
+ *
+ * And because our TypeScript type name generator properly ignores `:`, this is safe to prepend to
+ * all generated type names.
+ */
+const REF_PLACEHOLDER = '::convert::';
+const REF_PLACEHOLDER_REGEX = /"::convert::([a-zA-Z_$\\d]*)"/g;
+
+export default class TSGenerator extends CodeGenerator {
   project: Project;
 
-  outputJS: boolean;
-
-  compilerTarget: 'cjs' | 'esm';
-
   types: Map<string, string>;
 
   sdk!: ClassDeclaration;
@@ -70,101 +77,61 @@ export default class TSGenerator extends CodeGeneratorLanguage {
 
   usesHTTPMethodRangeInterface = false;
 
-  constructor(spec: Oas, specPath: string, identifier: string, opts: TSGeneratorOptions = {}) {
-    const options: { compilerTarget: 'cjs' | 'esm'; outputJS: boolean } = {
-      outputJS: false,
-      compilerTarget: 'cjs',
-      ...opts,
-    };
-
-    if (!options.outputJS) {
-      // TypeScript compilation will always target towards ESM-like imports and exports.
-      options.compilerTarget = 'esm';
-    }
-
+  constructor(spec: Oas, specPath: string, identifier: string) {
     super(spec, specPath, identifier);
 
     this.requiredPackages = {
-      api: {
-        reason: "Required for the `@readme/api-core` library that the codegen'd SDK uses for making requests.",
+      '@readme/api-core': {
+        reason: "The core magic of your codegen'd SDK and is what is used for making requests.",
         url: 'https://npm.im/api',
+        version:
+          // When running unit tests we're installing `@readme/api-core` but because that package
+          // source lives in this repository NPM will throw a gnarly "Cannot set properties of null
+          // (setting 'dev')" workspace error message because we're creating a funky circular
+          // dependency.
+          process.env.NODE_ENV === 'test'
+            ? `file:${path.relative(__dirname, path.dirname(require.resolve('@readme/api-core/package.json')))}`
+            : '^7.0.0',
       },
       'json-schema-to-ts': {
         reason: 'Required for TypeScript type handling.',
         url: 'https://npm.im/json-schema-to-ts',
+        version: '^2.9.2',
       },
       oas: {
         reason: 'Used within `@readme/api-core` and is also loaded for TypeScript types.',
         url: 'https://npm.im/oas',
+        version: '^23.0.0',
       },
     };
 
     this.project = new Project({
-      manipulationSettings: {
-        indentationText: IndentationText.TwoSpaces,
-        quoteKind: QuoteKind.Single,
-      },
       compilerOptions: {
-        // If we're exporting a TypeScript SDK then we don't need to pollute the codegen directory
-        // with unnecessary declaration `.d.ts` files.
-        declaration: options.outputJS,
         outDir: 'dist',
         resolveJsonModule: true,
-        target: options.compilerTarget === 'cjs' ? ScriptTarget.ES5 : ScriptTarget.ES2020,
-
-        // If we're compiling to a CJS target then we need to include this compiler option
-        // otherwise TS will attempt to load our `openapi.json` import with a `.default` property
-        // which doesn't exist. `esModuleInterop` wraps imports in a small `__importDefault`
-        // function that does some determination to see if the module has a default export or not.
-        //
-        // Basically without this option CJS code will fail.
-        ...(options.compilerTarget === 'cjs' ? { esModuleInterop: true } : {}),
+        target: ScriptTarget.ES2022,
       },
+      manipulationSettings: {
+        indentationText: IndentationText.TwoSpaces,
+        quoteKind: QuoteKind.Single,
+      },
+      useInMemoryFileSystem: true,
     });
 
-    this.compilerTarget = options.compilerTarget;
-    this.outputJS = options.outputJS;
-
     this.types = new Map();
     this.schemas = {};
   }
 
-  async installer(storage: Storage, opts: InstallerOptions = {}): Promise<void> {
+  // eslint-disable-next-line class-methods-use-this
+  async install(storage: Storage, opts: InstallerOptions = {}): Promise<void> {
     const installDir = storage.getIdentifierStorageDir();
 
-    const info = this.spec.getDefinition().info;
-    let pkgVersion = semver.coerce(info.version);
-    if (!pkgVersion) {
-      // If the version that's in `info.version` isn't compatible with semver NPM won't be able to
-      // handle it properly so we need to fallback to something it can.
-      pkgVersion = semver.coerce('0.0.0') as SemVer;
-    }
-
-    const pkg: PackageJson = {
-      name: `@api/${storage.identifier}`,
-      version: pkgVersion.version,
-      main: `./index.${this.outputJS ? 'js' : 'ts'}`,
-      types: './index.d.ts', // Types are always present regardless if you're getting compiled JS.
-    };
-
-    fs.writeFileSync(path.join(installDir, 'package.json'), JSON.stringify(pkg, null, 2));
-
     const npmInstall = ['install', '--save', opts.dryRun ? '--dry-run' : ''].filter(Boolean);
 
-    // This will install packages required for the SDK within its installed directory in `.apis/`.
-    await execa('npm', [...npmInstall, ...Object.keys(this.requiredPackages)].filter(Boolean), {
-      cwd: installDir,
-    }).then(res => {
-      if (opts.dryRun) {
-        (opts.logger ? opts.logger : logger)(res.command);
-        (opts.logger ? opts.logger : logger)(res.stdout);
-      }
-    });
-
     // This will install the installed SDK as a dependency within the current working directory,
     // adding `@api/<sdk identifier>` as a dependency there so you can load it with
     // `require('@api/<sdk identifier>)`.
-    return execa('npm', [...npmInstall, installDir].filter(Boolean))
+    await execa('npm', [...npmInstall, installDir].filter(Boolean))
       .then(res => {
         if (opts.dryRun) {
           (opts.logger ? opts.logger : logger)(res.command);
@@ -172,6 +139,17 @@ export default class TSGenerator extends CodeGeneratorLanguage {
         }
       })
       .catch(err => {
+        // If `npm install` throws this error it always happens **after** our dependencies have been
+        // installed and is an annoying quirk that sometimes occurs when installing a package within
+        // our workspace as we're creating a circular dependency on `@readme/api-core`.
+        if (
+          process.env.NODE_ENV === 'test' &&
+          err.message.includes("npm ERR! Cannot set properties of null (setting 'dev')")
+        ) {
+          (opts.logger ? opts.logger : logger)("npm threw an error but we're ignoring it");
+          return;
+        }
+
         if (opts.dryRun) {
           (opts.logger ? opts.logger : logger)(err.message);
           return;
@@ -182,39 +160,46 @@ export default class TSGenerator extends CodeGeneratorLanguage {
   }
 
   /**
-   * Compile the current OpenAPI definition into a TypeScript library.
+   * Compile the TS code we generated into JS for use in CJS and ESM environments.
    *
    */
-  async generator() {
-    const sdkSource = this.createSourceFile();
+  // eslint-disable-next-line class-methods-use-this
+  async compile(storage: Storage, opts: InstallerOptions = {}): Promise<void> {
+    const installDir = storage.getIdentifierStorageDir();
+
+    await execa('npx', ['tsup'], {
+      cwd: installDir,
+    })
+      .then(res => {
+        if (opts.dryRun) {
+          (opts.logger ? opts.logger : logger)(res.command);
+          (opts.logger ? opts.logger : logger)(res.stdout);
+        }
+      })
+      .catch(err => {
+        if (opts.dryRun) {
+          (opts.logger ? opts.logger : logger)(err.message);
+          return;
+        }
+
+        throw err;
+      });
+  }
+
+  /**
+   * Generate the current OpenAPI definition into a TypeScript library.
+   *
+   */
+  async generate() {
+    const srcDirectory = this.project.createDirectory('src');
+    const sdkSource = this.createSDKSource(srcDirectory);
+
+    this.createPackageJSON();
+    this.createTSConfig();
 
     if (Object.keys(this.schemas).length) {
-      this.createSchemasFile();
-      this.createTypesFile();
-
-      /**
-       * Export all of our available types so they can be used in SDK implementations. Types are
-       * exported individually because TS has no way right now of allowing us to do
-       * `export type * from './types'` on a non-named entry.
-       *
-       * Types in the main entry point are only being exported for TS outputs as JS users won't be
-       * able to use them and it clashes with the default SDK export present.
-       *
-       * @see {@link https://github.com/microsoft/TypeScript/issues/37238}
-       * @see {@link https://github.com/readmeio/api/issues/588}
-       */
-      if (!this.outputJS) {
-        const types = Array.from(this.types.keys());
-        types.sort();
-
-        sdkSource.addExportDeclarations([
-          {
-            isTypeOnly: true,
-            namedExports: types,
-            moduleSpecifier: './types',
-          },
-        ]);
-      }
+      this.createSchemasFile(srcDirectory);
+      this.createTypesFile(srcDirectory);
     } else {
       // If we don't have any schemas then we shouldn't import a `types` file that doesn't exist.
       sdkSource
@@ -232,46 +217,19 @@ export default class TSGenerator extends CodeGeneratorLanguage {
         ?.replaceWithText("import type { ConfigOptions, FetchResponse } from '@readme/api-core';");
     }
 
-    if (this.outputJS) {
-      return this.project
-        .emitToMemory()
-        .getFiles()
-        .map(sourceFile => {
-          const file = path.basename(sourceFile.filePath);
-          if (file === 'schemas.js' || file === 'types.js') {
-            // If we're generating a JS SDK then we don't need to generate these two files as the
-            // user will have `.d.ts` files for them instead.
-            return {};
-          }
-
-          let code = sourceFile.text;
-          if (file === 'index.js' && this.compilerTarget === 'cjs') {
-            /**
-             * There's an annoying quirk with `ts-morph` where if we're exporting a default export
-             * to a CJS environment, it'll export it as `exports.default`. Because we don't want
-             * folks in these environments to have to load their SDKs with
-             * `require('@api/sdk').default` we're overriding that here to change it to being the
-             * module exports.
-             *
-             * `ts-morph` unfortunately doesn't give us any options for programatically doing this
-             * so we need to resort to modifying the emitted JS code.
-             */
-            code = code
-              .replace(/Object\.defineProperty\(exports, '__esModule', { value: true }\);\n/, '')
-              .replace('exports.default = createSDK;', 'module.exports = createSDK;');
-          }
-
-          return {
-            [file]: code,
-          };
-        })
-        .reduce((prev, next) => Object.assign(prev, next));
-    }
-
     return [
-      ...this.project.getSourceFiles().map(sourceFile => ({
-        [sourceFile.getBaseName()]: sourceFile.getFullText(),
-      })),
+      ...this.project.getSourceFiles().map(sourceFile => {
+        // `getFilePath` will always return a string that contains a preceeding directory separator
+        // however when we're creating these codegen'd files that may cause us to create that file
+        // in the root directory (because it's preceeded by a `/`). We don't want that to happen so
+        // we're slicing off that first character.
+        let filePath = sourceFile.getFilePath().toString();
+        filePath = filePath.substring(1);
+
+        return {
+          [filePath]: sourceFile.getFullText(),
+        };
+      }),
 
       // Because we're returning the raw source files for TS generation we also need to separately
       // emit out our declaration files so we can put those into a separate file in the installed
@@ -289,10 +247,10 @@ export default class TSGenerator extends CodeGeneratorLanguage {
    * Create our main SDK source file.
    *
    */
-  createSourceFile() {
+  private createSDKSource(sourceDirectory: Directory) {
     const { operations } = this.loadOperationsAndMethods();
 
-    const sourceFile = this.project.createSourceFile('index.ts', '');
+    const sourceFile = sourceDirectory.createSourceFile('index.ts', '');
 
     sourceFile.addImportDeclarations([
       // This import will be automatically removed later if the SDK ends up not having any types.
@@ -425,7 +383,7 @@ sdk.server('https://eu.api.example.com/v14');`),
         {
           name: 'createSDK',
           initializer: writer => {
-            // `ts-morph` doesn't have any way to cleanly create an IFEE.
+            // `ts-morph` doesn't have any way to cleanly create an IIFE.
             writer.writeLine('(() => { return new SDK(); })()');
             return writer;
           },
@@ -434,49 +392,154 @@ sdk.server('https://eu.api.example.com/v14');`),
     });
 
     sourceFile.addExportAssignment({
-      // Because CJS targets have `createSDK` exported with `module.exports`, but the TS type side
-      // of things to work right we need to set this as `export =`. Thankfully `ts-morph` will
-      // handle this accordingly and still create our JS file with `module.exports` and not
-      // `export =` -- only TS types will have this export style.
-      isExportEquals: this.compilerTarget === 'cjs' && this.outputJS,
+      // Because we're exporting `createSDK` as an IIFE constant we need to have it exported as
+      // `export default createSDK`. `addExportAssignment` by default wants it exported as
+      // `export = createSDK`, which will throw TS errors because we may also be exporting types in
+      // the `./types.ts` file.
+      isExportEquals: false,
       expression: 'createSDK',
     });
 
     return sourceFile;
   }
 
+  /**
+   * Create the `tsconfig.json` file that will allow this SDK to be compiled for use.
+   *
+   */
+  createTSConfig() {
+    const sourceFile = this.project.createSourceFile('tsconfig.json', '');
+
+    const config: TsConfigJson = {
+      compilerOptions: {
+        checkJs: true,
+        esModuleInterop: true,
+        module: 'NodeNext',
+        resolveJsonModule: true,
+      },
+      include: ['./src/**/*'],
+      exclude: ['dist'],
+    };
+
+    sourceFile.addStatements(JSON.stringify(config, null, 2));
+
+    return sourceFile;
+  }
+
+  /**
+   * Create the `package.json` file that will ultimately make this SDK available to use.
+   *
+   */
+  createPackageJSON() {
+    const sourceFile = this.project.createSourceFile('package.json', '');
+
+    const hasTypes = !!Object.keys(this.schemas).length;
+
+    const info = this.spec.getDefinition().info;
+    let pkgVersion = semver.coerce(info.version);
+    if (!pkgVersion) {
+      // If the version that's in `info.version` isn't compatible with semver NPM won't be able to
+      // handle it properly so we need to fallback to something it can.
+      pkgVersion = semver.coerce('0.0.0') as SemVer;
+    }
+
+    const tsupOptions: Options = {
+      cjsInterop: true,
+      clean: true,
+      dts: true,
+      entry: [
+        './src/index.ts',
+        // If this SDK has schemas and generated types then we should also export those too so
+        // they're available to use.
+        hasTypes ? './src/types.ts' : '',
+      ].filter(Boolean),
+      // TODO: figure this out
+      // external: ['@readme/api-core'],
+      format: ['esm', 'cjs'],
+      minify: false,
+      shims: true,
+      sourcemap: true,
+      splitting: true,
+    };
+
+    const dependencies = Object.entries(this.requiredPackages)
+      .map(([dep, { version }]) => ({ [dep]: version }))
+      .reduce((prev, next) => Object.assign(prev, next));
+
+    const pkg: PackageJson = {
+      name: `@api/${this.identifier}`,
+      version: pkgVersion.version,
+      main: './dist/index.js',
+      types: './dist/index.d.ts',
+      module: './dist/index.mts',
+      exports: {
+        '.': {
+          import: './dist/index.mjs',
+          require: './dist/index.js',
+        },
+        ...(hasTypes
+          ? {
+              './types': {
+                import: './dist/types.d.mts',
+                require: './dist/types.d.ts',
+              },
+            }
+          : {}),
+      },
+      dependencies,
+      tsup: tsupOptions as JsonObject,
+    };
+
+    sourceFile.addStatements(JSON.stringify(pkg, null, 2));
+
+    return sourceFile;
+  }
+
   /**
    * Create our main schemas file. This is where all of the JSON Schema that our TypeScript typing
    * infrastructure sources its data from. Without this there are no types.
    *
    */
-  createSchemasFile() {
-    const sourceFile = this.project.createSourceFile('schemas.ts', '');
+  private createSchemasFile(sourceDirectory: Directory) {
+    const sourceFile = sourceDirectory.createSourceFile('schemas.ts', '');
+    const schemasDir = sourceDirectory.createDirectory('schemas');
 
     const sortedSchemas = new Map(Array.from(Object.entries(this.schemas)).sort());
 
     Array.from(sortedSchemas).forEach(([schemaName, schema]) => {
-      sourceFile.addVariableStatement({
+      const schemaFile = schemasDir.createSourceFile(`${schemaName}.ts`);
+
+      // Because we're chunking our schemas into a `schemas/` directory we need to add imports
+      // for these schemas into our main `schemas.ts` file.`
+      sourceFile.addImportDeclaration({
+        defaultImport: schemaName,
+        moduleSpecifier: `./schemas/${schemaName}`,
+      });
+
+      let str = JSON.stringify(schema);
+      const referencedSchemas = str.match(REF_PLACEHOLDER_REGEX)?.map(s => s.replace(REF_PLACEHOLDER_REGEX, '$1'));
+      if (referencedSchemas) {
+        referencedSchemas.sort();
+        referencedSchemas.forEach(ref => {
+          // Because this schema is referenced from another file we need to create an `import`
+          // declaration for it.
+          schemaFile.addImportDeclaration({
+            defaultImport: ref,
+            moduleSpecifier: `./${ref}`,
+          });
+        });
+      }
+
+      // Load the schema into the schema file within the `schemas/` directory.
+      schemaFile.addVariableStatement({
         declarationKind: VariableDeclarationKind.Const,
         declarations: [
           {
             name: schemaName,
             initializer: writer => {
-              /**
-               * This is the conversion prefix that we add to all `$ref` pointers we find in
-               * generated JSON Schema.
-               *
-               * Because the pointer name is a string we want to have it reference the schema
-               * constant we're adding into the codegen'd schema file. As there's no way, not even
-               * using `eval()` in this case, to convert a string to a constant we're prefixing
-               * them with this so we can later remove it and rewrite the value to a literal.
-               * eg. `'Pet'` becomes `Pet`.
-               *
-               * And because our TypeScript type name generator properly ignores `:`, this is safe
-               * to prepend to all generated type names.
-               */
-              let str = JSON.stringify(schema);
-              str = str.replace(/"::convert::([a-zA-Z_$\\d]*)"/g, '$1');
+              // We can't have `::convert::<schemaName>` variables within these schema files so we
+              // need to clean them up.
+              str = str.replace(REF_PLACEHOLDER_REGEX, '$1');
 
               writer.writeLine(`${str} as const`);
               return writer;
@@ -484,8 +547,11 @@ sdk.server('https://eu.api.example.com/v14');`),
           },
         ],
       });
+
+      schemaFile.addStatements(`export default ${schemaName}`);
     });
 
+    // Export all of our schemas from inside the main `schemas.ts` file.
     sourceFile.addStatements(`export { ${Array.from(sortedSchemas.keys()).join(', ')} }`);
 
     return sourceFile;
@@ -498,8 +564,8 @@ sdk.server('https://eu.api.example.com/v14');`),
    *
    * @see {@link https://npm.im/json-schema-to-ts}
    */
-  createTypesFile() {
-    const sourceFile = this.project.createSourceFile('types.ts', '');
+  private createTypesFile(sourceDirectory: Directory) {
+    const sourceFile = sourceDirectory.createSourceFile('types.ts', '');
 
     sourceFile.addImportDeclarations([
       { defaultImport: 'type { FromSchema }', moduleSpecifier: 'json-schema-to-ts' },
@@ -513,25 +579,11 @@ sdk.server('https://eu.api.example.com/v14');`),
     return sourceFile;
   }
 
-  /**
-   * Add a new JSDoc `@tag` to an existing docblock.
-   *
-   */
-  static addTagToDocblock(docblock: OptionalKind<JSDocStructure>, tag: OptionalKind<JSDocTagStructure>) {
-    const tags = docblock.tags ?? [];
-    tags.push(tag);
-
-    return {
-      ...docblock,
-      tags,
-    };
-  }
-
   /**
    * Create operation accessors on the SDK.
    *
    */
-  createOperationAccessor(
+  private createOperationAccessor(
     operation: Operation,
     operationId: string,
     paramTypes?: OperationTypeHousing['types']['params'],
@@ -556,7 +608,7 @@ sdk.server('https://eu.api.example.com/v14');`),
       };
 
       if (summary && description) {
-        docblock = TSGenerator.addTagToDocblock(docblock, {
+        docblock = TSGenerator.#addTagToDocblock(docblock, {
           tagName: 'summary',
           text: docblockEscape(wordWrap(summary)),
         });
@@ -609,7 +661,7 @@ sdk.server('https://eu.api.example.com/v14');`),
             }
 
             if (Number(statusPrefix) >= 4) {
-              docblock = TSGenerator.addTagToDocblock(docblock, {
+              docblock = TSGenerator.#addTagToDocblock(docblock, {
                 tagName: 'throws',
                 text: `FetchError<${status}, ${responseType}>${
                   responseDescription ? docblockEscape(wordWrap(` ${responseDescription}`)) : ''
@@ -626,7 +678,7 @@ sdk.server('https://eu.api.example.com/v14');`),
           // 400 and 500 status code families are thrown as exceptions so adding them as a possible
           // return type isn't valid.
           if (Number(status) >= 400) {
-            docblock = TSGenerator.addTagToDocblock(docblock, {
+            docblock = TSGenerator.#addTagToDocblock(docblock, {
               tagName: 'throws',
               text: `FetchError<${status}, ${responseType}>${
                 responseDescription ? docblockEscape(wordWrap(` ${responseDescription}`)) : ''
@@ -736,7 +788,7 @@ sdk.server('https://eu.api.example.com/v14');`),
    * along with every HTTP method that's in use.
    *
    */
-  loadOperationsAndMethods() {
+  private loadOperationsAndMethods() {
     const operations: Record</* operationId */ string, OperationTypeHousing> = {};
     const methods = new Set<HttpMethods>();
 
@@ -777,7 +829,7 @@ sdk.server('https://eu.api.example.com/v14');`),
    * usable TypeScript types.
    *
    */
-  prepareParameterTypesForOperation(operation: Operation, operationId: string) {
+  private prepareParameterTypesForOperation(operation: Operation, operationId: string) {
     const schemas = operation.getParametersAsJSONSchema({
       includeDiscriminatorMappingRefs: false,
       mergeIntoBodyAndMetadata: true,
@@ -789,7 +841,7 @@ sdk.server('https://eu.api.example.com/v14');`),
           const typeName = generateTypeName(s['x-readme-ref-name']);
           this.addSchemaToExport(s, typeName, typeName);
 
-          return `::convert::${typeName}` as SchemaObject;
+          return `${REF_PLACEHOLDER}${typeName}` as SchemaObject;
         }
 
         return s;
@@ -808,10 +860,10 @@ sdk.server('https://eu.api.example.com/v14');`),
       .map(([paramType, schema]: [string, string | SchemaObject]) => {
         let typeName;
 
-        if (typeof schema === 'string' && schema.startsWith('::convert::')) {
+        if (typeof schema === 'string' && schema.startsWith(REF_PLACEHOLDER)) {
           // If this schema is a string and has our conversion prefix then we've already created
           // a type for it.
-          typeName = schema.replace('::convert::', '');
+          typeName = schema.replace(REF_PLACEHOLDER, '');
         } else {
           typeName = generateTypeName(operationId, paramType, 'param');
           this.addSchemaToExport(schema as SchemaObject, typeName, `${generateTypeName(operationId)}.${paramType}`);
@@ -830,7 +882,7 @@ sdk.server('https://eu.api.example.com/v14');`),
    * Compile the response schemas for an API operation into usable TypeScript types.
    *
    */
-  prepareResponseTypesForOperation(operation: Operation, operationId: string) {
+  private prepareResponseTypesForOperation(operation: Operation, operationId: string) {
     const responseStatusCodes = operation.getResponseStatusCodes();
     if (!responseStatusCodes.length) {
       return undefined;
@@ -847,7 +899,7 @@ sdk.server('https://eu.api.example.com/v14');`),
               const typeName = generateTypeName(s['x-readme-ref-name']);
               this.addSchemaToExport(s, typeName, `${typeName}`);
 
-              return `::convert::${typeName}` as SchemaObject;
+              return `${REF_PLACEHOLDER}${typeName}` as SchemaObject;
             }
 
             return s;
@@ -868,10 +920,10 @@ sdk.server('https://eu.api.example.com/v14');`),
       .map(([status, { description, schema }]) => {
         let typeName;
 
-        if (typeof schema === 'string' && schema.startsWith('::convert::')) {
+        if (typeof schema === 'string' && schema.startsWith(REF_PLACEHOLDER)) {
           // If this schema is a string and has our conversion prefix then we've already created
           // a type for it.
-          typeName = schema.replace('::convert::', '');
+          typeName = schema.replace(REF_PLACEHOLDER, '');
         } else {
           typeName = generateTypeName(operationId, 'response', status);
 
@@ -899,7 +951,7 @@ sdk.server('https://eu.api.example.com/v14');`),
    * Add a given schema into our schema dataset that we'll be be exporting as types.
    *
    */
-  addSchemaToExport(schema: SchemaObject, typeName: string, pointer: string) {
+  private addSchemaToExport(schema: SchemaObject, typeName: string, pointer: string) {
     if (this.types.has(typeName)) {
       return;
     }
@@ -907,4 +959,18 @@ sdk.server('https://eu.api.example.com/v14');`),
     setWith(this.schemas, pointer, schema, Object);
     this.types.set(typeName, `FromSchema<typeof schemas.${pointer}>`);
   }
+
+  /**
+   * Add a new JSDoc `@tag` to an existing docblock.
+   *
+   */
+  static #addTagToDocblock(docblock: OptionalKind<JSDocStructure>, tag: OptionalKind<JSDocTagStructure>) {
+    const tags = docblock.tags ?? [];
+    tags.push(tag);
+
+    return {
+      ...docblock,
+      tags,
+    };
+  }
 }