@adonisjs/assembler 8.0.0-next.4 → 8.0.0-next.6

package/README.md

@@ -420,83 +420,111 @@ export const policies = {
 }
 ```
 
-### makeEntityIndex
-The method is used to create an index file for a collection of entities discovered from one or more root folders. We use this method to create an index file for controllers or generate types for Inertia pages.
+## Index generator
+
+The `IndexGenerator` is a core concept in Assembler that is used to watch the filesystem and create barrel files or types from a source directory.
+
+For example, the core of the framework uses the following config to generate controllers, events, and listeners barrel file.
 
 ```ts
-const transformer = new CodeTransformer(appRoot)
+import hooks from '@adonisjs/assembler/hooks'
+
+export default hooks.init((type, parent, indexGenerator) => {
+  indexGenerator.add('controllers', {
+    source: './app/controllers',
+    importAlias: '#controllers',
+    as: 'barrelFile',
+    exportName: 'controllers',
+    removeSuffix: 'controllers',
+    output: './.adonisjs/server/controllers.ts',
+  })
 
-const output = await transformer.makeEntityIndex({
-  source: 'app/controllers',
-  importAlias: '#controllers'
-}, {
-  destination: '.adonisjs/backend/controllers',
-  exportName: 'controllers'
-})
+  indexGenerator.add('events', {
+    source: './app/events',
+    importAlias: '#events',
+    as: 'barrelFile',
+    exportName: 'events',
+    output: './.adonisjs/server/events.ts',
+  })
 
-/**
-  export const controllers = {
-    SignupController: () => import('#controllers/auth/signup_controller'),
-    PostsController: () => import('#controllers/posts_controller'),
-    HomePage: () => import('#controllers/public/home_page'),
-    UserPostsController: () => import('#controllers/user/posts_controller'),
-  }
- */
+  indexGenerator.add('listeners', {
+    source: './app/listeners',
+    importAlias: '#listeners',
+    as: 'barrelFile',
+    exportName: 'listeners',
+    removeSuffix: 'listener',
+    output: './.adonisjs/server/listeners.ts',
+  })
+})
 ```
 
-If you would like to remove the `Controller` suffix from the key (which we do in our official generator), then you can specify the `removeNameSuffix` option.
+Once the configurations have been registered with the `IndexGenerator`, it will scan the needed directories and generate the output files. Additionally, the file watchers will re-trigger the index generation when a file is added or removed from the source directory.
 
-```ts
-const output = await transformer.makeEntityIndex({
-  source: 'app/controllers',
-  importAlias: '#controllers'
-}, {
-  destination: '.adonisjs/backend/controllers',
-  exportName: 'controllers',
-  removeNameSuffix: 'controller'
-})
+### Barrel file generation
+
+Barrel files provide a single entry point by exporting a collection of lazily imported entities, recursively gathered from a source directory. The `IndexGenerator` automates this process by scanning nested directories and generating import mappings that mirror the file structure.
+
+For example, given the following `controllers` directory structure:
+
+```sh
+app/controllers/
+├── auth/
+│   ├── login_controller.ts
+│   └── register_controller.ts
+├── blog/
+│   ├── posts_controller.ts
+│   └── post_comments_controller.ts
+└── users_controller.ts
 ```
 
-For more advanced use-cases, you can specify the `computeBaseName` method to self compute the key name for the collection.
+When processed with the controllers configuration, the `IndexGenerator` produces a barrel file that reflects the directory hierarchy as nested objects, using capitalized file names as property keys.
 
 ```ts
-import StringBuilder from '@poppinss/utils/string_builder'
-
-const output = await transformer.makeEntityIndex({
-  source: 'app/controllers',
-  importAlias: '#controllers'
-}, {
-  destination: '.adonisjs/backend/controllers',
-  exportName: 'controllers',
-  computeBaseName(filePath, sourcePath) {
-    const baseName = relative(sourcePath, filePath)
-    return new StringBuilder(baseName).toUnixSlash().removeExtension().removeSuffix('Controller').toString()
+export const controllers = {
+  auth: {
+    Login: () => import('#controllers/auth/login_controller'),
+    Register: () => import('#controllers/auth/register_controller'),
   },
-})
+  blog: {
+    Posts: () => import('#controllers/blog/posts_controller'),
+    PostComments: () => import('#controllers/blog/post_comments_controller'),
+  },
+  Users: () => import('#controllers/users_controller'),
+}
 ```
 
-#### Controlling the output
-The output is an object with key-value pair in which the value is a lazily imported module. However, you can customize the output to generate a TypeScript type using the `computeOutput` method.
+### Types generation
+
+To generate a types file, register a custom callback that takes an instance of the `VirtualFileSystem` and updates the output string via the `buffer` object. 
+
+The collection is represented as key–value pairs:
+
+- **Key** — the relative path (without extension) from the root of the source directory.
+- **Value** — an object containing the file's `importPath`, `relativePath`, and `absolutePath`.
 
 ```ts
-const output = await transformer.makeEntityIndex(
-  { source: './inertia/pages', allowedExtensions: ['.tsx'] },
-  {
-    destination: outputPath,
-    computeOutput(entries) {
-      return entries
-        .reduce<string[]>(
-          (result, entry) => {
-            result.push(`${entry.name}: typeof import('${entry.importPath}')`)
-            return result
-          },
-          [`declare module '@adonisjs/inertia' {`, 'export interface Pages {']
+import hooks from '@adonisjs/assembler/hooks'
+
+export default hooks.init((type, parent, indexGenerator) => {
+  indexGenerator.add('inertiaPages', {
+    source: './inertia/pages',
+    as: (vfs, buffer) => {
+      buffer.write(`declare module '@adonisjs/inertia' {`).indent()
+      buffer.write(`export interface Pages {`).indent()
+
+      const files = vfs.asList()
+      Object.keys(files).forEach((filePath) => {
+        buffer.write(
+          `'${filePath}': InferPageProps<typeof import('${file.importPath}').default>`
         )
-        .concat('}', '}')
-        .join('\n')
+      })
+
+      buffer.dedent().write('}')
+      buffer.dedent().write('}')
     },
-  }
-)
+    output: './.adonisjs/server/inertia_pages.d.ts',
+  })
+})
 ```
 
 ## Contributing

package/build/chunk-F4RAGKQN.js

@@ -0,0 +1,387 @@
+// src/debug.ts
+import { debuglog } from "util";
+var debug_default = debuglog("adonisjs:assembler");
+
+// src/virtual_file_system.ts
+import { fdir } from "fdir";
+import Cache2 from "tmp-cache";
+import { relative as relative2 } from "path/posix";
+import lodash from "@poppinss/utils/lodash";
+import string from "@poppinss/utils/string";
+import { readFile } from "fs/promises";
+import { naturalSort } from "@poppinss/utils";
+import { Lang, parse } from "@ast-grep/napi";
+import picomatch from "picomatch";
+
+// 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, cwd).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, ...args) => {
+    if (cache.has(input)) {
+      return cache.get(input);
+    }
+    return fn(input, ...args);
+  };
+}
+function isRelative(pathValue) {
+  return pathValue.startsWith("./") || pathValue.startsWith("../");
+}
+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;
+}
+function removeExtension(filePath) {
+  return filePath.substring(0, filePath.lastIndexOf("."));
+}
+
+// src/virtual_file_system.ts
+var BYPASS_FN = (input) => input;
+var DEFAULT_GLOB = ["**/!(*.d).ts", "**/*.tsx", "**/*.js"];
+var VirtualFileSystem = class {
+  /**
+   * Absolute path to the source directory from where to read the files.
+   * Additionally, a glob pattern or a filter could be specified to
+   * narrow down the scanned files list.
+   */
+  #source;
+  /**
+   * Filesystem options
+   */
+  #options;
+  /**
+   * Files collected from the initial scan with pre-computed relative paths
+   */
+  #files = /* @__PURE__ */ new Map();
+  /**
+   * LRU cache storing parsed AST nodes by file path with size limit
+   */
+  #astCache = new Cache2({ max: 60 });
+  /**
+   * Matcher is defined when glob is defined via the options
+   */
+  #matcher;
+  /**
+   * Picomatch options used for file pattern matching
+   */
+  #picoMatchOptions;
+  /**
+   * Create a new VirtualFileSystem instance
+   *
+   * @param source - Absolute path to the source directory
+   * @param options - Optional configuration for file filtering and processing
+   */
+  constructor(source, options) {
+    this.#source = source;
+    this.#options = options ?? {};
+    this.#picoMatchOptions = {
+      cwd: this.#source
+    };
+    this.#matcher = picomatch(this.#options.glob ?? DEFAULT_GLOB, this.#picoMatchOptions);
+  }
+  /**
+   * Scans the filesystem to collect the files. Newly files must
+   * be added via the ".add" method.
+   *
+   * This method performs an initial scan of the source directory using
+   * the configured glob patterns and populates the internal file list.
+   */
+  async scan() {
+    debug_default('fetching entities from source "%s"', this.#source);
+    const filesList = await new fdir().globWithOptions(this.#options.glob ?? DEFAULT_GLOB, this.#picoMatchOptions).withFullPaths().crawl(this.#source).withPromise();
+    debug_default("scanned files %O", filesList);
+    const sortedFiles = filesList.sort(naturalSort);
+    this.#files.clear();
+    for (let filePath of sortedFiles) {
+      filePath = string.toUnixSlash(filePath);
+      const relativePath = removeExtension(relative2(this.#source, filePath));
+      this.#files.set(filePath, relativePath);
+    }
+  }
+  /**
+   * Check if a given file is part of the virtual file system. The method
+   * checks for the scanned files as well as glob pattern matches.
+   *
+   * @param filePath - Absolute file path to check
+   * @returns True if the file is tracked or matches the configured patterns
+   */
+  has(filePath) {
+    if (this.#files.has(filePath)) {
+      return true;
+    }
+    if (!filePath.startsWith(this.#source)) {
+      return false;
+    }
+    return this.#matcher(filePath);
+  }
+  /**
+   * Returns the files as a flat list of key-value pairs
+   *
+   * Converts the tracked files into a flat object where keys are relative
+   * paths (without extensions) and values are absolute file paths.
+   *
+   * @param options - Optional transformation functions for keys and values
+   * @returns Object with file mappings
+   */
+  asList(options) {
+    const list = {};
+    const transformKey = options?.transformKey ?? BYPASS_FN;
+    const transformValue = options?.transformValue ?? BYPASS_FN;
+    for (const [filePath, relativePath] of this.#files) {
+      list[transformKey(relativePath)] = transformValue(filePath);
+    }
+    return list;
+  }
+  /**
+   * Returns the files as a nested tree structure
+   *
+   * Converts the tracked files into a hierarchical object structure that
+   * mirrors the directory structure of the source files.
+   *
+   * @param options - Optional transformation functions for keys and values
+   * @returns Nested object representing the file tree
+   */
+  asTree(options) {
+    const list = {};
+    const transformKey = options?.transformKey ?? BYPASS_FN;
+    const transformValue = options?.transformValue ?? BYPASS_FN;
+    for (const [filePath, relativePath] of this.#files) {
+      lodash.set(list, transformKey(relativePath).split("/"), transformValue(filePath));
+    }
+    return list;
+  }
+  /**
+   * Add a new file to the virtual file system. File is only added when it
+   * matches the pre-defined filters.
+   *
+   * @param filePath - Absolute path of the file to add
+   * @returns True if the file was added, false if it doesn't match filters
+   */
+  add(filePath) {
+    if (this.has(filePath)) {
+      debug_default('adding new "%s" file to the virtual file system', filePath);
+      const relativePath = removeExtension(relative2(this.#source, filePath));
+      this.#files.set(filePath, relativePath);
+      return true;
+    }
+    return false;
+  }
+  /**
+   * Remove a file from the virtual file system
+   *
+   * @param filePath - Absolute path of the file to remove
+   * @returns True if the file was removed, false if it wasn't tracked
+   */
+  remove(filePath) {
+    debug_default('removing "%s" file from virtual file system', filePath);
+    return this.#files.delete(filePath);
+  }
+  /**
+   * Returns the file contents as AST-grep node and caches it
+   * forever. Use the "invalidate" method to remove it from the cache.
+   *
+   * This method reads the file content, parses it into an AST using ast-grep,
+   * and caches the result for future requests to improve performance.
+   *
+   * @param filePath - The absolute path to the file to parse
+   * @returns Promise resolving to the AST-grep node
+   */
+  async get(filePath) {
+    const cached = this.#astCache.get(filePath);
+    if (cached) {
+      debug_default('returning AST nodes from cache "%s"', filePath);
+      return cached;
+    }
+    const fileContents = await readFile(filePath, "utf-8");
+    debug_default('parsing "%s" file to AST', filePath);
+    this.#astCache.set(filePath, parse(Lang.TypeScript, fileContents).root());
+    return this.#astCache.get(filePath);
+  }
+  /**
+   * Invalidates AST cache for a single file or all files
+   *
+   * Use this method when files have been modified to ensure fresh
+   * AST parsing on subsequent get() calls.
+   *
+   * @param filePath - Optional file path to clear. If omitted, clears entire cache
+   */
+  invalidate(filePath) {
+    debug_default('invalidate AST cache "%s"', filePath);
+    filePath ? this.#astCache.delete(filePath) : this.#astCache.clear();
+  }
+  /**
+   * Clear all scanned files from memory
+   *
+   * Removes all tracked files from the internal file list, effectively
+   * resetting the virtual file system.
+   */
+  clear() {
+    this.#files.clear();
+  }
+};
+
+export {
+  debug_default,
+  parseConfig,
+  runNode,
+  run,
+  watch,
+  getPort,
+  copyFiles,
+  memoize,
+  isRelative,
+  loadHooks,
+  throttle,
+  removeExtension,
+  VirtualFileSystem
+};