@adonisjs/assembler 8.0.0-next.0 → 8.0.0-next.10

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

@@ -0,0 +1,229 @@
+/**
+ * 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 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.
+     * May be duplicate across different domains.
+     */
+    name: string;
+    /**
+     * HTTP methods for which the route is defined (GET, POST, PUT, etc.)
+     */
+    methods: string[];
+    /**
+     * The domain on which the route is registered (typically 'root')
+     */
+    domain: string;
+    /**
+     * The route pattern with parameter placeholders (e.g., '/users/:id')
+     */
+    pattern: string;
+    /**
+     * Route tokens that can be used for constructing URIs without parsing the pattern.
+     * Contains information about static and dynamic segments.
+     */
+    tokens: {
+        val: string;
+        old: string;
+        type: 0 | 1 | 2 | 3;
+        end: string;
+    }[];
+    /**
+     * 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 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 validator information from the controller method.
+     * Only present when using controller-based routes with validation.
+     */
+    validators?: ScannedValidator[];
+    /**
+     * Extracted controller information including class and method details.
+     * Only present when using controller-based routes.
+     */
+    controller?: ScannedController;
+};
+/**
+ * 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;
+        type: 0 | 1 | 2 | 3;
+        end: string;
+    }[];
+};
+/**
+ * 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 processing.
+     * Useful for excluding routes that don't need type generation.
+     */
+    skip: string[];
+    /**
+     * 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 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';