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

package/build/src/bundler.d.ts

@@ -1,13 +1,28 @@
 import type tsStatic from 'typescript';
 import type { BundlerOptions } from './types/common.ts';
 import { type SupportedPackageManager } from './types/code_transformer.ts';
+/**
+ * List of package managers we support in order to
+ * copy lockfiles
+ */
+export declare const SUPPORTED_PACKAGE_MANAGERS: {
+    [K in SupportedPackageManager]: {
+        packageManagerFiles: string[];
+        installCommand: string;
+    };
+};
 /**
  * The bundler class exposes the API to build an AdonisJS project.
+ *
+ * @example
+ * const bundler = new Bundler(new URL('./'), ts, { hooks: [] })
+ * const success = await bundler.bundle()
  */
 export declare class Bundler {
     #private;
-    cwd: URL;
-    options: BundlerOptions;
+    /**
+     * CLI UI instance for displaying colorful messages and progress information
+     */
     ui: {
         colors: import("@poppinss/colors/types").Colors;
         logger: import("@poppinss/cliui").Logger;
@@ -30,12 +45,38 @@ export declare class Bundler {
         useColors(colorsToUse: import("@poppinss/colors/types").Colors): void;
     };
     /**
-     * Package manager detect from the project environment
+     * Package manager detected from the project environment
      */
     packageManager: SupportedPackageManager;
+    /**
+     * The current working directory URL
+     */
+    cwd: URL;
+    /**
+     * The current working project directory path as string
+     */
+    cwdPath: string;
+    /**
+     * Bundler configuration options including hooks and meta files
+     */
+    options: BundlerOptions;
+    /**
+     * Create a new bundler instance
+     *
+     * @param cwd - The current working directory URL
+     * @param ts - TypeScript module reference
+     * @param options - Bundler configuration options
+     */
     constructor(cwd: URL, ts: typeof tsStatic, options: BundlerOptions);
     /**
      * Bundles the application to be run in production
+     *
+     * @param stopOnError - Whether to stop the build process on TypeScript errors
+     * @param client - Override the detected package manager
+     * @returns Promise that resolves to true if build succeeded, false otherwise
+     *
+     * @example
+     * const success = await bundler.bundle(true, 'npm')
      */
     bundle(stopOnError?: boolean, client?: SupportedPackageManager): Promise<boolean>;
 }

package/build/src/code_scanners/routes_scanner/main.d.ts

@@ -0,0 +1,119 @@
+import { type AsyncOrSync } from '@poppinss/utils/types';
+import { PathsResolver } from '../../paths_resolver.ts';
+import { type ScannedRoute, type RoutesListItem, type ScannedController, type RoutesScannerRules } from '../../types/code_scanners.ts';
+/**
+ * RoutesScanner is responsible for scanning application routes,
+ * extracting their controllers, validators, request and response types.
+ *
+ * The RoutesScanner analyzes route definitions to extract TypeScript type information
+ * for request validation, response types, and controller methods. It supports custom
+ * rules for overriding default behavior and provides hooks for extending functionality.
+ *
+ * @example
+ * const scanner = new RoutesScanner(appRoot, [rules])
+ * scanner.defineResponse((route, controller) => {
+ *   return { type: 'CustomResponseType', imports: [] }
+ * })
+ * await scanner.scan(routes)
+ * const scannedRoutes = scanner.getScannedRoutes()
+ */
+export declare class RoutesScanner {
+    #private;
+    /**
+     * 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;
+    };
+    /**
+     * The paths resolver is used to convert subpath and package
+     * imports to absolute paths
+     */
+    pathsResolver: PathsResolver;
+    /**
+     * The rules to apply when scanning routes
+     */
+    rules: RoutesScannerRules;
+    /**
+     * Create a new RoutesScanner instance
+     *
+     * @param appRoot - The root directory of the application
+     * @param rulesCollection - Collection of rules to apply during scanning
+     */
+    constructor(appRoot: string, rulesCollection: RoutesScannerRules[]);
+    /**
+     * Register a callback to self compute the response types for
+     * a given route. The callback will be executed for all
+     * the routes and you must return undefined to fallback
+     * to the default behavior of detecting types
+     *
+     * @param callback - Function to compute response types for routes
+     * @returns This RoutesScanner instance for method chaining
+     */
+    defineResponse(callback: (route: ScannedRoute, controller: ScannedController, scanner: RoutesScanner) => AsyncOrSync<ScannedRoute['response']>): this;
+    /**
+     * Register a callback to self compute the request types for
+     * a given route. The callback will be executed for all
+     * the routes and you must return undefined to fallback
+     * to the default behavior of detecting types
+     *
+     * @param callback - Function to compute request types for routes
+     * @returns This RoutesScanner instance for method chaining
+     */
+    defineRequest(callback: (route: ScannedRoute, controller: ScannedController, scanner: RoutesScanner) => AsyncOrSync<ScannedRoute['request']>): this;
+    /**
+     * Register a callback to extract validators from the route controller
+     *
+     * @param callback - Function to extract validators from controllers
+     * @returns This RoutesScanner instance for method chaining
+     */
+    extractValidators(callback: (route: ScannedRoute, controller: ScannedController, scanner: RoutesScanner) => AsyncOrSync<ScannedRoute['validators']>): this;
+    /**
+     * Returns the scanned routes
+     *
+     * @returns Array of scanned routes with their metadata
+     */
+    getScannedRoutes(): ScannedRoute[];
+    /**
+     * Returns an array of controllers bound to the provided
+     * routes
+     *
+     * @returns Array of controller's absolute paths
+     */
+    getControllers(): string[];
+    /**
+     * Invalidating a controller will trigger computing the validators,
+     * request types and the response types.
+     *
+     * @param controllerPath - Path to the controller file to invalidate
+     */
+    invalidate(controllerPath: string): Promise<boolean>;
+    /**
+     * Scans an array of Route list items and fetches their validators,
+     * controllers, and request/response types.
+     *
+     * This is the main method that processes all routes and extracts
+     * their type information for code generation purposes.
+     *
+     * @param routes - Array of route list items to scan
+     */
+    scan(routes: RoutesListItem[]): Promise<void>;
+}

package/build/src/code_scanners/routes_scanner/main.js

@@ -0,0 +1,8 @@
+import {
+  RoutesScanner
+} from "../../../chunk-NAASGAFO.js";
+import "../../../chunk-TIKQQRMX.js";
+import "../../../chunk-JFBQ4OEM.js";
+export {
+  RoutesScanner
+};

package/build/src/code_scanners/routes_scanner/validator_extractor.d.ts

@@ -0,0 +1,26 @@
+import { type VirtualFileSystem } from '../../virtual_file_system.ts';
+import { type ScannedController, type ScannedRoute } from '../../types/code_scanners.ts';
+/**
+ * Extracts the VineJS validator usage from within a controller method.
+ *
+ * This function analyzes controller method code to detect validator usage patterns
+ * and extracts the validator references along with their import information.
+ * The following syntaxes are supported:
+ *
+ * - `request.validateUsing(validatorReference)`
+ * - `vine.validate(validatorReference)`
+ * - `validatorReference.validate(request.all())`
+ *
+ * - `request.validateUsing(ControllerReference.validator)`
+ * - `vine.validate(ControllerReference.validator)`
+ * - `ControllerReference.validator.validate(request.all())`
+ *
+ * The app root is needed to create relative validator imports in case
+ * a relative import was used within the controller file.
+ *
+ * @param appRoot - The root directory of the application
+ * @param vfs - Virtual file system instance for code analysis
+ * @param controller - The controller to analyze for validator usage
+ * @returns Promise resolving to array of validator information or undefined
+ */
+export declare function extractValidators(appRoot: string, vfs: VirtualFileSystem, controller: ScannedController): Promise<ScannedRoute['validators']>;

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

@@ -1,44 +1,72 @@
-import { type OneOrMore } from '@poppinss/utils/types';
 import { installPackage, detectPackageManager } from '@antfu/install-pkg';
 import { Project } from 'ts-morph';
 import { RcFileTransformer } from './rc_file_transformer.ts';
 import type { MiddlewareNode, EnvValidationNode, BouncerPolicyNode } from '../types/code_transformer.ts';
 /**
- * This class is responsible for updating
+ * This class is responsible for transforming AdonisJS project code,
+ * including updating middleware, environment validations, and other
+ * code generation tasks.
+ *
+ * The CodeTransformer provides methods for modifying various AdonisJS
+ * configuration files and code structures using AST manipulation through
+ * ts-morph. It can update middleware stacks, add environment validations,
+ * register plugins, and modify RC file configurations.
+ *
+ * @example
+ * const transformer = new CodeTransformer(cwd)
+ * await transformer.addMiddlewareToStack('server', [{
+ *   path: '#middleware/cors_middleware',
+ *   position: 'before'
+ * }])
  */
 export declare class CodeTransformer {
     #private;
     /**
-     * Exporting utilities to install package and detect
-     * the package manager
+     * Utility function for installing packages
      */
     installPackage: typeof installPackage;
+    /**
+     * Utility function for detecting the package manager
+     */
     detectPackageManager: typeof detectPackageManager;
     /**
-     * The TsMorph project
+     * The TsMorph project instance for AST manipulation
      */
     project: Project;
+    /**
+     * Create a new CodeTransformer instance
+     *
+     * @param cwd - The current working directory URL
+     */
     constructor(cwd: URL);
     /**
-     * Add new env variable validation in the
-     * `env.ts` file
+     * Add new env variable validation in the `env.ts` file
+     *
+     * @param definition - Environment validation definition containing variables and comment
      */
     defineEnvValidations(definition: EnvValidationNode): Promise<void>;
     /**
-     * Define new middlewares inside the `start/kernel.ts`
-     * file
+     * Define new middlewares inside the `start/kernel.ts` file
      *
      * This function is highly based on some assumptions
      * and will not work if you significantly tweaked
      * your `start/kernel.ts` file.
+     *
+     * @param stack - The middleware stack to add to ('server', 'router', or 'named')
+     * @param middleware - Array of middleware entries to add
      */
     addMiddlewareToStack(stack: 'server' | 'router' | 'named', middleware: MiddlewareNode[]): Promise<void>;
     /**
-     * Update the `adonisrc.ts` file
+     * Update the `adonisrc.ts` file using the provided callback
+     *
+     * @param callback - Function that receives the RcFileTransformer for modifications
      */
     updateRcFile(callback: (transformer: RcFileTransformer) => void): Promise<void>;
     /**
      * Add a new Japa plugin in the `tests/bootstrap.ts` file
+     *
+     * @param pluginCall - The plugin function call to add
+     * @param importDeclarations - Import declarations needed for the plugin
      */
     addJapaPlugin(pluginCall: string, importDeclarations: {
         isNamed: boolean;
@@ -46,7 +74,10 @@ export declare class CodeTransformer {
         identifier: string;
     }[]): Promise<void>;
     /**
-     * Add a new Vite plugin
+     * Add a new Vite plugin to the `vite.config.ts` file
+     *
+     * @param pluginCall - The plugin function call to add
+     * @param importDeclarations - Import declarations needed for the plugin
      */
     addVitePlugin(pluginCall: string, importDeclarations: {
         isNamed: boolean;
@@ -56,38 +87,8 @@ export declare class CodeTransformer {
     /**
      * Adds a policy to the list of `policies` object configured
      * inside the `app/policies/main.ts` file.
-     */
-    addPolicies(policies: BouncerPolicyNode[]): Promise<void>;
-    /**
-     * Creates an index file that exports an object in which the key is the PascalCase
-     * name of the entity and the value is a dynamic import.
-     *
-     * For example, in case of controllers, the index file will be the list of controller
-     * names pointing a dynamically imported controller file.
      *
-     * ```ts
-     * export const controllers = {
-     *   LoginController: () => import('#controllers/login_controller'),
-     *   LogoutController: () => import('#controllers/logout_controller'),
-     * }
-     * ```
-     *
-     * @param source
-     * @param outputPath
-     * @param importAlias
+     * @param policies - Array of bouncer policy entries to add
      */
-    makeEntityIndex(input: OneOrMore<{
-        source: string;
-        importAlias?: string;
-        allowedExtensions?: string[];
-    }>, output: {
-        destination: string;
-        exportName?: string;
-        removeNameSuffix?: string;
-        computeBaseName?: (filePath: string, sourcePath: string) => string;
-        computeOutput?: (entries: {
-            name: string;
-            importPath: string;
-        }[]) => string;
-    }): Promise<void>;
+    addPolicies(policies: BouncerPolicyNode[]): Promise<void>;
 }