@adonisjs/assembler 8.0.0-next.5 → 8.0.0-next.7

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

@@ -1,3 +1,16 @@
+/**
+ * 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';

package/build/src/utils.d.ts

@@ -1,16 +1,30 @@
 import Hooks from '@poppinss/hooks';
 import type tsStatic from 'typescript';
 import { type ChokidarOptions } from 'chokidar';
-import { type UnWrapLazyImport } from '@poppinss/utils/types';
 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.
+ *
+ * @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;
 /**
  * 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[];
@@ -28,6 +42,13 @@ export declare function runNode(cwd: string | URL, options: RunScriptOptions): i
 }>;
 /**
  * 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;
@@ -42,51 +63,105 @@ export declare function run(cwd: string | URL, options: Omit<RunScriptOptions, '
     };
 }>;
 /**
- * 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) => 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;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@adonisjs/assembler",
   "description": "Provides utilities to run AdonisJS development server and build project for production",
-  "version": "8.0.0-next.5",
+  "version": "8.0.0-next.7",
   "engines": {
     "node": ">=24.0.0"
   },
@@ -19,6 +19,8 @@
     ".": "./build/index.js",
     "./code_transformer": "./build/src/code_transformer/main.js",
     "./routes_scanner": "./build/src/code_scanners/routes_scanner/main.js",
+    "./index_generator": "./build/src/index_generator/main.js",
+    "./helpers": "./build/src/helpers.js",
     "./types": "./build/src/types/main.js"
   },
   "scripts": {
@@ -61,7 +63,7 @@
     "typescript": "^5.9.2"
   },
   "dependencies": {
-    "@adonisjs/env": "^6.2.0",
+    "@adonisjs/env": "^7.0.0-next.1",
     "@antfu/install-pkg": "^1.1.0",
     "@ast-grep/napi": "^0.39.4",
     "@poppinss/cliui": "^6.4.4",
@@ -71,10 +73,11 @@
     "dedent": "^1.6.0",
     "execa": "^9.6.0",
     "fast-glob": "^3.3.3",
+    "fdir": "^6.5.0",
     "get-port": "^7.1.0",
     "junk": "^4.0.1",
     "open": "^10.2.0",
-    "parse-imports": "^2.2.1",
+    "parse-imports": "^3.0.0",
     "picomatch": "^4.0.3",
     "pretty-hrtime": "^1.0.3",
     "tmp-cache": "^1.1.0",
@@ -105,6 +108,9 @@
     "entry": [
       "./index.ts",
       "./src/types/main.ts",
+      "./src/helpers.ts",
+      "./src/code_scanners/routes_scanner/main.ts",
+      "./src/index_generator/main.ts",
       "./src/code_transformer/main.ts"
     ],
     "outDir": "./build",

package/build/chunk-RR4HCA4M.js

@@ -1,7 +0,0 @@
-// src/debug.ts
-import { debuglog } from "util";
-var debug_default = debuglog("adonisjs:assembler");
-
-export {
-  debug_default
-};

package/build/src/ast_file_system.d.ts

@@ -1,17 +0,0 @@
-import { type SgNode } from '@ast-grep/napi';
-/**
- * An abstraction around converting files to an AST and caching
- * them forever. The cache could be cleared manually.
- */
-export declare class AstFileSystem {
-    #private;
-    /**
-     * Returns the file contents as AST-grep node and caches it
-     * forever.
-     */
-    get(filePath: string): Promise<SgNode>;
-    /**
-     * Clear AST cache for a single file or all the files
-     */
-    clear(filePath?: string): void;
-}