@adonisjs/assembler 8.0.0-next.4 → 8.0.0-next.6

package/build/src/dev_server.d.ts

@@ -1,4 +1,5 @@
 import type tsStatic from 'typescript';
+import { cliui } from '@poppinss/cliui';
 import type { DevServerOptions } from './types/common.ts';
 /**
  * Exposes the API to start the development server in HMR, watch or static mode.
@@ -9,35 +10,21 @@ import type { DevServerOptions } from './types/common.ts';
  * 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),
  * or registered as metaFiles.
+ *
+ * @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 to log colorful messages and progress information
      */
-    ui: {
-        colors: import("@poppinss/colors/types").Colors;
-        logger: import("@poppinss/cliui").Logger;
-        table: (tableOptions?: Partial<import("@poppinss/cliui/types").TableOptions>) => import("@poppinss/cliui").Table;
-        tasks: (tasksOptions?: Partial<import("@poppinss/cliui/types").TaskManagerOptions>) => import("@poppinss/cliui").TaskManager;
-        icons: {
-            tick: string;
-            cross: string;
-            bullet: string;
-            nodejs: string;
-            pointer: string;
-            info: string;
-            warning: string;
-            squareSmallFilled: string;
-        };
-        sticker: () => import("@poppinss/cliui").Instructions;
-        instructions: () => import("@poppinss/cliui").Instructions;
-        switchMode(modeToUse: "raw" | "silent" | "normal"): void;
-        useRenderer(rendererToUse: import("@poppinss/cliui/types").RendererContract): void;
-        useColors(colorsToUse: import("@poppinss/colors/types").Colors): void;
-    };
+    get ui(): ReturnType<typeof cliui>;
+    /**
+     * CLI UI instance to log colorful messages and progress information
+     */
+    set ui(ui: ReturnType<typeof cliui>);
     /**
      * The mode in which the DevServer is running.
      */
@@ -46,15 +33,33 @@ export declare class DevServer {
      * Script file to start the development server
      */
     scriptFile: string;
+    /**
+     * The current working directory URL
+     */
+    cwd: URL;
+    /**
+     * 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
+     * Add listener to get notified when dev server is closed
+     *
+     * @param callback - Function to call when dev server closes
+     * @returns This DevServer instance for method chaining
      */
     onClose(callback: (exitCode: number) => any): this;
     /**
-     * Add listener to get notified when dev server exists
-     * with an error
+     * Add listener to get notified when dev server encounters an error
+     *
+     * @param callback - Function to call when dev server encounters an error
+     * @returns This DevServer instance for method chaining
      */
     onError(callback: (error: any) => any): this;
     /**
@@ -62,11 +67,16 @@ export declare class DevServer {
      */
     close(): Promise<void>;
     /**
-     * Start the development server
+     * Start the development server in static or HMR mode
+     *
+     * @param ts - TypeScript module reference
      */
     start(ts: typeof tsStatic): Promise<void>;
     /**
-     * Start the development server in watch mode
+     * Start the development server in watch mode and restart on file changes
+     *
+     * @param ts - TypeScript module reference
+     * @param options - Watch options including polling mode
      */
     startAndWatch(ts: typeof tsStatic, options?: {
         poll: boolean;

package/build/src/file_buffer.d.ts

@@ -0,0 +1,67 @@
+/**
+ * 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;
+    /**
+     * 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): 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): 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;
+    /**
+     * 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

@@ -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: tsStatic.ParsedCommandLine, 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;
 }

package/build/src/helpers.d.ts

@@ -1,26 +1,76 @@
 import { type SgNode } from '@ast-grep/napi';
 import type { Import } from './types/common.ts';
 /**
- * Finds an import reference inside a code snippet
+ * Finds an import reference inside a code snippet by analyzing the import statements
+ * and matching against the provided import reference identifier.
+ *
+ * The function searches through all import statements in the code and matches
+ * against default, namespace, or named imports based on the import reference.
+ *
+ * @param code - The code snippet to search for imports
+ * @param importReference - The import reference identifier to find (can include dot notation)
+ * @returns Promise that resolves to an Import object or null if not found
+ *
+ * @example
+ * const importInfo = await findImport(code, 'validateUser')
+ * if (importInfo) {
+ *   console.log(importInfo.specifier) // '@/validators/user'
+ * }
  */
 export declare function findImport(code: string, importReference: string): Promise<Import | null>;
 /**
  * Returns a node that represents a TypeScript class or null
  * when unable to find the class.
+ *
+ * This function searches for class declarations within the provided AST node
+ * using ast-grep's pattern matching capabilities.
+ *
+ * @param node - The AST node to search within for class declarations
+ * @returns The SgNode representing the class or null if not found
+ *
+ * @example
+ * const classNode = inspectClass(rootNode)
+ * if (classNode) {
+ *   console.log('Found class:', classNode.text())
+ * }
  */
 export declare function inspectClass(node: SgNode): SgNode | null;
 /**
  * Returns an array of SgNodes for class methods. The input node
  * must represent a class.
+ *
+ * This function finds all method definitions within a class node,
+ * including both regular methods and static methods.
+ *
+ * @param node - The AST node representing a class to search for methods
+ * @returns Array of SgNodes representing method definitions within the class
+ *
+ * @example
+ * const classNode = inspectClass(rootNode)
+ * if (classNode) {
+ *   const methods = inspectClassMethods(classNode)
+ *   methods.forEach(method => console.log('Method:', method.text()))
+ * }
  */
 export declare function inspectClassMethods(node: SgNode): SgNode[];
 /**
- * Converts an array of SgNode to plain text by removing whitespaces,
- * identation and comments in between. Tested with the following
+ * Converts an SgNode to plain text by removing whitespaces,
+ * indentation and comments in between. Tested with the following
  * children nodes only.
  *
  * - MemberExpression
- * - Identifer
+ * - Identifier
+ *
+ * This function recursively traverses the AST node and extracts only
+ * the meaningful text content without any formatting or whitespace.
+ *
+ * @param node - The AST node to convert to plain text
+ * @returns String representation of the node without formatting
+ *
+ * @example
+ * const memberExpression = node.find({ rule: { kind: 'member_expression' } })
+ * const plainText = nodeToPlainText(memberExpression)
+ * console.log(plainText) // 'user.validate'
  */
 export declare function nodeToPlainText(node: SgNode): string;
 /**
@@ -30,11 +80,36 @@ export declare function nodeToPlainText(node: SgNode): string;
  *
  * For example: In case of validators, we will first find the Controller
  * method for which we want the validation method calls.
+ *
+ * This function searches for call expressions that match the provided method
+ * names and returns their argument nodes for further analysis.
+ *
+ * @param node - The AST node to search within for method calls
+ * @param methodCalls - Array of method call names to search for (supports dot notation)
+ * @returns Array of SgNodes representing the arguments of matching method calls
+ *
+ * @example
+ * const controllerMethod = classNode.find({ rule: { kind: 'method_definition' } })
+ * const validatorArgs = inspectMethodArguments(controllerMethod, ['validate', 'request.validate'])
+ * validatorArgs.forEach(arg => console.log('Validator argument:', arg.text()))
  */
 export declare function inspectMethodArguments(node: SgNode, methodCalls: string[]): SgNode[];
 /**
  * Inspect the validator direct usage code snippets. A member expression
  * calling the ".validate" method is considered as direct usage of
  * the validator.
+ *
+ * This function specifically looks for patterns where validators are called
+ * directly with the `.validate()` method, which is common in AdonisJS applications.
+ *
+ * @param node - The AST node to search within for validator direct usage
+ * @returns Array of SgNodes representing validator expressions that call validate method
+ *
+ * @example
+ * const methodNode = classNode.find({ rule: { kind: 'method_definition' } })
+ * const validators = searchValidatorDirectUsage(methodNode)
+ * validators.forEach(validator => {
+ *   console.log('Direct validator usage:', nodeToPlainText(validator))
+ * })
  */
 export declare function searchValidatorDirectUsage(node: SgNode): SgNode[];

package/build/src/helpers.js

@@ -0,0 +1,16 @@
+import {
+  findImport,
+  inspectClass,
+  inspectClassMethods,
+  inspectMethodArguments,
+  nodeToPlainText,
+  searchValidatorDirectUsage
+} from "../chunk-TIKQQRMX.js";
+export {
+  findImport,
+  inspectClass,
+  inspectClassMethods,
+  inspectMethodArguments,
+  nodeToPlainText,
+  searchValidatorDirectUsage
+};

package/build/src/index_generator/main.d.ts

@@ -0,0 +1,73 @@
+import { type Logger } from '@poppinss/cliui';
+import { type IndexGeneratorSourceConfig } from '../types/common.ts';
+/**
+ * IndexGenerator manages the generation of index files for AdonisJS applications.
+ *
+ * This class provides a way to configure multiple sources and generate index files
+ * that export collections of modules, typically used for barrel exports or
+ * auto-discovery patterns in AdonisJS applications.
+ *
+ * @example
+ * const generator = new IndexGenerator(appRoot)
+ * generator.add('controllers', {
+ *   source: 'app/controllers',
+ *   output: 'app/controllers/index.ts',
+ *   as: 'barrelFile',
+ *   exportName: 'controllers'
+ * })
+ * await generator.generate()
+ */
+export declare class IndexGenerator {
+    #private;
+    /**
+     * Create a new IndexGenerator instance
+     *
+     * @param appRoot - The application root directory path
+     * @param cliLogger - Logger instance for CLI output
+     */
+    constructor(appRoot: string, cliLogger: Logger);
+    /**
+     * Set the logger instance used for CLI output
+     *
+     * Updates the CLI logger instance for this index generator and all
+     * registered sources to use the new logger for output.
+     *
+     * @param cliLogger - New logger instance to use
+     */
+    setLogger(cliLogger: Logger): void;
+    /**
+     * Add a new index generator source
+     *
+     * @param name - Unique name for the source
+     * @param config - Configuration for the index generator source
+     * @returns This IndexGenerator instance for method chaining
+     */
+    add(name: string, config: IndexGeneratorSourceConfig): this;
+    /**
+     * Add a file to all registered index generator sources
+     *
+     * This method propagates the file addition to all registered sources,
+     * allowing them to regenerate their index files if the new file matches
+     * their glob patterns.
+     *
+     * @param filePath - Absolute path of the file to add
+     */
+    addFile(filePath: string): Promise<void>;
+    /**
+     * Remove a file from all registered index generator sources
+     *
+     * This method propagates the file removal to all registered sources,
+     * allowing them to regenerate their index files if the removed file
+     * was previously tracked.
+     *
+     * @param filePath - Absolute path of the file to remove
+     */
+    removeFile(filePath: string): Promise<void>;
+    /**
+     * Generate all registered index files
+     *
+     * Iterates through all registered sources and generates their
+     * corresponding index files.
+     */
+    generate(): Promise<void>;
+}

package/build/src/index_generator/main.js

@@ -0,0 +1,7 @@
+import {
+  IndexGenerator
+} from "../../chunk-MC3FJR62.js";
+import "../../chunk-F4RAGKQN.js";
+export {
+  IndexGenerator
+};

package/build/src/index_generator/source.d.ts

@@ -0,0 +1,66 @@
+import { type Logger } from '@poppinss/cliui';
+import { type IndexGeneratorSourceConfig } from '../types/common.ts';
+/**
+ * IndexGeneratorSource handles the generation of a single index file.
+ *
+ * This class is responsible for scanning a source directory, processing files
+ * according to configuration, and generating an index file that exports the
+ * discovered modules. It supports both barrel file generation and custom
+ * generation strategies.
+ *
+ * @example
+ * const source = new IndexGeneratorSource(appRoot, {
+ *   source: 'app/controllers',
+ *   output: 'app/controllers/index.ts',
+ *   as: 'barrelFile',
+ *   exportName: 'controllers'
+ * })
+ * await source.generate()
+ */
+export declare class IndexGeneratorSource {
+    #private;
+    /**
+     * Unique name for this index generator source
+     */
+    name: string;
+    /**
+     * Create a new IndexGeneratorSource instance
+     *
+     * @param name - Unique name for this index generator source
+     * @param appRoot - The application root directory path
+     * @param cliLogger - Logger instance for CLI output
+     * @param config - Configuration for this index generator source
+     */
+    constructor(name: string, appRoot: string, cliLogger: Logger, config: IndexGeneratorSourceConfig);
+    /**
+     * Set the logger instance used for CLI output
+     *
+     * @param cliLogger - New logger instance to use
+     */
+    setLogger(cliLogger: Logger): void;
+    /**
+     * Add a file to the virtual file system and regenerate index if needed
+     *
+     * If the file matches the configured glob patterns, it will be added
+     * to the virtual file system and the index file will be regenerated.
+     *
+     * @param filePath - Absolute path of the file to add
+     */
+    addFile(filePath: string): Promise<void>;
+    /**
+     * Remove a file from the virtual file system and regenerate index if needed
+     *
+     * If the file was previously tracked, it will be removed from the
+     * virtual file system and the index file will be regenerated.
+     *
+     * @param filePath - Absolute path of the file to remove
+     */
+    removeFile(filePath: string): Promise<void>;
+    /**
+     * Generate the index file
+     *
+     * This method scans the source directory, processes files according to
+     * the configuration, and writes the generated index file to disk.
+     */
+    generate(): Promise<void>;
+}

package/build/src/paths_resolver.d.ts

@@ -1,15 +1,40 @@
 /**
  * Encapsulates the API to resolve import specifiers with the ability
- * to define customer resolver.
+ * to define custom resolver functions.
+ *
+ * The PathsResolver provides a caching mechanism to avoid resolving the same
+ * specifier multiple times and supports custom resolvers for handling
+ * special import patterns like path aliases.
+ *
+ * @example
+ * const resolver = new PathsResolver()
+ * resolver.use((specifier) => '/custom/path/' + specifier)
+ * const resolved = resolver.resolve('#app/models/user')
  */
 export declare class PathsResolver {
     #private;
     /**
      * Define a custom resolver that resolves a path
+     *
+     * The custom resolver function will be used instead of the default
+     * import.meta.resolve() for resolving import specifiers.
+     *
+     * @param resolver - Function that takes a specifier and returns resolved path
      */
     use(resolver: (specifier: string) => string): void;
     /**
-     * Resolve import specifier
+     * Resolve import specifier to an absolute file path
+     *
+     * This method caches resolved paths to improve performance on repeated
+     * resolutions. Relative paths are not supported and will throw an error.
+     *
+     * @param specifier - The import specifier to resolve (must not be relative)
+     * @returns The resolved absolute file path
+     * @throws Error when attempting to resolve relative paths
+     *
+     * @example
+     * const path = resolver.resolve('#app/models/user')
+     * const path2 = resolver.resolve('@/utils/helper')
      */
     resolve(specifier: string): string;
 }

package/build/src/shortcuts_manager.d.ts

@@ -1,24 +1,62 @@
 import { type ShortcutsManagerOptions } from './types/common.ts';
 /**
- * Manages keyboard shortcuts for development server
+ * Manages keyboard shortcuts for development server interaction.
+ *
+ * The ShortcutsManager provides a convenient way to handle keyboard inputs
+ * during development, allowing users to restart servers, clear console,
+ * open browsers, and perform other common development tasks through simple
+ * key presses.
+ *
+ * @example
+ * const shortcuts = new ShortcutsManager({
+ *   logger: ui.logger,
+ *   callbacks: {
+ *     onRestart: () => server.restart(),
+ *     onClear: () => console.clear(),
+ *     onQuit: () => process.exit()
+ *   }
+ * })
+ * shortcuts.setup()
  */
 export declare class ShortcutsManager {
     #private;
+    /**
+     * Create a new ShortcutsManager instance
+     *
+     * @param options - Configuration options for the shortcuts manager
+     */
     constructor(options: ShortcutsManagerOptions);
     /**
      * Set server url for opening in browser
+     *
+     * This URL will be used when the user presses 'o' to open the
+     * development server in their default browser.
+     *
+     * @param url - The server URL to open when 'o' key is pressed
      */
     setServerUrl(url: string): void;
     /**
-     * Initialize keyboard shortcuts
+     * Initialize keyboard shortcuts by setting up raw mode on stdin
+     *
+     * This method enables raw mode on stdin to capture individual keypresses
+     * and sets up the event listener for handling keyboard input. Only works
+     * in TTY environments.
      */
     setup(): void;
     /**
-     * Show available keyboard shortcuts
+     * Show available keyboard shortcuts in the console
+     *
+     * Displays a formatted list of all available keyboard shortcuts
+     * and their descriptions to help users understand what actions
+     * are available.
      */
     showHelp(): void;
     /**
-     * Cleanup keyboard shortcuts
+     * Cleanup keyboard shortcuts and restore terminal state
+     *
+     * Disables raw mode on stdin, removes event listeners, and restores
+     * the terminal to its normal state. Should be called when shutting down
+     * the development server.
      */
     cleanup(): void;
 }