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

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

package/build/src/test_runner.d.ts

@@ -4,19 +4,29 @@ 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,27 +53,63 @@ 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?: {
         poll: boolean;

package/build/src/types/code_scanners.d.ts

@@ -1,45 +1,115 @@
+/**
+ * Represents a controller that has been scanned and analyzed by the routes scanner.
+ * Contains metadata about the controller class and the specific method being called.
+ *
+ * @example
+ * const controller: ScannedController = {
+ *   name: 'UsersController',
+ *   path: '/project/app/controllers/users_controller.ts',
+ *   method: 'index',
+ *   import: {
+ *     type: 'default',
+ *     specifier: '#controllers/users_controller',
+ *     value: 'UsersController'
+ *   }
+ * }
+ */
 export type ScannedController = {
+    /** The name of the controller class */
     name: string;
+    /** Absolute file path to the controller */
     path: string;
+    /** The method name being called on the controller */
     method: string;
+    /** Import information for the controller */
     import: {
+        /** Import type (always 'default' for controllers) */
         type: 'default';
+        /** Import specifier used to import the controller */
         specifier: string;
+        /** The imported value name */
         value: string;
     };
 };
+/**
+ * Represents a validator that has been extracted from controller methods.
+ * Contains information about how the validator is imported and used.
+ *
+ * @example
+ * const validator: ScannedValidator = {
+ *   name: 'createUserValidator',
+ *   import: {
+ *     type: 'named',
+ *     specifier: '#validators/user_validators',
+ *     value: 'createUserValidator'
+ *   }
+ * }
+ */
 export type ScannedValidator = {
+    /** The name/identifier of the validator */
     name: string;
+    /** Import information for the validator */
     import: {
+        /** The type of import (namespace, default, or named) */
         type: 'namespace' | 'default' | 'named';
+        /** The module specifier being imported from */
         specifier: string;
+        /** The imported value name */
         value: string;
     };
 };
 /**
- * Output of scanned route
+ * Output of a scanned route containing all extracted metadata including
+ * controller information, validators, request/response types, and route patterns.
+ *
+ * @example
+ * const scannedRoute: ScannedRoute = {
+ *   name: 'users.store',
+ *   methods: ['POST'],
+ *   domain: 'root',
+ *   pattern: '/users',
+ *   tokens: [{ val: '/users', old: '/users', type: 0, end: '' }],
+ *   request: {
+ *     type: 'Infer<typeof createUserValidator>',
+ *     imports: ['import { Infer } from "@vinejs/vine/types"']
+ *   },
+ *   response: {
+ *     type: 'ReturnType<UsersController["store"]>',
+ *     imports: []
+ *   },
+ *   validators: [{
+ *     name: 'createUserValidator',
+ *     import: { type: 'named', specifier: '#validators/user', value: 'createUserValidator' }
+ *   }],
+ *   controller: {
+ *     name: 'UsersController',
+ *     method: 'store',
+ *     path: '/app/controllers/users_controller.ts',
+ *     import: { type: 'default', specifier: '#controllers/users_controller', value: 'UsersController' }
+ *   }
+ * }
  */
 export type ScannedRoute = {
     /**
-     * A unique name for the route provided by AdonisJS http-server. It
-     * could be duplicate across domains.
+     * A unique name for the route provided by AdonisJS http-server.
+     * May be duplicate across different domains.
      */
     name: string;
     /**
-     * HTTP methods for which the route is defined
+     * HTTP methods for which the route is defined (GET, POST, PUT, etc.)
      */
     methods: string[];
     /**
-     * HTTP method for which the route is defined
+     * The domain on which the route is registered (typically 'root')
      */
     domain: string;
     /**
-     * The route pattern
+     * The route pattern with parameter placeholders (e.g., '/users/:id')
      */
     pattern: string;
     /**
-     * Route tokens could be used for constructing a URI for
-     * the route without parsing the pattern
+     * Route tokens that can be used for constructing URIs without parsing the pattern.
+     * Contains information about static and dynamic segments.
      */
     tokens: {
         val: string;
@@ -48,44 +118,70 @@ export type ScannedRoute = {
         end: string;
     }[];
     /**
-     * Inferred request data accepted by the route. By default, the request
-     * data type is inferred when route is using a controller with a
-     * validator
+     * Inferred request data type accepted by the route.
+     * Generated when the route uses a controller with validators.
      */
     request?: {
+        /** TypeScript type definition for the request data */
         type: string;
+        /** Import statements needed for the type definition */
         imports: string[];
     };
     /**
-     * Inferred response for the route. By default, the response is only
-     * inferred when the route is using a controller.
+     * Inferred response type returned by the route.
+     * Generated when the route uses a controller method.
      */
     response?: {
+        /** TypeScript type definition for the response data */
         type: string;
+        /** Import statements needed for the type definition */
         imports: string[];
     };
     /**
-     * Extracted validators info, only when using the controller.
+     * Extracted validator information from the controller method.
+     * Only present when using controller-based routes with validation.
      */
     validators?: ScannedValidator[];
     /**
-     * Extracted controller info, only when using the controller.
+     * Extracted controller information including class and method details.
+     * Only present when using controller-based routes.
      */
     controller?: ScannedController;
 };
 /**
- * The route accepted by the routes scanner when initiating
- * the scanning process.
+ * The route data structure accepted by the routes scanner when initiating
+ * the scanning process. This represents the raw route definition before analysis.
+ *
+ * @example
+ * const routeItem: RoutesListItem = {
+ *   name: 'users.store',
+ *   pattern: '/users',
+ *   domain: 'root',
+ *   methods: ['POST'],
+ *   controllerReference: {
+ *     importExpression: "() => import('#controllers/users_controller')",
+ *     method: 'store'
+ *   },
+ *   tokens: [{ val: '/users', old: '/users', type: 0, end: '' }]
+ * }
  */
 export type RoutesListItem = {
+    /** Optional unique name for the route */
     name?: string;
+    /** Route pattern with parameter placeholders */
     pattern: string;
+    /** Domain on which the route is registered */
     domain: string;
+    /** HTTP methods accepted by this route */
     methods: string[];
+    /** Controller reference information (if controller-based route) */
     controllerReference?: {
+        /** Dynamic import expression for the controller */
         importExpression: string;
+        /** Specific controller method to call */
         method?: string;
     };
+    /** Parsed route tokens for URI construction */
     tokens: {
         val: string;
         old: string;
@@ -94,22 +190,40 @@ export type RoutesListItem = {
     }[];
 };
 /**
- * Rules accepted by the route scanner.
+ * Configuration rules accepted by the routes scanner to customize
+ * the scanning behavior and override type inference.
+ *
+ * @example
+ * const rules: RoutesScannerRules = {
+ *   skip: ['admin.dashboard', 'health.check'],
+ *   response: {
+ *     'users.index': {
+ *       type: 'PaginatedResponse<User[]>',
+ *       imports: ['import { User } from "#models/user"']
+ *     }
+ *   },
+ *   request: {
+ *     'users.store': {
+ *       type: 'CreateUserRequest',
+ *       imports: ['import { CreateUserRequest } from "#types/requests"']
+ *     }
+ *   }
+ * }
  */
 export type RoutesScannerRules = {
     /**
-     * An array of route names or controller+method paths to skip from
-     * the processing
+     * An array of route names or controller+method paths to skip from processing.
+     * Useful for excluding routes that don't need type generation.
      */
     skip: string[];
     /**
-     * Define custom response type for a route by its name or the
-     * controller+method path
+     * Define custom response types for specific routes by their name
+     * or controller+method path. Overrides automatic type inference.
      */
     response: Record<string, ScannedRoute['response']>;
     /**
-     * Define custom request data type for a route by its name
-     * or the controller+method path
+     * Define custom request data types for specific routes by their name
+     * or controller+method path. Overrides automatic type inference.
      */
     request: Record<string, ScannedRoute['response']>;
 };

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

@@ -1,61 +1,103 @@
 /**
- * Entry to add a middleware to a given middleware stack
- * via the CodeTransformer
+ * Entry to add a middleware to a given middleware stack via the CodeTransformer.
+ * Represents middleware configuration for server, router, or named middleware stacks.
+ *
+ * @example
+ * const corsMiddleware: MiddlewareNode = {
+ *   path: '@adonisjs/cors/cors_middleware',
+ *   position: 'before'
+ * }
+ *
+ * const namedMiddleware: MiddlewareNode = {
+ *   name: 'auth',
+ *   path: '#middleware/auth_middleware',
+ *   position: 'after'
+ * }
  */
 export type MiddlewareNode = {
     /**
-     * If you are adding a named middleware, then you must
-     * define the name.
+     * Required for named middleware. The key name under which the middleware
+     * will be registered in the named middleware collection.
      */
     name?: string;
     /**
-     * The path to the middleware file
+     * The import path to the middleware file. Can be a package import,
+     * subpath import, or relative path.
      *
      * @example
-     *  `@adonisjs/static/static_middleware`
-     *  `#middlewares/silent_auth.js`
+     * '@adonisjs/static/static_middleware'
+     * '#middlewares/silent_auth'
+     * './middleware/custom_middleware.js'
      */
     path: string;
     /**
-     * The position to add the middleware. If `before`
-     * middleware will be added at the first position and
-     * therefore will be run before all others
+     * The position to add the middleware in the stack.
+     * 'before' adds at the beginning (runs first), 'after' adds at the end (runs last).
      *
      * @default 'after'
      */
     position?: 'before' | 'after';
 };
 /**
- * Policy node to be added to the list of policies.
+ * Policy node to be added to the list of Bouncer authorization policies.
+ * Used for registering policies in the application's policy registry.
+ *
+ * @example
+ * const userPolicy: BouncerPolicyNode = {
+ *   name: 'UserPolicy',
+ *   path: '#policies/user_policy'
+ * }
  */
 export type BouncerPolicyNode = {
     /**
-     * Policy name
+     * The name of the policy class (should match the exported class name)
      */
     name: string;
     /**
-     * Policy import path
+     * The import path to the policy file
      */
     path: string;
 };
 /**
- * Defines the structure of an environment variable validation
- * definition
+ * Defines the structure of an environment variable validation definition.
+ * Used to add new environment variable validations to the start/env.ts file.
+ *
+ * @example
+ * const envValidation: EnvValidationNode = {
+ *   leadingComment: 'Database configuration',
+ *   variables: {
+ *     DB_HOST: 'Env.schema.string()',
+ *     DB_PORT: 'Env.schema.number.optional({ port: 5432 })',
+ *     DB_PASSWORD: 'Env.schema.string.optional()'
+ *   }
+ * }
  */
 export type EnvValidationNode = {
     /**
-     * Write a leading comment on top of your variables
+     * Optional leading comment to write above the variable definitions.
+     * Helps group related environment variables together.
      */
     leadingComment?: string;
     /**
-     * A key-value pair of env variables and their validation
+     * A key-value pair of environment variables and their validation schemas.
+     * The key is the environment variable name, the value is the validation code.
      *
      * @example
-     *  MY_VAR: 'Env.schema.string.optional()'
+     * {
+     *   MY_VAR: 'Env.schema.string.optional()',
+     *   API_KEY: 'Env.schema.string()'
+     * }
      */
     variables: Record<string, string>;
 };
 /**
- * The supported package managers for installing packages
+ * The supported package managers for installing packages and managing lockfiles.
+ * Each package manager has specific lockfiles and install commands.
+ *
+ * @example
+ * const packageManager: SupportedPackageManager = 'pnpm'
+ *
+ * // Used in bundler configuration
+ * const bundler = new Bundler(cwd, ts, { packageManager: 'yarn@berry' })
  */
 export type SupportedPackageManager = 'npm' | 'yarn' | 'yarn@berry' | 'pnpm' | 'bun';