🛠️ Repo: Bump jsdoc from 3 to 4

[JoshuaKGoldberg]

Tooling Suggestion Checklist

• I have tried restarting my IDE and the issue persists.
• I have pulled the latest main branch of the repository.
• I have read and agree to Mocha's Code of Conduct and Contributing Guidelines
• I have searched for related issues and issues with the faq label, but none matched my issue.
• I want to provide a PR to resolve this

Overview

Mocha has a devDependency right now on a 4-year-old version of jsdoc:

mocha/package.json

Line 145 in b2985b3

"jsdoc": "^3.6.7",

This isn't a problem on its own. jsdoc@3 works as-is. But it pulls in old dependencies that bloat our local node_modules size. For example, in #5484, we see it pulling in strip-json-comments@3:

$ npm ls strip-json-comments@3
mocha@11.7.4 /Users/josh/repos/mocha
├─┬ eslint@8.56.0
│ └─┬ @eslint/eslintrc@2.1.4
│   └── strip-json-comments@3.1.1
├─┬ jsdoc@3.6.11
│ └── strip-json-comments@3.1.1
└─┬ markdownlint-cli@0.30.0
  └─┬ run-con@1.2.11
    └── strip-json-comments@3.1.1

I think it'd be a good idea in general to bump it to the latest major version.

Additional Info

In theory it'd be nice to automatically upgrade all devDependencies. #5055 is blocked for now: #5055 (comment).

JSDoc only recently started using semantic versioning, so there may be difficult-to-find breaking changes: https://github.com/jsdoc/jsdoc/blob/main/CHANGES.md

💖

[JoshuaKGoldberg]

😩 Blocked on removing @mocha/docdash or updating its dependencies:

$ npm i
npm error code ERESOLVE
npm error ERESOLVE could not resolve
npm error
npm error While resolving: @mocha/docdash@4.0.1
npm error Found: jsdoc@4.0.5
npm error node_modules/jsdoc
npm error   dev jsdoc@"^4.0.5" from the root project
npm error   peer jsdoc@"*" from jsdoc-ts-utils@6.0.0
npm error   node_modules/jsdoc-ts-utils
npm error     dev jsdoc-ts-utils@"^6.0.0" from the root project
npm error
npm error Could not resolve dependency:
npm error peer jsdoc@"^3.6.7" from @mocha/docdash@4.0.1
npm error node_modules/@mocha/docdash
npm error   dev @mocha/docdash@"^4.0.1" from the root project
npm error
npm error Conflicting peer dependency: jsdoc@3.6.11
npm error node_modules/jsdoc
npm error   peer jsdoc@"^3.6.7" from @mocha/docdash@4.0.1
npm error   node_modules/@mocha/docdash
npm error     dev @mocha/docdash@"^4.0.1" from the root project
npm error

We plan on getting rid of @mocha/docdash by migrating from the old site to Astro.

[mark-wiemer]

I think we're ready, opened #5576, its sub-issue #5577 will fully unblock this one