@vamship/build-utils 1.6.1 → 2.0.0-1

package/src/schema/project-definition.js

@@ -0,0 +1,137 @@
+/**
+ * Defines the JSON schema for a project definition.
+ */
+export default {
+    type: 'object',
+    properties: {
+        /**
+         * Project name
+         */
+        name: { type: 'string', minLength: 1 },
+
+        /**
+         * Project description
+         */
+        description: { type: 'string', minLength: 1 },
+
+        /**
+         * Project version
+         */
+        version: { type: 'string', minLength: 1 },
+
+        /**
+         * Metadata used to configure project builds.
+         */
+        buildMetadata: {
+            type: 'object',
+            properties: {
+                /**
+                 * The project type - determines the build tasks that are
+                 * generated.
+                 */
+                type: {
+                    enum: [
+                        'lib',
+                        'api',
+                        'cli',
+                        'ui',
+                        'container',
+                        'aws-microservice',
+                    ],
+                },
+
+                /**
+                 * The programming language used for the project.
+                 */
+                language: { enum: ['js', 'ts'] },
+
+                /**
+                 * AWS configuration - cloud formation stacks, etc.
+                 */
+                aws: {
+                    type: 'object',
+                    properties: {
+                        stacks: {
+                            type: 'object',
+                            /**
+                             * Individual stack names.
+                             */
+                            patternProperties: {
+                                '^[a-zA-Z0-9-_]+$': {
+                                    type: 'string',
+                                    minLength: 1,
+                                },
+                            },
+                            additionalProperties: false,
+                        },
+                    },
+                    additionalProperties: false,
+                    required: ['stacks'],
+                },
+
+                /**
+                 * Container configuration - image builds, etc.
+                 */
+                container: {
+                    type: 'object',
+                    /**
+                     * Container build configurations.
+                     */
+                    patternProperties: {
+                        '^[a-zA-Z0-9-_]+$': {
+                            type: 'object',
+                            properties: {
+                                /**
+                                 * Name of the repository that houses the
+                                 * container image.
+                                 */
+                                repo: { type: 'string', minLength: 1 },
+
+                                /**
+                                 * The file containing build instructions.
+                                 */
+                                buildFile: { type: 'string', minLength: 1 },
+
+                                /**
+                                 * Collection of arguments passed to the
+                                 * container build.
+                                 */
+                                buildArgs: {
+                                    type: 'object',
+                                    /**
+                                     * Individual build arguments
+                                     */
+                                    patternProperties: {
+                                        '^[a-zA-Z0-9-_]+$': {
+                                            type: 'string',
+                                            minLength: 1,
+                                        },
+                                    },
+                                    additionalProperties: false,
+                                },
+                            },
+                            required: ['repo'],
+                            additionalProperties: false,
+                        },
+                    },
+                    required: ['default'],
+                    additionalProperties: false,
+                },
+
+                /**
+                 * Any environment variables that have to be defined for the
+                 * build to succeed.
+                 */
+                requiredEnv: { type: 'array' },
+
+                /**
+                 * Any static files that should be copied over during the build
+                 * process without any compilation/modification.
+                 */
+                staticFilePatterns: { type: 'array' },
+            },
+            required: ['type', 'language'],
+        },
+    },
+    required: ['name', 'description', 'version', 'buildMetadata'],
+};

package/src/task-builder.js

@@ -0,0 +1,100 @@
+import { Project } from './project.js';
+
+/**
+ * Represents a builder class that can construct a Gulp task. This abstract base
+ * class must be extended by child classes that provide the required
+ * implementation.
+ */
+export default class TaskBuilder {
+    /**
+     * Creates a task builder with the given name and description.
+     *
+     * @param {string} name The name of the task - this will be the name
+     * recognized by gulp, and must be unique.
+     * @param {string} description The description of the task - this will be
+     * the description shown by gulp.
+     */
+    constructor(name, description) {
+        if (typeof name !== 'string' || name.length <= 0) {
+            throw new Error('Invalid name (arg #1)');
+        }
+        if (typeof description !== 'string' || description.length <= 0) {
+            throw new Error('Invalid description (arg #2)');
+        }
+
+        this._name = name;
+        this._description = description;
+    }
+
+    /**
+     * Creates a new task - needs to be implemented by a child class.
+     *
+     * @protected
+     * @param {Object} project The project for which the task will be created.
+     * @returns {Function} A gulp task
+     */
+    _createTask(project) {
+        throw new Error('Not implemented - TaskBuilder._createTask()');
+    }
+
+    /**
+     * Gets the name of the task.
+     *
+     * @returns {String} The task name.
+     */
+    get name() {
+        return this._name;
+    }
+
+    /**
+     * Gets the description of the task.
+     *
+     * @returns {String} The task description.
+     */
+    get description() {
+        return this._description;
+    }
+
+    /**
+     * Builds and returns a Gulp task.
+     *
+     * @param {Object} project The project for which the task will be created.
+     * @returns {Function} A gulp task
+     */
+    buildTask(project) {
+        if (!(project instanceof Project)) {
+            throw new Error('Invalid project (arg #1)');
+        }
+        const task = this._createTask(project);
+        task.displayName = this._name;
+        task.description = this._description;
+        return task;
+    }
+
+    /**
+     * Returns an array of paths that should be watched for changes when
+     * enabling watch (monitor and execute tasks). No watch tasks will be
+     * created if this method returns a falsy value or an empty array
+     *
+     * The default implementation returns an array that watches source files.
+     * This implementation can be overridden by child classes to provide
+     * specific paths for the task.
+     *
+     * @param {Object} project The project used to generate watch tasks.
+     * @returns {Array} An array of paths to watch.
+     */
+    getWatchPaths(project) {
+        if (!(project instanceof Project)) {
+            throw new Error('Invalid project (arg #1)');
+        }
+        const dirs = ['src', 'test', 'infra'];
+        const exts = ['md', 'html', 'json', 'js', 'jsx', 'ts', 'tsx'];
+        return dirs
+            .map((dir) =>
+                exts.map((ext) =>
+                    project.rootDir.getChild(dir).getAllFilesGlob(ext),
+                ),
+            )
+            .flat();
+    }
+}

package/src/task-builders/build-js-task-builder.js

@@ -0,0 +1,57 @@
+'use strict';
+
+import _gulp from 'gulp';
+
+import TaskBuilder from '../task-builder.js';
+import { Project } from '../project.js';
+
+/**
+ * Builder that can be used to generate a gulp task to copy javascript files
+ * from source to build directories.
+ */
+export class BuildJsTaskBuilder extends TaskBuilder {
+    /**
+     * Creates a new task builder.
+     */
+    constructor() {
+        super(
+            'build-js',
+            'Copies javascript files from source to destination directories',
+        );
+    }
+
+    /**
+     * Generates a gulp task to copy javascript files from source to build
+     * directories.
+     *
+     * @protected
+     * @param {Object} project Reference to the project for which the task needs
+     * to be defined.
+     *
+     * @returns {Function} A gulp task.
+     */
+    _createTask(project) {
+        if (!(project instanceof Project)) {
+            throw new Error('Invalid project (arg #1)');
+        }
+
+        const { rootDir } = project;
+        const dirs = ['src', 'test', 'infra'];
+        const extensions = ['js'];
+
+        const paths = dirs
+            .map((dir) => rootDir.getChild(dir))
+            .map((dir) => extensions.map((ext) => dir.getAllFilesGlob(ext)))
+            .reduce((result, arr) => result.concat(arr), []);
+
+        const task = () =>
+            _gulp
+                .src(paths, {
+                    allowEmpty: true,
+                    base: rootDir.globPath,
+                })
+                .pipe(_gulp.dest(rootDir.getChild('working').absolutePath));
+
+        return task;
+    }
+}

package/src/task-builders/build-task-builder.js

@@ -0,0 +1,78 @@
+'use strict';
+
+import _gulp from 'gulp';
+import TaskBuilder from '../task-builder.js';
+import { Project } from '../project.js';
+import { NotSupportedTaskBuilder } from './not-supported-task-builder.js';
+import { BuildJsTaskBuilder } from './build-js-task-builder.js';
+import { BuildTsTaskBuilder } from './build-ts-task-builder.js';
+import { BuildUiTaskBuilder } from './build-ui-task-builder.js';
+import { CopyFilesTaskBuilder } from './copy-files-task-builder.js';
+
+/**
+ * General purpose build task that configures sub tasks for build based on the
+ * project.
+ */
+export class BuildTaskBuilder extends TaskBuilder {
+    /**
+     * Creates a new task builder.
+     */
+    constructor() {
+        super(
+            'build',
+            `Builds the project making it ready for execution/packaging`,
+        );
+    }
+
+    /**
+     * Generates a gulp task to package a project for building a project.
+     *
+     * @protected
+     * @param {Object} project Reference to the project for which the task needs
+     * to be defined.
+     *
+     * @returns {Function} A gulp task.
+     */
+    _createTask(project) {
+        if (!(project instanceof Project)) {
+            throw new Error('Invalid project (arg #1)');
+        }
+
+        const builders = this._getSubBuilders(project).map((builder) =>
+            builder.buildTask(project),
+        );
+
+        const task = _gulp.series(builders);
+        return task;
+    }
+
+    /**
+     * Returns a list of sub builders based on the project type and language.
+     * @private
+     */
+    _getSubBuilders(project) {
+        const { type, language } = project;
+        if (type === 'ui') {
+            return [new BuildUiTaskBuilder(), new CopyFilesTaskBuilder()];
+        } else if (type === 'container') {
+            return [new NotSupportedTaskBuilder()];
+        } else if (language === 'ts') {
+            return [new BuildTsTaskBuilder(), new CopyFilesTaskBuilder()];
+        } else {
+            return [new BuildJsTaskBuilder(), new CopyFilesTaskBuilder()];
+        }
+    }
+
+    /**
+     * @override
+     */
+    getWatchPaths(project) {
+        if (!(project instanceof Project)) {
+            throw new Error('Invalid project (arg #1)');
+        }
+        const paths = this._getSubBuilders(project)
+            .map((builder) => builder.getWatchPaths(project))
+            .flat();
+        return [...new Set(paths)];
+    }
+}

package/src/task-builders/build-ts-task-builder.js

@@ -0,0 +1,63 @@
+'use strict';
+
+import _gulp from 'gulp';
+
+import _typescript from 'gulp-typescript';
+import TaskBuilder from '../task-builder.js';
+import { Project } from '../project.js';
+
+/**
+ * Builder that can be used to generate a gulp task to compile typescript files.
+ */
+export class BuildTsTaskBuilder extends TaskBuilder {
+    /**
+     * Creates a new task builder.
+     */
+    constructor() {
+        super(
+            'build-ts',
+            'Build typescript files and writes them to the build directory',
+        );
+    }
+
+    /**
+     * Generates a gulp task to build typescript files.
+     *
+     * @protected
+     * @param {Object} project Reference to the project for which the task needs
+     * to be defined.
+     *
+     * @returns {Function} A gulp task.
+     */
+    _createTask(project) {
+        if (!(project instanceof Project)) {
+            throw new Error('Invalid project (arg #1)');
+        }
+
+        const { rootDir } = project;
+        const dirs = ['src', 'test', 'infra'];
+        const extensions = ['ts'];
+
+        const paths = dirs
+            .map((dir) => rootDir.getChild(dir))
+            .map((dir) => extensions.map((ext) => dir.getAllFilesGlob(ext)))
+            .reduce((result, arr) => result.concat(arr), []);
+
+        const task = () =>
+            _gulp
+                .src(paths, {
+                    allowEmpty: true,
+                    base: rootDir.globPath,
+                })
+                .pipe(_typescript.createProject('tsconfig.json')())
+                .on('error', (err) => {
+                    /*
+                     * Do nothing. This handler prevents the gulp task from
+                     * crashing with an unhandled error.
+                     */
+                })
+                .pipe(_gulp.dest(rootDir.getChild('working').absolutePath));
+
+        return task;
+    }
+}

package/src/task-builders/build-ui-task-builder.js

@@ -0,0 +1,45 @@
+'use strict';
+
+import TaskBuilder from '../task-builder.js';
+import { Project } from '../project.js';
+import { execa as _execa } from 'execa';
+
+/**
+ * Builder that can be used to generate a gulp task to build a web UI project.
+ */
+export class BuildUiTaskBuilder extends TaskBuilder {
+    /**
+     * Creates a new task builder.
+     */
+    constructor() {
+        super('build-ui', 'Build web ui project');
+    }
+
+    /**
+     * Generates a gulp task to build a web UI project.
+     *
+     * @protected
+     * @param {Object} project Reference to the project for which the task needs
+     * to be defined.
+     *
+     * @returns {Function} A gulp task.
+     */
+    _createTask(project) {
+        if (!(project instanceof Project)) {
+            throw new Error('Invalid project (arg #1)');
+        }
+
+        const viteBin = project.rootDir.getFilePath('node_modules/.bin/vite');
+        const task = () =>
+            _execa(viteBin, ['build'], { stdio: 'inherit' }).then(
+                undefined,
+                (err) => {
+                    /*
+                     * Do nothing. This handler prevents the gulp task from
+                     * crashing with an unhandled error.
+                     */
+                },
+            );
+        return task;
+    }
+}

package/src/task-builders/clean-task-builder.js

@@ -0,0 +1,39 @@
+import _delete from 'delete';
+import TaskBuilder from '../task-builder.js';
+import { Project } from '../project.js';
+
+/**
+ * Builder that can be used to generate a gulp task to clean temporary project
+ * files.
+ */
+export class CleanTaskBuilder extends TaskBuilder {
+    /**
+     * Creates a new task builder.
+     */
+    constructor() {
+        super(
+            'clean',
+            'Cleans out working, distribution and temporary files and directories',
+        );
+    }
+
+    /**
+     * Generates a gulp task to clean up temporary project files.
+     *
+     * @protected
+     * @param {Object} project Reference to the project for which the task needs
+     * to be defined.
+     *
+     * @returns {Function} A gulp task.
+     */
+    _createTask(project) {
+        if (!(project instanceof Project)) {
+            throw new Error('Invalid project (arg #1)');
+        }
+        const rootDir = project.rootDir;
+        const dirs = ['coverage', 'dist', 'working', '.tscache', 'cdk.out'];
+
+        const paths = dirs.map((dir) => rootDir.getChild(dir).globPath);
+        return () => _delete(paths);
+    }
+}

package/src/task-builders/copy-files-task-builder.js

@@ -0,0 +1,78 @@
+'use strict';
+
+import _gulp from 'gulp';
+
+import TaskBuilder from '../task-builder.js';
+import { Project } from '../project.js';
+
+/**
+ * Builder that can be used to generate a gulp task to copy project files from
+ * source to build directories.
+ */
+export class CopyFilesTaskBuilder extends TaskBuilder {
+    /**
+     * Creates a new task builder.
+     */
+    constructor() {
+        super(
+            'copy-files',
+            'Copies project files from source to build directories',
+        );
+    }
+
+    /**
+     * Generates a gulp task to copy common files from source to build
+     * directories.
+     *
+     * @protected
+     * @param {Object} project Reference to the project for which the task needs
+     * to be defined.
+     *
+     * @returns {Function} A gulp task.
+     */
+    _createTask(project) {
+        if (!(project instanceof Project)) {
+            throw new Error('Invalid project (arg #1)');
+        }
+
+        const { rootDir } = project;
+        const dirs = ['src', 'test', 'infra'];
+        const extensions = ['json'].concat(project.getStaticFilePatterns());
+        const containerBuildFiles = project
+            .getContainerTargets()
+            .map(
+                (target) =>
+                    project.getContainerDefinition(target).buildFile ||
+                    'Dockerfile',
+            );
+
+        const extras = [
+            project.configFileName,
+            'package-lock.json',
+            'package.json',
+            'LICENSE',
+            'README.md',
+            '_scripts/*',
+            'nginx.conf',
+            '.env',
+            '.npmignore',
+            '.npmrc',
+        ].concat(containerBuildFiles);
+
+        const paths = dirs
+            .map((dir) => rootDir.getChild(dir))
+            .map((dir) => extensions.map((ext) => dir.getAllFilesGlob(ext)))
+            .reduce((result, arr) => result.concat(arr), [])
+            .concat(extras.map((item) => rootDir.getFileGlob(item)));
+
+        const task = () =>
+            _gulp
+                .src(paths, {
+                    allowEmpty: true,
+                    base: rootDir.globPath,
+                })
+                .pipe(_gulp.dest(rootDir.getChild('working').absolutePath));
+
+        return task;
+    }
+}

package/src/task-builders/docs-js-task-builder.js

@@ -0,0 +1,74 @@
+import _path from 'path';
+import _gulp from 'gulp';
+import _gulpJsdoc from 'gulp-jsdoc3';
+
+import TaskBuilder from '../task-builder.js';
+import { Project } from '../project.js';
+
+/**
+ * Builder that can be used to generate a gulp task to generate documentation
+ * from code comments in javascript files.
+ */
+export class DocsJsTaskBuilder extends TaskBuilder {
+    /**
+     * Creates a new task builder.
+     */
+    constructor() {
+        super(
+            'docs-js',
+            'Generates documentation from code comments in javascript files',
+        );
+    }
+
+    /**
+     * Generates a gulp task to generate documentation from code comments in
+     * source code.
+     *
+     * @protected
+     * @param {Object} project Reference to the project for which the task needs
+     * to be defined.
+     *
+     * @returns {Function} A gulp task.
+     */
+    _createTask(project) {
+        if (!(project instanceof Project)) {
+            throw new Error('Invalid project (arg #1)');
+        }
+
+        const { rootDir, name, version } = project;
+        const docsDir = rootDir.getChild('docs');
+
+        const dirs = ['src'];
+        const extensions = ['js'];
+        const options = {
+            opts: {
+                readme: rootDir.getFilePath('README.md'),
+                destination: docsDir.getFilePath(
+                    `${name}${_path.sep}${version}`,
+                ),
+                template: _path.join('node_modules', 'docdash'),
+            },
+        };
+
+        const paths = dirs
+            .map((dir) => project.rootDir.getChild(dir))
+            .map((dir) => extensions.map((ext) => dir.getAllFilesGlob(ext)))
+            .reduce((result, arr) => result.concat(arr), []);
+
+        const task = () =>
+            _gulp
+                .src(paths, {
+                    allowEmpty: true,
+                    base: project.rootDir.globPath,
+                })
+                .pipe(_gulpJsdoc(options))
+                .on('error', (err) => {
+                    /*
+                     * Do nothing. This handler prevents the gulp task from
+                     * crashing with an unhandled error.
+                     */
+                    console.error(err);
+                });
+        return task;
+    }
+}