alias lookupFiles, loadRc, loadPkgRc and loadOptions to lib/cli module; fixes #4398

lib/cli/cli.js

@@ -3,19 +3,24 @@
 'use strict';
 
 /**
- * This is where we finally parse and handle arguments passed to the `mocha` executable.
- * Option parsing is handled by {@link https://npm.im/yargs yargs}.
- * If executed via `node`, this module will run {@linkcode module:lib/cli/cli.main main()}.
- *
- * @private
- * @module
+ * Contains CLI entry point and public API for programmatic usage in Node.js.
+ * - Option parsing is handled by {@link https://npm.im/yargs yargs}.
+ * - If executed via `node`, this module will run {@linkcode module:lib/cli.main main()}.
+ * @public
+ * @module lib/cli
  */
 
 const debug = require('debug')('mocha:cli:cli');
 const symbols = require('log-symbols');
 const yargs = require('yargs/yargs');
 const path = require('path');
-const {loadOptions, YARGS_PARSER_CONFIG} = require('./options');
+const {
+  loadRc,
+  loadPkgRc,
+  loadOptions,
+  YARGS_PARSER_CONFIG
+} = require('./options');
+const lookupFiles = require('./lookup-files');
 const commands = require('./commands');
 const ansi = require('ansi-colors');
 const {repository, homepage, version, gitter} = require('../../package.json');
@@ -25,7 +30,8 @@ const {cwd} = require('../utils');
  * - Accepts an `Array` of arguments
  * - Modifies {@link https://nodejs.org/api/modules.html#modules_module_paths Node.js' search path} for easy loading of consumer modules
  * - Sets {@linkcode https://nodejs.org/api/errors.html#errors_error_stacktracelimit Error.stackTraceLimit} to `Infinity`
- * @summary Mocha's main entry point from the command-line.
+ * @public
+ * @summary Mocha's main command-line entry-point.
  * @param {string[]} argv - Array of arguments to parse, or by default the lovely `process.argv.slice(2)`
  */
 exports.main = (argv = process.argv.slice(2)) => {
@@ -71,6 +77,11 @@ exports.main = (argv = process.argv.slice(2)) => {
     .parse(args._);
 };
 
+exports.lookupFiles = lookupFiles;
+exports.loadOptions = loadOptions;
+exports.loadPkgRc = loadPkgRc;
+exports.loadRc = loadRc;
+
 // allow direct execution
 if (require.main === module) {
   exports.main();

lib/cli/index.js

@@ -1,9 +1,3 @@
 'use strict';
 
-/**
- * Just exports {@link module:lib/cli/cli} for convenience.
- * @private
- * @module lib/cli
- * @exports module:lib/cli/cli
- */
 module.exports = require('./cli');

lib/cli/lookup-files.js

@@ -1,5 +1,11 @@
 'use strict';
 
+/**
+ * Contains `lookupFiles`, which takes some globs/dirs/options and returns a list of files.
+ * @module
+ * @private
+ */
+
 var fs = require('fs');
 var path = require('path');
 var glob = require('glob');
@@ -53,7 +59,7 @@ function hasMatchingExtname(pathname, exts) {
  * **Make no assumption that the names will be sorted in any fashion.**
  *
  * @public
- * @memberof Mocha.utils
+ * @alias module:lib/cli.lookupFiles
  * @param {string} filepath - Base path to start searching from.
  * @param {string[]} [extensions=[]] - File extensions to look for.
  * @param {boolean} [recursive=false] - Whether to recurse into subdirectories.

lib/cli/options.js

@@ -3,7 +3,8 @@
 /**
  * Main entry point for handling filesystem-based configuration,
  * whether that's a config file or `package.json` or whatever.
- * @module
+ * @module lib/cli/options
+ * @private
  */
 
 const fs = require('fs');
@@ -150,7 +151,7 @@ const parse = (args = [], defaultValues = {}, ...configObjects) => {
  * @param {Object} [args] - Arguments object
  * @param {string|boolean} [args.config] - Path to config file or `false` to skip
  * @public
- * @memberof module:lib/cli/options
+ * @alias module:lib/cli.loadRc
  * @returns {external:yargsParser.Arguments|void} Parsed config, or nothing if `args.config` is `false`
  */
 const loadRc = (args = {}) => {
@@ -167,7 +168,7 @@ module.exports.loadRc = loadRc;
  * @param {Object} [args] - Arguments object
  * @param {string|boolean} [args.config] - Path to `package.json` or `false` to skip
  * @public
- * @memberof module:lib/cli/options
+ * @alias module:lib/cli.loadPkgRc
  * @returns {external:yargsParser.Arguments|void} Parsed config, or nothing if `args.package` is `false`
  */
 const loadPkgRc = (args = {}) => {
@@ -210,7 +211,7 @@ module.exports.loadPkgRc = loadPkgRc;
  * @summary Parses options read from `.mocharc.*` and `package.json`.
  * @param {string|string[]} [argv] - Arguments to parse
  * @public
- * @memberof module:lib/cli/options
+ * @alias module:lib/cli.loadOptions
  * @returns {external:yargsParser.Arguments} Parsed args from everything
  */
 const loadOptions = (argv = []) => {

lib/mocha.js

@@ -12,18 +12,18 @@ var builtinReporters = require('./reporters');
 var growl = require('./nodejs/growl');
 var utils = require('./utils');
 var mocharc = require('./mocharc.json');
-var errors = require('./errors');
 var Suite = require('./suite');
 var esmUtils = utils.supportsEsModules(true)
   ? require('./esm-utils')
   : undefined;
 var createStatsCollector = require('./stats-collector');
-var createInvalidReporterError = errors.createInvalidReporterError;
-var createInvalidInterfaceError = errors.createInvalidInterfaceError;
-var createMochaInstanceAlreadyDisposedError =
-  errors.createMochaInstanceAlreadyDisposedError;
-var createMochaInstanceAlreadyRunningError =
-  errors.createMochaInstanceAlreadyRunningError;
+const {
+  createUnsupportedError,
+  createInvalidInterfaceError,
+  createInvalidReporterError,
+  createMochaInstanceAlreadyDisposedError,
+  createMochaInstanceAlreadyRunningError
+} = require('./errors');
 var EVENT_FILE_PRE_REQUIRE = Suite.constants.EVENT_FILE_PRE_REQUIRE;
 var EVENT_FILE_POST_REQUIRE = Suite.constants.EVENT_FILE_POST_REQUIRE;
 var EVENT_FILE_REQUIRE = Suite.constants.EVENT_FILE_REQUIRE;
@@ -445,7 +445,12 @@ Mocha.prototype.loadFilesAsync = function() {
  * @param {string} file - Pathname of file to be unloaded.
  */
 Mocha.unloadFile = function(file) {
-  delete require.cache[require.resolve(file)];
+  if (utils.isBrowser()) {
+    throw createUnsupportedError(
+      'unloadFile() is only suported in a Node.js environment'
+    );
+  }
+  return require('./nodejs/file-unloader').unloadFile(file);
 };
 
 /**
@@ -1051,9 +1056,7 @@ Mocha.prototype.rootHooks = function rootHooks(hooks) {
  */
 Mocha.prototype.parallelMode = function parallelMode(enable) {
   if (utils.isBrowser()) {
-    throw errors.createUnsupportedError(
-      'parallel mode is only supported in Node.js'
-    );
+    throw createUnsupportedError('parallel mode is only supported in Node.js');
   }
   var parallel = enable === true;
   if (
@@ -1064,7 +1067,7 @@ Mocha.prototype.parallelMode = function parallelMode(enable) {
     return this;
   }
   if (this._state !== mochaStates.INIT) {
-    throw errors.createUnsupportedError(
+    throw createUnsupportedError(
       'cannot change parallel mode after having called run()'
     );
   }

lib/nodejs/file-unloader.js

@@ -0,0 +1,15 @@
+'use strict';
+
+/**
+ * This module should not be in the browser bundle, so it's here.
+ * @private
+ * @module
+ */
+
+/**
+ * Deletes a file from the `require` cache.
+ * @param {string} file - File
+ */
+exports.unloadFile = file => {
+  delete require.cache[require.resolve(file)];
+};

lib/utils.js

@@ -645,3 +645,32 @@ exports.cwd = function cwd() {
 exports.isBrowser = function isBrowser() {
   return Boolean(process.browser);
 };
+
+/**
+ * Lookup file names at the given `path`.
+ *
+ * @description
+ * Filenames are returned in _traversal_ order by the OS/filesystem.
+ * **Make no assumption that the names will be sorted in any fashion.**
+ *
+ * @public
+ * @alias module:lib/cli.lookupFiles
+ * @param {string} filepath - Base path to start searching from.
+ * @param {string[]} [extensions=[]] - File extensions to look for.
+ * @param {boolean} [recursive=false] - Whether to recurse into subdirectories.
+ * @return {string[]} An array of paths.
+ * @throws {Error} if no files match pattern.
+ * @throws {TypeError} if `filepath` is directory and `extensions` not provided.
+ * @deprecated Moved to {@link module:lib/cli.lookupFiles}
+ */
+exports.lookupFiles = (...args) => {
+  if (exports.isBrowser()) {
+    throw require('./errors').createUnsupportedError(
+      'lookupFiles() is only supported in Node.js!'
+    );
+  }
+  exports.deprecate(
+    '`lookupFiles()` in module `mocha/lib/utils` has moved to module `mocha/lib/cli` and will be removed in the next major revision of Mocha'
+  );
+  return require('./cli').lookupFiles(...args);
+};