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/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);
+};

package.json

@@ -173,7 +173,8 @@
     "./lib/nodejs/worker.js": false,
     "./lib/nodejs/buffered-worker-pool.js": false,
     "./lib/nodejs/parallel-buffered-runner.js": false,
-    "./lib/nodejs/reporters/parallel-buffered.js": false
+    "./lib/nodejs/reporters/parallel-buffered.js": false,
+    "./lib/cli/index.js": false
   },
   "prettier": {
     "singleQuote": true,

test/unit/utils.spec.js

@@ -742,4 +742,49 @@ describe('lib/utils', function() {
       expect(utils.slug('poppies & fritz'), 'to be', 'poppies-fritz');
     });
   });
+
+  describe('lookupFiles()', function() {
+    beforeEach(function() {
+      sinon.stub(utils, 'deprecate');
+    });
+
+    describe('when run in Node.js', function() {
+      before(function() {
+        if (process.browser) {
+          return this.skip();
+        }
+      });
+
+      beforeEach(function() {
+        sinon.stub(utils, 'isBrowser').returns(false);
+        sinon.stub(require('../../lib/cli'), 'lookupFiles').returns([]);
+      });
+
+      it('should print a deprecation message', function() {
+        utils.lookupFiles();
+        expect(utils.deprecate, 'was called once');
+      });
+
+      it('should delegate to new location of lookupFiles()', function() {
+        utils.lookupFiles(['foo']);
+        expect(
+          require('../../lib/cli').lookupFiles,
+          'to have a call satisfying',
+          [['foo']]
+        ).and('was called once');
+      });
+    });
+
+    describe('when run in browser', function() {
+      beforeEach(function() {
+        sinon.stub(utils, 'isBrowser').returns(true);
+      });
+
+      it('should throw', function() {
+        expect(() => utils.lookupFiles(['foo']), 'to throw', {
+          code: 'ERR_MOCHA_UNSUPPORTED'
+        });
+      });
+    });
+  });
 });