@buildvision/nest-sdk-generator 2.3.0 → 3.0.0

package/src/engine/ast.ts

@@ -0,0 +1,105 @@
+/**
+ * @file AST helpers reproducing the semantics of the ts-morph methods used by the legacy analyzer
+ */
+
+import { AnalysisHost, TsNode } from './host'
+
+/** ts-morph's `node.getText()`: the node's source text, without leading trivia */
+export function nodeText(node: TsNode, sourceFile: TsNode): string {
+  return sourceFile.text.substring(node.getStart(sourceFile), node.end)
+}
+
+/** ts-morph's `node.getName()` for named and nameable declarations (class, function, method, parameter...) */
+export function nodeName(node: TsNode, sourceFile: TsNode): string | undefined {
+  return node.name ? nodeText(node.name, sourceFile) : undefined
+}
+
+/** ts-morph's `node.getDecorators()` */
+export function getDecorators(host: AnalysisHost, node: TsNode): TsNode[] {
+  return (node.modifiers ?? []).filter((m: TsNode) => m.kind === host.SyntaxKind.Decorator)
+}
+
+/** ts-morph's `decorator._getInnerExpression()` */
+function decoratorInnerExpression(host: AnalysisHost, decorator: TsNode): TsNode {
+  let expr = decorator.expression
+  while (expr.kind === host.SyntaxKind.ParenthesizedExpression) expr = expr.expression
+  return expr
+}
+
+/** ts-morph's `decorator.getCallExpression()` */
+export function decoratorCallExpression(host: AnalysisHost, decorator: TsNode): TsNode | undefined {
+  const expr = decoratorInnerExpression(host, decorator)
+  return expr.kind === host.SyntaxKind.CallExpression ? expr : undefined
+}
+
+/** ts-morph's `decorator.getArguments()` */
+export function decoratorArguments(host: AnalysisHost, decorator: TsNode): TsNode[] {
+  return decoratorCallExpression(host, decorator)?.arguments ?? []
+}
+
+/** ts-morph's `decorator.getName()` */
+export function decoratorName(host: AnalysisHost, decorator: TsNode, sourceFile: TsNode): string {
+  const callExpression = decoratorCallExpression(host, decorator)
+  let identifier = callExpression ? callExpression.expression : decoratorInnerExpression(host, decorator)
+
+  if (identifier.kind === host.SyntaxKind.PropertyAccessExpression) {
+    identifier = identifier.name
+  }
+
+  if (identifier.kind !== host.SyntaxKind.Identifier) {
+    throw new Error(
+      `Expected the decorator expression '${nodeText(identifier, sourceFile)}' to be an identifier. ` +
+        `Please deal directly with 'getExpression()' on the decorator to handle more complex scenarios.`
+    )
+  }
+
+  return nodeText(identifier, sourceFile)
+}
+
+/** ts-morph's `Node.isStringLiteral()` */
+export function isStringLiteral(host: AnalysisHost, node: TsNode): boolean {
+  return node.kind === host.SyntaxKind.StringLiteral
+}
+
+function hasModifier(node: TsNode, kind: number): boolean {
+  return (node.modifiers ?? []).some((m: TsNode) => m.kind === kind)
+}
+
+/** ts-morph's `classDeclaration.getMembers()` */
+export function getClassMembers(host: AnalysisHost, decl: TsNode, sourceFile: TsNode): TsNode[] {
+  const SK = host.SyntaxKind
+  const isAmbient = hasModifier(decl, SK.DeclareKeyword) || sourceFile.isDeclarationFile
+
+  return (decl.members as TsNode[])
+    .filter((m) => {
+      if (isAmbient) return true
+      if (m.kind !== SK.Constructor && m.kind !== SK.MethodDeclaration) return true
+      if (m.kind === SK.MethodDeclaration && hasModifier(m, SK.AbstractKeyword)) return true
+      return m.body != null
+    })
+    .filter((m) =>
+      [
+        SK.MethodDeclaration,
+        SK.PropertyDeclaration,
+        SK.GetAccessor,
+        SK.SetAccessor,
+        SK.Constructor,
+        SK.ClassStaticBlockDeclaration,
+      ].includes(m.kind)
+    )
+}
+
+/** ts-morph's `classDeclaration.getProperties()` / `interfaceDeclaration.getProperties()` */
+export function getDeclarationProperties(host: AnalysisHost, decl: TsNode, sourceFile: TsNode): TsNode[] {
+  const SK = host.SyntaxKind
+  return decl.kind === SK.ClassDeclaration
+    ? getClassMembers(host, decl, sourceFile).filter((m) => m.kind === SK.PropertyDeclaration)
+    : (decl.members as TsNode[]).filter((m) => m.kind === SK.PropertySignature)
+}
+
+/** ts-morph's `classDeclaration.getExtends()` (first type only) / `interfaceDeclaration.getExtends()` (all types) */
+export function getExtendsTypeNodes(host: AnalysisHost, decl: TsNode): TsNode[] {
+  const clause = (decl.heritageClauses ?? []).find((c: TsNode) => c.token === host.SyntaxKind.ExtendsKeyword)
+  const types: TsNode[] = clause?.types ?? []
+  return decl.kind === host.SyntaxKind.ClassDeclaration ? types.slice(0, 1) : types
+}

package/src/engine/file-order.ts

@@ -0,0 +1,104 @@
+/**
+ * @file Order project files the way ts-morph's `project.getSourceFiles()` does
+ *
+ * The order of the source files determines the order controllers are analyzed in, which in turn determines the order
+ * of the generated modules and types.
+ *
+ * ts-morph keeps a tree of the directories containing source files. Directories without a parent in the tree are
+ * "roots", kept in the order they were created (i.e. the order files were added: the tsconfig's files, then the files
+ * they import). The tree is walked breadth-first by depth: at each depth, the roots at that depth come first, then the
+ * children of the previous depth's directories, sorted by name. The files of each directory are sorted by name.
+ */
+
+function compareNames(a: string, b: string): number {
+  // Same comparison as ts-morph's `LocaleStringComparer`
+  const result = a.localeCompare(b, 'en-us-u-kf-upper')
+  return result < 0 ? -1 : result === 0 ? 0 : 1
+}
+
+function dirname(file: string): string {
+  const index = file.lastIndexOf('/')
+  return index <= 0 ? '/' : file.substring(0, index)
+}
+
+function depth(dir: string): number {
+  return dir.split('/').filter((part) => part.length > 0).length
+}
+
+function isProjectFile(file: string): boolean {
+  // Files ts-morph considers part of the project: anything outside of `node_modules` (and outside of TypeScript's
+  // bundled libraries, which tsgo exposes with non-absolute paths)
+  return (file.startsWith('/') || /^[a-zA-Z]:\//.test(file)) && file.toLowerCase().lastIndexOf('/node_modules/') === -1
+}
+
+/**
+ * Get the project's files, in ts-morph's order
+ * @param rootFiles The tsconfig's files, in the tsconfig's order (absolute paths, forward slashes)
+ * @param programFiles All files of the program (absolute paths, forward slashes)
+ */
+export function orderProjectFiles(rootFiles: string[], programFiles: string[]): string[] {
+  // ts-morph adds the tsconfig's files first, then the files the compiler requested while building the program.
+  // The latter only affect the order of directories outside of the tsconfig's ones: sort them for determinism.
+  const rootFilesSet = new Set(rootFiles)
+  const files = [...new Set([...rootFiles, ...programFiles.filter((file) => !rootFilesSet.has(file)).sort()])].filter(isProjectFile)
+
+  const filesByDir = new Map<string, string[]>()
+
+  for (const file of files) {
+    const dir = dirname(file)
+    const dirFiles = filesByDir.get(dir)
+    if (dirFiles) dirFiles.push(file)
+    else filesByDir.set(dir, [file])
+  }
+
+  // Directories, in creation order
+  const dirs = [...filesByDir.keys()]
+  const dirsSet = new Set(dirs)
+
+  const hasAncestorInTree = (dir: string) => {
+    for (let parent = dirname(dir); ; parent = dirname(parent)) {
+      if (dirsSet.has(parent)) return true
+      if (parent === '/' || parent === dirname(parent)) return false
+    }
+  }
+
+  const roots = dirs.filter((dir) => !hasAncestorInTree(dir))
+
+  // Link every directory to its parent, creating the intermediate directories up to the nearest directory in the tree
+  const children = new Map<string, Set<string>>()
+
+  for (const dir of dirs) {
+    if (roots.includes(dir)) continue
+
+    for (let current = dir; !roots.includes(current) && !children.get(dirname(current))?.has(current); current = dirname(current)) {
+      const parent = dirname(current)
+      const siblings = children.get(parent)
+      if (siblings) siblings.add(current)
+      else children.set(parent, new Set([current]))
+    }
+  }
+
+  // Breadth-first walk, like ts-morph's `DirectoryCache.getAllByDepth()`
+  const levels = new Map<number, string[]>()
+
+  const addToLevel = (dir: string) => {
+    const level = levels.get(depth(dir))
+    if (level) level.push(dir)
+    else levels.set(depth(dir), [dir])
+  }
+
+  roots.forEach(addToLevel)
+
+  const ordered: string[] = []
+
+  for (let currentDepth = Math.min(...levels.keys()); levels.size > 0; currentDepth++) {
+    for (const dir of levels.get(currentDepth) ?? []) {
+      ordered.push(...(filesByDir.get(dir) ?? []).sort((a, b) => compareNames(a.substring(dir.length), b.substring(dir.length))))
+      ;[...(children.get(dir) ?? [])].sort((a, b) => compareNames(a.substring(dir.length), b.substring(dir.length))).forEach(addToLevel)
+    }
+
+    levels.delete(currentDepth)
+  }
+
+  return ordered
+}

package/src/engine/host.ts

@@ -0,0 +1,79 @@
+/**
+ * @file Minimal compiler interface the analyzer needs from a TypeScript engine
+ *
+ * Both the in-process TypeScript compiler API and the TypeScript 7 native (tsgo) API expose the same AST shapes
+ * (`kind`, `statements`, `members`, `modifiers`...) and the same checker operations, so the analyzer is written once
+ * against this interface. Syntax kinds differ between TypeScript versions, so they are provided by the host.
+ */
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+/** A compiler AST node (TypeScript JS API or TypeScript 7 API) */
+export type TsNode = any
+
+/** A compiler type (TypeScript JS API or TypeScript 7 API) */
+export type TsType = any
+
+/**
+ * Flags ts-morph uses by default when printing a type with `Type.getText()`:
+ * UseTypeOfFunction (4096) | NoTruncation (1) | UseFullyQualifiedType (64) | WriteTypeArgumentsOfSignature (32)
+ */
+export const TYPE_FORMAT_FLAGS = 4193
+
+export interface SyntaxKinds {
+  readonly AbstractKeyword: number
+  readonly CallExpression: number
+  readonly ClassDeclaration: number
+  readonly ClassStaticBlockDeclaration: number
+  readonly Constructor: number
+  readonly DeclareKeyword: number
+  readonly Decorator: number
+  readonly EnumDeclaration: number
+  readonly ExtendsKeyword: number
+  readonly FunctionDeclaration: number
+  readonly GetAccessor: number
+  readonly Identifier: number
+  readonly InterfaceDeclaration: number
+  readonly MethodDeclaration: number
+  readonly ParenthesizedExpression: number
+  readonly PropertyAccessExpression: number
+  readonly PropertyDeclaration: number
+  readonly PropertySignature: number
+  readonly SetAccessor: number
+  readonly StringLiteral: number
+  readonly TypeAliasDeclaration: number
+}
+
+export interface AnalysisHost {
+  readonly SyntaxKind: SyntaxKinds
+
+  /** Release the engine's resources */
+  dispose(): void
+
+  /** Equivalent of ts-morph's `type.getStringIndexType()` / `type.getNumberIndexType()` */
+  getIndexType(type: TsType, keyKind: 'string' | 'number'): TsType | undefined
+
+  /**
+   * Absolute paths of the project's source files: the files ts-morph would consider part of the project (the tsconfig's
+   * files and the non-`node_modules` files they import), in the order of ts-morph's `project.getSourceFiles()`
+   */
+  getProjectFilePaths(): string[]
+
+  /** Equivalent of ts-morph's `method.getReturnType()` */
+  getReturnTypeOfDeclaration(node: TsNode): TsType
+
+  /** Get a source file of the program, if it exists */
+  getSourceFile(absolutePath: string): TsNode | undefined
+
+  /** Equivalent of ts-morph's `node.getType()` */
+  getTypeAtLocation(node: TsNode): TsType
+
+  /** Equivalent of ts-morph's `type.isObject()` */
+  isObjectType(type: TsType): boolean
+
+  /** Engine name, for logging */
+  readonly name: string
+
+  /** Equivalent of ts-morph's `type.getText()` */
+  typeToString(type: TsType): string
+}

package/src/engine/index.ts

@@ -0,0 +1,79 @@
+/**
+ * @file Analysis engines
+ *
+ * - `tsgo` (default): TypeScript 7's native compiler, through its API. Fastest.
+ * - `typescript`: the TypeScript compiler installed for the analyzed API (6.x), running in-process. Generates the same SDK
+ *   as `tsgo`, and is used automatically if `tsgo` can't be started.
+ * - `ts-morph`: the original analyzer, running on the TypeScript 4.8 compiler bundled with ts-morph. Slowest; generates
+ *   the same SDK as previous versions of this tool (which may differ from TypeScript 6+ on some inferred types).
+ */
+
+/* eslint-disable @typescript-eslint/no-var-requires -- engines are loaded lazily, as loading a compiler is expensive */
+
+import * as path from 'path'
+
+import type { SdkContent } from '../analyzer/sdk'
+import { Config } from '../config'
+import { debug, notice, panic } from '../logging'
+
+import { analyzeWithHost } from './analyze'
+
+export const ENGINES = ['tsgo', 'typescript', 'ts-morph'] as const
+
+export type EngineName = (typeof ENGINES)[number]
+
+/** Internal engine running this analyzer on ts-morph's program, used to verify it matches the legacy analyzer */
+const TS_MORPH_COMPAT_ENGINE = 'ts-morph-compat'
+
+export function isEngineName(name: string): name is EngineName {
+  return (ENGINES as readonly string[]).includes(name) || name === TS_MORPH_COMPAT_ENGINE
+}
+
+export async function analyze(config: Config, engine: EngineName): Promise<SdkContent> {
+  debug('Analysis engine: {yellow}', engine)
+
+  const sourcePath = path.resolve(process.cwd(), config.apiInputPath)
+
+  switch (engine as string) {
+    // Engines are loaded lazily: loading a compiler is expensive
+    case 'ts-morph': {
+      const { analyzerCli }: typeof import('../analyzer') = require('../analyzer')
+      return analyzerCli(config)
+    }
+
+    case TS_MORPH_COMPAT_ENGINE: {
+      const { createTsMorphCompatHost }: typeof import('./ts-morph-compat-host') = require('./ts-morph-compat-host')
+      return analyzeWithHost(config, createTsMorphCompatHost)
+    }
+
+    case 'typescript': {
+      const { createTypeScriptHost, loadTypeScript }: typeof import('./typescript-host') = require('./typescript-host')
+      return analyzeWithHost(config, (tsConfigFilePath) =>
+        createTypeScriptHost(loadTypeScript(sourcePath, config.typescriptPath), tsConfigFilePath)
+      )
+    }
+
+    case 'tsgo': {
+      const { createTsgoHost }: typeof import('./tsgo-host') = require('./tsgo-host')
+      const { createTypeScriptHost, loadTypeScript }: typeof import('./typescript-host') = require('./typescript-host')
+
+      return analyzeWithHost(config, (tsConfigFilePath) => {
+        try {
+          return createTsgoHost(tsConfigFilePath)
+        } catch (e) {
+          // Only startup failures end up here (e.g. no native binary for this platform): analysis errors happen later on
+          notice(
+            'Could not start the {yellow} engine, falling back to the {yellow} engine (same output, slower):\n{}',
+            'tsgo',
+            'typescript',
+            e instanceof Error ? e.message : String(e)
+          )
+          return createTypeScriptHost(loadTypeScript(sourcePath, config.typescriptPath), tsConfigFilePath)
+        }
+      })
+    }
+
+    default:
+      panic('Unknown analysis engine {yellow} (expected one of: {})', engine, ENGINES.join(', '))
+  }
+}

package/src/engine/ts-morph-compat-host.ts

@@ -0,0 +1,20 @@
+/**
+ * @file Analysis host running on the TypeScript program built by ts-morph (TypeScript 4.8)
+ *
+ * This is not meant for users: it runs the engine-independent analyzer against the exact same program, type checker
+ * and file order as the legacy ts-morph analyzer, which lets the parity tests verify both analyzers are equivalent.
+ */
+
+import { Project, ts } from 'ts-morph'
+
+import { AnalysisHost } from './host'
+import { createProgramHost } from './typescript-host'
+
+export function createTsMorphCompatHost(tsConfigFilePath: string): AnalysisHost {
+  // Same project setup as the legacy analyzer (src/analyzer/index.ts)
+  const project = new Project({ tsConfigFilePath })
+
+  const projectFilePaths = project.getSourceFiles().map((file) => file.getFilePath() as string)
+
+  return createProgramHost('ts-morph-compat', ts, project.getProgram().compilerObject, projectFilePaths)
+}

package/src/engine/tsgo-host.ts

@@ -0,0 +1,119 @@
+/**
+ * @file Analysis host backed by the TypeScript 7 native compiler (tsgo), through its synchronous API
+ */
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/* eslint-disable @typescript-eslint/no-var-requires -- the TypeScript 7 API is loaded lazily, and can fail to load */
+
+import * as fs from 'fs'
+import * as path from 'path'
+
+import { debug } from '../logging'
+
+import { orderProjectFiles } from './file-order'
+import { AnalysisHost, SyntaxKinds, TsNode, TsType, TYPE_FORMAT_FLAGS } from './host'
+
+/**
+ * The API throws synchronously when the native executable is missing, but if it exists and can't be executed, the
+ * failure surfaces as an unhandled 'error' event of the child process, which would crash instead of falling back
+ */
+function assertTsgoIsExecutable() {
+  if (process.platform === 'win32') return
+
+  // Same resolution as TypeScript's lib/getExePath.js
+  const platformPackage = `@typescript/typescript-${process.platform}-${process.arch}`
+  const packageJson = require.resolve(`${platformPackage}/package.json`, {
+    paths: [path.dirname(require.resolve('typescript/package.json'))],
+  })
+  fs.accessSync(path.join(path.dirname(packageJson), 'lib', 'tsc'), fs.constants.X_OK)
+}
+
+/**
+ * Stop tsgo
+ * The API's `close()` sends SIGTERM, to which a busy tsgo process responds by logging "context canceled" to the stderr
+ * it shares with this process. tsgo holds no state worth a graceful shutdown, so it is killed with SIGKILL first.
+ */
+function terminate(api: any) {
+  // Private fields of TypeScript 7.0's synchronous API (the dependency's version is pinned)
+  const client = api.client
+  const child = client?.channel?.child
+
+  if (!child) {
+    api.close()
+    return
+  }
+
+  if (child.exitCode === null && child.signalCode === null) {
+    child.kill('SIGKILL')
+  }
+
+  // Only close the channel: `api.close()` would first ask the (now dead) process to release its snapshots
+  client.close()
+}
+
+/**
+ * Load the TypeScript 7 API and start a tsgo process
+ * Throws if the API can't be loaded or tsgo can't be started (e.g. unsupported platform)
+ */
+export function createTsgoHost(tsConfigFilePath: string): AnalysisHost {
+  // The synchronous API relies on Node.js internals (and the tsgo process it spawns would then never exit)
+  if (process.versions['bun']) {
+    throw new Error("TypeScript 7's API requires the Node.js runtime (run the generator with `bun x` or `npx`, without `--bun`)")
+  }
+
+  // The API is published as ES modules: this relies on `require(esm)` (Node.js 20.19+ / 22.12+, Bun)
+  const { API, TypeFlags } = require('typescript/unstable/sync')
+  const { SyntaxKind } = require('typescript/unstable/ast')
+
+  assertTsgoIsExecutable()
+
+  const api = new API({ cwd: path.dirname(tsConfigFilePath) })
+
+  // Errors exit the process right away: stop tsgo then too. Prepended, to run before the API's own exit handler.
+  const onExit = () => terminate(api)
+  process.prependListener('exit', onExit)
+
+  try {
+    const snapshot = api.updateSnapshot({ openProjects: [tsConfigFilePath] })
+    const project = snapshot.getProject(tsConfigFilePath)
+
+    if (!project) {
+      throw new Error(`tsgo did not load the project for ${tsConfigFilePath}`)
+    }
+
+    const { checker, program } = project
+
+    debug('Using TypeScript {yellow} (native)', String(require('typescript/package.json').version))
+
+    return {
+      name: 'tsgo',
+      SyntaxKind: SyntaxKind as SyntaxKinds,
+      getProjectFilePaths: () => orderProjectFiles(project.rootFiles, program.getSourceFileNames()),
+      getSourceFile: (absolutePath) => program.getSourceFile(absolutePath),
+      getTypeAtLocation: (node: TsNode) => checker.getTypeAtLocation(node),
+      getReturnTypeOfDeclaration(node: TsNode) {
+        const signature = checker.getSignatureFromDeclaration(node)
+
+        if (!signature) {
+          throw new Error('Expected the node to have a signature.')
+        }
+
+        return checker.getReturnTypeOfSignature(signature)
+      },
+      typeToString: (type: TsType) => checker.typeToString(type, undefined, TYPE_FORMAT_FLAGS),
+      isObjectType: (type: TsType) => (type.flags & TypeFlags.Object) !== 0,
+      getIndexType(type: TsType, keyKind) {
+        const keyFlag = keyKind === 'string' ? TypeFlags.String : TypeFlags.Number
+        return checker.getIndexInfosOfType(type).find((info: any) => (info.keyType.flags & keyFlag) !== 0)?.valueType
+      },
+      dispose() {
+        process.removeListener('exit', onExit)
+        terminate(api)
+      },
+    }
+  } catch (e) {
+    process.removeListener('exit', onExit)
+    terminate(api)
+    throw e
+  }
+}

package/src/engine/typescript-host.ts

@@ -0,0 +1,159 @@
+/**
+ * @file Analysis host backed by the in-process TypeScript compiler API
+ */
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/* eslint-disable @typescript-eslint/no-var-requires -- the TypeScript compiler is resolved at runtime */
+
+import * as fs from 'fs'
+import * as path from 'path'
+
+import { debug, notice, panic } from '../logging'
+
+import { orderProjectFiles } from './file-order'
+import { AnalysisHost, SyntaxKinds, TsNode, TsType, TYPE_FORMAT_FLAGS } from './host'
+
+/** The TypeScript compiler module (`typeof import('typescript')` for TypeScript 6 and below) */
+export type TypeScriptModule = any
+
+/**
+ * Resolution mode attributes of import types, e.g. `import("pkg", { with: { "resolution-mode": "import" } }).Type`
+ * TypeScript 5.3+ prints them for ESM-only modules referenced from CommonJS files; TypeScript 7 and 4.8 print the
+ * same type as `import("pkg").Type`.
+ */
+const IMPORT_TYPE_ATTRIBUTES_REGEX = /\bimport\(("[^"]+"|'[^']+'), \{ (?:with|assert): \{ "resolution-mode": "(?:import|require)" \} \}\)/g
+
+/**
+ * Create a host from an existing program
+ * @param name Engine name
+ * @param ts The TypeScript module the program was created with
+ * @param program The TypeScript program
+ * @param projectFilePaths Files that are part of the project
+ */
+export function createProgramHost(name: string, ts: TypeScriptModule, program: any, projectFilePaths: string[]): AnalysisHost {
+  const checker = program.getTypeChecker()
+
+  return {
+    name,
+    SyntaxKind: ts.SyntaxKind as SyntaxKinds,
+    getProjectFilePaths: () => projectFilePaths,
+    getSourceFile: (absolutePath) => program.getSourceFile(absolutePath),
+    getTypeAtLocation: (node: TsNode) => checker.getTypeAtLocation(node),
+    getReturnTypeOfDeclaration(node: TsNode) {
+      const signature = checker.getSignatureFromDeclaration(node)
+
+      if (!signature) {
+        throw new Error('Expected the node to have a signature.')
+      }
+
+      return checker.getReturnTypeOfSignature(signature)
+    },
+    typeToString: (type: TsType) =>
+      checker.typeToString(type, undefined, TYPE_FORMAT_FLAGS).replace(IMPORT_TYPE_ATTRIBUTES_REGEX, 'import($1)'),
+    isObjectType: (type: TsType) => (type.flags & ts.TypeFlags.Object) !== 0,
+    getIndexType: (type: TsType, keyKind) => (keyKind === 'string' ? type.getStringIndexType() : type.getNumberIndexType()),
+    dispose() {},
+  }
+}
+
+/**
+ * Load the TypeScript compiler used by the `typescript` engine
+ * By default, this is the TypeScript version installed for the analyzed API (resolved from its source directory).
+ * @param sourcePath Absolute path of the API's source directory
+ * @param typescriptPath Explicit path to a TypeScript package (from the configuration file)
+ */
+export function loadTypeScript(sourcePath: string, typescriptPath: string | undefined): TypeScriptModule {
+  let modulePath: string
+
+  try {
+    modulePath = typescriptPath
+      ? require.resolve(path.resolve(process.cwd(), typescriptPath))
+      : require.resolve('typescript', { paths: [sourcePath] })
+  } catch (e) {
+    // TypeScript 7 packages have no main entry point
+    const packageJsonPath = typescriptPath && path.resolve(process.cwd(), typescriptPath, 'package.json')
+
+    if (packageJsonPath && fs.existsSync(packageJsonPath)) {
+      panic(
+        'The TypeScript package at {magentaBright} (version {yellow}) does not provide the JavaScript compiler API required by the {yellow} engine.\nUse TypeScript 6 or below, or the {yellow} engine.',
+        path.dirname(packageJsonPath),
+        String(JSON.parse(fs.readFileSync(packageJsonPath, 'utf8')).version),
+        'typescript',
+        'tsgo'
+      )
+    }
+
+    panic(
+      typescriptPath
+        ? 'Could not load TypeScript from {magentaBright}'
+        : 'The {yellow} engine uses the TypeScript compiler installed for the analyzed API, but none was found from {magentaBright}.\nInstall {yellow} or set the {yellow} option.',
+      ...(typescriptPath ? [typescriptPath] : ['typescript', sourcePath, 'typescript', 'typescriptPath'])
+    )
+  }
+
+  const ts = require(modulePath)
+
+  if (typeof ts.createProgram !== 'function') {
+    panic(
+      'The TypeScript package at {magentaBright} (version {yellow}) does not provide the JavaScript compiler API required by the {yellow} engine.\nUse TypeScript 6 or below, or the {yellow} engine.',
+      modulePath,
+      String(ts.version),
+      'typescript',
+      'tsgo'
+    )
+  }
+
+  const [major] = String(ts.version).split('.').map(Number)
+
+  if (major < 6) {
+    notice(
+      'TypeScript {yellow} does not support stable type ordering: generated types may be ordered differently than with the {yellow} engine.',
+      String(ts.version),
+      'tsgo'
+    )
+  }
+
+  debug('Using TypeScript {yellow} from {magentaBright}', String(ts.version), modulePath)
+
+  return ts
+}
+
+/**
+ * Create a host running the in-process TypeScript compiler on a tsconfig file
+ * Uses the same settings as the TypeScript 7 native compiler, so both engines generate the same SDK.
+ */
+export function createTypeScriptHost(ts: TypeScriptModule, tsConfigFilePath: string): AnalysisHost {
+  const parsed = ts.getParsedCommandLineOfConfigFile(
+    tsConfigFilePath,
+    {},
+    {
+      ...ts.sys,
+      onUnRecoverableConfigFileDiagnostic: (diagnostic: any) =>
+        panic('Failed to parse {yellow}: {}', tsConfigFilePath, ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n')),
+    }
+  )
+
+  // Order union constituents deterministically, like TypeScript 7 does
+  const options = { ...parsed.options, stableTypeOrdering: true }
+
+  const compilerHost = ts.createCompilerHost(options)
+
+  // JSDoc comments don't affect types in TypeScript files: skip parsing them (TypeScript 5.3+)
+  if (ts.JSDocParsingMode) {
+    compilerHost.jsDocParsingMode = ts.JSDocParsingMode.ParseForTypeErrors
+  }
+
+  const program = ts.createProgram({
+    rootNames: parsed.fileNames,
+    options,
+    host: compilerHost,
+    projectReferences: parsed.projectReferences,
+  })
+
+  const projectFilePaths = orderProjectFiles(
+    parsed.fileNames,
+    program.getSourceFiles().map((file: any) => file.fileName)
+  )
+
+  return createProgramHost('typescript', ts, program, projectFilePaths)
+}