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

[JoshuaKGoldberg]

PR Checklist

• [x] Addresses an existing open issue: fixes #5347
• [x] That issue was marked as status: accepting prs
• [x] Steps in CONTRIBUTING.md were taken

Overview

Creates a new lib/types.d.ts and moves every @callback and @typedef {Object} to it. A new tsconfig.json & tsc script can be run to verify that the types in that file can be type checked.

Does not yet validate types in .js files (#4154, #4228). You can preview those by switching tsconfig.json's allowJs to checkJs. I made sure there are no more "Cannot find name ..." errors but fixing the rest of the ~650+ will be a lot more work. Much of the code will be much easier to get type-safe when it's ported from manual function prototypes to classes (#5025). I also held off porting all the info from @types/mocha there to keep the changes minimal.

Does not yet try to pull in types or descriptions from @types/mocha. That would be a bigger change too.

Moves error constants from errors.js to error-constants.js to avoid circular dependency errors.

[voxpelli]

Why everything in one large .d.ts?

Also: You can try to use (still sometimes buggy) the @import to import instead of using typedef, eg:

/** @import { Foo } from './bar.js' */

[JoshuaKGoldberg]

Why everything in one large .d.ts?

I don't have preferences on where to organize types, since this feels like a transient "we'll clean things up over time anyway" kind of situation to me 😄. Do you have a preference for where things should go?

[JoshuaKGoldberg]

ping @voxpelli did you mean for https://github.com/mochajs/mocha/pull/5351#issuecomment-2852296087 to be a full review? I'm not clear on whether you're requesting changes and waiting on me, or just posting thoughts pending a full review?

[voxpelli]

@JoshuaKGoldberg Posting thoughts pending a full review, thanks for pinging and asking 🙏

[mark-wiemer]

@JoshuaKGoldberg I'm good to merge this if you are