@vamship/build-utils 1.0.0-0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) [2019] [Vamshi K Ponnapalli]
+
+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:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,179 @@
+# @vamship/grunt-utils
+
+_Library of modules that are designed to construct an opinionated dev/build
+toolchain for Javascript and Typescript projects._
+
+> This library was originally intended for internal consumption, though the
+> functionality provided by this library is fairly generic.
+
+## API Documentation
+
+API documentation can be found [here](https://vamship.github.io/build-utils).
+
+## Motivation
+
+In addition to writing code (and tests!), every project brings with it a common
+set of tasks that comprise a _development workflow_ for the project. This
+workflow includes common activities such as linting, formatting files, testing,
+building, packaging, etc.
+
+Having consistent way of performing these tasks makes it easier to switch from
+one project to another, because all common tasks will be identical for a given
+class of project (nodejs library, API server, etc.).
+
+In order to ensure this consistency, a common task automation framework (Gulp)
+is used, combined with a consistent configuration and development tool set for
+that framework.
+
+This library exports modules and classes that enable the creation of Gulpfiles,
+ensuring that they can be ported from project to project with no changes.
+
+All project specific parameters can be declared within a `buildMetdata` property
+in package.json.
+
+## Installation
+
+This library can be installed using npm:
+
+```
+npm install @vamship/build-utils
+```
+
+## Usage
+
+This library is intended to be used with a Gulpfile that imports the necessary
+tasks for the build system. The `examples` directory has a sample Gulpfile that
+can be used for any project.
+
+### Environment Variables
+
+Setting certain environment variables can alter the behavior of different build
+tasks. The environment variables and their effects are listed below:
+
+`BUILD_EXPORT_DOCKER_IMAGE`: When set to `true`, packaging a docker enabled
+project will result in the creation of a tar file called `image-<key>.tar`
+(using `docker save ...`) under the dist directory.
+
+`BUILD_DOCKER_REPO`: This environment variable can be used to override the
+docker repository name during package/publish operations.
+
+### Configuring package.json
+
+The build system derives its configuration from buildMetadata that is explicitly
+passed to the the project object via the Gulpfile, or by configuring settings
+in the package.json file. We **strongly recommend** the use of package.json to
+configure the build system.
+
+Build metadata is identified in `package.json` via a property named
+`buildMetadata`, which is an object that supports the following fields:
+
+```json
+{
+  "projectType": "lib|cli|api|aws-microservice|container",
+  "language": "ts|js",
+  "requiredEnv": [ "...", "..." ],
+  "aws": {
+    "stacks" {
+      "stack-key": "stack-name",
+      ...
+    }
+  },
+  "docker": {
+    "x86": {
+      "repo": "...",
+      "buildFile": "Dockerfile"
+      "buildArgs": {
+        "arg-name": "__ENV__|<value>"
+      },
+      "isDefault": true,
+    },
+    "arm64": {
+      "repo": "...",
+      "buildFile": "Dockerfile.arm64"
+      "buildArgs": {
+        "arg-name": "__ENV__|<value>"
+      }
+    }
+  }
+}
+```
+
+Note that all properties are not required for all types of projects. Refer to
+the package.json files in the `examples` directory to get an idea of typical
+configuration for different project types.
+
+#### Upgrading to v0.3x
+
+Starting from version 0.3, the docker build configuration supports multiple
+targets, meaning that the application may be used to generate different docker
+images, typically intended for different processor architectures. While the
+changes are backwards compatible with 0.2.x, a deprecation warning will be
+posted if the old style configuration is specified.
+
+In order to upgrade to v 0.3 and above, the docker section should be updated
+from
+
+```
+  "docker": {
+    "repo": "...",
+    "registry": "Dockerfile"
+    "buildArgs": {
+      "arg-name": "__ENV__|<value>"
+    },
+  }
+```
+
+to:
+
+```
+  "docker": {
+    "default": {
+      "repo": "...",
+      "buildFile": "Dockerfile"
+      "buildArgs": {
+        "arg-name": "__ENV__|<value>"
+      }
+    }
+  }
+```
+
+The basic change is that the build configuration is specified as the value of a
+build target key.
+
+Note that the `docker.registry` parameter is no longer supported in the new
+configuration format.
+
+#### Properties:
+
+`projectType`: Identifies the project type, which in turn determines the build
+tasks generated by the system.
+
+`language`: The project language - javascript or typescript.
+
+`requiredEnv`: A list of environment variables that must be defined prior to some
+tasks, such as publishing AWS projects, packaging docker images, publishing
+private npm repositories, etc. The build system only checks for the existinence
+of these variables, but does not care about their values.
+
+`aws`: This object must be specified for aws microservice projects.
+`aws.stacks`: This sub object defines a list of cloud formation stacks published
+by the project. The keys represent the names that will be used for the gulp
+tasks, and the values are the names of the cloud formation stacks.
+
+`docker`: This object must be sepcified for projects that result in docker
+images. This could apply to multiple project types including `cli`, `api` and
+`container`. The docker configuration can specify multiple targets with
+different docker files and build arguments. Each target has a name and a
+corresponding set of configuration options. The name of the target can be any
+string, except that a target named "default" is treated as the default packaging
+target.
+
+Each target can have the following properties:
+
+`[target].repo`: A fully qualified repo name to be used to publish docker images.
+`[target].buildFile`: The name of the docker file to use for the build. If
+omitted, will default to "Dockerfile"
+`[target].buildArgs`: This is a map of build arguments that will be passed to
+docker at build time. The keys are the build argument names, and the values are
+the argument values. A special value `__ENV__` indicates that the actual value
+of the build argument must be extracted from the environment.

package/package.json

@@ -0,0 +1,92 @@
+{
+    "name": "@vamship/build-utils",
+    "version": "1.0.0-0",
+    "description": "Utility library for build tooling",
+    "main": "src/index.js",
+    "scripts": {
+        "clean": "rm -rf .nyc_output coverage",
+        "monitor": "nodemon --exec npm run test",
+        "test": "nyc mocha -R spec --recursive test/unit/ && nyc report --reporter=html",
+        "lint": "eslint src/**/*.js test/**/*.js",
+        "format": "prettier --write \"{{src,test}/**/*.js,README.md}\"",
+        "docs": "jsdoc --readme README.md --package package.json --template node_modules/docdash --destination docs --recurse src",
+        "all": "npm run format && npm run lint && npm run test && npm run clean"
+    },
+    "files": [
+        "package.json",
+        "LICENSE",
+        "README.md",
+        "src/**/*"
+    ],
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/vamship/build-utils.git"
+    },
+    "keywords": [
+        "gulp",
+        "build",
+        "test",
+        "utilities"
+    ],
+    "author": "Vamshi K Ponnapalli <vamshi.ponnapalli@gmail.com>",
+    "contributors": [
+        {
+            "name": "Onaje Baxley",
+            "email": "onaje.baxley@gmail.com"
+        }
+    ],
+    "license": "MIT",
+    "bugs": {
+        "url": "https://github.com/vamship/build-utils/issues"
+    },
+    "homepage": "https://github.com/vamship/build-utils#readme",
+    "devDependencies": {
+        "chai": "^4.3.4",
+        "chai-as-promised": "^7.1.1",
+        "eslint": "^7.32.0",
+        "gulp": "^4.0.2",
+        "gulp-eslint": "^6.0.0",
+        "gulp-jsdoc3": "^3.0.0",
+        "gulp-prettier": "^4.0.0",
+        "gulp-typedoc": "^3.0.1",
+        "gulp-typescript": "^5.0.1",
+        "gulp-zip": "^5.1.0",
+        "jsdoc": "^3.6.7",
+        "mocha": "^9.1.2",
+        "nodemon": "^2.0.13",
+        "nyc": "^15.1.0",
+        "prettier": "^2.4.1",
+        "rewire": "^5.0.0",
+        "sinon": "^11.1.2",
+        "sinon-chai": "^3.7.0"
+    },
+    "dependencies": {
+        "camelcase": "^6.2.0",
+        "delete": "^1.1.0",
+        "docdash": "^1.2.0",
+        "dotenv": "^10.0.0",
+        "dotenv-expand": "^5.1.0",
+        "execa": "^5.1.1",
+        "fancy-log": "^1.3.3",
+        "mkdirp": "^1.0.4",
+        "semver": "^7.3.5"
+    },
+    "peerDependencies": {
+        "@typescript-eslint/eslint-plugin": ">= ^4.25.0",
+        "@typescript-eslint/parser": ">= ^4.25.0",
+        "gulp": ">= ^4.0.2",
+        "gulp-eslint": ">= ^6.0.0",
+        "gulp-jsdoc3": ">= ^3.0.0",
+        "gulp-prettier": ">= ^4.0.0",
+        "gulp-typedoc": ">= ^3.0.1",
+        "gulp-typescript": ">= ^5.0.1",
+        "gulp-zip": ">= ^5.1.0",
+        "mocha": ">= ^9.1.2",
+        "nyc": ">= ^15.1.0",
+        "prettier": ">= ^2.4.1"
+    },
+    "optionalDependencies": {
+        "typedoc": ">= ^0.22.5",
+        "typescript": ">= ^4.4.4"
+    }
+}

package/src/directory.js

@@ -0,0 +1,234 @@
+'use strict';
+
+const _path = require('path');
+
+const _sepRegexp = new RegExp(_path.sep.replace(/\\/g, '\\\\'), 'g');
+
+/**
+ * Abstract representation of a directory, with methods for traversal and
+ * glob pattern generation.
+ */
+class Directory {
+    /**
+     * @param {String} path The path represented by this directory.
+     */
+    constructor(path) {
+        if (typeof path !== 'string') {
+            throw new Error('Invalid path specified (arg #1)');
+        }
+
+        let relativePath = path.replace(process.cwd(), '');
+        this._name = _path.basename(_path.resolve(path));
+        this._path = _path.join(relativePath, `.${_path.sep}`);
+
+        this._absolutePath = _path.join(_path.resolve(path), _path.sep);
+        this._globPath = this._absolutePath.replace(_sepRegexp, '/');
+
+        this._children = [];
+    }
+
+    /**
+     * Creates a folder tree based on an object that describes the tree
+     * structure.
+     *
+     * @param {String} rootPath A string that represents the path to the root
+     *        directory of the tree.
+     * @param {Object} tree An object representation of the tree structure.
+     * @return {Directory} A directory object that represents the root of
+     *         the tree.
+     */
+    static createTree(rootPath, tree) {
+        if (typeof rootPath !== 'string') {
+            throw new Error('Invalid rootPath specified (arg #1)');
+        }
+        if (!tree || tree instanceof Array || typeof tree !== 'object') {
+            throw new Error('Invalid tree specified (arg #2)');
+        }
+
+        function createRecursive(parent, tree) {
+            if (typeof parent === 'string') {
+                parent = new Directory(parent);
+            }
+
+            if (tree && !(tree instanceof Array) && typeof tree === 'object') {
+                for (let dirName in tree) {
+                    let child = parent.addChild(dirName);
+                    createRecursive(child, tree[dirName]);
+                }
+            }
+            return parent;
+        }
+
+        return createRecursive(rootPath, tree);
+    }
+
+    /**
+     * Traverses a directory tree, invoking the callback function at each level
+     * of the tree.
+     *
+     * @param {Directory} root The root level of the tree to traverse.
+     * @param {Function} callback The callback function that is invoked as each
+     *        directory is traversed.
+     */
+    static traverseTree(root, callback) {
+        if (!(root instanceof Directory)) {
+            throw new Error('Invalid root directory specified (arg #1)');
+        }
+        if (typeof callback !== 'function') {
+            throw new Error('Invalid callback function specified (arg #1)');
+        }
+        function traverseRecursive(parent, level) {
+            callback(parent, level);
+            level++;
+            parent.getChildren().forEach((child) => {
+                traverseRecursive(child, level);
+            });
+        }
+
+        return traverseRecursive(root, 0);
+    }
+
+    /**
+     * Returns the name of the directory.
+     *
+     * @type {String}
+     */
+    get name() {
+        return this._name;
+    }
+
+    /**
+     * Returns the relative path to this directory.
+     *
+     * @return {String}
+     */
+    get path() {
+        return this._path;
+    }
+
+    /**
+     * Returns the absolute path to this directory.
+     *
+     * @type {String}
+     */
+    get absolutePath() {
+        return this._absolutePath;
+    }
+
+    /**
+     * Returns the glob path to the file.
+     */
+    get globPath() {
+        return this._globPath;
+    }
+
+    /**
+     * Adds a child directory object to the current directory.
+     *
+     * @param {String} name Name of the child directory.
+     */
+    addChild(name) {
+        if (typeof name !== 'string' || name.length <= 0) {
+            throw new Error('Invalid directory name specified (arg #1)');
+        }
+        if (name.match(/[\\/:]/)) {
+            throw new Error(
+                'Directory name cannot include path separators (:, \\ or /)'
+            );
+        }
+        const child = new Directory(_path.join(this.path, name));
+        this._children.push(child);
+
+        return child;
+    }
+
+    /**
+     * Retrieves a child directory object by recursively searching through the
+     * current directory's child tree.
+     *
+     * @param {String} path The relative path to the child directory, with
+     *        each path element separated by "/".
+     * @return {Directory} A directory reference for the specified child. If
+     *         a child is not found at the specified path, an error will be
+     *         thrown.
+     */
+    getChild(path) {
+        if (typeof path !== 'string' || path.length <= 0) {
+            throw new Error('Invalid child path specified (arg #1)');
+        }
+        const tokens = path.split('/');
+        const child = tokens.reduce((result, name) => {
+            if (!result) {
+                return result;
+            }
+            const children = result.getChildren();
+            return children.find((child) => child.name === name);
+        }, this);
+
+        if (!child) {
+            throw new Error(`Child not found at path: [${path}]`);
+        }
+        return child;
+    }
+
+    /**
+     * Returns an array containing all first level children of the current
+     * directory.
+     *
+     * @return {Directory[]} An array of first level children for the directory.
+     */
+    getChildren() {
+        return this._children.slice();
+    }
+
+    /**
+     * Returns the path to a file within the current directory. This file
+     * does not have to actually exist on the file system, and can also be the
+     * name of a directory.
+     *
+     * @param {String} fileName The name of the file.
+     * @return {String} The path to the file including the current directory
+     *         path.
+     */
+    getFilePath(fileName) {
+        if (typeof fileName !== 'string') {
+            fileName = '';
+        }
+        return _path.join(this.absolutePath, fileName);
+    }
+
+    /**
+     * Returns a glob path to a file within the current directory. This file
+     * does not have to actually exist on the file system, and can also be the
+     * name of a directory.
+     *
+     * @param {String} fileName The name of the file.
+     * @return {String} The path to the file including the current directory
+     *         path.
+     */
+    getFileGlob(fileName) {
+        if (typeof fileName !== 'string') {
+            fileName = '';
+        }
+        return _path.join(this.absolutePath, fileName).replace(_sepRegexp, '/');
+    }
+
+    /**
+     * Gets a string glob that can be used to match all folders/files in the
+     * current folder and all sub folders, optionally filtered by file
+     * extension.
+     *
+     * @param {String} [extension] An optional extension to use when generating
+     *        a globbing pattern.
+     */
+    getAllFilesGlob(extension) {
+        if (typeof extension !== 'string') {
+            extension = '*';
+        } else {
+            extension = `*.${extension}`;
+        }
+        return `${this.globPath}**/${extension}`;
+    }
+}
+
+module.exports = Directory;

package/src/index.js

@@ -0,0 +1,22 @@
+'use strict';
+
+/**
+ * Utility library that can be used to create development tooling.
+ */
+module.exports = {
+    /**
+     * A class that represents a directory on the file system.
+     */
+    Directory: require('./directory'),
+
+    /**
+     * Represents a specific project configuration.
+     */
+    Project: require('./project'),
+
+    /**
+     * A collection of task builder functions that can be used to generate
+     * commonly used gulp files for projects.
+     */
+    taskBuilders: require('./task-builders'),
+};