@adonisjs/assembler 8.0.0-next.2 → 8.0.0-next.20

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;
 }

package/build/src/helpers.d.ts

@@ -0,0 +1,115 @@
+import { type SgNode } from '@ast-grep/napi';
+import type { Import } from './types/common.ts';
+/**
+ * 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 SgNode to plain text by removing whitespaces,
+ * indentation and comments in between. Tested with the following
+ * children nodes only.
+ *
+ * - MemberExpression
+ * - 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;
+/**
+ * Inspects arguments for one or more method calls. If you want to
+ * scope the search within a specific context, then make sure to
+ * first narrow down the AST and pass a specific SgNode.
+ *
+ * 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,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,7 @@
+import {
+  IndexGenerator
+} from "../../chunk-4452KFDQ.js";
+import "../../chunk-JFBQ4OEM.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

@@ -0,0 +1,41 @@
+/**
+ * Encapsulates the API to resolve import specifiers with the ability
+ * 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 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, rewriteAliasImportExtension?: boolean): string;
+}

package/build/src/shortcuts_manager.d.ts

@@ -1,47 +1,62 @@
-import type { Logger } from '@poppinss/cliui';
+import { type ShortcutsManagerOptions } from './types/common.ts';
 /**
- * Keyboard shortcut definition
- */
-export interface KeyboardShortcut {
-    key: string;
-    description: string;
-    handler: () => void;
-}
-/**
- * Callbacks for keyboard shortcuts actions
- */
-export interface KeyboardShortcutsCallbacks {
-    onRestart: () => void;
-    onClear: () => void;
-    onQuit: () => void;
-}
-/**
- * Shortcuts manager options
- */
-export interface ShortcutsManagerOptions {
-    logger: Logger;
-    callbacks: KeyboardShortcutsCallbacks;
-}
-/**
- * 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>;
 }