nitrogen 0.2.23 → 0.29.4

package/src/index.ts

@@ -0,0 +1,146 @@
+#!/usr/bin/env node
+
+import yargs from 'yargs/yargs'
+import { hideBin } from 'yargs/helpers'
+import chalk from 'chalk'
+import { prettifyDirectory } from './prettifyDirectory.js'
+import { getFiles } from './getFiles.js'
+import { runNitrogen } from './nitrogen.js'
+import { promises as fs } from 'fs'
+import { isValidLogLevel, setLogLevel } from './Logger.js'
+import { initNewNitroModule } from './init.js'
+import { NITROGEN_VERSION } from './utils.js'
+
+const commandName = 'nitrogen'
+
+// Maximum of 100 col width
+const cliWidth = Math.min(process.stdout.columns * 0.9, 100)
+
+// Set up yargs CLI app
+await yargs(hideBin(process.argv))
+  .option('log-level', {
+    type: 'string',
+    description: 'Configures the log-level of nitrogen.',
+    default: 'info',
+    choices: ['debug', 'info', 'warning', 'error'],
+  })
+  .middleware((args) => {
+    if (!isValidLogLevel(args.logLevel)) {
+      throw new Error(`Invalid log-level ("${args.logLevel}")!`)
+    }
+    setLogLevel(args.logLevel)
+  })
+  // 🔥 nitrogen [path]
+  .command(
+    '$0 [basePath]',
+    `Usage: ${chalk.bold(`${commandName} <basePath> [options]`)}\n` +
+      `Run the nitro code-generator on all ${chalk.underline('**/*.nitro.ts')} files found ` +
+      `in the current directory and generate C++, Swift or Kotlin outputs in ${chalk.underline('./nitrogen/generated')}.`,
+    (y) =>
+      y
+        .positional('basePath', {
+          type: 'string',
+          description: `The base path of where Nitrogen will start looking for ${chalk.underline('**/*.nitro.ts')} specs.`,
+          default: process.cwd(),
+        })
+        .option('out', {
+          type: 'string',
+          description:
+            'Configures the output path of the generated C++, Swift or Kotlin files.',
+          default: './nitrogen/generated',
+        })
+        .option('config', {
+          type: 'string',
+          description: `A custom path to a ${chalk.underline('nitro.json')} config file.`,
+          default: './nitro.json',
+        }),
+    async (argv) => {
+      const basePath = argv.basePath
+      const outputDirectory = argv.out
+      await runNitrogenCommand(basePath, outputDirectory)
+    }
+  )
+  // 🔥 nitrogen init <moduleName>
+  .command(
+    'init <moduleName>',
+    `Usage: ${chalk.bold(`${commandName} init <moduleName> [options]`)}\n` +
+      `Create a new Nitro Module.`,
+    (y) =>
+      y
+        .positional('moduleName', {
+          type: 'string',
+          description: 'The name of the Nitro Module that will be created.',
+          demandOption: true,
+        })
+        .option('path', {
+          type: 'string',
+          description: `A custom path to create the new Nitro Module in - instead of the current working directory.`,
+          default: process.cwd(),
+        }),
+    async (argv) => {
+      await initNewNitroModule(argv.path, argv.moduleName)
+    }
+  )
+  .usage(
+    `Usage: ${chalk.bold('$0 [options]')}\n` +
+      `$0 is a code-generater for Nitro Modules (${chalk.underline('https://github.com/mrousavy/nitro')})\n` +
+      `It converts all TypeScript specs found in ${chalk.underline('**/*.nitro.ts')} to C++, Swift or Kotlin specs.\n` +
+      `Each library/module must have a ${chalk.underline('nitro.json')} configuration file in it's root directory.\n` +
+      `$Nitrogen Version: ${chalk.bold(NITROGEN_VERSION)}`
+  )
+  .help()
+  .strict()
+  .wrap(cliWidth).argv
+
+async function runNitrogenCommand(
+  baseDirectory: string,
+  outputDirectory: string
+): Promise<void> {
+  // 1. Prepare output folders
+  const filesBefore = await getFiles(outputDirectory)
+
+  const start = performance.now()
+
+  // 2. Run Nitrogen
+  const { generatedFiles, generatedSpecsCount, targetSpecsCount } =
+    await runNitrogen({
+      baseDirectory: baseDirectory,
+      outputDirectory: outputDirectory,
+    })
+
+  const end = performance.now()
+  const timeS = ((end - start) / 1000).toFixed(1)
+  console.log(
+    `🎉  Generated ${generatedSpecsCount}/${targetSpecsCount} HybridObject${generatedSpecsCount === 1 ? '' : 's'} in ${timeS}s!`
+  )
+  console.log(
+    `💡  Your code is in ${chalk.underline(prettifyDirectory(outputDirectory))}`
+  )
+
+  // 3. Delete all old dangling files
+  const addedFiles = generatedFiles.filter((f) => !filesBefore.includes(f))
+  const removedFiles = filesBefore.filter((f) => !generatedFiles.includes(f))
+  if (addedFiles.length > 0 || removedFiles.length > 0) {
+    let text = ''
+    const as = addedFiles.length > 1 ? 's' : ''
+    const rs = removedFiles.length > 1 ? 's' : ''
+    if (addedFiles.length > 0 && removedFiles.length === 0) {
+      text = `Added ${addedFiles.length} file${as}`
+    } else if (addedFiles.length === 0 && removedFiles.length > 0) {
+      text = `Removed ${removedFiles.length} file${rs}`
+    } else {
+      text = `Added ${addedFiles.length} file${as} and removed ${removedFiles.length} file${rs}`
+    }
+
+    console.log(
+      `‼️   ${text} - ${chalk.bold('you need to run `pod install`/sync gradle to update files!')}`
+    )
+  }
+  const promises = removedFiles.map(async (file) => {
+    const stat = await fs.stat(file)
+    if (stat.isFile()) {
+      await fs.rm(file)
+    }
+  })
+  await Promise.all(promises)
+}

package/src/init.ts

@@ -0,0 +1,186 @@
+import path from 'path'
+import { prettifyDirectory } from './prettifyDirectory.js'
+import fs from 'fs/promises'
+import { existsSync } from 'fs'
+import { Logger } from './Logger.js'
+import chalk from 'chalk'
+import { execSync } from 'child_process'
+import { randomUUID } from 'crypto'
+
+export async function initNewNitroModule(
+  baseDirectory: string,
+  moduleName: string,
+  ref: string = 'main'
+): Promise<void> {
+  Logger.info(
+    `⚙️  Creating new Nitro Module "${chalk.bold(moduleName)}" in ${chalk.underline(prettifyDirectory(baseDirectory))}...`
+  )
+
+  const directory = path.join(baseDirectory, moduleName)
+  if (existsSync(directory)) {
+    Logger.error(
+      `❌ A folder named "${chalk.underline(moduleName)}" already exists in the directory ${chalk.underline(prettifyDirectory(baseDirectory))}!`
+    )
+    process.exit(1)
+  }
+
+  await fs.mkdir(directory)
+
+  const modulePath = await downloadGitHubFolder(
+    'mrousavy',
+    'nitro',
+    ref,
+    'packages/template',
+    directory
+  )
+  Logger.info(`🏗️  Constructing template...`)
+
+  const cleanLibraryName = moduleName.replace('react-native-', '')
+  const cxxNamespace = cleanLibraryName.replaceAll('-', '')
+  let camelCaseName = cleanLibraryName
+    .split('-')
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
+    .join('')
+  if (!camelCaseName.startsWith('Nitro')) {
+    camelCaseName = 'Nitro' + camelCaseName
+  }
+
+  await replaceTemplate(modulePath, `cxxNamespace`, cxxNamespace)
+  await replaceTemplate(modulePath, `androidNamespace`, cxxNamespace)
+  await replaceTemplate(modulePath, `androidCxxLibName`, camelCaseName)
+  await replaceTemplate(modulePath, `iosModuleName`, camelCaseName)
+  await replaceTemplate(modulePath, `packageName`, moduleName)
+  await replaceTemplate(modulePath, `packageDescription`, moduleName)
+
+  Logger.info(
+    `🎉 Created Nitro Module "${chalk.bold(moduleName)}" in ${chalk.underline(prettifyDirectory(directory))}!`
+  )
+  Logger.info(
+    `👉 To install dependencies, use your package manager of choice (e.g. ${chalk.bold('npm install')})`
+  )
+  Logger.info(
+    `👉 To create your first Hybrid Object, add a ${chalk.underline(`*.nitro.ts`)} file, declare a TypeScript interface that extends ${chalk.bold('HybridObject<...>')}, and run ${chalk.bold('npx nitrogen')}.`
+  )
+  Logger.info(
+    `👉 To test your module in an app, create a new React Native app somewhere (e.g. in ${chalk.underline(`./${moduleName}/example`)}) and add ${chalk.bold(moduleName)} as a local dependency.`
+  )
+}
+
+async function isGitInstalled(): Promise<boolean> {
+  try {
+    execSync('git --version')
+    return true
+  } catch (error) {
+    return false
+  }
+}
+
+async function downloadGitHubFolder(
+  owner: string,
+  repo: string,
+  branch: string,
+  folder: string,
+  outputPath: string
+): Promise<string> {
+  if (!isGitInstalled()) {
+    console.error(
+      `❌ ${chalk.bold('git')} is not installed or available in the current path! Make sure to install ${chalk.bold('git')} and try again.`
+    )
+    process.exit(1)
+  }
+
+  const repoUrl = `https://github.com/${owner}/${repo}`
+  Logger.info(`⏳ Cloning ${chalk.underline(repoUrl)}...`)
+  const tempPath = randomUUID()
+  const tempDir = path.join(outputPath, tempPath)
+  execSync(
+    `git clone --depth 1 --filter=blob:none -b ${branch} --quiet --sparse ${repoUrl} ${tempDir}`
+  )
+  const prettyOutputPath = prettifyDirectory(outputPath)
+
+  const initialDir = process.cwd()
+  try {
+    process.chdir(tempDir)
+
+    Logger.debug(`⏳ Checking out ${chalk.underline(folder)}...`)
+    execSync(`git sparse-checkout set ${folder}`)
+
+    Logger.debug(
+      `📁 Copying files from ${chalk.underline(`${prettyOutputPath}/${tempPath}`)} to ${chalk.underline(prettyOutputPath)}...`
+    )
+    const sourcePath = path.join(tempDir, folder)
+    await fs.mkdir(outputPath, { recursive: true })
+    await copyFolder(sourcePath, outputPath)
+
+    return outputPath
+  } finally {
+    // change dir back to original
+    process.chdir(initialDir)
+
+    Logger.debug(
+      `🗑️  Removing temporary folder ${chalk.underline(prettifyDirectory(tempDir))}...`
+    )
+    await fs.rm(tempDir, { recursive: true, force: true })
+  }
+}
+
+async function copyFolder(src: string, dest: string) {
+  const entries = await fs.readdir(src, { withFileTypes: true })
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name)
+    const destPath = path.join(dest, entry.name)
+    if (entry.isDirectory()) {
+      await fs.mkdir(destPath, { recursive: true })
+      await copyFolder(srcPath, destPath)
+    } else {
+      await fs.copyFile(srcPath, destPath)
+    }
+  }
+}
+
+async function replaceTemplate(
+  dir: string,
+  templateName: string,
+  replacementValue: string
+): Promise<void> {
+  const replaceInFile = async (filePath: string) => {
+    const content = await fs.readFile(filePath, 'utf8')
+    const updatedContent = content.replaceAll(
+      `$$${templateName}$$`,
+      replacementValue
+    )
+    if (content !== updatedContent) {
+      await fs.writeFile(filePath, updatedContent, 'utf8')
+    }
+  }
+
+  const replaceInName = (name: string) => {
+    return name.replaceAll(`$$${templateName}$$`, replacementValue)
+  }
+
+  const processDirectory = async (currentDir: string) => {
+    const entries = await fs.readdir(currentDir, { withFileTypes: true })
+
+    for (const entry of entries) {
+      const oldPath = path.join(currentDir, entry.name)
+      const updatedName = replaceInName(entry.name)
+      const newPath = path.join(currentDir, updatedName)
+
+      if (oldPath !== newPath) {
+        await fs.rename(oldPath, newPath)
+      }
+
+      if (entry.isDirectory()) {
+        await processDirectory(newPath)
+      } else if (entry.isFile()) {
+        await replaceInFile(newPath)
+      }
+    }
+  }
+
+  if (!existsSync(dir)) {
+    throw new Error(`The directory "${dir}" does not exist.`)
+  }
+
+  await processDirectory(dir)
+}

package/src/nitrogen.ts

@@ -0,0 +1,246 @@
+import { Project } from 'ts-morph'
+import {
+  extendsHybridObject,
+  isHybridView,
+  getHybridObjectPlatforms,
+  getHybridViewPlatforms,
+  type Platform,
+} from './getPlatformSpecs.js'
+import { generatePlatformFiles } from './createPlatformSpec.js'
+import path from 'path'
+import { prettifyDirectory } from './prettifyDirectory.js'
+import {
+  capitalizeName,
+  deduplicateFiles,
+  errorToString,
+  indent,
+  NITROGEN_VERSION,
+} from './utils.js'
+import { writeFile } from './writeFile.js'
+import chalk from 'chalk'
+import { groupByPlatform, type SourceFile } from './syntax/SourceFile.js'
+import { Logger } from './Logger.js'
+import { NitroConfig } from './config/NitroConfig.js'
+import { createIOSAutolinking } from './autolinking/createIOSAutolinking.js'
+import { createAndroidAutolinking } from './autolinking/createAndroidAutolinking.js'
+import type { Autolinking } from './autolinking/Autolinking.js'
+import { createGitAttributes } from './createGitAttributes.js'
+import type { PlatformSpec } from 'react-native-nitro-modules'
+
+interface NitrogenOptions {
+  baseDirectory: string
+  outputDirectory: string
+}
+
+interface NitrogenResult {
+  generatedFiles: string[]
+  targetSpecsCount: number
+  generatedSpecsCount: number
+}
+
+export async function runNitrogen({
+  baseDirectory,
+  outputDirectory,
+}: NitrogenOptions): Promise<NitrogenResult> {
+  let targetSpecs = 0
+  let generatedSpecs = 0
+
+  // Create the TS project
+  const project = new Project({
+    compilerOptions: {
+      strict: true,
+      strictNullChecks: true,
+      noUncheckedIndexedAccess: true,
+    },
+  })
+
+  const ignorePaths = NitroConfig.current.getIgnorePaths()
+  const globPattern = [path.join(baseDirectory, '**', '*.nitro.ts')]
+  ignorePaths.forEach((ignorePath) => {
+    globPattern.push('!' + path.join(baseDirectory, ignorePath))
+  })
+  project.addSourceFilesAtPaths(globPattern)
+
+  // Loop through all source files to log them
+  Logger.info(
+    chalk.reset(
+      `🚀  Nitrogen ${chalk.bold(NITROGEN_VERSION)} runs at ${chalk.underline(prettifyDirectory(baseDirectory))}`
+    )
+  )
+  for (const dir of project.getDirectories()) {
+    const specs = dir.getSourceFiles().length
+    const relativePath = prettifyDirectory(dir.getPath())
+    Logger.info(
+      `    🔍  Nitrogen found ${specs} spec${specs === 1 ? '' : 's'} in ${chalk.underline(relativePath)}`
+    )
+  }
+
+  // If no source files are found, we can exit
+  if (project.getSourceFiles().length === 0) {
+    const searchDir = prettifyDirectory(
+      path.join(path.resolve(baseDirectory), '**', '*.nitro.ts')
+    )
+    Logger.error(
+      `❌  Nitrogen didn't find any spec files in ${chalk.underline(searchDir)}! ` +
+        `To create a Nitro Module, create a TypeScript file with the "${chalk.underline('.nitro.ts')}" suffix ` +
+        'and export an interface that extends HybridObject<T>.'
+    )
+    process.exit()
+  }
+
+  const usedPlatforms: Platform[] = []
+  const filesAfter: string[] = []
+  const writtenFiles: SourceFile[] = []
+
+  for (const sourceFile of project.getSourceFiles()) {
+    Logger.info(`⏳  Parsing ${sourceFile.getBaseName()}...`)
+
+    const startedWithSpecs = generatedSpecs
+
+    // Find all interfaceDeclarations in the given file
+    const declarations = [
+      ...sourceFile.getInterfaces(),
+      ...sourceFile.getTypeAliases(),
+    ]
+    for (const declaration of declarations) {
+      let typeName = declaration.getName()
+      try {
+        let platformSpec: PlatformSpec
+        if (isHybridView(declaration.getType())) {
+          // Hybrid View Props
+          const targetPlatforms = getHybridViewPlatforms(declaration)
+          if (targetPlatforms == null) {
+            // It does not extend HybridView, continue..
+            continue
+          }
+          platformSpec = targetPlatforms
+        } else if (extendsHybridObject(declaration.getType(), true)) {
+          // Hybrid View
+          const targetPlatforms = getHybridObjectPlatforms(declaration)
+          if (targetPlatforms == null) {
+            // It does not extend HybridObject, continue..
+            continue
+          }
+          platformSpec = targetPlatforms
+        } else {
+          continue
+        }
+
+        const platforms = Object.keys(platformSpec) as Platform[]
+
+        if (platforms.length === 0) {
+          Logger.warn(
+            `⚠️   ${typeName} does not declare any platforms in HybridObject<T> - nothing can be generated.`
+          )
+          continue
+        }
+
+        targetSpecs++
+
+        Logger.info(
+          `    ⚙️   Generating specs for HybridObject "${chalk.bold(typeName)}"...`
+        )
+
+        // Create all files and throw it into a big list
+        let allFiles = platforms.flatMap((p) => {
+          usedPlatforms.push(p)
+          const language = platformSpec[p]!
+          const r = generatePlatformFiles(declaration.getType(), language)
+          return r
+        })
+        allFiles = deduplicateFiles(allFiles)
+        // Group the files by platform ({ ios: [], android: [], shared: [] })
+        const filesPerPlatform = groupByPlatform(allFiles)
+        // Loop through each platform one by one so that it has some kind of order (per-platform)
+        for (const [p, files] of Object.entries(filesPerPlatform)) {
+          const platform = p as SourceFile['platform']
+          const language =
+            platform === 'shared' ? 'c++' : platformSpec[platform]
+          if (language == null) {
+            // if the language was never specified in the spec, skip it
+            continue
+          }
+          if (files.length === 0) {
+            // if no files exist on this platform, skip it
+            continue
+          }
+
+          Logger.info(
+            `        ${chalk.dim(platform)}: Generating ${capitalizeName(language)} code...`
+          )
+          // Write the actual files for this specific platform.
+          for (const file of files) {
+            const basePath = path.join(
+              outputDirectory,
+              file.platform,
+              file.language
+            )
+            const actualPath = await writeFile(basePath, file)
+            filesAfter.push(actualPath)
+            writtenFiles.push(file)
+          }
+        }
+
+        // Done!
+        generatedSpecs++
+      } catch (error) {
+        const message = indent(errorToString(error), '    ')
+        Logger.error(
+          chalk.redBright(
+            `        ❌  Failed to generate spec for ${typeName}! ${message}`
+          )
+        )
+        process.exitCode = 1
+      }
+    }
+
+    if (generatedSpecs === startedWithSpecs) {
+      Logger.error(
+        chalk.redBright(
+          `    ❌  No specs found in ${sourceFile.getBaseName()}!`
+        )
+      )
+    }
+  }
+
+  // Autolinking
+  Logger.info(`⛓️   Setting up build configs for autolinking...`)
+
+  const autolinkingFiles: Autolinking[] = []
+
+  if (usedPlatforms.includes('ios')) {
+    autolinkingFiles.push(createIOSAutolinking())
+  }
+  if (usedPlatforms.includes('android')) {
+    autolinkingFiles.push(createAndroidAutolinking(writtenFiles))
+  }
+
+  for (const autolinking of autolinkingFiles) {
+    Logger.info(
+      `    Creating autolinking build setup for ${chalk.dim(autolinking.platform)}...`
+    )
+    for (const file of autolinking.sourceFiles) {
+      const basePath = path.join(outputDirectory, file.platform)
+      const actualPath = await writeFile(
+        basePath,
+        file as unknown as SourceFile
+      )
+      filesAfter.push(actualPath)
+    }
+  }
+
+  try {
+    // write a .gitattributes file
+    const markAsGenerated = NitroConfig.current.getGitAttributesGeneratedFlag()
+    const file = await createGitAttributes(markAsGenerated, outputDirectory)
+    filesAfter.push(file)
+  } catch {
+    Logger.error(`❌  Failed to write ${chalk.dim(`.gitattributes`)}!`)
+  }
+
+  return {
+    generatedFiles: filesAfter,
+    targetSpecsCount: targetSpecs,
+    generatedSpecsCount: generatedSpecs,
+  }
+}

package/src/prettifyDirectory.ts

@@ -0,0 +1,32 @@
+import os from 'os'
+import path from 'path'
+
+export function prettifyDirectory(directory: string): string {
+  let relativePath = path.relative(process.cwd(), path.resolve(directory))
+  if (!relativePath.startsWith('.') && relativePath.length > 0) {
+    // Make sure all relative paths start with "./something", not just "something"
+    relativePath = `./${relativePath}`
+  }
+
+  const home = os.homedir()
+  const homeShorthand = os.platform() === 'win32' ? '$HOME' : '~'
+  const prettifiedHomeShorthand = directory.startsWith(home)
+    ? `${homeShorthand}${directory.slice(home.length)}`
+    : directory
+
+  if (relativePath.length < 1) {
+    // If relativePath is ".", we don't want to return it
+    return prettifiedHomeShorthand
+  }
+
+  if (
+    relativePath.length > 0 &&
+    relativePath.length < prettifiedHomeShorthand.length
+  ) {
+    // If relativePath is shroter than the ~/... home path, we use the relative one.
+    return relativePath
+  } else {
+    // ..otherwise just use the ~/... home relative path.
+    return prettifiedHomeShorthand
+  }
+}

package/src/syntax/BridgedType.ts

@@ -0,0 +1,59 @@
+import type { Language } from '../getPlatformSpecs.js'
+import type { SourceFile, SourceImport } from './SourceFile.js'
+import type { Type } from './types/Type.js'
+
+export interface BridgedType<
+  FromLanguage extends Language,
+  ToLanguage extends Language,
+> {
+  /**
+   * The underlying type that is being bridged between {@linkcode FromLanguage} and {@linkcode ToLanguage}
+   */
+  readonly type: Type
+  /**
+   * Whether the underlying type has a valid type (is not void or null)
+   */
+  readonly hasType: boolean
+  /**
+   * Whether this type can be passed by reference
+   */
+  readonly canBePassedByReference: boolean
+  /**
+   * Whether this bridged type needs special handling, or can just be used as-is
+   */
+  readonly needsSpecialHandling: boolean
+
+  /**
+   * Get all imports required for this bridge to work
+   */
+  getRequiredImports(language: Language): SourceImport[]
+
+  /**
+   * Get all extra files that need to be created for this type, as well as the bridge.
+   */
+  getExtraFiles(): SourceFile[]
+
+  /**
+   * Get the code for the type itself in the given language
+   */
+  getTypeCode(language: FromLanguage | ToLanguage): string
+
+  /**
+   * Parse the given parameter from the source language to the given target language, in the given language.
+   * For example, to convert an ArrayBuffer from Swift ({@linkcode from}) to C++ ({@linkcode to}) we
+   * have to wrap it in an ArrayBufferHolder in Swift ({@linkcode inLanguage}), and unwrap
+   * it from the ArrayBufferHolder again in C++ ({@linkcode inLanguage})
+   */
+  parse(
+    parameterName: string,
+    from: FromLanguage,
+    to: ToLanguage,
+    inLanguage: FromLanguage | ToLanguage
+  ): string
+  parse(
+    parameterName: string,
+    from: ToLanguage,
+    to: FromLanguage,
+    inLanguage: FromLanguage | ToLanguage
+  ): string
+}

package/src/syntax/CodeNode.ts

@@ -0,0 +1,24 @@
+import type { Language } from '../getPlatformSpecs.js'
+import type { SourceFile, SourceImport } from './SourceFile.js'
+
+export interface CodeNode {
+  /**
+   * Get the code of this code node (e.g. property, method) in the given language.
+   */
+  getCode(language: Language): string
+  /**
+   * Get all extra definition files this code node needs (e.g. extra type/struct declarations
+   * for complex types), or `[]` if none are required (e.g. if this uses primitive types only)
+   *
+   * All files returned here must be created in the project.
+   * To include them, see {@linkcode getRequiredImports | getRequiredImports()}
+   */
+  getExtraFiles(): SourceFile[]
+  /**
+   * Get all required imports this code node needs (e.g. extra type/struct declarations for complex types),
+   * or `[]` if no imports are required (e.g. if this uses primitive types only).
+   *
+   * All imports returned here must be included in the current file (e.g. `#include "..."` or `import ...`)
+   */
+  getRequiredImports(language: Language): SourceImport[]
+}