@automattic/vip 4.1.5 → 4.1.8

package/node_modules/lando/lib/plugins.js

@@ -22,39 +22,52 @@ const autoLoaders = [
   'types',
 ];
 
-// Helper to build out a fully fleshed plugin object
+/**
+ * Builds the base plugin metadata for a discovered plugin file.
+ * @param {string} file Plugin entry file.
+ * @param {string} namespace Plugin namespace prefix.
+ * @returns {{name: string, path: string, dir: string}} Plugin metadata.
+ */
 const buildPlugin = (file, namespace) => ({
   name: _.compact([namespace, _.last(resolver(path.dirname(file)).split(path.sep))]).join('/'),
   path: file,
   dir: path.dirname(file),
 });
 
-// Helper to discover things in the plugin that can be autoloaded
+/**
+ * Discovers autoloadable resources within a plugin directory.
+ * @param {{dir: string}} plugin Plugin metadata.
+ * @returns {object} Discovered autoload entries keyed by basename.
+ */
 const discoverPlugin = plugin => _(autoLoaders)
     .map(thing => path.join(plugin.dir, thing))
     .filter(path => fs.existsSync(path))
     .keyBy(file => path.basename(_.last(file.split(path.sep)), '.js'))
     .value();
 
-/*
- * @TODO
+/**
+ * Discovers and loads Lando plugins.
  */
 module.exports = class Plugins {
+  /**
+   * @param {Log} [log] Logger instance.
+   */
   constructor(log = new Log()) {
+    /** @type {object[]} */
     this.registry = [];
+    /** @type {Log} */
     this.log = log;
   };
 
   /**
    * Finds plugins
-   *
    * @since 3.5.0
    * @alias lando.plugins.find
-   * @param {Array} dirs Directories to scan for plugins
-   * @param {Object} options Options to pass in
-   * @param {Array} [options.disablePlugins=[]] Array of plugin names to not load
-   * @param {Array} [options.plugins=[]] Array of additional plugins to consider loading
-   * @return {Array} Array of plugin metadata
+   * @param {Array<string|object>} dirs Directories to scan for plugins.
+   * @param {object} [options] Options to pass in.
+   * @param {string[]} [options.disablePlugins] Array of plugin names to not load.
+   * @param {object[]} [options.plugins] Array of additional plugins to consider loading.
+   * @returns {object[]} Array of plugin metadata.
    */
   find(dirs, {disablePlugins = [], plugins = []} = {}) {
     return _(dirs)
@@ -106,13 +119,12 @@ module.exports = class Plugins {
 
   /**
    * Loads a plugin.
-   *
    * @since 3.0.0
    * @alias lando.plugins.load
-   * @param {Object} plugin The name of the plugin
-   * @param {String} [file=plugin.path] That path to the plugin
-   * @param {Object} [...injected] Something to inject into the plugin
-   * @return {Object} Data about our plugin.
+   * @param {object} plugin The plugin metadata.
+   * @param {string} [file] The path to the plugin.
+   * @param {...object} injected Something to inject into the plugin.
+   * @returns {object} Data about our plugin.
    */
   load(plugin, file = plugin.path, ...injected) {
     try {

package/node_modules/lando/lib/promise.js

@@ -3,14 +3,11 @@
 /**
  * Extends [bluebird](http://bluebirdjs.com/docs/api-reference.html)
  * so that our promises have some retry functionality.
- *
  * All functionality should be the same as bluebird except where indicated
- * below
- *
+ * below.
  * Note that bluebird currently wants you to use scoped prototypes to extend
  * it rather than the normal extend syntax so that is why this is using the "old"
- * way
- *
+ * way.
  * @member
  * @alias lando.Promise
  * @see http://bluebirdjs.com/docs/api-reference.html
@@ -22,9 +19,13 @@ const Promise = require('bluebird');
 // Use long stack traces.
 Promise.config({longStackTraces: true, cancellation: true});
 
-/*
- * Retry the function fn up to max times until it successfully completes
- * without an error. Pause backoff * retry milliseconds between tries.
+/**
+ * Retries a function until it resolves or the retry limit is exhausted.
+ * @param {function(number): Promise} fn Function to retry.
+ * @param {object} [opts] Retry options.
+ * @param {number} [opts.max] Maximum retry attempts.
+ * @param {number} [opts.backoff] Retry delay multiplier in milliseconds.
+ * @returns {Promise} Promise resolving to the callback result.
  */
 const retry = (fn, {max = 5, backoff = 500} = {}) => Promise.resolve().then(() => {
   const rec = counter => Promise.try(() => fn(counter).catch(err => {
@@ -39,25 +40,24 @@ const retry = (fn, {max = 5, backoff = 500} = {}) => Promise.resolve().then(() =
   return rec(1);
 });
 
-/*
- * Adds a retry method to the bluebird Promise module.
+/**
+ * Adds a retry helper to the Promise constructor.
+ * @type {function(function(number): Promise, object=): Promise}
  */
 Promise.retry = retry;
 
 /**
  * Adds a retry method to all Promise instances.
- *
  * @since 3.0.0
  * @alias lando.Promise.retry
- * @param {Function} fn The function to retry.
- * @param {Opts} [opts] Options to specify how retry works.
- * @param {Integer} [opts.max=5] The amount of times to retry.
- * @param {Integer} [opts.backoff=500] The amount to wait between retries. In milliseconds and cumulative.
- * @return {Promise} A Promise
+ * @param {function(number): Promise} fn The function to retry.
+ * @param {object} [opts] Options to specify how retry works.
+ * @param {number} [opts.max] The amount of times to retry.
+ * @param {number} [opts.backoff] The amount to wait between retries in milliseconds and cumulative.
+ * @returns {Promise} A Promise.
  * @example
  * // And then retry 25 times until we've connected, increase delay between retries by 1 second
  * Promise.retry(someFunction, {max: 25, backoff: 1000});
- *
  */
 // eslint-disable-next-line no-extend-native
 Promise.prototype.retry = retry;

package/node_modules/lando/lib/router.js

@@ -6,9 +6,11 @@ const _ = require('lodash');
 const Promise = require('./promise');
 const utils = require('./utils');
 
-// Helper to strip user from opts
-// NOTE: we need this because our run command will try start/stop with run opts if it needs to
-// and docker compose does not like that
+/**
+ * Removes run-specific options before delegating to start/stop operations.
+ * @param {import('./engine').EngineTaskData} datum Engine task data.
+ * @returns {import('./engine').EngineTaskData} Cloned task data without incompatible run options.
+ */
 const stripRun = datum => {
   const newDatum = _.cloneDeep(datum);
   if (_.has(newDatum, 'opts.user')) delete newDatum.opts.user;
@@ -18,19 +20,41 @@ const stripRun = datum => {
   return newDatum;
 };
 
-// Helper to retry each
+/**
+ * Runs an operation over one or more task entries in series.
+ * @param {import('./engine').EngineTaskData|import('./engine').EngineTaskData[]} data Engine task data.
+ * @param {function(import('./engine').EngineTaskData): Promise} run Operation to run for each datum.
+ * @returns {Promise} Bluebird promise for the serial operation.
+ */
 const retryEach = (data, run) => Promise.each(utils.normalizer(data), datum => run(datum));
 
-// Helper to run engine event commands
+/**
+ * Wraps an engine command with daemon startup and event emission.
+ * @param {string} name Engine action name.
+ * @param {import('./daemon')} daemon Daemon controller.
+ * @param {import('./events')} events Event emitter.
+ * @param {import('./engine').EngineTaskData|import('./engine').EngineTaskData[]} data Engine task data.
+ * @param {function(import('./engine').EngineTaskData|import('./engine').EngineTaskData[]): Promise} run Action callback.
+ * @returns {Promise} Promise for the wrapped action.
+ */
 exports.eventWrapper = (name, daemon, events, data, run) => daemon.up()
     .then(() => events.emit(`pre-engine-${name}`, data))
     .then(() => run(data))
     .tap(() => events.emit(`post-engine-${name}`, data));
 
+/**
+ * Routes pull requests through compose.
+ * @param {import('./engine').EngineComposeTaskData|import('./engine').EngineComposeTaskData[]} data Compose task data.
+ * @param {import('./engine').ComposeCommandRunner} compose Compose command runner.
+ * @returns {Promise} Promise for the pull operation.
+ */
 exports.pull = (data, compose) => retryEach(data, datum => compose('pull', datum));
 
-/*
- * Helper to route to build command
+/**
+ * Pulls images and then builds compose services.
+ * @param {import('./engine').EngineComposeTaskData|import('./engine').EngineComposeTaskData[]} data Compose task data.
+ * @param {import('./engine').ComposeCommandRunner} compose Compose command runner.
+ * @returns {Promise} Promise for the build workflow.
  */
 exports.build = (data, compose) => {
   // Pull
@@ -39,15 +63,24 @@ exports.build = (data, compose) => {
       .then(() => retryEach(data, datum => compose('build', datum)));
 };
 
-/*
- * Helper to route to destroy command
+/**
+ * Removes compose or docker resources for the provided task data.
+ * @param {import('./engine').EngineTaskData|import('./engine').EngineTaskData[]} data Engine task data.
+ * @param {import('./engine').ComposeCommandRunner} compose Compose command runner.
+ * @param {import('./docker')} docker Docker client wrapper.
+ * @returns {Promise} Promise for the destroy workflow.
  */
 exports.destroy = (data, compose, docker) => retryEach(data, datum => {
   return (datum.compose) ? compose('remove', datum) : docker.remove(utils.getId(datum), datum.opts);
 });
 
-/*
- * Helper to route to exist command
+/**
+ * Checks whether the target compose service or container exists.
+ * @param {import('./engine').EngineTaskData} data Engine task data.
+ * @param {import('./engine').ComposeCommandRunner} compose Compose command runner.
+ * @param {import('./docker')} docker Docker client wrapper.
+ * @param {string[]} [ids] Reused id accumulator.
+ * @returns {Promise} Promise resolving to whether the target exists.
  */
 exports.exists = (data, compose, docker, ids = []) => {
   if (data.compose) return compose('getId', data).then(id => !_.isEmpty(id));
@@ -61,13 +94,21 @@ exports.exists = (data, compose, docker, ids = []) => {
   }
 };
 
-/*
- * Helper to route to destroy command
+/**
+ * Streams logs for compose services.
+ * @param {import('./engine').EngineComposeTaskData|import('./engine').EngineComposeTaskData[]} data Compose task data.
+ * @param {import('./engine').ComposeCommandRunner} compose Compose command runner.
+ * @returns {Promise} Promise for the logs operation.
  */
 exports.logs = (data, compose) => retryEach(data, datum => compose('logs', datum));
 
-/*
- * Helper to route to run command
+/**
+ * Runs commands inside services, starting or stopping containers as needed.
+ * @param {import('./engine').EngineRunTaskData|import('./engine').EngineRunTaskData[]} data Engine task data.
+ * @param {import('./engine').ComposeCommandRunner} compose Compose command runner.
+ * @param {import('./docker')} docker Docker client wrapper.
+ * @param {boolean} [started] Whether the target is already running.
+ * @returns {Promise} Promise for the run workflow.
  */
 exports.run = (data, compose, docker, started = true) => Promise.mapSeries(utils.normalizer(data), datum => {
   // Merge in default cli envars
@@ -101,8 +142,12 @@ exports.run = (data, compose, docker, started = true) => Promise.mapSeries(utils
       });
 });
 
-/*
- * Helper to route to scan command
+/**
+ * Inspects the running container backing a compose or docker task.
+ * @param {import('./engine').EngineTaskData} data Engine task data.
+ * @param {import('./engine').ComposeCommandRunner} compose Compose command runner.
+ * @param {import('./docker')} docker Docker client wrapper.
+ * @returns {Promise|undefined} Promise for the scan operation.
  */
 exports.scan = (data, compose, docker) => {
   if (data.compose) {
@@ -118,15 +163,24 @@ exports.scan = (data, compose, docker) => {
   } else if (utils.getId(data)) {
     return docker.scan(utils.getId(data));
   }
+
+  return undefined;
 };
 
-/*
- * Helper to route to start command
+/**
+ * Starts compose services.
+ * @param {import('./engine').EngineComposeTaskData|import('./engine').EngineComposeTaskData[]} data Compose task data.
+ * @param {import('./engine').ComposeCommandRunner} compose Compose command runner.
+ * @returns {Promise} Promise for the start operation.
  */
 exports.start = (data, compose) => retryEach(data, datum => compose('start', datum));
 
-/*
- * Helper to route to stop command
+/**
+ * Stops compose or standalone docker containers.
+ * @param {import('./engine').EngineTaskData|import('./engine').EngineTaskData[]} data Engine task data.
+ * @param {import('./engine').ComposeCommandRunner} compose Compose command runner.
+ * @param {import('./docker')} docker Docker client wrapper.
+ * @returns {Promise} Promise for the stop operation.
  */
 exports.stop = (data, compose, docker) => retryEach(data, datum => {
   return (datum.compose) ? compose('stop', datum) : docker.stop(utils.getId(datum));

package/node_modules/lando/lib/scan.js

@@ -8,10 +8,10 @@ const Log = require('./logger');
 // eslint-disable-next-line no-redeclare
 const Promise = require('./promise');
 
-/*
- * Helper to load request library
- * We do this for testing so we can stub axios and ensure it isn't auto cached
- * via require when we new Lando()
+/**
+ * Loads an axios client configured for URL scanning.
+ * This is loaded lazily so tests can stub axios before it is cached.
+ * @returns {object} Axios client instance.
  */
 const requestClient = () => {
   const axios = require('axios');
@@ -26,28 +26,45 @@ const requestClient = () => {
 
 // We make this module into a function so we can pass in a logger
 module.exports = (log = new Log()) => {
-  // Helper to return a url status and log things
+  /**
+   * Builds a URL scan result and logs the outcome.
+   * @param {string} url Scanned URL.
+   * @param {boolean} [status] Whether the URL is considered available.
+   * @param {string} [color] CLI color hint.
+   * @param {string} [message] Log message template.
+   * @returns {{url: string, status: boolean, color: string}} Scan result.
+   */
   const setStatus = (url, status = true, color = 'green', message = '%s is ready') => {
     log.debug(message, url);
     return {url, status, color};
   };
 
-  // Convenience helpers
+  /**
+   * @param {string} url URL to mark as available.
+   * @returns {{url: string, status: boolean, color: string}} Scan result.
+   */
   const setGood = url => setStatus(url);
+  /**
+   * @param {string} url URL to mark as reachable with caveats.
+   * @returns {{url: string, status: boolean, color: string}} Scan result.
+   */
   const setOK = url => setStatus(url, true, 'yellow');
+  /**
+   * @param {string} url URL to mark as unavailable.
+   * @returns {{url: string, status: boolean, color: string}} Scan result.
+   */
   const setBad = url => setStatus(url, false, 'red', '%s not currently accessible');
 
   /**
    * Scans URLs to determine if they are up or down.
-   *
    * @since 3.0.0
    * @alias lando.scanUrls
    * @param {string[]} urls An array of urls like `https://mysite.lndo.site` or `https://localhost:34223`
-   * @param {Object} [opts] Options to configure the scan.
-   * @param {number} [opts.max=7] The amount of times to retry accessing each URL.
-   * @param {number[]} [opts.waitCodes=[400, 502, 404]] The HTTP codes to prompt a retry.
-   * @param {number} [opts.timeout=15000] The timeout for each request in milliseconds.
-   * @return {Array} An array of objects of the form {url: url, status: true|false}
+   * @param {object} [opts] Options to configure the scan.
+   * @param {number} [opts.max] The amount of times to retry accessing each URL.
+   * @param {number[]} [opts.waitCodes] The HTTP codes to prompt a retry.
+   * @param {number} [opts.timeout] The timeout for each request in milliseconds.
+   * @returns {Array<{url: string, status: boolean, color: string}>} URL scan results.
    * @example
    * // Scan URLs and print results
    * return lando.utils.scanUrls(['http://localhost', 'https://localhost'])

package/node_modules/lando/lib/shell.js

@@ -11,8 +11,10 @@ const parse = require('yargs-parser');
 const Promise = require('./promise');
 const {PassThrough} = require('stream');
 
-/*
- * Helper to parse a command into useful metadataz
+/**
+ * Parses a command into running-process metadata.
+ * @param {object} meta Parsed argv metadata.
+ * @returns {object} Normalized process metadata.
  */
 const parseCmd = meta => _.merge({}, meta, {
   bin: _.trimEnd(path.basename(_.first(meta._), '"')),
@@ -20,15 +22,24 @@ const parseCmd = meta => _.merge({}, meta, {
   args: _.drop(meta._, 2),
 });
 
-/*
- * Helper to parse and add a command to our running process log
+/**
+ * Builds a running-process record.
+ * @param {object} [options] Process options.
+ * @param {string|string[]} [options.cmd] Command argv.
+ * @param {string} [options.id] Process id.
+ * @param {string} [options.mode] Execution mode.
+ * @param {object} [options.process] Child process instance.
+ * @returns {object} Running-process record.
  */
 const addCommand = ({cmd, id, mode = 'exec', process = {}} = {}) => _.merge({},
     parseCmd(parse(cmd)), {id, mode, process},
 );
 
-/*
- * Helper to promisify the exec
+/**
+ * Promisifies shelljs exec.
+ * @param {string[]} cmd Command argv.
+ * @param {object} opts Exec options.
+ * @returns {Promise<{code: number, stdout: string, stderr: string}>} Collected results.
  */
 const exec = (cmd, opts) => new Promise(resolve => {
   _shell.exec(cmd.join(' '), opts, (code, stdout, stderr) => {
@@ -36,8 +47,15 @@ const exec = (cmd, opts) => new Promise(resolve => {
   });
 });
 
-/*
- * Handle the spawn function
+/**
+ * Collects output from a spawned child process.
+ * @param {object} run Child process instance.
+ * @param {{stdio: string|string[]}} options Spawn stdio options.
+ * @param {boolean} [silent] Whether process output should be suppressed.
+ * @param {object} shell Shell instance.
+ * @param {string} [stdout] Collected stdout.
+ * @param {string} [stderr] Collected stderr.
+ * @returns {Promise<{code: number, stdout: string, stderr: string}>} Collected results.
  */
 const spawn = (run, {stdio}, silent = false, shell, stdout = '', stderr = '') => {
   // Run the spawn
@@ -67,19 +85,25 @@ const spawn = (run, {stdio}, silent = false, shell, stdout = '', stderr = '') =>
 
 // We make this module into a function so we can pass in a logger
 module.exports = class Shell {
+  /**
+   * @param {Log} [log] Logger instance.
+   */
   constructor(log = new Log()) {
+    /** @type {Log} */
     this.log = log;
+    /** @type {object[]} */
     this.running = [];
+    /** @type {PassThrough} */
     this.stdout = new PassThrough();
+    /** @type {PassThrough} */
     this.stderr = new PassThrough();
   }
 
   /**
    * Gets running processes.
-   *
    * @since 3.0.0
    * @alias lando.shell.get
-   * @return {Array} An array of the currently running processes
+   * @returns {object[]} An array of the currently running processes.
    */
   get() {
     return this.running;
@@ -93,17 +117,18 @@ module.exports = class Shell {
    *  1. Delegates to either node's native `spawn` or `exec` methods.
    *  2. Promisifies the calling of these function
    *  3. Handles `stdout`, `stdin` and `stderr`
-   *
    * @since 3.0.0
    * @alias lando.shell.sh
    * @see [extra exec options](https://nodejs.org/api/child_process.html#child_process_child_process_exec_command_options_callback)
    * @see [extra spawn options](https://nodejs.org/api/child_process.html#child_process_child_process_spawn_command_args_options)
-   * @param {Array} cmd The command to run as elements in an array.
-   * @param {Object} [opts] Options to help determine how the exec is run.
-   * @param {Boolean} [opts.mode='exec'] The mode to run in
-   * @param {Boolean} [opts.detached=false] Whether we are running in detached mode or not (deprecated)
-   * @param {Boolean} [opts.cwd=process.cwd()] The directory to run the command from
-   * @return {Promise} A promise with collected results if applicable.
+   * @param {string[]} cmd The command to run as elements in an array.
+   * @param {object} [opts] Options to help determine how the exec is run.
+   * @param {string} [opts.mode] The mode to run in.
+   * @param {boolean} [opts.detached] Whether we are running in detached mode or not (deprecated).
+   * @param {string} [opts.cwd] The directory to run the command from.
+   * @param {string|string[]} [opts.cstdio] stdio setting for spawn mode.
+   * @param {boolean} [opts.silent] Whether process output should be suppressed.
+   * @returns {Promise<string>} A promise with collected results if applicable.
    * @example
    * // Run a command in collect mode
    * return lando.shell.sh(['ls', '-lsa', '/'], {mode: 'collect'})
@@ -163,12 +188,11 @@ module.exports = class Shell {
 
   /**
    * Returns the path of a specific command or binary.
-   *
    * @since 3.0.0
    * @function
    * @alias lando.shell.which
-   * @param {String} cmd A command to search for.
-   * @return {String|null} The path to the command or null.
+   * @param {string} cmd A command to search for.
+   * @returns {string|null} The path to the command or null.
    * @example
    * // Determine the location of the 'docker' command
    * const which = lando.shell.which(DOCKER_EXECUTABLE);

package/node_modules/lando/lib/user.js

@@ -6,13 +6,11 @@ const os = require('os');
 
 /**
  * Returns the id of the current user or username.
- *
  * Note that on Windows this value is more or less worthless and `username` has
- * has no effect
- *
+ * no effect.
  * @since 3.0.0
  * @alias lando.user.getUid
- * @return {String} The user ID.
+ * @returns {string} The user ID.
  * @example
  * // Get the id of the user.
  * const userId = lando.user.getUid();
@@ -20,31 +18,27 @@ const os = require('os');
 exports.getUid = () => (process.platform === 'win32') ? '1000' : _.toString(os.userInfo().uid);
 
 /**
-* Returns the gid of the current user or username.
-*
-* Note that on Windows this value is more or less worthless and `username` has
-* has no effect
- *
+ * Returns the gid of the current user.
+ * Note that on Windows this value is more or less worthless and `username` has
+ * no effect.
  * @since 3.0.0
  * @alias lando.user.getGid
- * @return {String} The group ID.
+ * @returns {string} The group ID.
  * @example
- * // Get the id of the user.
+ * // Get the group id of the user.
  * const groupId = lando.user.getGid();
  */
 exports.getGid = () => (process.platform === 'win32') ? '1000' : _.toString(os.userInfo().gid);
 
 /**
-* Returns the username of the current user
-*
-* Note that on Windows this value is more or less worthless and `username` has
-* has no effect
- *
+ * Returns the username of the current user.
+ * Note that on Windows this value is more or less worthless and `username` has
+ * no effect.
  * @since 3.0.0
- * @alias lando.user.getGid
- * @return {String} The group ID.
+ * @alias lando.user.getUsername
+ * @returns {string} The current username.
  * @example
- * // Get the id of the user.
- * const groupId = lando.user.getGid();
+ * // Get the current username.
+ * const username = lando.user.getUsername();
  */
 exports.getUsername = () => os.userInfo().username;