feat: add option to use posix exit code upon fatal signal

[73rhodes]

Requirements

• Filling out the template is required. Any pull request that does not include enough information to be reviewed in a timely manner may be closed at the maintainers' discretion.
• All new code requires tests to ensure against regressions.

Description of the Change

This PR introduces a --posix-exit-codes boolean command-line option. If this option is specified, a fatal signal (eg. SIGABRT, et al) will cause the process to consistently exit with a standard posix exit code (128 + the numeric ID of the signal) when mocha is run as a child process (which is the case when passing node options). This helps to solve issues for toolchains that expect standard posix exit codes, for example by preventing out-of-memory crashes from being silently ignored.

Alternate Designs

The alternatives considered were not in the scope of the mocha project.

Why should this be in core?

This option is implemented in the core repository where signal handling occurs.

Benefits

This PR provides a solution for #3559 and various downstream issues reported by mocha consumers; it preserves non-zero exit codes when mocha is spawned as a child process via various CI/CD or reporting tools and prevents silently swallowing out-of-memory errors.

Possible Drawbacks

Introduces another option. Requires docs. Leaves non-standard exit code behavior to remain as the default.

Applicable issues

fixes #3559
#3893
#2445
#2438
istanbuljs/nyc#798
cypress-io/cypress#24695

• No breaking changes; this is an ehancement (minor release)

[linux-foundation-easycla]

The committers listed above are authorized under a signed CLA.

• ✅ login: 73rhodes / name: Darren DeRidder (34f2822, d2991a1, 2150c30, 8a4f2bd, 62528c5, 3438da6, 592f071, 817d890, 0fb6ca3, 8999b7b, 609f94f, b71eaf3, ad30057, 0aa939f, 26bebac, 59e471d, 7cf79d8, 3b99517, 6d237fc, b6e6d30)

[github-actions]

This PR hasn't had any recent activity, and I'm labeling it stale. Remove the label or comment or this PR will be closed in 14 days. Thanks for contributing to Mocha!

[JoshuaKGoldberg]

We should probably disable the stale action, pending picking up reviewing PRs.

[JoshuaKGoldberg]

Nice and clean implementation, thanks! ✨

Requesting changes on a few things. But let me know, please, if I'm off base here 🙂.

[JoshuaKGoldberg]

Note that after this lands, we'll want to file a followup issue about making this the default behavior in some future version of Mocha.

[73rhodes]

@JoshuaKGoldberg Thanks for the review! Hopefully that latest update addresses your questions, but let me know if there's anything else you'd like to see. Looking froward to not using our own fork of mocha! 😆

[JoshuaKGoldberg]

Progress! Thanks for adding in the tests. I think we'll need to capture some more cases?

[73rhodes]

@JoshuaKGoldberg do you want to take a look at this again? I went with your suggestion to exit with 1 like Jest and Vitest when you've asked for posix/unix shell exit codes and you've got test failures. @plroebuck raised the point that there's a distinction between posix exit codes and unix shell exit codes but I think the naming is okay given the following documentation from the GNU libc manual page on exit status:

Warning: Don’t try to use the number of errors as the exit status. This is actually not very useful; a parent process would generally not care how many errors occurred. Worse than that, it does not work, because the status value is truncated to eight bits. Thus, if the program tried to report 256 errors, the parent would receive a report of 0 errors—that is, success.

For the same reason, it does not work to use the value of errno as the exit status—these can exceed 255.

Portability note: Some non-POSIX systems use different conventions for exit status values. For greater portability, you can use the macros EXIT_SUCCESS and EXIT_FAILURE for the conventional status value for success and failure, respectively. They are declared in the file stdlib.h.

[edit: this mention of non-POSIX systems implies that the exit status reporting described in the GNU libc manual is pretty standard for POSIX systems, hence my feeling that --posix-exit-codes is a pretty okay name for the flag).

[JoshuaKGoldberg]

Will take a look, thanks!

[JoshuaKGoldberg]

Threading #4989 (comment) & from #4989 (comment):

(which might better be called --unix-exit-codes based on the discussion here)

Yeah, the requested behavior has evolved a good bit. I wonder if a better name would be --standard-exit-codes? That way the word "standard" is intentionally a little ambiguous, to match how this adheres more to the general community standard of how test runners should exit, rather than the precise posix or unix standards...

This isn't a blocker for me. The long-term plan is to make this the default in a future Mocha version anyway. So I'll happily defer to you & the rest of the team. 😄

[73rhodes]

I've no strong opinion on the naming and can change it if that's needed to get final approval, but I'll leave it as-is for now considering that the gnu docs I referenced mention this kind of exit code is standard for posix systems... lmk if I should change it though.

[JoshuaKGoldberg]

This looks wonderful to me, thanks so much for all the discussion and iteration @73rhodes! 🙌

Marking this as having one team member approval. We'll want another team member to take a look too. Ping @voxpelli, IIRC you were particularly interested in making Mocha more standards-compliant?

[coveralls]

coverage: 94.371% (+0.01%) from 94.358%
when pulling 59e471d on zendesk:master
into 99601da on mochajs:master.