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

[boneskull]

• 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:

const {loadRc, loadPkgRc, loadOptions, lookupFiles} = require('mocha/lib/cli');

UPDATE

• restores lookupFiles to lib/utils to un-break the breaking change introduced in v8.1.0.
• use of lookupFiles in lib/utils will print a deprecation notice directing the consumer to the new path
• use of lookupFiles in lib/utils in a browser (since it's accessible) will throw an exception.

ANOTHER UPDATE

• moves require.cache-touching code out of lib/mocha.js and into lib/nodejs/file-unloader.js; excludes this file from the bundle
• add test to assert a webpack build which imports the mocha bundle emits no errors or warnings

[coveralls]

Coverage increased (+0.02%) to 93.827% when pulling 72346e3 on boneskull/issue/4398 into c733254 on master.

[boneskull]

@mochajs/core I know y'all had some thoughts about #4398, so would appreciate feedback here. I think it's important to fix the breaking change and issue a deprecation notice, but I won't protest if you'd like me to revert my other API-surface changes here.

[Munter]

I moved lookupFiles out of utils because utils is required in the browser build and having a dependency graph in there that starts requiring node libraries was problematic. If we add node specific code back to the utils dependency graph we need to make sure the browser bundle doesn't break, and given #4422 that it also doesn't cause bundlers to break

[nicojs]

Good to add this API back. 👍

[boneskull]

yes, it does not appear in the bundle.

[boneskull]

Will fix #4422 here as well.

[boneskull]

@Munter to be clear, I don't disagree that file-touching stuff should not be in lib/utils.js or lib/mocha.js.

@mochajs/core we can move utils.lookupFiles() and Mocha.unloadFiles() (Mocha.unloadFile() is not a public API) for good in v9, if we want. I did not soft-deprecate Mocha.unloadFiles() here, but perhaps I should, and export it from lib/cli like the others?

[boneskull]

please note that this now adds webpack to our development dependencies 😦 . probably better to do declare it explicitly than to just npx it.

[Munter]

A future major to move these out of the browser graph would be great. I have a few ideas for attempting a cleaner cut that I can start a draft of soon

[craigtaub]

LGTM

[auroq]

As per request for comment here: #4398 (comment)

In terms of whether we need globbing to be part of Mocha, the answer is no. It's not difficult to do globbing ourselves. However, what we are trying to do when calling mocha.run programmatically is emulate the CLI in an automated fashion.

Thus, my argument is one for consistency. As boneskull stated, something like globbing being part of mocha is "of dubious necessity" as third party globbing tools could be used. If that's the case, though, I would expect to also need to do globbing beforehand if I was calling mocha from CLI or in a bash script.

Basically, I advocate that one shouldn't have to relearn a new approach to calling a tool like mocha for every method of interaction it supports. It should be basically the same overall approach.

Regardless, thank you for your time and thoughtful consideration in maintaining this library.