WIP Playing around with .d.ts generation

.gitignore

@@ -4,6 +4,7 @@ docs/_dist
 mocha.js
 .karma/
 !lib/mocha.js
+/types
 
 #########################################
 # NON-MOCHA STUFF GOES BELOW THIS THING #

globals.d.ts

@@ -0,0 +1,11 @@
+import * as Mocha from './';
+
+declare global {
+  const after: typeof Mocha.after;
+  const afterEach: typeof Mocha.afterEach;
+  const before: typeof Mocha.after;
+  const beforeEach: typeof Mocha.beforeEach;
+  const describe: typeof Mocha.describe;
+  const it: typeof Mocha.after;
+  const xit: typeof Mocha.xit;
+}

index.d.ts

@@ -0,0 +1,2 @@
+import * as Mocha from './types/mocha';
+export = Mocha;

lib/cli/options.js

@@ -165,9 +165,8 @@ const parseMochaOpts = content =>
 
 /**
  * Given filepath in `args.opts`, attempt to load and parse a `mocha.opts` file.
- * @param {Object} [args] - Arguments object
- * @param {string|boolean} [args.opts] - Filepath to mocha.opts; defaults to whatever's in `mocharc.opts`, or `false` to skip
- * @returns {external:yargsParser.Arguments|void} If read, object containing parsed arguments
+ * @param {import('./options_t').MochaArgs} [args] - Arguments object
+ * @returns {import('yargs-parser').Arguments | void} If read, object containing parsed arguments
  * @memberof module:lib/cli/options
  * @see {@link /#mochaopts|mocha.opts}
  * @public
@@ -210,11 +209,10 @@ module.exports.loadMochaOpts = loadMochaOpts;
 
 /**
  * Given path to config file in `args.config`, attempt to load & parse config file.
- * @param {Object} [args] - Arguments object
- * @param {string|boolean} [args.config] - Path to config file or `false` to skip
+ * @param {import('./options_t').MochaArgs} [args] - Arguments object
  * @public
  * @memberof module:lib/cli/options
- * @returns {external:yargsParser.Arguments|void} Parsed config, or nothing if `args.config` is `false`
+ * @returns {import('yargs-parser').Arguments | void} Parsed config, or nothing if `args.config` is `false`
  */
 const loadRc = (args = {}) => {
   if (args.config !== false) {
@@ -227,11 +225,10 @@ module.exports.loadRc = loadRc;
 
 /**
  * Given path to `package.json` in `args.package`, attempt to load config from `mocha` prop.
- * @param {Object} [args] - Arguments object
- * @param {string|boolean} [args.config] - Path to `package.json` or `false` to skip
+ * @param {import('./options_t').MochaArgs} [args] - Arguments object
  * @public
  * @memberof module:lib/cli/options
- * @returns {external:yargsParser.Arguments|void} Parsed config, or nothing if `args.package` is `false`
+ * @returns {import('yargs-parser').Arguments | void} Parsed config, or nothing if `args.package` is `false`
  */
 const loadPkgRc = (args = {}) => {
   let result;
@@ -275,7 +272,7 @@ module.exports.loadPkgRc = loadPkgRc;
  * @param {string|string[]} [argv] - Arguments to parse
  * @public
  * @memberof module:lib/cli/options
- * @returns {external:yargsParser.Arguments} Parsed args from everything
+ * @returns {import('yargs-parser').Arguments} Parsed args from everything
  */
 const loadOptions = (argv = []) => {
   let args = parse(argv);

lib/cli/options_t.ts

@@ -0,0 +1,7 @@
+export interface MochaArgs {
+  /** Path to `package.json` or `false` to skip */
+  config?: string | false;
+  package?: boolean;
+  /** Filepath to mocha.opts; defaults to whatever's in `mocharc.opts`, or `false` to skip */
+  opts?: string | false;
+}

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
  */
 exports.types = {
@@ -63,7 +63,7 @@ exports.types = {
 /**
  * Option aliases keyed by canonical option name.
  * Arrays used to reduce
- * @type {{string:string[]}}
+ * @type {Record<string, string[]>}
  * @private
  */
 exports.aliases = {

lib/runnable.js

@@ -64,7 +64,7 @@ utils.inherits(Runnable, EventEmitter);
  *
  * @private
  * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/setTimeout#Maximum_delay_value}
- * @param {number|string} ms - Timeout threshold value.
+ * @param {number|string} [ms] - Timeout threshold value.
  * @returns {Runnable} this
  * @chainable
  */
@@ -260,13 +260,14 @@ Runnable.prototype.resetTimeout = function() {
     return;
   }
   this.clearTimeout();
-  this.timer = setTimeout(function() {
+  /** @type {number} */
+  this.timer = /** @type {any} */ (setTimeout(function() {
     if (!self._enableTimeouts) {
       return;
     }
     self.callback(self._timeoutError(ms));
     self.timedOut = true;
-  }, ms);
+  }, ms));
 };
 
 /**

lib/utils.js

@@ -29,7 +29,10 @@ var assign = (exports.assign = require('object.assign').getPolyfill());
  * @throws {TypeError} if either constructor is null, or if super constructor
  *     lacks a prototype.
  */
-exports.inherits = util.inherits;
+exports.inherits = function(ctor, superCtor) {
+  // Wrapper prevents type declarations from referring to @types/node
+  return util.inherits.call(this, ctor, superCtor);
+};
 
 /**
  * Escape special characters in the given string of html.
@@ -708,7 +711,7 @@ exports.isPromise = function isPromise(value) {
  * Clamps a numeric value to an inclusive range.
  *
  * @param {number} value - Value to be clamped.
- * @param {numer[]} range - Two element array specifying [min, max] range.
+ * @param {number[]} range - Two element array specifying [min, max] range.
  * @returns {number} clamped value
  */
 exports.clamp = function clamp(value, range) {

package-scripts.js

@@ -23,8 +23,18 @@ function test(testName, mochaParams) {
 module.exports = {
   scripts: {
     build: {
-      script: `browserify -e browser-entry.js --plugin ./scripts/dedefine --ignore './lib/cli/*.js' --ignore 'chokidar' --ignore 'fs' --ignore 'glob' --ignore 'path' --ignore 'supports-color' -o mocha.js`,
-      description: 'Build browser bundle'
+      default: {
+        script: 'nps build.types build.browser',
+        description: 'Build'
+      },
+      types: {
+        script: 'tsc -p . || true', // swallowing until I finish fixing all semantic errors
+        description: 'Build type declarations'
+      },
+      browser: {
+        script: `browserify -e browser-entry.js --plugin ./scripts/dedefine --ignore './lib/cli/*.js' --ignore 'chokidar' --ignore 'fs' --ignore 'glob' --ignore 'path' --ignore 'supports-color' -o mocha.js`,
+        description: 'Build browser bundle'
+      }
     },
     lint: {
       default: {
@@ -64,7 +74,7 @@ module.exports = {
     },
     test: {
       default: {
-        script: 'nps lint test.node test.browser test.bundle',
+        script: 'nps lint test.node test.browser test.bundle test.types',
         description: 'Run all linters and all tests'
       },
       node: {
@@ -251,6 +261,10 @@ module.exports = {
           description: 'Run AMD bundle tests',
           hiddenFromHelp: true
         }
+      },
+      types: {
+        script: 'cd test/types && tsc -p .',
+        description: 'Test emitted type declarations.'
       }
     },
     coveralls: {

package.json

@@ -521,6 +521,7 @@
     "mocha": "./bin/mocha",
     "_mocha": "./bin/_mocha"
   },
+  "types": "types",
   "directories": {
     "lib": "./lib",
     "test": "./test"
@@ -564,6 +565,8 @@
     "@11ty/eleventy": "^0.8.3",
     "@mocha/contributors": "^1.0.4",
     "@mocha/docdash": "^2.1.2",
+    "@types/node": "^13.1.8",
+    "@types/yargs": "^15.0.0",
     "acorn": "^7.0.0",
     "assetgraph-builder": "^6.10.1",
     "autoprefixer": "^9.6.0",
@@ -615,6 +618,7 @@
     "svgo": "^1.2.2",
     "through2": "^3.0.1",
     "to-vfile": "^5.0.3",
+    "typescript": "^3.7.5",
     "unexpected": "^10.40.2",
     "unexpected-eventemitter": "^1.1.3",
     "unexpected-sinon": "^10.11.2",