From 247d9611ea1a77d1c1029b0eae812b271445592f Mon Sep 17 00:00:00 2001
From: Christopher Hiller <boneskull@boneskull.com>
Date: Tue, 25 Aug 2020 13:41:34 -0700
Subject: [PATCH] alias lookupFiles, loadRc, loadPkgRc and loadOptions to
 lib/cli module; fixes #4398

- fixes API documentation for all of these (and `module:lib/cli.main`) via JSDoc aliasing
- aliases `lib/cli/cli.js` to `module:lib/cli`; `module:lib/cli/cli` is no longer a thing
- the `lib/cli/options.js` and `lib/cli/lookup-files.js` _modules_ (not necessarily their _contents_) are now private

example usage:

```js
const {loadRc, loadPkgRc, loadOptions, lookupFiles} = require('mocha/lib/cli');
```
---
 lib/cli/cli.js          | 27 +++++++++++++++++++--------
 lib/cli/index.js        |  6 ------
 lib/cli/lookup-files.js |  8 +++++++-
 lib/cli/options.js      |  9 +++++----
 4 files changed, 31 insertions(+), 19 deletions(-)

diff --git a/lib/cli/cli.js b/lib/cli/cli.js
index ffbe5dada5..f3b780cf9d 100755
--- a/lib/cli/cli.js
+++ b/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();
diff --git a/lib/cli/index.js b/lib/cli/index.js
index d792f0c9de..f20314ea99 100644
--- a/lib/cli/index.js
+++ b/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');
diff --git a/lib/cli/lookup-files.js b/lib/cli/lookup-files.js
index 2223ad09c2..c49204842a 100644
--- a/lib/cli/lookup-files.js
+++ b/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.
diff --git a/lib/cli/options.js b/lib/cli/options.js
index c51865916d..1ffa000398 100644
--- a/lib/cli/options.js
+++ b/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 = []) => {