@adonisjs/assembler 6.1.3-2 → 6.1.3-20

package/LICENSE.md

@@ -1,6 +1,6 @@
 # The MIT License
 
-Copyright (c) 2023 AdonisJS Framework
+Copyright (c) 2023 Harminder Virk
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 

package/README.md

@@ -2,7 +2,7 @@
 
 <br />
 
-[![gh-workflow-image]][gh-workflow-url] [![npm-image]][npm-url] ![][typescript-image] [![license-image]][license-url] [![synk-image]][synk-url]
+[![gh-workflow-image]][gh-workflow-url] [![npm-image]][npm-url] ![][typescript-image] [![license-image]][license-url]
 
 ## Introduction
 Assembler exports the API for starting the **AdonisJS development server**, **building project for production** and **running tests** in watch mode. Assembler must be used during development only.
@@ -21,8 +21,8 @@ In order to ensure that the AdonisJS community is welcoming to all, please revie
 ## License
 AdonisJS Assembler is open-sourced software licensed under the [MIT license](LICENSE.md).
 
-[gh-workflow-image]: https://img.shields.io/github/actions/workflow/status/adonisjs/assembler/test.yml?style=for-the-badge
-[gh-workflow-url]: https://github.com/adonisjs/assembler/actions/workflows/test.yml "Github action"
+[gh-workflow-image]: https://img.shields.io/github/actions/workflow/status/adonisjs/assembler/checks.yml?style=for-the-badge
+[gh-workflow-url]: https://github.com/adonisjs/assembler/actions/workflows/checks.yml "Github action"
 
 [npm-image]: https://img.shields.io/npm/v/@adonisjs/assembler/latest.svg?style=for-the-badge&logo=npm
 [npm-url]: https://npmjs.org/package/@adonisjs/assembler/v/latest "npm"
@@ -31,6 +31,3 @@ AdonisJS Assembler is open-sourced software licensed under the [MIT license](LIC
 
 [license-url]: LICENSE.md
 [license-image]: https://img.shields.io/github/license/adonisjs/ace?style=for-the-badge
-
-[synk-image]: https://img.shields.io/snyk/vulnerabilities/github/adonisjs/assembler?label=Synk%20Vulnerabilities&style=for-the-badge
-[synk-url]: https://snyk.io/test/github/adonisjs/assembler?targetFile=package.json "synk"

package/build/index.d.ts

@@ -1,2 +1,3 @@
 export { Bundler } from './src/bundler.js';
 export { DevServer } from './src/dev_server.js';
+export { TestRunner } from './src/test_runner.js';

package/build/index.js

@@ -1,2 +1,11 @@
+/*
+ * @adonisjs/assembler
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
 export { Bundler } from './src/bundler.js';
 export { DevServer } from './src/dev_server.js';
+export { TestRunner } from './src/test_runner.js';

package/build/src/assets_dev_server.d.ts

@@ -0,0 +1,32 @@
+/// <reference types="node" resolution-mode="require"/>
+import { type Logger } from '@poppinss/cliui';
+import type { AssetsBundlerOptions } from './types.js';
+/**
+ * Exposes the API to start the development server for processing assets during
+ * development.
+ *
+ * - Here we are running the assets dev server in a child process.
+ * - Piping the output from the child process and reformatting it before writing it to
+ *   process streams.
+ *
+ * AssetsDevServer is agnostic and can run any assets dev server. Be it Vite or Encore or
+ * even Webpack directly.
+ */
+export declare class AssetsDevServer {
+    #private;
+    constructor(cwd: URL, options?: AssetsBundlerOptions);
+    /**
+     * Set a custom CLI UI logger
+     */
+    setLogger(logger: Logger): this;
+    /**
+     * Starts the assets bundler server. The assets bundler server process is
+     * considered as the secondary process and therefore we do not perform
+     * any cleanup if it dies.
+     */
+    start(): void;
+    /**
+     * Stop the dev server
+     */
+    stop(): void;
+}

package/build/src/assets_dev_server.js

@@ -0,0 +1,158 @@
+/*
+ * @adonisjs/core
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+import { cliui } from '@poppinss/cliui';
+import { run } from './helpers.js';
+/**
+ * Instance of CLIUI
+ */
+const ui = cliui();
+/**
+ * Exposes the API to start the development server for processing assets during
+ * development.
+ *
+ * - Here we are running the assets dev server in a child process.
+ * - Piping the output from the child process and reformatting it before writing it to
+ *   process streams.
+ *
+ * AssetsDevServer is agnostic and can run any assets dev server. Be it Vite or Encore or
+ * even Webpack directly.
+ */
+export class AssetsDevServer {
+    #cwd;
+    #logger = ui.logger;
+    #options;
+    #devServer;
+    /**
+     * Getting reference to colors library from logger
+     */
+    get #colors() {
+        return this.#logger.getColors();
+    }
+    constructor(cwd, options) {
+        this.#cwd = cwd;
+        this.#options = options;
+    }
+    /**
+     * Logs messages from vite dev server stdout and stderr
+     */
+    #logViteDevServerMessage(data) {
+        const dataString = data.toString();
+        const lines = dataString.split('\n');
+        /**
+         * Logging VITE ready in message with proper
+         * spaces and newlines
+         */
+        if (dataString.includes('ready in')) {
+            console.log('');
+            console.log(dataString.trim());
+            return;
+        }
+        /**
+         * Put a wrapper around vite network address log
+         */
+        if (dataString.includes('Local') && dataString.includes('Network')) {
+            const sticker = ui.sticker().useColors(this.#colors).useRenderer(this.#logger.getRenderer());
+            lines.forEach((line) => {
+                if (line.trim()) {
+                    sticker.add(line);
+                }
+            });
+            sticker.render();
+            return;
+        }
+        /**
+         * Log rest of the lines
+         */
+        lines.forEach((line) => {
+            if (line.trim()) {
+                console.log(line);
+            }
+        });
+    }
+    /**
+     * Logs messages from assets dev server stdout and stderr
+     */
+    #logAssetsDevServerMessage(data) {
+        const dataString = data.toString();
+        const lines = dataString.split('\n');
+        lines.forEach((line) => {
+            if (line.trim()) {
+                console.log(line);
+            }
+        });
+    }
+    /**
+     * Set a custom CLI UI logger
+     */
+    setLogger(logger) {
+        this.#logger = logger;
+        return this;
+    }
+    /**
+     * Starts the assets bundler server. The assets bundler server process is
+     * considered as the secondary process and therefore we do not perform
+     * any cleanup if it dies.
+     */
+    start() {
+        if (!this.#options?.serve) {
+            return;
+        }
+        this.#logger.info(`starting "${this.#options.driver}" dev server...`);
+        /**
+         * Create child process
+         */
+        this.#devServer = run(this.#cwd, {
+            script: this.#options.cmd,
+            /**
+             * We do not inherit the stdio for vite and encore, because in
+             * inherit mode they own the stdin and interrupts the
+             * `Ctrl + C` command.
+             */
+            stdio: 'pipe',
+            scriptArgs: this.#options.args,
+        });
+        /**
+         * Log child process messages
+         */
+        this.#devServer.stdout?.on('data', (data) => {
+            if (this.#options.driver === 'vite') {
+                this.#logViteDevServerMessage(data);
+            }
+            else {
+                this.#logAssetsDevServerMessage(data);
+            }
+        });
+        this.#devServer.stderr?.on('data', (data) => {
+            if (this.#options.driver === 'vite') {
+                this.#logViteDevServerMessage(data);
+            }
+            else {
+                this.#logAssetsDevServerMessage(data);
+            }
+        });
+        this.#devServer
+            .then((result) => {
+            this.#logger.warning(`"${this.#options.driver}" dev server closed with status code "${result.exitCode}"`);
+        })
+            .catch((error) => {
+            this.#logger.warning(`unable to connect to "${this.#options.driver}" dev server`);
+            this.#logger.fatal(error);
+        });
+    }
+    /**
+     * Stop the dev server
+     */
+    stop() {
+        if (this.#devServer) {
+            this.#devServer.removeAllListeners();
+            this.#devServer.kill('SIGKILL');
+            this.#devServer = undefined;
+        }
+    }
+}

package/build/src/bundler.d.ts

@@ -2,9 +2,18 @@
 import type tsStatic from 'typescript';
 import { type Logger } from '@poppinss/cliui';
 import type { BundlerOptions } from './types.js';
+/**
+ * The bundler class exposes the API to build an AdonisJS project.
+ */
 export declare class Bundler {
     #private;
     constructor(cwd: URL, ts: typeof tsStatic, options: BundlerOptions);
+    /**
+     * Set a custom CLI UI logger
+     */
     setLogger(logger: Logger): this;
+    /**
+     * Bundles the application to be run in production
+     */
     bundle(stopOnError?: boolean, client?: 'npm' | 'yarn' | 'pnpm'): Promise<boolean>;
 }

package/build/src/bundler.js

@@ -1,18 +1,33 @@
+/*
+ * @adonisjs/assembler
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
 import slash from 'slash';
-import copyfiles from 'cpy';
 import fs from 'node:fs/promises';
 import { fileURLToPath } from 'node:url';
 import { join, relative } from 'node:path';
 import { cliui } from '@poppinss/cliui';
-import { run } from './run.js';
-import { parseConfig } from './parse_config.js';
+import { run, parseConfig, copyFiles } from './helpers.js';
+/**
+ * Instance of CLIUI
+ */
 const ui = cliui();
+/**
+ * The bundler class exposes the API to build an AdonisJS project.
+ */
 export class Bundler {
     #cwd;
     #cwdPath;
     #ts;
     #logger = ui.logger;
     #options;
+    /**
+     * Getting reference to colors library from logger
+     */
     get #colors() {
         return this.#logger.getColors();
     }
@@ -25,9 +40,15 @@ export class Bundler {
     #getRelativeName(filePath) {
         return slash(relative(this.#cwdPath, filePath));
     }
+    /**
+     * Cleans up the build directory
+     */
     async #cleanupBuildDirectory(outDir) {
         await fs.rm(outDir, { recursive: true, force: true, maxRetries: 5 });
     }
+    /**
+     * Runs assets bundler command to build assets.
+     */
     async #buildAssets() {
         const assetsBundler = this.#options.assets;
         if (!assetsBundler?.serve) {
@@ -38,7 +59,7 @@ export class Bundler {
             await run(this.#cwd, {
                 stdio: 'inherit',
                 script: assetsBundler.cmd,
-                scriptArgs: [],
+                scriptArgs: assetsBundler.args,
             });
             return true;
         }
@@ -46,6 +67,9 @@ export class Bundler {
             return false;
         }
     }
+    /**
+     * Runs tsc command to build the source.
+     */
     async #runTsc(outDir) {
         try {
             await run(this.#cwd, {
@@ -59,9 +83,12 @@ export class Bundler {
             return false;
         }
     }
+    /**
+     * Copy files to destination directory
+     */
     async #copyFiles(files, outDir) {
         try {
-            await copyfiles(files, outDir, { cwd: this.#cwdPath });
+            await copyFiles(files, this.#cwdPath, outDir);
         }
         catch (error) {
             if (!error.message.includes("the file doesn't exist")) {
@@ -69,12 +96,18 @@ export class Bundler {
             }
         }
     }
+    /**
+     * Copy meta files to the output directory
+     */
     async #copyMetaFiles(outDir, additionalFilesToCopy) {
         const metaFiles = (this.#options.metaFiles || [])
             .map((file) => file.pattern)
             .concat(additionalFilesToCopy);
         await this.#copyFiles(metaFiles, outDir);
     }
+    /**
+     * Copies .adonisrc.json file to the destination
+     */
     async #copyAdonisRcFile(outDir) {
         const existingContents = JSON.parse(await fs.readFile(join(this.#cwdPath, '.adonisrc.json'), 'utf-8'));
         const compiledContents = Object.assign({}, existingContents, {
@@ -84,6 +117,9 @@ export class Bundler {
         await fs.mkdir(outDir, { recursive: true });
         await fs.writeFile(join(outDir, '.adonisrc.json'), JSON.stringify(compiledContents, null, 2) + '\n');
     }
+    /**
+     * Returns the lock file name for a given packages client
+     */
     #getClientLockFile(client) {
         switch (client) {
             case 'npm':
@@ -94,6 +130,9 @@ export class Bundler {
                 return 'pnpm-lock.yaml';
         }
     }
+    /**
+     * Returns the installation command for a given packages client
+     */
     #getClientInstallCommand(client) {
         switch (client) {
             case 'npm':
@@ -104,24 +143,46 @@ export class Bundler {
                 return 'pnpm i --prod';
         }
     }
+    /**
+     * Set a custom CLI UI logger
+     */
     setLogger(logger) {
         this.#logger = logger;
         return this;
     }
+    /**
+     * Bundles the application to be run in production
+     */
     async bundle(stopOnError = true, client = 'npm') {
+        /**
+         * Step 1: Parse config file to get the build output directory
+         */
         const config = parseConfig(this.#cwd, this.#ts);
         if (!config) {
             return false;
         }
+        /**
+         * Step 2: Cleanup existing build directory (if any)
+         */
         const outDir = config.options.outDir || fileURLToPath(new URL('build/', this.#cwd));
         this.#logger.info('cleaning up output directory', { suffix: this.#getRelativeName(outDir) });
         await this.#cleanupBuildDirectory(outDir);
+        /**
+         * Step 3: Build frontend assets
+         */
         if (!(await this.#buildAssets())) {
             return false;
         }
+        /**
+         * Step 4: Build typescript source code
+         */
         this.#logger.info('compiling typescript source', { suffix: 'tsc' });
         const buildCompleted = await this.#runTsc(outDir);
         await this.#copyFiles(['ace.js'], outDir);
+        /**
+         * Remove incomplete build directory when tsc build
+         * failed and stopOnError is set to true.
+         */
         if (!buildCompleted && stopOnError) {
             await this.#cleanupBuildDirectory(outDir);
             const instructions = ui
@@ -133,13 +194,22 @@ export class Bundler {
             this.#logger.logError(instructions.prepare());
             return false;
         }
+        /**
+         * Step 5: Copy meta files to the build directory
+         */
         const pkgFiles = ['package.json', this.#getClientLockFile(client)];
         this.#logger.info('copying meta files to the output directory');
         await this.#copyMetaFiles(outDir, pkgFiles);
+        /**
+         * Step 6: Copy .adonisrc.json file to the build directory
+         */
         this.#logger.info('copying .adonisrc.json file to the output directory');
         await this.#copyAdonisRcFile(outDir);
         this.#logger.success('build completed');
         this.#logger.log('');
+        /**
+         * Next steps
+         */
         ui.instructions()
             .useRenderer(this.#logger.getRenderer())
             .heading('Run the following commands to start the server in production')

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,201 @@
+/*
+ * @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;
+    /**
+     * Settings to use when persisting files
+     */
+    #editorSettings = {
+        indentSize: 2,
+        convertTabsToSpaces: true,
+        trimTrailingWhitespace: true,
+    };
+    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}')`;
+        /**
+         * Delete the existing middleware if it exists
+         */
+        const existingMiddleware = arrayLiteralExpression
+            .getElements()
+            .findIndex((element) => element.getText() === middleware);
+        if (existingMiddleware !== -1) {
+            arrayLiteralExpression.removeElement(existingMiddleware);
+        }
+        /**
+         * Add the middleware to the top or bottom of the array
+         */
+        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.');
+        }
+        /**
+         * Check if property is already defined. If so, remove it
+         */
+        const existingProperty = namedMiddlewareObject.getProperty(middlewareEntry.name);
+        if (existingProperty)
+            existingProperty.remove();
+        /**
+         * Add the named middleware
+         */
+        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(this.#editorSettings);
+        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)) {
+            /**
+             * Check if the variable is already defined. If so, remove it
+             */
+            const existingProperty = objectLiteralExpression.getProperty(variable);
+            if (existingProperty)
+                existingProperty.remove();
+            objectLiteralExpression.addPropertyAssignment({
+                name: variable,
+                initializer: validation,
+                leadingTrivia: (writer) => {
+                    if (firstAdded)
+                        return;
+                    firstAdded = true;
+                    return this.#addLeadingComment(writer, definition.leadingComment);
+                },
+            });
+        }
+        file.formatText(this.#editorSettings);
+        await file.save();
+    }
+}