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

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,34 @@ 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;
+    /**
+     * 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

@@ -1,11 +1,26 @@
 import { type AsyncOrSync } from '@poppinss/utils/types';
 import { PathsResolver } from '../../paths_resolver.ts';
-import { AstFileSystem } from '../../ast_file_system.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 to log colorful messages
+     * CLI UI instance to log colorful messages and progress information
      */
     ui: {
         colors: import("@poppinss/colors/types").Colors;
@@ -33,21 +48,25 @@ export declare class RoutesScanner {
      * imports to absolute paths
      */
     pathsResolver: PathsResolver;
-    /**
-     * The AstFileSystem is used to convert files to AST-grep nodes.
-     * The AST is cached to speed up the performance.
-     */
-    astFileSystem: AstFileSystem;
     /**
      * 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;
     /**
@@ -55,25 +74,46 @@ export declare class RoutesScanner {
      * 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.
+     * 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<void>;
     /**
      * 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,445 @@
+import {
+  findImport,
+  inspectClass,
+  inspectClassMethods,
+  inspectMethodArguments,
+  nodeToPlainText,
+  searchValidatorDirectUsage
+} from "../../../chunk-TIKQQRMX.js";
+import {
+  VirtualFileSystem,
+  debug_default,
+  isRelative
+} from "../../../chunk-F4RAGKQN.js";
+
+// src/code_scanners/routes_scanner/main.ts
+import { cliui } from "@poppinss/cliui";
+import string2 from "@poppinss/utils/string";
+import { parseImports } from "parse-imports";
+import StringBuilder from "@poppinss/utils/string_builder";
+
+// src/paths_resolver.ts
+import { fileURLToPath } from "url";
+var PathsResolver = class {
+  /**
+   * Cache of resolved paths to avoid resolving the same specifier multiple times
+   */
+  #resolvedPaths = {};
+  /**
+   * The resolver function used to resolve import specifiers
+   */
+  #resolver = (specifier) => import.meta.resolve(specifier);
+  /**
+   * 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) {
+    this.#resolver = resolver;
+  }
+  /**
+   * 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) {
+    if (isRelative(specifier)) {
+      throw new Error("Cannot resolve relative paths using PathsResolver");
+    }
+    const cacheKey = specifier;
+    const cached = this.#resolvedPaths[cacheKey];
+    if (cached) {
+      return cached;
+    }
+    this.#resolvedPaths[cacheKey] = fileURLToPath(this.#resolver(specifier));
+    return this.#resolvedPaths[cacheKey];
+  }
+};
+
+// src/code_scanners/routes_scanner/validator_extractor.ts
+import { relative } from "path";
+import string from "@poppinss/utils/string";
+import { fileURLToPath as fileURLToPath2, pathToFileURL } from "url";
+async function extractValidators(appRoot, vfs, controller) {
+  const root = await vfs.get(controller.path);
+  const fileContents = root.text();
+  const controllerClass = inspectClass(root);
+  if (!controllerClass) {
+    debug_default(`No class defined within the "%s"`, controller.import.specifier);
+    return;
+  }
+  const method = inspectClassMethods(controllerClass).find((e) => {
+    return e.find({
+      rule: { kind: "property_identifier", regex: `\\b${controller.method}\\b` }
+    });
+  });
+  if (!method) {
+    debug_default(`Unable to find "%s" method in "%s"`, controller.method, controller.import.specifier);
+    return;
+  }
+  const validationCalls = inspectMethodArguments(method, ["request.validateUsing", "vine.validate"]).map((node) => {
+    const firstArg = node.find({
+      rule: { any: [{ kind: "identifier" }, { kind: "member_expression" }] }
+    });
+    if (!firstArg) {
+      return;
+    }
+    return nodeToPlainText(firstArg);
+  }).filter((node) => node !== void 0).concat(searchValidatorDirectUsage(method).map((node) => nodeToPlainText(node)));
+  if (!validationCalls.length) {
+    debug_default(
+      `Unable to detect any validation calls in "%s.%s" method`,
+      controller.import.specifier,
+      controller.method
+    );
+    return;
+  }
+  const controllerName = controllerClass.find({ rule: { kind: "type_identifier" } }).text();
+  const controllerURL = pathToFileURL(controller.path);
+  const imports = await Promise.all(
+    validationCalls.map(async (validationCall) => {
+      const validatorNamespace = validationCall.split(".")[0];
+      if (validatorNamespace === controllerName) {
+        return {
+          name: validationCall,
+          import: {
+            specifier: controller.import.specifier,
+            type: "default",
+            value: controllerName
+          }
+        };
+      }
+      const importCall = await findImport(fileContents, validationCall);
+      if (!importCall) {
+        debug_default(
+          'Unable to find import for "%s" used by "%s.%s" method',
+          validationCall,
+          controller.import.specifier,
+          controller.method
+        );
+        return null;
+      }
+      return {
+        name: validationCall,
+        import: {
+          specifier: isRelative(importCall.specifier) ? string.toUnixSlash(
+            relative(appRoot, fileURLToPath2(new URL(importCall.specifier, controllerURL)))
+          ) : importCall.specifier,
+          type: importCall.clause.type,
+          value: importCall.clause.value
+        }
+      };
+    })
+  );
+  return imports.filter((value) => !!value);
+}
+
+// src/code_scanners/routes_scanner/main.ts
+var RoutesScanner = class {
+  /**
+   * The root of the application from where we will resolve
+   * paths.
+   */
+  #appRoot;
+  /**
+   * Collection of routes by their controller file path. This helps
+   * us re-compute request types when the controller is changed.
+   */
+  #controllerRoutes = {};
+  /**
+   * Collection of scanned routes
+   */
+  #scannedRoutes = [];
+  /**
+   * A custom method to self compute the response type for a route. Return
+   * undefined to fallback to the default behavior
+   */
+  #computeResponseTypes;
+  /**
+   * A custom method to self compute the request type for a route. Return
+   * undefined to fallback to the default behavior
+   */
+  #computeRequestTypes;
+  /**
+   * A custom method to self extract the validators from the route controller.
+   * Return undefined to fallback to the default behavior.
+   */
+  #extractValidators;
+  /**
+   * CLI UI instance to log colorful messages and progress information
+   */
+  ui = cliui();
+  /**
+   * The paths resolver is used to convert subpath and package
+   * imports to absolute paths
+   */
+  pathsResolver = new PathsResolver();
+  /**
+   * The rules to apply when scanning routes
+   */
+  rules = {
+    skip: [],
+    request: {},
+    response: {}
+  };
+  /**
+   * Create a new RoutesScanner instance
+   *
+   * @param appRoot - The root directory of the application
+   * @param rulesCollection - Collection of rules to apply during scanning
+   */
+  constructor(appRoot, rulesCollection) {
+    this.#appRoot = appRoot;
+    rulesCollection.forEach((rules) => {
+      this.rules.skip = this.rules.skip.concat(rules.skip);
+      Object.assign(this.rules.request, rules.request);
+      Object.assign(this.rules.response, rules.response);
+    });
+    this.rules.skip = Array.from(/* @__PURE__ */ new Set([...this.rules.skip]));
+  }
+  /**
+   * Assumes the validators are from VineJS and computes the request types from them
+   *
+   * This method generates TypeScript type definitions for request validation
+   * by analyzing VineJS validators and creating Infer types.
+   *
+   * @param route - The scanned route with validators
+   * @returns Request type definition or undefined
+   */
+  #prepareRequestTypes(route) {
+    if (!route.validators) {
+      return;
+    }
+    const schemas = route.validators.reduce((result, validator) => {
+      const validatorExport = validator.import.type === "default" ? ".default" : validator.import.type === "named" ? `.${validator.import.value}` : "";
+      const [, ...segments] = validator.name.split(".");
+      const namespace = segments.map((segment) => `['${segment}']`).join("");
+      result.push(
+        `Infer<(typeof import('${validator.import.specifier}')${validatorExport})${namespace}>`
+      );
+      return result;
+    }, []);
+    return {
+      type: schemas.join("|"),
+      imports: [`import { Infer } from '@vinejs/vine/types'`]
+    };
+  }
+  /**
+   * Inspects the controller reference and fetches its import specifier
+   * and the controller name from it.
+   */
+  async #inspectControllerSpecifier(importExpression, method) {
+    const imports = [...await parseImports(importExpression)];
+    const importedModule = imports.find(
+      ($import) => $import.isDynamicImport && $import.moduleSpecifier.value
+    );
+    if (!importedModule || importedModule.moduleSpecifier.type !== "package" || !importedModule.moduleSpecifier.value) {
+      return null;
+    }
+    const specifier = importedModule.moduleSpecifier.value;
+    const name = new StringBuilder(specifier.split("/").pop()).removeSuffix("Controller").pascalCase().suffix("Controller").toString();
+    return {
+      name,
+      method: method ?? "handle",
+      path: string2.toUnixSlash(this.pathsResolver.resolve(specifier)),
+      import: {
+        specifier,
+        type: "default",
+        value: name
+      }
+    };
+  }
+  /**
+   * Defines the response type for the route
+   */
+  async #setResponse(route, controller) {
+    const responseType = await this.#computeResponseTypes?.(route, controller, this);
+    route.response = responseType ?? {
+      type: `ReturnType<import('${controller.import.specifier}').default['${controller.method}']>`,
+      imports: []
+    };
+  }
+  /**
+   * Defines the request type for the route
+   */
+  async #setRequest(route, controller, vfs) {
+    route.validators = await this.#extractValidators?.(route, controller, this) ?? await extractValidators(this.#appRoot, vfs, controller);
+    route.request = await this.#computeRequestTypes?.(route, controller, this) ?? this.#prepareRequestTypes(route);
+  }
+  /**
+   * Scans a route that is not using a controller
+   */
+  #processRouteWithoutController(route) {
+    if (!route.name) {
+      debug_default(`skipping route "%s" scanning. Missing a controller reference`, route.name);
+      return;
+    }
+    const scannedRoute = {
+      name: route.name,
+      domain: route.domain,
+      methods: route.methods,
+      pattern: route.pattern,
+      tokens: route.tokens,
+      request: this.rules.request[route.name],
+      response: this.rules.response[route.name]
+    };
+    this.#scannedRoutes.push(scannedRoute);
+  }
+  /**
+   * Scans a route that is using a controller reference
+   */
+  async #processRouteWithController(route, vfs) {
+    const controller = await this.#inspectControllerSpecifier(
+      route.controllerReference.importExpression,
+      route.controllerReference.method
+    );
+    if (!controller) {
+      return this.#processRouteWithoutController(route);
+    }
+    const routeName = route.name ?? new StringBuilder(controller.name).removeSuffix("Controller").snakeCase().suffix(`.${string2.snakeCase(controller.method)}`).toString();
+    if (this.rules.skip.includes(routeName)) {
+      return;
+    }
+    const scannedRoute = {
+      name: routeName,
+      domain: route.domain,
+      methods: route.methods,
+      pattern: route.pattern,
+      tokens: route.tokens,
+      request: this.rules.request[routeName],
+      response: this.rules.response[routeName],
+      controller
+    };
+    this.#scannedRoutes.push(scannedRoute);
+    if (!scannedRoute.request || !scannedRoute.response) {
+      this.#controllerRoutes[controller.path] ??= [];
+      this.#controllerRoutes[controller.path].push(scannedRoute);
+      if (!scannedRoute.response) {
+        await this.#setResponse(scannedRoute, controller);
+      }
+      if (!scannedRoute.request) {
+        await this.#setRequest(scannedRoute, controller, vfs);
+      }
+    }
+  }
+  /**
+   * Processing a given route list item and further scan it to
+   * fetch the controller, request and response types.
+   */
+  async #processRoute(route, vfs) {
+    if (route.name && this.rules.skip.includes(route.name)) {
+      return;
+    }
+    if (!route.controllerReference) {
+      this.#processRouteWithoutController(route);
+      return;
+    }
+    await this.#processRouteWithController(
+      route,
+      vfs
+    );
+  }
+  /**
+   * 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) {
+    this.#computeResponseTypes = callback;
+    return 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) {
+    this.#computeRequestTypes = callback;
+    return 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) {
+    this.#extractValidators = callback;
+    return this;
+  }
+  /**
+   * Returns the scanned routes
+   *
+   * @returns Array of scanned routes with their metadata
+   */
+  getScannedRoutes() {
+    return this.#scannedRoutes;
+  }
+  /**
+   * Returns an array of controllers bound to the provided
+   * routes
+   *
+   * @returns Array of controller's absolute paths
+   */
+  getControllers() {
+    return Object.keys(this.#controllerRoutes);
+  }
+  /**
+   * Invalidating a controller will trigger computing the validators,
+   * request types and the response types.
+   *
+   * @param controllerPath - Path to the controller file to invalidate
+   */
+  async invalidate(controllerPath) {
+    const controllerRoutes = this.#controllerRoutes[controllerPath];
+    if (!controllerRoutes) {
+      return;
+    }
+    for (let scannedRoute of controllerRoutes) {
+      if (scannedRoute.controller) {
+        const vfs = new VirtualFileSystem(this.#appRoot);
+        await this.#setResponse(scannedRoute, scannedRoute.controller);
+        await this.#setRequest(scannedRoute, scannedRoute.controller, vfs);
+      }
+    }
+  }
+  /**
+   * 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
+   */
+  async scan(routes) {
+    const vfs = new VirtualFileSystem(this.#appRoot);
+    for (let route of routes) {
+      await this.#processRoute(route, vfs);
+    }
+    vfs.invalidate();
+  }
+};
+export {
+  RoutesScanner
+};

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

@@ -1,8 +1,11 @@
-import { type AstFileSystem } from '../../ast_file_system.ts';
+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. The following syntaxes are supported.
+ * 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)`
@@ -14,5 +17,10 @@ import { type ScannedController, type ScannedRoute } from '../../types/code_scan
  *
  * 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, astFileSystem: AstFileSystem, controller: ScannedController): Promise<ScannedRoute['validators']>;
+export declare function extractValidators(appRoot: string, vfs: VirtualFileSystem, controller: ScannedController): Promise<ScannedRoute['validators']>;