Pass returnValue to formatter with needlessDisables + invalidScopeDisables

[shawnbot]

Fixes #4136. I've shuffled things around in the standalone prepareReturnValue() function so that the output is set last and the formatting function gets the returnValue object as its second argument, so that needless disables can be accessed like so in a custom formatter:

module.exports = function customFormatter(results, returnValue) {
  const errors = formatErrors(results)
  if (returnValue.needlessDisables) {
    errors.push(...formatNeedlessDisables(returnValue.needlessDisables))
  }
  return errors.join('\n')
}

The returnValue object includes:

• the errored flag
• a needlessDisables array if configured with reportNeedlessDisables: true
• an invalidScopeDisables array if configured with reportInvalidScopeDisables: true
• a maxWarningsExceeded object if configured with maxWarnings

[shawnbot]

Initializing these with empty values appears to have been necessary to appease the lint:types script (tsc). I'm not familiar with TypeScript, but I imagine there's a way to do this in the @type comment instead?

[vankop]

I thinks it is fine to initialize with empty fields

[vankop]

👍

[hudochenkov]

Thank you for fixing this problem!

Could you update documentation, please? https://github.com/stylelint/stylelint/blob/master/docs/developer-guide/formatters.md

[github-actions]

Coverage increased (+0.0006%) to 96.875% when pulling b318ea1 on primer:format-needless-disables into 85174c7 on stylelint:master.

[shawnbot]

Okay, docs updated in 2982fa1; preview here.

[hudochenkov]

• Added: more information for custom formatters (#4393).