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

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,2 @@
+import { a as nodeToPlainText, i as inspectMethodArguments, n as inspectClass, o as searchValidatorDirectUsage, r as inspectClassMethods, t as findImport } from "../helpers-DDurYRsZ.js";
+export { findImport, inspectClass, inspectClassMethods, inspectMethodArguments, nodeToPlainText, searchValidatorDirectUsage };

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

@@ -0,0 +1,68 @@
+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;
+    /**
+     * The application root directory path
+     */
+    appRoot: string;
+    /**
+     * 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,3 @@
+import "../../virtual_file_system-bGeoWsK-.js";
+import { t as IndexGenerator } from "../../main-CknPN3rJ.js";
+export { IndexGenerator };

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

@@ -0,0 +1,60 @@
+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);
+    /**
+     * 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,41 @@
 /**
  * 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;
+    constructor(appRoot: string);
     /**
      * 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;
+    resolve(specifier: string, rewriteAliasImportExtension?: boolean): 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;
 }

package/build/src/test_runner.d.ts

@@ -1,22 +1,31 @@
-import type tsStatic from 'typescript';
 import type { TestRunnerOptions } from './types/common.ts';
 /**
  * Exposes the API to run Japa tests and optionally watch for file
  * changes to re-run the tests.
  *
- * The watch mode functions as follows.
+ * The TestRunner provides intelligent test execution with watch mode capabilities.
+ * When files change, it can selectively run specific tests or the entire suite
+ * based on what changed.
  *
+ * The watch mode functions as follows:
  *  - If the changed file is a test file, then only tests for that file
  *    will be re-run.
  *  - Otherwise, all tests will re-run with respect to the initial
  *    filters applied when running the `node ace test` command.
+ *
+ * @example
+ * const testRunner = new TestRunner(cwd, { suites: [], hooks: [] })
+ * await testRunner.run()
+ *
+ * @example
+ * // Run tests in watch mode
+ * const testRunner = new TestRunner(cwd, { suites: [], hooks: [] })
+ * await testRunner.runAndWatch(ts, { poll: false })
  */
 export declare class TestRunner {
     #private;
-    cwd: URL;
-    options: TestRunnerOptions;
     /**
-     * CLI UI to log colorful messages
+     * CLI UI instance for displaying colorful messages and progress information
      */
     ui: {
         colors: import("@poppinss/colors/types").Colors;
@@ -43,29 +52,65 @@ export declare class TestRunner {
      * The script file to run as a child process
      */
     scriptFile: string;
+    /**
+     * The current working directory URL
+     */
+    cwd: URL;
+    /**
+     * The current working directory path as a string
+     */
+    cwdPath: string;
+    /**
+     * Test runner configuration options including filters, reporters, and hooks
+     */
+    options: TestRunnerOptions;
+    /**
+     * Create a new TestRunner instance
+     *
+     * @param cwd - The current working directory URL
+     * @param options - Test runner configuration options
+     */
     constructor(cwd: URL, options: TestRunnerOptions);
     /**
-     * Add listener to get notified when dev server is
-     * closed
+     * Add listener to get notified when test runner is closed
+     *
+     * @param callback - Function to call when test runner closes
+     * @returns This TestRunner 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 test runner encounters an error
+     *
+     * @param callback - Function to call when test runner encounters an error
+     * @returns This TestRunner instance for method chaining
      */
     onError(callback: (error: any) => any): this;
     /**
      * Close watchers and running child processes
+     *
+     * Cleans up file system watchers and terminates any running test
+     * processes to ensure graceful shutdown.
      */
     close(): Promise<void>;
     /**
-     * Runs tests
+     * Runs tests once without watching for file changes
+     *
+     * Executes the test suite a single time and exits. This is the
+     * equivalent of running tests in CI/CD environments.
      */
     run(): Promise<void>;
     /**
-     * Run tests in watch mode
+     * Run tests in watch mode and re-run them when files change
+     *
+     * Starts the test runner in watch mode, monitoring the file system
+     * for changes and automatically re-running tests when relevant files
+     * are modified. Uses intelligent filtering to run only affected tests
+     * when possible.
+     *
+     * @param ts - TypeScript module reference for parsing configuration
+     * @param options - Watch options including polling mode for file system monitoring
      */
-    runAndWatch(ts: typeof tsStatic, options?: {
+    runAndWatch(options?: {
         poll: boolean;
     }): Promise<void>;
 }