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

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-25Q3N5JR.js

@@ -0,0 +1,392 @@
+import {
+  VirtualFileSystem,
+  debug_default,
+  removeExtension,
+  throttle
+} from "./chunk-PORDZS62.js";
+
+// src/index_generator/source.ts
+import string from "@poppinss/utils/string";
+import { mkdir, writeFile } from "fs/promises";
+import { dirname, join, relative } from "path/posix";
+import StringBuilder from "@poppinss/utils/string_builder";
+
+// src/file_buffer.ts
+var FileBuffer = class _FileBuffer {
+  /**
+   * Collected lines
+   */
+  #buffer = [];
+  /**
+   * Current indentation size. Each call to indent will increment
+   * it by 2
+   */
+  #identationSize = 0;
+  /**
+   * Cached compiled output. Once this value is set, the `flush`
+   * method will become a noop
+   */
+  #compiledOutput;
+  /**
+   * Creates a new child buffer instance
+   *
+   * @returns A new FileBuffer instance
+   */
+  create() {
+    return new _FileBuffer();
+  }
+  /**
+   * Returns the size of buffer text
+   *
+   * @returns The number of lines in the buffer
+   */
+  get size() {
+    return this.#buffer.length;
+  }
+  /**
+   * Write a new line to the output with current indentation
+   *
+   * @param text - The text to write as a new line
+   * @returns This FileBuffer instance for method chaining
+   */
+  writeLine(text) {
+    this.#buffer.push(`${" ".repeat(this.#identationSize)}${text}
+`);
+    return this;
+  }
+  /**
+   * Write text to the output without adding a new line
+   *
+   * @param text - The text to write without a newline
+   * @returns This FileBuffer instance for method chaining
+   */
+  write(text) {
+    this.#buffer.push(`${" ".repeat(this.#identationSize)}${text}`);
+    return this;
+  }
+  /**
+   * Increase indentation by 2 spaces
+   *
+   * @returns This FileBuffer instance for method chaining
+   */
+  indent() {
+    this.#identationSize += 2;
+    return this;
+  }
+  /**
+   * Decrease indentation by 2 spaces (minimum of 0)
+   *
+   * @returns This FileBuffer instance for method chaining
+   */
+  dedent() {
+    this.#identationSize -= 2;
+    if (this.#identationSize < 0) {
+      this.#identationSize = 0;
+    }
+    return this;
+  }
+  /**
+   * Return template as a string, joining all buffer lines
+   *
+   * Once called, the output is cached and subsequent calls return the same result.
+   * The flush method becomes a no-op after the first call.
+   *
+   * @returns The complete buffer content as a string
+   */
+  flush() {
+    if (this.#compiledOutput !== void 0) {
+      return this.#compiledOutput;
+    }
+    this.#compiledOutput = this.#buffer.join("\n");
+    return this.#compiledOutput;
+  }
+};
+
+// src/index_generator/source.ts
+var IndexGeneratorSource = class {
+  /**
+   * The application root directory path
+   */
+  #appRoot;
+  /**
+   * The absolute path to the output file
+   */
+  #output;
+  /**
+   * The absolute path to the source directory
+   */
+  #source;
+  /**
+   * The directory containing the output file
+   */
+  #outputDirname;
+  /**
+   * Virtual file system for scanning source files
+   */
+  #vfs;
+  /**
+   * Configuration for this index generator source
+   */
+  #config;
+  /**
+   * CLI logger instance for output messages
+   */
+  #cliLogger;
+  /**
+   * Generate the output content and write it to the output file
+   *
+   * This method creates the file buffer, populates it with the generated
+   * content based on configuration, and writes it to disk.
+   */
+  #generateOutput = throttle(async () => {
+    const buffer = new FileBuffer();
+    if (this.#config.as === "barrelFile") {
+      this.#asBarrelFile(this.#vfs, buffer, this.#config.exportName);
+    } else {
+      this.#config.as(this.#vfs, buffer, this.#config);
+    }
+    await mkdir(dirname(this.#output), { recursive: true });
+    await writeFile(this.#output, buffer.flush());
+  });
+  /**
+   * Unique name for this index generator source
+   */
+  name;
+  /**
+   * Create a new IndexGeneratorSource instance
+   *
+   * @param name - Unique name for this index generator source
+   * @param appRoot - The application root directory path
+   * @param cliLogger - Logger instance for CLI output
+   * @param config - Configuration for this index generator source
+   */
+  constructor(name, appRoot, cliLogger, config) {
+    this.name = name;
+    this.#config = config;
+    this.#appRoot = appRoot;
+    this.#cliLogger = cliLogger;
+    this.#source = join(this.#appRoot, this.#config.source);
+    this.#output = join(this.#appRoot, this.#config.output);
+    this.#outputDirname = dirname(this.#output);
+    this.#vfs = new VirtualFileSystem(this.#source, {
+      glob: this.#config.glob
+    });
+  }
+  /**
+   * Converts a recursive file tree to a string representation
+   *
+   * This method recursively processes a file tree structure and writes
+   * it as JavaScript object notation to the provided buffer.
+   *
+   * @param input - The recursive file tree to convert
+   * @param buffer - The file buffer to write the output to
+   */
+  #treeToString(input, buffer) {
+    Object.keys(input).forEach((key) => {
+      const value = input[key];
+      if (typeof value === "string") {
+        buffer.write(`'${key}': ${value},`);
+      } else {
+        buffer.write(`'${key}': {`).indent();
+        this.#treeToString(value, buffer);
+        buffer.dedent().write(`},`);
+      }
+    });
+  }
+  /**
+   * Transforms the barrel file index key. Converts basename to PascalCase
+   * and all other paths to camelCase
+   *
+   * @param config - Configuration containing suffix removal options
+   * @returns Function that transforms file paths to appropriate keys
+   */
+  #createBarrelFileKeyGenerator(config) {
+    return function(key) {
+      const paths = key.split("/");
+      const baseName = new StringBuilder(paths.pop()).removeSuffix(config.removeSuffix ?? "").pascalCase().toString();
+      return [...paths.map((p) => string.camelCase(p)), baseName].join("/");
+    };
+  }
+  /**
+   * Converts the file path to a lazy import. In case of an alias, the source
+   * path is replaced with the alias, otherwise a relative import is created
+   * from the output dirname.
+   *
+   * @param source - The source directory path
+   * @param outputDirname - The output directory path
+   * @param config - Configuration containing import alias options
+   * @returns Function that converts file paths to import statements
+   */
+  #createBarrelFileImportGenerator(source, outputDirname, config) {
+    return function(filePath) {
+      if (config.importAlias) {
+        debug_default('converting "%s" to import alias, source "%s"', filePath, source);
+        return `() => import('${removeExtension(filePath.replace(source, config.importAlias))}')`;
+      }
+      debug_default('converting "%s" to relative import, source "%s"', filePath, outputDirname);
+      return `() => import('${relative(outputDirname, filePath)}')`;
+    };
+  }
+  /**
+   * Generate a barrel file export structure
+   *
+   * This method creates a nested object structure that represents all
+   * discovered files as lazy imports, organized by directory structure.
+   *
+   * @param vfs - Virtual file system containing the scanned files
+   * @param buffer - File buffer to write the barrel exports to
+   * @param exportName - Name for the main export object
+   */
+  #asBarrelFile(vfs, buffer, exportName) {
+    const keyGenerator = this.#createBarrelFileKeyGenerator(this.#config);
+    const importGenerator = this.#createBarrelFileImportGenerator(
+      this.#source,
+      this.#outputDirname,
+      this.#config
+    );
+    const tree = vfs.asTree({
+      transformKey: keyGenerator,
+      transformValue: importGenerator
+    });
+    buffer.write(`export const ${exportName} = {`).indent();
+    this.#treeToString(tree, buffer);
+    buffer.dedent().write(`}`);
+  }
+  /**
+   * Create a log action for tracking file generation progress
+   *
+   * @example
+   * const action = this.#createLogAction()
+   * // ... perform operations
+   * action.displayDuration().succeeded()
+   */
+  #createLogAction() {
+    return this.#cliLogger.action(`create ${this.#config.output}`);
+  }
+  /**
+   * Add a file to the virtual file system and regenerate index if needed
+   *
+   * If the file matches the configured glob patterns, it will be added
+   * to the virtual file system and the index file will be regenerated.
+   *
+   * @param filePath - Absolute path of the file to add
+   */
+  async addFile(filePath) {
+    const added = this.#vfs.add(filePath);
+    if (added) {
+      debug_default('file added, re-generating "%s" index', this.name);
+      const action = this.#createLogAction();
+      await this.#generateOutput();
+      action.displayDuration().succeeded();
+    }
+  }
+  /**
+   * Remove a file from the virtual file system and regenerate index if needed
+   *
+   * If the file was previously tracked, it will be removed from the
+   * virtual file system and the index file will be regenerated.
+   *
+   * @param filePath - Absolute path of the file to remove
+   */
+  async removeFile(filePath) {
+    const removed = this.#vfs.remove(filePath);
+    if (removed) {
+      debug_default('file removed, re-generating "%s" index', this.name);
+      const action = this.#createLogAction();
+      await this.#generateOutput();
+      action.displayDuration().succeeded();
+    }
+  }
+  /**
+   * Generate the index file
+   *
+   * This method scans the source directory, processes files according to
+   * the configuration, and writes the generated index file to disk.
+   */
+  async generate() {
+    const action = this.#createLogAction();
+    await this.#vfs.scan();
+    await this.#generateOutput();
+    action.displayDuration().succeeded();
+  }
+};
+
+// src/index_generator/main.ts
+var IndexGenerator = class {
+  /**
+   * The application root directory path
+   */
+  #appRoot;
+  /**
+   * Collection of registered index generator sources
+   */
+  #sources = {};
+  #cliLogger;
+  /**
+   * Create a new IndexGenerator instance
+   *
+   * @param appRoot - The application root directory path
+   * @param cliLogger - Logger instance for CLI output
+   */
+  constructor(appRoot, cliLogger) {
+    this.#appRoot = appRoot;
+    this.#cliLogger = cliLogger;
+  }
+  /**
+   * Add a new index generator source
+   *
+   * @param name - Unique name for the source
+   * @param config - Configuration for the index generator source
+   * @returns This IndexGenerator instance for method chaining
+   */
+  add(name, config) {
+    this.#sources[name] = new IndexGeneratorSource(name, this.#appRoot, this.#cliLogger, config);
+    return this;
+  }
+  /**
+   * Add a file to all registered index generator sources
+   *
+   * This method propagates the file addition to all registered sources,
+   * allowing them to regenerate their index files if the new file matches
+   * their glob patterns.
+   *
+   * @param filePath - Absolute path of the file to add
+   */
+  async addFile(filePath) {
+    const sources = Object.values(this.#sources);
+    for (let source of sources) {
+      await source.addFile(filePath);
+    }
+  }
+  /**
+   * Remove a file from all registered index generator sources
+   *
+   * This method propagates the file removal to all registered sources,
+   * allowing them to regenerate their index files if the removed file
+   * was previously tracked.
+   *
+   * @param filePath - Absolute path of the file to remove
+   */
+  async removeFile(filePath) {
+    const sources = Object.values(this.#sources);
+    for (let source of sources) {
+      await source.removeFile(filePath);
+    }
+  }
+  /**
+   * Generate all registered index files
+   *
+   * Iterates through all registered sources and generates their
+   * corresponding index files.
+   */
+  async generate() {
+    const sources = Object.values(this.#sources);
+    for (let source of sources) {
+      await source.generate();
+    }
+  }
+};
+
+export {
+  IndexGenerator
+};