@adonisjs/assembler 8.0.0-next.5 → 8.0.0-next.7

package/build/src/dev_server.d.ts

@@ -9,13 +9,15 @@ 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 for displaying colorful messages and progress information
      */
     ui: {
         colors: import("@poppinss/colors/types").Colors;
@@ -46,15 +48,37 @@ export declare class DevServer {
      * 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
+     * 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 +86,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/hooks.d.ts

@@ -0,0 +1,224 @@
+import { type AsyncOrSync } from '@poppinss/utils/types';
+import { type HookParams } from './types/hooks.ts';
+/**
+ * Collection of hooks that can be used to listen for various events during
+ * the application lifecycle. These hooks allow you to execute custom logic
+ * at specific points in the development server, build process, and testing.
+ *
+ * @example
+ * ```js
+ * const { hooks } = await import('@adonisjs/assembler/hooks')
+ *
+ * hooks.init((app) => {
+ *   console.log('Application initialized')
+ * })
+ *
+ * hooks.devServerStarted((server) => {
+ *   console.log('Dev server started on port', server.port)
+ * })
+ * ```
+ */
+export declare const hooks: {
+    /**
+     * Hook called during application initialization. This is the first hook
+     * that gets executed when the assembler starts up.
+     *
+     * @param callback - Function to execute when the init event occurs
+     *
+     * @example
+     * ```js
+     * hooks.init((app) => {
+     *   console.log('Application is initializing')
+     *   // Setup global configurations
+     * })
+     * ```
+     */
+    init(callback: (...args: HookParams<"init">) => AsyncOrSync<void>): (parent: import("./dev_server.ts").DevServer | import("./test_runner.ts").TestRunner | import("./bundler.ts").Bundler, indexGenerator: import("./index_generator/main.ts").IndexGenerator) => AsyncOrSync<void>;
+    /**
+     * Hook called after routes have been committed to the router.
+     * This occurs after all route definitions have been processed.
+     *
+     * @param callback - Function to execute when routes are committed
+     *
+     * @example
+     * ```js
+     * hooks.routesCommitted((router) => {
+     *   console.log('All routes have been committed to the router')
+     *   // Perform route-based setup
+     * })
+     * ```
+     */
+    routesCommitted(callback: (...args: HookParams<"routesCommitted">) => AsyncOrSync<void>): (parent: import("./dev_server.ts").DevServer, routes: Record<string, import("./types/code_scanners.ts").RoutesListItem[]>) => AsyncOrSync<void>;
+    /**
+     * Hook called when the assembler starts scanning for route files.
+     * This happens before any route files are actually processed.
+     *
+     * @param callback - Function to execute when route scanning begins
+     *
+     * @example
+     * ```js
+     * hooks.routesScanning(() => {
+     *   console.log('Starting to scan for route files')
+     *   // Setup route scanning configurations
+     * })
+     * ```
+     */
+    routesScanning(callback: (...args: HookParams<"routesScanning">) => AsyncOrSync<void>): (parent: import("./dev_server.ts").DevServer, routesScanner: import("./code_scanners/routes_scanner/main.ts").RoutesScanner) => AsyncOrSync<void>;
+    /**
+     * Hook called after all route files have been scanned and processed.
+     * This occurs once the route scanning phase is complete.
+     *
+     * @param callback - Function to execute when route scanning is finished
+     *
+     * @example
+     * ```js
+     * hooks.routesScanned((scannedRoutes) => {
+     *   console.log('Route scanning completed')
+     *   // Process scanned route information
+     * })
+     * ```
+     */
+    routesScanned(callback: (...args: HookParams<"routesScanned">) => AsyncOrSync<void>): (parent: import("./dev_server.ts").DevServer, routesScanner: import("./code_scanners/routes_scanner/main.ts").RoutesScanner) => AsyncOrSync<void>;
+    /**
+     * Hook called when a file is modified during development.
+     * This is triggered by the file watcher when changes are detected.
+     *
+     * @param callback - Function to execute when a file changes
+     *
+     * @example
+     * ```js
+     * hooks.fileChanged((filePath, stats) => {
+     *   console.log(`File changed: ${filePath}`)
+     *   // Handle file change logic
+     * })
+     * ```
+     */
+    fileChanged(callback: (...args: HookParams<"fileChanged">) => AsyncOrSync<void>): (relativePath: string, absolutePath: string, info: {
+        source: "hot-hook" | "watcher";
+        hotReloaded: boolean;
+        fullReload: boolean;
+    }, parent: import("./dev_server.ts").DevServer | import("./test_runner.ts").TestRunner) => AsyncOrSync<void>;
+    /**
+     * Hook called when a new file is added during development.
+     * This is triggered by the file watcher when new files are created.
+     *
+     * @param callback - Function to execute when a file is added
+     *
+     * @example
+     * ```js
+     * hooks.fileAdded((filePath, stats) => {
+     *   console.log(`New file added: ${filePath}`)
+     *   // Handle new file logic
+     * })
+     * ```
+     */
+    fileAdded(callback: (...args: HookParams<"fileAdded">) => AsyncOrSync<void>): (relativePath: string, absolutePath: string, server: import("./dev_server.ts").DevServer | import("./test_runner.ts").TestRunner) => AsyncOrSync<void>;
+    /**
+     * Hook called when a file is removed during development.
+     * This is triggered by the file watcher when files are deleted.
+     *
+     * @param callback - Function to execute when a file is removed
+     *
+     * @example
+     * ```js
+     * hooks.fileRemoved((filePath) => {
+     *   console.log(`File removed: ${filePath}`)
+     *   // Handle file removal logic
+     * })
+     * ```
+     */
+    fileRemoved(callback: (...args: HookParams<"fileRemoved">) => AsyncOrSync<void>): (relativePath: string, absolutePath: string, server: import("./dev_server.ts").DevServer | import("./test_runner.ts").TestRunner) => AsyncOrSync<void>;
+    /**
+     * Hook called when the development server is about to start.
+     * This occurs before the server begins listening for connections.
+     *
+     * @param callback - Function to execute when dev server is starting
+     *
+     * @example
+     * ```js
+     * hooks.devServerStarting((server) => {
+     *   console.log('Development server is starting')
+     *   // Setup server configurations
+     * })
+     * ```
+     */
+    devServerStarting(callback: (...args: HookParams<"devServerStarting">) => AsyncOrSync<void>): (server: import("./dev_server.ts").DevServer) => AsyncOrSync<void>;
+    /**
+     * Hook called after the development server has successfully started.
+     * This occurs once the server is listening and ready to accept requests.
+     *
+     * @param callback - Function to execute when dev server has started
+     *
+     * @example
+     * ```js
+     * hooks.devServerStarted((server) => {
+     *   console.log(`Development server started on port ${server.port}`)
+     *   // Notify external services or open browser
+     * })
+     * ```
+     */
+    devServerStarted(callback: (...args: HookParams<"devServerStarted">) => AsyncOrSync<void>): (server: import("./dev_server.ts").DevServer, info: {
+        port: number;
+        host: string;
+    }, uiInstructions: import("@poppinss/cliui").Instructions) => AsyncOrSync<void>;
+    /**
+     * Hook called when the build process is about to start.
+     * This occurs before any build tasks are executed.
+     *
+     * @param callback - Function to execute when build is starting
+     *
+     * @example
+     * ```js
+     * hooks.buildStarting((buildConfig) => {
+     *   console.log('Build process is starting')
+     *   // Setup build configurations or clean directories
+     * })
+     * ```
+     */
+    buildStarting(callback: (...args: HookParams<"buildStarting">) => AsyncOrSync<void>): (server: import("./bundler.ts").Bundler) => AsyncOrSync<void>;
+    /**
+     * Hook called after the build process has completed.
+     * This occurs once all build tasks have finished executing.
+     *
+     * @param callback - Function to execute when build is finished
+     *
+     * @example
+     * ```js
+     * hooks.buildFinished((buildResult) => {
+     *   console.log('Build process completed')
+     *   // Deploy artifacts or notify build completion
+     * })
+     * ```
+     */
+    buildFinished(callback: (...args: HookParams<"buildFinished">) => AsyncOrSync<void>): (server: import("./bundler.ts").Bundler, uiInstructions: import("@poppinss/cliui").Instructions) => AsyncOrSync<void>;
+    /**
+     * Hook called when the test suite is about to start.
+     * This occurs before any test files are executed.
+     *
+     * @param callback - Function to execute when tests are starting
+     *
+     * @example
+     * ```js
+     * hooks.testsStarting((testConfig) => {
+     *   console.log('Test suite is starting')
+     *   // Setup test database or mock services
+     * })
+     * ```
+     */
+    testsStarting(callback: (...args: HookParams<"testsStarting">) => AsyncOrSync<void>): (server: import("./test_runner.ts").TestRunner) => AsyncOrSync<void>;
+    /**
+     * Hook called after the test suite has completed.
+     * This occurs once all test files have finished executing.
+     *
+     * @param callback - Function to execute when tests are finished
+     *
+     * @example
+     * ```js
+     * hooks.testsFinished((testResults) => {
+     *   console.log('Test suite completed')
+     *   // Generate test reports or cleanup test resources
+     * })
+     * ```
+     */
+    testsFinished(callback: (...args: HookParams<"testsFinished">) => AsyncOrSync<void>): (server: import("./test_runner.ts").TestRunner) => AsyncOrSync<void>;
+};

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

@@ -0,0 +1,64 @@
+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);
+    /**
+     * 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-25Q3N5JR.js";
+import "../../chunk-PORDZS62.js";
+export {
+  IndexGenerator
+};