nitrogen 0.2.23 → 0.29.4

package/src/config/NitroUserConfig.ts

@@ -0,0 +1,105 @@
+import { z } from 'zod'
+
+// Namespaces and package names in C++/Java will be matched with a regex.
+const safeNamePattern = /^[a-zA-Z_][a-zA-Z0-9_]*$/
+
+const isNotReservedKeyword = (val: string) =>
+  !['core', 'nitro', 'NitroModules'].includes(val)
+const isReservedKeywordError = {
+  message: `This value is reserved and cannot be used!`,
+}
+
+export const NitroUserConfigSchema = z.object({
+  /**
+   * Represents the C++ namespace of the module that will be generated.
+   *
+   * This can have multiple sub-namespaces, and is always relative to `margelo::nitro`.
+   * @example `['image']` -> `margelo::nitro::image`
+   */
+  cxxNamespace: z
+    .array(
+      z
+        .string()
+        .regex(safeNamePattern)
+        .refine(isNotReservedKeyword, isReservedKeywordError)
+    )
+    .min(1),
+  /**
+   * iOS specific options.
+   */
+  ios: z.object({
+    /**
+     * Represents the iOS module name of the module that will be generated.
+     *
+     * This will be used to generate Swift bridges, as those are always namespaced within the clang module.
+     *
+     * If you are using CocoaPods, this should be the Pod name defined in the `.podspec`.
+     * @example `NitroTest`
+     */
+    iosModuleName: z
+      .string()
+      .regex(safeNamePattern)
+      .refine(isNotReservedKeyword, isReservedKeywordError),
+  }),
+  /**
+   * Android specific options.
+   */
+  android: z.object({
+    /**
+     * Represents the Android namespace ("package") of the module that will be generated.
+     *
+     * This can have multiple sub-namespaces, and is always relative to `com.margelo.nitro`.
+     * @example `['image']` -> `com.margelo.nitro.image`
+     */
+    androidNamespace: z
+      .array(
+        z
+          .string()
+          .regex(safeNamePattern)
+          .refine(isNotReservedKeyword, isReservedKeywordError)
+      )
+      .min(1),
+
+    /**
+     * Represents the name of the Android C++ library (aka name in CMakeLists.txt `add_library(..)`).
+     * This will be loaded via `System.loadLibrary(...)`.
+     * @example `NitroTest`
+     */
+    androidCxxLibName: z
+      .string()
+      .regex(safeNamePattern)
+      .refine(isNotReservedKeyword, isReservedKeywordError),
+  }),
+  /**
+   * Configures the code that gets generated for autolinking (registering)
+   * Hybrid Object constructors.
+   *
+   * Each class listed here needs to have a default constructor/initializer that takes
+   * zero arguments.
+   */
+  autolinking: z.record(
+    z.string(),
+    z.object({
+      cpp: z.string().optional(),
+      swift: z.string().optional(),
+      kotlin: z.string().optional(),
+    })
+  ),
+  /**
+   * A list of paths relative to the project directory that should be ignored by nitrogen.
+   * Nitrogen will not look for `.nitro.ts` files in these directories.
+   */
+  ignorePaths: z.array(z.string()).optional(),
+  /**
+   * Configures whether all nitro-generated files are marked as
+   * [`linguist-generated`](https://docs.github.com/en/repositories/working-with-files/managing-files/customizing-how-changed-files-appear-on-github)
+   * for GitHub. This disables diffing for generated content and excludes them from language statistics.
+   * This is controlled via `nitrogen/generated/.gitattributes`.
+   */
+  gitAttributesGeneratedFlag: z.boolean().optional().default(true),
+})
+
+/**
+ * Represents the structure of a `nitro.json` config file.
+ */
+export type NitroUserConfig = z.infer<typeof NitroUserConfigSchema>

package/src/config/getConfig.ts

@@ -0,0 +1,91 @@
+import { ZodError } from 'zod'
+import fs from 'fs'
+import {
+  NitroUserConfigSchema,
+  type NitroUserConfig,
+} from './NitroUserConfig.js'
+import chalk from 'chalk'
+
+function readFile(configPath: string): string {
+  try {
+    return fs.readFileSync(configPath, 'utf8')
+  } catch (error) {
+    if (typeof error === 'object' && error != null && 'code' in error) {
+      switch (error.code) {
+        case 'ENOENT':
+        case 'ENOTDIR':
+          console.error(
+            `❌  The path ${chalk.underline(configPath)} does not exist! Create a ${chalk.underline('nitro.json')} file and try again.`
+          )
+          process.exit(1)
+          // @ts-expect-error
+          break
+        default:
+          throw error
+      }
+    } else {
+      // different kind of error, throw it.
+      throw error
+    }
+  }
+}
+
+function propPathToString(propPath: PropertyKey[]): string {
+  if (propPath.length === 0) return ''
+  const prop = propPath.reduce<string>((prev, curr) => {
+    if (typeof curr === 'string') {
+      return `${prev}.${curr}`
+    } else if (typeof curr === 'number') {
+      return `${prev}[${curr}]`
+    } else {
+      return prev
+    }
+  }, '')
+  return prop.slice(1)
+}
+
+function parseConfig(json: string): NitroUserConfig {
+  let object: unknown
+  try {
+    object = JSON.parse(json)
+  } catch (error) {
+    throw new Error(
+      `Failed to parse nitro.json config as JSON! Make sure it has a valid JSON syntax. JSON: ${json}`,
+      {
+        cause: error,
+      }
+    )
+  }
+
+  try {
+    return NitroUserConfigSchema.parse(object)
+  } catch (error) {
+    if (error instanceof ZodError) {
+      const issues = error.issues.map((i) => {
+        const prop = propPathToString(i.path)
+        switch (i.code) {
+          case 'invalid_type':
+            return `\`${prop}\` must be ${i.expected}, but is ${i.input}.`
+          case 'invalid_value':
+          case 'invalid_union':
+          case 'invalid_element':
+            return `\`${prop}\` is not a valid & safe string. It must only contain alphanumeric characters and must not start with a number.`
+          default:
+            return `\`${prop}\`: ${i.message} (${i.code})`
+        }
+      })
+      console.error(
+        `❌  Invalid nitro.json config file! ${issues.join(' - also, ')}`
+      )
+      process.exit(1)
+    } else {
+      throw error
+    }
+  }
+}
+
+export function readUserConfig(configPath: string): NitroUserConfig {
+  const json = readFile(configPath)
+  const config = parseConfig(json)
+  return config
+}

package/src/createGitAttributes.ts

@@ -0,0 +1,15 @@
+import fs from 'fs/promises'
+import path from 'path'
+
+export async function createGitAttributes(
+  markAsGenerated: boolean,
+  folder: string
+): Promise<string> {
+  const file = path.join(folder, '.gitattributes')
+  // Marks all files in this current folder as "generated"
+  const content = `
+** linguist-generated=${markAsGenerated}
+  `.trim()
+  await fs.writeFile(file, content + '\n', 'utf-8')
+  return file
+}

package/src/createPlatformSpec.ts

@@ -0,0 +1,176 @@
+import { Node, Type } from 'ts-morph'
+import type { SourceFile } from './syntax/SourceFile.js'
+import { createCppHybridObject } from './syntax/c++/CppHybridObject.js'
+import {
+  extendsHybridObject,
+  isHybridView,
+  isAnyHybridSubclass,
+  isDirectlyHybridObject,
+  type Language,
+  isHybridViewProps,
+  isHybridViewMethods,
+} from './getPlatformSpecs.js'
+import type { HybridObjectSpec } from './syntax/HybridObjectSpec.js'
+import { Property } from './syntax/Property.js'
+import { Method } from './syntax/Method.js'
+import { createSwiftHybridObject } from './syntax/swift/SwiftHybridObject.js'
+import { createKotlinHybridObject } from './syntax/kotlin/KotlinHybridObject.js'
+import { createType } from './syntax/createType.js'
+import { Parameter } from './syntax/Parameter.js'
+import { getBaseTypes, getHybridObjectNitroModuleConfig } from './utils.js'
+import { NitroConfig } from './config/NitroConfig.js'
+
+export function generatePlatformFiles(
+  interfaceType: Type,
+  language: Language
+): SourceFile[] {
+  const spec = getHybridObjectSpec(interfaceType, language)
+
+  // TODO: We currently just call this so the HybridObject itself is a "known type".
+  // This causes the Swift Umbrella header to properly forward-declare it.
+  // Without this, only Hybrid Objects that are actually used in public APIs will be forward-declared.
+  createType(language, interfaceType, false)
+
+  switch (language) {
+    case 'c++':
+      return generateCppFiles(spec)
+    case 'swift':
+      return generateSwiftFiles(spec)
+    case 'kotlin':
+      return generateKotlinFiles(spec)
+    default:
+      throw new Error(`Language "${language}" is not supported!`)
+  }
+}
+
+function getHybridObjectSpec(type: Type, language: Language): HybridObjectSpec {
+  const config = getHybridObjectNitroModuleConfig(type) ?? NitroConfig.current
+
+  if (isHybridView(type)) {
+    const symbol = type.getAliasSymbolOrThrow()
+    const name = symbol.getEscapedName()
+
+    // It's a Hybrid View - the `Props & Methods` types are just intersected together.
+    const unions = type.getIntersectionTypes()
+    const props = unions.find((t) => isHybridViewProps(t))
+    const methods = unions.find((t) => isHybridViewMethods(t))
+    if (props == null)
+      throw new Error(
+        `Props cannot be null! ${name}<...> (HybridView) requires type arguments.`
+      )
+    const propsSpec = getHybridObjectSpec(props, language)
+    const methodsSpec =
+      methods != null ? getHybridObjectSpec(methods, language) : undefined
+
+    return {
+      baseTypes: [],
+      isHybridView: true,
+      language: language,
+      methods: methodsSpec?.methods ?? [],
+      properties: propsSpec.properties,
+      name: name,
+      config: config,
+    }
+  }
+
+  const symbol = type.getSymbolOrThrow()
+  const name = symbol.getEscapedName()
+
+  const properties: Property[] = []
+  const methods: Method[] = []
+  for (const prop of type.getProperties()) {
+    const declarations = prop.getDeclarations()
+    if (declarations.length > 1) {
+      throw new Error(
+        `${name}: Function overloading is not supported! (In "${prop.getName()}")`
+      )
+    }
+    let declaration = declarations[0]
+    if (declaration == null) {
+      throw new Error(
+        `${name}: Property "${prop.getName()}" does not have a type declaration!`
+      )
+    }
+
+    const parent = declaration.getParentOrThrow().getType()
+
+    if (parent === type) {
+      // it's an own property. declared literally here. fine.
+    } else if (
+      extendsHybridObject(parent, true) ||
+      isDirectlyHybridObject(parent)
+    ) {
+      // it's coming from a base class that is already a HybridObject. We can grab this via inheritance.
+      // don't generate this property natively.
+      continue
+    } else {
+      // it's coming from any TypeScript type that is not a HybridObject.
+      // Maybe just a literal interface, then we copy over the props.
+    }
+
+    if (Node.isPropertySignature(declaration)) {
+      const t = declaration.getType()
+      const propType = createType(
+        language,
+        t,
+        prop.isOptional() || t.isNullable()
+      )
+      properties.push(
+        new Property(prop.getName(), propType, declaration.isReadonly())
+      )
+    } else if (Node.isMethodSignature(declaration)) {
+      const returnType = declaration.getReturnType()
+      const methodReturnType = createType(
+        language,
+        returnType,
+        returnType.isNullable()
+      )
+      const methodParameters = declaration
+        .getParameters()
+        .map((p) => new Parameter(p, language))
+      methods.push(
+        new Method(prop.getName(), methodReturnType, methodParameters)
+      )
+    } else {
+      throw new Error(
+        `${name}: Property "${prop.getName()}" is neither a property, nor a method!`
+      )
+    }
+  }
+
+  const bases = getBaseTypes(type)
+    .filter((t) => isAnyHybridSubclass(t))
+    .map((t) => getHybridObjectSpec(t, language))
+
+  const spec: HybridObjectSpec = {
+    language: language,
+    name: name,
+    properties: properties,
+    methods: methods,
+    baseTypes: bases,
+    isHybridView: isHybridView(type),
+    config: config,
+  }
+  return spec
+}
+
+function generateCppFiles(spec: HybridObjectSpec): SourceFile[] {
+  const cppFiles = createCppHybridObject(spec)
+  return cppFiles
+}
+
+function generateSwiftFiles(spec: HybridObjectSpec): SourceFile[] {
+  // 1. Always generate a C++ spec for the shared layer and type declarations (enums, interfaces, ...)
+  const cppFiles = generateCppFiles(spec)
+  // 2. Generate Swift specific files and potentially a C++ binding layer
+  const swiftFiles = createSwiftHybridObject(spec)
+  return [...cppFiles, ...swiftFiles]
+}
+
+function generateKotlinFiles(spec: HybridObjectSpec): SourceFile[] {
+  // 1. Always generate a C++ spec for the shared layer and type declarations (enums, interfaces, ...)
+  const cppFiles = generateCppFiles(spec)
+  // 2. Generate Kotlin specific files and potentially a C++ binding layer
+  const kotlinFiles = createKotlinHybridObject(spec)
+  return [...cppFiles, ...kotlinFiles]
+}

package/src/getFiles.ts

@@ -0,0 +1,31 @@
+import { Dirent, promises as fs } from 'fs'
+import path from 'path'
+
+function getFilePath(file: Dirent, rootDir: string): string {
+  const dir = file.parentPath ?? file.path ?? rootDir
+  return path.join(dir, file.name)
+}
+
+export async function getFiles(directory: string): Promise<string[]> {
+  try {
+    const files = await fs.readdir(directory, {
+      recursive: true,
+      withFileTypes: true,
+    })
+
+    return files.filter((f) => f.isFile()).map((f) => getFilePath(f, directory))
+  } catch (error) {
+    if (
+      typeof error === 'object' &&
+      error != null &&
+      'code' in error &&
+      error.code === 'ENOENT'
+    ) {
+      // directory does not exist
+      return []
+    } else {
+      // different error
+      throw error
+    }
+  }
+}

package/src/getPlatformSpecs.ts

@@ -0,0 +1,202 @@
+import type { PlatformSpec } from 'react-native-nitro-modules'
+import type { InterfaceDeclaration, Type, TypeAliasDeclaration } from 'ts-morph'
+import { Node, Symbol } from 'ts-morph'
+import { getBaseTypes } from './utils.js'
+
+export type Platform = keyof Required<PlatformSpec>
+export type Language = Required<PlatformSpec>[keyof PlatformSpec]
+
+const platformLanguages: { [K in Platform]: Language[] } = {
+  ios: ['swift', 'c++'],
+  android: ['kotlin', 'c++'],
+}
+const allPlatforms = Object.keys(platformLanguages) as Platform[]
+const allLanguages = Object.values(platformLanguages).flatMap((l) => l)
+
+function isValidLanguage(language: string | undefined): language is Language {
+  if (language == null) {
+    return false
+  }
+  return allLanguages.includes(language as Language)
+}
+
+function isValidPlatform(platform: string): platform is Platform {
+  return allPlatforms.includes(platform as Platform)
+}
+
+function getLiteralValue(symbol: Symbol): string | undefined {
+  const value = symbol.getValueDeclaration()
+  if (value == null) {
+    return undefined
+  }
+  const type = value.getType()
+  const literal = type.getLiteralValue()
+  if (typeof literal === 'string') {
+    return literal
+  }
+  return undefined
+}
+
+// TODO: The type casting result here doesn't really work in TS.
+function isValidLanguageForPlatform(
+  language: Language,
+  platform: Platform
+): language is Required<PlatformSpec>[typeof platform] {
+  return platformLanguages[platform].includes(language)
+}
+
+function getPlatformSpec(typeName: string, platformSpecs: Type): PlatformSpec {
+  const result: PlatformSpec = {}
+
+  // Properties (ios, android)
+  const properties = platformSpecs.getProperties()
+  for (const property of properties) {
+    // Property name (ios, android)
+    const platform = property.getName()
+    if (!isValidPlatform(platform)) {
+      console.warn(
+        `    ⚠️   ${typeName} does not properly extend HybridObject<T> - "${platform}" is not a valid Platform! ` +
+          `Valid platforms are: [${allPlatforms.join(', ')}]`
+      )
+      continue
+    }
+
+    // Value (swift, kotlin, c++)
+    const language = getLiteralValue(property)
+    if (!isValidLanguage(language)) {
+      console.warn(
+        `    ⚠️   ${typeName}: Language ${language} is not a valid language for ${platform}! ` +
+          `Valid languages are: [${platformLanguages[platform].join(', ')}]`
+      )
+      continue
+    }
+
+    // Double-check that language works on this platform (android: kotlin/c++, ios: swift/c++)
+    if (!isValidLanguageForPlatform(language, platform)) {
+      console.warn(
+        `    ⚠️   ${typeName}: Language ${language} is not a valid language for ${platform}! ` +
+          `Valid languages are: [${platformLanguages[platform].join(', ')}]`
+      )
+      continue
+    }
+
+    // @ts-expect-error because TypeScript isn't smart enough yet to correctly cast after the `isValidLanguageForPlatform` check.
+    result[platform] = language
+  }
+
+  return result
+}
+
+function isDirectlyType(type: Type, name: string): boolean {
+  const symbol = type.getSymbol() ?? type.getAliasSymbol()
+  if (symbol?.getName() === name) {
+    return true
+  }
+  return false
+}
+
+function extendsType(type: Type, name: string, recursive: boolean): boolean {
+  for (const base of getBaseTypes(type)) {
+    const isHybrid = isDirectlyType(base, name)
+    if (isHybrid) {
+      return true
+    }
+    if (recursive) {
+      const baseExtends = extendsType(base, name, recursive)
+      if (baseExtends) {
+        return true
+      }
+    }
+  }
+  return false
+}
+
+export function isDirectlyHybridObject(type: Type): boolean {
+  return isDirectlyType(type, 'HybridObject')
+}
+
+export function extendsHybridObject(type: Type, recursive: boolean): boolean {
+  return extendsType(type, 'HybridObject', recursive)
+}
+
+export function isHybridViewProps(type: Type): boolean {
+  return extendsType(type, 'HybridViewProps', true)
+}
+export function isHybridViewMethods(type: Type): boolean {
+  return extendsType(type, 'HybridViewMethods', true)
+}
+
+export function isHybridView(type: Type): boolean {
+  // HybridViews are type aliases for `HybridView`, and `Props & Methods` are just intersected together.
+  const unionTypes = type.getIntersectionTypes()
+  for (const union of unionTypes) {
+    const symbol = union.getSymbol()
+    if (symbol == null) return false
+    return symbol.getName() === 'HybridViewTag'
+  }
+  return false
+}
+
+export function isAnyHybridSubclass(type: Type): boolean {
+  if (isDirectlyHybridObject(type)) return false
+
+  if (isHybridView(type)) return true
+
+  if (extendsHybridObject(type, true)) return true
+
+  return false
+}
+
+/**
+ * If the given interface ({@linkcode declaration}) extends `HybridObject`,
+ * this method returns the platforms it exists on.
+ * If it doesn't extend `HybridObject`, this returns `undefined`.
+ */
+export function getHybridObjectPlatforms(
+  declaration: InterfaceDeclaration | TypeAliasDeclaration
+): PlatformSpec | undefined {
+  const base = getBaseTypes(declaration.getType()).find((t) =>
+    isDirectlyHybridObject(t)
+  )
+  if (base == null) {
+    // this type does not extend `HybridObject`.
+    throw new Error(
+      `Couldn't find HybridObject<..> base for ${declaration.getName()}! (${declaration.getText()})`
+    )
+  }
+
+  const genericArguments = base.getTypeArguments()
+  const platformSpecsArgument = genericArguments[0]
+  if (platformSpecsArgument == null) {
+    // it uses `HybridObject` without generic arguments. This defaults to C++
+    return { android: 'c++', ios: 'c++' }
+  }
+
+  return getPlatformSpec(declaration.getName(), platformSpecsArgument)
+}
+
+export function getHybridViewPlatforms(
+  view: InterfaceDeclaration | TypeAliasDeclaration
+): PlatformSpec | undefined {
+  if (Node.isTypeAliasDeclaration(view)) {
+    const hybridViewTypeNode = view.getTypeNode()
+
+    const isHybridViewType =
+      Node.isTypeReference(hybridViewTypeNode) &&
+      hybridViewTypeNode.getTypeName().getText() === 'HybridView'
+
+    if (!isHybridViewType) {
+      return
+    }
+
+    const genericArguments = hybridViewTypeNode.getTypeArguments()
+
+    const platformSpecArg = genericArguments[2]
+    if (platformSpecArg != null) {
+      return getPlatformSpec(view.getName(), platformSpecArg.getType())
+    }
+  }
+
+  // it uses `HybridObject` without generic arguments. This defaults to platform native languages
+  return { ios: 'swift', android: 'kotlin' }
+}