require-returns-check doesn't support TypeScript assertion functions

[turadg]

The TypeScript assertion functions is not recognized by the require-returns-check rule.

Expected behavior

No errors from this plugin.

Actual behavior

Rule https://github.com/gajus/eslint-plugin-jsdoc#eslint-plugin-jsdoc-rules-require-returns-check reports:
JSDoc @returns declaration present but return expression not available in function.

ESLint sample

This code narrows the type of maybeNum to number:

/** @type {number | string | undefined} */
let maybeNum;
/**
 * @param {unknown} val
 * @returns { asserts val is number }
 */
function assertNumber(val) {
  assert(typeof val === 'number');
}
assertNumber(maybeNum);
maybeNum.toFixed;

Environment

• Node version: v18.7.0
• ESLint version v7.32.0
• eslint-plugin-jsdoc version: 39.3.3

[brettz9]

These type issues should be reported to https://github.com/jsdoc-type-pratt-parser/jsdoc-type-pratt-parser . It is really a dupe of jsdoc-type-pratt-parser/jsdoc-type-pratt-parser#96 , though the project owner has expressed openness to the filing of separate issues for particularly desired features, so if you want this faster, I'd suggest filing over there. I'll close the issue here as we tend to update quickly upon changes to jsdoc-type-pratt-parser.

[turadg]

I don't think this is a dupe. The issue linked is about syntax errors. E.g.,

   77:0  warning  Syntax error in type: asserts specimen is bigint                                                                                                                                                                           jsdoc/valid-types

In this report, there are no syntax errors. The jsdoc/require-returns-check is issuing a warning, "JSDoc @returns declaration present but return expression not available in function" because there is no return expression.

I think the solution is for the plugin to not expect a return expression when the return type is an assertion function.

For anyone else encountering this, a workaround my colleague found is to put a newline between the jsdoc and the function it describes:

TypeScript will still associate it but ESlint will not. Of course you lose the linting.