Update LoadedFormatter and FormatterFunction typedefs

Originally suggested by @fasttime in
#16348 (comment).

Internally, I define two types, `MaxWarningsExceeded` and `ResultsMeta`,
that the updated `LoadedFormatter` and `FormatterFunction` types can
use. I'm then able to reuse the `ResultsMeta` type instead of the
generic `Object` type in `ESLint` and `FlatESLint`'s `format` wrapper
functions.

Externally in the Node.js API docs, I describe the new second argument
to `LoadedFormatter`'s `format` method inline rather than separately
documenting the new types.

While working on this, I noticed that `FlatESLint` is using the
pre-PR #15727 `Formatter` type rather than `LoadedFormatter` and
`FormatterFunction`. I'll fix that in a follow-up PR to keep this PR
scoped to passing `maxWarningsExceeded` info.

docs/src/developer-guide/nodejs-api.md

@@ -410,8 +410,8 @@ This edit information means replacing the range of the `range` property by the `
 
 The `LoadedFormatter` value is the object to convert the [LintResult] objects to text. The [eslint.loadFormatter()][eslint-loadformatter] method returns it. It has the following method:
 
-* `format` (`(results: LintResult[]) => string | Promise<string>`)<br>
-  The method to convert the [LintResult] objects to text.
+* `format` (`(results: LintResult[], resultsMeta: ResultsMeta) => string | Promise<string>`)<br>
+  The method to convert the [LintResult] objects to text. `resultsMeta` is an object that will contain a `maxWarningsExceeded` object if `--max-warnings` was set and the number of warnings exceeded the limit. The `maxWarningsExceeded` object will contain two properties: `maxWarnings`, the value of the `--max-warnings` option, and `foundWarnings`, the number of lint warnings.
 
 ---
 

lib/cli.js

@@ -38,6 +38,7 @@ const debug = require("debug")("eslint:cli");
 /** @typedef {import("./eslint/eslint").LintMessage} LintMessage */
 /** @typedef {import("./eslint/eslint").LintResult} LintResult */
 /** @typedef {import("./options").ParsedCLIOptions} ParsedCLIOptions */
+/** @typedef {import("./shared/types").ResultsMeta} ResultsMeta */
 
 //------------------------------------------------------------------------------
 // Helpers
@@ -239,7 +240,7 @@ async function isDirectory(filePath) {
  * @param {LintResult[]} results The results to print.
  * @param {string} format The name of the formatter to use or the path to the formatter.
  * @param {string} outputFile The path for the output file.
- * @param {Object} resultsMeta Warning count and max threshold.
+ * @param {ResultsMeta} resultsMeta Warning count and max threshold.
  * @returns {Promise<boolean>} True if the printing succeeds, false if not.
  * @private
  */

lib/eslint/eslint.js

@@ -36,11 +36,12 @@ const { version } = require("../../package.json");
 /** @typedef {import("../shared/types").Plugin} Plugin */
 /** @typedef {import("../shared/types").Rule} Rule */
 /** @typedef {import("../shared/types").LintResult} LintResult */
+/** @typedef {import("../shared/types").ResultsMeta} ResultsMeta */
 
 /**
  * The main formatter object.
  * @typedef LoadedFormatter
- * @property {function(LintResult[]): string | Promise<string>} format format function.
+ * @property {(results: LintResult[], resultsMeta: ResultsMeta) => string | Promise<string>} format format function.
  */
 
 /**
@@ -625,7 +626,7 @@ class ESLint {
             /**
              * The main formatter method.
              * @param {LintResult[]} results The lint results to format.
-             * @param {Object} resultsMeta Warning count and max threshold.
+             * @param {ResultsMeta} resultsMeta Warning count and max threshold.
              * @returns {string | Promise<string>} The formatted lint results.
              */
             format(results, resultsMeta) {

lib/eslint/flat-eslint.js

@@ -59,6 +59,7 @@ const LintResultCache = require("../cli-engine/lint-result-cache");
 /** @typedef {import("../shared/types").LintMessage} LintMessage */
 /** @typedef {import("../shared/types").ParserOptions} ParserOptions */
 /** @typedef {import("../shared/types").Plugin} Plugin */
+/** @typedef {import("../shared/types").ResultsMeta} ResultsMeta */
 /** @typedef {import("../shared/types").RuleConf} RuleConf */
 /** @typedef {import("../shared/types").Rule} Rule */
 /** @typedef {ReturnType<ConfigArray.extractConfig>} ExtractedConfig */
@@ -1114,7 +1115,7 @@ class FlatESLint {
             /**
              * The main formatter method.
              * @param {LintResults[]} results The lint results to format.
-             * @param {Object} resultsMeta Warning count and max threshold.
+             * @param {ResultsMeta} resultsMeta Warning count and max threshold.
              * @returns {string} The formatted lint results.
              */
             format(results, resultsMeta) {

lib/shared/types.js

@@ -190,10 +190,23 @@ module.exports = {};
  * @property {DeprecatedRuleInfo[]} usedDeprecatedRules The list of used deprecated rules.
  */
 
+/**
+ * Information provided when the maximum warning threshold is exceeded.
+ * @typedef {Object} MaxWarningsExceeded
+ * @property {number} maxWarnings Number of warnings to trigger nonzero exit code.
+ * @property {number} foundWarnings Number of warnings found while linting.
+ */
+
+/**
+ * Metadata about results for formatters.
+ * @typedef {Object} ResultsMeta
+ * @property {MaxWarningsExceeded} [maxWarningsExceeded] Present if the maxWarnings threshold was exceeded.
+ */
+
 /**
  * A formatter function.
  * @callback FormatterFunction
  * @param {LintResult[]} results The list of linting results.
- * @param {{cwd: string, rulesMeta: Record<string, RuleMeta>}} [context] A context object.
+ * @param {{cwd: string, maxWarningsExceeded?: MaxWarningsExceeded, rulesMeta: Record<string, RuleMeta>}} [context] A context object.
  * @returns {string | Promise<string>} Formatted text.
  */