@automattic/vip 4.1.5 → 4.1.6

package/node_modules/lando/lib/events.js

@@ -7,38 +7,40 @@ const Log = require('./logger');
 const Promise = require('./promise');
 
 /**
- * @typedef {Object} Listener
- * @property {string} name The name of the event
+ * @typedef {object} Listener
+ * @property {string} name The event name.
  * @property {number} priority The priority the event should run in.
- * @property {Function} fn The function to call. Should get the args specified in the corresponding `emit` declaration.
+ * @property {function(...unknown): unknown} fn Listener callback.
  */
 
 /**
  * Creates a new Events instance.
- *
  * @property {Log} log The log instance.
  * @property {Listener[]} _listeners The listeners for this event emitter.
  */
 class AsyncEvents extends EventEmitter {
+  /**
+  * @param {Log} [log] Logger instance.
+   */
   constructor(log = new Log()) {
     // Get the event emitter stuffs
     super();
     // Set things
+    /** @type {Log} */
     this.log = log;
+    /** @type {Listener[]} */
     this._listeners = [];
   }
 
   /**
    * Our overridden event on method.
-   *
    * This optionally allows a priority to be specified. Lower priorities run first.
-   *
    * @since 3.0.0
    * @alias lando.events.on
-   * @param {string} name The name of the event
-   * @param {number|Function} [priority] If a number, the priority the event should run in; if a function, the function to call.
-   * @param {Function} [fn] The function to call. Should get the args specified in the corresponding `emit` declaration.
-   * @return {this}
+   * @param {string} name The event name.
+   * @param {number|function(...unknown): unknown} [priority] Priority value or listener callback.
+   * @param {function(...unknown): unknown} [fn] Listener callback.
+   * @returns {this} The event emitter instance.
    * @example
    * // Print out all our apps as they get instantiated and do it before other `post-instantiate-app` events
    * lando.events.on('post-instantiate-app', 1, app => {
@@ -67,14 +69,12 @@ class AsyncEvents extends EventEmitter {
 
   /**
    * Reimplements event emit method.
-   *
    * This makes events blocking and promisified.
-   *
    * @since 3.0.0
    * @alias lando.events.emit
-   * @param {string} name The name of the event
-   * @param {...any} args Options args to pass.
-   * @return {Promise<boolean>} A Promise
+   * @param {string} name The event name.
+   * @param {...unknown} args Additional arguments to pass.
+   * @returns {Promise<boolean>} Promise resolving to whether any listeners ran.
    * @example
    * // Emits a global event with a config arg
    * return lando.events.emit('wolf359', config);

package/node_modules/lando/lib/factory.js

@@ -5,30 +5,49 @@ const _ = require('lodash');
 const fs = require('fs');
 const utils = require('./utils');
 
-/*
- * The lowest level class from which all other services and recipes are built on
- * @TODO: presumably this will get larger over time as we add more options
+/**
+ * A registered builder entry in the factory.
+ * @typedef {object} FactoryRegistryEntry
+ * @property {string} name Builder name.
+ * @property {function((object|null), object): object} builder Builder constructor or factory.
+ */
+
+/**
+ * Base compose service used by generated service definitions.
  */
 const dockerCompose = class ComposeService {
+  /**
+   * @param {string} id Compose group identifier.
+   * @param {object} [info] Metadata about the compose group.
+   * @param {...object} sources Compose source fragments.
+   */
   constructor(id, info = {}, ...sources) {
+    /** @type {string} */
     this.id = id;
+    /** @type {object} */
     this.info = info;
+    /** @type {object[]} */
     this.data = _(sources).map(source => _.merge({}, source, {})).value();
   };
 };
 
-/*
- * The lowest level class from which all other services and recipes are built on
- * @TODO: presumably this will get larger over time as we add more options
+/**
+ * Base recipe wrapper used by generated app recipes.
  */
 const landoRecipe = class LandoRecipe {
+  /**
+   * @param {string} id Recipe identifier.
+   * @param {object} [config] Recipe configuration.
+   */
   constructor(id, config = {}) {
     // Move our config into the userconfroot if we have some
     // NOTE: we need to do this because on macOS and Windows not all host files
     // are shared into the docker vm
 
     if (fs.existsSync(config.confSrc)) utils.moveConfig(config.confSrc, config.confDest);
+    /** @type {string} */
     this.id = id;
+    /** @type {object} */
     this.config = {
       proxy: config.proxy,
       services: config.services,
@@ -37,30 +56,40 @@ const landoRecipe = class LandoRecipe {
   };
 };
 
-/*
- * @TODO
+/**
+ * Creates registry-backed builders for compose services and recipes.
  */
 module.exports = class Factory {
   // @TODO add recipe base class as well?
+  /**
+   * @param {FactoryRegistryEntry[]} [classes] Initial factory registry.
+   */
   constructor(classes = [
     {name: '_compose', builder: dockerCompose},
     {name: '_recipe', builder: landoRecipe},
   ]) {
+    /** @type {FactoryRegistryEntry[]} */
     this.registry = classes;
   };
 
-  /*
-   * Add things
-   * @TODO: Document the common form here
+  /**
+   * Registers a new builder derived from an optional parent builder.
+   * @param {object} entry Builder definition.
+   * @param {string} entry.name Builder name.
+   * @param {function((object|null), object): object} entry.builder Builder factory.
+   * @param {object} [entry.config] Builder configuration.
+   * @param {string|null} [entry.parent] Parent builder name.
+   * @returns {object|undefined} Resolved builder instance.
    */
   add({name, builder, config = {}, parent = null}) {
     this.registry.push({name, builder: builder(this.get(parent), config)});
     return this.get(name);
   };
 
-  /*
-   * Retrieve one or all the builders
-   * @TODO: provide warning when we can't find a builder and list valid registry things
+  /**
+   * Retrieves a specific builder or the full registry.
+   * @param {string} [name] Builder name.
+   * @returns {object|FactoryRegistryEntry[]|undefined} Matching builder or the registry.
    */
   get(name = '') {
     return (!_.isEmpty(name)) ? _.find(this.registry, {name}).builder : this.registry;

package/node_modules/lando/lib/formatters.js

@@ -6,7 +6,9 @@ const os = require('os');
 const util = require('util');
 
 // Const
+/** @type {string[]} */
 const formats = ['default', 'json', 'table'];
+/** @type {object} */
 const formatOpts = {
   format: {
     describe: `Output in given format: ${formats.join(', ')}`,
@@ -24,8 +26,15 @@ const formatOpts = {
   },
 };
 
-/*
- * Format data
+/**
+ * Formats command output for CLI display.
+ * @param {unknown} data Output data.
+ * @param {object} [formatting] Output formatting options.
+ * @param {string} [formatting.path] Object path to extract.
+ * @param {'default'|'json'|'table'} [formatting.format] Output format.
+ * @param {string[]} [formatting.filter] Array filters in `key=value` form.
+ * @param {object} [opts] Table or inspect options.
+ * @returns {string} Formatted output.
  */
 exports.formatData = (data, {path = '', format = 'default', filter = []} = {}, opts = {}) => {
   // Attempt to filter if we can
@@ -62,38 +71,17 @@ exports.formatData = (data, {path = '', format = 'default', filter = []} = {}, o
   }
 };
 
-/*
- * FormatOptios
+/**
+ * Returns CLI formatter options, omitting selected keys.
+ * @param {string[]} [omit] Option keys to omit.
+ * @returns {object} Formatter option config.
  */
 exports.formatOptions = (omit = []) => _.omit(formatOpts, omit);
 
-/*
- * Helper to get interactive options
- */
-exports.getInteractive = (options, argv) => _(options)
-    .map((option, name) => _.merge({}, {name}, {option}))
-    .filter(option => !_.isEmpty(_.get(option, 'option.interactive', {})))
-    .map(option => _.merge({}, {name: option.name, weight: 0}, option.option.interactive))
-    .map(option => {
-      if (_.isNil(argv[option.name]) || argv[option.name] === false) return option;
-      else {
-        return _.merge({}, option, {when: answers => {
-          answers[option.name] = argv[option.name];
-          return false;
-        }});
-      }
-    })
-    .value();
-
-/*
- * Helper to prompt the user if needed
- */
-exports.handleInteractive = (inquiry, argv, command, lando) => lando.Promise.try(() => {
-  return {};
-});
-
-/*
- * Helper to sort options
+/**
+ * Sorts option objects by key name.
+ * @param {object} options Option config keyed by name.
+ * @returns {object} Sorted option config.
  */
 exports.sortOptions = options => _(options)
     .keys()

package/node_modules/lando/lib/lando.js

@@ -16,16 +16,25 @@ const BOOTSTRAP_LEVELS = {
 };
 
 // Default version information
+/** @type {object} */
 const DEFAULT_VERSIONS = {networking: 1};
 
-// Helper to get init config
+/**
+ * Loads init plugin definitions from plugin directories.
+ * @param {string[]} dirs Directories to scan.
+ * @returns {object[]} Init plugin configs.
+ */
 const getInitConfig = dirs => _(dirs)
     .filter(dir => typeof dir === 'string' && fs.existsSync(dir))
     .flatMap(dir => globSync(normalizePathForGlob(path.join(dir, '*', 'init.js'))).sort())
     .map(file => require(file))
     .value();
 
-// Helper to get init source config
+/**
+ * Loads init source definitions from plugin directories.
+ * @param {string[]} dirs Directories to scan.
+ * @returns {object[]} Init source configs.
+ */
 const getInitSourceConfig = dirs => _(dirs)
     .filter(dir => typeof dir === 'string' && fs.existsSync(dir))
     .flatMap(dir => globSync(normalizePathForGlob(path.join(dir, '*.js'))).sort())
@@ -33,8 +42,10 @@ const getInitSourceConfig = dirs => _(dirs)
     .flatMap(source => source.sources)
     .value();
 
-/*
- * Helper to bootstrap plugins
+/**
+ * Bootstraps plugin discovery and merges plugin config into Lando.
+ * @param {Lando} lando Lando instance.
+ * @returns {Promise} Promise for plugin bootstrap.
  */
 const bootstrapConfig = lando => {
   const Plugins = require('./plugins');
@@ -54,8 +65,10 @@ const bootstrapConfig = lando => {
       });
 };
 
-/*
- * Helper to bootstrap tasks
+/**
+ * Bootstraps tasks, init sources, and cached task metadata.
+ * @param {Lando} lando Lando instance.
+ * @returns {Promise} Promise for task bootstrap.
  */
 const bootstrapTasks = lando => {
   // Load in config from init and source plugins
@@ -89,8 +102,10 @@ const bootstrapTasks = lando => {
       });
 };
 
-/*
- * Helper to bootstrap engine
+/**
+ * Bootstraps shell, scan helpers, engine, scripts, and docker version data.
+ * @param {Lando} lando Lando instance.
+ * @returns {Promise} Promise for engine bootstrap.
  */
 const bootstrapEngine = lando => {
   const Shell = require('./shell');
@@ -134,8 +149,10 @@ const bootstrapEngine = lando => {
   return Promise.all([pluginPromise, versionsPromise]);
 };
 
-/*
- * Helper to bootstrap app stuffs
+/**
+ * Bootstraps builders and YAML helpers for app-level operations.
+ * @param {Lando} lando Lando instance.
+ * @returns {void}
  */
 const bootstrapApp = lando => {
   const Factory = require('./factory');
@@ -153,8 +170,11 @@ const bootstrapApp = lando => {
   _.forEach(builders, builder => lando.log.debug('autoloaded builder %s', builder));
 };
 
-/*
- * Helper to route bootstrap things
+/**
+ * Routes bootstrap execution to the requested bootstrap level.
+ * @param {'config'|'tasks'|'engine'|'app'} level Bootstrap level.
+ * @param {Lando} lando Lando instance.
+ * @returns {Promise|boolean|void} Bootstrap result.
  */
 const bootstrapRouter = (level, lando) => {
   switch (level) {
@@ -174,11 +194,8 @@ const bootstrapRouter = (level, lando) => {
  *
  * Check out `./bin/lando.js` in this repository for an example of how we instantiate
  * `lando` for usage in a CLI.
- *
  * @since 3.0.0
  * @name Lando
- * @param {Object} [options] Options to initialize a Lando object with
- * @return {Lando} An initialized Lando instance
  * @example
  * // Get a new lando instance
  * const Lando = require('lando');
@@ -192,20 +209,33 @@ const bootstrapRouter = (level, lando) => {
  * });
  */
 module.exports = class Lando {
+  /**
+   * @param {object} [options] Options to initialize the Lando instance with.
+   */
   constructor(options = {}) {
+    /** @type {object} */
     this.BOOTSTRAP_LEVELS = BOOTSTRAP_LEVELS;
+    /** @type {object} */
     this.config = bootstrap.buildConfig(options);
+    /** @type {typeof import('./promise')} */
     this.Promise = require('./promise');
+    /** @type {object[]} */
     this.tasks = [];
     const AsyncEvents = require('./events');
     const Cli = require('./cli');
     const Log = require('./logger');
     const ErrorHandler = require('./error');
+    /** @type {import('./logger')} */
     this.log = new Log(this.config);
+    /** @type {import('./cache')} */
     this.cache = bootstrap.setupCache(this.log, this.config);
+    /** @type {import('./cli')} */
     this.cli = new Cli();
+    /** @type {import('./error')} */
     this.error = new ErrorHandler(this.log);
+    /** @type {import('./events')} */
     this.events = new AsyncEvents(this.log);
+    /** @type {object} */
     this.user = require('./user');
   };
 
@@ -234,7 +264,6 @@ module.exports = class Lando {
    *
    * Check out `./bin/lando.js` in this repository for an example of bootstraping
    * `lando` for usage in a CLI.
-   *
    * @since 3.0.0
    * @alias lando.bootstrap
    * @fires pre_bootstrap_config
@@ -245,11 +274,11 @@ module.exports = class Lando {
    * @fires post_bootstrap_tasks
    * @fires post_bootstrap_engine
    * @fires post_bootstrap_app
-   * @param {String} [level=app] Level with which to bootstrap Lando
-   * @return {Promise} A Promise
+   * @param {string} [level] Level with which to bootstrap Lando.
+    * @returns {Promise<Lando>} Promise resolving to the bootstrapped Lando instance.
    * @example
    * // Bootstrap lando at default level and then exit
-   * lando.bootstrap().then(() => process.exit(0))l
+    * lando.bootstrap().then(() => process.exit(0))
    */
   bootstrap(level = 'app') {
     // Log that we've begun
@@ -266,11 +295,9 @@ module.exports = class Lando {
 
       /**
        * Event that runs before we bootstrap config.
-       *
        * @since 3.0.0
-       * @alias lando.events:pre-bootstrap-config
        * @event pre_bootstrap_config
-       * @property {Lando} lando The lando object
+      * @property {Lando} lando The lando object.
        * @example
        * lando.events.on('pre-bootstrap-config', lando => {
        *   // My codes
@@ -278,11 +305,9 @@ module.exports = class Lando {
        */
       /**
        * Event that runs before we bootstrap tasks.
-       *
        * @since 3.0.0
-       * @alias lando.events:pre-bootstrap-tasks
        * @event pre_bootstrap_tasks
-       * @property {Lando} lando The lando object
+      * @property {Lando} lando The lando object.
        * @example
        * lando.events.on('pre-bootstrap-tasks', lando => {
        *   // My codes
@@ -290,11 +315,9 @@ module.exports = class Lando {
        */
       /**
        * Event that runs before we bootstrap the engine.
-       *
        * @since 3.0.0
-       * @alias lando.events:pre-bootstrap-engine
        * @event pre_bootstrap_engine
-       * @property {Lando} lando The lando object
+      * @property {Lando} lando The lando object.
        * @example
        * lando.events.on('pre-bootstrap-engine', lando => {
        *   // My codes
@@ -302,11 +325,9 @@ module.exports = class Lando {
        */
       /**
        * Event that runs before we bootstrap the app.
-       *
        * @since 3.0.0
-       * @alias lando.events:pre-bootstrap-app
        * @event pre_bootstrap_app
-       * @property {Lando} lando The lando object
+      * @property {Lando} lando The lando object.
        * @example
        * lando.events.on('pre-bootstrap-app', lando => {
        *   // My codes
@@ -319,11 +340,9 @@ module.exports = class Lando {
 
       /**
        * Event that runs after we bootstrap config
-       *
        * @since 3.0.0
-       * @alias lando.events:post-bootstrap-config
        * @event post_bootstrap_config
-       * @property {Lando} lando The Lando object
+      * @property {Lando} lando The Lando object.
        * @example
        * lando.events.on('post-bootstrap-config', lando => {
        *   // My codes
@@ -331,11 +350,9 @@ module.exports = class Lando {
        */
       /**
        * Event that runs after we bootstrap tasks
-       *
        * @since 3.0.0
-       * @alias lando.events:post-bootstrap-tasks
        * @event post_bootstrap_tasks
-       * @property {Lando} lando The Lando object
+      * @property {Lando} lando The Lando object.
        * @example
        * lando.events.on('post-bootstrap-tasks', lando => {
        *   // My codes
@@ -343,11 +360,9 @@ module.exports = class Lando {
        */
       /**
        * Event that runs after we bootstrap the engine
-       *
        * @since 3.0.0
-       * @alias lando.events:post-bootstrap-engine
        * @event post_bootstrap_engine
-       * @property {Lando} lando The Lando object
+      * @property {Lando} lando The Lando object.
        * @example
        * lando.events.on('post-bootstrap-engine', lando => {
        *   // My codes
@@ -355,11 +370,9 @@ module.exports = class Lando {
        */
       /**
        * Event that runs after we bootstrap the app
-       *
        * @since 3.0.0
-       * @alias lando.events:post-bootstrap-app
        * @event post_bootstrap_app
-       * @property {Lando} lando The Lando object
+      * @property {Lando} lando The Lando object.
        * @example
        * lando.events.on('post-bootstrap-app', lando => {
        *   // My codes
@@ -376,14 +389,12 @@ module.exports = class Lando {
 
   /**
    * Gets a fully instantiated App instance.
-   *
    * Lando will also scan parent directories if no app is found in `startFrom`
-   *
    * @since 3.0.0
    * @alias lando.getApp
-   * @param {String} [startFrom=process.cwd()] The directory to start looking for an app
-   * @param {Boolean} [warn=true] Show a warning if we can't find an app
-   * @return {App} Returns an instantiated App instandce.
+   * @param {string} [startFrom] The directory to start looking for an app.
+   * @param {boolean} [warn] Show a warning if we can't find an app.
+  * @returns {import('./app')|undefined} Instantiated App instance when found.
    * @example
    * const app = lando.getApp('/path/to/my/app')
    */

package/node_modules/lando/lib/logger.js

@@ -88,60 +88,52 @@ const consoleFormat = (logLevelConsole, defaultLogName) =>
 
 /**
  * Logs a debug message.
- *
  * Debug messages are intended to communicate lifecycle milestones and events that are relevant to developers
- *
  * @since 3.0.0
  * @function
  * @name lando.log.debug
  * @alias lando.log.debug
- * @param {String} msg A string that will be passed into nodes core `utils.format()`
- * @param {...Any} [values] Values to be passed `utils.format()`
+ * @param {string} msg A string passed into node core `util.format()`.
+ * @param {...unknown} [values] Values passed to `util.format()`.
  * @example
  * // Log a debug message
  * lando.log.debug('All details about docker inspect %j', massiveObject);
  */
 /**
  * Logs an error message.
- *
  * Errors are intended to communicate there is a serious problem with the application
- *
  * @since 3.0.0
  * @function
  * @name lando.log.error
  * @alias lando.log.error
- * @param {String} msg A string that will be passed into nodes core `utils.format()`
- * @param {...Any} [values] Values to be passed `utils.format()`
+ * @param {string} msg A string passed into node core `util.format()`.
+ * @param {...unknown} [values] Values passed to `util.format()`.
  * @example
  * // Log an error message
  * lando.log.error('This is an err with details %s', err);
  */
 /**
  * Logs an info message.
- *
  * Info messages are intended to communicate lifecycle milestones and events that are relevant to users
- *
  * @since 3.0.0
  * @function
  * @name lando.log.info
  * @alias lando.log.info
- * @param {String} msg A string that will be passed into nodes core `utils.format()`
- * @param {...Any} [values] Values to be passed `utils.format()`
+ * @param {string} msg A string passed into node core `util.format()`.
+ * @param {...unknown} [values] Values passed to `util.format()`.
  * @example
  * // Log an info message
  * lando.log.info('It is happening!');
  */
 /**
  * Logs a silly message.
- *
  * Silly messages are meant for hardcore debugging
- *
  * @since 3.0.0
  * @function
  * @name lando.log.silly
  * @alias lando.log.silly
- * @param {String} msg A string that will be passed into nodes core `utils.format()`
- * @param {...Any} [values] Values to be passed `utils.format()`
+ * @param {string} msg A string passed into node core `util.format()`.
+ * @param {...unknown} [values] Values passed to `util.format()`.
  * @example
  * // Log a silly message
  * lando.log.silly('All details about all the things', unreasonablySizedObject);
@@ -151,31 +143,27 @@ const consoleFormat = (logLevelConsole, defaultLogName) =>
  */
 /**
  * Logs a verbose message.
- *
  * Verbose messages are intended to communicate extra information to the user and basics to a developer. They sit somewhere
  * in between info and debug
- *
  * @since 3.0.0
  * @function
  * @name lando.log.verbose
  * @alias lando.log.verbose
- * @param {String} msg A string that will be passed into nodes core `utils.format()`
- * @param {...Any} [values] Values to be passed `utils.format()`
+ * @param {string} msg A string passed into node core `util.format()`.
+ * @param {...unknown} [values] Values passed to `util.format()`.
  * @example
  * // Log a verbose message
  * lando.log.verbose('Config file %j loaded from %d', config, directory);
  */
 /**
  * Logs a warning message.
- *
  * Warnings are intended to communicate you _might_ have a problem.
- *
  * @since 3.0.0
  * @function
  * @name lando.log.warn
  * @alias lando.log.warn
- * @param {String} msg A string that will be passed into nodes core `utils.format()`
- * @param {...Any} [values] Values to be passed `utils.format()`
+ * @param {string} msg A string passed into node core `util.format()`.
+ * @param {...unknown} [values] Values passed to `util.format()`.
  * @example
  * // Log a warning message
  * lando.log.warning('Something is up with app %s in directory %s', appName, dir);