[Feature] add exit code explanations for "yarn npm audit"

[Crare]

• I'd be willing to implement this feature (contributing guide)
• This feature is important to have in this repository; a contrib plugin wouldn't do

Describe the user story

We are using 'yarn npm audit' for auditing packages in pipeline. we want to receive information about what severity by highest severity was found with the exit code, if it's over moderate severity, we want it to return exit code that we can check to stop the pipeline continuing. Lower severities will print out warnings. We still want to see the audit results in full so the "--severity" argument is not an option as I think it will hide lower severity results. So we use the exitcode to define what severity is highest. But there is no documentation what these exitcodes are. Are they even the severity level or something else like the amount of vulnerabilities found?

Describe the solution you'd like

Add clear list of all the possible exit codes the "yarn npm audit" outputs and their explanation in the documentation : https://yarnpkg.com/cli/npm/audit.

Describe the drawbacks of your solution

I can't see none, it's just adding more information what the script does.

Describe alternatives you've considered

none.

[SimonMorkSaetre]

Yarn Classic has documentation for the exit codes. I assume the documentation is still valid? Would be nice to have it in the newest Yarn documentation too Yarn Audit

[Crare]

@SimonMorkSaetre wait that is additive:

For example, if only INFO and MODERATE vulnerabilities were found, then the exit code will be 1 + 4 = 5

if it were possible to have the exitcode to be the highest value instead, that would be more useful for me. Because you can have many moderate vulnerabilities that count to big number, but you are more conserned about the high severities etc. for example.
Maybe make it have an extra argument to make the exitcode to be the highest severity instead combination of those severities?

[SimonMorkSaetre]

@Crare
The audit exit code does care about the amount of vulnerabilities, only if there are any in a certain category. You can either use yarn audit --critical, yarn audit --high and so on in descending order. Then make it exit whenever it finds something in that vulnerability category

[arcanis]

That's only how classic worked. The command now simply fails if you have errors:
https://github.com/yarnpkg/berry/blob/master/packages/plugin-npm-cli/sources/commands/npm/audit.ts#L235

If you wish to tweak what type of error exist, run the command multiple times with different severities, or use the structured JSON output (--json).