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

package/build/src/test_runner.d.ts

@@ -1,69 +1,96 @@
 import type tsStatic from 'typescript';
+import { cliui } from '@poppinss/cliui';
 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 to log colorful messages and progress information
      */
-    ui: {
-        colors: import("@poppinss/colors/types").Colors;
-        logger: import("@poppinss/cliui").Logger;
-        table: (tableOptions?: Partial<import("@poppinss/cliui/types").TableOptions>) => import("@poppinss/cliui").Table;
-        tasks: (tasksOptions?: Partial<import("@poppinss/cliui/types").TaskManagerOptions>) => import("@poppinss/cliui").TaskManager;
-        icons: {
-            tick: string;
-            cross: string;
-            bullet: string;
-            nodejs: string;
-            pointer: string;
-            info: string;
-            warning: string;
-            squareSmallFilled: string;
-        };
-        sticker: () => import("@poppinss/cliui").Instructions;
-        instructions: () => import("@poppinss/cliui").Instructions;
-        switchMode(modeToUse: "raw" | "silent" | "normal"): void;
-        useRenderer(rendererToUse: import("@poppinss/cliui/types").RendererContract): void;
-        useColors(colorsToUse: import("@poppinss/colors/types").Colors): void;
-    };
+    get ui(): ReturnType<typeof cliui>;
+    /**
+     * CLI UI instance to log colorful messages and progress information
+     */
+    set ui(ui: ReturnType<typeof cliui>);
     /**
      * The script file to run as a child process
      */
     scriptFile: string;
+    /**
+     * The current working directory URL
+     */
+    cwd: URL;
+    /**
+     * 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';