@adonisjs/assembler 8.0.0 → 8.1.0

package/build/src/file_system.d.ts

@@ -37,7 +37,7 @@ export declare class FileSystem {
      *
      * Following patterns are always ignored
      *
-     * '.git/**', 'coverage/**', '.github/**'
+     * '.git/**', 'coverage/**', '.github/**', '.adonisjs/**', 'tmp/**', 'storage/**', 'build/**'
      */
     get excludes(): string[];
     /**

package/build/src/helpers.js

@@ -1,9 +1,37 @@
+import "../chunk-DF48asd8.js";
 import { parseImports } from "parse-imports";
+//#region src/helpers.ts
+/**
+* Finds an import reference inside a code snippet by analyzing the import statements
+* and matching against the provided import reference identifier.
+*
+* The function searches through all import statements in the code and matches
+* against default, namespace, or named imports based on the import reference.
+*
+* @param code - The code snippet to search for imports
+* @param importReference - The import reference identifier to find (can include dot notation)
+* @returns Promise that resolves to an Import object or null if not found
+*
+* @example
+* const importInfo = await findImport(code, 'validateUser')
+* if (importInfo) {
+*   console.log(importInfo.specifier) // '@/validators/user'
+* }
+*/
 async function findImport(code, importReference) {
 	const importIdentifier = importReference.split(".")[0];
 	for (const $import of await parseImports(code, {})) {
+		/**
+		* An import without any clause
+		*/
 		if (!$import.importClause) continue;
+		/**
+		* An import without any clause
+		*/
 		if (!$import.moduleSpecifier.value) continue;
+		/**
+		* Import identifier matches a default import
+		*/
 		if ($import.importClause.default === importIdentifier) return {
 			specifier: $import.moduleSpecifier.value,
 			isConstant: $import.moduleSpecifier.isConstant,
@@ -12,6 +40,9 @@ async function findImport(code, importReference) {
 				value: importIdentifier
 			}
 		};
+		/**
+		* Import identifier matches a namespace import
+		*/
 		if ($import.importClause.namespace === importIdentifier) return {
 			specifier: $import.moduleSpecifier.value,
 			isConstant: $import.moduleSpecifier.isConstant,
@@ -23,6 +54,9 @@ async function findImport(code, importReference) {
 		const namedImport = $import.importClause.named.find(({ binding }) => {
 			return binding === importIdentifier;
 		});
+		/**
+		* Import identifier matches a named import
+		*/
 		if (namedImport) return {
 			specifier: $import.moduleSpecifier.value,
 			isConstant: $import.moduleSpecifier.isConstant,
@@ -35,12 +69,64 @@ async function findImport(code, importReference) {
 	}
 	return null;
 }
+/**
+* Returns a node that represents a TypeScript class or null
+* when unable to find the class.
+*
+* This function searches for class declarations within the provided AST node
+* using ast-grep's pattern matching capabilities.
+*
+* @param node - The AST node to search within for class declarations
+* @returns The SgNode representing the class or null if not found
+*
+* @example
+* const classNode = inspectClass(rootNode)
+* if (classNode) {
+*   console.log('Found class:', classNode.text())
+* }
+*/
 function inspectClass(node) {
 	return node.find({ rule: { kind: "class_declaration" } });
 }
+/**
+* Returns an array of SgNodes for class methods. The input node
+* must represent a class.
+*
+* This function finds all method definitions within a class node,
+* including both regular methods and static methods.
+*
+* @param node - The AST node representing a class to search for methods
+* @returns Array of SgNodes representing method definitions within the class
+*
+* @example
+* const classNode = inspectClass(rootNode)
+* if (classNode) {
+*   const methods = inspectClassMethods(classNode)
+*   methods.forEach(method => console.log('Method:', method.text()))
+* }
+*/
 function inspectClassMethods(node) {
 	return node.findAll({ rule: { kind: "method_definition" } });
 }
+/**
+* Converts an SgNode to plain text by removing whitespaces,
+* indentation and comments in between. Tested with the following
+* children nodes only.
+*
+* - MemberExpression
+* - Identifier
+*
+* This function recursively traverses the AST node and extracts only
+* the meaningful text content without any formatting or whitespace.
+*
+* @param node - The AST node to convert to plain text
+* @returns String representation of the node without formatting
+*
+* @example
+* const memberExpression = node.find({ rule: { kind: 'member_expression' } })
+* const plainText = nodeToPlainText(memberExpression)
+* console.log(plainText) // 'user.validate'
+*/
 function nodeToPlainText(node) {
 	let out = [];
 	function toText(one) {
@@ -51,6 +137,26 @@ function nodeToPlainText(node) {
 	toText(node);
 	return out.join("");
 }
+/**
+* Inspects arguments for one or more method calls. If you want to
+* scope the search within a specific context, then make sure to
+* first narrow down the AST and pass a specific SgNode.
+*
+* For example: In case of validators, we will first find the Controller
+* method for which we want the validation method calls.
+*
+* This function searches for call expressions that match the provided method
+* names and returns their argument nodes for further analysis.
+*
+* @param node - The AST node to search within for method calls
+* @param methodCalls - Array of method call names to search for (supports dot notation)
+* @returns Array of SgNodes representing the arguments of matching method calls
+*
+* @example
+* const controllerMethod = classNode.find({ rule: { kind: 'method_definition' } })
+* const validatorArgs = inspectMethodArguments(controllerMethod, ['validate', 'request.validate'])
+* validatorArgs.forEach(arg => console.log('Validator argument:', arg.text()))
+*/
 function inspectMethodArguments(node, methodCalls) {
 	return node.findAll({ rule: { any: methodCalls.map((methodCall) => {
 		return { pattern: {
@@ -61,12 +167,39 @@ function inspectMethodArguments(node, methodCalls) {
 		return matchingExpression.findAll({ rule: { kind: "arguments" } });
 	});
 }
+/**
+* Inspect the validator direct usage code snippets. A member expression
+* calling the ".validate" method is considered as direct usage of
+* the validator.
+*
+* This function specifically looks for patterns where validators are called
+* directly with the `.validate()` method, which is common in AdonisJS applications.
+*
+* @param node - The AST node to search within for validator direct usage
+* @returns Array of SgNodes representing validator expressions that call validate method
+*
+* @example
+* const methodNode = classNode.find({ rule: { kind: 'method_definition' } })
+* const validators = searchValidatorDirectUsage(methodNode)
+* validators.forEach(validator => {
+*   console.log('Direct validator usage:', nodeToPlainText(validator))
+* })
+*/
 function searchValidatorDirectUsage(node) {
 	return node.findAll({ rule: { pattern: {
 		context: "$$$VALIDATOR.validate($$$)",
 		selector: "call_expression"
 	} } }).flatMap((expression) => {
+		/**
+		* Since we capture all "$$$.validate" calls, the first node
+		* within the call expression will be a member expression
+		* and its property identifier will be "validate".
+		*
+		* What we need is the text of this member expression without the
+		* comments
+		*/
 		return expression.getMultipleMatches("VALIDATOR");
 	});
 }
+//#endregion
 export { findImport, inspectClass, inspectClassMethods, inspectMethodArguments, nodeToPlainText, searchValidatorDirectUsage };

package/build/src/index_generator/main.js

@@ -1,29 +1,4 @@
-import "../../virtual_file_system-bGeoWsK-.js";
-import { t as IndexGeneratorSource } from "../../source-dVeugJ0e.js";
-var IndexGenerator = class {
-	appRoot;
-	#sources = {};
-	#cliLogger;
-	constructor(appRoot, cliLogger) {
-		this.appRoot = appRoot;
-		this.#cliLogger = cliLogger;
-	}
-	add(name, config) {
-		this.#sources[name] = new IndexGeneratorSource(name, this.appRoot, this.#cliLogger, config);
-		return this;
-	}
-	async addFile(filePath) {
-		const sources = Object.values(this.#sources);
-		for (let source of sources) await source.addFile(filePath);
-	}
-	async removeFile(filePath) {
-		const sources = Object.values(this.#sources);
-		for (let source of sources) await source.removeFile(filePath);
-	}
-	async generate() {
-		const sources = Object.values(this.#sources);
-		for (let source of sources) await source.generate();
-		if (sources.length) this.#cliLogger.info(`codegen: created ${sources.length} file(s)`);
-	}
-};
+import "../../chunk-DF48asd8.js";
+import "../../virtual_file_system-dzfXNwEp.js";
+import { t as IndexGenerator } from "../../main-INOi9swJ.js";
 export { IndexGenerator };

package/build/src/types/main.js

@@ -1 +1,2 @@
+import "../../chunk-DF48asd8.js";
 export {};

package/build/src/utils.d.ts

@@ -40,7 +40,6 @@ export declare function runNode(cwd: string | URL, options: RunScriptOptions): i
     buffer: false;
     stdio: "pipe" | "inherit";
     env: {
-        TZ?: string | undefined;
         FORCE_COLOR?: string | undefined;
     };
 }>;
@@ -62,7 +61,6 @@ export declare function run(cwd: string | URL, options: Omit<RunScriptOptions, '
     buffer: false;
     stdio: "pipe" | "inherit";
     env: {
-        TZ?: string | undefined;
         FORCE_COLOR?: string | undefined;
     };
 }>;

package/build/{virtual_file_system-bGeoWsK-.js → virtual_file_system-dzfXNwEp.js}

@@ -19,8 +19,40 @@ import { fdir } from "fdir";
 import lodash from "@poppinss/utils/lodash";
 import { Lang, parse } from "@ast-grep/napi";
 import picomatch from "picomatch";
+//#region src/debug.ts
+/**
+* Debug logger for the AdonisJS assembler package.
+*
+* This debug instance is configured to log messages under the 'adonisjs:assembler'
+* namespace. Debug messages are only shown when the NODE_DEBUG environment variable
+* includes 'adonisjs:assembler'.
+*
+* @example
+* // Enable debug logging
+* // NODE_DEBUG=adonisjs:assembler node ace serve
+* debug('Starting development server...')
+*/
 var debug_default = debuglog("adonisjs:assembler");
+//#endregion
+//#region src/utils.ts
+/**
+* Default set of args to pass in order to run TypeScript
+* source. Used by "run" and "runNode" scripts
+*/
 const DEFAULT_NODE_ARGS = ["--import=@poppinss/ts-exec", "--enable-source-maps"];
+/**
+* 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
+*/
 function parseConfig(cwd, ts) {
 	const cwdPath = typeof cwd === "string" ? cwd : fileURLToPath(cwd);
 	const configFile = join$1(cwdPath, "tsconfig.json");
@@ -70,6 +102,17 @@ function readTsConfig(cwd) {
 		return 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
+*/
 function runNode(cwd, options) {
 	return execaNode(options.script, options.scriptArgs, {
 		nodeOptions: DEFAULT_NODE_ARGS.concat(options.nodeArgs),
@@ -86,6 +129,16 @@ function runNode(cwd, options) {
 		}
 	});
 }
+/**
+* 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
+*/
 function run(cwd, options) {
 	return execa(options.script, options.scriptArgs, {
 		preferLocal: true,
@@ -100,24 +153,81 @@ function run(cwd, options) {
 		}
 	});
 }
+/**
+* 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
+*/
 function watch(options) {
 	return chokidar.watch(["."], options);
 }
+/**
+* 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:
+*
+* - 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
+*/
 async function getPort(cwd) {
+	/**
+	* Use existing port if exists
+	*/
 	if (process.env.PORT) return getRandomPort({ port: Number(process.env.PORT) });
+	/**
+	* Loop over files and use the port from their contents. Stops
+	* after first match
+	*/
 	const files = await new EnvLoader(cwd).load();
 	for (let file of files) {
 		const envVariables = await new EnvParser(file.contents, cwd).parse();
 		if (envVariables.PORT) return getRandomPort({ port: Number(envVariables.PORT) });
 	}
+	/**
+	* Use 3333 as the port
+	*/
 	return getRandomPort({ port: 3333 });
 }
+/**
+* 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
+*/
 async function copyFiles(files, cwd, outDir) {
+	/**
+	* Looping over files and create a new collection with paths
+	* and glob patterns
+	*/
 	const { paths, patterns } = files.reduce((result, file) => {
+		/**
+		* If file is a glob pattern, then push it to patterns
+		*/
 		if (fastGlob.isDynamicPattern(file)) {
 			result.patterns.push(file);
 			return result;
 		}
+		/**
+		* Otherwise, check if file exists and push it to paths to copy
+		*/
 		if (existsSync(join$1(cwd, file))) result.paths.push(file);
 		return result;
 	}, {
@@ -125,12 +235,19 @@ async function copyFiles(files, cwd, outDir) {
 		paths: []
 	});
 	debug_default("copyFiles inputs: %O, paths: %O, patterns: %O", files, paths, patterns);
+	/**
+	* Getting list of relative paths from glob patterns
+	*/
 	const filePaths = paths.concat(await fastGlob(patterns, {
 		cwd,
 		dot: true
 	})).filter((file) => {
 		return !isJunk(basename(file));
 	});
+	/**
+	* Finally copy files to the destination by keeping the same
+	* directory structure and ignoring junk files
+	*/
 	debug_default("copying files %O to destination \"%s\"", filePaths, outDir);
 	const copyPromises = filePaths.map(async (file) => {
 		const src = isAbsolute(file) ? file : join$1(cwd, file);
@@ -140,6 +257,17 @@ async function copyFiles(files, cwd, outDir) {
 	});
 	return await Promise.all(copyPromises);
 }
+/**
+* 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
+*/
 function memoize(fn, maxKeys) {
 	const cache = new Cache({ max: maxKeys });
 	return (input, ...args) => {
@@ -147,9 +275,28 @@ function memoize(fn, maxKeys) {
 		return fn(input, ...args);
 	};
 }
+/**
+* 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
+*/
 function isRelative(pathValue) {
 	return pathValue.startsWith("./") || pathValue.startsWith("../");
 }
+/**
+* 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
+*/
 async function loadHooks(rcFileHooks, names) {
 	const groups = names.map((name) => {
 		return {
@@ -162,6 +309,18 @@ async function loadHooks(rcFileHooks, names) {
 	else hooks.add(group, await importDefault(item));
 	return hooks;
 }
+/**
+* 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
+*/
 function throttle(fn, name) {
 	name = name || "throttled";
 	let isBusy = false;
@@ -187,28 +346,83 @@ function throttle(fn, name) {
 	}
 	return throttled;
 }
+/**
+* Removes the file extension from a file path
+*
+* @param filePath - The file path with extension
+* @returns The file path without extension
+*/
 function removeExtension(filePath) {
 	return filePath.substring(0, filePath.lastIndexOf("."));
 }
+//#endregion
+//#region src/virtual_file_system.ts
 const BYPASS_FN = (input) => input;
 const DEFAULT_GLOB = [
 	"**/!(*.d).ts",
 	"**/*.tsx",
 	"**/*.js"
 ];
+/**
+* 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')
+*/
 var VirtualFileSystem = class {
+	/**
+	* Absolute path to the source directory from where to read the files.
+	* Additionally, a glob pattern or a filter could be specified to
+	* narrow down the scanned files list.
+	*/
 	#source;
+	/**
+	* Filesystem options
+	*/
 	#options;
+	/**
+	* Files collected from the initial scan with pre-computed relative paths
+	*/
 	#files = /* @__PURE__ */ new Map();
+	/**
+	* LRU cache storing parsed AST nodes by file path with size limit
+	*/
 	#astCache = new Cache({ max: 60 });
+	/**
+	* Matcher is defined when glob is defined via the options
+	*/
 	#matcher;
+	/**
+	* Picomatch options used for file pattern matching
+	*/
 	#picoMatchOptions;
+	/**
+	* Create a new VirtualFileSystem instance
+	*
+	* @param source - Absolute path to the source directory
+	* @param options - Optional configuration for file filtering and processing
+	*/
 	constructor(source, options) {
 		this.#source = source;
 		this.#options = options ?? {};
 		this.#picoMatchOptions = { cwd: this.#source };
 		this.#matcher = picomatch(this.#options.glob ?? DEFAULT_GLOB, this.#picoMatchOptions);
 	}
+	/**
+	* 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.
+	*/
 	async scan() {
 		debug_default("fetching entities from source \"%s\"", this.#source);
 		const crawler = new fdir().globWithOptions(this.#options.glob ?? DEFAULT_GLOB, this.#picoMatchOptions).withFullPaths();
@@ -223,11 +437,37 @@ var VirtualFileSystem = class {
 			this.#files.set(filePath, relativePath);
 		}
 	}
+	/**
+	* 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) {
+		/**
+		* File is already tracked as part of the initial scan
+		*/
 		if (this.#files.has(filePath)) return true;
+		/**
+		* Return false if file is not within the source dir
+		*/
 		if (!filePath.startsWith(this.#source)) return false;
+		/**
+		* If a match exists, then check if the file matches via the
+		* matcher test
+		*/
 		return this.#matcher(filePath);
 	}
+	/**
+	* 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) {
 		const list = {};
 		const transformKey = options?.transformKey ?? BYPASS_FN;
@@ -235,6 +475,15 @@ var VirtualFileSystem = class {
 		for (const [filePath, relativePath] of this.#files) list[transformKey(relativePath)] = transformValue(filePath);
 		return list;
 	}
+	/**
+	* 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) {
 		const list = {};
 		const transformKey = options?.transformKey ?? BYPASS_FN;
@@ -245,6 +494,13 @@ var VirtualFileSystem = class {
 		}
 		return list;
 	}
+	/**
+	* 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) {
 		if (this.has(filePath)) {
 			debug_default("adding new \"%s\" file to the virtual file system", filePath);
@@ -254,10 +510,26 @@ var VirtualFileSystem = class {
 		}
 		return false;
 	}
+	/**
+	* 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) {
 		debug_default("removing \"%s\" file from virtual file system", filePath);
 		return this.#files.delete(filePath);
 	}
+	/**
+	* 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
+	*/
 	async get(filePath) {
 		const cached = this.#astCache.get(filePath);
 		if (cached) {
@@ -269,6 +541,14 @@ var VirtualFileSystem = class {
 		this.#astCache.set(filePath, parse(Lang.TypeScript, fileContents).root());
 		return this.#astCache.get(filePath);
 	}
+	/**
+	* 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) {
 		if (filePath) {
 			debug_default("invalidate AST cache \"%s\"", filePath);
@@ -278,8 +558,15 @@ var VirtualFileSystem = class {
 			this.#astCache.clear();
 		}
 	}
+	/**
+	* Clear all scanned files from memory
+	*
+	* Removes all tracked files from the internal file list, effectively
+	* resetting the virtual file system.
+	*/
 	clear() {
 		this.#files.clear();
 	}
 };
+//#endregion
 export { loadHooks as a, readTsConfig as c, runNode as d, throttle as f, isRelative as i, removeExtension as l, debug_default as m, copyFiles as n, memoize as o, watch as p, getPort as r, parseConfig as s, VirtualFileSystem as t, run as u };