@adonisjs/assembler 8.0.0-next.3 → 8.0.0-next.30

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/codemod_exception-vyN1VXuX.js

@@ -0,0 +1,137 @@
+var CodemodException = class CodemodException extends Error {
+	instructions;
+	filePath;
+	constructor(message, options) {
+		super(message);
+		this.name = "CodemodException";
+		this.instructions = options?.instructions;
+		this.filePath = options?.filePath;
+	}
+	static #formatEnvValidations(definition) {
+		const lines = [];
+		if (definition.leadingComment) {
+			lines.push(`/*`);
+			lines.push(`|----------------------------------------------------------`);
+			lines.push(`| ${definition.leadingComment}`);
+			lines.push(`|----------------------------------------------------------`);
+			lines.push(`*/`);
+		}
+		for (const [variable, validation] of Object.entries(definition.variables)) lines.push(`${variable}: ${validation},`);
+		return lines.join("\n");
+	}
+	static #formatMiddleware(stack, middleware) {
+		if (stack === "named") return `export const middleware = router.named({\n  ${middleware.filter((m) => m.name).map((m) => `${m.name}: () => import('${m.path}')`).join(",\n  ")}\n})`;
+		return `${stack}.use([\n  ${middleware.map((m) => `() => import('${m.path}')`).join(",\n  ")}\n])`;
+	}
+	static #formatPolicies(policies) {
+		return `export const policies = {\n  ${policies.map((p) => `${p.name}: () => import('${p.path}')`).join(",\n  ")}\n}`;
+	}
+	static #formatVitePlugin(pluginCall, importDeclarations) {
+		return `${importDeclarations.map((decl) => decl.isNamed ? `import { ${decl.identifier} } from '${decl.module}'` : `import ${decl.identifier} from '${decl.module}'`).join("\n")}\n\nexport default defineConfig({\n  plugins: [${pluginCall}]\n})`;
+	}
+	static #formatJapaPlugin(pluginCall, importDeclarations) {
+		return `${importDeclarations.map((decl) => decl.isNamed ? `import { ${decl.identifier} } from '${decl.module}'` : `import ${decl.identifier} from '${decl.module}'`).join("\n")}\n\nexport const plugins: Config['plugins'] = [\n  ${pluginCall}\n]`;
+	}
+	static missingEnvFile(filePath, definition) {
+		const code = this.#formatEnvValidations(definition);
+		return new CodemodException(`Could not find source file at path: "${filePath}"`, {
+			filePath,
+			instructions: `Add the following code to "${filePath}":\n\n${code}`
+		});
+	}
+	static missingEnvCreate(filePath, definition) {
+		return new CodemodException(`Cannot find Env.create statement in the file.`, {
+			filePath,
+			instructions: `Add the following code inside Env.create() in "${filePath}":\n\n${this.#formatEnvValidations(definition)}`
+		});
+	}
+	static invalidEnvCreate(filePath, definition) {
+		return new CodemodException(`The second argument of Env.create is not an object literal.`, {
+			filePath,
+			instructions: `Add the following code inside Env.create() in "${filePath}":\n\n${this.#formatEnvValidations(definition)}`
+		});
+	}
+	static missingKernelFile(filePath, stack, middleware) {
+		const code = this.#formatMiddleware(stack, middleware);
+		return new CodemodException(`Could not find source file at path: "${filePath}"`, {
+			filePath,
+			instructions: `Add the following code to "${filePath}":\n\n${code}`
+		});
+	}
+	static missingMiddlewareStack(filePath, stack, middleware) {
+		const code = this.#formatMiddleware(stack, middleware);
+		return new CodemodException(`Cannot find ${stack === "named" ? "middleware variable" : `${stack}.use`} statement in the file.`, {
+			filePath,
+			instructions: `Add the following code to "${filePath}":\n\n${code}`
+		});
+	}
+	static invalidMiddlewareStack(filePath, stack, middleware, reason) {
+		return new CodemodException(reason, {
+			filePath,
+			instructions: `Add the following code to "${filePath}":\n\n${this.#formatMiddleware(stack, middleware)}`
+		});
+	}
+	static missingPoliciesFile(filePath, policies) {
+		const code = this.#formatPolicies(policies);
+		return new CodemodException(`Could not find source file at path: "${filePath}"`, {
+			filePath,
+			instructions: `Add the following code to "${filePath}":\n\n${code}`
+		});
+	}
+	static invalidPoliciesFile(filePath, policies, reason) {
+		return new CodemodException(reason, {
+			filePath,
+			instructions: `Add the following code to "${filePath}":\n\n${this.#formatPolicies(policies)}`
+		});
+	}
+	static missingViteConfig(filePath, pluginCall, importDeclarations) {
+		return new CodemodException(`Cannot find vite.config.ts file. Make sure to rename vite.config.js to vite.config.ts`, {
+			filePath,
+			instructions: `Add the following code to "${filePath}":\n\n${this.#formatVitePlugin(pluginCall, importDeclarations)}`
+		});
+	}
+	static invalidViteConfig(filePath, pluginCall, importDeclarations, reason) {
+		return new CodemodException(reason, {
+			filePath,
+			instructions: `Add the following code to "${filePath}":\n\n${this.#formatVitePlugin(pluginCall, importDeclarations)}`
+		});
+	}
+	static missingJapaBootstrap(filePath, pluginCall, importDeclarations) {
+		const code = this.#formatJapaPlugin(pluginCall, importDeclarations);
+		return new CodemodException(`Could not find source file at path: "${filePath}"`, {
+			filePath,
+			instructions: `Add the following code to "${filePath}":\n\n${code}`
+		});
+	}
+	static invalidJapaBootstrap(filePath, pluginCall, importDeclarations, reason) {
+		return new CodemodException(reason, {
+			filePath,
+			instructions: `Add the following code to "${filePath}":\n\n${this.#formatJapaPlugin(pluginCall, importDeclarations)}`
+		});
+	}
+	static missingRcFile(filePath, codeToAdd) {
+		return new CodemodException(`Could not find source file at path: "${filePath}"`, {
+			filePath,
+			instructions: `Add the following code to "${filePath}":\n\n${codeToAdd}`
+		});
+	}
+	static invalidRcFile(filePath, codeToAdd, reason) {
+		return new CodemodException(reason, {
+			filePath,
+			instructions: `Add the following code to "${filePath}":\n\n${codeToAdd}`
+		});
+	}
+	static E_CODEMOD_FILE_NOT_FOUND(filePath, codeToAdd) {
+		return new CodemodException(`Could not find source file at path: "${filePath}"`, {
+			filePath,
+			instructions: `Add the following code to "${filePath}":\n\n${codeToAdd}`
+		});
+	}
+	static E_CODEMOD_INVALID_STRUCTURE(message, filePath, codeToAdd) {
+		return new CodemodException(message, {
+			filePath,
+			instructions: `Add the following code to "${filePath}":\n\n${codeToAdd}`
+		});
+	}
+};
+export { CodemodException as t };

package/build/helpers-DDurYRsZ.js

@@ -0,0 +1,72 @@
+import { parseImports } from "parse-imports";
+async function findImport(code, importReference) {
+	const importIdentifier = importReference.split(".")[0];
+	for (const $import of await parseImports(code, {})) {
+		if (!$import.importClause) continue;
+		if (!$import.moduleSpecifier.value) continue;
+		if ($import.importClause.default === importIdentifier) return {
+			specifier: $import.moduleSpecifier.value,
+			isConstant: $import.moduleSpecifier.isConstant,
+			clause: {
+				type: "default",
+				value: importIdentifier
+			}
+		};
+		if ($import.importClause.namespace === importIdentifier) return {
+			specifier: $import.moduleSpecifier.value,
+			isConstant: $import.moduleSpecifier.isConstant,
+			clause: {
+				type: "namespace",
+				value: importIdentifier
+			}
+		};
+		const namedImport = $import.importClause.named.find(({ binding }) => {
+			return binding === importIdentifier;
+		});
+		if (namedImport) return {
+			specifier: $import.moduleSpecifier.value,
+			isConstant: $import.moduleSpecifier.isConstant,
+			clause: {
+				type: "named",
+				value: namedImport.specifier,
+				...namedImport.binding !== namedImport.specifier ? { alias: namedImport.binding } : {}
+			}
+		};
+	}
+	return null;
+}
+function inspectClass(node) {
+	return node.find({ rule: { kind: "class_declaration" } });
+}
+function inspectClassMethods(node) {
+	return node.findAll({ rule: { kind: "method_definition" } });
+}
+function nodeToPlainText(node) {
+	let out = [];
+	function toText(one) {
+		const children = one.children();
+		if (!children.length) out.push(one.text());
+		else children.forEach((child) => toText(child));
+	}
+	toText(node);
+	return out.join("");
+}
+function inspectMethodArguments(node, methodCalls) {
+	return node.findAll({ rule: { any: methodCalls.map((methodCall) => {
+		return { pattern: {
+			context: `${methodCall}($$$ARGUMENTS)`,
+			selector: "call_expression"
+		} };
+	}) } }).flatMap((matchingExpression) => {
+		return matchingExpression.findAll({ rule: { kind: "arguments" } });
+	});
+}
+function searchValidatorDirectUsage(node) {
+	return node.findAll({ rule: { pattern: {
+		context: "$$$VALIDATOR.validate($$$)",
+		selector: "call_expression"
+	} } }).flatMap((expression) => {
+		return expression.getMultipleMatches("VALIDATOR");
+	});
+}
+export { nodeToPlainText as a, inspectMethodArguments as i, inspectClass as n, searchValidatorDirectUsage as o, inspectClassMethods as r, findImport as t };

package/build/index.d.ts

@@ -1,3 +1,7 @@
 export { Bundler } from './src/bundler.ts';
 export { DevServer } from './src/dev_server.ts';
 export { TestRunner } from './src/test_runner.ts';
+export { FileBuffer } from './src/file_buffer.ts';
+export { VirtualFileSystem } from './src/virtual_file_system.ts';
+export { CodemodException } from './src/exceptions/codemod_exception.ts';
+export { SUPPORTED_PACKAGE_MANAGERS } from './src/bundler.ts';