fix: allow typedef returns that may be void

[StantonMatt]

Fixes #1390.

This updates require-returns-check so a @returns tag whose type resolves to a same-file @typedef is treated as potentially undefined when that typedef includes void or undefined. That prevents the rule from reporting a missing return expression for patterns like:

/**
 * @typedef {{ loadTime: number; runTime: number; totalTime: number } | void} PerfResult
 * @returns {PerfResult}
 */

I also added generated docs coverage for the new valid case.

Verification:

• pnpm run test-index --rule require-returns-check
• pnpm exec eslint src/rules/requireReturnsCheck.js test/rules/assertions/requireReturnsCheck.js
• pnpm run tsc
• pnpm run check-docs
• pnpm run build
• git diff --check

[brettz9]

Thank you for this PR. However, I'm not sure how common it is that the typedef would be defined on the block itself. I was hoping any PR could search the document for typedefs (as does jsdoc/no-undefined-types. That may get complicated, but it would catch other typedefs within the same document...

[StantonMatt]

Updated in 99dfe01b. The rule now scans the source file's JSDoc comments for typedef-defining tags using the same filtering shape as no-undefined-types, so typedefs before or after the function comment are considered.

I added coverage for separate-block typedefs before and after the function, plus a non-void typedef case that still reports. Local checks: pnpm build, pnpm lint, and pnpm test (3118 passing). The fork workflow was still approval-gated when I pushed the update.

[brettz9]

Thanks! This looks good, but may take me maybe a few days to get to it to review.

[brettz9]

Looking good.

See the comments. My example code needs to be tested--just what I think it will probably look like.

[StantonMatt]

Superseded by the later 839ae3ef update below; editing this earlier note to avoid leaving a stale head SHA in the thread. The current PR head is 839ae3ef, and the GitHub workflow is green across Build, Lint, and the three Node/ESLint test jobs.

[StantonMatt]

Updated in 839ae3ef.

• moved the document-wide namepath/typedef scan into jsdocUtils and reused it from no-undefined-types
• changed require-returns-check to parse/traverse the return type so typedef references in unions, return-level void/undefined, and parenthesized cases are handled
• dropped the explicit TypeScript settings from the new fixtures and synced the generated docs examples

Local checks: focused require-returns-check and no-undefined-types suites, pnpm test, pnpm run build, and pnpm run lint.

GitHub checks are also green on the pushed head: Build, Lint, and the three Test matrix jobs.

[brettz9]

Looking very good to me, thanks!

[github-actions]

🎉 This PR is included in version 63.0.2 🎉

The release is available on:

• GitHub release
• npm package (@latest dist-tag)

Your semantic-release bot 📦🚀