feat: setup typedoc

Author: thetutlage

.github/workflows/release.yml

@@ -16,7 +16,7 @@ jobs:
 
       - uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: 24
 
       - name: git config
         run: |

index.ts

@@ -10,3 +10,4 @@
 export { Bundler } from './src/bundler.ts'
 export { DevServer } from './src/dev_server.ts'
 export { TestRunner } from './src/test_runner.ts'
+export { SUPPORTED_PACKAGE_MANAGERS } from './src/bundler.ts'

package.json

@@ -19,6 +19,7 @@
     ".": "./build/index.js",
     "./code_transformer": "./build/src/code_transformer/main.js",
     "./routes_scanner": "./build/src/code_scanners/routes_scanner/main.js",
+    "./helpers": "./build/src/helpers.js",
     "./types": "./build/src/types/main.js"
   },
   "scripts": {
@@ -61,7 +62,7 @@
     "typescript": "^5.9.2"
   },
   "dependencies": {
-    "@adonisjs/env": "^6.2.0",
+    "@adonisjs/env": "^7.0.0-next.1",
     "@antfu/install-pkg": "^1.1.0",
     "@ast-grep/napi": "^0.39.4",
     "@poppinss/cliui": "^6.4.4",
@@ -105,6 +106,8 @@
     "entry": [
       "./index.ts",
       "./src/types/main.ts",
+      "./src/helpers.ts",
+      "./src/code_scanners/routes_scanner/main.ts",
       "./src/code_transformer/main.ts"
     ],
     "outDir": "./build",

src/ast_file_system.ts

@@ -15,13 +15,24 @@ import debug from './debug.ts'
 /**
  * An abstraction around converting files to an AST and caching
  * them forever. The cache could be cleared manually.
+ *
+ * @example
+ * const astfs = new AstFileSystem()
+ * const node = await astfs.get('./app/controllers/users_controller.ts')
+ * astfs.clear('./app/controllers/users_controller.ts')
  */
 export class AstFileSystem {
+  /**
+   * Cache map storing parsed AST nodes by file path
+   */
   #cache: Map<string, SgNode> = new Map()
 
   /**
    * Returns the file contents as AST-grep node and caches it
    * forever.
+   *
+   * @param filePath - The path to the file to parse
+   * @returns Promise resolving to the AST-grep node
    */
   async get(filePath: string): Promise<SgNode> {
     const cached = this.#cache.get(filePath)
@@ -38,6 +49,8 @@ export class AstFileSystem {
 
   /**
    * Clear AST cache for a single file or all the files
+   *
+   * @param filePath - Optional file path to clear. If omitted, clears entire cache
    */
   clear(filePath?: string) {
     debug('clear AST cache "%s"', filePath)

src/bundler.ts

@@ -27,7 +27,7 @@ import { type SupportedPackageManager } from './types/code_transformer.ts'
  * List of package managers we support in order to
  * copy lockfiles
  */
-const SUPPORTED_PACKAGE_MANAGERS: {
+export const SUPPORTED_PACKAGE_MANAGERS: {
   [K in SupportedPackageManager]: {
     packageManagerFiles: string[]
     installCommand: string
@@ -57,9 +57,20 @@ const SUPPORTED_PACKAGE_MANAGERS: {
 
 /**
  * The bundler class exposes the API to build an AdonisJS project.
+ *
+ * @example
+ * const bundler = new Bundler(new URL('./'), ts, { hooks: [] })
+ * const success = await bundler.bundle()
  */
 export class Bundler {
+  /**
+   * The current working project directory path as string
+   */
   #cwdPath: string
+
+  /**
+   * Reference to the TypeScript module
+   */
   #ts: typeof tsStatic
 
   /**
@@ -72,13 +83,23 @@ export class Bundler {
     ]
   }>
 
+  /**
+   * CLI UI instance for displaying colorful messages and progress information
+   */
   ui = cliui()
 
   /**
-   * Package manager detect from the project environment
+   * Package manager detected from the project environment
    */
   declare packageManager: SupportedPackageManager
 
+  /**
+   * Create a new bundler instance
+   *
+   * @param cwd - The current working directory URL
+   * @param ts - TypeScript module reference
+   * @param options - Bundler configuration options
+   */
   constructor(
     public cwd: URL,
     ts: typeof tsStatic,
@@ -168,6 +189,13 @@ export class Bundler {
 
   /**
    * Bundles the application to be run in production
+   *
+   * @param stopOnError - Whether to stop the build process on TypeScript errors
+   * @param client - Override the detected package manager
+   * @returns Promise that resolves to true if build succeeded, false otherwise
+   *
+   * @example
+   * const success = await bundler.bundle(true, 'npm')
    */
   async bundle(stopOnError: boolean = true, client?: SupportedPackageManager): Promise<boolean> {
     this.#hooks = await loadHooks(this.options.hooks, ['buildStarting', 'buildFinished'])

src/code_scanners/routes_scanner/main.ts

@@ -25,6 +25,18 @@ import {
   type RoutesScannerRules,
 } from '../../types/code_scanners.ts'
 
+/**
+ * RoutesScanner is responsible for scanning application routes,
+ * extracting their controllers, validators, request and response types.
+ *
+ * @example
+ * const scanner = new RoutesScanner(appRoot, [rules])
+ * scanner.defineResponse((route, controller) => {
+ *   return { type: 'CustomResponseType', imports: [] }
+ * })
+ * await scanner.scan(routes)
+ * const scannedRoutes = scanner.getScannedRoutes()
+ */
 export class RoutesScanner {
   /**
    * The root of the application from where we will resolve
@@ -74,7 +86,7 @@ export class RoutesScanner {
   ) => AsyncOrSync<ScannedRoute['validators']>
 
   /**
-   * CLI UI to log colorful messages
+   * CLI UI instance to log colorful messages and progress information
    */
   ui = cliui()
 
@@ -99,6 +111,12 @@ export class RoutesScanner {
     response: {},
   }
 
+  /**
+   * Create a new RoutesScanner instance
+   *
+   * @param appRoot - The root directory of the application
+   * @param rulesCollection - Collection of rules to apply during scanning
+   */
   constructor(appRoot: string, rulesCollection: RoutesScannerRules[]) {
     this.#appRoot = appRoot
 
@@ -340,6 +358,9 @@ export class RoutesScanner {
    * a given route. The callback will be executed for all
    * the routes and you must return undefined to fallback
    * to the default behavior of detecting types
+   *
+   * @param callback - Function to compute response types for routes
+   * @returns This RoutesScanner instance for method chaining
    */
   defineResponse(
     callback: (
@@ -357,6 +378,9 @@ export class RoutesScanner {
    * a given route. The callback will be executed for all
    * the routes and you must return undefined to fallback
    * to the default behavior of detecting types
+   *
+   * @param callback - Function to compute request types for routes
+   * @returns This RoutesScanner instance for method chaining
    */
   defineRequest(
     callback: (
@@ -370,8 +394,10 @@ export class RoutesScanner {
   }
 
   /**
-   * Register a callback to extract validators from the route
-   * controller.
+   * Register a callback to extract validators from the route controller
+   *
+   * @param callback - Function to extract validators from controllers
+   * @returns This RoutesScanner instance for method chaining
    */
   extractValidators(
     callback: (
@@ -386,6 +412,8 @@ export class RoutesScanner {
 
   /**
    * Returns the scanned routes
+   *
+   * @returns Array of scanned routes with their metadata
    */
   getScannedRoutes() {
     return this.#scannedRoutes
@@ -394,6 +422,8 @@ export class RoutesScanner {
   /**
    * Invalidating a controller will trigger computing the validators,
    * request types and the response types.
+   *
+   * @param controllerPath - Path to the controller file to invalidate
    */
   async invalidate(controllerPath: string) {
     controllerPath = string.toUnixSlash(controllerPath)
@@ -414,6 +444,8 @@ export class RoutesScanner {
   /**
    * Scans an array of Route list items and fetches their validators,
    * controllers, and request/response types.
+   *
+   * @param routes - Array of route list items to scan
    */
   async scan(routes: RoutesListItem[]) {
     for (let route of routes) {

src/code_transformer/main.ts

@@ -35,14 +35,26 @@ import type {
 } from '../types/code_transformer.ts'
 
 /**
- * This class is responsible for updating
+ * This class is responsible for transforming AdonisJS project code,
+ * including updating middleware, environment validations, and other
+ * code generation tasks.
+ *
+ * @example
+ * const transformer = new CodeTransformer(cwd)
+ * await transformer.addMiddlewareToStack('server', [{
+ *   path: '#middleware/cors_middleware',
+ *   position: 'before'
+ * }])
  */
 export class CodeTransformer {
   /**
-   * Exporting utilities to install package and detect
-   * the package manager
+   * Utility function for installing packages
    */
   installPackage = installPackage
+
+  /**
+   * Utility function for detecting the package manager
+   */
   detectPackageManager = detectPackageManager
 
   /**
@@ -52,7 +64,7 @@ export class CodeTransformer {
   #cwdPath: string
 
   /**
-   * The TsMorph project
+   * The TsMorph project instance for AST manipulation
    */
   project: Project
 
@@ -69,6 +81,11 @@ export class CodeTransformer {
     semicolons: 'remove',
   }
 
+  /**
+   * Create a new CodeTransformer instance
+   *
+   * @param cwd - The current working directory URL
+   */
   constructor(cwd: URL) {
     this.#cwd = cwd
     this.#cwdPath = fileURLToPath(this.#cwd)
@@ -237,8 +254,9 @@ export class CodeTransformer {
   }
 
   /**
-   * Add new env variable validation in the
-   * `env.ts` file
+   * Add new env variable validation in the `env.ts` file
+   *
+   * @param definition - Environment validation definition containing variables and comment
    */
   async defineEnvValidations(definition: EnvValidationNode) {
     /**
@@ -306,12 +324,14 @@ export class CodeTransformer {
   }
 
   /**
-   * Define new middlewares inside the `start/kernel.ts`
-   * file
+   * Define new middlewares inside the `start/kernel.ts` file
    *
    * This function is highly based on some assumptions
    * and will not work if you significantly tweaked
    * your `start/kernel.ts` file.
+   *
+   * @param stack - The middleware stack to add to ('server', 'router', or 'named')
+   * @param middleware - Array of middleware entries to add
    */
   async addMiddlewareToStack(stack: 'server' | 'router' | 'named', middleware: MiddlewareNode[]) {
     /**
@@ -336,7 +356,9 @@ export class CodeTransformer {
   }
 
   /**
-   * Update the `adonisrc.ts` file
+   * Update the `adonisrc.ts` file using the provided callback
+   *
+   * @param callback - Function that receives the RcFileTransformer for modifications
    */
   async updateRcFile(callback: (transformer: RcFileTransformer) => void) {
     const rcFileTransformer = new RcFileTransformer(this.#cwd, this.project)
@@ -346,6 +368,9 @@ export class CodeTransformer {
 
   /**
    * Add a new Japa plugin in the `tests/bootstrap.ts` file
+   *
+   * @param pluginCall - The plugin function call to add
+   * @param importDeclarations - Import declarations needed for the plugin
    */
   async addJapaPlugin(
     pluginCall: string,
@@ -383,7 +408,10 @@ export class CodeTransformer {
   }
 
   /**
-   * Add a new Vite plugin
+   * Add a new Vite plugin to the `vite.config.ts` file
+   *
+   * @param pluginCall - The plugin function call to add
+   * @param importDeclarations - Import declarations needed for the plugin
    */
   async addVitePlugin(
     pluginCall: string,
@@ -442,6 +470,8 @@ export class CodeTransformer {
   /**
    * Adds a policy to the list of `policies` object configured
    * inside the `app/policies/main.ts` file.
+   *
+   * @param policies - Array of bouncer policy entries to add
    */
   async addPolicies(policies: BouncerPolicyNode[]) {
     /**
@@ -475,9 +505,14 @@ export class CodeTransformer {
    * }
    * ```
    *
-   * @param source
-   * @param outputPath
-   * @param importAlias
+   * @param input - Source configuration for entity scanning
+   * @param output - Output configuration for the generated index file
+   *
+   * @example
+   * await transformer.makeEntityIndex(
+   *   { source: 'app/controllers', importAlias: '#controllers' },
+   *   { destination: 'start/controllers.ts', exportName: 'controllers' }
+   * )
    */
   async makeEntityIndex(
     input: OneOrMore<{ source: string; importAlias?: string; allowedExtensions?: string[] }>,