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

package/README.md

@@ -420,83 +420,371 @@ 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.
+### addValidator
+Create a new validator file or add a validator to an existing file. If the file does not exist, it will be created with the provided contents. If it exists and the export name is not already defined, the validator will be appended to the file.
+
+> [!IMPORTANT]
+> This codemod respects the `validators` directory configured in `adonisrc.ts` and defaults to `app/validators`.
+
+```ts
+const transformer = new CodeTransformer(appRoot)
+
+try {
+  await transformer.addValidator({
+    validatorFileName: 'user.ts',
+    exportName: 'loginValidator',
+    contents: `export const loginValidator = vine.compile(
+  vine.object({
+    email: vine.string().email(),
+    password: vine.string().minLength(8)
+  })
+)`
+  })
+} catch (error) {
+  console.error('Unable to add validator')
+  console.error(error)
+}
+```
+
+Output (app/validators/user.ts)
+
+```ts
+export const loginValidator = vine.compile(
+  vine.object({
+    email: vine.string().email(),
+    password: vine.string().minLength(8)
+  })
+)
+```
+
+### addLimiter
+Create a new rate limiter file or add a limiter to an existing file. If the file does not exist, it will be created with the provided contents. If it exists and the export name is not already defined, the limiter will be appended to the file.
+
+> [!IMPORTANT]
+> Limiters are created in the `start` directory configured in `adonisrc.ts` and defaults to `start`.
 
 ```ts
 const transformer = new CodeTransformer(appRoot)
 
-const output = await transformer.makeEntityIndex({
-  source: 'app/controllers',
-  importAlias: '#controllers'
-}, {
-  destination: '.adonisjs/backend/controllers',
-  exportName: 'controllers'
+try {
+  await transformer.addLimiter({
+    limiterFileName: 'limiters.ts',
+    exportName: 'apiThrottle',
+    contents: `export const apiThrottle = limiter.define('api', () => {
+  return limiter.allowRequests(10).every('1 minute')
+})`
+  })
+} catch (error) {
+  console.error('Unable to add limiter')
+  console.error(error)
+}
+```
+
+Output (start/limiters.ts)
+
+```ts
+export const apiThrottle = limiter.define('api', () => {
+  return limiter.allowRequests(10).every('1 minute')
 })
+```
+
+### addModelMixins
+Apply one or more mixins to a model class. This wraps the model's extends clause with the `compose` helper and applies the specified mixins.
+
+> [!IMPORTANT]
+> This codemod expects the model file to exist with a default exported class that extends a base class.
+
+```ts
+const transformer = new CodeTransformer(appRoot)
+
+try {
+  await transformer.addModelMixins('user.ts', [
+    {
+      name: 'SoftDeletes',
+      importPath: '@adonisjs/lucid/orm/mixins/soft_deletes',
+      importType: 'named'
+    },
+    {
+      name: 'Sluggable',
+      importPath: '#mixins/sluggable',
+      importType: 'default',
+      args: ['title', '{ strategy: "dbIncrement" }']
+    }
+  ])
+} catch (error) {
+  console.error('Unable to add mixins to model')
+  console.error(error)
+}
+```
+
+Input (app/models/user.ts)
+
+```ts
+import { BaseModel } from '@adonisjs/lucid/orm'
+
+export default class User extends BaseModel {
+  // ...
+}
+```
+
+Output (app/models/user.ts)
+
+```ts
+import { BaseModel } from '@adonisjs/lucid/orm'
+import { compose } from '@adonisjs/core/helpers'
+import { SoftDeletes } from '@adonisjs/lucid/orm/mixins/soft_deletes'
+import Sluggable from '#mixins/sluggable'
+
+export default class User extends compose(BaseModel, SoftDeletes(), Sluggable(title, { strategy: "dbIncrement" })) {
+  // ...
+}
+```
+
+### addControllerMethod
+Create a new controller file or add a method to an existing controller class. If the controller file does not exist, it will be created with the class and method. If it exists and the method is not already defined, the method will be added to the class.
+
+> [!IMPORTANT]
+> This codemod respects the `controllers` directory configured in `adonisrc.ts` and defaults to `app/controllers`.
+
+```ts
+const transformer = new CodeTransformer(appRoot)
+
+try {
+  await transformer.addControllerMethod({
+    controllerFileName: 'users_controller.ts',
+    className: 'UsersController',
+    name: 'destroy',
+    contents: `async destroy({ params, response }: HttpContext) {
+  const user = await User.findOrFail(params.id)
+  await user.delete()
+  return response.noContent()
+}`,
+    imports: [
+      { isType: false, isNamed: true, name: 'HttpContext', path: '@adonisjs/core/http' },
+      { isType: false, isNamed: false, name: 'User', path: '#models/user' }
+    ]
+  })
+} catch (error) {
+  console.error('Unable to add controller method')
+  console.error(error)
+}
+```
 
-/**
-  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'),
+Output (app/controllers/users_controller.ts)
+
+```ts
+import type { HttpContext } from '@adonisjs/core/http'
+import User from '#models/user'
+
+export default class UsersController {
+  async destroy({ params, response }: HttpContext) {
+    const user = await User.findOrFail(params.id)
+    await user.delete()
+    return response.noContent()
   }
- */
+}
+```
+
+### RcFileTransformer additional methods
+
+The `RcFileTransformer` class (accessible via `updateRcFile` callback) now supports additional methods for managing imports and hooks.
+
+#### addNamedImport
+Add a named import to the `adonisrc.ts` file.
+
+```ts
+const transformer = new CodeTransformer(appRoot)
+
+try {
+  await transformer.updateRcFile((rcFile) => {
+    rcFile.addNamedImport('@adonisjs/core/types', ['Middleware', 'Provider'])
+  })
+} catch (error) {
+  console.error('Unable to add named import')
+  console.error(error)
+}
 ```
 
-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.
+Output
 
 ```ts
-const output = await transformer.makeEntityIndex({
-  source: 'app/controllers',
-  importAlias: '#controllers'
-}, {
-  destination: '.adonisjs/backend/controllers',
-  exportName: 'controllers',
-  removeNameSuffix: 'controller'
+import { defineConfig } from '@adonisjs/core/app'
+import { Middleware, Provider } from '@adonisjs/core/types'
+
+export default defineConfig({
+  // ...
 })
 ```
 
-For more advanced use-cases, you can specify the `computeBaseName` method to self compute the key name for the collection.
+#### addDefaultImport
+Add a default import to the `adonisrc.ts` file.
 
 ```ts
-import StringBuilder from '@poppinss/utils/string_builder'
+const transformer = new CodeTransformer(appRoot)
 
-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()
-  },
+try {
+  await transformer.updateRcFile((rcFile) => {
+    rcFile.addDefaultImport('#config/database', 'databaseConfig')
+  })
+} catch (error) {
+  console.error('Unable to add default import')
+  console.error(error)
+}
+```
+
+Output
+
+```ts
+import { defineConfig } from '@adonisjs/core/app'
+import databaseConfig from '#config/database'
+
+export default defineConfig({
+  // ...
 })
 ```
 
-#### 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.
+#### addAssemblerHook
+Add assembler hooks to the `adonisrc.ts` file. Hooks can be added as thunk imports (lazy loaded) or as raw values for direct import references.
 
 ```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 {']
+const transformer = new CodeTransformer(appRoot)
+
+try {
+  await transformer.updateRcFile((rcFile) => {
+    // Add a thunk-style hook (lazy import)
+    rcFile.addAssemblerHook('onBuildStarting', './commands/build_hook.js')
+
+    // Add a raw hook (direct import reference)
+    rcFile.addAssemblerHook('onBuildCompleted', 'buildCompletedHook', true)
+  })
+} catch (error) {
+  console.error('Unable to add assembler hook')
+  console.error(error)
+}
+```
+
+Output
+
+```ts
+import { defineConfig } from '@adonisjs/core/app'
+
+export default defineConfig({
+  hooks: {
+    onBuildStarting: [
+      () => import('./commands/build_hook.js')
+    ],
+    onBuildCompleted: [
+      buildCompletedHook
+    ]
+  }
+})
+```
+
+## 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
+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',
+  })
+
+  indexGenerator.add('events', {
+    source: './app/events',
+    importAlias: '#events',
+    as: 'barrelFile',
+    exportName: 'events',
+    output: './.adonisjs/server/events.ts',
+  })
+
+  indexGenerator.add('listeners', {
+    source: './app/listeners',
+    importAlias: '#listeners',
+    as: 'barrelFile',
+    exportName: 'listeners',
+    removeSuffix: 'listener',
+    output: './.adonisjs/server/listeners.ts',
+  })
+})
+```
+
+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.
+
+### 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
+```
+
+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
+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'),
+}
+```
+
+### 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
+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';