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

package/build/index.js

@@ -1,183 +1,252 @@
 import {
-  debug_default
-} from "./chunk-RR4HCA4M.js";
+  IndexGenerator
+} from "./chunk-25Q3N5JR.js";
+import {
+  copyFiles,
+  debug_default,
+  getPort,
+  loadHooks,
+  memoize,
+  parseConfig,
+  run,
+  runNode,
+  throttle,
+  watch
+} from "./chunk-PORDZS62.js";
+
+// src/hooks.ts
+var hooks = {
+  /**
+   * Hook called during application initialization. This is the first hook
+   * that gets executed when the assembler starts up.
+   *
+   * @param callback - Function to execute when the init event occurs
+   *
+   * @example
+   * ```js
+   * hooks.init((app) => {
+   *   console.log('Application is initializing')
+   *   // Setup global configurations
+   * })
+   * ```
+   */
+  init(callback) {
+    return callback;
+  },
+  /**
+   * Hook called after routes have been committed to the router.
+   * This occurs after all route definitions have been processed.
+   *
+   * @param callback - Function to execute when routes are committed
+   *
+   * @example
+   * ```js
+   * hooks.routesCommitted((router) => {
+   *   console.log('All routes have been committed to the router')
+   *   // Perform route-based setup
+   * })
+   * ```
+   */
+  routesCommitted(callback) {
+    return callback;
+  },
+  /**
+   * Hook called when the assembler starts scanning for route files.
+   * This happens before any route files are actually processed.
+   *
+   * @param callback - Function to execute when route scanning begins
+   *
+   * @example
+   * ```js
+   * hooks.routesScanning(() => {
+   *   console.log('Starting to scan for route files')
+   *   // Setup route scanning configurations
+   * })
+   * ```
+   */
+  routesScanning(callback) {
+    return callback;
+  },
+  /**
+   * Hook called after all route files have been scanned and processed.
+   * This occurs once the route scanning phase is complete.
+   *
+   * @param callback - Function to execute when route scanning is finished
+   *
+   * @example
+   * ```js
+   * hooks.routesScanned((scannedRoutes) => {
+   *   console.log('Route scanning completed')
+   *   // Process scanned route information
+   * })
+   * ```
+   */
+  routesScanned(callback) {
+    return callback;
+  },
+  /**
+   * Hook called when a file is modified during development.
+   * This is triggered by the file watcher when changes are detected.
+   *
+   * @param callback - Function to execute when a file changes
+   *
+   * @example
+   * ```js
+   * hooks.fileChanged((filePath, stats) => {
+   *   console.log(`File changed: ${filePath}`)
+   *   // Handle file change logic
+   * })
+   * ```
+   */
+  fileChanged(callback) {
+    return callback;
+  },
+  /**
+   * Hook called when a new file is added during development.
+   * This is triggered by the file watcher when new files are created.
+   *
+   * @param callback - Function to execute when a file is added
+   *
+   * @example
+   * ```js
+   * hooks.fileAdded((filePath, stats) => {
+   *   console.log(`New file added: ${filePath}`)
+   *   // Handle new file logic
+   * })
+   * ```
+   */
+  fileAdded(callback) {
+    return callback;
+  },
+  /**
+   * Hook called when a file is removed during development.
+   * This is triggered by the file watcher when files are deleted.
+   *
+   * @param callback - Function to execute when a file is removed
+   *
+   * @example
+   * ```js
+   * hooks.fileRemoved((filePath) => {
+   *   console.log(`File removed: ${filePath}`)
+   *   // Handle file removal logic
+   * })
+   * ```
+   */
+  fileRemoved(callback) {
+    return callback;
+  },
+  /**
+   * Hook called when the development server is about to start.
+   * This occurs before the server begins listening for connections.
+   *
+   * @param callback - Function to execute when dev server is starting
+   *
+   * @example
+   * ```js
+   * hooks.devServerStarting((server) => {
+   *   console.log('Development server is starting')
+   *   // Setup server configurations
+   * })
+   * ```
+   */
+  devServerStarting(callback) {
+    return callback;
+  },
+  /**
+   * Hook called after the development server has successfully started.
+   * This occurs once the server is listening and ready to accept requests.
+   *
+   * @param callback - Function to execute when dev server has started
+   *
+   * @example
+   * ```js
+   * hooks.devServerStarted((server) => {
+   *   console.log(`Development server started on port ${server.port}`)
+   *   // Notify external services or open browser
+   * })
+   * ```
+   */
+  devServerStarted(callback) {
+    return callback;
+  },
+  /**
+   * Hook called when the build process is about to start.
+   * This occurs before any build tasks are executed.
+   *
+   * @param callback - Function to execute when build is starting
+   *
+   * @example
+   * ```js
+   * hooks.buildStarting((buildConfig) => {
+   *   console.log('Build process is starting')
+   *   // Setup build configurations or clean directories
+   * })
+   * ```
+   */
+  buildStarting(callback) {
+    return callback;
+  },
+  /**
+   * Hook called after the build process has completed.
+   * This occurs once all build tasks have finished executing.
+   *
+   * @param callback - Function to execute when build is finished
+   *
+   * @example
+   * ```js
+   * hooks.buildFinished((buildResult) => {
+   *   console.log('Build process completed')
+   *   // Deploy artifacts or notify build completion
+   * })
+   * ```
+   */
+  buildFinished(callback) {
+    return callback;
+  },
+  /**
+   * Hook called when the test suite is about to start.
+   * This occurs before any test files are executed.
+   *
+   * @param callback - Function to execute when tests are starting
+   *
+   * @example
+   * ```js
+   * hooks.testsStarting((testConfig) => {
+   *   console.log('Test suite is starting')
+   *   // Setup test database or mock services
+   * })
+   * ```
+   */
+  testsStarting(callback) {
+    return callback;
+  },
+  /**
+   * Hook called after the test suite has completed.
+   * This occurs once all test files have finished executing.
+   *
+   * @param callback - Function to execute when tests are finished
+   *
+   * @example
+   * ```js
+   * hooks.testsFinished((testResults) => {
+   *   console.log('Test suite completed')
+   *   // Generate test reports or cleanup test resources
+   * })
+   * ```
+   */
+  testsFinished(callback) {
+    return callback;
+  }
+};
 
 // src/bundler.ts
 import dedent from "dedent";
 import fs from "fs/promises";
 import { cliui } from "@poppinss/cliui";
-import { fileURLToPath as fileURLToPath2 } from "url";
-import { join as join2, relative as relative2 } from "path";
+import { fileURLToPath } from "url";
 import string from "@poppinss/utils/string";
+import { join, relative } from "path/posix";
 import { detectPackageManager } from "@antfu/install-pkg";
-
-// src/utils.ts
-import Cache from "tmp-cache";
-import { isJunk } from "junk";
-import fastGlob from "fast-glob";
-import Hooks from "@poppinss/hooks";
-import { existsSync } from "fs";
-import getRandomPort from "get-port";
-import { fileURLToPath } from "url";
-import { execaNode, execa } from "execa";
-import { importDefault } from "@poppinss/utils";
-import { copyFile, mkdir } from "fs/promises";
-import { EnvLoader, EnvParser } from "@adonisjs/env";
-import chokidar from "chokidar";
-import { basename, dirname, isAbsolute, join, relative } from "path";
-var DEFAULT_NODE_ARGS = ["--import=@poppinss/ts-exec", "--enable-source-maps"];
-function parseConfig(cwd, ts) {
-  const cwdPath = typeof cwd === "string" ? cwd : fileURLToPath(cwd);
-  const configFile = join(cwdPath, "tsconfig.json");
-  debug_default('parsing config file "%s"', configFile);
-  let hardException = null;
-  const parsedConfig = ts.getParsedCommandLineOfConfigFile(
-    configFile,
-    {},
-    {
-      ...ts.sys,
-      useCaseSensitiveFileNames: true,
-      getCurrentDirectory: () => cwdPath,
-      onUnRecoverableConfigFileDiagnostic: (error) => hardException = error
-    }
-  );
-  if (hardException) {
-    const compilerHost = ts.createCompilerHost({});
-    console.log(ts.formatDiagnosticsWithColorAndContext([hardException], compilerHost));
-    return;
-  }
-  if (parsedConfig.errors.length) {
-    const compilerHost = ts.createCompilerHost({});
-    console.log(ts.formatDiagnosticsWithColorAndContext(parsedConfig.errors, compilerHost));
-    return;
-  }
-  return parsedConfig;
-}
-function runNode(cwd, options) {
-  const childProcess = execaNode(options.script, options.scriptArgs, {
-    nodeOptions: DEFAULT_NODE_ARGS.concat(options.nodeArgs),
-    preferLocal: true,
-    windowsHide: false,
-    localDir: cwd,
-    cwd,
-    reject: options.reject ?? false,
-    buffer: false,
-    stdio: options.stdio || "inherit",
-    env: {
-      ...options.stdio === "pipe" ? { FORCE_COLOR: "true" } : {},
-      ...options.env
-    }
-  });
-  return childProcess;
-}
-function run(cwd, options) {
-  const childProcess = execa(options.script, options.scriptArgs, {
-    preferLocal: true,
-    windowsHide: false,
-    localDir: cwd,
-    cwd,
-    buffer: false,
-    stdio: options.stdio || "inherit",
-    env: {
-      ...options.stdio === "pipe" ? { FORCE_COLOR: "true" } : {},
-      ...options.env
-    }
-  });
-  return childProcess;
-}
-function watch(options) {
-  return chokidar.watch(["."], options);
-}
-async function getPort(cwd) {
-  if (process.env.PORT) {
-    return getRandomPort({ port: Number(process.env.PORT) });
-  }
-  const files = await new EnvLoader(cwd).load();
-  for (let file of files) {
-    const envVariables = await new EnvParser(file.contents).parse();
-    if (envVariables.PORT) {
-      return getRandomPort({ port: Number(envVariables.PORT) });
-    }
-  }
-  return getRandomPort({ port: 3333 });
-}
-async function copyFiles(files, cwd, outDir) {
-  const { paths, patterns } = files.reduce(
-    (result, file) => {
-      if (fastGlob.isDynamicPattern(file)) {
-        result.patterns.push(file);
-        return result;
-      }
-      if (existsSync(join(cwd, file))) {
-        result.paths.push(file);
-      }
-      return result;
-    },
-    { patterns: [], paths: [] }
-  );
-  debug_default("copyFiles inputs: %O, paths: %O, patterns: %O", files, paths, patterns);
-  const filePaths = paths.concat(await fastGlob(patterns, { cwd, dot: true })).filter((file) => {
-    return !isJunk(basename(file));
-  });
-  debug_default('copying files %O to destination "%s"', filePaths, outDir);
-  const copyPromises = filePaths.map(async (file) => {
-    const src = isAbsolute(file) ? file : join(cwd, file);
-    const dest = join(outDir, relative(cwd, src));
-    await mkdir(dirname(dest), { recursive: true });
-    return copyFile(src, dest);
-  });
-  return await Promise.all(copyPromises);
-}
-function memoize(fn, maxKeys) {
-  const cache = new Cache({ max: maxKeys });
-  return (input) => {
-    if (cache.has(input)) {
-      return cache.get(input);
-    }
-    return fn(input);
-  };
-}
-async function loadHooks(rcFileHooks, names) {
-  const groups = names.map((name) => {
-    return {
-      group: name,
-      hooks: rcFileHooks?.[name] ?? []
-    };
-  });
-  const hooks = new Hooks();
-  for (const { group, hooks: collection } of groups) {
-    for (const item of collection) {
-      hooks.add(group, await importDefault(item));
-    }
-  }
-  return hooks;
-}
-function throttle(fn, name) {
-  name = name || "throttled";
-  let isBusy = false;
-  let hasQueuedCalls = false;
-  let lastCallArgs;
-  async function throttled(...args) {
-    if (isBusy) {
-      debug_default('ignoring "%s" invocation as current execution is in progress', name);
-      hasQueuedCalls = true;
-      lastCallArgs = args;
-      return;
-    }
-    isBusy = true;
-    debug_default('executing "%s" function', name);
-    await fn(...args);
-    isBusy = false;
-    if (hasQueuedCalls) {
-      hasQueuedCalls = false;
-      debug_default('resuming and running latest "%s" invocation', name);
-      await throttled(...lastCallArgs);
-    }
-  }
-  return throttled;
-}
-
-// src/bundler.ts
 var SUPPORTED_PACKAGE_MANAGERS = {
   "npm": {
     packageManagerFiles: ["package-lock.json"],
@@ -201,25 +270,53 @@ var SUPPORTED_PACKAGE_MANAGERS = {
   }
 };
 var Bundler = class {
-  constructor(cwd, ts, options) {
-    this.cwd = cwd;
-    this.options = options;
-    this.#cwdPath = fileURLToPath2(this.cwd);
-    this.#ts = ts;
-  }
-  #cwdPath;
+  /**
+   * 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(relative2(this.#cwdPath, filePath));
+    return string.toUnixSlash(relative(this.cwdPath, filePath));
   }
   /**
    * Cleans up the build directory
@@ -247,13 +344,13 @@ var Bundler = class {
    */
   async #copyMetaFiles(outDir, additionalFilesToCopy) {
     const metaFiles = (this.options.metaFiles || []).map((file) => file.pattern).concat(additionalFilesToCopy);
-    await copyFiles(metaFiles, this.#cwdPath, outDir);
+    await copyFiles(metaFiles, this.cwdPath, outDir);
   }
   /**
    * Detect the package manager used by the project
    */
   async #detectPackageManager() {
-    const pkgManager = await detectPackageManager(this.#cwdPath);
+    const pkgManager = await detectPackageManager(this.cwdPath);
     if (pkgManager === "deno") {
       return "npm";
     }
@@ -268,7 +365,7 @@ var Bundler = class {
    * in a production environment.
    */
   async #createAceFile(outDir) {
-    const aceFileLocation = join2(outDir, "ace.js");
+    const aceFileLocation = join(outDir, "ace.js");
     const aceFileContent = dedent(
       /* JavaScript */
       `
@@ -286,15 +383,28 @@ var Bundler = class {
   }
   /**
    * 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.#hooks = await loadHooks(this.options.hooks, ["buildStarting", "buildFinished"]);
     this.packageManager = client ?? await this.#detectPackageManager() ?? "npm";
     const config = parseConfig(this.cwd, this.#ts);
     if (!config) {
       return false;
     }
-    const outDir = config.options.outDir || fileURLToPath2(new URL("build/", this.cwd));
+    this.ui.logger.info("loading hooks...");
+    this.#hooks = await loadHooks(this.options.hooks, ["init", "buildStarting", "buildFinished"]);
+    this.#indexGenerator = new IndexGenerator(this.cwdPath, this.ui.logger);
+    await this.#hooks.runner("init").run(this, this.#indexGenerator);
+    this.#hooks.clear("init");
+    this.ui.logger.info("generating indexes...");
+    await this.#indexGenerator.generate();
+    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);
     await this.#hooks.runner("buildStarting").run(this);
@@ -331,20 +441,19 @@ var Bundler = class {
 };
 
 // src/dev_server.ts
-import { relative as relative4 } from "path";
 import { cliui as cliui2 } from "@poppinss/cliui";
 import prettyHrtime from "pretty-hrtime";
-import { fileURLToPath as fileURLToPath4 } from "url";
+import { fileURLToPath as fileURLToPath2 } from "url";
 import string3 from "@poppinss/utils/string";
+import { join as join2, relative as relative3 } from "path/posix";
 import { RuntimeException } from "@poppinss/utils/exception";
 
 // src/file_system.ts
 import picomatch from "picomatch";
-import { fileURLToPath as fileURLToPath3 } from "url";
-import { join as join3, relative as relative3 } from "path";
+import { relative as relative2 } from "path/posix";
 import string2 from "@poppinss/utils/string";
 var DEFAULT_INCLUDES = ["**/*"];
-var ALWAYS_EXCLUDE = [".git/**", "coverage/**", ".github/**"];
+var ALWAYS_EXCLUDE = [".git/**", "coverage/**", ".github/**", ".adonisjs/**"];
 var DEFAULT_EXCLUDES = ["node_modules/**", "bower_components/**", "jspm_packages/**"];
 var FileSystem = class {
   /**
@@ -386,7 +495,7 @@ var FileSystem = class {
    */
   #isTestFile;
   /**
-   * References to includes and excludes
+   * References to includes and excludes glob patterns
    */
   #includes;
   #excludes;
@@ -414,11 +523,25 @@ var FileSystem = class {
     return this.#excludes;
   }
   /**
-   * Inspect a relative path to find its source in the project
-   */
-  inspect = memoize((filePath) => {
-    const relativePath = filePath;
-    const absolutePath = string2.toUnixSlash(join3(this.#cwd, relativePath));
+   * 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 ?? relative2(this.#cwd, absolutePath);
     if (this.#isScriptFile(relativePath) && (this.#scannedTypeScriptFiles.has(absolutePath) || this.#isPartOfBackendProject(relativePath))) {
       debug_default('backend project file "%s"', relativePath);
       const isTestFile = this.#isTestFile(relativePath);
@@ -451,63 +574,73 @@ var FileSystem = class {
     return null;
   });
   /**
-   * Returns true if the directory should be watched. Chokidar sends
-   * absolute unix paths to the ignored callback.
+   * 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.
    *
-   * You must use "shouldWatchFile" method for files and call this method
-   * for directories only.
+   * 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) => {
     if (absolutePath === this.#cwd) {
       debug_default("watching project root");
       return true;
     }
-    const relativePath = string2.toUnixSlash(relative3(this.#cwd, absolutePath));
+    const relativePath = relative2(this.#cwd, absolutePath);
     if (this.#isExcluded(relativePath)) {
       debug_default('watching "%s"', absolutePath);
       return false;
     }
     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 = string2.toUnixSlash(typeof cwd === "string" ? cwd : fileURLToPath3(cwd));
+    this.#cwd = cwd;
     this.#tsConfig = tsConfig;
     const files = tsConfig.fileNames;
     const metaFiles = rcFile.metaFiles ?? [];
     const testSuites = rcFile.suites ?? [];
     const outDir = tsConfig.raw.compilerOptions?.outDir;
-    files.forEach((file) => this.#scannedTypeScriptFiles.add(string2.toUnixSlash(file)));
+    for (const file of files) {
+      this.#scannedTypeScriptFiles.add(string2.toUnixSlash(file));
+    }
     this.#includes = tsConfig.raw.include || DEFAULT_INCLUDES;
     this.#excludes = ALWAYS_EXCLUDE.concat(
       tsConfig.raw.exclude || (outDir ? DEFAULT_EXCLUDES.concat(outDir) : DEFAULT_EXCLUDES)
     );
-    this.#isMetaFileWithReloadsEnabled = picomatch(
-      metaFiles.filter((file) => !!file.reloadServer).map((file) => file.pattern),
-      {
-        cwd: this.#cwd
+    const metaFilesWithReloads = [];
+    const metaFilesWithoutReloads = [];
+    for (const file of metaFiles) {
+      if (file.reloadServer) {
+        metaFilesWithReloads.push(file.pattern);
+      } else {
+        metaFilesWithoutReloads.push(file.pattern);
       }
-    );
-    this.#isMetaFileWithReloadsDisabled = picomatch(
-      metaFiles.filter((file) => !file.reloadServer).map((file) => file.pattern),
-      {
-        cwd: this.#cwd
-      }
-    );
-    this.#isTestFile = picomatch(
-      testSuites.flatMap((suite) => suite.files),
-      {
-        cwd: this.#cwd
-      }
-    );
-    this.#isIncluded = picomatch(this.#includes, {
-      cwd: this.#cwd
-    });
-    this.#isExcluded = picomatch(this.#excludes, {
-      cwd: this.#cwd
-    });
+    }
+    const testFilePatterns = testSuites.flatMap((suite) => suite.files);
+    const picomatcchOptions = { cwd: this.#cwd };
+    this.#isMetaFileWithReloadsEnabled = picomatch(metaFilesWithReloads, picomatcchOptions);
+    this.#isMetaFileWithReloadsDisabled = picomatch(metaFilesWithoutReloads, picomatcchOptions);
+    this.#isTestFile = picomatch(testFilePatterns, picomatcchOptions);
+    this.#isIncluded = picomatch(this.#includes, picomatcchOptions);
+    this.#isExcluded = picomatch(this.#excludes, picomatcchOptions);
     debug_default("initiating file system %O", {
       includes: this.#includes,
-      excludes: this.#includes,
+      excludes: this.#excludes,
       outDir,
       files,
       metaFiles,
@@ -515,11 +648,15 @@ var FileSystem = class {
     });
   }
   /**
-   * Returns a boolean telling if a file path is a script file or not.
+   * Determines if a file path represents a script file based on TypeScript configuration.
    *
-   * - Files ending with ".ts", ".tsx" are considered are script files.
-   * - Files ending with ".js" with "allowJs" option enabled are considered are script files.
-   * - Files ending with ".json" with "resolveJsonModule" option enabled are considered are script files.
+   * 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")) {
@@ -534,9 +671,13 @@ var FileSystem = class {
     return false;
   }
   /**
-   * Check if the file path is part of the backend TypeScript project. We use
-   * tsconfig "includes", "excludes", and "files" paths to test if the file
-   * should be considered or not.
+   * 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) {
     if (this.#isExcluded(relativePath)) {
@@ -555,18 +696,36 @@ var FileSystem = class {
    *
    * 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(relative3(this.#cwd, absolutePath)) !== null;
+    return this.inspect(absolutePath) !== null;
   }
 };
 
 // src/shortcuts_manager.ts
 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",
@@ -596,18 +755,32 @@ 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
+   * 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) {
@@ -618,7 +791,12 @@ var ShortcutsManager = class {
     process.stdin.on("data", this.#keyPressHandler);
   }
   /**
-   * Handle key press events
+   * 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 === "") {
@@ -630,7 +808,10 @@ var ShortcutsManager = class {
     }
   }
   /**
-   * Handle opening browser
+   * 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("");
@@ -639,7 +820,11 @@ var ShortcutsManager = class {
     open(this.#serverUrl);
   }
   /**
-   * Show available keyboard shortcuts
+   * 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("");
@@ -647,29 +832,58 @@ var ShortcutsManager = class {
     this.#shortcuts.forEach(({ key, description }) => this.#logger.log(`\xB7 ${key}: ${description}`));
   }
   /**
-   * Cleanup keyboard shortcuts
+   * 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);
+    process.stdin.pause();
+    process.stdin.unref();
     process.stdin.removeListener("data", this.#keyPressHandler);
     this.#keyPressHandler = void 0;
   }
 };
 
 // src/dev_server.ts
-var DevServer = class {
-  constructor(cwd, options) {
-    this.cwd = cwd;
-    this.options = options;
-    this.#cwdPath = fileURLToPath4(this.cwd);
-  }
+var DevServer = class _DevServer {
   /**
-   * File path computed from the cwd
+   * Pre-allocated info object for hot-hook change events to avoid repeated object creation
    */
-  #cwdPath;
+  static #HOT_HOOK_CHANGE_INFO = {
+    source: "hot-hook",
+    fullReload: false,
+    hotReloaded: false
+  };
+  /**
+   * 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
@@ -694,7 +908,7 @@ var DevServer = class {
    */
   #httpServer;
   /**
-   * Keyboard shortcuts manager
+   * Keyboard shortcuts manager instance
    */
   #shortcutsManager;
   /**
@@ -702,10 +916,18 @@ var DevServer = class {
    * using hot-hook
    */
   #fileSystem;
+  /**
+   * Index generator for managing auto-generated index files
+   */
+  #indexGenerator;
   /**
    * Hooks to execute custom actions during the dev server lifecycle
    */
   #hooks;
+  /**
+   * CLI UI instance for displaying colorful messages and progress information
+   */
+  ui = cliui2();
   /**
    * Restarts the HTTP server and throttle concurrent calls to
    * ensure we do not end up with a long loop of restarts
@@ -718,7 +940,10 @@ var DevServer = class {
     await this.#startHTTPServer(this.#stickyPort);
   }, "restartHTTPServer");
   /**
-   * Sets up keyboard shortcuts
+   * 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({
@@ -732,15 +957,14 @@ var DevServer = class {
     this.#shortcutsManager.setup();
   }
   /**
-   * Cleanup keyboard shortcuts
+   * 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();
   }
-  /**
-   * CLI UI to log colorful messages
-   */
-  ui = cliui2();
   /**
    * The mode in which the DevServer is running.
    */
@@ -752,17 +976,51 @@ var DevServer = class {
    */
   scriptFile = "bin/server.ts";
   /**
-   * Inspect if child process message is from AdonisJS HTTP server
+   * 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 = string3.toUnixSlash(fileURLToPath2(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";
   }
   /**
-   * Displays the server info and executes the hooks after the server has been
-   * started.
+   * 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 = { host, port: message.port };
     const serverUrl = `http://${host}:${message.port}`;
     this.#shortcutsManager?.setServerUrl(serverUrl);
     const displayMessage = this.ui.sticker().add(`Server address: ${this.ui.colors.cyan(serverUrl)}`).add(`Mode: ${this.ui.colors.cyan(this.mode)}`);
@@ -771,7 +1029,7 @@ var DevServer = class {
     }
     displayMessage.add(`Press ${this.ui.colors.dim("h")} to show help`);
     try {
-      await this.#hooks.runner("devServerStarted").run(this, displayMessage);
+      await this.#hooks.runner("devServerStarted").run(this, info, displayMessage);
     } catch (error) {
       this.ui.logger.error('One of the "devServerStarted" hooks failed');
       this.ui.logger.fatal(error);
@@ -779,13 +1037,22 @@ var DevServer = class {
     displayMessage.render();
   }
   /**
-   * Inspect if child process message is coming from hot-hook
+   * 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 clear the terminal screen
+   * 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) {
@@ -793,48 +1060,120 @@ var DevServer = class {
     }
   }
   /**
-   * Handles file change event
+   * 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(filePath, action, info) {
+  #handleFileChange(relativePath, absolutePath, action, info) {
     if ((action === "add" || action === "delete") && this.mode === "hmr") {
-      debug_default("ignoring add and delete actions in HMR mode %s", filePath);
+      debug_default("ignoring add and delete actions in HMR mode %s", relativePath);
       return;
     }
     if (info && info.source === "hot-hook" && info.hotReloaded) {
-      debug_default("hot reloading %s, info %O", filePath, info);
-      this.ui.logger.log(`${this.ui.colors.green("invalidated")} ${filePath}`);
+      debug_default("hot reloading %s, info %O", relativePath, info);
+      this.ui.logger.log(`${this.ui.colors.green("invalidated")} ${relativePath}`);
       return;
     }
     if (info && !info.fullReload) {
-      debug_default("ignoring full reload", filePath, info);
+      debug_default("ignoring full reload", relativePath, info);
       return;
     }
-    const file = this.#fileSystem.inspect(filePath);
+    const file = this.#fileSystem.inspect(absolutePath, relativePath);
     if (!file) {
       return;
     }
     if (file.reloadServer) {
       this.#clearScreen();
-      this.ui.logger.log(`${this.ui.colors.green(action)} ${filePath}`);
+      this.ui.logger.log(`${this.ui.colors.green(action)} ${relativePath}`);
       this.#restartHTTPServer();
       return;
     }
-    this.ui.logger.log(`${this.ui.colors.green(action)} ${filePath}`);
+    this.ui.logger.log(`${this.ui.colors.green(action)} ${relativePath}`);
   }
   /**
-   * Registers inline hooks for the file changes and restarts the
-   * HTTP server when a file gets changed.
+   * 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);
+  }
+  /**
+   * 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", (filePath) => this.#handleFileChange(filePath, "add"));
+    this.#hooks.add("fileAdded", (relativePath, absolutePath) => {
+      this.#regenerateIndex(absolutePath, "add");
+      this.#handleFileChange(relativePath, absolutePath, "add");
+    });
     this.#hooks.add(
       "fileChanged",
-      (filePath, info) => this.#handleFileChange(filePath, "update", info)
+      (relativePath, absolutePath, info) => this.#handleFileChange(relativePath, absolutePath, "update", info)
     );
-    this.#hooks.add("fileRemoved", (filePath) => this.#handleFileChange(filePath, "delete"));
+    this.#hooks.add("fileRemoved", (relativePath, absolutePath) => {
+      this.#regenerateIndex(absolutePath, "delete");
+      this.#handleFileChange(relativePath, absolutePath, "delete");
+    });
+  }
+  /**
+   * Initiate the state for DevServer and executes the init hooks
+   */
+  async #init(ts, mode) {
+    const tsConfig = parseConfig(this.cwd, ts);
+    if (!tsConfig) {
+      this.#onError?.(new RuntimeException("Unable to parse tsconfig file"));
+      return false;
+    }
+    this.#mode = mode;
+    this.#clearScreen();
+    this.ui.logger.info(`starting server in ${this.#mode} mode...`);
+    this.#indexGenerator = new IndexGenerator(this.cwdPath, this.ui.logger);
+    this.#stickyPort = String(await getPort(this.cwd));
+    this.#fileSystem = new FileSystem(this.cwdPath, tsConfig, this.options);
+    this.ui.logger.info("loading hooks...");
+    this.#hooks = await loadHooks(this.options.hooks, [
+      "init",
+      "routesCommitted",
+      "routesScanning",
+      "routesScanned",
+      "devServerStarting",
+      "devServerStarted",
+      "fileAdded",
+      "fileChanged",
+      "fileRemoved"
+    ]);
+    this.#registerServerRestartHooks();
+    this.#setupKeyboardShortcuts();
+    await this.#hooks.runner("init").run(this, this.#indexGenerator);
+    this.#hooks.clear("init");
+    this.ui.logger.info("generating indexes...");
+    await this.#indexGenerator.generate();
+    return true;
   }
   /**
-   * Starts the HTTP server
+   * 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 and hot-hook events.
+   *
+   * @param port - Port number for the server to listen on
    */
   async #startHTTPServer(port) {
     await this.#hooks.runner("devServerStarting").run(this);
@@ -854,45 +1193,21 @@ var DevServer = class {
           resolve();
         } else if (this.#mode === "hmr" && this.#isHotHookMessage(message)) {
           debug_default("received hot-hook message %O", message);
+          const absolutePath = message.path ? string3.toUnixSlash(message.path) : "";
+          const relativePath = relative3(this.cwdPath, absolutePath);
           if (message.type === "hot-hook:file-changed") {
-            switch (message.action) {
-              case "add":
-                this.#hooks.runner("fileAdded").run(string3.toUnixSlash(relative4(this.#cwdPath, message.path)), this);
-                break;
-              case "change":
-                this.#hooks.runner("fileChanged").run(
-                  string3.toUnixSlash(relative4(this.#cwdPath, message.path)),
-                  {
-                    source: "hot-hook",
-                    fullReload: false,
-                    hotReloaded: false
-                  },
-                  this
-                );
-                break;
-              case "unlink":
-                this.#hooks.runner("fileRemoved").run(string3.toUnixSlash(relative4(this.#cwdPath, message.path)), this);
+            const { action } = message;
+            if (action === "add") {
+              this.#hooks.runner("fileAdded").run(relativePath, absolutePath, this);
+            } else if (action === "change") {
+              this.#hooks.runner("fileChanged").run(relativePath, absolutePath, _DevServer.#HOT_HOOK_CHANGE_INFO, this);
+            } else if (action === "unlink") {
+              this.#hooks.runner("fileRemoved").run(relativePath, absolutePath, this);
             }
           } else if (message.type === "hot-hook:full-reload") {
-            this.#hooks.runner("fileChanged").run(
-              string3.toUnixSlash(relative4(this.#cwdPath, message.path)),
-              {
-                source: "hot-hook",
-                fullReload: true,
-                hotReloaded: false
-              },
-              this
-            );
+            this.#hooks.runner("fileChanged").run(relativePath, absolutePath, _DevServer.#HOT_HOOK_FULL_RELOAD_INFO, this);
           } else if (message.type === "hot-hook:invalidated") {
-            this.#hooks.runner("fileChanged").run(
-              string3.toUnixSlash(relative4(this.#cwdPath, message.path)),
-              {
-                source: "hot-hook",
-                fullReload: false,
-                hotReloaded: true
-              },
-              this
-            );
+            this.#hooks.runner("fileChanged").run(relativePath, absolutePath, _DevServer.#HOT_HOOK_INVALIDATED_INFO, this);
           }
         }
       });
@@ -914,16 +1229,20 @@ var DevServer = class {
     });
   }
   /**
-   * Add listener to get notified when dev server is
-   * closed
+   * Add listener to get notified when dev server is closed
+   *
+   * @param callback - Function to call when dev server closes
+   * @returns This DevServer instance for method chaining
    */
   onClose(callback) {
     this.#onClose = callback;
     return this;
   }
   /**
-   * Add listener to get notified when dev server exists
-   * with an error
+   * Add listener to get notified when dev server encounters an error
+   *
+   * @param callback - Function to call when dev server encounters an error
+   * @returns This DevServer instance for method chaining
    */
   onError(callback) {
     this.#onError = callback;
@@ -941,27 +1260,17 @@ var DevServer = class {
     }
   }
   /**
-   * Start the development server
+   * Start the development server in static or HMR mode
+   *
+   * @param ts - TypeScript module reference
    */
   async start(ts) {
-    const tsConfig = parseConfig(this.cwd, ts);
-    if (!tsConfig) {
-      this.#onError?.(new RuntimeException("Unable to parse tsconfig file"));
+    const initiated = await this.#init(ts, this.options.hmr ? "hmr" : "static");
+    if (!initiated) {
       return;
     }
-    this.#stickyPort = String(await getPort(this.cwd));
-    this.#fileSystem = new FileSystem(this.cwd, tsConfig, this.options);
-    this.#hooks = await loadHooks(this.options.hooks, [
-      "devServerStarting",
-      "devServerStarted",
-      "fileAdded",
-      "fileChanged",
-      "fileRemoved"
-    ]);
-    this.#registerServerRestartHooks();
-    if (this.options.hmr) {
-      this.#mode = "hmr";
-      this.options.nodeArgs = this.options.nodeArgs.concat("--import=hot-hook/register");
+    if (this.#mode === "hmr") {
+      this.options.nodeArgs.push("--import=hot-hook/register");
       this.options.env = {
         ...this.options.env,
         HOT_HOOK_INCLUDE: this.#fileSystem.includes.join(","),
@@ -969,38 +1278,25 @@ var DevServer = class {
         HOT_HOOK_RESTART: (this.options.metaFiles ?? []).filter(({ reloadServer }) => !!reloadServer).map(({ pattern }) => pattern).join(",")
       };
     }
-    this.#clearScreen();
-    this.#setupKeyboardShortcuts();
     this.ui.logger.info("starting HTTP server...");
     await this.#startHTTPServer(this.#stickyPort);
   }
   /**
-   * Start the development server in watch mode
+   * Start the development server in watch mode and restart on file changes
+   *
+   * @param ts - TypeScript module reference
+   * @param options - Watch options including polling mode
    */
   async startAndWatch(ts, options) {
-    const tsConfig = parseConfig(this.cwd, ts);
-    if (!tsConfig) {
-      this.#onError?.(new RuntimeException("Unable to parse tsconfig file"));
+    const initiated = await this.#init(ts, "watch");
+    if (!initiated) {
       return;
     }
-    this.#mode = "watch";
-    this.#stickyPort = String(await getPort(this.cwd));
-    this.#fileSystem = new FileSystem(this.cwd, tsConfig, this.options);
-    this.#hooks = await loadHooks(this.options.hooks, [
-      "devServerStarting",
-      "devServerStarted",
-      "fileAdded",
-      "fileChanged",
-      "fileRemoved"
-    ]);
-    this.#registerServerRestartHooks();
-    this.#clearScreen();
-    this.#setupKeyboardShortcuts();
     this.ui.logger.info("starting HTTP server...");
     await this.#startHTTPServer(this.#stickyPort);
     this.#watcher = watch({
       usePolling: options?.poll ?? false,
-      cwd: this.#cwdPath,
+      cwd: this.cwdPath,
       ignoreInitial: true,
       ignored: (file, stats) => {
         if (!stats) {
@@ -1021,39 +1317,31 @@ var DevServer = class {
       this.#onError?.(error);
       this.#watcher?.close();
     });
-    this.#watcher.on(
-      "add",
-      (filePath) => this.#hooks.runner("fileAdded").run(string3.toUnixSlash(filePath), this)
-    );
-    this.#watcher.on(
-      "change",
-      (filePath) => this.#hooks.runner("fileChanged").run(
-        string3.toUnixSlash(filePath),
-        {
-          source: "watcher",
-          fullReload: true,
-          hotReloaded: false
-        },
-        this
-      )
-    );
-    this.#watcher.on(
-      "unlink",
-      (filePath) => this.#hooks.runner("fileRemoved").run(string3.toUnixSlash(filePath), this)
-    );
+    this.#watcher.on("add", (filePath) => {
+      const relativePath = string3.toUnixSlash(filePath);
+      const absolutePath = join2(this.cwdPath, relativePath);
+      this.#hooks.runner("fileAdded").run(relativePath, absolutePath, this);
+    });
+    this.#watcher.on("change", (filePath) => {
+      const relativePath = string3.toUnixSlash(filePath);
+      const absolutePath = join2(this.cwdPath, relativePath);
+      this.#hooks.runner("fileChanged").run(relativePath, absolutePath, _DevServer.#WATCHER_INFO, this);
+    });
+    this.#watcher.on("unlink", (filePath) => {
+      const relativePath = string3.toUnixSlash(filePath);
+      const absolutePath = join2(this.cwdPath, relativePath);
+      this.#hooks.runner("fileRemoved").run(relativePath, absolutePath, this);
+    });
   }
 };
 
 // src/test_runner.ts
+import { join as join3 } from "path/posix";
 import { cliui as cliui3 } from "@poppinss/cliui";
-import { fileURLToPath as fileURLToPath5 } from "url";
+import { fileURLToPath as fileURLToPath3 } from "url";
 import string4 from "@poppinss/utils/string";
 import { RuntimeException as RuntimeException2 } from "@poppinss/utils/exception";
 var TestRunner = class {
-  constructor(cwd, options) {
-    this.cwd = cwd;
-    this.options = options;
-  }
   /**
    * External listeners that are invoked when child process
    * gets an error or closes
@@ -1082,6 +1370,14 @@ var TestRunner = class {
    * 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 = cliui3();
   /**
    * Re-runs the test child process and throttle concurrent calls to
    * ensure we do not end up with a long loop of restarts
@@ -1093,16 +1389,40 @@ var TestRunner = class {
     }
     await this.#runTests(this.#stickyPort, filters);
   }, "reRunTests");
-  /**
-   * CLI UI to log colorful messages
-   */
-  ui = cliui3();
   /**
    * 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 = string4.toUnixSlash(fileURLToPath3(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 = [];
@@ -1124,7 +1444,13 @@ var TestRunner = class {
     return args;
   }
   /**
-   * Converts all known filters to CLI 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 = [];
@@ -1151,6 +1477,9 @@ var TestRunner = class {
   }
   /**
    * 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) {
@@ -1158,18 +1487,25 @@ var TestRunner = class {
     }
   }
   /**
-   * Runs tests
+   * 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, filters) {
     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) => {
-      const scriptArgs = this.#convertOptionsToArgs().concat(this.options.scriptArgs).concat(
-        this.#convertFiltersToArgs({
-          ...this.options.filters,
-          ...filters
-        })
-      );
+      const mergedFilters = { ...this.options.filters, ...filters };
+      const scriptArgs = [
+        ...this.#convertOptionsToArgs(),
+        ...this.options.scriptArgs,
+        ...this.#convertFiltersToArgs(mergedFilters)
+      ];
       this.#testsProcess = runNode(this.cwd, {
         script: this.scriptFile,
         reject: true,
@@ -1198,41 +1534,73 @@ var TestRunner = class {
     });
   }
   /**
-   * Handles file change event
+   * 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(filePath, action) {
-    const file = this.#fileSystem.inspect(filePath);
+  #handleFileChange(relativePath, absolutePath, action) {
+    const file = this.#fileSystem.inspect(absolutePath, relativePath);
     if (!file) {
       return;
     }
     this.#clearScreen();
-    this.ui.logger.log(`${this.ui.colors.green(action)} ${filePath}`);
+    this.ui.logger.log(`${this.ui.colors.green(action)} ${relativePath}`);
     if (file.fileType === "test") {
-      this.#reRunTests({ files: [filePath] });
+      this.#reRunTests({ files: [relativePath] });
     } else {
       this.#reRunTests();
     }
   }
   /**
-   * Registers inline hooks for the file changes and restarts the
-   * HTTP server when a file gets changed.
+   * 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", (filePath) => this.#handleFileChange(filePath, "add"));
-    this.#hooks.add("fileChanged", (filePath) => this.#handleFileChange(filePath, "update"));
-    this.#hooks.add("fileRemoved", (filePath) => this.#handleFileChange(filePath, "delete"));
+    this.#hooks.add("fileAdded", (relativePath, absolutePath) => {
+      this.#regenerateIndex(absolutePath, "add");
+      this.#handleFileChange(relativePath, absolutePath, "add");
+    });
+    this.#hooks.add("fileChanged", (relativePath, absolutePath) => {
+      this.#regenerateIndex(absolutePath, "add");
+      this.#handleFileChange(relativePath, absolutePath, "update");
+    });
+    this.#hooks.add("fileRemoved", (relativePath, absolutePath) => {
+      this.#regenerateIndex(absolutePath, "delete");
+      this.#handleFileChange(relativePath, absolutePath, "delete");
+    });
   }
   /**
-   * Add listener to get notified when dev server is
-   * closed
+   * 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 dev server exists
-   * with an error
+   * 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;
@@ -1240,6 +1608,9 @@ var TestRunner = class {
   }
   /**
    * 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();
@@ -1249,23 +1620,34 @@ var TestRunner = class {
     }
   }
   /**
-   * Runs tests
+   * 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.#hooks = await loadHooks(this.options.hooks, [
-      "testsStarting",
-      "testsFinished",
-      "fileAdded",
-      "fileChanged",
-      "fileRemoved"
-    ]);
+    this.#indexGenerator = new IndexGenerator(this.cwdPath, this.ui.logger);
     this.#clearScreen();
+    this.ui.logger.info("loading hooks...");
+    this.#hooks = await loadHooks(this.options.hooks, ["init", "testsStarting", "testsFinished"]);
+    await this.#hooks.runner("init").run(this, 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);
   }
   /**
-   * Run tests in watch mode
+   * 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(ts, options) {
     const tsConfig = parseConfig(this.cwd, ts);
@@ -1274,7 +1656,8 @@ var TestRunner = class {
       return;
     }
     this.#stickyPort = String(await getPort(this.cwd));
-    this.#fileSystem = new FileSystem(this.cwd, tsConfig, {
+    this.#indexGenerator = new IndexGenerator(this.cwdPath, this.ui.logger);
+    this.#fileSystem = new FileSystem(this.cwdPath, tsConfig, {
       ...this.options,
       suites: this.options.suites?.filter((suite) => {
         if (this.options.filters.suites) {
@@ -1283,7 +1666,10 @@ var TestRunner = class {
         return true;
       })
     });
+    this.#clearScreen();
+    this.ui.logger.info("loading hooks...");
     this.#hooks = await loadHooks(this.options.hooks, [
+      "init",
       "testsStarting",
       "testsFinished",
       "fileAdded",
@@ -1291,12 +1677,15 @@ var TestRunner = class {
       "fileRemoved"
     ]);
     this.#registerServerRestartHooks();
-    this.#clearScreen();
+    await this.#hooks.runner("init").run(this, 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.#watcher = watch({
       usePolling: options?.poll ?? false,
-      cwd: fileURLToPath5(this.cwd),
+      cwd: this.cwdPath,
       ignoreInitial: true,
       ignored: (file, stats) => {
         if (!stats) {
@@ -1317,30 +1706,36 @@ var TestRunner = class {
       this.#onError?.(error);
       this.#watcher?.close();
     });
-    this.#watcher.on(
-      "add",
-      (filePath) => this.#hooks.runner("fileAdded").run(string4.toUnixSlash(filePath), this)
-    );
-    this.#watcher.on(
-      "change",
-      (filePath) => this.#hooks.runner("fileChanged").run(
-        string4.toUnixSlash(filePath),
+    this.#watcher.on("add", (filePath) => {
+      const relativePath = string4.toUnixSlash(filePath);
+      const absolutePath = join3(this.cwdPath, filePath);
+      this.#hooks.runner("fileAdded").run(relativePath, absolutePath, this);
+    });
+    this.#watcher.on("change", (filePath) => {
+      const relativePath = string4.toUnixSlash(filePath);
+      const absolutePath = join3(this.cwdPath, filePath);
+      this.#hooks.runner("fileChanged").run(
+        relativePath,
+        absolutePath,
         {
           source: "watcher",
           fullReload: true,
           hotReloaded: false
         },
         this
-      )
-    );
-    this.#watcher.on(
-      "unlink",
-      (filePath) => this.#hooks.runner("fileRemoved").run(string4.toUnixSlash(filePath), this)
-    );
+      );
+    });
+    this.#watcher.on("unlink", (filePath) => {
+      const relativePath = string4.toUnixSlash(filePath);
+      const absolutePath = join3(this.cwdPath, filePath);
+      this.#hooks.runner("fileRemoved").run(relativePath, absolutePath, this);
+    });
   }
 };
 export {
   Bundler,
   DevServer,
-  TestRunner
+  SUPPORTED_PACKAGE_MANAGERS,
+  TestRunner,
+  hooks
 };