docs: document Node.js' --enable-source-maps flag

[bcoe]

Description of the Change

Newer versions of Node.js introduce the --enable-source-maps flag which, when enabled, caches source-maps and provides accurate stack traces to users running transpiled code, e.g., TypeScript.

Benefits

Many users of Node.js are writing TypeScript, this allows them to receive better stack traces in mocha without installing any dependencies.

Drawbacks

There's still work to be done to polish this feature in Node.js (would very much appreciate getting feedback).

[jsf-clabot]

All committers have signed the CLA.

[coveralls]

Coverage increased (+0.03%) to 93.467% when pulling edb8e6b on bcoe:note-about-source-maps into cb5eb8e on mochajs:master.

[juergba]

@bcoe thank you for this PR.

We do not whitelist or document NodeJs options in our documentation. There are just a few exceptions like --inspect/--inspect-brk or --experimental-modules.
IMO we should not start doing this, it's a bottomless task.
In our repo mocha-examples we offer some working samples incl. TS setups, maybe that's the place to recommend the --enable-source-maps flag.

[bcoe]

IMO we should not start doing this, it's a bottomless task.

I understand 100% where you're coming from.

Worth considering though, something like 60% of folks writing JavaScript these days spend at least some time writing TypeScript. Rather than just documenting this flag, it might be worth having a section of docs that speaks to making mocha work well with TypeScript:

1. speaking to which reporters work well with TypeScript (I believe some have source-map-support as a dependency?).
2. documenting the -enable-source-maps flag.
3. speaking to the source-map-support library.

[boneskull]

I think this is worth adding. I realize that documenting node flags is a slippery slope (as @juergba wrote, there's no end to it), but I think we should take it on a case-by-case basis. It's plainly useful information, and I'd like to see more of this on the docs site. That said, we should add to the examples repo.

@bcoe can you please resolve the conflict?

[boneskull]

please address comments + resolve conflicts

[bcoe]

@boneskull 👍 will try to get this done ASAP.

[outsideris]

It is under COMMAND-LINE USAGE now.
How about we document it under ABOUT node FLAGS because it is a node flag not mocha flag.

[boneskull]

@bcoe The build is failing because there's an incorrect anchor link. Also, @outsideris had a request

[bcoe]

@boneskull done 👍

[outsideris]

Thank you.