@adonisjs/assembler 6.1.3-17 → 6.1.3-18

package/build/src/code_transformer/main.d.ts

@@ -0,0 +1,28 @@
+/// <reference types="node" resolution-mode="require"/>
+import { RcFileTransformer } from './rc_file_transformer.js';
+import type { AddMiddlewareEntry, EnvValidationDefinition } from '../types.js';
+/**
+ * This class is responsible for updating
+ */
+export declare class CodeTransformer {
+    #private;
+    constructor(cwd: URL);
+    /**
+     * Update the `adonisrc.ts` file
+     */
+    updateRcFile(callback: (transformer: RcFileTransformer) => void): Promise<void>;
+    /**
+     * Define new middlewares inside the `start/kernel.ts`
+     * file
+     *
+     * This function is highly based on some assumptions
+     * and will not work if you significantly tweaked
+     * your `start/kernel.ts` file.
+     */
+    addMiddlewareToStack(stack: 'server' | 'router' | 'named', middleware: AddMiddlewareEntry[]): Promise<void>;
+    /**
+     * Add new env variable validation in the
+     * `env.ts` file
+     */
+    defineEnvValidations(definition: EnvValidationDefinition): Promise<void>;
+}

package/build/src/code_transformer/main.js

@@ -0,0 +1,166 @@
+/*
+ * @adonisjs/assembler
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Node, Project, SyntaxKind } from 'ts-morph';
+import { RcFileTransformer } from './rc_file_transformer.js';
+/**
+ * This class is responsible for updating
+ */
+export class CodeTransformer {
+    /**
+     * Directory of the adonisjs project
+     */
+    #cwd;
+    /**
+     * The TsMorph project
+     */
+    #project;
+    constructor(cwd) {
+        this.#cwd = cwd;
+        this.#project = new Project({
+            tsConfigFilePath: join(fileURLToPath(this.#cwd), 'tsconfig.json'),
+        });
+    }
+    /**
+     * Update the `adonisrc.ts` file
+     */
+    async updateRcFile(callback) {
+        const rcFileTransformer = new RcFileTransformer(this.#cwd, this.#project);
+        callback(rcFileTransformer);
+        await rcFileTransformer.save();
+    }
+    /**
+     * Add a new middleware to the middleware array of the
+     * given file
+     */
+    #addToMiddlewareArray(file, target, middlewareEntry) {
+        const callExpressions = file
+            .getDescendantsOfKind(SyntaxKind.CallExpression)
+            .filter((statement) => statement.getExpression().getText() === target);
+        if (!callExpressions.length) {
+            throw new Error(`Cannot find ${target} statement in the file.`);
+        }
+        const arrayLiteralExpression = callExpressions[0].getArguments()[0];
+        if (!arrayLiteralExpression || !Node.isArrayLiteralExpression(arrayLiteralExpression)) {
+            throw new Error(`Cannot find middleware array in ${target} statement.`);
+        }
+        const middleware = `() => import('${middlewareEntry.path}')`;
+        if (middlewareEntry.position === 'before') {
+            arrayLiteralExpression.insertElement(0, middleware);
+        }
+        else {
+            arrayLiteralExpression.addElement(middleware);
+        }
+    }
+    /**
+     * Add a new middleware to the named middleware of the given file
+     */
+    #addToNamedMiddleware(file, middlewareEntry) {
+        if (!middlewareEntry.name)
+            throw new Error('Named middleware requires a name.');
+        const callArguments = file
+            .getVariableDeclarationOrThrow('middleware')
+            .getInitializerIfKindOrThrow(SyntaxKind.CallExpression)
+            .getArguments();
+        if (callArguments.length === 0) {
+            throw new Error('Named middleware call has no arguments.');
+        }
+        const namedMiddlewareObject = callArguments[0];
+        if (!Node.isObjectLiteralExpression(namedMiddlewareObject)) {
+            throw new Error('The argument of the named middleware call is not an object literal.');
+        }
+        const middleware = `${middlewareEntry.name}: () => import('${middlewareEntry.path}')`;
+        namedMiddlewareObject.insertProperty(0, middleware);
+    }
+    /**
+     * Write a leading comment
+     */
+    #addLeadingComment(writer, comment) {
+        if (!comment)
+            return writer.blankLine();
+        return writer
+            .blankLine()
+            .writeLine('/*')
+            .writeLine(`|----------------------------------------------------------`)
+            .writeLine(`| ${comment}`)
+            .writeLine(`|----------------------------------------------------------`)
+            .writeLine(`*/`);
+    }
+    /**
+     * Define new middlewares inside the `start/kernel.ts`
+     * file
+     *
+     * This function is highly based on some assumptions
+     * and will not work if you significantly tweaked
+     * your `start/kernel.ts` file.
+     */
+    async addMiddlewareToStack(stack, middleware) {
+        /**
+         * Get the `start/kernel.ts` source file
+         */
+        const kernelUrl = fileURLToPath(new URL('./start/kernel.ts', this.#cwd));
+        const file = this.#project.getSourceFileOrThrow(kernelUrl);
+        /**
+         * Process each middleware entry
+         */
+        for (const middlewareEntry of middleware) {
+            if (stack === 'named') {
+                this.#addToNamedMiddleware(file, middlewareEntry);
+            }
+            else {
+                this.#addToMiddlewareArray(file, `${stack}.use`, middlewareEntry);
+            }
+        }
+        file.formatText();
+        await file.save();
+    }
+    /**
+     * Add new env variable validation in the
+     * `env.ts` file
+     */
+    async defineEnvValidations(definition) {
+        /**
+         * Get the `start/env.ts` source file
+         */
+        const kernelUrl = fileURLToPath(new URL('./start/env.ts', this.#cwd));
+        const file = this.#project.getSourceFileOrThrow(kernelUrl);
+        /**
+         * Get the `Env.create` call expression
+         */
+        const callExpressions = file
+            .getDescendantsOfKind(SyntaxKind.CallExpression)
+            .filter((statement) => statement.getExpression().getText() === 'Env.create');
+        if (!callExpressions.length) {
+            throw new Error(`Cannot find Env.create statement in the file.`);
+        }
+        const objectLiteralExpression = callExpressions[0].getArguments()[1];
+        if (!Node.isObjectLiteralExpression(objectLiteralExpression)) {
+            throw new Error(`The second argument of Env.create is not an object literal.`);
+        }
+        let firstAdded = false;
+        /**
+         * Add each variable validation
+         */
+        for (const [variable, validation] of Object.entries(definition.variables)) {
+            objectLiteralExpression.addPropertyAssignment({
+                name: variable,
+                initializer: validation,
+                leadingTrivia: (writer) => {
+                    if (firstAdded)
+                        return;
+                    firstAdded = true;
+                    return this.#addLeadingComment(writer, definition.leadingComment);
+                },
+            });
+        }
+        file.formatText();
+        await file.save();
+    }
+}

package/build/src/code_transformer/rc_file_transformer.d.ts

@@ -0,0 +1,43 @@
+/// <reference types="node" resolution-mode="require"/>
+import { Project } from 'ts-morph';
+import type { AppEnvironments } from '@adonisjs/application/types';
+/**
+ * RcFileTransformer is used to transform the `adonisrc.ts` file
+ * for adding new commands, providers, meta files etc
+ */
+export declare class RcFileTransformer {
+    #private;
+    constructor(cwd: URL, project: Project);
+    /**
+     * Add a new command to the rcFile
+     */
+    addCommand(commandPath: string): this;
+    /**
+     * Add a new preloaded file to the rcFile
+     */
+    addPreloadFile(modulePath: string, environments?: AppEnvironments[]): this;
+    /**
+     * Add a new provider to the rcFile
+     */
+    addProvider(providerPath: string, environments?: AppEnvironments[]): this;
+    /**
+     * Add a new meta file to the rcFile
+     */
+    addMetaFile(globPattern: string, reloadServer?: boolean): this;
+    /**
+     * Set directory name and path
+     */
+    setDirectory(key: string, value: string): this;
+    /**
+     * Set command alias
+     */
+    setCommandAlias(alias: string, command: string): this;
+    /**
+     * Add a new test suite to the rcFile
+     */
+    addSuite(suiteName: string, files: string | string[], timeout?: number): this;
+    /**
+     * Save the adonisrc.ts file
+     */
+    save(): Promise<void>;
+}

package/build/src/code_transformer/rc_file_transformer.js

@@ -0,0 +1,264 @@
+import { fileURLToPath } from 'node:url';
+import { Node, SyntaxKind, } from 'ts-morph';
+/**
+ * RcFileTransformer is used to transform the `adonisrc.ts` file
+ * for adding new commands, providers, meta files etc
+ */
+export class RcFileTransformer {
+    #cwd;
+    #project;
+    constructor(cwd, project) {
+        this.#cwd = cwd;
+        this.#project = project;
+    }
+    /**
+     * Get the `adonisrc.ts` source file
+     */
+    #getRcFileOrThrow() {
+        const kernelUrl = fileURLToPath(new URL('./adonisrc.ts', this.#cwd));
+        return this.#project.getSourceFileOrThrow(kernelUrl);
+    }
+    /**
+     * Check if environments array has a subset of available environments
+     */
+    #isInSpecificEnvironment(environments) {
+        if (!environments)
+            return false;
+        return !!['web', 'console', 'test', 'repl'].find((env) => !environments.includes(env));
+    }
+    /**
+     * Locate the `defineConfig` call inside the `adonisrc.ts` file
+     */
+    #locateDefineConfigCallOrThrow(file) {
+        const call = file
+            .getDescendantsOfKind(SyntaxKind.CallExpression)
+            .find((statement) => statement.getExpression().getText() === 'defineConfig');
+        if (!call) {
+            throw new Error('Could not locate the defineConfig call.');
+        }
+        return call;
+    }
+    /**
+     * Return the ObjectLiteralExpression of the defineConfig call
+     */
+    #getDefineConfigObjectOrThrow(defineConfigCall) {
+        const configObject = defineConfigCall
+            .getArguments()[0]
+            .asKindOrThrow(SyntaxKind.ObjectLiteralExpression);
+        return configObject;
+    }
+    /**
+     * Check if the defineConfig() call has the property assignment
+     * inside it or not. If not, it will create one and return it.
+     */
+    #getPropertyAssignmentInDefineConfigCall(propertyName, initializer) {
+        const file = this.#getRcFileOrThrow();
+        const defineConfigCall = this.#locateDefineConfigCallOrThrow(file);
+        const configObject = this.#getDefineConfigObjectOrThrow(defineConfigCall);
+        let property = configObject.getProperty(propertyName);
+        if (!property) {
+            configObject.addPropertyAssignment({ name: propertyName, initializer });
+            property = configObject.getProperty(propertyName);
+        }
+        return property;
+    }
+    /**
+     * Extract list of imported modules from an ArrayLiteralExpression
+     *
+     * It assumes that the array can have two types of elements:
+     *
+     * - Simple lazy imported modules: [() => import('path/to/file')]
+     * - Or an object entry: [{ file: () => import('path/to/file'), environment: ['web', 'console'] }]
+     *   where the `file` property is a lazy imported module.
+     */
+    #extractModulesFromArray(array) {
+        const modules = array.getElements().map((element) => {
+            /**
+             * Simple lazy imported module
+             */
+            if (Node.isArrowFunction(element)) {
+                const importExp = element.getFirstDescendantByKindOrThrow(SyntaxKind.CallExpression);
+                const literal = importExp.getFirstDescendantByKindOrThrow(SyntaxKind.StringLiteral);
+                return literal.getLiteralValue();
+            }
+            /**
+             * Object entry
+             */
+            if (Node.isObjectLiteralExpression(element)) {
+                const fileProp = element.getPropertyOrThrow('file');
+                const arrowFn = fileProp.getFirstDescendantByKindOrThrow(SyntaxKind.ArrowFunction);
+                const importExp = arrowFn.getFirstDescendantByKindOrThrow(SyntaxKind.CallExpression);
+                const literal = importExp.getFirstDescendantByKindOrThrow(SyntaxKind.StringLiteral);
+                return literal.getLiteralValue();
+            }
+        });
+        return modules.filter(Boolean);
+    }
+    /**
+     * Extract a specific property from an ArrayLiteralExpression
+     * that contains object entries.
+     *
+     * This function is mainly used for extractring the `pattern` property
+     * when adding a new meta files entry, or the `name` property when
+     * adding a new test suite.
+     */
+    #extractPropertyFromArray(array, propertyName) {
+        const property = array.getElements().map((el) => {
+            if (!Node.isObjectLiteralExpression(el))
+                return;
+            const nameProp = el.getPropertyOrThrow(propertyName);
+            if (!Node.isPropertyAssignment(nameProp))
+                return;
+            const name = nameProp.getInitializerIfKindOrThrow(SyntaxKind.StringLiteral);
+            return name.getLiteralValue();
+        });
+        return property.filter(Boolean);
+    }
+    /**
+     * Build a new module entry for the preloads and providers array
+     * based upon the environments specified
+     */
+    #buildNewModuleEntry(modulePath, environments) {
+        if (!this.#isInSpecificEnvironment(environments)) {
+            return `() => import('${modulePath}')`;
+        }
+        return `{
+      file: () => import('${modulePath}'),
+      environment: [${environments?.map((env) => `'${env}'`).join(', ')}],
+    }`;
+    }
+    /**
+     * Add a new command to the rcFile
+     */
+    addCommand(commandPath) {
+        const commandsProperty = this.#getPropertyAssignmentInDefineConfigCall('providers', '[]');
+        const commandsArray = commandsProperty.getInitializerIfKindOrThrow(SyntaxKind.ArrayLiteralExpression);
+        const commandString = `() => import('${commandPath}')`;
+        /**
+         * If the command already exists, do nothing
+         */
+        if (commandsArray.getElements().some((el) => el.getText() === commandString)) {
+            return this;
+        }
+        /**
+         * Add the command to the array
+         */
+        commandsArray.addElement(commandString);
+        return this;
+    }
+    /**
+     * Add a new preloaded file to the rcFile
+     */
+    addPreloadFile(modulePath, environments) {
+        const preloadsProperty = this.#getPropertyAssignmentInDefineConfigCall('preloads', '[]');
+        const preloadsArray = preloadsProperty.getInitializerIfKindOrThrow(SyntaxKind.ArrayLiteralExpression);
+        /**
+         * Check for duplicates
+         */
+        const existingPreloadedFiles = this.#extractModulesFromArray(preloadsArray);
+        const isDuplicate = existingPreloadedFiles.includes(modulePath);
+        if (isDuplicate) {
+            return this;
+        }
+        /**
+         * Add the preloaded file to the array
+         */
+        preloadsArray.addElement(this.#buildNewModuleEntry(modulePath, environments));
+        return this;
+    }
+    /**
+     * Add a new provider to the rcFile
+     */
+    addProvider(providerPath, environments) {
+        const property = this.#getPropertyAssignmentInDefineConfigCall('providers', '[]');
+        const providersArray = property.getInitializerIfKindOrThrow(SyntaxKind.ArrayLiteralExpression);
+        /**
+         * Check for duplicates
+         */
+        const existingProviderPaths = this.#extractModulesFromArray(providersArray);
+        const isDuplicate = existingProviderPaths.includes(providerPath);
+        if (isDuplicate) {
+            return this;
+        }
+        /**
+         * Add the provider to the array
+         */
+        providersArray.addElement(this.#buildNewModuleEntry(providerPath, environments));
+        return this;
+    }
+    /**
+     * Add a new meta file to the rcFile
+     */
+    addMetaFile(globPattern, reloadServer = false) {
+        const property = this.#getPropertyAssignmentInDefineConfigCall('metaFiles', '[]');
+        const metaFilesArray = property.getInitializerIfKindOrThrow(SyntaxKind.ArrayLiteralExpression);
+        /**
+         * Check for duplicates
+         */
+        const alreadyDefinedPatterns = this.#extractPropertyFromArray(metaFilesArray, 'pattern');
+        if (alreadyDefinedPatterns.includes(globPattern)) {
+            return this;
+        }
+        /**
+         * Add the meta file to the array
+         */
+        metaFilesArray.addElement(`{
+        pattern: '${globPattern}',
+        reloadServer: ${reloadServer},
+      }`);
+        return this;
+    }
+    /**
+     * Set directory name and path
+     */
+    setDirectory(key, value) {
+        const property = this.#getPropertyAssignmentInDefineConfigCall('directories', '{}');
+        const directories = property.getInitializerIfKindOrThrow(SyntaxKind.ObjectLiteralExpression);
+        directories.addPropertyAssignment({ name: key, initializer: `'${value}'` });
+        return this;
+    }
+    /**
+     * Set command alias
+     */
+    setCommandAlias(alias, command) {
+        const aliasProperty = this.#getPropertyAssignmentInDefineConfigCall('commandsAliases', '{}');
+        const aliases = aliasProperty.getInitializerIfKindOrThrow(SyntaxKind.ObjectLiteralExpression);
+        aliases.addPropertyAssignment({ name: alias, initializer: `'${command}'` });
+        return this;
+    }
+    /**
+     * Add a new test suite to the rcFile
+     */
+    addSuite(suiteName, files, timeout) {
+        const testProperty = this.#getPropertyAssignmentInDefineConfigCall('tests', `{ suites: [], forceExit: true, timeout: 2000 }`);
+        const property = testProperty
+            .getInitializerIfKindOrThrow(SyntaxKind.ObjectLiteralExpression)
+            .getPropertyOrThrow('suites');
+        const suitesArray = property.getInitializerIfKindOrThrow(SyntaxKind.ArrayLiteralExpression);
+        /**
+         * Check for duplicates
+         */
+        const existingSuitesNames = this.#extractPropertyFromArray(suitesArray, 'name');
+        if (existingSuitesNames.includes(suiteName)) {
+            return this;
+        }
+        /**
+         * Add the suite to the array
+         */
+        const filesArray = Array.isArray(files) ? files : [files];
+        suitesArray.addElement(`{
+        name: '${suiteName}',
+        files: [${filesArray.map((file) => `'${file}'`).join(', ')}],
+        timeout: ${timeout ?? 2000},
+      }`);
+        return this;
+    }
+    /**
+     * Save the adonisrc.ts file
+     */
+    save() {
+        const file = this.#getRcFileOrThrow();
+        file.formatText();
+        return file.save();
+    }
+}

package/build/src/types.d.ts

@@ -92,3 +92,47 @@ export type BundlerOptions = {
     metaFiles?: MetaFile[];
     assets?: AssetsBundlerOptions;
 };
+/**
+ * Entry to add a middleware to a given middleware stack
+ * via the CodeTransformer
+ */
+export type AddMiddlewareEntry = {
+    /**
+     * If you are adding a named middleware, then you must
+     * define the name.
+     */
+    name?: string;
+    /**
+     * The path to the middleware file
+     *
+     * @example
+     *  `@adonisjs/static/static_middleware`
+     *  `#middlewares/silent_auth.js`
+     */
+    path: string;
+    /**
+     * The position to add the middleware. If `before`
+     * middleware will be added at the first position and
+     * therefore will be run before all others
+     *
+     * @default 'after'
+     */
+    position?: 'before' | 'after';
+};
+/**
+ * Defines the structure of an environment variable validation
+ * definition
+ */
+export type EnvValidationDefinition = {
+    /**
+     * Write a leading comment on top of your variables
+     */
+    leadingComment?: string;
+    /**
+     * A key-value pair of env variables and their validation
+     *
+     * @example
+     *  MY_VAR: 'Env.schema.string.optional()'
+     */
+    variables: Record<string, string>;
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@adonisjs/assembler",
   "description": "Provides utilities to run AdonisJS development server and build project for production",
-  "version": "6.1.3-17",
+  "version": "6.1.3-18",
   "engines": {
     "node": ">=18.16.0"
   },
@@ -14,6 +14,7 @@
   ],
   "exports": {
     ".": "./build/index.js",
+    "./code_transformer": "./build/src/code_transformer/main.js",
     "./types": "./build/src/types.js"
   },
   "scripts": {
@@ -29,9 +30,10 @@
     "sync-labels": "github-label-sync --labels .github/labels.json adonisjs/assembler",
     "format": "prettier --write .",
     "prepublishOnly": "npm run build",
-    "quick:test": "node --loader=ts-node/esm bin/test.ts"
+    "quick:test": "node --enable-source-maps --loader=ts-node/esm bin/test.ts"
   },
   "devDependencies": {
+    "@adonisjs/application": "7.1.2-9",
     "@adonisjs/eslint-config": "^1.1.8",
     "@adonisjs/prettier-config": "^1.1.8",
     "@adonisjs/tsconfig": "^1.1.8",
@@ -40,11 +42,13 @@
     "@japa/assert": "^2.0.0-1",
     "@japa/file-system": "^2.0.0-1",
     "@japa/runner": "^3.0.0-6",
+    "@japa/snapshot": "2.0.0-1",
     "@swc/core": "^1.3.71",
     "@types/node": "^20.4.5",
     "@types/picomatch": "^2.3.0",
     "c8": "^8.0.1",
     "cross-env": "^7.0.3",
+    "dedent": "^1.5.1",
     "del-cli": "^5.0.0",
     "eslint": "^8.45.0",
     "github-label-sync": "^2.3.1",
@@ -65,7 +69,8 @@
     "get-port": "^7.0.0",
     "junk": "^4.0.1",
     "picomatch": "^2.3.1",
-    "slash": "^5.1.0"
+    "slash": "^5.1.0",
+    "ts-morph": "^19.0.0"
   },
   "peerDependencies": {
     "typescript": "^4.0.0 || ^5.0.0"