@adonisjs/assembler 8.0.0-next.9 → 8.0.1

package/README.md

@@ -420,6 +420,266 @@ export const policies = {
 }
 ```
 
+### 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)
+
+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)
+}
+```
+
+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)
+}
+```
+
+Output
+
+```ts
+import { defineConfig } from '@adonisjs/core/app'
+import { Middleware, Provider } from '@adonisjs/core/types'
+
+export default defineConfig({
+  // ...
+})
+```
+
+#### addDefaultImport
+Add a default import to the `adonisrc.ts` file.
+
+```ts
+const transformer = new CodeTransformer(appRoot)
+
+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({
+  // ...
+})
+```
+
+#### 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 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.

package/build/chunk-DF48asd8.js

@@ -0,0 +1,9 @@
+import "node:module";
+Object.create;
+Object.defineProperty;
+Object.getOwnPropertyDescriptor;
+Object.getOwnPropertyNames;
+Object.getPrototypeOf;
+Object.prototype.hasOwnProperty;
+//#endregion
+export {};

package/build/codemod_exception-BMNJZ0i1.js

@@ -0,0 +1,280 @@
+//#region src/exceptions/codemod_exception.ts
+/**
+* Custom exception for codemod errors that provides helpful instructions
+* to the user when automatic code transformation fails.
+*
+* @example
+* ```ts
+* throw CodemodException.missingEnvFile('start/env.ts', {
+*   variables: { MY_VAR: 'Env.schema.string()' }
+* })
+* ```
+*/
+var CodemodException = class CodemodException extends Error {
+	/**
+	* Instructions for the user to manually perform the codemod action
+	*/
+	instructions;
+	/**
+	* The file path that was being modified
+	*/
+	filePath;
+	constructor(message, options) {
+		super(message);
+		this.name = "CodemodException";
+		this.instructions = options?.instructions;
+		this.filePath = options?.filePath;
+	}
+	/**
+	* Format env validations as code string
+	*/
+	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");
+	}
+	/**
+	* Format middleware as code string
+	*/
+	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])`;
+	}
+	/**
+	* Format policies as code string
+	*/
+	static #formatPolicies(policies) {
+		return `export const policies = {\n  ${policies.map((p) => `${p.name}: () => import('${p.path}')`).join(",\n  ")}\n}`;
+	}
+	/**
+	* Format Vite plugin as code string
+	*/
+	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})`;
+	}
+	/**
+	* Format Japa plugin as code string
+	*/
+	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]`;
+	}
+	/**
+	* Creates an exception when start/env.ts file is missing
+	*
+	* @param filePath - The path to the missing file
+	* @param definition - The environment validation definition that was being added
+	*/
+	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}`
+		});
+	}
+	/**
+	* Creates an exception when Env.create is not found in the file
+	*
+	* @param filePath - The path to the file being modified
+	* @param definition - The environment validation definition that was being added
+	*/
+	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)}`
+		});
+	}
+	/**
+	* Creates an exception when Env.create has invalid structure
+	*
+	* @param filePath - The path to the file being modified
+	* @param definition - The environment validation definition that was being added
+	*/
+	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)}`
+		});
+	}
+	/**
+	* Creates an exception when start/kernel.ts file is missing
+	*
+	* @param filePath - The path to the missing file
+	* @param stack - The middleware stack that was being modified
+	* @param middleware - The middleware entries that were being added
+	*/
+	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}`
+		});
+	}
+	/**
+	* Creates an exception when server.use/router.use is not found
+	*
+	* @param filePath - The path to the file being modified
+	* @param stack - The middleware stack that was being modified
+	* @param middleware - The middleware entries that were being added
+	*/
+	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}`
+		});
+	}
+	/**
+	* Creates an exception when middleware array structure is invalid
+	*
+	* @param filePath - The path to the file being modified
+	* @param stack - The middleware stack that was being modified
+	* @param middleware - The middleware entries that were being added
+	* @param reason - The reason why the structure is invalid
+	*/
+	static invalidMiddlewareStack(filePath, stack, middleware, reason) {
+		return new CodemodException(reason, {
+			filePath,
+			instructions: `Add the following code to "${filePath}":\n\n${this.#formatMiddleware(stack, middleware)}`
+		});
+	}
+	/**
+	* Creates an exception when app/policies/main.ts file is missing
+	*
+	* @param filePath - The path to the missing file
+	* @param policies - The policies that were being added
+	*/
+	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}`
+		});
+	}
+	/**
+	* Creates an exception when policies structure is invalid
+	*
+	* @param filePath - The path to the file being modified
+	* @param policies - The policies that were being added
+	* @param reason - The reason why the structure is invalid
+	*/
+	static invalidPoliciesFile(filePath, policies, reason) {
+		return new CodemodException(reason, {
+			filePath,
+			instructions: `Add the following code to "${filePath}":\n\n${this.#formatPolicies(policies)}`
+		});
+	}
+	/**
+	* Creates an exception when vite.config.ts file is missing
+	*
+	* @param filePath - The path to the missing file
+	* @param pluginCall - The plugin call that was being added
+	* @param importDeclarations - The import declarations needed for the plugin
+	*/
+	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)}`
+		});
+	}
+	/**
+	* Creates an exception when vite.config.ts structure is invalid
+	*
+	* @param filePath - The path to the file being modified
+	* @param pluginCall - The plugin call that was being added
+	* @param importDeclarations - The import declarations needed for the plugin
+	* @param reason - The reason why the structure is invalid
+	*/
+	static invalidViteConfig(filePath, pluginCall, importDeclarations, reason) {
+		return new CodemodException(reason, {
+			filePath,
+			instructions: `Add the following code to "${filePath}":\n\n${this.#formatVitePlugin(pluginCall, importDeclarations)}`
+		});
+	}
+	/**
+	* Creates an exception when tests/bootstrap.ts file is missing
+	*
+	* @param filePath - The path to the missing file
+	* @param pluginCall - The plugin call that was being added
+	* @param importDeclarations - The import declarations needed for the plugin
+	*/
+	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}`
+		});
+	}
+	/**
+	* Creates an exception when tests/bootstrap.ts structure is invalid
+	*
+	* @param filePath - The path to the file being modified
+	* @param pluginCall - The plugin call that was being added
+	* @param importDeclarations - The import declarations needed for the plugin
+	* @param reason - The reason why the structure is invalid
+	*/
+	static invalidJapaBootstrap(filePath, pluginCall, importDeclarations, reason) {
+		return new CodemodException(reason, {
+			filePath,
+			instructions: `Add the following code to "${filePath}":\n\n${this.#formatJapaPlugin(pluginCall, importDeclarations)}`
+		});
+	}
+	/**
+	* Creates an exception when adonisrc.ts file is missing
+	*
+	* @param filePath - The path to the missing file
+	* @param codeToAdd - The code that should be added manually
+	*/
+	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}`
+		});
+	}
+	/**
+	* Creates an exception when adonisrc.ts structure is invalid
+	*
+	* @param filePath - The path to the file being modified
+	* @param codeToAdd - The code that should be added manually
+	* @param reason - The reason why the structure is invalid
+	*/
+	static invalidRcFile(filePath, codeToAdd, reason) {
+		return new CodemodException(reason, {
+			filePath,
+			instructions: `Add the following code to "${filePath}":\n\n${codeToAdd}`
+		});
+	}
+	/**
+	* Creates an exception when a file required for transformation is not found.
+	*
+	* @param filePath - The path to the missing file
+	* @param codeToAdd - The code that should be added manually
+	*/
+	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}`
+		});
+	}
+	/**
+	* Creates an exception when the file structure doesn't match expected patterns.
+	*
+	* @param message - Description of what structure was expected
+	* @param filePath - The path to the file being modified
+	* @param codeToAdd - The code that should be added manually
+	*/
+	static E_CODEMOD_INVALID_STRUCTURE(message, filePath, codeToAdd) {
+		return new CodemodException(message, {
+			filePath,
+			instructions: `Add the following code to "${filePath}":\n\n${codeToAdd}`
+		});
+	}
+};
+//#endregion
+export { CodemodException as t };

package/build/index.d.ts

@@ -1,7 +1,7 @@
-export { hooks } from './src/hooks.ts';
 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';