@adonisjs/assembler 8.0.0 → 8.1.0

package/build/main-DEUzrVBq.js

@@ -0,0 +1,565 @@
+import { i as isRelative, m as debug_default, t as VirtualFileSystem } from "./virtual_file_system-dzfXNwEp.js";
+import { findImport, inspectClass, inspectClassMethods, inspectMethodArguments, nodeToPlainText, searchValidatorDirectUsage } from "./src/helpers.js";
+import { cliui } from "@poppinss/cliui";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import string from "@poppinss/utils/string";
+import { join, relative } from "node:path";
+import StringBuilder from "@poppinss/utils/string_builder";
+import { parseImports } from "parse-imports";
+import { resolve } from "import-meta-resolve";
+//#region src/paths_resolver.ts
+/**
+* Encapsulates the API to resolve import specifiers with the ability
+* to define custom resolver functions.
+*
+* The PathsResolver provides a caching mechanism to avoid resolving the same
+* specifier multiple times and supports custom resolvers for handling
+* special import patterns like path aliases.
+*
+* @example
+* const resolver = new PathsResolver()
+* resolver.use((specifier) => '/custom/path/' + specifier)
+* const resolved = resolver.resolve('#app/models/user')
+*/
+var PathsResolver = class {
+	/**
+	* The root of the application from where we will resolve
+	* paths.
+	*/
+	#appRoot;
+	/**
+	* Cache of resolved paths to avoid resolving the same specifier multiple times
+	*/
+	#resolvedPaths = {};
+	/**
+	* The resolver function used to resolve import specifiers
+	*/
+	#resolver = (specifier, parentPath) => resolve(specifier, parentPath);
+	constructor(appRoot) {
+		this.#appRoot = pathToFileURL(join(appRoot, "index.js")).href;
+	}
+	/**
+	* 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, rewriteAliasImportExtension = false) {
+		if (isRelative(specifier)) throw new Error("Cannot resolve relative paths using PathsResolver");
+		const cacheKey = specifier;
+		const cached = this.#resolvedPaths[cacheKey];
+		if (cached) return cached;
+		/**
+		* Currently the PathsResolver relies on a non-standard way of resolving
+		* absolute paths or paths with subpath imports. Because of which, the
+		* on-disk file could be TypeScript, while the resolved filepath is
+		* JavaScript.
+		*
+		* To overcome this limitation, we rewrite the file extension to ".ts" when
+		* the import specifier starts with a "#".
+		*/
+		let resolvedPath = fileURLToPath(this.#resolver(specifier, this.#appRoot));
+		if (rewriteAliasImportExtension && specifier.startsWith("#") && resolvedPath.endsWith(".js")) resolvedPath = resolvedPath.replace(/\.js$/, ".ts");
+		this.#resolvedPaths[cacheKey] = resolvedPath;
+		return this.#resolvedPaths[cacheKey];
+	}
+};
+//#endregion
+//#region src/code_scanners/routes_scanner/validator_extractor.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
+*/
+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;
+	}
+	/**
+	* Inspect class methods and find the scope down to the method
+	* we are currently inspecting
+	*/
+	const method = inspectClassMethods(controllerClass).find((methodNode) => {
+		return methodNode.find({ rule: { kind: "property_identifier" } })?.text() === controller.method;
+	});
+	if (!method) {
+		debug_default(`Unable to find "%s" method in "%s"`, controller.method, controller.import.specifier);
+		return;
+	}
+	/**
+	* Inspect validators via "request.validateUsing" and "vine.validate"
+	* method calls.
+	*/
+	const validationCalls = inspectMethodArguments(method, [
+		"request.validateUsing",
+		"request.tryValidateUsing",
+		"$CTX.request.validateUsing",
+		"$CTX.request.tryValidateUsing",
+		"vine.validate",
+		"vine.tryValidate"
+	]).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)));
+	/**
+	* Unable to find any validation calls, or the first argument of the
+	* validation call was not a member_expression or an identifier.
+	*/
+	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);
+	return (await Promise.all(validationCalls.map(async (validationCall) => {
+		if (validationCall.split(".")[0] === 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, fileURLToPath(new URL(importCall.specifier, controllerURL)))) : importCall.specifier,
+				type: importCall.clause.type,
+				value: importCall.clause.value
+			}
+		};
+	}))).filter((value) => !!value);
+}
+//#endregion
+//#region src/code_scanners/routes_scanner/main.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()
+*/
+var RoutesScanner = class {
+	/**
+	* Optional filter function to selectively include routes during scanning.
+	* When defined, only routes for which this function returns true will be processed.
+	*/
+	#filter;
+	/**
+	* 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;
+	/**
+	* The rules to apply when scanning routes
+	*/
+	rules = {
+		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;
+		this.pathsResolver = new PathsResolver(appRoot);
+		rulesCollection.forEach((rules) => {
+			Object.assign(this.rules.request, rules.request);
+			Object.assign(this.rules.response, rules.response);
+		});
+	}
+	/**
+	* Determines if a route should be skipped based on the filter function.
+	*
+	* @param route - The route to check
+	*/
+	#shouldSkipRoute(route) {
+		if (this.#filter) return !this.#filter(route);
+		return false;
+	}
+	/**
+	* 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;
+		return {
+			type: 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(`InferInput<(typeof import('${validator.import.specifier}')${validatorExport})${namespace}>`);
+				return result;
+			}, []).join("|"),
+			imports: [`import { InferInput } from '@vinejs/vine/types'`]
+		};
+	}
+	/**
+	* Inspects the controller reference and fetches its import specifier
+	* and the controller name from it.
+	*
+	* @param importExpression - The import expression to parse (e.g., "import('#controllers/users_controller')")
+	* @param method - The controller method name (defaults to 'handle' if not provided)
+	*/
+	async #inspectControllerSpecifier(importExpression, method) {
+		const importedModule = [...await parseImports(importExpression)].find(($import) => $import.isDynamicImport && $import.moduleSpecifier.value);
+		/**
+		* The provided expression was not a lazy load import.
+		*/
+		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: string.toUnixSlash(this.pathsResolver.resolve(specifier, true)),
+			import: {
+				specifier,
+				type: "default",
+				value: name
+			}
+		};
+	}
+	/**
+	* Defines the response type for the route by calling the custom compute function
+	* or falling back to inferring the return type from the controller method.
+	*
+	* @param route - The scanned route to set response type for
+	* @param controller - The controller containing the route handler
+	*/
+	async #setResponse(route, controller) {
+		route.response = await this.#computeResponseTypes?.(route, controller, this) ?? {
+			type: `ReturnType<import('${controller.import.specifier}').default['${controller.method}']>`,
+			imports: []
+		};
+		debug_default("computed route \"%s\" response %O", route.name, route.response);
+	}
+	/**
+	* Defines the request type for the route by extracting validators and computing
+	* the request type from them or using a custom compute function.
+	*
+	* @param route - The scanned route to set request type for
+	* @param controller - The controller containing the route handler
+	* @param vfs - Virtual file system for analyzing controller code
+	*/
+	async #setRequest(route, controller, vfs) {
+		route.validators = await this.#extractValidators?.(route, controller, this) ?? await extractValidators(this.#appRoot, vfs, controller);
+		debug_default("computed route \"%s\" validators %O", route.name, route.validators);
+		route.request = await this.#computeRequestTypes?.(route, controller, this) ?? this.#prepareRequestTypes(route);
+		debug_default("computed route \"%s\" request input %O", route.name, route.request);
+	}
+	/**
+	* Scans a route that is not using a controller (inline route handler).
+	* For routes without controllers, only rules-based request/response types are available.
+	*
+	* @param route - The route to process
+	*/
+	#processRouteWithoutController(route) {
+		if (!route.name) {
+			debug_default(`skipping route "%s" as it does not have a name`, route.pattern);
+			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]
+		};
+		debug_default("scanned route without controller %O", scannedRoute);
+		this.#scannedRoutes.push(scannedRoute);
+	}
+	/**
+	* Scans a route that is using a controller reference.
+	* Extracts controller information, validators, and type information.
+	*
+	* @param route - The route with a controller handler
+	* @param vfs - Virtual file system for analyzing controller code
+	*/
+	async #processRouteWithController(route, vfs) {
+		/**
+		* Process without controller, when importExpression is missing. This is
+		* the case where someone imports the controllers and uses it by
+		* reference
+		*/
+		if (!route.handler || !route.handler.importExpression) return this.#processRouteWithoutController(route);
+		/**
+		* Inspect controller by parsing its import expression
+		*/
+		const controller = await this.#inspectControllerSpecifier(route.handler.importExpression, route.handler.method);
+		/**
+		* Process route without a controller when we are not able to extract the import
+		* path of the controller, because the import path is needed to further extract
+		* request and response types.
+		*/
+		if (!controller) return this.#processRouteWithoutController(route);
+		debug_default("processing route \"%s\" with inspected controller %O", route.name, controller);
+		/**
+		* Converting controller name and its method to snake_case to create a unique
+		* name for the route. There could be chances where one controller+method
+		* combination is bound to multiple routes.
+		*/
+		route.name = route.name ?? new StringBuilder(controller.name).removeSuffix("Controller").snakeCase().suffix(`.${string.snakeCase(controller.method)}`).toString();
+		/**
+		* Skip route when its name is within the array of
+		* skip routes
+		*/
+		if (this.#shouldSkipRoute(route)) return;
+		/**
+		* Creating a scanned route and tracking it. We will inspect the response
+		* and request if these values are not provided via rules.
+		*/
+		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],
+			controller
+		};
+		debug_default("scanned route %O", scannedRoute);
+		this.#scannedRoutes.push(scannedRoute);
+		/**
+		* Track route next to the controller absolute path. This way we will be
+		* able to invalidate request types everytime the controller is modified.
+		*/
+		if (!scannedRoute.request || !scannedRoute.response) {
+			debug_default("tracking controller for rescanning %O", scannedRoute);
+			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);
+		}
+	}
+	/**
+	* Processes a given route list item and scans it to extract
+	* the controller, request and response types.
+	*
+	* @param route - The route to process
+	* @param vfs - Virtual file system for analyzing controller code
+	*/
+	async #processRoute(route, vfs) {
+		/**
+		* Skip route when it has a name and also part of
+		* skip array
+		*/
+		if (route.name && this.#shouldSkipRoute(route)) {
+			debug_default("route skipped route: %O, rules: %O", route, this.rules);
+			return;
+		}
+		/**
+		* Routes without a controller reference cannot have types for the request
+		* and response (unless provided via rules)
+		*/
+		if (typeof route.handler === "function") {
+			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 || !controllerRoutes.length) {
+			debug_default("\"%s\" controllers is not part of scanned controllers %O", controllerPath, this.#controllerRoutes);
+			return false;
+		}
+		for (let scannedRoute of controllerRoutes) if (scannedRoute.controller) {
+			debug_default("invalidating route %O", scannedRoute);
+			const vfs = new VirtualFileSystem(this.#appRoot);
+			await this.#setResponse(scannedRoute, scannedRoute.controller);
+			await this.#setRequest(scannedRoute, scannedRoute.controller, vfs);
+		}
+		return true;
+	}
+	/**
+	* Sets a filter function to selectively include routes during scanning.
+	*
+	* @param filterFn - Function that returns true for routes to include
+	* @returns This RoutesScanner instance for method chaining
+	*
+	* @example
+	* scanner.filter((route) => {
+	*   return route.pattern.startsWith('/api')
+	* })
+	*/
+	filter(filterFn) {
+		this.#filter = filterFn;
+		return this;
+	}
+	/**
+	* 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 (const route of routes) await this.#processRoute(route, vfs);
+		vfs.invalidate();
+	}
+};
+//#endregion
+export { RoutesScanner as t };