@adonisjs/assembler 8.0.0 → 8.0.1

package/build/index.js

@@ -1,9 +1,8 @@
-import { a as loadHooks, c as readTsConfig, d as runNode, f as throttle, m as debug_default, n as copyFiles, o as memoize, p as watch, r as getPort, s as parseConfig, t as VirtualFileSystem, u as run } from "./virtual_file_system-bGeoWsK-.js";
-import { n as FileBuffer } from "./source-dVeugJ0e.js";
-import { IndexGenerator } from "./src/index_generator/main.js";
-import "./validator_extractor-Ccio_Ndi.js";
-import { RoutesScanner } from "./src/code_scanners/routes_scanner/main.js";
-import { t as CodemodException } from "./codemod_exception-CzQgXAAf.js";
+import "./chunk-DF48asd8.js";
+import { a as loadHooks, c as readTsConfig, d as runNode, f as throttle, m as debug_default, n as copyFiles, o as memoize, p as watch, r as getPort, s as parseConfig, t as VirtualFileSystem, u as run } from "./virtual_file_system-dzfXNwEp.js";
+import { n as FileBuffer, t as IndexGenerator } from "./main-INOi9swJ.js";
+import { t as RoutesScanner } from "./main-Cpfvmdw6.js";
+import { t as CodemodException } from "./codemod_exception-BMNJZ0i1.js";
 import dedent from "dedent";
 import fs, { readFile, unlink } from "node:fs/promises";
 import { cliui } from "@poppinss/cliui";
@@ -15,6 +14,11 @@ import getRandomPort from "get-port";
 import picomatch from "picomatch";
 import prettyHrtime from "pretty-hrtime";
 import { RuntimeException } from "@poppinss/utils/exception";
+//#region src/bundler.ts
+/**
+* List of package managers we support in order to
+* copy lockfiles
+*/
 const SUPPORTED_PACKAGE_MANAGERS = {
 	"npm": {
 		packageManagerFiles: ["package-lock.json"],
@@ -41,23 +45,65 @@ const SUPPORTED_PACKAGE_MANAGERS = {
 		installCommand: "bun install --production"
 	}
 };
+/**
+* The bundler class exposes the API to build an AdonisJS project.
+*
+* @example
+* const bundler = new Bundler(new URL('./'), ts, { hooks: [] })
+* const success = await bundler.bundle()
+*/
 var Bundler = class {
+	/**
+	* Reference to the TypeScript module
+	*/
 	#ts;
+	/**
+	* Hooks to execute custom actions during the build process
+	*/
 	#hooks;
+	/**
+	* Index generator for managing auto-generated index files
+	*/
 	#indexGenerator;
+	/**
+	* CLI UI instance for displaying colorful messages and progress information
+	*/
 	ui = cliui();
+	/**
+	* The current working directory URL
+	*/
 	cwd;
+	/**
+	* The current working project directory path as string
+	*/
 	cwdPath;
+	/**
+	* Bundler configuration options including hooks and meta files
+	*/
 	options;
+	/**
+	* Create a new bundler instance
+	*
+	* @param cwd - The current working directory URL
+	* @param ts - TypeScript module reference
+	* @param options - Bundler configuration options
+	*/
 	constructor(cwd, ts, options) {
 		this.cwd = cwd;
 		this.options = options;
 		this.cwdPath = string.toUnixSlash(fileURLToPath(this.cwd));
 		this.#ts = ts;
 	}
+	/**
+	* Returns the relative unix path for an absolute
+	* file path
+	*/
 	#getRelativeName(filePath) {
 		return string.toUnixSlash(relative(this.cwdPath, filePath));
 	}
+	/**
+	* Cleans up the build directory
+	*/
 	async #cleanupBuildDirectory(outDir) {
 		await fs.rm(outDir, {
 			recursive: true,
@@ -65,6 +111,9 @@ var Bundler = class {
 			maxRetries: 5
 		});
 	}
+	/**
+	* Runs tsc command to build the source.
+	*/
 	async #runTsc(outDir) {
 		try {
 			await run(this.cwd, {
@@ -77,15 +126,26 @@ var Bundler = class {
 			return false;
 		}
 	}
+	/**
+	* Copy meta files to the output directory
+	*/
 	async #copyMetaFiles(outDir, additionalFilesToCopy) {
 		await copyFiles((this.options.metaFiles || []).map((file) => file.pattern).concat(additionalFilesToCopy), this.cwdPath, outDir);
 	}
+	/**
+	* Detect the package manager used by the project
+	*/
 	async #detectPackageManager() {
 		const pkgManager = await detectPackageManager(this.cwdPath);
 		if (pkgManager === "deno") return "npm";
 		if (pkgManager === "pnpm@6") return "pnpm";
 		return pkgManager;
 	}
+	/**
+	* Rewrite the ace file since the original one
+	* is importing ts-node which is not installed
+	* in a production environment.
+	*/
 	async #createAceFile(outDir) {
 		const aceFileLocation = join(outDir, "ace.js");
 		const aceFileContent = dedent(`
@@ -100,8 +160,21 @@ var Bundler = class {
 		await fs.writeFile(aceFileLocation, aceFileContent);
 		this.ui.logger.info("created ace file", { suffix: this.#getRelativeName(aceFileLocation) });
 	}
+	/**
+	* Bundles the application to be run in production
+	*
+	* @param stopOnError - Whether to stop the build process on TypeScript errors
+	* @param client - Override the detected package manager
+	* @returns Promise that resolves to true if build succeeded, false otherwise
+	*
+	* @example
+	* const success = await bundler.bundle(true, 'npm')
+	*/
 	async bundle(stopOnError = true, client) {
 		this.packageManager = client ?? await this.#detectPackageManager() ?? "npm";
+		/**
+		* Step 1: Parse config file to get the build output directory
+		*/
 		const config = parseConfig(this.cwd, this.#ts);
 		if (!config) return false;
 		this.ui.logger.info("loading hooks...");
@@ -111,17 +184,33 @@ var Bundler = class {
 			"buildFinished"
 		]);
 		this.#indexGenerator = new IndexGenerator(this.cwdPath, this.ui.logger);
+		/**
+		* Step 2: Run init hook and the index generator
+		*/
 		await this.#hooks.runner("init").run(this, this.#hooks, this.#indexGenerator);
 		this.#hooks.clear("init");
 		this.ui.logger.info("generating indexes...");
 		await this.#indexGenerator.generate();
+		/**
+		* Step 3: Cleanup existing build directory (if any)
+		*/
 		const outDir = config.options.outDir || fileURLToPath(new URL("build/", this.cwd));
 		this.ui.logger.info("cleaning up output directory", { suffix: this.#getRelativeName(outDir) });
 		await this.#cleanupBuildDirectory(outDir);
+		/**
+		* Step 4: Execute build starting hook
+		*/
 		await this.#hooks.runner("buildStarting").run(this);
+		/**
+		* Step 5: Build typescript source code
+		*/
 		this.ui.logger.info("compiling typescript source", { suffix: "tsc" });
 		const buildCompleted = await this.#runTsc(outDir);
 		await this.#createAceFile(outDir);
+		/**
+		* Remove incomplete build directory when tsc build
+		* failed and stopOnError is set to true.
+		*/
 		if (!buildCompleted && stopOnError) {
 			await this.#cleanupBuildDirectory(outDir);
 			const instructions = this.ui.sticker().fullScreen().drawBorder((borderChar, colors) => colors.red(borderChar));
@@ -130,48 +219,156 @@ var Bundler = class {
 			this.ui.logger.logError(instructions.prepare());
 			return false;
 		}
+		/**
+		* Step 6: Copy meta files to the build directory
+		*/
 		const pkgFiles = ["package.json", ...SUPPORTED_PACKAGE_MANAGERS[this.packageManager].packageManagerFiles];
 		this.ui.logger.info("copying meta files to the output directory");
 		await this.#copyMetaFiles(outDir, pkgFiles);
 		this.ui.logger.success("build completed");
 		this.ui.logger.log("");
 		const displayMessage = this.ui.instructions().heading("Run the following commands to start the server in production");
+		/**
+		* Step 7: Execute build completed hook
+		*/
 		await this.#hooks.runner("buildFinished").run(this, displayMessage);
+		/**
+		* Display next steps
+		*/
 		displayMessage.add(this.ui.colors.cyan(`cd ${this.#getRelativeName(outDir)}`)).add(this.ui.colors.cyan(SUPPORTED_PACKAGE_MANAGERS[this.packageManager].installCommand)).add(this.ui.colors.cyan("node bin/server.js")).render();
 		return true;
 	}
 };
+//#endregion
+//#region src/file_system.ts
 const DEFAULT_INCLUDES = ["**/*"];
 const ALWAYS_EXCLUDE = [
 	".git/**",
 	"coverage/**",
 	".github/**",
-	".adonisjs/**"
+	".adonisjs/**",
+	"tmp/**",
+	"storage/**",
+	"build/**"
 ];
 const DEFAULT_EXCLUDES = [
 	"node_modules/**",
 	"bower_components/**",
 	"jspm_packages/**"
 ];
+/**
+* Exposes an intutive API to run actions when different kind of files
+* are changed. The FileSystem is built around the vocabulary used by
+* AdonisJS. Which includes:
+*
+* - Source files: TypeScript, JavaScript, JSON, JSX, TSX files that are included
+*   inside the "tsconfig.json" file are considered as source files.
+* - Meta files: Files registered under the "metaFiles" array of "adonisrc.ts" file
+*   are called meta files.
+* - Meta restart files: Meta files with "restart: true" enabled are called meta restart
+*   files.
+*
+* Using FileSystem you can register actions to be executed when a file changes in
+* one of the above categories.
+*
+* @example
+* const fs = new FileSystem(cwd, tsConfig, rcFile)
+* const file = fs.inspect('./app/controllers/users_controller.ts')
+*/
 var FileSystem = class {
+	/**
+	* The current working project directory
+	*/
 	#cwd;
+	/**
+	* Referenced to the parsed ts config file. We use it to read the includes,
+	* excludes and pre-scanned files.
+	*/
 	#tsConfig;
+	/**
+	* Set of pre-scanned typeScript files provided by tsconfig
+	*/
 	#scannedTypeScriptFiles = /* @__PURE__ */ new Set();
+	/**
+	* Picomatch matcher function to know if a file path is
+	* part of includes
+	*/
 	#isIncluded;
+	/**
+	* Picomatch matcher function to know if a file path is
+	* part of excludes
+	*/
 	#isExcluded;
+	/**
+	* Picomatch matcher function to know if a file path is a
+	* meta file with reloadServer option enabled
+	*/
 	#isMetaFileWithReloadsEnabled;
+	/**
+	* Picomatch matcher function to know if a file path is a
+	* meta file with reloadServer option disabled
+	*/
 	#isMetaFileWithReloadsDisabled;
+	/**
+	* Picomatch matcher function to know if a file path is a
+	* test file or not
+	*/
 	#isTestFile;
+	/**
+	* References to includes and excludes glob patterns
+	*/
 	#includes;
 	#excludes;
+	/**
+	* Includes glob patterns extracted from "tsconfig.json" file.
+	* Defaults to: ["**\/*"]
+	*/
 	get includes() {
 		return this.#includes;
 	}
+	/**
+	* Excludes glob patterns extracted from "tsconfig.json" file.
+	*
+	* Defaults to: [
+	*   'node_modules/**',
+	*   'bower_components/**',
+	*   'jspm_packages/**,
+	* ]
+	*
+	* Following patterns are always ignored
+	*
+	* '.git/**', 'coverage/**', '.github/**', '.adonisjs/**', 'tmp/**', 'storage/**', 'build/**'
+	*/
 	get excludes() {
 		return this.#excludes;
 	}
+	/**
+	* Inspect a file path to determine its type and properties within the project.
+	*
+	* This method analyzes a file to categorize it as a script file, test file, or meta file,
+	* and determines whether changes to the file should trigger server restarts. Results
+	* are memoized for performance optimization.
+	*
+	* @param absolutePath - The absolute Unix path to the file
+	* @param relativePath - The relative Unix path from the project root
+	* @returns File inspection result or null if the file should be ignored
+	*
+	* @example
+	* const file = fileSystem.inspect('/project/app/models/user.ts', 'app/models/user.ts')
+	* if (file) {
+	*   console.log(file.fileType) // 'script'
+	*   console.log(file.reloadServer) // true
+	* }
+	*/
 	inspect = memoize((absolutePath, relativePath) => {
 		relativePath = relativePath ?? relative(this.#cwd, absolutePath);
+		/**
+		* If a file is a script file and part of the backend project, then we consider
+		* the file.
+		*
+		* Non script files are not checked inside the backend project, since there are
+		* anyways cannot be processed by TypeScript.
+		*/
 		if (this.#isScriptFile(relativePath) && (this.#scannedTypeScriptFiles.has(absolutePath) || this.#isPartOfBackendProject(relativePath))) {
 			debug_default("backend project file \"%s\"", relativePath);
 			const isTestFile = this.#isTestFile(relativePath);
@@ -182,6 +379,9 @@ var FileSystem = class {
 				unixAbsolutePath: absolutePath
 			};
 		}
+		/**
+		* Check for meta files with reload flag enabled
+		*/
 		if (this.#isMetaFileWithReloadsEnabled(relativePath)) {
 			debug_default("meta file \"%s\"", relativePath);
 			return {
@@ -191,6 +391,9 @@ var FileSystem = class {
 				unixAbsolutePath: absolutePath
 			};
 		}
+		/**
+		* Check for meta files with reload flag disabled
+		*/
 		if (this.#isMetaFileWithReloadsDisabled(relativePath)) {
 			debug_default("meta file \"%s\"", relativePath);
 			return {
@@ -203,11 +406,38 @@ var FileSystem = class {
 		debug_default("ignored file \"%s\"", relativePath);
 		return null;
 	});
+	/**
+	* Determines if a directory should be watched by the file watcher.
+	*
+	* This method checks if a directory should be monitored for file changes
+	* based on the TypeScript configuration includes/excludes patterns.
+	* Results are memoized for performance. Chokidar sends absolute Unix paths.
+	*
+	* Note: Use shouldWatchFile for files and this method for directories only.
+	*
+	* @param absolutePath - The absolute Unix path to the directory
+	* @returns True if the directory should be watched
+	*
+	* @example
+	* const shouldWatch = fileSystem.shouldWatchDirectory('/project/app/controllers')
+	* console.log(shouldWatch) // true
+	*/
 	shouldWatchDirectory = memoize((absolutePath) => {
+		/**
+		* Always watch the project root
+		*/
 		if (absolutePath === this.#cwd) {
 			debug_default("watching project root");
 			return true;
 		}
+		/**
+		* Ignore directories excluded by tsconfig.json file. If tsconfig excludes
+		* directories include by metaFiles, then its a mis-configuration and we
+		* should update excludes to be more specific.
+		*
+		* Overriding excludes via metaFiles patterns is close to impossible because
+		* of how undeterministic glob patterns are.
+		*/
 		const relativePath = relative(this.#cwd, absolutePath);
 		if (this.#isExcluded(relativePath)) {
 			debug_default("watching \"%s\"", absolutePath);
@@ -215,6 +445,13 @@ var FileSystem = class {
 		}
 		return true;
 	});
+	/**
+	* Create a new FileSystem instance
+	*
+	* @param cwd - The current working directory URL or string path
+	* @param tsConfig - Parsed TypeScript configuration
+	* @param rcFile - AdonisJS RC file configuration
+	*/
 	constructor(cwd, tsConfig, rcFile) {
 		this.#cwd = cwd;
 		this.#tsConfig = tsConfig;
@@ -222,15 +459,27 @@ var FileSystem = class {
 		const metaFiles = rcFile.metaFiles ?? [];
 		const testSuites = rcFile.suites ?? [];
 		const outDir = tsConfig.config.compilerOptions?.outDir;
+		/**
+		* Register files we know ahead of time
+		*/
 		for (const file of files) this.#scannedTypeScriptFiles.add(string.toUnixSlash(file));
+		/**
+		* Compute includes and excludes
+		*/
 		this.#includes = tsConfig.config.include || DEFAULT_INCLUDES;
 		this.#excludes = ALWAYS_EXCLUDE.concat(tsConfig.config.exclude || (outDir ? DEFAULT_EXCLUDES.concat(outDir) : DEFAULT_EXCLUDES));
+		/**
+		* Pre-compute meta file patterns to avoid repeated array operations
+		*/
 		const metaFilesWithReloads = [];
 		const metaFilesWithoutReloads = [];
 		for (const file of metaFiles) if (file.reloadServer) metaFilesWithReloads.push(file.pattern);
 		else metaFilesWithoutReloads.push(file.pattern);
 		const testFilePatterns = testSuites.flatMap((suite) => suite.files);
 		const picomatcchOptions = { cwd: this.#cwd };
+		/**
+		* Initiate picomatch matchers we will need to identify metafiles
+		*/
 		this.#isMetaFileWithReloadsEnabled = picomatch(metaFilesWithReloads, picomatcchOptions);
 		this.#isMetaFileWithReloadsDisabled = picomatch(metaFilesWithoutReloads, picomatcchOptions);
 		this.#isTestFile = picomatch(testFilePatterns, picomatcchOptions);
@@ -245,32 +494,104 @@ var FileSystem = class {
 			testSuites
 		});
 	}
+	/**
+	* Determines if a file path represents a script file based on TypeScript configuration.
+	*
+	* Script files are those that can be processed by the TypeScript compiler:
+	* - Files ending with ".ts" or ".tsx" (excluding ".d.ts" declaration files)
+	* - Files ending with ".js" when "allowJs" option is enabled in tsconfig
+	* - Files ending with ".json" when "resolveJsonModule" option is enabled in tsconfig
+	*
+	* @param relativePath - The relative file path to check
+	* @returns True if the file is a script file
+	*/
 	#isScriptFile(relativePath) {
 		if ((relativePath.endsWith(".ts") || relativePath.endsWith(".tsx")) && !relativePath.endsWith(".d.ts")) return true;
 		if (this.#tsConfig.config.compilerOptions?.allowJs && relativePath.endsWith(".js")) return true;
 		if (this.#tsConfig.config.compilerOptions?.resolveJsonModule && relativePath.endsWith(".json")) return true;
 		return false;
 	}
+	/**
+	* Checks if a file path is part of the backend TypeScript project.
+	*
+	* Uses TypeScript configuration "includes", "excludes", and "files" paths
+	* to determine if a file should be considered part of the project compilation.
+	*
+	* @param relativePath - The relative file path to check
+	* @returns True if the file is part of the backend project
+	*/
 	#isPartOfBackendProject(relativePath) {
+		/**
+		* Script and non-script files can be excluded using tsconfig
+		*/
 		if (this.#isExcluded(relativePath)) {
 			debug_default("excluded by tsconfig \"%s\"", relativePath);
 			return false;
 		}
+		/**
+		* Return true when included
+		*/
 		if (this.#isIncluded(relativePath)) {
 			debug_default("included by tsconfig \"%s\"", relativePath);
 			return true;
 		}
 		return false;
 	}
+	/**
+	* Returns true if the file should be watched. Chokidar sends
+	* absolute unix paths to the ignored callback.
+	*
+	* You must use "shouldWatchDirectory" method for directories and call
+	* this method for files only.
+	*
+	* @param absolutePath - The absolute path to the file
+	* @returns True if the file should be watched
+	*/
 	shouldWatchFile(absolutePath) {
 		return this.inspect(absolutePath) !== null;
 	}
 };
+//#endregion
+//#region src/shortcuts_manager.ts
+/**
+* Manages keyboard shortcuts for development server interaction.
+*
+* The ShortcutsManager provides a convenient way to handle keyboard inputs
+* during development, allowing users to restart servers, clear console,
+* open browsers, and perform other common development tasks through simple
+* key presses.
+*
+* @example
+* const shortcuts = new ShortcutsManager({
+*   logger: ui.logger,
+*   callbacks: {
+*     onRestart: () => server.restart(),
+*     onClear: () => console.clear(),
+*     onQuit: () => process.exit()
+*   }
+* })
+* shortcuts.setup()
+*/
 var ShortcutsManager = class {
+	/**
+	* Logger instance for displaying messages
+	*/
 	#logger;
+	/**
+	* Callback functions for different keyboard shortcuts
+	*/
 	#callbacks;
+	/**
+	* The server URL used for opening browser
+	*/
 	#serverUrl;
+	/**
+	* Key press event handler function
+	*/
 	#keyPressHandler;
+	/**
+	* Available keyboard shortcuts with their handlers
+	*/
 	#shortcuts = [
 		{
 			key: "r",
@@ -300,35 +621,83 @@ var ShortcutsManager = class {
 			handler: () => this.showHelp()
 		}
 	];
+	/**
+	* Create a new ShortcutsManager instance
+	*
+	* @param options - Configuration options for the shortcuts manager
+	*/
 	constructor(options) {
 		this.#logger = options.logger;
 		this.#callbacks = options.callbacks;
 	}
+	/**
+	* Set server url for opening in browser
+	*
+	* This URL will be used when the user presses 'o' to open the
+	* development server in their default browser.
+	*
+	* @param url - The server URL to open when 'o' key is pressed
+	*/
 	setServerUrl(url) {
 		this.#serverUrl = url;
 	}
+	/**
+	* Initialize keyboard shortcuts by setting up raw mode on stdin
+	*
+	* This method enables raw mode on stdin to capture individual keypresses
+	* and sets up the event listener for handling keyboard input. Only works
+	* in TTY environments.
+	*/
 	setup() {
 		if (!process.stdin.isTTY) return;
 		process.stdin.setRawMode(true);
 		this.#keyPressHandler = (data) => this.#handleKeyPress(data.toString());
 		process.stdin.on("data", this.#keyPressHandler);
 	}
+	/**
+	* Handle key press events and execute corresponding shortcuts
+	*
+	* Processes individual key presses and matches them against registered
+	* shortcuts. Also handles special key combinations like Ctrl+C and Ctrl+D.
+	*
+	* @param key - The pressed key as a string
+	*/
 	#handleKeyPress(key) {
 		if (key === "" || key === "") return this.#callbacks.onQuit();
 		const shortcut = this.#shortcuts.find((s) => s.key === key);
 		if (shortcut) shortcut.handler();
 	}
+	/**
+	* Handle opening browser with the configured server URL
+	*
+	* Uses the 'open' package to launch the default browser and navigate
+	* to the development server URL.
+	*/
 	async #handleOpenBrowser() {
 		this.#logger.log("");
 		this.#logger.info(`Opening ${this.#serverUrl}...`);
 		const { default: open } = await import("open");
 		open(this.#serverUrl);
 	}
+	/**
+	* Show available keyboard shortcuts in the console
+	*
+	* Displays a formatted list of all available keyboard shortcuts
+	* and their descriptions to help users understand what actions
+	* are available.
+	*/
 	showHelp() {
 		this.#logger.log("");
 		this.#logger.log("Available shortcuts:");
 		this.#shortcuts.forEach(({ key, description }) => this.#logger.log(`· ${key}: ${description}`));
 	}
+	/**
+	* Cleanup keyboard shortcuts and restore terminal state
+	*
+	* Disables raw mode on stdin, removes event listeners, and restores
+	* the terminal to its normal state. Should be called when shutting down
+	* the development server.
+	*/
 	cleanup() {
 		if (!process.stdin.isTTY) return;
 		process.stdin.setRawMode(false);
@@ -338,36 +707,111 @@ var ShortcutsManager = class {
 		this.#keyPressHandler = void 0;
 	}
 };
+//#endregion
+//#region src/dev_server.ts
+/**
+* Exposes the API to start the development server in HMR, watch or static mode
+*
+* In HMR mode, the DevServer will exec the "bin/server.ts" file and let hot-hook
+* manage the changes using hot module reloading.
+*
+* In watch mode, the DevServer will start an internal watcher and restarts the server
+* after every file change. The files must be part of the TypeScript project (via tsconfig.json),
+* or registered as metaFiles.
+*
+* In static mode, the server runs without file watching or hot reloading.
+*
+* @example
+* const devServer = new DevServer(cwd, { hmr: true, hooks: [] })
+* await devServer.start(ts)
+*/
 var DevServer = class DevServer {
+	/**
+	* Pre-allocated info object for hot-hook full reload events
+	*/
 	static #HOT_HOOK_FULL_RELOAD_INFO = {
 		source: "hot-hook",
 		fullReload: true,
 		hotReloaded: false
 	};
+	/**
+	* Pre-allocated info object for hot-hook invalidation events
+	*/
 	static #HOT_HOOK_INVALIDATED_INFO = {
 		source: "hot-hook",
 		fullReload: false,
 		hotReloaded: true
 	};
+	/**
+	* Pre-allocated info object for file watcher events
+	*/
 	static #WATCHER_INFO = {
 		source: "watcher",
 		fullReload: true,
 		hotReloaded: false
 	};
+	/**
+	* External listeners that are invoked when child process
+	* gets an error or closes
+	*/
 	#onError;
 	#onClose;
+	/**
+	* The stickyPort is set by the start and the startAndWatch methods
+	* and we will continue to use that port during restart
+	*/
 	#stickyPort;
+	/**
+	* The stickyHmrPort is set by the start and the startAndWatch methods
+	* and we will continue to use that port during restart
+	*/
 	#stickyHmrPort;
+	/**
+	* The mode is set by the start and the startAndWatch methods
+	*/
 	#mode = "static";
+	/**
+	* Reference to chokidar watcher
+	*/
 	#watcher;
+	/**
+	* Reference to the child process
+	*/
 	#httpServer;
+	/**
+	* Flag to track if the HTTP server child process is alive
+	*/
 	#isHttpServerAlive = false;
+	/**
+	* Keyboard shortcuts manager instance
+	*/
 	#shortcutsManager;
+	/**
+	* Filesystem is used to decide which files to watch or entertain when
+	* using hot-hook
+	*/
 	#fileSystem;
+	/**
+	* Index generator for managing auto-generated index files
+	*/
 	#indexGenerator;
+	/**
+	* Routes scanner to scan routes and infer route request and
+	* response data
+	*/
 	#routesScanner;
+	/**
+	* Hooks to execute custom actions during the dev server lifecycle
+	*/
 	#hooks;
+	/**
+	* CLI UI instance for displaying colorful messages and progress information
+	*/
 	ui = cliui();
+	/**
+	* Restarts the HTTP server and throttle concurrent calls to
+	* ensure we do not end up with a long loop of restarts
+	*/
 	#restartHTTPServer = throttle(async () => {
 		if (this.#httpServer) {
 			this.#httpServer.removeAllListeners();
@@ -375,6 +819,12 @@ var DevServer = class DevServer {
 		}
 		await this.#startHTTPServer(this.#stickyPort, this.#stickyHmrPort);
 	}, "restartHTTPServer");
+	/**
+	* Sets up keyboard shortcuts for development server interactions
+	*
+	* Initializes the shortcuts manager with callbacks for restarting the server,
+	* clearing the screen, and quitting the application.
+	*/
 	#setupKeyboardShortcuts() {
 		this.#shortcutsManager = new ShortcutsManager({
 			logger: this.ui.logger,
@@ -386,27 +836,85 @@ var DevServer = class DevServer {
 		});
 		this.#shortcutsManager.setup();
 	}
+	/**
+	* Cleanup keyboard shortcuts and restore terminal state
+	*
+	* Removes keyboard shortcuts event listeners and restores the terminal
+	* to its normal state when shutting down the development server.
+	*/
 	#cleanupKeyboardShortcuts() {
 		this.#shortcutsManager?.cleanup();
 	}
+	/**
+	* The mode in which the DevServer is running
+	*
+	* Returns the current operating mode of the development server:
+	* - 'hmr': Hot Module Reloading enabled
+	* - 'watch': File system watching with full restarts
+	* - 'static': No file watching or hot reloading
+	*/
 	get mode() {
 		return this.#mode;
 	}
+	/**
+	* Script file to start the development server
+	*/
 	scriptFile = "bin/server.ts";
+	/**
+	* The current working directory URL
+	*/
 	cwd;
+	/**
+	* File path computed from the cwd
+	*/
 	cwdPath;
+	/**
+	* Development server configuration options including hooks and environment variables
+	*/
 	options;
+	/**
+	* Create a new DevServer instance
+	*
+	* @param cwd - The current working directory URL
+	* @param options - Development server configuration options
+	*/
 	constructor(cwd, options) {
 		this.cwd = cwd;
 		this.options = options;
 		this.cwdPath = string.toUnixSlash(fileURLToPath(this.cwd));
 	}
+	/**
+	* Type guard to check if child process message is from AdonisJS HTTP server
+	*
+	* Validates that a message from the child process contains the expected
+	* structure indicating the AdonisJS server is ready and listening.
+	*
+	* @param message - Unknown message from child process
+	* @returns True if message is an AdonisJS ready message
+	*/
 	#isAdonisJSReadyMessage(message) {
 		return message !== null && typeof message === "object" && "isAdonisJS" in message && "environment" in message && message.environment === "web";
 	}
+	/**
+	* Type guard to check if child process message contains routes information
+	*
+	* Validates that a message from the child process contains the expected
+	* structure with routes file location from the AdonisJS server.
+	*
+	* @param message - Unknown message from child process
+	* @returns True if message contains routes file location
+	*/
 	#isAdonisJSRoutesMessage(message) {
 		return message !== null && typeof message === "object" && "routesFileLocation" in message;
 	}
+	/**
+	* Displays server information and executes hooks after server startup
+	*
+	* Shows server URL, mode, startup duration, and help instructions.
+	* Also executes the devServerStarted hooks to allow custom post-startup logic.
+	*
+	* @param message - Server ready message containing port, host, and optional duration
+	*/
 	async #postServerReady(message) {
 		const host = message.host === "0.0.0.0" ? "127.0.0.1" : message.host;
 		const info = {
@@ -418,6 +926,10 @@ var DevServer = class DevServer {
 		const displayMessage = this.ui.sticker().add(`Server address: ${this.ui.colors.cyan(serverUrl)}`).add(`Mode: ${this.ui.colors.cyan(this.mode)}`);
 		if (message.duration) displayMessage.add(`Ready in: ${this.ui.colors.cyan(prettyHrtime(message.duration))}`);
 		displayMessage.add(`Press ${this.ui.colors.dim("h")} to show help`);
+		/**
+		* Run hooks before displaying the "displayMessage". It will allow hooks to add
+		* custom lines to the display message.
+		*/
 		try {
 			await this.#hooks.runner("devServerStarted").run(this, info, displayMessage);
 		} catch (error) {
@@ -426,12 +938,30 @@ var DevServer = class DevServer {
 		}
 		displayMessage.render();
 	}
+	/**
+	* Type guard to check if child process message is from hot-hook
+	*
+	* Validates that a message from the child process is a hot-hook notification
+	* about file changes, invalidations, or full reloads.
+	*
+	* @param message - Unknown message from child process
+	* @returns True if message is a hot-hook message
+	*/
 	#isHotHookMessage(message) {
 		return message !== null && typeof message === "object" && "type" in message && typeof message.type === "string" && message.type.startsWith("hot-hook:");
 	}
+	/**
+	* Conditionally clears the terminal screen based on configuration
+	*
+	* Clears the terminal screen if the clearScreen option is enabled,
+	* providing a clean view for development output.
+	*/
 	#clearScreen() {
 		if (this.options.clearScreen) process.stdout.write("\x1Bc");
 	}
+	/**
+	* Creates our file system watcher
+	*/
 	#createWatcher(options) {
 		const watcher = watch({
 			usePolling: options?.poll ?? false,
@@ -455,6 +985,10 @@ var DevServer = class DevServer {
 		});
 		return watcher;
 	}
+	/**
+	* Handles file change events in HMR mode by forwarding to hot-hook
+	* or restarting the server if dead.
+	*/
 	#handleHmrWatcherEvent(options) {
 		const relativePath = string.toUnixSlash(options.filePath);
 		const absolutePath = join(this.cwdPath, relativePath);
@@ -464,24 +998,59 @@ var DevServer = class DevServer {
 			this.#restartHTTPServer();
 			return;
 		}
+		/**
+		* For add/unlink, we call the hooks directly since hot-hook ignores files
+		* not in its dependency tree. This ensures index files are regenerated
+		* for new/removed files.
+		*/
 		if (options.action === "add") this.#hooks.runner("fileAdded").run(relativePath, absolutePath, this);
 		else if (options.action === "unlink") this.#hooks.runner("fileRemoved").run(relativePath, absolutePath, this);
+		/**
+		* Forward all events to hot-hook so it can:
+		* - Update its dependency tree (for unlink)
+		* - Handle HMR for change events on imported files
+		* - Then we wait for hot-hook to notify us back via IPC message
+		*/
 		this.#httpServer?.send({
 			type: "hot-hook:file-changed",
 			path: absolutePath,
 			action: options.action
 		});
 	}
+	/**
+	* Handles file change events and triggers appropriate server actions
+	*
+	* Processes file change notifications and determines whether to restart
+	* the server, hot reload, or ignore the change based on file type and mode.
+	*
+	* @param relativePath - Relative path to the changed file
+	* @param absolutePath - Absolute path to the changed file
+	* @param action - Type of file change (add, update, delete)
+	* @param info - Optional information about the change source and reload behavior
+	*/
 	#handleFileChange(relativePath, absolutePath, action, info) {
+		/**
+		* Ignore add and delete events in HMR mode and let hot-hook find the
+		* file via import first.
+		*
+		* Remember, hot-hook does not send the action as "add" or "delete" if this
+		* file is being imported.
+		*/
 		if ((action === "add" || action === "delete") && this.mode === "hmr") {
 			debug_default("ignoring add and delete actions in HMR mode %s", relativePath);
 			return;
 		}
+		/**
+		* Notify about the invalidated file
+		*/
 		if (info && info.source === "hot-hook" && info.hotReloaded) {
 			debug_default("hot reloading %s, info %O", relativePath, info);
 			this.ui.logger.log(`${this.ui.colors.green("invalidated")} ${relativePath}`);
 			return;
 		}
+		/**
+		* Do not do anything when fullReload is not enabled.
+		*/
 		if (info && !info.fullReload) {
 			debug_default("ignoring full reload", relativePath, info);
 			return;
@@ -496,10 +1065,30 @@ var DevServer = class DevServer {
 		}
 		this.ui.logger.log(`${this.ui.colors.green(action)} ${relativePath}`);
 	}
+	/**
+	* Regenerates index files when a file is added or removed
+	*
+	* Updates the index generator to reflect file system changes by adding
+	* or removing files from the generated index files.
+	*
+	* @param filePath - Absolute path to the file that changed
+	* @param action - Whether the file was added or deleted
+	*/
 	#regenerateIndex(filePath, action) {
 		if (action === "add") return this.#indexGenerator.addFile(filePath);
 		return this.#indexGenerator.removeFile(filePath);
 	}
+	/**
+	* Re-scans routes when a file is modified during hot reloading
+	*
+	* Invalidates the routes cache for the given file and triggers route
+	* scanning hooks if the invalidation was successful.
+	*
+	* @param filePath - Absolute path to the file that was modified
+	*
+	* @example
+	* await devServer.#reScanRoutes('/path/to/routes.ts')
+	*/
 	async #reScanRoutes(filePath) {
 		if (!this.#routesScanner) return;
 		try {
@@ -509,18 +1098,47 @@ var DevServer = class DevServer {
 			this.ui.logger.fatal(error);
 		}
 	}
+	/**
+	* Processes routes received from the AdonisJS server
+	*
+	* Executes routesCommitted hooks and optionally scans routes if scanning
+	* hooks are registered. Creates a routes scanner instance if needed and
+	* processes routes for each domain.
+	*
+	* @param routesList - Routes organized by domain
+	*
+	* @example
+	* await devServer.#processRoutes({
+	*   'example.com': [
+	*     { pattern: '/', handler: 'HomeController.index' }
+	*   ]
+	* })
+	*/
 	#processRoutes = throttle(async (routesFileLocation) => {
 		try {
 			const scanRoutes = this.#hooks.has("routesScanning") || this.#hooks.has("routesScanned");
 			const shareRoutes = this.#hooks.has("routesCommitted");
+			/**
+			* Remove the routes file and return early when there are no
+			* hooks listening for routes related events
+			*/
 			if (!scanRoutes && !shareRoutes) {
 				unlink(routesFileLocation).catch(() => {});
 				return;
 			}
+			/**
+			* Read routes JSON, parse it and remove the file
+			*/
 			const routesJSON = await readFile(routesFileLocation, "utf-8");
 			const routesList = JSON.parse(routesJSON);
 			unlink(routesFileLocation).catch(() => {});
+			/**
+			* Notify about the existence of routes
+			*/
 			if (shareRoutes) await this.#hooks.runner("routesCommitted").run(this, routesList);
+			/**
+			* Scan routes and notify scanning and scanned hooks
+			*/
 			if (scanRoutes) {
 				this.#routesScanner = new RoutesScanner(this.cwdPath, []);
 				await this.#hooks.runner("routesScanning").run(this, this.#routesScanner);
@@ -532,12 +1150,22 @@ var DevServer = class DevServer {
 			this.ui.logger.fatal(error);
 		}
 	}, "processRoutes");
+	/**
+	* Registers hooks for file system events and server restart triggers
+	*
+	* Sets up event handlers that respond to file additions, changes, and removals
+	* by regenerating indexes and handling server restarts as needed.
+	*/
 	#registerServerRestartHooks() {
 		this.#hooks.add("fileAdded", (relativePath, absolutePath) => {
 			this.#regenerateIndex(absolutePath, "add");
 			this.#handleFileChange(relativePath, absolutePath, "add");
 		});
 		this.#hooks.add("fileChanged", (relativePath, absolutePath, info) => {
+			/**
+			* Rescan routes when the file is hot-reloaded or when the file is
+			* not part of the imports tree, but meant to be hot-reloaded
+			*/
 			if (info.hotReloaded || !info.hotReloaded && !info.fullReload) this.#reScanRoutes(absolutePath);
 			this.#handleFileChange(relativePath, absolutePath, "update", info);
 		});
@@ -546,6 +1174,23 @@ var DevServer = class DevServer {
 			this.#handleFileChange(relativePath, absolutePath, "delete");
 		});
 	}
+	/**
+	* Initializes the development server state and executes init hooks
+	*
+	* Parses TypeScript configuration, sets up file system, loads hooks,
+	* initializes the index generator, and prepares the server for the
+	* specified mode (HMR, watch, or static).
+	*
+	* @param ts - TypeScript module reference
+	* @param mode - Server mode (hmr, watch, or static)
+	* @returns True if initialization succeeds, false if tsconfig parsing fails
+	*
+	* @example
+	* const success = await devServer.#init(ts, 'hmr')
+	* if (!success) {
+	*   console.error('Failed to initialize dev server')
+	* }
+	*/
 	async #init(mode) {
 		const tsConfig = readTsConfig(this.cwdPath);
 		if (!tsConfig) {
@@ -573,16 +1218,40 @@ var DevServer = class DevServer {
 		]);
 		this.#registerServerRestartHooks();
 		this.#setupKeyboardShortcuts();
+		/**
+		* Run init hooks and clear them as they won't be executed
+		* ever again
+		*/
 		await this.#hooks.runner("init").run(this, this.#hooks, this.#indexGenerator);
 		this.#hooks.clear("init");
 		this.ui.logger.info("generating indexes...");
 		await this.#indexGenerator.generate();
 		return true;
 	}
+	/**
+	* Starts the HTTP server as a child process
+	*
+	* Creates a new Node.js child process to run the server script with the
+	* specified port and configuration. Sets up message handlers for server
+	* ready notifications, routes sharing, and hot-hook events. Executes
+	* devServerStarting hooks before spawning the process.
+	*
+	* @param port - Port number for the server to listen on
+	*
+	* @example
+	* await devServer.#startHTTPServer('3333')
+	*/
 	async #startHTTPServer(port, hmrPort) {
+		/**
+		* Execute the registered before creating the child process. This will allow
+		* hooks to modify the options before they are used.
+		*/
 		await this.#hooks.runner("devServerStarting").run(this);
 		debug_default("starting http server using \"%s\" file, options %O", this.scriptFile, this.options);
 		return new Promise((resolve) => {
+			/**
+			* Creating child process
+			*/
 			this.#httpServer = runNode(this.cwd, {
 				script: this.scriptFile,
 				env: {
@@ -630,14 +1299,52 @@ var DevServer = class DevServer {
 			});
 		});
 	}
+	/**
+	* Adds listener to get notified when dev server is closed
+	*
+	* Registers a callback function that will be invoked when the development
+	* server's child process exits. The callback receives the exit code.
+	*
+	* @param callback - Function to call when dev server closes
+	* @returns This DevServer instance for method chaining
+	*
+	* @example
+	* devServer.onClose((exitCode) => {
+	*   console.log(`Server closed with exit code: ${exitCode}`)
+	* })
+	*/
 	onClose(callback) {
 		this.#onClose = callback;
 		return this;
 	}
+	/**
+	* Adds listener to get notified when dev server encounters an error
+	*
+	* Registers a callback function that will be invoked when the development
+	* server's child process encounters an error or fails to start.
+	*
+	* @param callback - Function to call when dev server encounters an error
+	* @returns This DevServer instance for method chaining
+	*
+	* @example
+	* devServer.onError((error) => {
+	*   console.error('Dev server error:', error.message)
+	* })
+	*/
 	onError(callback) {
 		this.#onError = callback;
 		return this;
 	}
+	/**
+	* Closes watchers and terminates the running child process
+	*
+	* Cleans up keyboard shortcuts, stops file system watchers, and kills
+	* the HTTP server child process. This should be called when shutting down
+	* the development server.
+	*
+	* @example
+	* await devServer.close()
+	*/
 	async close() {
 		this.#cleanupKeyboardShortcuts();
 		await this.#watcher?.close();
@@ -646,6 +1353,19 @@ var DevServer = class DevServer {
 			this.#httpServer.kill("SIGKILL");
 		}
 	}
+	/**
+	* Starts the development server in static or HMR mode
+	*
+	* Initializes the server and starts the HTTP server. The mode is determined
+	* by the `hmr` option in DevServerOptions. In HMR mode, hot-hook is configured
+	* to enable hot module reloading.
+	*
+	* @param ts - TypeScript module reference
+	*
+	* @example
+	* const devServer = new DevServer(cwd, { hmr: true, hooks: [] })
+	* await devServer.start(ts)
+	*/
 	async start() {
 		if (!await this.#init(this.options.hmr ? "hmr" : "static")) return;
 		if (this.#mode === "hmr") {
@@ -681,6 +1401,21 @@ var DevServer = class DevServer {
 			});
 		});
 	}
+	/**
+	* Starts the development server in watch mode and restarts on file changes
+	*
+	* Initializes the server, starts the HTTP server, and sets up a file system
+	* watcher that monitors for changes. When files are added, modified, or deleted,
+	* the server automatically restarts. The watcher respects TypeScript project
+	* configuration and metaFiles settings.
+	*
+	* @param ts - TypeScript module reference
+	* @param options - Watch options including polling mode
+	*
+	* @example
+	* const devServer = new DevServer(cwd, { hooks: [] })
+	* await devServer.startAndWatch(ts, { poll: false })
+	*/
 	async startAndWatch(options) {
 		if (!await this.#init("watch")) return;
 		this.ui.logger.info("starting HTTP server...");
@@ -703,17 +1438,77 @@ var DevServer = class DevServer {
 		});
 	}
 };
+//#endregion
+//#region src/test_runner.ts
+/**
+* Exposes the API to run Japa tests and optionally watch for file
+* changes to re-run the tests.
+*
+* The TestRunner provides intelligent test execution with watch mode capabilities.
+* When files change, it can selectively run specific tests or the entire suite
+* based on what changed.
+*
+* The watch mode functions as follows:
+*  - If the changed file is a test file, then only tests for that file
+*    will be re-run.
+*  - Otherwise, all tests will re-run with respect to the initial
+*    filters applied when running the `node ace test` command.
+*
+* @example
+* const testRunner = new TestRunner(cwd, { suites: [], hooks: [] })
+* await testRunner.run()
+*
+* @example
+* // Run tests in watch mode
+* const testRunner = new TestRunner(cwd, { suites: [], hooks: [] })
+* await testRunner.runAndWatch(ts, { poll: false })
+*/
 var TestRunner = class {
+	/**
+	* External listeners that are invoked when child process
+	* gets an error or closes
+	*/
 	#onError;
 	#onClose;
+	/**
+	* The stickyPort is set by the startAndWatch method and we will
+	* continue to use this port during re-runs
+	*/
 	#stickyPort;
+	/**
+	* The stickyHmrPort is set by the start and the startAndWatch methods
+	* and we will continue to use that port during restart
+	*/
 	#stickyHmrPort;
+	/**
+	* Reference to chokidar watcher
+	*/
 	#watcher;
+	/**
+	* Reference to the test script child process
+	*/
 	#testsProcess;
+	/**
+	* Filesystem is used to decide which files to watch or entertain in watch
+	* mode
+	*/
 	#fileSystem;
+	/**
+	* Hooks to execute custom actions during the tests runner lifecycle
+	*/
 	#hooks;
+	/**
+	* Index generator for managing auto-generated index files
+	*/
 	#indexGenerator;
+	/**
+	* CLI UI instance for displaying colorful messages and progress information
+	*/
 	ui = cliui();
+	/**
+	* Re-runs the test child process and throttle concurrent calls to
+	* ensure we do not end up with a long loop of restarts
+	*/
 	#reRunTests = throttle(async (filters) => {
 		if (this.#testsProcess) {
 			this.#testsProcess.removeAllListeners();
@@ -721,15 +1516,41 @@ var TestRunner = class {
 		}
 		await this.#runTests(this.#stickyPort, this.#stickyHmrPort, filters);
 	}, "reRunTests");
+	/**
+	* The script file to run as a child process
+	*/
 	scriptFile = "bin/test.ts";
+	/**
+	* The current working directory URL
+	*/
 	cwd;
+	/**
+	* The current working directory path as a string
+	*/
 	cwdPath;
+	/**
+	* Test runner configuration options including filters, reporters, and hooks
+	*/
 	options;
+	/**
+	* Create a new TestRunner instance
+	*
+	* @param cwd - The current working directory URL
+	* @param options - Test runner configuration options
+	*/
 	constructor(cwd, options) {
 		this.cwd = cwd;
 		this.options = options;
 		this.cwdPath = string.toUnixSlash(fileURLToPath(this.cwd));
 	}
+	/**
+	* Convert test runner options to the CLI args
+	*
+	* Transforms the test runner configuration options into command-line
+	* arguments that can be passed to the test script.
+	*
+	* @returns Array of command-line arguments
+	*/
 	#convertOptionsToArgs() {
 		const args = [];
 		if (this.options.reporters) {
@@ -747,6 +1568,15 @@ var TestRunner = class {
 		}
 		return args;
 	}
+	/**
+	* Converts all known filters to CLI args
+	*
+	* Transforms test filters (suites, files, groups, tags, tests) into
+	* command-line arguments for the test script.
+	*
+	* @param filters - The test filters to convert
+	* @returns Array of command-line arguments representing the filters
+	*/
 	#convertFiltersToArgs(filters) {
 		const args = [];
 		if (filters.suites) args.push(...filters.suites);
@@ -768,13 +1598,37 @@ var TestRunner = class {
 		}
 		return args;
 	}
+	/**
+	* Conditionally clear the terminal screen
+	*
+	* Clears the terminal screen if the clearScreen option is enabled
+	* in the test runner configuration.
+	*/
 	#clearScreen() {
 		if (this.options.clearScreen) process.stdout.write("\x1Bc");
 	}
+	/**
+	* Runs tests as a child process
+	*
+	* Creates a Node.js child process to execute the test script with
+	* appropriate command-line arguments and environment variables.
+	* Handles process lifecycle and hook execution.
+	*
+	* @param port - The port number to set in the environment
+	* @param filters - Optional test filters to apply for this run
+	*/
 	async #runTests(port, hmrPort, filters) {
+		/**
+		* Execute the registered before creating the child process. This will allow
+		* hooks to modify the options before they are used.
+		*/
 		await this.#hooks.runner("testsStarting").run(this);
 		debug_default("running tests using \"%s\" file, options %O", this.scriptFile, this.options);
 		return new Promise(async (resolve) => {
+			/**
+			* If inline filters are defined, then we ignore the
+			* initial filters
+			*/
 			const mergedFilters = {
 				...this.options.filters,
 				...filters
@@ -813,6 +1667,16 @@ var TestRunner = class {
 			}).finally(() => resolve());
 		});
 	}
+	/**
+	* Handles file change event during watch mode
+	*
+	* Determines whether to run specific tests or all tests based on
+	* the type of file that changed. Test files trigger selective runs,
+	* while other files trigger full test suite runs.
+	*
+	* @param filePath - The path of the changed file
+	* @param action - The type of change (add, update, delete)
+	*/
 	#handleFileChange(relativePath, absolutePath, action) {
 		const file = this.#fileSystem.inspect(absolutePath, relativePath);
 		if (!file) return;
@@ -821,10 +1685,20 @@ var TestRunner = class {
 		if (file.fileType === "test") this.#reRunTests({ files: [relativePath] });
 		else this.#reRunTests();
 	}
+	/**
+	* Re-generates the index when a file is changed, but only in HMR
+	* mode
+	*/
 	#regenerateIndex(filePath, action) {
 		if (action === "add") return this.#indexGenerator.addFile(filePath);
 		return this.#indexGenerator.removeFile(filePath);
 	}
+	/**
+	* Registers inline hooks for file changes and test re-runs
+	*
+	* Sets up event handlers that respond to file system changes by
+	* triggering appropriate test runs based on the changed files.
+	*/
 	#registerServerRestartHooks() {
 		this.#hooks.add("fileAdded", (relativePath, absolutePath) => {
 			this.#regenerateIndex(absolutePath, "add");
@@ -839,14 +1713,32 @@ var TestRunner = class {
 			this.#handleFileChange(relativePath, absolutePath, "delete");
 		});
 	}
+	/**
+	* Add listener to get notified when test runner is closed
+	*
+	* @param callback - Function to call when test runner closes
+	* @returns This TestRunner instance for method chaining
+	*/
 	onClose(callback) {
 		this.#onClose = callback;
 		return this;
 	}
+	/**
+	* Add listener to get notified when test runner encounters an error
+	*
+	* @param callback - Function to call when test runner encounters an error
+	* @returns This TestRunner instance for method chaining
+	*/
 	onError(callback) {
 		this.#onError = callback;
 		return this;
 	}
+	/**
+	* Close watchers and running child processes
+	*
+	* Cleans up file system watchers and terminates any running test
+	* processes to ensure graceful shutdown.
+	*/
 	async close() {
 		await this.#watcher?.close();
 		if (this.#testsProcess) {
@@ -854,6 +1746,12 @@ var TestRunner = class {
 			this.#testsProcess.kill("SIGKILL");
 		}
 	}
+	/**
+	* Runs tests once without watching for file changes
+	*
+	* Executes the test suite a single time and exits. This is the
+	* equivalent of running tests in CI/CD environments.
+	*/
 	async run() {
 		this.#stickyPort = String(await getPort(this.cwd));
 		this.#stickyHmrPort = String(await getRandomPort({ port: 24678 }));
@@ -865,6 +1763,10 @@ var TestRunner = class {
 			"testsStarting",
 			"testsFinished"
 		]);
+		/**
+		* Run init hooks and clear them as they won't be executed
+		* ever again
+		*/
 		await this.#hooks.runner("init").run(this, this.#hooks, this.#indexGenerator);
 		this.#hooks.clear("init");
 		this.ui.logger.info("generating indexes...");
@@ -872,6 +1774,17 @@ var TestRunner = class {
 		this.ui.logger.info("booting application to run tests...");
 		await this.#runTests(this.#stickyPort, this.#stickyHmrPort);
 	}
+	/**
+	* Run tests in watch mode and re-run them when files change
+	*
+	* Starts the test runner in watch mode, monitoring the file system
+	* for changes and automatically re-running tests when relevant files
+	* are modified. Uses intelligent filtering to run only affected tests
+	* when possible.
+	*
+	* @param ts - TypeScript module reference for parsing configuration
+	* @param options - Watch options including polling mode for file system monitoring
+	*/
 	async runAndWatch(options) {
 		const tsConfig = readTsConfig(this.cwdPath);
 		if (!tsConfig) {
@@ -899,12 +1812,19 @@ var TestRunner = class {
 			"fileRemoved"
 		]);
 		this.#registerServerRestartHooks();
+		/**
+		* Run init hooks and clear them as they won't be executed
+		* ever again
+		*/
 		await this.#hooks.runner("init").run(this, this.#hooks, this.#indexGenerator);
 		this.#hooks.clear("init");
 		this.ui.logger.info("generating indexes...");
 		await this.#indexGenerator.generate();
 		this.ui.logger.info("booting application to run tests...");
 		await this.#runTests(this.#stickyPort, this.#stickyHmrPort);
+		/**
+		* Create watcher
+		*/
 		this.#watcher = watch({
 			usePolling: options?.poll ?? false,
 			cwd: this.cwdPath,
@@ -915,9 +1835,15 @@ var TestRunner = class {
 				return !this.#fileSystem.shouldWatchDirectory(file);
 			}
 		});
+		/**
+		* Notify the watcher is ready
+		*/
 		this.#watcher.on("ready", () => {
 			this.ui.logger.info("watching file system for changes...");
 		});
+		/**
+		* Cleanup when watcher dies
+		*/
 		this.#watcher.on("error", (error) => {
 			this.ui.logger.warning("file system watcher failure");
 			this.ui.logger.fatal(error);
@@ -945,4 +1871,5 @@ var TestRunner = class {
 		});
 	}
 };
+//#endregion
 export { Bundler, CodemodException, DevServer, FileBuffer, SUPPORTED_PACKAGE_MANAGERS, TestRunner, VirtualFileSystem };