@buildvision/nest-sdk-generator 1.1.3

package/src/analyzer/index.ts

@@ -0,0 +1,136 @@
+/**
+ * @file Entrypoint of the source API analyzer, used to generate the final SDK
+ */
+
+import * as fs from 'fs'
+import * as path from 'path'
+import { Project } from 'ts-morph'
+import { Config } from '../config'
+import { debug, panic } from '../logging'
+import { builtinMagicTypes } from './builtin'
+import { analyzeControllers, SdkModules } from './controllers'
+import { flattenSdkResolvedTypes, locateTypesFile, TypesExtractor, TypesExtractorContent } from './extractor'
+
+export interface SdkContent {
+  readonly modules: SdkModules
+  readonly types: TypesExtractorContent
+}
+
+export interface MagicType {
+  readonly package: string
+  readonly typeName: string
+  readonly content: string
+}
+
+export async function analyzerCli(config: Config): Promise<SdkContent> {
+  const started = Date.now()
+
+  const sourcePath = path.resolve(process.cwd(), config.apiInputPath)
+
+  if (!sourcePath) panic('Please provide a source directory')
+
+  if (!fs.existsSync(sourcePath)) panic('Provided source path {magentaBright} does not exist', sourcePath)
+  if (!fs.lstatSync(sourcePath).isDirectory()) panic('Provided source path is not a directory')
+
+  debug(`Analyzing from source directory {yellow}`, sourcePath)
+
+  if (config.jsonOutput) {
+    const jsonOutputParentDir = path.dirname(path.resolve(process.cwd(), config.jsonOutput))
+
+    if (!fs.existsSync(jsonOutputParentDir)) {
+      panic("Output file's parent directory {magentaBright} does not exist.", jsonOutputParentDir)
+    }
+
+    debug('Writing output to {yellow}', config.jsonOutput, config.jsonPrettyOutput ? 'beautified' : 'minified')
+  }
+
+  // ====== Find & parse 'tsconfig.json' ====== //
+  if (config.tsconfigFile && config.tsconfigFile.includes('/')) {
+    panic('Provided tsconfig file name contains slashes')
+  }
+
+  const tsConfigFileName = config.tsconfigFile ?? 'tsconfig.json'
+  const tsConfigFilePath = path.join(sourcePath, tsConfigFileName)
+
+  if (!fs.existsSync(tsConfigFilePath)) {
+    panic('No {yellow} file found in provided source path {yellow}', tsConfigFileName, sourcePath)
+  }
+
+  // Create a 'ts-morph' project
+  const project = new Project({
+    tsConfigFilePath,
+  })
+
+  // Get the list of all TypeScript files in the source directory
+  const sourceTSFiles = project.getSourceFiles().map((file) => path.relative(sourcePath, file.getFilePath()))
+  debug(`Found {magentaBright} source files.`, sourceTSFiles.length)
+
+  // Add them
+  debug('\nAdding them to the source project...')
+
+  let progressByTenth = 0
+  let strLen = sourceTSFiles.length.toString().length
+
+  const hasProgress = (filesTreated: number) => filesTreated / sourceTSFiles.length >= (progressByTenth + 1) / 10
+
+  const controllers = []
+
+  for (let i = 0; i < sourceTSFiles.length; i++) {
+    const file = sourceTSFiles[i]
+
+    if (file.endsWith('.controller.ts')) {
+      controllers.push(file)
+    }
+
+    if (hasProgress(i + 1)) {
+      while (hasProgress(i + 1)) progressByTenth++
+
+      debug(
+        '| Progress: {yellow} ({magentaBright} files) - {green} controller{} found',
+        (progressByTenth * 10).toString().padStart(3, ' ') + '%',
+        `${(i + 1).toString().padStart(strLen, ' ')} / ${sourceTSFiles.length}`,
+        controllers.length.toString().padStart(strLen, ''),
+        controllers.length > 1 ? 's' : ''
+      )
+    }
+  }
+
+  debug('All files were added successfully.\n')
+
+  const modules = analyzeControllers(controllers, sourcePath, project)
+
+  // Builtin magic types are concatenated **after** the configuration's ones, as this allows users to
+  // override the builtin ones if they want. Do **not** change the concatenation order!
+  const magicTypes = (config.magicTypes ?? []).concat(builtinMagicTypes)
+
+  const typesCache = new TypesExtractor(project, sourcePath, magicTypes)
+
+  const typesToExtract = locateTypesFile(flattenSdkResolvedTypes(modules))
+
+  debug('\n==== Extracting {} type' + (typesToExtract.length > 1 ? 's' : '') + ' ====\n', typesToExtract.length)
+
+  for (const loc of typesToExtract) {
+    const result = typesCache.extractType(loc)
+
+    if (result instanceof Error) {
+      panic(result.message)
+    }
+  }
+
+  const content: SdkContent = {
+    modules,
+    types: typesCache.extracted,
+  }
+
+  if (config.jsonOutput) {
+    fs.writeFileSync(
+      config.jsonOutput,
+      JSON.stringify(content, (_, v) => (v instanceof Map ? Object.fromEntries(v) : v), config.jsonPrettyOutput ? 4 : 0),
+      'utf8'
+    )
+  }
+
+  debug('\n===== Done in {green}! ====', ((Date.now() - started) / 1000).toFixed(2) + 's')
+
+  return content
+}

package/src/analyzer/methods.ts

@@ -0,0 +1,166 @@
+/**
+ * @file Analyzer for the source API's methods
+ */
+
+import { blue } from 'chalk'
+import { ClassDeclaration, MethodDeclaration, Node } from 'ts-morph'
+import { debug, format } from '../logging'
+import { analyzeParams, SdkMethodParams } from './params'
+import { analyzeUri, debugUri, Route } from './route'
+import { ResolvedTypeDeps, resolveTypeDependencies } from './typedeps'
+
+/**
+ * SDK interface for a single controller's method
+ */
+export interface SdkMethod {
+  /** Method's name */
+  readonly name: string
+
+  /** Method's HTTP method (e.g. GET / POST) */
+  readonly httpMethod: SdkHttpMethod
+
+  /** Method's return type with resolved dependencies */
+  readonly returnType: ResolvedTypeDeps
+
+  /** Method's parsed route */
+  readonly route: Route
+
+  /** Method's URI path */
+  readonly uriPath: string
+
+  /** Method's parameters */
+  readonly params: SdkMethodParams
+}
+
+/**
+ * HTTP method of a controller's method
+ */
+export enum SdkHttpMethod {
+  Get = 'GET',
+  Post = 'POST',
+  Put = 'PUT',
+  Patch = 'PATCH',
+  Delete = 'DELETE',
+}
+
+/**
+ * Generate a SDK interface for a controller
+ * @param controllerClass The class declaration of the controller
+ * @param controllerUriPrefix Optional URI prefix for this controller (e.g. `@Controller("registrationName")`)
+ * @param filePath Path to the controller's file
+ * @param absoluteSrcPath Absolute path to the source directory
+ */
+export function analyzeMethods(
+  controllerClass: ClassDeclaration,
+  controllerUriPrefix: string | null,
+  filePath: string,
+  absoluteSrcPath: string
+): SdkMethod[] | Error {
+  // Output variable
+  const collected = new Array<SdkMethod>()
+
+  // Get the list of all methods
+  const methods = controllerClass.forEachChildAsArray().filter((node) => node instanceof MethodDeclaration) as MethodDeclaration[]
+
+  for (const method of methods) {
+    const methodName = method.getName()
+
+    debug('├─ Found method: {yellow}', methodName)
+
+    // Get the HTTP decorator(s) of the method
+    const decorators = method.getDecorators().filter((dec) => Object.keys(SdkHttpMethod).includes(dec.getName()))
+
+    // We expect to have exactly one HTTP decorator
+    if (decorators.length > 1) {
+      // If there is more than one decorator, that's invalid, so we can't analyze the method
+      return new Error(
+        format('├─── Detected multiple HTTP decorators on method: {yellow}' + decorators.map((dec) => dec.getName()).join(','))
+      )
+    } else if (decorators.length === 0) {
+      // If there isn't any HTTP decorator, this is simply not a method available from the outside and so we won't generate an interface for it
+      debug('├─── Skipping this method as it does not have an HTTP decorator')
+      continue
+    }
+
+    // Get the HTTP decorator
+    const dec = decorators[0]
+
+    // We need to put a '@ts-ignore' here because TypeScript doesn't like indexing an enumeration with a string key, although this works fine
+    // @ts-ignore
+    const httpMethod = SdkHttpMethod[dec.getName()]
+
+    debug('├─── Detected HTTP method: {magentaBright}', httpMethod.toLocaleUpperCase())
+
+    // Get the arguments provided to the HTTP decorator (we expect one, the URI path)
+    const decArgs = dec.getArguments()
+
+    // The method's URI path
+    let uriPath: string
+
+    // We expect the decorator to have exactly one argument
+    if (decArgs.length > 1) {
+      // If we have more than one argument, that's invalid (or at least not supported here), so we can't analyze the method
+      return new Error(`Multiple (${decArgs.length}) arguments were provided to the HTTP decorator`)
+    } else if (decArgs.length === 0) {
+      // If there is no argument, we take the method's name as the URI path
+      debug('├─── No argument found for decorator, using base URI path.')
+      uriPath = ''
+    } else {
+      // If we have exactly one argument, hurray! That's our URI path.
+      const uriNameDec = decArgs[0]
+
+      // Variables are not supported
+      if (!Node.isStringLiteral(uriNameDec)) {
+        return new Error(
+          format('├─── The argument provided to the HTTP decorator is not a string literal:\n>> {cyan}', uriNameDec.getText())
+        )
+      }
+
+      // Update the method's URI path
+      uriPath = uriNameDec.getLiteralText()
+
+      debug('├─── Detected argument in HTTP decorator, mapping this method to custom URI name')
+    }
+
+    debug('├─── Detected URI name: {yellow}', uriPath)
+
+    // Analyze the method's URI
+    const route = analyzeUri(controllerUriPrefix ? (uriPath ? `/${controllerUriPrefix}/${uriPath}` : `/` + controllerUriPrefix) : uriPath)
+
+    if (route instanceof Error) {
+      return new Error(
+        '├─── Detected unsupported URI format:\n' +
+          route.message
+            .split('\n')
+            .map((line) => '├───── ' + line)
+            .join('\n')
+      )
+    }
+
+    debug('├─── Parsed URI name to route: {yellow}', debugUri(route, blue))
+
+    // Analyze the method's arguments
+    debug('├─── Analyzing arguments...')
+    const params = analyzeParams(httpMethod, route, method.getParameters(), filePath, absoluteSrcPath)
+
+    if (params instanceof Error) return params
+
+    // Get the method's return type
+    debug('├─── Resolving return type...')
+    const returnType = resolveTypeDependencies(method.getReturnType(), filePath, absoluteSrcPath)
+
+    debug('├─── Detected return type: {cyan}', returnType.resolvedType)
+
+    // Success!
+    collected.push({
+      name: methodName,
+      httpMethod,
+      returnType,
+      route,
+      uriPath,
+      params,
+    })
+  }
+
+  return collected
+}

package/src/analyzer/module.ts

@@ -0,0 +1,56 @@
+/**
+ * @file Analyzer for the source API's modules
+ */
+
+import * as path from 'path'
+import { Node, Project } from 'ts-morph'
+import { format, panic } from '../logging'
+
+/**
+ * Get the name of a module
+ * @param project TS-Morph project the module is contained in
+ * @param modulePath Path to the module's file
+ * @param sourcePath Path to the TypeScript root directory
+ */
+export function getModuleName(project: Project, modulePath: string, sourcePath: string): string {
+  // Prepare the source file to analyze
+  const file = project.getSourceFileOrThrow(path.resolve(sourcePath, modulePath))
+
+  // Find the module class declaration
+  const classDecl = file.forEachChildAsArray().find((node) => Node.isClassDeclaration(node) && node.getDecorators().length > 0)
+
+  if (!classDecl) {
+    panic('No class declaration found in module at {yellow}', modulePath)
+  }
+
+  if (!Node.isClassDeclaration(classDecl))
+    panic('Internal error: found class declaration statement which is not an instance of ClassDeclaration')
+
+  const moduleName = classDecl.getName()
+
+  if (moduleName === undefined) {
+    panic('Internal error: failed to retrieve name of declared class')
+  }
+
+  const decorators = classDecl.getDecorators()
+
+  if (decorators.length > 1) {
+    panic(`Found multiple decorators on module class {yellow} declared at {yellow}`, moduleName, modulePath)
+  }
+
+  const decName = decorators[0].getName()
+
+  if (decName !== 'Module') {
+    panic(
+      format(
+        `The decorator on module class {yellow} was expected to be a {yellow}, found an {yellow} instead\nModule path is: {yellow}`,
+        moduleName,
+        '@Module',
+        '@' + decName,
+        modulePath
+      )
+    )
+  }
+
+  return moduleName.substr(0, 1).toLocaleLowerCase() + moduleName.substr(1)
+}

package/src/analyzer/params.ts

@@ -0,0 +1,241 @@
+/**
+ * @file Analyzer for the source API's controllers' methods' parameters
+ */
+
+import { ParameterDeclaration } from 'ts-morph'
+import { debug, format, warn } from '../logging'
+import { expectSingleStrLitDecorator } from './decorator'
+import { SdkHttpMethod } from './methods'
+import { paramsOfRoute, Route } from './route'
+import { ResolvedTypeDeps, resolveTypeDependencies } from './typedeps'
+
+/**
+ * SDK interface for a controller's method's parameters
+ */
+export interface SdkMethodParams {
+  /** Route parameters */
+  parameters: Map<string, ResolvedTypeDeps> | null
+
+  /** Query parameters */
+  query: Map<string, ResolvedTypeDeps> | null
+
+  /** Body parameters */
+  body: SdkMethodBodyParam | null
+}
+
+/**
+ * Single body parameter in a SDK's method
+ */
+export type SdkMethodBodyParam = { full: true; type: ResolvedTypeDeps } | { full: false; fields: Map<string, ResolvedTypeDeps> }
+
+/**
+ * Generate a SDK interface for a controller's method's parameters
+ * @param httpMethod The method's HTTP method
+ * @param route The method's route
+ * @param args The method's arguments
+ * @param filePath Path to the controller's file
+ * @param absoluteSrcPath Absolute path to the source directory
+ * @returns A SDK interface for the method's parameters
+ */
+export function analyzeParams(
+  httpMethod: SdkHttpMethod,
+  route: Route,
+  args: ParameterDeclaration[],
+  filePath: string,
+  absoluteSrcPath: string
+): SdkMethodParams | Error {
+  // The collected informations we will return
+  const collected: SdkMethodParams = {
+    parameters: null,
+    query: null,
+    body: null,
+  }
+
+  // Get the named parameters of the route
+  const routeParams = paramsOfRoute(route)
+
+  // Treat all arguments (to not confuse with the route's parameters)
+  for (const arg of args) {
+    const name = arg.getName()
+
+    debug('├───── Detected argument: {yellow}', name)
+
+    // Arguments are collected as soon as they have a decorator like @Query() or @Body()
+    const decs = arg.getDecorators()
+
+    if (decs.length === 0) {
+      // If we have no argument, this is not an argument we are interested in, so we just skip it
+      debug('├───── Skipping this argument as it does not have a decorator')
+      continue
+    } else if (decs.length > 1) {
+      // If we have more than one decorator, this could mean we have for instance an @NotEmpty() @Query() or something like this,
+      //  which is currently not supported.
+      return new Error('Skipping this argument as it has multiple decorators, which is currently not supported')
+    }
+
+    // Get the only decrator
+    const dec = decs[0]
+    const decName = dec.getName()
+
+    // Treat the @Param() decorator
+    if (decName === 'Param') {
+      debug('├───── Detected decorator {blue}', '@Param')
+
+      // We expect a single string argument for this decorator,
+      // which is the route parameter's name
+      const paramName = expectSingleStrLitDecorator(dec)
+
+      if (paramName instanceof Error) return paramName
+
+      // If there is no argument, this argument is a global receiver which maps the full set of parameters
+      // We theorically *could* extract the type informations from this object type, but this would be insanely complex
+      // So, we just skip it as it's a lot more simple, and is not commonly used anyway as it has a set of downsides
+      if (paramName === null) {
+        warn('├───── Skipping this argument as it is a generic parameters receiver, which is currently not supported')
+        continue
+      }
+
+      // Ensure the specified parameter appears in the method's route
+      if (!routeParams.includes(paramName)) return new Error(format('├───── Cannot map unknown parameter {yellow}', paramName))
+
+      debug('├───── Mapping argument to parameter: {yellow}', paramName)
+
+      // Get the route parameter's type
+      const typ = resolveTypeDependencies(arg.getType(), filePath, absoluteSrcPath)
+
+      debug('├───── Detected parameter type: {yellow} ({magentaBright} dependencies)', typ.resolvedType, typ.dependencies.size)
+
+      // Update the method's route parameters
+
+      if (paramName in {}) {
+        return new Error(
+          format(`Detected @Param() field whose name {yellow} collides with a JavaScript's native object property`, paramName)
+        )
+      }
+
+      collected.parameters ??= new Map()
+      collected.parameters.set(paramName, typ)
+    }
+
+    // Treat the @Query() decorator
+    else if (decName === 'Query') {
+      debug('├───── Detected decorator {blue}', '@Query')
+
+      // We expect a single string argument for this decorator,
+      // which is the query parameter's name
+      const queryName = expectSingleStrLitDecorator(dec)
+
+      if (queryName instanceof Error) return queryName
+
+      // If there is no argument, this argument is a global receiver which maps the full set of parameters
+      // We theorically *could* extract the type informations from this object type, but this would be insanely complex
+      // So, we just skip it as it's a lot more simple, and is not commonly used anyway as it has a set of downsides
+      if (queryName === null) {
+        warn('├───── Skipping this argument as it is a generic query receiver')
+        continue
+      }
+
+      debug('├───── Mapping argument to query: {yellow}', queryName)
+
+      // Get the parameter's type
+      const typ = resolveTypeDependencies(arg.getType(), filePath, absoluteSrcPath)
+
+      debug(`├───── Detected query type: {yellow} ({magentaBright} dependencies)`, typ.resolvedType, typ.dependencies.size)
+
+      // Update the method's query parameter
+
+      if (queryName in {}) {
+        return new Error(
+          format(`Detected @Query() field whose name {yellow} collides with a JavaScript's native object property`, queryName)
+        )
+      }
+
+      collected.query ??= new Map()
+      collected.query.set(queryName, typ)
+    }
+
+    // Treat the @Body() decorator
+    else if (decName === 'Body') {
+      debug('├───── Detected decorator {blue}', '@Body')
+
+      // GET requests cannot have a BODY
+      if (httpMethod === SdkHttpMethod.Get) {
+        return new Error('GET requests cannot have a BODY!')
+      }
+
+      // We expect a single string argument for this decorator,
+      // which is the body field's name
+      const fieldName = expectSingleStrLitDecorator(dec)
+
+      if (fieldName instanceof Error) return fieldName
+
+      // Get the field's type
+      const typ = resolveTypeDependencies(arg.getType(), filePath, absoluteSrcPath)
+
+      const depsCount = typ.dependencies.size
+
+      debug(
+        `├───── Detected BODY type: {cyan} ({magentaBright} ${
+          depsCount === 0 ? 'no dependency' : depsCount > 1 ? 'dependencies' : 'dependency'
+        })`,
+        typ.resolvedType,
+        depsCount
+      )
+
+      // If there no name was provided to the decorator, then the decorator is a generic receiver which means it maps to the full body type
+      // This also means we can map the BODY type to this argument's type
+      if (fieldName === null) {
+        const body = collected.body
+
+        // If we previously had an @Body(<name>) decorator on another argument, we have an important risk of mistyping
+        // => e.g. `@Body("a") a: string, @Body() body: { a: number }` is invalid as the type for the `a` field mismatches
+        // => It's easy to make an error as the @Body() type is often hidden behind a DTO
+        // But that's extremely complex to check automatically, so we just display a warning instead
+        // Also, that's not the kind of thing we make on purpose very often, so it's more likely it's an error, which makes it even more important
+        //  to display a warning here.
+        if (body?.full === false)
+          warn('├───── Detected full @Body() decorator after a single parameter. This is considered a bad practice, avoid it if you can!')
+        // Having two generic @Body() decorators is meaningless and will likey lead to errors, so we return a precise error here
+        else if (body?.full) {
+          return new Error(
+            format(
+              `Detected two @Body() decorators: found {yellow} previously, while method argument {yellow} indicates type {yellow}`,
+              body.type.resolvedType,
+              name,
+              typ.resolvedType
+            )
+          )
+        }
+
+        debug("├───── Mapping argument to full request's body")
+
+        // Update the whole BODY type
+        collected.body = { full: true, type: typ }
+      } else {
+        // Here we have an @Body(<string>) decorator
+
+        // If we previously had an @Body() decorator, this can lead to several types of errors (see the big comment above for more informations)
+        if (collected.body?.full) {
+          warn('├───── Detected single @Body() decorator after a full parameter. This is considered a bad practice, avoid it if you can!')
+        } else {
+          debug('├───── Mapping argument to BODY field: {yellow}', fieldName)
+
+          // Update the BODY type by adding the current field to it
+
+          if (fieldName in {}) {
+            return new Error(
+              format(`Detected @Body() field whose name {yellow} collides with a JavaScript's native object property`, fieldName)
+            )
+          }
+
+          collected.body ??= { full: false, fields: new Map() }
+
+          collected.body.fields.set(fieldName, typ)
+        }
+      }
+    }
+  }
+
+  // Success!
+  return collected
+}