chore: move callback and object typedefs to a new types.d.ts (#5351)

* chore: move callback and object typedefs to a new types.d.ts

* fix: correct constants import path for options.spec.js

* Correct another require

* Fix another require

* Apply suggestions from code review

Co-authored-by: Mark Wiemer <[email protected]>

* copy-and-paste, why have you forsaken me

* Remove stub @types/workerpool

---------

Co-authored-by: Mark Wiemer <[email protected]>

Author: JoshuaKGoldberg

.github/workflows/mocha.yml

@@ -99,3 +99,8 @@ jobs:
   #   with:
   #     browsers: 'firefox@latest,chrome@latest,MicrosoftEdge@latest,safari@latest'
   #     npm-script: test-browser
+
+  tsc:
+    uses: ./.github/workflows/npm-script.yml
+    with:
+      npm-script: tsc

lib/cli/collect-files.js

@@ -4,7 +4,7 @@ const path = require('node:path');
 const pc = require('picocolors');
 const debug = require('debug')('mocha:cli:run:helpers');
 const { minimatch } = require('minimatch');
-const {NO_FILES_MATCH_PATTERN} = require('../errors').constants;
+const {NO_FILES_MATCH_PATTERN} = require('../error-constants').constants;
 const lookupFiles = require('./lookup-files');
 const {castArray} = require('../utils');
 
@@ -16,6 +16,11 @@ const {castArray} = require('../utils');
  * @private
  */
 
+/**
+ * @typedef {import('../types.d.ts').FileCollectionOptions} FileCollectionOptions
+ * @typedef {import('../types.d.ts').FileCollectionResponse} FileCollectionResponse
+ */
+
 /**
  * Smash together an array of test files in the correct order
  * @param {FileCollectionOptions} [opts] - Options
@@ -107,30 +112,3 @@ module.exports = ({
     unmatchedFiles
   };
 };
-
-/**
- * An object to configure how Mocha gathers test files
- * @private
- * @typedef {Object} FileCollectionOptions
- * @property {string[]} extension - File extensions to use
- * @property {string[]} spec - Files, dirs, globs to run
- * @property {string[]} ignore - Files, dirs, globs to ignore
- * @property {string[]} file - List of additional files to include
- * @property {boolean} recursive - Find files recursively
- * @property {boolean} sort - Sort test files
- */
-
-/**
- * Diagnostic object containing unmatched files
- * @typedef {Object} UnmatchedFile -
- * @property {string} absolutePath - A list of unmatched files derived from the file arguments passed in.
- * @property {string} pattern - A list of unmatched files derived from the file arguments passed in.
- *
- */
-
-/**
- * Response object containing a list of files to test and unmatched files.
- * @typedef {Object} FileCollectionResponse
- * @property {string[]} files - A list of files to test
- * @property {UnmatchedFile[]} unmatchedFiles - A list of unmatched files derived from the file arguments passed in.
- */

lib/cli/run-helpers.js

@@ -7,6 +7,13 @@
  * @private
  */
 
+/**
+ * @typedef {import('../mocha.js')} Mocha
+ * @typedef {import('../types.d.ts').MochaOptions} MochaOptions
+ * @typedef {import('../types.d.ts').UnmatchedFile} UnmatchedFile
+ * @typedef {import('../runner.js')} Runner
+ */
+
 const fs = require('node:fs');
 const path = require('node:path');
 const pc = require('picocolors');
@@ -137,9 +144,7 @@ const handleUnmatchedFiles = (mocha, unmatchedFiles) => {
 /**
  * Collect and load test files, then run mocha instance.
  * @param {Mocha} mocha - Mocha instance
- * @param {Options} [opts] - Command line options
- * @param {boolean} [opts.exit] - Whether or not to force-exit after tests are complete
- * @param {boolean} [opts.passOnFailingTestSuite] - Whether or not to fail test run if tests were failed
+ * @param {MochaOptions} [opts] - Command line options
  * @param {Object} fileCollectParams - Parameters that control test
  *   file collection. See `lib/cli/collect-files.js`.
  * @returns {Promise<Runner>}
@@ -167,15 +172,15 @@ const singleRun = async (
 };
 
 /**
- * Collect files and run tests (using `BufferedRunner`).
+ * Collect files and run tests (using `Runner`).
  *
  * This is `async` for consistency.
  *
  * @param {Mocha} mocha - Mocha instance
- * @param {Options} options - Command line options
+ * @param {MochaOptions} options - Command line options
  * @param {Object} fileCollectParams - Parameters that control test
  *   file collection. See `lib/cli/collect-files.js`.
- * @returns {Promise<BufferedRunner>}
+ * @returns {Promise<Runner>}
  * @ignore
  * @private
  */
@@ -205,7 +210,7 @@ const parallelRun = async (mocha, options, fileCollectParams) => {
  * - `parallelRun`: run tests in parallel & exit
  * - `watchParallelRun`: run tests in parallel, rerunning as files change
  * @param {Mocha} mocha - Mocha instance
- * @param {Options} opts - Command line options
+ * @param {MochaOptions} options - Command line options
  * @private
  * @returns {Promise<Runner>}
  */

lib/cli/run-option-metadata.js

@@ -9,7 +9,7 @@
 
 /**
  * Dictionary of yargs option types to list of options having said type
- * @type {{string:string[]}}
+ * @type {Record<string, string[]>}
  * @private
  */
 const TYPES = (exports.types = {
@@ -67,7 +67,7 @@ const TYPES = (exports.types = {
 /**
  * Option aliases keyed by canonical option name.
  * Arrays used to reduce
- * @type {{string:string[]}}
+ * @type {Record<string, string[]>}
  * @private
  */
 exports.aliases = {

lib/cli/watch-run.js

@@ -8,6 +8,14 @@ const Context = require('../context');
 const collectFiles = require('./collect-files');
 const glob = require('glob');
 
+/**
+ * @typedef {import('chokidar').FSWatcher} FSWatcher
+ * @typedef {import('../mocha.js')} Mocha
+ * @typedef {import('../types.d.ts').BeforeWatchRun} BeforeWatchRun
+ * @typedef {import('../types.d.ts').FileCollectionOptions} FileCollectionOptions
+ * @typedef {import('../types.d.ts').Rerunner} Rerunner
+ */
+
 /**
  * Exports the `watchRun` function that runs mocha in "watch" mode.
  * @see module:lib/cli/run-helpers
@@ -402,20 +410,3 @@ const blastCache = watcher => {
   });
   debug('deleted %d file(s) from the require cache', files.length);
 };
-
-/**
- * Callback to be run before `mocha.run()` is called.
- * Optionally, it can return a new `Mocha` instance.
- * @callback BeforeWatchRun
- * @private
- * @param {{mocha: Mocha, watcher: FSWatcher}} options
- * @returns {Mocha}
- */
-
-/**
- * Object containing run control methods
- * @typedef {Object} Rerunner
- * @private
- * @property {Function} run - Calls `mocha.run()`
- * @property {Function} scheduleRun - Schedules another call to `run`
- */

lib/context.js

@@ -1,4 +1,9 @@
 'use strict';
+
+/**
+ * @typedef {import('./runnable.js')} Runnable
+ */
+
 /**
  * @module Context
  */

lib/error-constants.js

@@ -0,0 +1,123 @@
+'use strict';
+
+/**
+ * When Mocha throws exceptions (or rejects `Promise`s), it attempts to assign a `code` property to the `Error` object, for easier handling. These are the potential values of `code`.
+ * @public
+ * @namespace
+ * @memberof module:lib/errors
+ */
+var constants = {
+  /**
+   * An unrecoverable error.
+   * @constant
+   * @default
+   */
+  FATAL: 'ERR_MOCHA_FATAL',
+
+  /**
+   * The type of an argument to a function call is invalid
+   * @constant
+   * @default
+   */
+  INVALID_ARG_TYPE: 'ERR_MOCHA_INVALID_ARG_TYPE',
+
+  /**
+   * The value of an argument to a function call is invalid
+   * @constant
+   * @default
+   */
+  INVALID_ARG_VALUE: 'ERR_MOCHA_INVALID_ARG_VALUE',
+
+  /**
+   * Something was thrown, but it wasn't an `Error`
+   * @constant
+   * @default
+   */
+  INVALID_EXCEPTION: 'ERR_MOCHA_INVALID_EXCEPTION',
+
+  /**
+   * An interface (e.g., `Mocha.interfaces`) is unknown or invalid
+   * @constant
+   * @default
+   */
+  INVALID_INTERFACE: 'ERR_MOCHA_INVALID_INTERFACE',
+
+  /**
+   * A reporter (.e.g, `Mocha.reporters`) is unknown or invalid
+   * @constant
+   * @default
+   */
+  INVALID_REPORTER: 'ERR_MOCHA_INVALID_REPORTER',
+
+  /**
+   * `done()` was called twice in a `Test` or `Hook` callback
+   * @constant
+   * @default
+   */
+  MULTIPLE_DONE: 'ERR_MOCHA_MULTIPLE_DONE',
+
+  /**
+   * No files matched the pattern provided by the user
+   * @constant
+   * @default
+   */
+  NO_FILES_MATCH_PATTERN: 'ERR_MOCHA_NO_FILES_MATCH_PATTERN',
+
+  /**
+   * Known, but unsupported behavior of some kind
+   * @constant
+   * @default
+   */
+  UNSUPPORTED: 'ERR_MOCHA_UNSUPPORTED',
+
+  /**
+   * Invalid state transition occurring in `Mocha` instance
+   * @constant
+   * @default
+   */
+  INSTANCE_ALREADY_RUNNING: 'ERR_MOCHA_INSTANCE_ALREADY_RUNNING',
+
+  /**
+   * Invalid state transition occurring in `Mocha` instance
+   * @constant
+   * @default
+   */
+  INSTANCE_ALREADY_DISPOSED: 'ERR_MOCHA_INSTANCE_ALREADY_DISPOSED',
+
+  /**
+   * Use of `only()` w/ `--forbid-only` results in this error.
+   * @constant
+   * @default
+   */
+  FORBIDDEN_EXCLUSIVITY: 'ERR_MOCHA_FORBIDDEN_EXCLUSIVITY',
+
+  /**
+   * To be thrown when a user-defined plugin implementation (e.g., `mochaHooks`) is invalid
+   * @constant
+   * @default
+   */
+  INVALID_PLUGIN_IMPLEMENTATION: 'ERR_MOCHA_INVALID_PLUGIN_IMPLEMENTATION',
+
+  /**
+   * To be thrown when a builtin or third-party plugin definition (the _definition_ of `mochaHooks`) is invalid
+   * @constant
+   * @default
+   */
+  INVALID_PLUGIN_DEFINITION: 'ERR_MOCHA_INVALID_PLUGIN_DEFINITION',
+
+  /**
+   * When a runnable exceeds its allowed run time.
+   * @constant
+   * @default
+   */
+  TIMEOUT: 'ERR_MOCHA_TIMEOUT',
+
+  /**
+   * Input file is not able to be parsed
+   * @constant
+   * @default
+   */
+  UNPARSABLE_FILE: 'ERR_MOCHA_UNPARSABLE_FILE'
+};
+
+module.exports = { constants };