@adonisjs/assembler 8.0.0-next.3 → 8.0.0-next.30

package/build/src/code_transformer/rc_file_transformer.d.ts

@@ -3,45 +3,123 @@ import { type AssemblerRcFile } from '../types/common.ts';
 declare const ALLOWED_ENVIRONMENTS: readonly ["web", "console", "test", "repl"];
 /**
  * RcFileTransformer is used to transform the `adonisrc.ts` file
- * for adding new commands, providers, meta files etc
+ * for adding new commands, providers, meta files etc.
+ *
+ * This class provides a fluent API for modifying the AdonisJS configuration
+ * file (adonisrc.ts) by adding various types of entries like providers,
+ * commands, preloaded files, meta files, and test suites.
+ *
+ * @example
+ * const transformer = new RcFileTransformer(cwd, project)
+ * transformer.addProvider('#providers/app_provider')
+ * transformer.addCommand('#commands/make_controller')
+ * await transformer.save()
  */
 export declare class RcFileTransformer {
     #private;
+    /**
+     * Create a new RcFileTransformer instance
+     *
+     * @param cwd - The current working directory URL
+     * @param project - The TsMorph project instance
+     */
     constructor(cwd: URL, project: Project);
     /**
      * Add a new command to the rcFile
+     *
+     * @param commandPath - The path to the command file
+     * @returns This RcFileTransformer instance for method chaining
      */
     addCommand(commandPath: string): this;
     /**
      * Add a new preloaded file to the rcFile
+     *
+     * @param modulePath - The path to the preload file
+     * @param environments - Optional array of environments where this preload should run
+     * @returns This RcFileTransformer instance for method chaining
      */
     addPreloadFile(modulePath: string, environments?: (typeof ALLOWED_ENVIRONMENTS)[number][]): this;
     /**
      * Add a new provider to the rcFile
+     *
+     * @param providerPath - The path to the provider file
+     * @param environments - Optional array of environments where this provider should run
+     * @returns This RcFileTransformer instance for method chaining
      */
     addProvider(providerPath: string, environments?: (typeof ALLOWED_ENVIRONMENTS)[number][]): this;
     /**
      * Add a new meta file to the rcFile
+     *
+     * @param globPattern - The glob pattern for the meta file
+     * @param reloadServer - Whether the server should reload when this file changes
+     * @returns This RcFileTransformer instance for method chaining
      */
     addMetaFile(globPattern: string, reloadServer?: boolean): this;
     /**
-     * Set directory name and path
+     * Set directory name and path in the directories configuration
+     *
+     * @param key - The directory key (e.g., 'controllers', 'models')
+     * @param value - The directory path
+     * @returns This RcFileTransformer instance for method chaining
      */
     setDirectory(key: string, value: string): this;
     /**
-     * Set command alias
+     * Set command alias in the command aliases configuration
+     *
+     * @param alias - The alias name
+     * @param command - The full command name
+     * @returns This RcFileTransformer instance for method chaining
      */
     setCommandAlias(alias: string, command: string): this;
     /**
      * Add a new test suite to the rcFile
+     *
+     * @param suiteName - The name of the test suite
+     * @param files - File patterns for the test suite (string or array)
+     * @param timeout - Optional timeout in milliseconds (defaults to 2000)
+     * @returns This RcFileTransformer instance for method chaining
      */
     addSuite(suiteName: string, files: string | string[], timeout?: number): this;
     /**
      * Add a new assembler hook
+     * The format `thunk` write `() => import(path)`.
+     *
+     * @param type - The type of hook to add
+     * @param value - The path to the hook file or value to write
+     * @param raw - Wether to write a thunk import or as raw value
+     * @returns This RcFileTransformer instance for method chaining
+     */
+    addAssemblerHook(type: keyof Exclude<AssemblerRcFile['hooks'], undefined>, value: string, raw?: boolean): this;
+    /**
+     * Add a named import
+     *
+     * @param specifier - The module specifier to import
+     * @param names - Names to import from the module
+     * @returns This RcFileTransformer instance for method chaining
+     */
+    addNamedImport(specifier: string, names: string[]): this;
+    /**
+     * Add a default import
+     *
+     * @param specifier - The module specifier to import
+     * @param name - Name of the default import
+     * @returns This RcFileTransformer instance for method chaining
+     */
+    addDefaultImport(specifier: string, name: string): this;
+    /**
+     * Get a directory value from the directories configuration.
+     *
+     * @param key - The directory key to retrieve
+     * @param defaultValue - The default value if not configured
+     * @returns The configured directory path or the default value
      */
-    addAssemblerHook(type: keyof Exclude<AssemblerRcFile['hooks'], undefined>, path: string): this;
+    getDirectory(key: string, defaultValue: string): string;
     /**
-     * Save the adonisrc.ts file
+     * Save the adonisrc.ts file with all applied transformations
+     *
+     * Formats the file according to editor settings and saves it to disk.
+     *
+     * @returns Promise that resolves when the file is saved
      */
     save(): Promise<void>;
 }

package/build/src/debug.d.ts

@@ -1,2 +1,14 @@
-declare const _default: import("util").DebugLogger;
+/**
+ * Debug logger for the AdonisJS assembler package.
+ *
+ * This debug instance is configured to log messages under the 'adonisjs:assembler'
+ * namespace. Debug messages are only shown when the NODE_DEBUG environment variable
+ * includes 'adonisjs:assembler'.
+ *
+ * @example
+ * // Enable debug logging
+ * // NODE_DEBUG=adonisjs:assembler node ace serve
+ * debug('Starting development server...')
+ */
+declare const _default: import("node:util").DebugLogger;
 export default _default;

package/build/src/dev_server.d.ts

@@ -1,21 +1,24 @@
-import type tsStatic from 'typescript';
 import type { DevServerOptions } from './types/common.ts';
 /**
- * Exposes the API to start the development server in HMR, watch or static mode.
+ * Exposes the API to start the development server in HMR, watch or static mode
  *
  * In HMR mode, the DevServer will exec the "bin/server.ts" file and let hot-hook
  * manage the changes using hot module reloading.
  *
- * In watch mode, the DevServer will start an internal watcher and restarts the after
- * every file change. The files must be part of the TypeScript project (via tsconfig.json),
+ * In watch mode, the DevServer will start an internal watcher and restarts the server
+ * after every file change. The files must be part of the TypeScript project (via tsconfig.json),
  * or registered as metaFiles.
+ *
+ * In static mode, the server runs without file watching or hot reloading.
+ *
+ * @example
+ * const devServer = new DevServer(cwd, { hmr: true, hooks: [] })
+ * await devServer.start(ts)
  */
 export declare class DevServer {
     #private;
-    cwd: URL;
-    options: DevServerOptions;
     /**
-     * CLI UI to log colorful messages
+     * CLI UI instance for displaying colorful messages and progress information
      */
     ui: {
         colors: import("@poppinss/colors/types").Colors;
@@ -39,36 +42,108 @@ export declare class DevServer {
         useColors(colorsToUse: import("@poppinss/colors/types").Colors): void;
     };
     /**
-     * The mode in which the DevServer is running.
+     * The mode in which the DevServer is running
+     *
+     * Returns the current operating mode of the development server:
+     * - 'hmr': Hot Module Reloading enabled
+     * - 'watch': File system watching with full restarts
+     * - 'static': No file watching or hot reloading
      */
     get mode(): "hmr" | "watch" | "static";
     /**
      * Script file to start the development server
      */
     scriptFile: string;
+    /**
+     * The current working directory URL
+     */
+    cwd: URL;
+    /**
+     * File path computed from the cwd
+     */
+    cwdPath: string;
+    /**
+     * Development server configuration options including hooks and environment variables
+     */
+    options: DevServerOptions;
+    /**
+     * Create a new DevServer instance
+     *
+     * @param cwd - The current working directory URL
+     * @param options - Development server configuration options
+     */
     constructor(cwd: URL, options: DevServerOptions);
     /**
-     * Add listener to get notified when dev server is
-     * closed
+     * Adds listener to get notified when dev server is closed
+     *
+     * Registers a callback function that will be invoked when the development
+     * server's child process exits. The callback receives the exit code.
+     *
+     * @param callback - Function to call when dev server closes
+     * @returns This DevServer instance for method chaining
+     *
+     * @example
+     * devServer.onClose((exitCode) => {
+     *   console.log(`Server closed with exit code: ${exitCode}`)
+     * })
      */
     onClose(callback: (exitCode: number) => any): this;
     /**
-     * Add listener to get notified when dev server exists
-     * with an error
+     * Adds listener to get notified when dev server encounters an error
+     *
+     * Registers a callback function that will be invoked when the development
+     * server's child process encounters an error or fails to start.
+     *
+     * @param callback - Function to call when dev server encounters an error
+     * @returns This DevServer instance for method chaining
+     *
+     * @example
+     * devServer.onError((error) => {
+     *   console.error('Dev server error:', error.message)
+     * })
      */
     onError(callback: (error: any) => any): this;
     /**
-     * Close watchers and the running child process
+     * Closes watchers and terminates the running child process
+     *
+     * Cleans up keyboard shortcuts, stops file system watchers, and kills
+     * the HTTP server child process. This should be called when shutting down
+     * the development server.
+     *
+     * @example
+     * await devServer.close()
      */
     close(): Promise<void>;
     /**
-     * Start the development server
+     * Starts the development server in static or HMR mode
+     *
+     * Initializes the server and starts the HTTP server. The mode is determined
+     * by the `hmr` option in DevServerOptions. In HMR mode, hot-hook is configured
+     * to enable hot module reloading.
+     *
+     * @param ts - TypeScript module reference
+     *
+     * @example
+     * const devServer = new DevServer(cwd, { hmr: true, hooks: [] })
+     * await devServer.start(ts)
      */
-    start(ts: typeof tsStatic): Promise<void>;
+    start(): Promise<void>;
     /**
-     * Start the development server in watch mode
+     * Starts the development server in watch mode and restarts on file changes
+     *
+     * Initializes the server, starts the HTTP server, and sets up a file system
+     * watcher that monitors for changes. When files are added, modified, or deleted,
+     * the server automatically restarts. The watcher respects TypeScript project
+     * configuration and metaFiles settings.
+     *
+     * @param ts - TypeScript module reference
+     * @param options - Watch options including polling mode
+     *
+     * @example
+     * const devServer = new DevServer(cwd, { hooks: [] })
+     * await devServer.startAndWatch(ts, { poll: false })
      */
-    startAndWatch(ts: typeof tsStatic, options?: {
+    startAndWatch(options?: {
         poll: boolean;
     }): Promise<void>;
 }

package/build/src/exceptions/codemod_exception.d.ts

@@ -0,0 +1,178 @@
+import type { MiddlewareNode, EnvValidationNode, BouncerPolicyNode } from '../types/code_transformer.ts';
+/**
+ * Options for creating a CodemodException
+ */
+export interface CodemodExceptionOptions {
+    /**
+     * Instructions for the user to manually perform the codemod action
+     */
+    instructions?: string;
+    /**
+     * The file path that was being modified
+     */
+    filePath?: string;
+}
+/**
+ * Custom exception for codemod errors that provides helpful instructions
+ * to the user when automatic code transformation fails.
+ *
+ * @example
+ * ```ts
+ * throw CodemodException.missingEnvFile('start/env.ts', {
+ *   variables: { MY_VAR: 'Env.schema.string()' }
+ * })
+ * ```
+ */
+export declare class CodemodException extends Error {
+    #private;
+    /**
+     * Instructions for the user to manually perform the codemod action
+     */
+    instructions?: string;
+    /**
+     * The file path that was being modified
+     */
+    filePath?: string;
+    constructor(message: string, options?: CodemodExceptionOptions);
+    /**
+     * Creates an exception when start/env.ts file is missing
+     *
+     * @param filePath - The path to the missing file
+     * @param definition - The environment validation definition that was being added
+     */
+    static missingEnvFile(filePath: string, definition: EnvValidationNode): CodemodException;
+    /**
+     * Creates an exception when Env.create is not found in the file
+     *
+     * @param filePath - The path to the file being modified
+     * @param definition - The environment validation definition that was being added
+     */
+    static missingEnvCreate(filePath: string, definition: EnvValidationNode): CodemodException;
+    /**
+     * Creates an exception when Env.create has invalid structure
+     *
+     * @param filePath - The path to the file being modified
+     * @param definition - The environment validation definition that was being added
+     */
+    static invalidEnvCreate(filePath: string, definition: EnvValidationNode): CodemodException;
+    /**
+     * Creates an exception when start/kernel.ts file is missing
+     *
+     * @param filePath - The path to the missing file
+     * @param stack - The middleware stack that was being modified
+     * @param middleware - The middleware entries that were being added
+     */
+    static missingKernelFile(filePath: string, stack: 'server' | 'router' | 'named', middleware: MiddlewareNode[]): CodemodException;
+    /**
+     * Creates an exception when server.use/router.use is not found
+     *
+     * @param filePath - The path to the file being modified
+     * @param stack - The middleware stack that was being modified
+     * @param middleware - The middleware entries that were being added
+     */
+    static missingMiddlewareStack(filePath: string, stack: 'server' | 'router' | 'named', middleware: MiddlewareNode[]): CodemodException;
+    /**
+     * Creates an exception when middleware array structure is invalid
+     *
+     * @param filePath - The path to the file being modified
+     * @param stack - The middleware stack that was being modified
+     * @param middleware - The middleware entries that were being added
+     * @param reason - The reason why the structure is invalid
+     */
+    static invalidMiddlewareStack(filePath: string, stack: 'server' | 'router' | 'named', middleware: MiddlewareNode[], reason: string): CodemodException;
+    /**
+     * Creates an exception when app/policies/main.ts file is missing
+     *
+     * @param filePath - The path to the missing file
+     * @param policies - The policies that were being added
+     */
+    static missingPoliciesFile(filePath: string, policies: BouncerPolicyNode[]): CodemodException;
+    /**
+     * Creates an exception when policies structure is invalid
+     *
+     * @param filePath - The path to the file being modified
+     * @param policies - The policies that were being added
+     * @param reason - The reason why the structure is invalid
+     */
+    static invalidPoliciesFile(filePath: string, policies: BouncerPolicyNode[], reason: string): CodemodException;
+    /**
+     * Creates an exception when vite.config.ts file is missing
+     *
+     * @param filePath - The path to the missing file
+     * @param pluginCall - The plugin call that was being added
+     * @param importDeclarations - The import declarations needed for the plugin
+     */
+    static missingViteConfig(filePath: string, pluginCall: string, importDeclarations: {
+        isNamed: boolean;
+        module: string;
+        identifier: string;
+    }[]): CodemodException;
+    /**
+     * Creates an exception when vite.config.ts structure is invalid
+     *
+     * @param filePath - The path to the file being modified
+     * @param pluginCall - The plugin call that was being added
+     * @param importDeclarations - The import declarations needed for the plugin
+     * @param reason - The reason why the structure is invalid
+     */
+    static invalidViteConfig(filePath: string, pluginCall: string, importDeclarations: {
+        isNamed: boolean;
+        module: string;
+        identifier: string;
+    }[], reason: string): CodemodException;
+    /**
+     * Creates an exception when tests/bootstrap.ts file is missing
+     *
+     * @param filePath - The path to the missing file
+     * @param pluginCall - The plugin call that was being added
+     * @param importDeclarations - The import declarations needed for the plugin
+     */
+    static missingJapaBootstrap(filePath: string, pluginCall: string, importDeclarations: {
+        isNamed: boolean;
+        module: string;
+        identifier: string;
+    }[]): CodemodException;
+    /**
+     * Creates an exception when tests/bootstrap.ts structure is invalid
+     *
+     * @param filePath - The path to the file being modified
+     * @param pluginCall - The plugin call that was being added
+     * @param importDeclarations - The import declarations needed for the plugin
+     * @param reason - The reason why the structure is invalid
+     */
+    static invalidJapaBootstrap(filePath: string, pluginCall: string, importDeclarations: {
+        isNamed: boolean;
+        module: string;
+        identifier: string;
+    }[], reason: string): CodemodException;
+    /**
+     * Creates an exception when adonisrc.ts file is missing
+     *
+     * @param filePath - The path to the missing file
+     * @param codeToAdd - The code that should be added manually
+     */
+    static missingRcFile(filePath: string, codeToAdd: string): CodemodException;
+    /**
+     * Creates an exception when adonisrc.ts structure is invalid
+     *
+     * @param filePath - The path to the file being modified
+     * @param codeToAdd - The code that should be added manually
+     * @param reason - The reason why the structure is invalid
+     */
+    static invalidRcFile(filePath: string, codeToAdd: string, reason: string): CodemodException;
+    /**
+     * Creates an exception when a file required for transformation is not found.
+     *
+     * @param filePath - The path to the missing file
+     * @param codeToAdd - The code that should be added manually
+     */
+    static E_CODEMOD_FILE_NOT_FOUND(filePath: string, codeToAdd: string): CodemodException;
+    /**
+     * Creates an exception when the file structure doesn't match expected patterns.
+     *
+     * @param message - Description of what structure was expected
+     * @param filePath - The path to the file being modified
+     * @param codeToAdd - The code that should be added manually
+     */
+    static E_CODEMOD_INVALID_STRUCTURE(message: string, filePath: string, codeToAdd: string): CodemodException;
+}

package/build/src/file_buffer.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Buffer class to construct template output with proper indentation and formatting.
+ *
+ * The FileBuffer class provides a fluent API for building text output with automatic
+ * indentation management. It's commonly used for generating code or template files
+ * where proper formatting is important.
+ *
+ * @example
+ * const buffer = new FileBuffer()
+ * buffer
+ *   .writeLine('function example() {')
+ *   .indent()
+ *   .writeLine('return "Hello World"')
+ *   .dedent()
+ *   .writeLine('}')
+ * console.log(buffer.flush())
+ */
+export declare class FileBuffer {
+    #private;
+    /**
+     * Creates a new child buffer instance
+     *
+     * @returns A new FileBuffer instance
+     */
+    create(): FileBuffer;
+    /**
+     * Returns the size of buffer text
+     *
+     * @returns The number of lines in the buffer
+     */
+    get size(): number;
+    /**
+     * Enable or disable end-of-line character at the end of output
+     *
+     * @param enabled - Whether to add EOL character
+     * @returns This FileBuffer instance for method chaining
+     *
+     * @example
+     * const buffer = new FileBuffer()
+     * buffer.eol(true).writeLine('Hello').flush() // 'Hello\n\n'
+     */
+    eol(enabled: boolean): this;
+    /**
+     * Write a new line to the output with current indentation
+     *
+     * @param text - The text to write as a new line
+     * @returns This FileBuffer instance for method chaining
+     */
+    writeLine(text: string | FileBuffer): this;
+    /**
+     * Write text to the output without adding a new line
+     *
+     * @param text - The text to write without a newline
+     * @returns This FileBuffer instance for method chaining
+     */
+    write(text: string | FileBuffer): this;
+    /**
+     * Increase indentation by 2 spaces
+     *
+     * @returns This FileBuffer instance for method chaining
+     */
+    indent(): this;
+    /**
+     * Decrease indentation by 2 spaces (minimum of 0)
+     *
+     * @returns This FileBuffer instance for method chaining
+     */
+    dedent(): this;
+    /**
+     * Convert the buffer to a string representation
+     *
+     * @example
+     * const buffer = new FileBuffer()
+     * buffer.writeLine('Hello')
+     * console.log(buffer.toString())
+     */
+    toString(): string;
+    /**
+     * Return template as a string, joining all buffer lines
+     *
+     * Once called, the output is cached and subsequent calls return the same result.
+     * The flush method becomes a no-op after the first call.
+     *
+     * @returns The complete buffer content as a string
+     */
+    flush(): string;
+}

package/build/src/file_system.d.ts

@@ -1,4 +1,4 @@
-import type tsStatic from 'typescript';
+import { type TsConfigResult } from 'get-tsconfig';
 import { type InspectedFile, type AssemblerRcFile } from './types/common.ts';
 /**
  * Exposes an intutive API to run actions when different kind of files
@@ -14,6 +14,10 @@ import { type InspectedFile, type AssemblerRcFile } from './types/common.ts';
  *
  * Using FileSystem you can register actions to be executed when a file changes in
  * one of the above categories.
+ *
+ * @example
+ * const fs = new FileSystem(cwd, tsConfig, rcFile)
+ * const file = fs.inspect('./app/controllers/users_controller.ts')
  */
 export declare class FileSystem {
     #private;
@@ -37,24 +41,58 @@ export declare class FileSystem {
      */
     get excludes(): string[];
     /**
-     * Inspect a relative path to find its source in the project
+     * Inspect a file path to determine its type and properties within the project.
+     *
+     * This method analyzes a file to categorize it as a script file, test file, or meta file,
+     * and determines whether changes to the file should trigger server restarts. Results
+     * are memoized for performance optimization.
+     *
+     * @param absolutePath - The absolute Unix path to the file
+     * @param relativePath - The relative Unix path from the project root
+     * @returns File inspection result or null if the file should be ignored
+     *
+     * @example
+     * const file = fileSystem.inspect('/project/app/models/user.ts', 'app/models/user.ts')
+     * if (file) {
+     *   console.log(file.fileType) // 'script'
+     *   console.log(file.reloadServer) // true
+     * }
      */
-    inspect: (input: string) => InspectedFile | null;
+    inspect: (input: string, args_0?: string | undefined) => InspectedFile | null;
     /**
-     * Returns true if the directory should be watched. Chokidar sends
-     * absolute unix paths to the ignored callback.
+     * Determines if a directory should be watched by the file watcher.
+     *
+     * This method checks if a directory should be monitored for file changes
+     * based on the TypeScript configuration includes/excludes patterns.
+     * Results are memoized for performance. Chokidar sends absolute Unix paths.
      *
-     * You must use "shouldWatchFile" method for files and call this method
-     * for directories only.
+     * Note: Use shouldWatchFile for files and this method for directories only.
+     *
+     * @param absolutePath - The absolute Unix path to the directory
+     * @returns True if the directory should be watched
+     *
+     * @example
+     * const shouldWatch = fileSystem.shouldWatchDirectory('/project/app/controllers')
+     * console.log(shouldWatch) // true
      */
     shouldWatchDirectory: (input: string) => unknown;
-    constructor(cwd: URL | string, tsConfig: tsStatic.ParsedCommandLine, rcFile: AssemblerRcFile);
+    /**
+     * Create a new FileSystem instance
+     *
+     * @param cwd - The current working directory URL or string path
+     * @param tsConfig - Parsed TypeScript configuration
+     * @param rcFile - AdonisJS RC file configuration
+     */
+    constructor(cwd: string, tsConfig: TsConfigResult, rcFile: AssemblerRcFile);
     /**
      * Returns true if the file should be watched. Chokidar sends
      * absolute unix paths to the ignored callback.
      *
      * You must use "shouldWatchDirectory" method for directories and call
      * this method for files only.
+     *
+     * @param absolutePath - The absolute path to the file
+     * @returns True if the file should be watched
      */
     shouldWatchFile(absolutePath: string): boolean;
 }