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

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

@@ -3,67 +3,280 @@ import { type AsyncOrSync, type LazyImport } from '@poppinss/utils/types';
 import { type Bundler } from '../bundler.ts';
 import { type DevServer } from '../dev_server.ts';
 import { type TestRunner } from '../test_runner.ts';
+import { type RoutesListItem } from './code_scanners.ts';
+import { type IndexGenerator } from '../index_generator/main.ts';
+import { type RoutesScanner } from '../code_scanners/routes_scanner/main.ts';
 /**
- * Hooks executed by the file watcher.
+ * Defines a hook that can be either a lazy import or an object with a run method.
+ * This type provides flexibility in how hooks are defined and imported, supporting
+ * both dynamic imports for code splitting and direct object definitions.
+ *
+ * @template Fn - The function signature that the hook must conform to
+ *
+ * @example
+ * // Using lazy import
+ * const hook: DefineHook<(server: DevServer) => void> = () => import('./my-hook')
+ *
+ * // Using direct object
+ * const hook: DefineHook<(server: DevServer) => void> = {
+ *   run: (server) => console.log('Hook executed')
+ * }
+ */
+type DefineHook<Fn extends (...args: any) => any> = LazyImport<Fn> | {
+    run: Fn;
+};
+/**
+ * Common hooks executed by the dev-server, test runner and the bundler.
+ * These hooks are shared across all assembler operations and provide
+ * lifecycle management for initialization tasks.
+ *
+ * @example
+ * const commonHooks: CommonHooks = {
+ *   init: [
+ *     () => import('./hooks/create_barrel_files')
+ *   ]
+ * }
+ */
+export type CommonHooks = {
+    /**
+     * The hook is executed as the first step when assembler starts the
+     * dev-server, runs tests or creates a build. Use this hook to perform
+     * initialization tasks that are common across all operations.
+     *
+     * @param parent - The parent instance (DevServer, TestRunner, or Bundler)
+     */
+    init: DefineHook<(parent: DevServer | TestRunner | Bundler, indexGenerator: IndexGenerator) => AsyncOrSync<void>>[];
+};
+/**
+ * Hooks executed by the dev server around the router.
+ * These hooks provide lifecycle management for route scanning and processing.
+ *
+ * @example
+ * const routerHooks: RouterHooks = {
+ *   routesCommitted: [
+ *     () => import('./hooks/on_routes_committed')
+ *   ],
+ *   routesScanning: [
+ *     () => import('./hooks/before_routes_scan')
+ *   ],
+ *   routesScanned: [
+ *     () => import('./hooks/after_routes_scan')
+ *   ]
+ * }
+ */
+export type RouterHooks = {
+    /**
+     * The hook is executed when routes are committed by the dev server child
+     * process. Use this hook to react to route changes and perform related tasks.
+     *
+     * @param parent - The DevServer instance
+     * @param routes - Record of routes grouped by domain or method
+     */
+    routesCommitted: DefineHook<(parent: DevServer, routes: Record<string, RoutesListItem[]>) => AsyncOrSync<void>>[];
+    /**
+     * The hook is executed when dev server begins the routes scanning process.
+     * Use this hook to prepare for route scanning or modify scanner configuration.
+     *
+     * @param parent - The DevServer instance
+     * @param routesScanner - The RoutesScanner instance being used
+     */
+    routesScanning: DefineHook<(parent: DevServer, routesScanner: RoutesScanner) => AsyncOrSync<void>>[];
+    /**
+     * The hook is executed when routes scanning process has finished.
+     * Use this hook to process the scanned routes or clean up resources.
+     *
+     * @param parent - The DevServer instance
+     * @param routesScanner - The RoutesScanner instance that was used
+     */
+    routesScanned: DefineHook<(parent: DevServer, routesScanner: RoutesScanner) => AsyncOrSync<void>>[];
+};
+/**
+ * Hooks executed by the file watcher during development and testing.
  *
  * - In HMR mode, assembler will rely on hot-hook to notify about the filesystem changes.
  * - Otherwise, the inbuilt watcher of the DevServer or the TestsRunner will notify.
+ *
+ * @example
+ * const watcherHooks: WatcherHooks = {
+ *   fileChanged: [
+ *     () => import('./hooks/on_file_changed')
+ *   ],
+ *   fileAdded: [
+ *     () => import('./hooks/on_file_added')
+ *   ],
+ *   fileRemoved: [
+ *     () => import('./hooks/on_file_removed')
+ *   ]
+ * }
  */
 export type WatcherHooks = {
     /**
-     * The hook is executed after a file has been changed in the watch mode.
+     * The hook is executed after a file has been changed in watch mode.
+     * Provides information about the change source and reload behavior.
+     * Use this hook to react to file changes and trigger custom actions.
+     *
+     * @param filePath - The relative path to the changed file
+     * @param info - Information about the file change
+     * @param info.source - Source of the file change notification
+     * @param info.hotReloaded - Whether the file was hot reloaded without server restart
+     * @param info.fullReload - Whether a full server reload is required
+     * @param parent - The parent DevServer or TestRunner instance
      */
-    fileChanged: LazyImport<(filePath: string, info: {
+    fileChanged: DefineHook<(relativePath: string, absolutePath: string, info: {
+        /** Source of the file change notification */
         source: 'hot-hook' | 'watcher';
+        /** Whether the file was hot reloaded without server restart */
         hotReloaded: boolean;
+        /** Whether a full server reload is required */
         fullReload: boolean;
-    }, server: DevServer | TestRunner) => AsyncOrSync<void>>[];
+    }, parent: DevServer | TestRunner) => AsyncOrSync<void>>[];
     /**
-     * The hook is executed after a file has been added.
+     * The hook is executed after a file has been added to the filesystem.
+     * Use this hook to react to new files being added to the project.
+     *
+     * @param filePath - The absolute path to the added file
+     * @param server - The DevServer or TestRunner instance
      */
-    fileAdded: LazyImport<(filePath: string, server: DevServer | TestRunner) => AsyncOrSync<void>>[];
+    fileAdded: DefineHook<(relativePath: string, absolutePath: string, server: DevServer | TestRunner) => AsyncOrSync<void>>[];
     /**
-     * The hook is executed after a file has been removed.
+     * The hook is executed after a file has been removed from the filesystem.
+     * Use this hook to clean up resources or update caches when files are deleted.
+     *
+     * @param filePath - The absolute path to the removed file
+     * @param server - The DevServer or TestRunner instance
      */
-    fileRemoved: LazyImport<(filePath: string, server: DevServer | TestRunner) => AsyncOrSync<void>>[];
+    fileRemoved: DefineHook<(relativePath: string, absolutePath: string, server: DevServer | TestRunner) => AsyncOrSync<void>>[];
 };
 /**
- * Hooks executed when running the dev server.
+ * Hooks executed when running the development server.
+ *
+ * @example
+ * const devServerHooks: DevServerHooks = {
+ *   devServerStarting: [
+ *     () => import('./hooks/before_dev_server_start')
+ *   ],
+ *   devServerStarted: [
+ *     () => import('./hooks/after_dev_server_start')
+ *   ]
+ * }
  */
 export type DevServerHooks = {
     /**
-     * The hook is executed before the child process for the dev server
-     * is started.
+     * The hook is executed before the child process for the dev server is started.
+     * Use this hook to perform setup tasks or modify server configuration.
+     *
+     * @param server - The DevServer instance that is about to start
      */
-    devServerStarting: LazyImport<(server: DevServer) => AsyncOrSync<void>>[];
+    devServerStarting: DefineHook<(server: DevServer) => AsyncOrSync<void>>[];
     /**
      * The hook is executed after the child process has been started.
+     * Use this hook to display additional information or perform post-startup tasks.
+     *
+     * @param server - The DevServer instance that has started
+     * @param info - Server information containing port and host
+     * @param info.port - The port number the server is running on
+     * @param info.host - The host address the server is bound to
+     * @param uiInstructions - UI instructions for displaying server information
      */
-    devServerStarted: LazyImport<(server: DevServer, uiInstructions: Instructions) => AsyncOrSync<void>>[];
+    devServerStarted: DefineHook<(server: DevServer, info: {
+        port: number;
+        host: string;
+    }, uiInstructions: Instructions) => AsyncOrSync<void>>[];
 };
 /**
  * Hooks executed when the production build is created.
+ *
+ * @example
+ * const bundlerHooks: BundlerHooks = {
+ *   buildStarting: [
+ *     () => import('./hooks/before_build')
+ *   ],
+ *   buildFinished: [
+ *     () => import('./hooks/after_build')
+ *   ]
+ * }
  */
 export type BundlerHooks = {
     /**
-     * The hook is executed before we begin creating the production build
+     * The hook is executed before we begin creating the production build.
+     * Use this hook to perform pre-build tasks like asset optimization.
+     *
+     * @param server - The Bundler instance that will create the build
      */
-    buildStarting: LazyImport<(server: Bundler) => AsyncOrSync<void>>[];
+    buildStarting: DefineHook<(server: Bundler) => AsyncOrSync<void>>[];
     /**
-     * The hook is executed after the production build has been created
+     * The hook is executed after the production build has been created.
+     * Use this hook to perform post-build tasks or display build statistics.
+     *
+     * @param server - The Bundler instance that created the build
+     * @param uiInstructions - UI instructions for displaying build information
      */
-    buildFinished: LazyImport<(server: Bundler, uiInstructions: Instructions) => AsyncOrSync<void>>[];
+    buildFinished: DefineHook<(server: Bundler, uiInstructions: Instructions) => AsyncOrSync<void>>[];
 };
 /**
- * Hooks executed when running the tests
+ * Hooks executed when running the test suite.
+ *
+ * @example
+ * const testRunnerHooks: TestRunnerHooks = {
+ *   testsStarting: [
+ *     () => import('./hooks/before_tests')
+ *   ],
+ *   testsFinished: [
+ *     () => import('./hooks/after_tests')
+ *   ]
+ * }
  */
 export type TestRunnerHooks = {
     /**
-     * The hook is executed before we begin executing the tests
+     * The hook is executed before we begin executing the tests.
+     * Use this hook to set up test databases or perform pre-test setup.
+     *
+     * @param server - The TestRunner instance that will execute the tests
      */
-    testsStarting: LazyImport<(server: TestRunner) => AsyncOrSync<void>>[];
+    testsStarting: DefineHook<(server: TestRunner) => AsyncOrSync<void>>[];
     /**
-     * The hook is executed after the tests have been executed
+     * The hook is executed after the tests have been executed.
+     * Use this hook to clean up resources or generate test reports.
+     *
+     * @param server - The TestRunner instance that executed the tests
      */
-    testsFinished: LazyImport<(server: TestRunner) => AsyncOrSync<void>>[];
+    testsFinished: DefineHook<(server: TestRunner) => AsyncOrSync<void>>[];
 };
+/**
+ * Combined type representing all available hooks across the assembler ecosystem.
+ * This intersection type merges all hook categories into a single type for
+ * comprehensive hook management and type safety.
+ *
+ * @example
+ * ```js
+ * const allHooks: AllHooks = {
+ *   init: [() => import('./hooks/init')],
+ *   fileChanged: [() => import('./hooks/file_changed')],
+ *   devServerStarted: [() => import('./hooks/dev_server_started')],
+ *   buildFinished: [() => import('./hooks/build_finished')],
+ *   testsFinished: [() => import('./hooks/tests_finished')],
+ *   routesCommitted: [() => import('./hooks/routes_committed')]
+ * }
+ * ```
+ */
+export type AllHooks = CommonHooks & WatcherHooks & DevServerHooks & BundlerHooks & TestRunnerHooks & RouterHooks;
+/**
+ * Utility type that extracts the parameter types for a specific hook.
+ * This type helps maintain type safety when working with hook callbacks
+ * by providing the exact parameter signature for any given hook name.
+ *
+ * @template Hook - The name of the hook to extract parameters for
+ *
+ * @example
+ * ```js
+ * // Get parameters for the fileChanged hook
+ * type FileChangedParams = HookParams<'fileChanged'>
+ * // Result: [string, string, {...}, DevServer | TestRunner]
+ *
+ * // Get parameters for the devServerStarted hook
+ * type DevServerStartedParams = HookParams<'devServerStarted')
+ * // Result: [DevServer, {port: number, host: string}, Instructions]
+ * ```
+ */
+export type HookParams<Hook extends keyof AllHooks> = AllHooks[Hook][number] extends DefineHook<infer A> ? Parameters<A> : never;
+export {};

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

@@ -1,3 +1,17 @@
-export * from './common.ts';
+/**
+ * Main types module that re-exports all TypeScript type definitions
+ * used throughout the AdonisJS Assembler package.
+ *
+ * This module provides a single entry point for all type definitions including:
+ * - Hook types for development server, bundler, test runner, and file watcher
+ * - Common configuration types for servers and runners
+ * - Code scanner types for route analysis and type generation
+ * - Code transformer types for middleware, policies, and environment validation
+ *
+ * @example
+ * import { DevServerOptions, BundlerHooks, ScannedRoute } from '@adonisjs/assembler/types'
+ */
 export * from './hooks.ts';
+export * from './common.ts';
+export * from './code_scanners.ts';
 export * from './code_transformer.ts';

package/build/src/utils.d.ts

@@ -1,16 +1,34 @@
 import Hooks from '@poppinss/hooks';
 import type tsStatic from 'typescript';
 import { type ChokidarOptions } from 'chokidar';
-import { type UnWrapLazyImport } from '@poppinss/utils/types';
+import { type TsConfigResult } from 'get-tsconfig';
 import type { RunScriptOptions } from './types/common.ts';
-import { type WatcherHooks, type BundlerHooks, type DevServerHooks, type TestRunnerHooks } from './types/hooks.ts';
+import { type AllHooks, type HookParams } from './types/hooks.ts';
 /**
- * Parses tsconfig.json and prints errors using typescript compiler
- * host
+ * Parses tsconfig.json and prints errors using typescript compiler host
+ *
+ * This function reads and parses the tsconfig.json file from the given directory,
+ * handling diagnostic errors and returning a parsed configuration that can be
+ * used by other TypeScript operations.
+ *
+ * @deprecated While we are experimenting with the readTsConfig method
+ *
+ * @param cwd - The current working directory URL or string path
+ * @param ts - TypeScript module reference
+ * @returns Parsed TypeScript configuration or undefined if parsing failed
  */
 export declare function parseConfig(cwd: URL | string, ts: typeof tsStatic): tsStatic.ParsedCommandLine | undefined;
+export declare function readTsConfig(cwd: string): TsConfigResult | null;
 /**
  * Runs a Node.js script as a child process and inherits the stdio streams
+ *
+ * This function spawns a Node.js child process with TypeScript support enabled
+ * by default through ts-exec. It's primarily used for running development
+ * servers and test scripts.
+ *
+ * @param cwd - The current working directory URL or string path
+ * @param options - Script execution options including args, environment, etc.
+ * @returns Child process instance from execa
  */
 export declare function runNode(cwd: string | URL, options: RunScriptOptions): import("execa").ResultPromise<{
     nodeOptions: string[];
@@ -22,12 +40,19 @@ export declare function runNode(cwd: string | URL, options: RunScriptOptions): i
     buffer: false;
     stdio: "pipe" | "inherit";
     env: {
-        TZ?: string;
+        TZ?: string | undefined;
         FORCE_COLOR?: string | undefined;
     };
 }>;
 /**
  * Runs a script as a child process and inherits the stdio streams
+ *
+ * This function spawns a generic child process for running any executable
+ * script. Unlike runNode, this doesn't include TypeScript-specific Node.js arguments.
+ *
+ * @param cwd - The current working directory URL or string path
+ * @param options - Script execution options (excluding nodeArgs)
+ * @returns Child process instance from execa
  */
 export declare function run(cwd: string | URL, options: Omit<RunScriptOptions, 'nodeArgs'>): import("execa").ResultPromise<{
     preferLocal: true;
@@ -37,51 +62,110 @@ export declare function run(cwd: string | URL, options: Omit<RunScriptOptions, '
     buffer: false;
     stdio: "pipe" | "inherit";
     env: {
-        TZ?: string;
+        TZ?: string | undefined;
         FORCE_COLOR?: string | undefined;
     };
 }>;
 /**
- * Watches the file system using tsconfig file
+ * Watches the file system using chokidar with the provided options
+ *
+ * Creates a file system watcher that monitors the current directory
+ * for changes, supporting various chokidar options for customization.
+ *
+ * @param options - Chokidar watch options
+ * @returns Chokidar FSWatcher instance
  */
 export declare function watch(options: ChokidarOptions): import("chokidar").FSWatcher;
 /**
  * Check if file is a .env file
+ *
+ * Determines if a given file path represents an environment file,
+ * including .env and .env.* variants.
+ *
+ * @param filePath - The file path to check
+ * @returns True if the file is an environment file
  */
 export declare function isDotEnvFile(filePath: string): boolean;
 /**
- * Returns the port to use after inspect the dot-env files inside
+ * Returns the port to use after inspecting the dot-env files inside
  * a given directory.
  *
  * A random port is used when the specified port is in use. Following
- * is the logic for finding a specified port.
+ * is the logic for finding a specified port:
  *
  * - The "process.env.PORT" value is used if exists.
  * - The dot-env files are loaded using the "EnvLoader" and the PORT
  *   value is used by iterating over all the loaded files. The
  *   iteration stops after first find.
+ * - Falls back to port 3333 if no PORT is found in environment files.
+ *
+ * @param cwd - The current working directory URL
+ * @returns Promise resolving to an available port number
  */
 export declare function getPort(cwd: URL): Promise<number>;
 /**
- * Helper function to copy files from relative paths or glob
- * patterns
+ * Helper function to copy files from relative paths or glob patterns
+ *
+ * This function handles copying files and directories while preserving
+ * directory structure. It supports both direct file paths and glob patterns,
+ * and automatically filters out junk files.
+ *
+ * @param files - Array of file paths or glob patterns to copy
+ * @param cwd - Source directory path
+ * @param outDir - Destination directory path
+ * @returns Promise resolving when all files are copied
  */
 export declare function copyFiles(files: string[], cwd: string, outDir: string): Promise<void[]>;
 /**
  * Memoize a function using an LRU cache. The function must accept
  * only one argument as a string value.
+ *
+ * This utility provides caching for expensive function calls to improve
+ * performance by storing results in memory.
+ *
+ * @param fn - Function to memoize (only first argument is considered for memoization)
+ * @param maxKeys - Optional maximum number of cached keys
+ * @returns Memoized version of the function
  */
-export declare function memoize<Result>(fn: (input: string) => any, maxKeys?: number): (input: string) => Result;
+export declare function memoize<T extends any[], Result>(fn: (input: string, ...args: T) => any, maxKeys?: number): (input: string, ...args: T) => Result;
+/**
+ * Returns a boolean telling if the path value is a relative
+ * path starting with "./" or "../"
+ *
+ * @param pathValue - The path string to check
+ * @returns True if the path is relative, false otherwise
+ */
+export declare function isRelative(pathValue: string): boolean;
 /**
  * Imports a selected set of lazy hooks and creates an instance of the
  * Hooks class
+ *
+ * This function dynamically imports and initializes hooks based on the
+ * provided configuration, supporting different types of hooks for various
+ * assembler operations.
+ *
+ * @param rcFileHooks - Hook configuration from the RC file
+ * @param names - Array of hook names to load
+ * @returns Promise resolving to configured Hooks instance
  */
-type AllHooks = WatcherHooks & DevServerHooks & BundlerHooks & TestRunnerHooks;
-export declare function loadHooks<K extends keyof AllHooks>(rcFileHooks: Partial<AllHooks> | undefined, names: K[]): Promise<Hooks<{ [P in K]: [Parameters<UnWrapLazyImport<AllHooks[K][number]>>, Parameters<UnWrapLazyImport<AllHooks[K][number]>>]; }>>;
+export declare function loadHooks<K extends keyof AllHooks>(rcFileHooks: Partial<AllHooks> | undefined, names: K[]): Promise<Hooks<{ [P in K]: [HookParams<P>, HookParams<P>]; }>>;
 /**
  * Wraps a function inside another function that throttles the concurrent
  * executions of a function. If the function is called too quickly, then
  * it may result in two invocations at max.
+ *
+ * This utility prevents overwhelming the system with rapid successive calls
+ * by ensuring only one execution happens at a time, with at most one queued call.
+ *
+ * @param fn - Function to throttle
+ * @param name - Optional name for debugging purposes
+ * @returns Throttled version of the function
  */
 export declare function throttle<Args extends any[]>(fn: (...args: Args) => PromiseLike<any>, name?: string): (...args: Args) => Promise<void>;
-export {};
+/**
+ * Removes the file extension from a file path
+ *
+ * @param filePath - The file path with extension
+ * @returns The file path without extension
+ */
+export declare function removeExtension(filePath: string): string;

package/build/src/virtual_file_system.d.ts

@@ -0,0 +1,112 @@
+import { type SgNode } from '@ast-grep/napi';
+import { type RecursiveFileTree, type VirtualFileSystemOptions } from './types/common.ts';
+/**
+ * Virtual file system for managing and tracking files with AST parsing capabilities.
+ *
+ * The VirtualFileSystem provides an abstraction layer over the physical file system,
+ * allowing efficient file scanning, filtering, and AST parsing with caching. It's
+ * designed to work with TypeScript/JavaScript files and provides various output
+ * formats for different use cases.
+ *
+ * @example
+ * const vfs = new VirtualFileSystem('/src', { glob: ['**\/*.ts'] })
+ * await vfs.scan()
+ * const fileTree = vfs.asTree()
+ * const astNode = await vfs.get('/src/app.ts')
+ */
+export declare class VirtualFileSystem {
+    #private;
+    /**
+     * Create a new VirtualFileSystem instance
+     *
+     * @param source - Absolute path to the source directory
+     * @param options - Optional configuration for file filtering and processing
+     */
+    constructor(source: string, options?: VirtualFileSystemOptions);
+    /**
+     * Scans the filesystem to collect the files. Newly files must
+     * be added via the ".add" method.
+     *
+     * This method performs an initial scan of the source directory using
+     * the configured glob patterns and populates the internal file list.
+     */
+    scan(): Promise<void>;
+    /**
+     * Check if a given file is part of the virtual file system. The method
+     * checks for the scanned files as well as glob pattern matches.
+     *
+     * @param filePath - Absolute file path to check
+     * @returns True if the file is tracked or matches the configured patterns
+     */
+    has(filePath: string): boolean;
+    /**
+     * Returns the files as a flat list of key-value pairs
+     *
+     * Converts the tracked files into a flat object where keys are relative
+     * paths (without extensions) and values are absolute file paths.
+     *
+     * @param options - Optional transformation functions for keys and values
+     * @returns Object with file mappings
+     */
+    asList(options?: {
+        transformKey?: (key: string) => string;
+        transformValue?: (filePath: string) => string;
+    }): {
+        [key: string]: string;
+    };
+    /**
+     * Returns the files as a nested tree structure
+     *
+     * Converts the tracked files into a hierarchical object structure that
+     * mirrors the directory structure of the source files.
+     *
+     * @param options - Optional transformation functions for keys and values
+     * @returns Nested object representing the file tree
+     */
+    asTree(options?: {
+        transformKey?: (key: string) => string;
+        transformValue?: (filePath: string, key: string) => string;
+    }): RecursiveFileTree;
+    /**
+     * Add a new file to the virtual file system. File is only added when it
+     * matches the pre-defined filters.
+     *
+     * @param filePath - Absolute path of the file to add
+     * @returns True if the file was added, false if it doesn't match filters
+     */
+    add(filePath: string): boolean;
+    /**
+     * Remove a file from the virtual file system
+     *
+     * @param filePath - Absolute path of the file to remove
+     * @returns True if the file was removed, false if it wasn't tracked
+     */
+    remove(filePath: string): boolean;
+    /**
+     * Returns the file contents as AST-grep node and caches it
+     * forever. Use the "invalidate" method to remove it from the cache.
+     *
+     * This method reads the file content, parses it into an AST using ast-grep,
+     * and caches the result for future requests to improve performance.
+     *
+     * @param filePath - The absolute path to the file to parse
+     * @returns Promise resolving to the AST-grep node
+     */
+    get(filePath: string): Promise<SgNode>;
+    /**
+     * Invalidates AST cache for a single file or all files
+     *
+     * Use this method when files have been modified to ensure fresh
+     * AST parsing on subsequent get() calls.
+     *
+     * @param filePath - Optional file path to clear. If omitted, clears entire cache
+     */
+    invalidate(filePath?: string): void;
+    /**
+     * Clear all scanned files from memory
+     *
+     * Removes all tracked files from the internal file list, effectively
+     * resetting the virtual file system.
+     */
+    clear(): void;
+}