@adonisjs/assembler 8.0.0 → 8.0.1

package/build/src/code_transformer/main.js

@@ -1,18 +1,43 @@
-import { t as CodemodException } from "../../codemod_exception-CzQgXAAf.js";
+import "../../chunk-DF48asd8.js";
+import { t as CodemodException } from "../../codemod_exception-BMNJZ0i1.js";
 import { fileURLToPath } from "node:url";
 import { detectPackageManager, installPackage } from "@antfu/install-pkg";
 import { ImportsBag } from "@poppinss/utils";
 import { join } from "node:path";
 import { Node, Project, QuoteKind, SyntaxKind } from "ts-morph";
+//#region src/code_transformer/rc_file_transformer.ts
 const ALLOWED_ENVIRONMENTS = [
 	"web",
 	"console",
 	"test",
 	"repl"
 ];
+/**
+* RcFileTransformer is used to transform the `adonisrc.ts` file
+* for adding new commands, providers, meta files etc.
+*
+* This class provides a fluent API for modifying the AdonisJS configuration
+* file (adonisrc.ts) by adding various types of entries like providers,
+* commands, preloaded files, meta files, and test suites.
+*
+* @example
+* const transformer = new RcFileTransformer(cwd, project)
+* transformer.addProvider('#providers/app_provider')
+* transformer.addCommand('#commands/make_controller')
+* await transformer.save()
+*/
 var RcFileTransformer = class {
+	/**
+	* The current working directory URL
+	*/
 	#cwd;
+	/**
+	* The TsMorph project instance
+	*/
 	#project;
+	/**
+	* Settings to use when persisting files
+	*/
 	#editorSettings = {
 		indentSize: 2,
 		convertTabsToSpaces: true,
@@ -21,10 +46,22 @@ var RcFileTransformer = class {
 		indentStyle: 2,
 		semicolons: "remove"
 	};
+	/**
+	* Create a new RcFileTransformer instance
+	*
+	* @param cwd - The current working directory URL
+	* @param project - The TsMorph project instance
+	*/
 	constructor(cwd, project) {
 		this.#cwd = cwd;
 		this.#project = project;
 	}
+	/**
+	* Get the `adonisrc.ts` source file
+	*
+	* @returns The adonisrc.ts source file
+	* @throws CodemodException if the file cannot be found
+	*/
 	#getRcFileOrThrow() {
 		const filePath = "adonisrc.ts";
 		const rcFileUrl = fileURLToPath(new URL(`./${filePath}`, this.#cwd));
@@ -36,10 +73,23 @@ export default defineConfig({
 })`);
 		return file;
 	}
+	/**
+	* Check if environments array has a subset of available environments
+	*
+	* @param environments - Optional array of environment names
+	* @returns True if the provided environments are a subset of available ones
+	*/
 	#isInSpecificEnvironment(environments) {
 		if (!environments) return false;
 		return !!ALLOWED_ENVIRONMENTS.find((env) => !environments.includes(env));
 	}
+	/**
+	* Locate the `defineConfig` call inside the `adonisrc.ts` file
+	*
+	* @param file - The source file to search in
+	* @returns The defineConfig call expression
+	* @throws CodemodException if defineConfig call cannot be found
+	*/
 	#locateDefineConfigCallOrThrow(file) {
 		const call = file.getDescendantsOfKind(SyntaxKind.CallExpression).find((statement) => statement.getExpression().getText() === "defineConfig");
 		if (!call) throw CodemodException.invalidRcFile("adonisrc.ts", `import { defineConfig } from '@adonisjs/core/app'
@@ -49,9 +99,24 @@ export default defineConfig({
 })`, "Could not locate the defineConfig call.");
 		return call;
 	}
+	/**
+	* Return the ObjectLiteralExpression of the defineConfig call
+	*
+	* @param defineConfigCall - The defineConfig call expression
+	* @returns The configuration object literal expression
+	* @throws Error if the object literal cannot be found
+	*/
 	#getDefineConfigObjectOrThrow(defineConfigCall) {
 		return defineConfigCall.getArguments()[0].asKindOrThrow(SyntaxKind.ObjectLiteralExpression);
 	}
+	/**
+	* Check if the defineConfig() call has the property assignment
+	* inside it or not. If not, it will create one and return it.
+	*
+	* @param propertyName - The name of the property to find or create
+	* @param initializer - The initial value if the property needs to be created
+	* @returns The property assignment node
+	*/
 	#getPropertyAssignmentInDefineConfigCall(propertyName, initializer) {
 		const file = this.#getRcFileOrThrow();
 		const defineConfigCall = this.#locateDefineConfigCallOrThrow(file);
@@ -66,12 +131,35 @@ export default defineConfig({
 		}
 		return property;
 	}
+	/**
+	* Extract list of imported modules from an ArrayLiteralExpression
+	*
+	* It assumes that the array can have two types of elements:
+	*
+	* - Simple lazy imported modules: [() => import('path/to/file')]
+	* - Or an object entry: [{ file: () => import('path/to/file'), environment: ['web', 'console'] }]
+	*   where the `file` property is a lazy imported module.
+	*/
 	#extractModulesFromArray(array) {
 		return array.getElements().map((element) => {
+			/**
+			* Simple lazy imported module
+			*/
 			if (Node.isArrowFunction(element)) return element.getFirstDescendantByKindOrThrow(SyntaxKind.CallExpression).getFirstDescendantByKindOrThrow(SyntaxKind.StringLiteral).getLiteralValue();
+			/**
+			* Object entry
+			*/
 			if (Node.isObjectLiteralExpression(element)) return element.getPropertyOrThrow("file").getFirstDescendantByKindOrThrow(SyntaxKind.ArrowFunction).getFirstDescendantByKindOrThrow(SyntaxKind.CallExpression).getFirstDescendantByKindOrThrow(SyntaxKind.StringLiteral).getLiteralValue();
 		}).filter(Boolean);
 	}
+	/**
+	* Extract a specific property from an ArrayLiteralExpression
+	* that contains object entries.
+	*
+	* This function is mainly used for extractring the `pattern` property
+	* when adding a new meta files entry, or the `name` property when
+	* adding a new test suite.
+	*/
 	#extractPropertyFromArray(array, propertyName) {
 		return array.getElements().map((el) => {
 			if (!Node.isObjectLiteralExpression(el)) return;
@@ -80,6 +168,10 @@ export default defineConfig({
 			return nameProp.getInitializerIfKindOrThrow(SyntaxKind.StringLiteral).getLiteralValue();
 		}).filter(Boolean);
 	}
+	/**
+	* Build a new module entry for the preloads and providers array
+	* based upon the environments specified
+	*/
 	#buildNewModuleEntry(modulePath, environments) {
 		if (!this.#isInSpecificEnvironment(environments)) return `() => import('${modulePath}')`;
 		return `{
@@ -87,34 +179,83 @@ export default defineConfig({
       environment: [${environments?.map((env) => `'${env}'`).join(", ")}],
     }`;
 	}
+	/**
+	* Add a new command to the rcFile
+	*
+	* @param commandPath - The path to the command file
+	* @returns This RcFileTransformer instance for method chaining
+	*/
 	addCommand(commandPath) {
 		const commandsArray = this.#getPropertyAssignmentInDefineConfigCall("commands", "[]").getInitializerIfKindOrThrow(SyntaxKind.ArrayLiteralExpression);
 		const commandString = `() => import('${commandPath}')`;
+		/**
+		* If the command already exists, do nothing
+		*/
 		if (commandsArray.getElements().some((el) => el.getText() === commandString)) return this;
+		/**
+		* Add the command to the array
+		*/
 		commandsArray.addElement(commandString);
 		return this;
 	}
+	/**
+	* Add a new preloaded file to the rcFile
+	*
+	* @param modulePath - The path to the preload file
+	* @param environments - Optional array of environments where this preload should run
+	* @returns This RcFileTransformer instance for method chaining
+	*/
 	addPreloadFile(modulePath, environments) {
 		const preloadsArray = this.#getPropertyAssignmentInDefineConfigCall("preloads", "[]").getInitializerIfKindOrThrow(SyntaxKind.ArrayLiteralExpression);
 		if (this.#extractModulesFromArray(preloadsArray).includes(modulePath)) return this;
+		/**
+		* Add the preloaded file to the array
+		*/
 		preloadsArray.addElement(this.#buildNewModuleEntry(modulePath, environments));
 		return this;
 	}
+	/**
+	* Add a new provider to the rcFile
+	*
+	* @param providerPath - The path to the provider file
+	* @param environments - Optional array of environments where this provider should run
+	* @returns This RcFileTransformer instance for method chaining
+	*/
 	addProvider(providerPath, environments) {
 		const providersArray = this.#getPropertyAssignmentInDefineConfigCall("providers", "[]").getInitializerIfKindOrThrow(SyntaxKind.ArrayLiteralExpression);
 		if (this.#extractModulesFromArray(providersArray).includes(providerPath)) return this;
+		/**
+		* Add the provider to the array
+		*/
 		providersArray.addElement(this.#buildNewModuleEntry(providerPath, environments));
 		return this;
 	}
+	/**
+	* Add a new meta file to the rcFile
+	*
+	* @param globPattern - The glob pattern for the meta file
+	* @param reloadServer - Whether the server should reload when this file changes
+	* @returns This RcFileTransformer instance for method chaining
+	*/
 	addMetaFile(globPattern, reloadServer = false) {
 		const metaFilesArray = this.#getPropertyAssignmentInDefineConfigCall("metaFiles", "[]").getInitializerIfKindOrThrow(SyntaxKind.ArrayLiteralExpression);
 		if (this.#extractPropertyFromArray(metaFilesArray, "pattern").includes(globPattern)) return this;
+		/**
+		* Add the meta file to the array
+		*/
 		metaFilesArray.addElement(`{
         pattern: '${globPattern}',
         reloadServer: ${reloadServer},
       }`);
 		return this;
 	}
+	/**
+	* Set directory name and path in the directories configuration
+	*
+	* @param key - The directory key (e.g., 'controllers', 'models')
+	* @param value - The directory path
+	* @returns This RcFileTransformer instance for method chaining
+	*/
 	setDirectory(key, value) {
 		this.#getPropertyAssignmentInDefineConfigCall("directories", "{}").getInitializerIfKindOrThrow(SyntaxKind.ObjectLiteralExpression).addPropertyAssignment({
 			name: key,
@@ -122,6 +263,13 @@ export default defineConfig({
 		});
 		return this;
 	}
+	/**
+	* Set command alias in the command aliases configuration
+	*
+	* @param alias - The alias name
+	* @param command - The full command name
+	* @returns This RcFileTransformer instance for method chaining
+	*/
 	setCommandAlias(alias, command) {
 		this.#getPropertyAssignmentInDefineConfigCall("commandsAliases", "{}").getInitializerIfKindOrThrow(SyntaxKind.ObjectLiteralExpression).addPropertyAssignment({
 			name: alias,
@@ -129,9 +277,20 @@ export default defineConfig({
 		});
 		return this;
 	}
+	/**
+	* Add a new test suite to the rcFile
+	*
+	* @param suiteName - The name of the test suite
+	* @param files - File patterns for the test suite (string or array)
+	* @param timeout - Optional timeout in milliseconds (defaults to 2000)
+	* @returns This RcFileTransformer instance for method chaining
+	*/
 	addSuite(suiteName, files, timeout) {
 		const suitesArray = this.#getPropertyAssignmentInDefineConfigCall("tests", `{ suites: [], forceExit: true, timeout: 2000 }`).getInitializerIfKindOrThrow(SyntaxKind.ObjectLiteralExpression).getPropertyOrThrow("suites").getInitializerIfKindOrThrow(SyntaxKind.ArrayLiteralExpression);
 		if (this.#extractPropertyFromArray(suitesArray, "name").includes(suiteName)) return this;
+		/**
+		* Add the suite to the array
+		*/
 		const filesArray = Array.isArray(files) ? files : [files];
 		suitesArray.addElement(`{
         name: '${suiteName}',
@@ -140,6 +299,15 @@ export default defineConfig({
       }`);
 		return this;
 	}
+	/**
+	* Add a new assembler hook
+	* The format `thunk` write `() => import(path)`.
+	*
+	* @param type - The type of hook to add
+	* @param value - The path to the hook file or value to write
+	* @param raw - Wether to write a thunk import or as raw value
+	* @returns This RcFileTransformer instance for method chaining
+	*/
 	addAssemblerHook(type, value, raw = false) {
 		const hooks = this.#getPropertyAssignmentInDefineConfigCall("hooks", "{}").getInitializerIfKindOrThrow(SyntaxKind.ObjectLiteralExpression);
 		let hookArray = hooks.getProperty(type);
@@ -158,6 +326,13 @@ export default defineConfig({
 		}
 		return this;
 	}
+	/**
+	* Add a named import
+	*
+	* @param specifier - The module specifier to import
+	* @param names - Names to import from the module
+	* @returns This RcFileTransformer instance for method chaining
+	*/
 	addNamedImport(specifier, names) {
 		this.#getRcFileOrThrow().addImportDeclaration({
 			moduleSpecifier: specifier,
@@ -165,6 +340,13 @@ export default defineConfig({
 		});
 		return this;
 	}
+	/**
+	* Add a default import
+	*
+	* @param specifier - The module specifier to import
+	* @param name - Name of the default import
+	* @returns This RcFileTransformer instance for method chaining
+	*/
 	addDefaultImport(specifier, name) {
 		this.#getRcFileOrThrow().addImportDeclaration({
 			moduleSpecifier: specifier,
@@ -172,6 +354,13 @@ export default defineConfig({
 		});
 		return this;
 	}
+	/**
+	* Get a directory value from the directories configuration.
+	*
+	* @param key - The directory key to retrieve
+	* @param defaultValue - The default value if not configured
+	* @returns The configured directory path or the default value
+	*/
 	getDirectory(key, defaultValue) {
 		try {
 			const file = this.#getRcFileOrThrow();
@@ -189,18 +378,62 @@ export default defineConfig({
 			return defaultValue;
 		}
 	}
+	/**
+	* Save the adonisrc.ts file with all applied transformations
+	*
+	* Formats the file according to editor settings and saves it to disk.
+	*
+	* @returns Promise that resolves when the file is saved
+	*/
 	save() {
 		const file = this.#getRcFileOrThrow();
 		file.formatText(this.#editorSettings);
 		return file.save();
 	}
 };
+//#endregion
+//#region src/code_transformer/main.ts
+/**
+* This class is responsible for transforming AdonisJS project code,
+* including updating middleware, environment validations, and other
+* code generation tasks.
+*
+* The CodeTransformer provides methods for modifying various AdonisJS
+* configuration files and code structures using AST manipulation through
+* ts-morph. It can update middleware stacks, add environment validations,
+* register plugins, and modify RC file configurations.
+*
+* @example
+* const transformer = new CodeTransformer(cwd)
+* await transformer.addMiddlewareToStack('server', [{
+*   path: '#middleware/cors_middleware',
+*   position: 'before'
+* }])
+*/
 var CodeTransformer = class {
+	/**
+	* Utility function for installing packages
+	*/
 	installPackage = installPackage;
+	/**
+	* Utility function for detecting the package manager
+	*/
 	detectPackageManager = detectPackageManager;
+	/**
+	* Directory of the adonisjs project
+	*/
 	#cwd;
+	/**
+	* String path version of the current working directory
+	*/
 	#cwdPath;
+	/**
+	* The TsMorph project instance for AST manipulation
+	*/
 	project;
+	/**
+	* Settings to use when persisting files
+	*/
 	#editorSettings = {
 		indentSize: 2,
 		convertTabsToSpaces: true,
@@ -209,6 +442,11 @@ var CodeTransformer = class {
 		indentStyle: 2,
 		semicolons: "remove"
 	};
+	/**
+	* Create a new CodeTransformer instance
+	*
+	* @param cwd - The current working directory URL
+	*/
 	constructor(cwd) {
 		this.#cwd = cwd;
 		this.#cwdPath = fileURLToPath(this.#cwd);
@@ -217,6 +455,14 @@ var CodeTransformer = class {
 			manipulationSettings: { quoteKind: QuoteKind.Single }
 		});
 	}
+	/**
+	* Get directories configured in adonisrc.ts, with defaults fallback.
+	*
+	* This method reads the adonisrc.ts file and extracts the directories
+	* configuration. If a directory is not configured, the default value is used.
+	*
+	* @returns Object containing directory paths
+	*/
 	getDirectories() {
 		const rcFileTransformer = new RcFileTransformer(this.#cwd, this.project);
 		return {
@@ -228,15 +474,38 @@ var CodeTransformer = class {
 			controllers: rcFileTransformer.getDirectory("controllers", "app/controllers")
 		};
 	}
+	/**
+	* Add a new middleware to the middleware array of the given file
+	*
+	* This method locates middleware stack calls (like server.use or router.use)
+	* and adds the middleware entry to the appropriate position in the array.
+	*
+	* @param file - The source file to modify
+	* @param target - The target method call (e.g., 'server.use', 'router.use')
+	* @param middlewareEntry - The middleware entry to add
+	*/
 	#addToMiddlewareArray(file, target, middlewareEntry) {
 		const callExpressions = file.getDescendantsOfKind(SyntaxKind.CallExpression).filter((statement) => statement.getExpression().getText() === target);
 		if (!callExpressions.length) throw new Error(`Cannot find ${target} statement in the file.`);
 		const arrayLiteralExpression = callExpressions[0].getArguments()[0];
 		if (!arrayLiteralExpression || !Node.isArrayLiteralExpression(arrayLiteralExpression)) throw new Error(`Cannot find middleware array in ${target} statement.`);
 		const middleware = `() => import('${middlewareEntry.path}')`;
-		if (arrayLiteralExpression.getElements().findIndex((element) => element.getText() === middleware) === -1) if (middlewareEntry.position === "before") arrayLiteralExpression.insertElement(0, middleware);
+		if (arrayLiteralExpression.getElements().findIndex((element) => element.getText() === middleware) === -1)
+ /**
+		* Add the middleware to the top or bottom of the array
+		*/
+		if (middlewareEntry.position === "before") arrayLiteralExpression.insertElement(0, middleware);
 		else arrayLiteralExpression.addElement(middleware);
 	}
+	/**
+	* Add a new middleware to the named middleware of the given file
+	*
+	* This method adds middleware entries to the named middleware object,
+	* typically used for route-specific middleware registration.
+	*
+	* @param file - The source file to modify
+	* @param middlewareEntry - The middleware entry to add (must have a name)
+	*/
 	#addToNamedMiddleware(file, middlewareEntry) {
 		if (!middlewareEntry.name) throw new Error("Named middleware requires a name.");
 		const callArguments = file.getVariableDeclarationOrThrow("middleware").getInitializerIfKindOrThrow(SyntaxKind.CallExpression).getArguments();
@@ -244,10 +513,22 @@ var CodeTransformer = class {
 		const namedMiddlewareObject = callArguments[0];
 		if (!Node.isObjectLiteralExpression(namedMiddlewareObject)) throw new Error("The argument of the named middleware call is not an object literal.");
 		if (!namedMiddlewareObject.getProperty(middlewareEntry.name)) {
+			/**
+			* Add the named middleware
+			*/
 			const middleware = `${middlewareEntry.name}: () => import('${middlewareEntry.path}')`;
 			namedMiddlewareObject.insertProperty(0, middleware);
 		}
 	}
+	/**
+	* Add a policy to the list of pre-registered policies
+	*
+	* This method adds bouncer policy entries to the policies object,
+	* allowing them to be used in route authorization.
+	*
+	* @param file - The source file to modify
+	* @param policyEntry - The policy entry to add
+	*/
 	#addToPoliciesList(file, policyEntry) {
 		const policiesObject = file.getVariableDeclarationOrThrow("policies").getInitializerIfKindOrThrow(SyntaxKind.ObjectLiteralExpression);
 		if (!policiesObject.getProperty(policyEntry.name)) {
@@ -255,13 +536,26 @@ var CodeTransformer = class {
 			policiesObject.insertProperty(0, policy);
 		}
 	}
+	/**
+	* Add the given import declarations to the source file
+	* and merge named imports with the existing import
+	*/
 	#addImportDeclarations(file, importDeclarations) {
 		importDeclarations.forEach((importDeclaration) => {
 			const existingImport = file.getImportDeclarations().find((mod) => mod.getModuleSpecifierValue() === importDeclaration.module);
+			/**
+			* Add a new named import to existing import for the
+			* same module
+			*/
 			if (existingImport && importDeclaration.isNamed) {
 				if (!existingImport.getNamedImports().find((namedImport) => namedImport.getName() === importDeclaration.identifier)) existingImport.addNamedImport(importDeclaration.identifier);
 				return;
 			}
+			/**
+			* Ignore default import when the same module is already imported.
+			* The chances are the existing default import and the importDeclaration
+			* identifiers are not the same. But we should not modify existing source
+			*/
 			if (existingImport) return;
 			file.addImportDeclaration({
 				...importDeclaration.isNamed ? { namedImports: [importDeclaration.identifier] } : { defaultImport: importDeclaration.identifier },
@@ -269,6 +563,9 @@ var CodeTransformer = class {
 			});
 		});
 	}
+	/**
+	* Convert ImportInfo array to import declarations and add them to the file
+	*/
 	#addImportsFromImportInfo(file, imports) {
 		const importsBag = new ImportsBag();
 		for (const importInfo of imports) importsBag.add(importInfo);
@@ -287,23 +584,50 @@ var CodeTransformer = class {
 		});
 		this.#addImportDeclarations(file, importDeclarations);
 	}
+	/**
+	* Write a leading comment
+	*/
 	#addLeadingComment(writer, comment) {
 		if (!comment) return writer.blankLine();
 		return writer.blankLine().writeLine("/*").writeLine(`|----------------------------------------------------------`).writeLine(`| ${comment}`).writeLine(`|----------------------------------------------------------`).writeLine(`*/`);
 	}
+	/**
+	* Add new env variable validation in the `env.ts` file
+	*
+	* @param definition - Environment validation definition containing variables and comment
+	*/
 	async defineEnvValidations(definition) {
 		const filePath = `${this.getDirectories().start}/env.ts`;
+		/**
+		* Get the env.ts source file
+		*/
 		const envUrl = join(this.#cwdPath, `./${filePath}`);
 		const file = this.project.getSourceFile(envUrl);
 		if (!file) throw CodemodException.missingEnvFile(filePath, definition);
+		/**
+		* Get the `Env.create` call expression
+		*/
 		const callExpressions = file.getDescendantsOfKind(SyntaxKind.CallExpression).filter((statement) => statement.getExpression().getText() === "Env.create");
 		if (!callExpressions.length) throw CodemodException.missingEnvCreate(filePath, definition);
 		const objectLiteralExpression = callExpressions[0].getArguments()[1];
 		if (!Node.isObjectLiteralExpression(objectLiteralExpression)) throw CodemodException.invalidEnvCreate(filePath, definition);
 		let shouldAddComment = true;
+		/**
+		* Add each variable validation
+		*/
 		for (const [variable, validation] of Object.entries(definition.variables)) {
+			/**
+			* Check if the variable is already defined. If so, remove it
+			*/
 			const existingProperty = objectLiteralExpression.getProperty(variable);
+			/**
+			* Do not add leading comment if one or more properties
+			* already exists
+			*/
 			if (existingProperty) shouldAddComment = false;
+			/**
+			* Add property only when the property does not exist
+			*/
 			if (!existingProperty) objectLiteralExpression.addPropertyAssignment({
 				name: variable,
 				initializer: validation,
@@ -317,11 +641,27 @@ var CodeTransformer = class {
 		file.formatText(this.#editorSettings);
 		await file.save();
 	}
+	/**
+	* Define new middlewares inside the `start/kernel.ts` file
+	*
+	* This function is highly based on some assumptions
+	* and will not work if you significantly tweaked
+	* your `start/kernel.ts` file.
+	*
+	* @param stack - The middleware stack to add to ('server', 'router', or 'named')
+	* @param middleware - Array of middleware entries to add
+	*/
 	async addMiddlewareToStack(stack, middleware) {
 		const filePath = `${this.getDirectories().start}/kernel.ts`;
+		/**
+		* Get the kernel.ts source file
+		*/
 		const kernelUrl = join(this.#cwdPath, `./${filePath}`);
 		const file = this.project.getSourceFile(kernelUrl);
 		if (!file) throw CodemodException.missingKernelFile(filePath, stack, middleware);
+		/**
+		* Process each middleware entry
+		*/
 		try {
 			for (const middlewareEntry of middleware) if (stack === "named") this.#addToNamedMiddleware(file, middlewareEntry);
 			else this.#addToMiddlewareArray(file, `${stack}.use`, middlewareEntry);
@@ -332,35 +672,81 @@ var CodeTransformer = class {
 		file.formatText(this.#editorSettings);
 		await file.save();
 	}
+	/**
+	* Update the `adonisrc.ts` file using the provided callback
+	*
+	* @param callback - Function that receives the RcFileTransformer for modifications
+	*/
 	async updateRcFile(callback) {
 		const rcFileTransformer = new RcFileTransformer(this.#cwd, this.project);
 		callback(rcFileTransformer);
 		await rcFileTransformer.save();
 	}
+	/**
+	* Add a new Japa plugin in the `tests/bootstrap.ts` file
+	*
+	* @param pluginCall - The plugin function call to add
+	* @param importDeclarations - Import declarations needed for the plugin
+	*/
 	async addJapaPlugin(pluginCall, importDeclarations) {
 		const filePath = `${this.getDirectories().tests}/bootstrap.ts`;
+		/**
+		* Get the bootstrap.ts source file
+		*/
 		const testBootstrapUrl = join(this.#cwdPath, `./${filePath}`);
 		const file = this.project.getSourceFile(testBootstrapUrl);
 		if (!file) throw CodemodException.missingJapaBootstrap(filePath, pluginCall, importDeclarations);
+		/**
+		* Add the import declarations
+		*/
 		this.#addImportDeclarations(file, importDeclarations);
+		/**
+		* Insert the plugin call in the `plugins` array
+		*/
 		const pluginsArray = file.getVariableDeclaration("plugins")?.getInitializerIfKind(SyntaxKind.ArrayLiteralExpression);
+		/**
+		* Add plugin call to the plugins array
+		*/
 		if (pluginsArray) {
 			if (!pluginsArray.getElements().find((element) => element.getText() === pluginCall)) pluginsArray.addElement(pluginCall);
 		}
 		file.formatText(this.#editorSettings);
 		await file.save();
 	}
+	/**
+	* Add a new Vite plugin to the `vite.config.ts` file
+	*
+	* @param pluginCall - The plugin function call to add
+	* @param importDeclarations - Import declarations needed for the plugin
+	*/
 	async addVitePlugin(pluginCall, importDeclarations) {
 		const filePath = "vite.config.ts";
+		/**
+		* Get the `vite.config.ts` source file
+		*/
 		const viteConfigTsUrl = join(this.#cwdPath, `./${filePath}`);
 		const file = this.project.getSourceFile(viteConfigTsUrl);
 		if (!file) throw CodemodException.missingViteConfig(filePath, pluginCall, importDeclarations);
 		try {
+			/**
+			* Add the import declarations
+			*/
 			this.#addImportDeclarations(file, importDeclarations);
+			/**
+			* Get the default export options
+			*/
 			const defaultExport = file.getDefaultExportSymbol();
 			if (!defaultExport) throw new Error("Cannot find the default export in vite.config.ts");
+			/**
+			* Get the options object
+			* - Either the first argument of `defineConfig` call : `export default defineConfig({})`
+			* - Or child literal expression of the default export : `export default {}`
+			*/
 			const declaration = defaultExport.getDeclarations()[0];
 			const pluginsArray = (declaration.getChildrenOfKind(SyntaxKind.ObjectLiteralExpression)[0] || declaration.getChildrenOfKind(SyntaxKind.CallExpression)[0].getArguments()[0]).getPropertyOrThrow("plugins").getFirstChildByKindOrThrow(SyntaxKind.ArrayLiteralExpression);
+			/**
+			* Add plugin call to the plugins array
+			*/
 			if (!pluginsArray.getElements().find((element) => element.getText() === pluginCall)) pluginsArray.addElement(pluginCall);
 		} catch (error) {
 			if (error instanceof CodemodException) throw error;
@@ -370,11 +756,23 @@ var CodeTransformer = class {
 		file.formatText(this.#editorSettings);
 		await file.save();
 	}
+	/**
+	* Adds a policy to the list of `policies` object configured
+	* inside the `app/policies/main.ts` file.
+	*
+	* @param policies - Array of bouncer policy entries to add
+	*/
 	async addPolicies(policies) {
 		const filePath = `${this.getDirectories().policies}/main.ts`;
+		/**
+		* Get the policies/main.ts source file
+		*/
 		const policiesUrl = join(this.#cwdPath, `./${filePath}`);
 		const file = this.project.getSourceFile(policiesUrl);
 		if (!file) throw CodemodException.missingPoliciesFile(filePath, policies);
+		/**
+		* Process each policy entry
+		*/
 		try {
 			for (const policy of policies) this.#addToPoliciesList(file, policy);
 		} catch (error) {
@@ -386,11 +784,20 @@ var CodeTransformer = class {
 	}
 	async addValidator(definition) {
 		const filePath = `${this.getDirectories().validators}/${definition.validatorFileName}`;
+		/**
+		* Get the validator file URL
+		*/
 		const validatorFileUrl = join(this.#cwdPath, `./${filePath}`);
 		let file = this.project.getSourceFile(validatorFileUrl);
+		/**
+		* Try to load the file from disk if not already in the project
+		*/
 		if (!file) try {
 			file = this.project.addSourceFileAtPath(validatorFileUrl);
 		} catch {}
+		/**
+		* If the file does not exist, create it
+		*/
 		if (!file) {
 			file = this.project.createSourceFile(validatorFileUrl, definition.contents);
 			file.formatText(this.#editorSettings);
@@ -398,17 +805,29 @@ var CodeTransformer = class {
 			return;
 		}
 		if (file.getVariableDeclaration(definition.exportName)) return;
+		/**
+		* Add the validator to the existing file
+		*/
 		file.addStatements(`\n${definition.contents}`);
 		file.formatText(this.#editorSettings);
 		await file.save();
 	}
 	async addLimiter(definition) {
 		const filePath = `${this.getDirectories().start}/${definition.limiterFileName}`;
+		/**
+		* Get the limiter file URL
+		*/
 		const limiterFileUrl = join(this.#cwdPath, `./${filePath}`);
 		let file = this.project.getSourceFile(limiterFileUrl);
+		/**
+		* Try to load the file from disk if not already in the project
+		*/
 		if (!file) try {
 			file = this.project.addSourceFileAtPath(limiterFileUrl);
 		} catch {}
+		/**
+		* If the file does not exist, create it
+		*/
 		if (!file) {
 			file = this.project.createSourceFile(limiterFileUrl, definition.contents);
 			file.formatText(this.#editorSettings);
@@ -416,25 +835,40 @@ var CodeTransformer = class {
 			return;
 		}
 		if (file.getVariableDeclaration(definition.exportName)) return;
+		/**
+		* Add the limiter to the existing file
+		*/
 		file.addStatements(`\n${definition.contents}`);
 		file.formatText(this.#editorSettings);
 		await file.save();
 	}
 	async addModelMixins(modelFileName, mixins) {
 		const filePath = `${this.getDirectories().models}/${modelFileName}`;
+		/**
+		* Get the model file URL
+		*/
 		const modelFileUrl = join(this.#cwdPath, `./${filePath}`);
 		let file = this.project.getSourceFile(modelFileUrl);
+		/**
+		* Try to load the file from disk if not already in the project
+		*/
 		if (!file) try {
 			file = this.project.addSourceFileAtPath(modelFileUrl);
 		} catch {
 			throw new Error(`Could not find source file at path: "${filePath}"`);
 		}
+		/**
+		* Get the default export class declaration
+		*/
 		const defaultExportSymbol = file.getDefaultExportSymbol();
 		if (!defaultExportSymbol) throw new Error(`Could not find default export in "${filePath}". The model must have a default export class.`);
 		const declarations = defaultExportSymbol.getDeclarations();
 		if (declarations.length === 0) throw new Error(`Could not find default export declaration in "${filePath}".`);
 		const declaration = declarations[0];
 		if (!Node.isClassDeclaration(declaration)) throw new Error(`Default export in "${filePath}" is not a class. The model must be exported as a class.`);
+		/**
+		* Add import declarations for the mixins
+		*/
 		const mixinImports = mixins.map((mixin) => {
 			if (mixin.importType === "named") return {
 				source: mixin.importPath,
@@ -446,21 +880,40 @@ var CodeTransformer = class {
 			};
 		});
 		this.#addImportsFromImportInfo(file, mixinImports);
+		/**
+		* Get the heritage clause (extends clause)
+		*/
 		const heritageClause = declaration.getHeritageClauseByKind(SyntaxKind.ExtendsKeyword);
 		if (!heritageClause) throw new Error(`Could not find extends clause in "${filePath}".`);
 		const extendsExpression = heritageClause.getTypeNodes()[0];
 		if (!extendsExpression) throw new Error(`Could not find extends expression in "${filePath}".`);
+		/**
+		* Get the expression that the class extends
+		*/
 		const extendsExpressionNode = extendsExpression.getExpression();
+		/**
+		* Check if the class already uses compose
+		*/
 		let composeCall;
 		if (Node.isCallExpression(extendsExpressionNode)) {
 			if (extendsExpressionNode.getExpression().getText() === "compose") composeCall = extendsExpressionNode;
 		}
+		/**
+		* Build the mixin calls
+		*/
 		const mixinCalls = mixins.map((mixin) => {
 			const args = mixin.args && mixin.args.length > 0 ? mixin.args.join(", ") : "";
 			return `${mixin.name}(${args})`;
 		});
+		/**
+		* If the class is already using compose, add the mixins to the compose call
+		*/
 		if (composeCall && Node.isCallExpression(composeCall)) {
 			const existingArgsText = composeCall.getArguments().map((arg) => arg.getText());
+			/**
+			* Filter out mixins that are already applied by checking if a call
+			* to the mixin function already exists in the compose arguments
+			*/
 			const newMixinCalls = mixinCalls.filter((mixinCall) => {
 				const mixinFunctionName = mixinCall.split("(")[0];
 				return !existingArgsText.some((existingArg) => {
@@ -470,6 +923,10 @@ var CodeTransformer = class {
 			const newArgs = [...existingArgsText, ...newMixinCalls];
 			composeCall.replaceWithText(`compose(${newArgs.join(", ")})`);
 		} else {
+			/**
+			* If the class is not using compose, wrap the extends expression in compose
+			* and add import for compose
+			*/
 			this.#addImportDeclarations(file, [{
 				isNamed: true,
 				module: "@adonisjs/core/helpers",
@@ -483,21 +940,36 @@ var CodeTransformer = class {
 	}
 	async addControllerMethod(definition) {
 		const filePath = `${this.getDirectories().controllers}/${definition.controllerFileName}`;
+		/**
+		* Get the controller file URL
+		*/
 		const controllerFileUrl = join(this.#cwdPath, `./${filePath}`);
 		let file = this.project.getSourceFile(controllerFileUrl);
+		/**
+		* Try to load the file from disk if not already in the project
+		*/
 		if (!file) try {
 			file = this.project.addSourceFileAtPath(controllerFileUrl);
 		} catch {}
+		/**
+		* If the file does not exist, create it with the controller class and method
+		*/
 		if (!file) {
 			const contents = `export default class ${definition.className} {
   ${definition.contents}
 }`;
 			file = this.project.createSourceFile(controllerFileUrl, contents);
+			/**
+			* Add imports if specified
+			*/
 			if (definition.imports) this.#addImportsFromImportInfo(file, definition.imports);
 			file.formatText(this.#editorSettings);
 			await file.save();
 			return;
 		}
+		/**
+		* Get the default export class declaration
+		*/
 		const defaultExportSymbol = file.getDefaultExportSymbol();
 		if (!defaultExportSymbol) throw new Error(`Could not find default export in "${filePath}". The controller must have a default export class.`);
 		const declarations = defaultExportSymbol.getDeclarations();
@@ -505,10 +977,17 @@ var CodeTransformer = class {
 		const declaration = declarations[0];
 		if (!Node.isClassDeclaration(declaration)) throw new Error(`Default export in "${filePath}" is not a class. The controller must be exported as a class.`);
 		if (declaration.getMethod(definition.name)) return;
+		/**
+		* Add imports if specified
+		*/
 		if (definition.imports) this.#addImportsFromImportInfo(file, definition.imports);
+		/**
+		* Add the method to the class by inserting the raw method text
+		*/
 		declaration.addMember(definition.contents);
 		file.formatText(this.#editorSettings);
 		await file.save();
 	}
 };
+//#endregion
 export { CodeTransformer };