@suffolklitlab/alkiln 5.13.2 → 5.13.3-feat-random

package/lib/utils/files.js

@@ -21,20 +21,27 @@ files.readable_date = function() {
   return fancy_str;
 };  // Ends files.readable_date()
 
-files.make_artifacts_folder = function (folder_name) {
-  /** Makes a folder in the root of the project, either with the given name
-  *   or with a default name.
-  * 
-  * Works for local development as well, unlike action.yml or the workflow file.
-  */
-  if (folder_name) {
-    folder_name = safe_filename( folder_name );
+files.make_artifacts_folder = function (path) {
+  /** Makes a folder in the root of the project if it doesn't
+   *  already exist, either with the given name or with a default name.
+   *
+   * Works for local development as well, without action.yml or workflow files.
+   * */
+  if (path) {
+    let name_parts = path.split(`/`);
+    let safe_parts = [];
+    for ( let part of name_parts ) {
+      safe_parts.push(safe_filename( part ));
+    }
+    path = safe_parts.join(`/`);
   } else {
-    folder_name = `alkiln-${ files.readable_date() }`
+    path = `alkiln-${ files.readable_date() }`
   }
 
-  fs.mkdirSync( folder_name );
-  return folder_name;
+  // `recursive` avoids errors if folder already exists
+  // https://nodejs.org/docs/latest-v18.x/api/fs.html#fspromisesmkdirpath-options
+  fs.mkdirSync( path, { recursive: true });
+  return path;
 };  // Ends files.make_artifacts_folder()
 
 module.exports = files;

package/lib/utils/get_error_stacks.js

@@ -0,0 +1,16 @@
+module.exports = function get_error_stacks({ errors }) {
+  /** Given a list of Error instances, return a list of their stacks
+   * 
+   * Discuss: Move this into `Log`. Potentially print each stack with the
+   *    same icon as the message. `{to_stack: [Errors]}.
+   * 
+   * @param {object} obj - Named arguments
+   * @param {[Error]} obj.errors - A list of Error instances
+   * 
+   * @returns {[Error.stack]} - A list of Error instances' `.stack` properties
+   * */
+  let stacks = errors.map(function( error ) {
+    return error.stack;
+  });
+  return stacks;
+};

package/lib/utils/reports.js

@@ -57,7 +57,7 @@ reports.addToReport = function( scope, { type, code, value }) {
   // thrown errors if needed.
 
   // Debugging logs
-  let debug_line = getDebugLine({ type, code, value });
+  let debug_line = getDebugLine({ type, code, value, indent: global_indent });
   if ( session_vars.get_debug() ) {
     console.log( `Report: ${ debug_line }` );
   }
@@ -66,24 +66,43 @@ reports.addToReport = function( scope, { type, code, value }) {
   const MISC_ARTIFACTS_DIR = `_alkiln-misc_artifacts`;
   if ( !scope.paths ) {
     // Can this be usefully abstracted?
-    scope.paths = { debug_log: `${ MISC_ARTIFACTS_DIR }/unit_tests_logs-${ files.readable_date() }.txt` };
+    let date = files.readable_date();
+    scope.paths = {
+      debug_log: `${ MISC_ARTIFACTS_DIR }/unit_tests_debug_log-${ date }.txt`,
+      report_log: `${ MISC_ARTIFACTS_DIR }/unit_tests_report_log-${ date }.txt`,
+    };
   }
 
   try {
     fs.appendFileSync( scope.paths.debug_log, `\nReport:\n${debug_line}` );
-  } catch ( err ) {
+    fs.appendFileSync( scope.paths.report_log, `\nReport:\n${debug_line}` );
+  } catch ( file_error ) {
     fs.mkdirSync( MISC_ARTIFACTS_DIR );
     fs.appendFileSync( scope.paths.debug_log, `\nReport:\n${debug_line}` );
+    fs.appendFileSync( scope.paths.report_log, `\nReport:\n${debug_line}` );
     // An error in here should throw (for now)
   }
 
   // Report stuff
   let scenario = reports.makeSureScenarioExists( scope );
-  scenario.lines.push({ type, code, value });
+  scenario.lines.push({ type, code, value, indent: global_indent });
 
-  return getLineText({ type, code, value });
+  return getLineText({ type, code, value, indent: global_indent });
 };  // Ends reports.addToReport()
 
+
+let indent_num = 0;
+let global_indent = ``;
+reports.indent = function() {
+  indent_num += 2;
+  global_indent = ` `.repeat( indent_num );
+}
+reports.outdent = function() {
+  indent_num = Math.max( 0, indent_num - 2 );
+  global_indent = ` `.repeat( indent_num );
+}
+
+
 reports.create = function( scope ) {
   reports.makeSureReportExists( scope );
 }
@@ -115,25 +134,66 @@ reports.saveFinalScenarioData = function( scope, { status=`in progress` }) {
   this.setReportScenarioStatus( scope, { status });
   let scenario = scope.report.get( scope.scenario_id );
   let report = this.getPrintableScenario( scenario );
-  if ( scenario.status === `FAILED` ) { this.failures.push( report ); }
-  else if ( scenario.status === `PASSED` ) { this.successes.push( report ); }
-  // else if ( scenario.status === `WARNING` ) { passed_reports += report; this.warnings.push( report ); }
-  // else if ( scenario.status === `UNDEFINED` ) { passed_reports += report; this.undefineds.push( report ); }
-  else { this.others.push( report ); }
-
-  // Save to failures.txt (worry about optimization later)
-  if ( this.failures.length > 1 || this.others.length > 1 ) {
-    fs.writeFileSync(
-      scope.paths.failures,
-      this.title + this.getPrintableUnexpected( scope )
-    );
+  if ( scenario.status === `PASSED` ) {
+    this.successes.push( report );
+  } else {
+    this._save_unexpected( scope, { status: scenario.status, report });
   }
+  // if ( scenario.status === `FAILED` ) {
+  //   this.failures.push( report );
+  // }
+  // else if ( scenario.status === `PASSED` ) { this.successes.push( report ); }
+  // // else if ( scenario.status === `WARNING` ) { passed_reports += report; this.warnings.push( report ); }
+  // // else if ( scenario.status === `UNDEFINED` ) { passed_reports += report; this.undefineds.push( report ); }
+  // else { this.others.push( report ); }
+
+  // // Save to unexpected results files (worry about optimization later)
+  // if ( this.failures.length > 1 || this.others.length > 1 ) {
+  //   let unexpected_results = this.title + this.getPrintableUnexpected( scope );
+  //   fs.writeFileSync( scope.paths.report_of_unexpected, unexpected_results );
+  //   fs.appendFileSync( scope.paths.debug_of_unexpected, unexpected_results );
+  // }
+
   // Save to reports.txt (worry about optimization later)
   fs.writeFileSync( scope.paths.report, this.getPrintableReport( scope ) );
 
   return scenario;
 };  // Ends reports.saveFinalScenarioData()
 
+reports._save_unexpected = function(scope, { status, report }) {
+  /** Store the unexpected report and write to the unexpected report file.
+   *
+   * @param {Object} scope - State and methods of the current tests
+   * @param {Object} data
+   * @param {Object} data.status - Status of the current scenario
+   * @param {string} data.report - Report for the current scenario
+   * */
+  if ( status === `FAILED` ) {
+    this.failures.push( report );
+  // } else if ( status === `WARNING` ) { passed_reports += report; this.warnings.push( report );
+  // } else if ( status === `UNDEFINED` ) { passed_reports += report; this.undefineds.push( report ); }
+  } else {
+    this.others.push( report );
+  }
+
+  // If it's our first unexpected result, add the title to the top of the page
+  let already_unexpected = ``;
+  try { already_unexpected = fs.readFileSync( scope.paths.report_of_unexpected ); }
+  catch ( ignore_non_critical_error ) {}
+  if ( already_unexpected === `` ) {
+    try { fs.appendFileSync( scope.paths.report_of_unexpected, this.title ); }
+    catch ( ignore_non_critical_error ) {}
+  }
+
+  try { fs.appendFileSync( scope.paths.report_of_unexpected, report ); }
+  catch ( ignore_non_critical_error ) {}
+
+  return this;
+}
+
+reports.progress = function ({ logs=[] }) {
+  // TODO: save stdout-style to report_log, object, and getting printable scenario
+};
 
 reports.setReportScenarioStatus = function( scope, { status=`PASSED` }) {
   /** Add final status of scenario to scenario report object - passed, failed, etc. */
@@ -197,38 +257,45 @@ reports.getPrintableScenario = function( scenario ) {
   /** Return a string generated from scenario list of report items. */
   let report = ``;
   for ( let line of scenario.lines ) {
-    let { type, code, value } = line;
-    report += `${ getLineText({ type, code, value }) }\n`;
+    let { type, code, value, indent } = line;
+    report += `${ getLineText({ type, code, value, indent }) }\n`;
   }
   return report;
 };  // Ends reports.getPrintableScenario()
 
-let getLineText = function ({ type=`no type`, code=`ALK0000`, value=`` }) {
-  let start = ``;
+let getLineText = function ({ type=`no type`, code=`ALK00rl`, value=``, indent=`` }) {
+
+  value = `${ value.replace( /\n/g, "\n" + indent ) }`;
+
+  if ( type === `as_is` ) { return `${ indent }${ value }`; }
+
+  let start = indent;
+  if ( type.includes(`outcome`) ) { start = `\n`; }
+
   if ( type.includes(`page_id`) ) { start += `screen id: `; }
-  else if ( type.includes(`outcome`) ) { start += `\n`; }  // extra new line
   else if ( type.includes(`warning`) ) { start += `🔎 ${ code } WARNING: `; }
   else if ( type.includes(`error`) ) { start += `\n🤕 ${ code } ERROR: `; }  // extra new line
-  return `${ start }${ value }`;
+  let result = `${ start }${ value }`;
+  return result;
 };  // Ends getLine()
 
-let getDebugLine = function ({ type=``, code=`ALK0000`, value=`` }) {
+let getDebugLine = function ({ type=``, code=`ALK00rd`, value=``, indent=`` }) {
   /** In debug log lines, include all the information possible. */
 
   // `plain` is usually used for visual clarity and shouldn't have
   // codes and such associated with it. Return right away.
-  if ( type.includes(`plain`) ) { return value; }
+  if ( type.includes(`plain`) ) { return `${ indent }${ value }`; }
 
-  let start = ``;
+  let start = indent;
 
   // Get all the relevant emoji
-  if ( type.includes(`debug`) ) { start += `🐞`; }
+  if ( type.includes(`debug`) ) { start += `🐛`; }
   if ( type.includes(`info`) ) { start += `💡`; }
   if ( type.includes(`success`) ) { start += `🌈`; }
   if ( type.includes(`warning`) ) { start += `🔎`; }
   if ( type.includes(`error`) ) { start += `🤕`; }
   // Default
-  if ( start === `` ) { start += `?`; }
+  if ( start === indent ) { start += `?`; }
 
   start += ` ${ code }`;
 

package/lib/utils/session_vars.js

@@ -3,19 +3,29 @@ const fg = require('fast-glob');
 const path = require('path'); 
 require('dotenv').config();
 
+/** WARNING: Avoid importing other project files into here. Every other
+ *  file should be able to reference this one without worrying
+ *  about circular references.
+ * */
+
+/** This file provides user info variable getters and setters.
+ *  E.g. server address. It often uses `process.env` vars or
+ *  vars that have been built from `process.env` vars. It is
+ *  meant to avoid duplication, make testing easier, and leave
+ *  room for future manipulation.
+ *
+ * No other file should need to use `process.env`.
+ *
+ * We use `.get_foo()` functions partly because it makes the code
+ * easier to test.
+ * */
+
 /**
- * This code assumes that this module is run as part of a GitHub Action.  If the
- * customer is running it as a CLI tool, then they won't get useful messages yet.
- */
-
-/* This file provides user info variables. E.g. server address. They're either
-*    `process.env` vars or vars that have been built from `process.env` vars.
-*    It is meant to avoid duplication, make testing easier, and leave room for
-*    future manipulation. No other file should need to use `process.env`.
-*
-* We have a bunch of `.get_foo()` functions partly because it makes the code
-*    much easier to test.
-*/
+ * Discuss: consider returning most logs (info, error, warning) so that the
+ *    calling functions can use a `Log` to log them properly instead of logging
+ *    to the console. Alternatively, move everything in here that `Log` uses
+ *    into its own file so that `session_vars` can have its own `Log` instance.
+ * */
 
 const session_vars = {};
 
@@ -59,6 +69,18 @@ session_vars.get_setup_timeout_ms = function () {
   return timeout;
 };
 
+session_vars.get_max_tests_per_generator_scenario = function() {
+  /** Returns the maximum number of tests to generate for any one generator
+   *    Scenario.
+   * 
+   * Assumes an average of 30 secs per test with a max of 20 min. for all tests
+   *    for that one generator Scenario.
+   * 
+   * @returns {int} - Max number of tests for one generator Scenario
+   * */
+  return process.env.MAX_RANDOM_TESTS_PER_SCENARIO || 40;
+}
+
 session_vars.get_da_server_url = function () {
   try {
     let url = process.env.SERVER_URL || process.env.BASE_URL;
@@ -136,7 +158,7 @@ session_vars.save_project_name = function ( project_name ) {
   let file = fs.writeFileSync( runtime_config_path, JSON.stringify( json, null, 2 ) );
 
   if ( session_vars.get_debug() ) {
-    console.log( `🐞 ALK0036 DEBUG: Stored name of Project "${ project_name }" locally.` );
+    console.debug( `🐛 ALK0036 DEBUG: Stored name of Project "${ project_name }" locally.` );
   }
   return file;
 };  // Ends save_project_name()
@@ -148,7 +170,7 @@ session_vars.get_project_name = function () {
   }
   let json = JSON.parse( fs.readFileSync( runtime_config_path ));
   let project_name = json[ project_name_key ] || null;
-  if ( session_vars.get_debug() ) { console.log( `🐞 ALK0037 DEBUG: Project name from file is "${ project_name }".` ); }
+  if ( session_vars.get_debug() ) { console.debug( `🐛 ALK0037 DEBUG: Project name from file is "${ project_name }".` ); }
   return project_name;
 };  // Ends get_project_name()
 
@@ -172,29 +194,41 @@ session_vars.delete_project_name = function () {
 // const file_storing_artifact_path = `_alkiln_test_artifacts_dir_name.json`;
 const artifacts_path_key = `artifacts_path`;
 session_vars.save_artifacts_path_name = function ( path_name ) {
-  /* Save a key with the name of the current artifacts folder in case it doesn't exist. */
+  /** Save a key with the name of the current artifacts folder
+   *    in case it doesn't exist.
+   * */
   return session_vars.save_runtime_config_var({ key: artifacts_path_key, value: path_name });
 };  // Ends save_artifacts_path_name()
 session_vars.get_artifacts_path_name = function () {
-  /* Get the name of the current artifacts path. */
+  /** Get the name of the current artifacts path. */
   return session_vars.get_runtime_config_var( artifacts_path_key );
 };  // Ends get_artifacts_path_name()
+session_vars.delete_artifacts_path_name = function () {
+  /** Delete the runtime config value of the artifacts path. */
+  return session_vars.delete_runtime_config_var({ key: artifacts_path_key });
+};
 
 
+/** We use `da_install_method` for temp server vs. author's account (Playground)
+ *  on author's server. For example, for deciding how to get the url of a
+ *  server. See docs on 4 environments. TODO: Change `_method` to `_location`?
+ * */
 const install_method_key = `da_install_method`;
 session_vars.save_install_method = function ( install_method ) {
-  /* Save a key with the name of the current artifacts folder in case it doesn't exist. */
+  /** Save a key with the name of the current artifacts folder in case it
+   *  doesn't exist. */
   return session_vars.save_runtime_config_var({ key: install_method_key, value: install_method });
 };  // Ends save_install_method()
 session_vars.get_install_method = function () {
-  /* Get the name of the current install method. */
+  /** Get the name of the current install method. */
   return session_vars.get_runtime_config_var( install_method_key );
 };  // Ends get_install_method()
 
 
 const repo_folder_key = `da_repo_folder_name`;
 session_vars.save_repo_folder_name = function (repo_folder_name) {
-  /** Save a key with the name of the main package folder in the repository. */
+  /** Save a key with the name of the main package folder in the repository. For
+   *  example, EvictionDefense in the docassemble-EvictionDefense folder. */
   return session_vars.save_runtime_config_var({ key: repo_folder_key, value: repo_folder_name });
 };  // Ends session_vars.save_repo_folder_name()
 session_vars.get_repo_folder_name = function () {
@@ -208,10 +242,11 @@ session_vars.save_runtime_config_var = function ({ key, value }) {
   *   the json object there. The functions calling this are keeping
   *   track of the key, so they're useful to keep around.
   * 
-  * @param key {str} Key to use to store `value` in runtime config file
-  * @param value {any} Value to store in runtime config file
+  * @param {object} obj - Named arguments
+  * @param {str} obj.key - Key to use to store `value` in runtime config file
+  * @param {any} obj.value - Value to store in runtime config object
   * 
-  * @returns file {binary?} Runtime config file
+  * @returns {binary?} file Runtime config file
   */
 
   // Ensure runtime config file exists
@@ -226,82 +261,76 @@ session_vars.save_runtime_config_var = function ({ key, value }) {
   let file = fs.writeFileSync( runtime_config_path, JSON.stringify( json, null, 2 ) );
 
   if ( session_vars.get_debug() ) {
-    console.log( `🐞 ALK0040 DEBUG: Stored runtime config var "${key}" locally as "${value}".` );
+    console.debug( `🐛 ALK0040 DEBUG: Stored runtime config var "${key}" locally as "${value}".` );
   }
   return file;
 };  // Ends session_vars.save_runtime_config_var()
 
 session_vars.get_runtime_config_var = function ( key ) {
   /** Get the value of the given key from the runtime config file.
-  * 
-  * @param key {str} Key in runtime config file that contains the desired value
-  * @returns value || null {any} Value of key in runtime config file. If it
-  *    doesn't exist, returns null.
-  */
+   * 
+   * @param {str} key - Key in runtime config file that contains the desired val
+   * 
+   * @returns {any} - Value of given key in runtime config file or null
+   */
   try {
     let json = JSON.parse( fs.readFileSync( runtime_config_path ));
     let value = json[ key ];
     if ( session_vars.get_debug() ) {
-      console.log( `🐞 ALK0041 DEBUG: Runtime config var "${key}" is "${value}".` );
+      console.debug( `🐛 ALK0041 DEBUG: Runtime config var "${ key }" is "${ value }".` );
     }
-
     return value;
-  } catch ( error ) {
+  } catch ( get_var_error ) {
+
+    console.debug(`🖊️ ALK0271 NOTE: Skipped getting runtime config var "${ key }".`, get_var_error.stack );
     return null;
+
   }
 };  // Ends session_vars.get_runtime_config_var()
 
+session_vars.delete_runtime_config_var = function ({ key }) {
+  /** Delete the runtime config var of the given `key`
+   * 
+   * @param {object} obj - Named arguments
+   * @param {str} obj.key - Key in runtime config file object to delete
+   * 
+   * @returns {null}
+   * */
+  try {
+    if ( !fs.existsSync( runtime_config_path )) { return null; }
+    
+    let json = JSON.parse( fs.readFileSync( runtime_config_path ));
+    delete json[ key ];
+    fs.writeFileSync( runtime_config_path, JSON.stringify( json, null, 2 ));
+    return null;
 
-session_vars.set_sources_paths = function ( paths ) {
-  /** Returns whether at least one of the given path exists. Store
-  *   a list of the existing paths. Warn of any missing paths. Can be
-  *   used for getting, e.g .feature files, files to upload, etc.
-  * 
-  * Our code should ensure this gets run before cucumber tests get triggered.
-  * 
-  * @param paths { [str] } List of paths to the 'sources' folder.
-  * 
-  * @returns bool
-  */
+  } catch ( delete_var_error ) {
 
-  // Check every path, tracking which exist and which are missing
-  let existing_paths = [];
-  let missing_paths = [];
-  for ( let path of paths ) {
-    let dirs = fg.sync(
-      [ path ],
-      { onlyFiles: false, suppressErrors: true }
-    );
-
-    if ( dirs.length > 0 ) {
-      existing_paths.push( ...dirs );
-    } else {
-      missing_paths.push( path );
-    }
-  }
+    console.debug( `🖊️ ALK0272 NOTE: Skipped deleting runtime config var "${ key }".`, delete_var_error.stack );
+    return null
 
-  // If no paths were valid
-  if ( existing_paths.length <= 0 ) {
-    session_vars._sources_paths = null;
-    return false;
   }
+};  // Ends session_vars.delete_runtime_config_var()
 
-  console.info(
-    `🌈 ALK0042 SUCCESS: Did find "sources" file(s) at "${ existing_paths.join('", "') }".`
-  )
 
-  // Otherwise, store valid paths
-  session_vars._sources_paths = existing_paths;
-  return true;
+session_vars.set_sources_paths = function ( paths ) {
+  /** Set the globally accessible value of the paths to the sources folder.
+   *    Saves and returns the argument it was given.
+   * 
+   * @param paths {[string]} List of paths to the 'sources' folder.
+   * 
+   * @returns {null | [string]}
+   * */
+  session_vars._sources_paths = paths;
+  return paths || null;
 };  // End session_vars.set_sources_paths()
 
 session_vars.get_sources_paths = function () {
-  /** Get the "sources" folder path. Should never be undefined during
-  *   a run of the test. run_cucumber.js should make sure it has
-  *   a default value.
-  * 
-  * @returns str || null */
-  return session_vars._sources_paths;
+  /** Get the previously stored "sources" folder paths.
+   * 
+   * @returns {null | [string]}
+   * */
+  return session_vars._sources_paths || null;
 };
 
 

package/lib/utils/set_sources_paths.js

@@ -0,0 +1,98 @@
+const fast_glob = require(`fast-glob`);
+
+const session_vars = require(`./session_vars`);
+
+
+module.exports = function set_sources_paths({ log }) {
+  /** Set the globally accessible value of the paths to the sources folder,
+   *    where authors store tests and other relevant test files. Can throw an
+   *    error.
+   * 
+   * @param {object} obj - Named arguments
+   * @param {Log} obj.log - Logs and saves useful info for later debugging.
+   * 
+   * @returns {[string]} - All paths found for package sources folders.
+   * */
+  session_vars.validateEnvironment();
+
+  let maybe_paths = get_potential_paths();
+
+  let sources_paths = get_sources_paths({ maybe_paths });
+  if ( sources_paths === 0 ) {
+    // If we don't throw, it'll be more confusing when no tests run
+    log.throw({ code: `ALK0050`, context: `sources`,
+      error: new ReferenceError(
+        `ALKiln can't find your "sources" folder(s) which should contain tests and their related files.`
+      ),
+    });
+  }
+
+  log.info({ code: `ALK0042`, context: `sources` },
+    `Did find "sources" file(s) at "${ sources_paths.join('", "') }".`
+  );
+  session_vars.set_sources_paths( sources_paths );
+  
+  return sources_paths;
+}
+
+
+function get_potential_paths() {
+  /** Use command line args and session vars to return a list of strings of
+   *    possible sources files paths.
+   * 
+   * @returns {[string]} - Potential sources paths.
+   * */
+  // `project` is the name in the server docassemble "Project" page
+  let project = session_vars.get_user_project_name();
+  let id = session_vars.get_user_id();
+
+  // process.argv is a list of strings of commands and args.
+  // Internal note: If using `npm run cucumber`, use `--` before
+  //    `--sources=./foo`
+  let cli_args = require(`minimist`)( process.argv.slice(2), {
+    default: {
+      sources: [
+        `./docassemble/*/data/sources`,  // In GitHub folder
+        `/usr/share/docassemble/files/playgroundsources/${id}/${project}/*.feature`, // From playground without S3
+        `/tmp/playgroundsources/${id}/${project}/*.feature` // From playground with S3
+      ],
+    }
+  });
+
+  // Make sure `sources` is always a list
+  let potential_paths_list = cli_args.sources;
+  if ( !Array.isArray( cli_args.sources )) {
+    potential_paths_list = [ cli_args.sources ];
+  }
+
+  return potential_paths_list;
+}
+
+
+function get_sources_paths({ maybe_paths }) {
+  /** Of the given possible paths, return the paths that actually exist. Maybe
+   *    none.
+   * 
+   * @param {object} obj - Named arguments
+   * @param {[string]} obj.maybe_paths - All possible paths
+   * 
+   * @returns {[string]} - List of all existing paths
+   * */
+  // Check every path, tracking which exist and which are missing
+  let existing_paths = [];
+  let missing_paths = [];
+  for ( let path of maybe_paths ) {
+    let dirs = fast_glob.sync(
+      [ path ],
+      { onlyFiles: false, suppressErrors: true }
+    );
+
+    if ( dirs.length > 0 ) {
+      existing_paths.push( ...dirs );
+    } else {
+      missing_paths.push( path );
+    }
+  }
+
+  return existing_paths;
+}

package/lib/utils/time.js

@@ -24,3 +24,47 @@ time.waitForTimeout = function( milliseconds ) {
     setTimeout(resolve, milliseconds);
   });
 };
+time.sleep = time.waitForTimeout;
+time.wait = time.waitForTimeout;
+
+time.filename_date = function() {
+  /** Return the current timestamp in a human-readable
+  *   filename-safe format to match the workflow artifact
+  *   date format.
+  *   See https://stackoverflow.com/a/48729396/14144258 and https://stackoverflow.com/a/6040556/14144258
+  */
+  // let date = new Date();  // now
+  // let day = ("0" + date.getUTCDate()).slice(-2);
+  // let month = ("0" + (date.getUTCMonth() + 1)).slice(-2);
+  // let year = date.getUTCFullYear();
+  // let hours = ("0" + date.getUTCHours()).slice(-2);
+  // let mins = ("0" + date.getUTCMinutes()).slice(-2);
+  // let secs = ("0" + date.getUTCSeconds()).slice(-2);
+
+  let dt = time.get_time_parts();
+  let safe_date = `${ dt.y }-${ dt.mon }-${ dt.d } at ${ dt.h }h${ dt.min }m${ dt.s }sUTC`;
+  return safe_date;
+};  // Ends time.filename_date()
+
+time.log_date = function () {
+  /** Return the current timestamp in a human-readable
+  *   more compact log format.
+  * See https://stackoverflow.com/a/48729396/14144258 and https://stackoverflow.com/a/6040556/14144258
+  */
+  let dt = time.get_time_parts();
+  let short_date = `${ dt.y }-${ dt.mon }-${ dt.d } ${ dt.h }:${ dt.min }:${ dt.s }UTC`;
+  return short_date;
+};  // Ends time.log_date()
+
+time.get_time_parts = function () {
+  /** Get all the parts of the date as numbers. */
+  let date = new Date();  // now
+  return ({
+    y: date.getUTCFullYear(),
+    mon: ("0" + (date.getUTCMonth() + 1)).slice(-2),
+    d: ("0" + date.getUTCDate()).slice(-2),
+    h: ("0" + date.getUTCHours()).slice(-2),
+    min: ("0" + date.getUTCMinutes()).slice(-2),
+    s: ("0" + date.getUTCSeconds()).slice(-2),
+  });
+}