@vamship/build-utils 1.0.0-0

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

@@ -0,0 +1,47 @@
+'use strict';
+
+const _gulp = require('gulp');
+
+/**
+ * Sub builder that creates a task that will copy type declaration files that
+ * have been marked for export from source to build directories. This method
+ * will return a watcher if the watch option is set to true.
+ *
+ * @private
+ * @param {Object} project Reference to an object that contains project metadata
+ *        that can be used to customize build outputs.
+ * @param {Object} options An options object that can be used to customize the
+ *        task.
+ *
+ * @returns {Function} A gulp task.
+ */
+module.exports = (project, options) => {
+    const { watch } = Object.assign({ watch: false }, options);
+    const rootDir = project.rootDir;
+    const workingDir = rootDir.getChild('working');
+
+    const paths = [project.exportedTypes]
+        .map((dir) => rootDir.getChild(dir))
+        .map((dir) => [undefined].map((ext) => dir.getAllFilesGlob(ext)))
+        .reduce((result, arr) => result.concat(arr), []);
+    console.log('building types');
+
+    const task = () =>
+        _gulp
+            .src(paths, { allowEmpty: true, base: rootDir.globPath })
+            .pipe(_gulp.dest(workingDir.absolutePath));
+
+    task.displayName = 'build-types';
+    task.description =
+        'Copy type declaration files from source to build directory';
+
+    if (watch) {
+        const watchTask = () => _gulp.watch(paths, task);
+        watchTask.displayName = 'watch-build-types';
+        watchTask.description =
+            'Automatically copy type declaration files to build directory on change';
+
+        return watchTask;
+    }
+    return task;
+};

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

@@ -0,0 +1,52 @@
+'use strict';
+
+const _gulp = require('gulp');
+
+/**
+ * Builder function that can be used to generate a gulp task to build source
+ * files. The task takes on different implementations based on project types.
+ * For example, this task will compile typescript projects, copy AWS
+ * microservice projects to the target directory, and has no effect on other
+ * pure javascript projects.
+ *
+ * @param {Object} project Reference to an object that contains project metadata
+ *        that can be used to customize build outputs.
+ * @param {Object} options An options object that can be used to customize the
+ *        task.
+ *
+ * @returns {Function} A gulp task.
+ */
+module.exports = (project, options) => {
+    const { watch } = Object.assign({ watch: false }, options);
+
+    if (
+        !project.hasExportedTypes &&
+        !project.hasTypescript &&
+        project.projectType !== 'aws-microservice'
+    ) {
+        return;
+    }
+
+    const jsBuild = require('./build-js');
+    const tasks = [jsBuild(project, options)];
+
+    if (project.hasTypescript) {
+        const tsBuild = require('./build-ts');
+        tasks.push(tsBuild(project, options));
+    } else if (project.hasExportedTypes) {
+        const typesBuild = require('./build-types');
+        tasks.push(typesBuild(project, options));
+    }
+
+    const task = _gulp.parallel(tasks);
+    if (!watch) {
+        task.displayName = 'build';
+        task.description = 'Transpile/copy source files into working directory';
+    } else {
+        task.displayName = 'watch-build';
+        task.description =
+            'Automatically transpile/copy source files on change';
+    }
+
+    return task;
+};

package/src/task-builders/clean.js

@@ -0,0 +1,57 @@
+'use strict';
+
+const _delete = require('delete');
+
+/**
+ * Builder function that can be used to generate a gulp task to clean temporary
+ * project files.
+ *
+ * @param {Object} project Reference to an object that contains project metadata
+ *        that can be used to customize build outputs.
+ * @param {Object} options An options object that can be used to customize the
+ *        task.
+ *
+ * @returns {Function} A gulp task.
+ */
+module.exports = (project, options) => {
+    const rootDir = project.rootDir;
+
+    const dirs = ['coverage', 'dist'];
+    const extras = [];
+
+    if (
+        project.hasExportedTypes ||
+        project.hasTypescript ||
+        project.projectType === 'aws-microservice'
+    ) {
+        dirs.push('working');
+    }
+
+    if (project.hasTypescript) {
+        dirs.push('.tscache');
+        extras.push({
+            name: 'typescript-temp',
+            path: rootDir.getFileGlob('tscommand-*.tmp.txt'),
+        });
+    }
+
+    if (project.projectType === 'aws-microservice') {
+        dirs.push('cdk.out');
+    }
+
+    if (project.hasServer) {
+        extras.push({
+            name: 'logs',
+            path: rootDir.getChild('logs').getAllFilesGlob('log'),
+        });
+    }
+
+    const paths = dirs.map((dir) => rootDir.getChild(dir).globPath);
+    const task = () => _delete(paths);
+
+    task.displayName = 'clean';
+    task.description =
+        'Cleans out working, distribution and temporary files and directories';
+
+    return task;
+};

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

@@ -0,0 +1,41 @@
+'use strict';
+
+const _gulp = require('gulp');
+const _gulpJsdoc = require('gulp-jsdoc3');
+
+/**
+ * Sub builder that creates a task that will generate documentation from
+ * javascript files.
+ *
+ * @private
+ * @param {Object} project Reference to an object that contains project metadata
+ *        that can be used to customize build outputs.
+ * @param {Object} options An options object that can be used to customize the
+ *        task.
+ *
+ * @returns {Function} A gulp task.
+ */
+module.exports = (project, options) => {
+    const { rootDir, name, version } = project;
+
+    const docOptions = Object.assign(
+        {
+            opts: {
+                readme: rootDir.getFilePath('README.md'),
+                destination: rootDir.getFilePath(`docs/${name}/${version}`),
+                template: rootDir.getFilePath('node_modules/docdash'),
+            },
+        },
+        options
+    );
+
+    const paths = ['src']
+        .map((dir) => rootDir.getChild(dir))
+        .map((dir) => ['js'].map((ext) => dir.getAllFilesGlob(ext)))
+        .reduce((result, arr) => result.concat(arr), []);
+
+    const task = () =>
+        _gulp.src(paths, { allowEmpty: true }).pipe(_gulpJsdoc(docOptions));
+
+    return task;
+};

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

@@ -0,0 +1,40 @@
+'use strict';
+
+const _gulp = require('gulp');
+const _gulpTypedoc = require('gulp-typedoc');
+
+/**
+ * Sub builder that creates a task that will generate documentation from
+ * typescript files.
+ *
+ * @private
+ * @param {Object} project Reference to an object that contains project metadata
+ *        that can be used to customize build outputs.
+ * @param {Object} options An options object that can be used to customize the
+ *        task.
+ *
+ * @returns {Function} A gulp task.
+ */
+module.exports = (project, options) => {
+    const { rootDir, name, version } = project;
+
+    const docOptions = Object.assign(
+        {
+            name: `${name} Documentation`,
+            disableOutputCheck: true,
+            readme: rootDir.getFilePath('README.md'),
+            out: rootDir.getFilePath(`docs/${name}/${version}`),
+        },
+        options
+    );
+
+    const paths = ['src']
+        .map((dir) => rootDir.getChild(dir))
+        .map((dir) => ['ts'].map((ext) => dir.getAllFilesGlob(ext)))
+        .reduce((result, arr) => result.concat(arr), []);
+
+    const task = () =>
+        _gulp.src(paths, { allowEmpty: true }).pipe(_gulpTypedoc(docOptions));
+
+    return task;
+};

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

@@ -0,0 +1,32 @@
+'use strict';
+
+const _gulp = require('gulp');
+
+/**
+ * Builder function that can be used to generate a gulp task that generates
+ * documentation from code docs. The task takes on different implementations
+ * based on the programming language - javascript or typescript.
+ *
+ * @param {Object} project Reference to an object that contains project metadata
+ *        that can be used to customize build outputs.
+ * @param {Object} options An options object that can be used to customize the
+ *        task.
+ *
+ * @returns {Function} A gulp task.
+ */
+module.exports = (project, options) => {
+    let createTask = null;
+
+    if (project.hasTypescript) {
+        createTask = require('./docs-ts');
+    } else {
+        createTask = require('./docs-js');
+    }
+
+    const task = createTask(project, options);
+
+    task.displayName = 'docs';
+    task.description = 'Generates project documentation from code docs';
+
+    return task;
+};

package/src/task-builders/format.js

@@ -0,0 +1,56 @@
+'use strict';
+
+const _gulp = require('gulp');
+const _prettier = require('gulp-prettier');
+
+/**
+ * Builder function that can be used to generate a gulp task to format source
+ * files.
+ *
+ * @param {Object} project Reference to an object that contains project metadata
+ *        that can be used to customize build outputs.
+ * @param {Object} options An options object that can be used to customize the
+ *        task.
+ *
+ * @returns {Function} A gulp task.
+ */
+module.exports = (project, options) => {
+    const { watch } = Object.assign({ watch: false }, options);
+
+    const rootDir = project.rootDir;
+
+    const dirs = ['src', 'test', '.gulp'];
+    const extras = ['Gulpfile.js', 'README.md'];
+
+    if (project.projectType === 'aws-microservice') {
+        dirs.push('infra');
+    }
+
+    const paths = dirs
+        .map((dir) => rootDir.getChild(dir))
+        .map((dir) =>
+            ['ts', 'js', 'json', 'py'].map((ext) => dir.getAllFilesGlob(ext))
+        )
+        .reduce((result, arr) => result.concat(arr), [])
+        .concat(extras.map((file) => rootDir.getFileGlob(file)));
+
+    const task = () =>
+        _gulp
+            .src(paths, { allowEmpty: true, base: rootDir.globPath })
+            .pipe(_prettier())
+            .pipe(_gulp.dest(rootDir.absolutePath));
+
+    task.displayName = 'format';
+    task.description = 'Formats all source files, README.md and build scripts';
+
+    if (watch) {
+        const watch = () =>
+            _gulp.watch(paths, { usePolling: true, delay: 5000 }, task);
+
+        watch.displayName = 'watch-format';
+        watch.description = 'Automatically format files on change';
+
+        return watch;
+    }
+    return task;
+};

package/src/task-builders/index.js

@@ -0,0 +1,19 @@
+'use strict';
+
+/**
+ * A collection of task builder functions that can be used to generate gulp
+ * tasks based on project configuration.
+ */
+module.exports = [
+    'clean',
+    'format',
+    'lint',
+    'build',
+    'test',
+    'docs',
+    'package',
+    'publish',
+].reduce((tasks, task) => {
+    tasks[task] = require(`./${task}`);
+    return tasks;
+}, {});

package/src/task-builders/lint.js

@@ -0,0 +1,56 @@
+'use strict';
+
+const _gulp = require('gulp');
+const _eslint = require('gulp-eslint');
+
+/**
+ * Builder function that can be used to generate a gulp task to format source
+ * files.
+ *
+ * @param {Object} project Reference to an object that contains project metadata
+ *        that can be used to customize build outputs.
+ * @param {Object} options An options object that can be used to customize the
+ *        task.
+ *
+ * @returns {Function} A gulp task.
+ */
+module.exports = (project, options) => {
+    const { watch } = Object.assign({ watch: false }, options);
+
+    const rootDir = project.rootDir;
+    const extensions = ['js'];
+    const dirs = ['src', 'test'];
+
+    if (project.hasTypescript) {
+        extensions.push('ts');
+    }
+
+    if (project.projectType === 'aws-microservice') {
+        dirs.push('infra');
+    }
+
+    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 })
+            .pipe(_eslint())
+            .pipe(_eslint.format())
+            .pipe(_eslint.failAfterError());
+
+    task.displayName = 'lint';
+    task.description = 'Lints source files';
+
+    if (watch) {
+        return task;
+    } else {
+        const watchTask = () => _gulp.watch(paths, task);
+        watchTask.displayName = 'watch-lint';
+        watchTask.description = 'Automatically lint files on change';
+
+        return watchTask;
+    }
+};

package/src/task-builders/package/index.js

@@ -0,0 +1,50 @@
+'use strict';
+
+const _gulp = require('gulp');
+
+/**
+ * Builder function that can be used to generate a gulp task to package a
+ * project for distribution. The task takes on different implementations based
+ * on project types. For example, javascript libraries will yield an archive
+ * resulting from an `npm pack`, while docker enabled projects will result in
+ * the creation of a docker image.
+ *
+ * @param {Object} project Reference to an object that contains project metadata
+ *        that can be used to customize build outputs.
+ * @param {Object} options An options object that can be used to customize the
+ *        task.
+ *
+ * @returns {Function} A gulp task.
+ */
+module.exports = (project, options) => {
+    const { types } = options;
+    let createTask = null;
+
+    if (types) {
+        if (!project.hasExportedTypes) {
+            return;
+        }
+        createTask = require('./package-types');
+    } else if (project.projectType === 'aws-microservice') {
+        createTask = require('./package-aws');
+    } else if (project.hasDocker) {
+        createTask = require('./package-docker');
+    } else if (project.projectType === 'lib' || project.projectType === 'cli') {
+        createTask = require('./package-npm');
+    }
+
+    const task = createTask(project, options);
+
+    if (!(task instanceof Array)) {
+        if (types) {
+            task.displayName = 'package-types';
+            task.description =
+                'Create a distribution package for the types exported by the project';
+        } else {
+            task.displayName = 'package';
+            task.description = 'Create a distribution package for the project';
+        }
+    }
+
+    return task;
+};

package/src/task-builders/package/package-aws.js

@@ -0,0 +1,58 @@
+'use strict';
+
+const _gulp = require('gulp');
+const _zip = require('gulp-zip');
+const _execa = require('execa');
+
+/**
+ * Sub builder that packages an aws-microservice project for deployment. This
+ * follows the build steps described for
+ * [lambda deployments](https://docs.aws.amazon.com/lambda/latest/dg/nodejs-create-deployment-pkg.html#nodejs-package-dependencies)
+ *
+ * @private
+ * @param {Object} project Reference to an object that contains project metadata
+ *        that can be used to customize build outputs.
+ * @param {Object} options An options object that can be used to customize the
+ *        task.
+ *
+ * @returns {Function} A gulp task.
+ */
+module.exports = (project, options) => {
+    const { snakeCasedName, version, rootDir } = project;
+    const workingDir = rootDir.getChild('working');
+
+    const packageName = `${snakeCasedName}-${version}.zip`;
+
+    const installTask = () => {
+        const npmBin = 'npm';
+        const args = ['install', '--production'];
+
+        return _execa(npmBin, args, {
+            stdio: 'inherit',
+            cwd: workingDir.absolutePath,
+        });
+    };
+
+    installTask.displayName = 'package-aws-install';
+    installTask.description = 'Install package dependency in working directory';
+
+    const dirs = ['src', 'node_modules'];
+    const extras = ['package.json', project.configFileName];
+
+    const paths = dirs
+        .map((dir) => workingDir.getChild(dir))
+        .map((dir) => dir.getAllFilesGlob())
+        .concat(extras.map((file) => workingDir.getFileGlob(file)));
+
+    const zipTask = () =>
+        _gulp
+            .src(paths, { allowEmpty: true, base: workingDir.globPath })
+            .pipe(_zip(packageName))
+            .pipe(_gulp.dest(rootDir.getChild('dist').absolutePath));
+
+    zipTask.displayName = 'package-aws-zip';
+    zipTask.description =
+        'Create a project distribution for AWS lambda deployments';
+
+    return _gulp.series([installTask, zipTask]);
+};

package/src/task-builders/package/package-docker.js

@@ -0,0 +1,128 @@
+'use strict';
+
+const _execa = require('execa');
+const _gulp = require('gulp');
+const _log = require('fancy-log');
+const _mkdirp = require('mkdirp');
+
+/**
+ * Sub builder that builds a docker image based on a predefined dockerfile.
+ *
+ * @private
+ * @param {Object} project Reference to an object that contains project metadata
+ *        that can be used to customize build outputs.
+ * @param {Object} options An options object that can be used to customize the
+ *        task.
+ *
+ * @returns {Function} A gulp task.
+ */
+module.exports = (project, options) => {
+    const {
+        unscopedName,
+        version,
+        description,
+        configFileName,
+        jsRootDir,
+        rootDir,
+    } = project;
+
+    const dockerBin = 'docker';
+
+    const tasks = project.getDockerTargets().map((target) => {
+        const { name, buildFile, buildArgs, isDeprecated, isDefault } = target;
+
+        const suffix = isDefault ? '' : `-${name}`;
+        const targetName = isDefault ? '' : name;
+
+        let repo = target.repo;
+        if (typeof process.env.BUILD_DOCKER_REPO !== 'undefined') {
+            repo = process.env.BUILD_DOCKER_REPO;
+            _log.warn(`Docker repo override specified: [${repo}]`);
+        }
+
+        if (isDeprecated) {
+            _log.warn(
+                '[WARNING] Docker package task configuration is deprecated. Please upgrade to the newer format'
+            );
+            _log.warn(
+                '[WARNING] See: https://github.com/vamship/build-utils#upgrading-to-v03x for more information'
+            );
+        }
+
+        const buildTaskArgs = [
+            'build',
+            '--rm',
+            '--file',
+            buildFile,
+            '--tag',
+            `${repo}:latest`,
+            '--build-arg',
+            `APP_NAME=${unscopedName}`,
+            '--build-arg',
+            `APP_VERSION=${version}`,
+            '--build-arg',
+            `APP_DESCRIPTION='${description}'`,
+            '--build-arg',
+            `CONFIG_FILE_NAME=${configFileName}`,
+            '--build-arg',
+            `BUILD_TIMESTAMP=${Date.now()}`,
+        ];
+
+        project.validateRequiredEnv();
+        buildArgs.forEach(({ name, value }) => {
+            buildTaskArgs.push('--build-arg');
+            buildTaskArgs.push(`${name}=${value}`);
+        });
+
+        buildTaskArgs.push('.');
+
+        const buildTask = () =>
+            _execa(dockerBin, buildTaskArgs, {
+                stdio: 'inherit',
+                cwd: jsRootDir.absolutePath,
+            });
+        buildTask.displayName = `package-build${suffix}`;
+        buildTask.description = `Builds a docker image (${targetName}) based on the Dockerfile contained in the project`;
+
+        const tasks = [buildTask];
+
+        if (process.env.BUILD_EXPORT_DOCKER_IMAGE === 'true') {
+            _log.warn(`Docker save image enabled.`);
+
+            const distDir = rootDir.getChild('dist');
+            const savePath = distDir.getFilePath(`image${suffix}.tar`);
+
+            const ensureDirTask = () => {
+                _log.info(
+                    `Ensuring that output path exists: ${distDir.absolutePath}`
+                );
+                return _mkdirp(distDir.absolutePath);
+            };
+            ensureDirTask.displayName = `package-save${suffix}`;
+            ensureDirTask.description = `Ensures that destination directory (${savePath}) exists.`;
+            tasks.push(ensureDirTask);
+
+            const saveTask = () => {
+                _log.info(
+                    `Docker save enabled. File will be created at: ${savePath}`
+                );
+                return _execa(dockerBin, ['save', '--output', savePath, repo], {
+                    stdio: 'inherit',
+                    cwd: jsRootDir.absolutePath,
+                });
+            };
+            saveTask.displayName = `package-save${suffix}`;
+            ensureDirTask.description = `Saves a tar file that represents the docker image`;
+            tasks.push(saveTask);
+        }
+
+        const task = _gulp.series(tasks);
+
+        task.displayName = `package${suffix}`;
+        task.description = `Builds a docker image (${targetName}) based on the Dockerfile contained in the project`;
+
+        return task;
+    });
+
+    return tasks;
+};

package/src/task-builders/package/package-npm.js

@@ -0,0 +1,25 @@
+'use strict';
+
+const { createNpmPackageTask } = require('./utils');
+
+/**
+ * Sub builder that packages a project using npm pack, from source files or
+ * compiled typescript files.
+ *
+ * @private
+ * @param {Object} project Reference to an object that contains project metadata
+ *        that can be used to customize build outputs.
+ * @param {Object} options An options object that can be used to customize the
+ *        task.
+ *
+ * @returns {Function} A gulp task.
+ */
+module.exports = (project, options) => {
+    const { snakeCasedName, version, rootDir, jsRootDir } = project;
+
+    const packageName = `${snakeCasedName}-${version}.tgz`;
+    const packageDir = jsRootDir;
+    const distDir = rootDir.getChild('dist');
+
+    return createNpmPackageTask(packageDir, packageName, distDir);
+};