@depup/eslint-plugin-jsdoc 62.8.0-depup.0

package/src/rules/requireReturns.js

@@ -0,0 +1,291 @@
+import exportParser from '../exportParser.js';
+import iterateJsdoc from '../iterateJsdoc.js';
+
+/**
+ * We can skip checking for a return value, in case the documentation is inherited
+ * or the method is either a constructor or an abstract method.
+ *
+ * In either of these cases the return value is optional or not defined.
+ * @param {import('../iterateJsdoc.js').Utils} utils
+ *   a reference to the utils which are used to probe if a tag is present or not.
+ * @returns {boolean}
+ *   true in case deep checking can be skipped; otherwise false.
+ */
+const canSkip = (utils) => {
+  return utils.hasATag([
+    // inheritdoc implies that all documentation is inherited
+    // see https://jsdoc.app/tags-inheritdoc.html
+    //
+    // Abstract methods are by definition incomplete,
+    // so it is not an error if it declares a return value but does not implement it.
+    'abstract',
+    'virtual',
+
+    // Constructors do not have a return value by definition (https://jsdoc.app/tags-class.html)
+    // So we can bail out here, too.
+    'class',
+    'constructor',
+
+    // Return type is specified by type in @type
+    'type',
+
+    // This seems to imply a class as well
+    'interface',
+  ]) ||
+    utils.avoidDocs();
+};
+
+export default iterateJsdoc(({
+  context,
+  info: {
+    comment,
+  },
+  node,
+  report,
+  settings,
+  utils,
+}) => {
+  const {
+    contexts,
+    enableFixer = false,
+    forceRequireReturn = false,
+    forceReturnsWithAsync = false,
+    publicOnly = false,
+  } = context.options[0] || {};
+
+  // A preflight check. We do not need to run a deep check
+  // in case the @returns comment is optional or undefined.
+  if (canSkip(utils)) {
+    return;
+  }
+
+  /** @type {boolean|undefined} */
+  let forceRequireReturnContext;
+  if (contexts) {
+    const {
+      foundContext,
+    } = utils.findContext(contexts, comment);
+    if (typeof foundContext === 'object') {
+      forceRequireReturnContext = foundContext.forceRequireReturn;
+    }
+  }
+
+  const tagName = /** @type {string} */ (utils.getPreferredTagName({
+    tagName: 'returns',
+  }));
+  if (!tagName) {
+    return;
+  }
+
+  const tags = utils.getTags(tagName);
+
+  if (tags.length > 1) {
+    report(`Found more than one @${tagName} declaration.`);
+  }
+
+  const iteratingFunction = utils.isIteratingFunction();
+
+  // In case the code returns something, we expect a return value in JSDoc.
+  const [
+    tag,
+  ] = tags;
+  const missingReturnTag = typeof tag === 'undefined' || tag === null;
+
+  const shouldReport = () => {
+    if (!missingReturnTag) {
+      return false;
+    }
+
+    if (publicOnly) {
+      /** @type {import('./requireJsdoc.js').RequireJsdocOpts} */
+      const opt = {
+        ancestorsOnly: Boolean(publicOnly?.ancestorsOnly ?? false),
+        esm: Boolean(publicOnly?.esm ?? true),
+        initModuleExports: Boolean(publicOnly?.cjs ?? true),
+        initWindow: Boolean(publicOnly?.window ?? false),
+      };
+      /* c8 ignore next -- Fallback to deprecated method */
+      const {
+        // @ts-expect-error ESLint < 10
+        sourceCode = context.getSourceCode(),
+      } = context;
+      const exported = exportParser.isUncommentedExport(
+        /** @type {import('eslint').Rule.Node} */ (node), sourceCode, opt, settings,
+      );
+
+      if (!exported) {
+        return false;
+      }
+    }
+
+    if ((forceRequireReturn || forceRequireReturnContext) && (
+      iteratingFunction || utils.isVirtualFunction()
+    )) {
+      return true;
+    }
+
+    const isAsync = !iteratingFunction && utils.hasTag('async') ||
+      iteratingFunction && utils.isAsync();
+
+    if (forceReturnsWithAsync && isAsync) {
+      return true;
+    }
+
+    return iteratingFunction && utils.hasValueOrExecutorHasNonEmptyResolveValue(
+      forceReturnsWithAsync,
+    );
+  };
+
+  if (shouldReport()) {
+    utils.reportJSDoc(`Missing JSDoc @${tagName} declaration.`, null, enableFixer ? () => {
+      utils.addTag(tagName);
+    } : null);
+  }
+}, {
+  contextDefaults: true,
+  meta: {
+    docs: {
+      description: 'Requires that returns are documented with `@returns`.',
+      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-returns.md#repos-sticky-header',
+    },
+    fixable: 'code',
+    schema: [
+      {
+        additionalProperties: false,
+        properties: {
+          checkConstructors: {
+            default: false,
+            description: `A value indicating whether \`constructor\`s should
+be checked for \`@returns\` tags. Defaults to \`false\`.`,
+            type: 'boolean',
+          },
+          checkGetters: {
+            default: true,
+            description: `Boolean to determine whether getter methods should
+be checked for \`@returns\` tags. Defaults to \`true\`.`,
+            type: 'boolean',
+          },
+          contexts: {
+            description: `Set this to an array of strings representing the AST context
+(or objects with optional \`context\` and \`comment\` properties) where you wish
+the rule to be applied.
+
+\`context\` defaults to \`any\` and \`comment\` defaults to no specific comment context.
+
+Overrides the default contexts (\`ArrowFunctionExpression\`, \`FunctionDeclaration\`,
+\`FunctionExpression\`). Set to \`"any"\` if you want
+the rule to apply to any JSDoc block throughout your files (as is necessary
+for finding function blocks not attached to a function declaration or
+expression, i.e., \`@callback\` or \`@function\` (or its aliases \`@func\` or
+\`@method\`) (including those associated with an \`@interface\`). This
+rule will only apply on non-default contexts when there is such a tag
+present and the \`forceRequireReturn\` option is set or if the
+\`forceReturnsWithAsync\` option is set with a present \`@async\` tag
+(since we are not checking against the actual \`return\` values in these
+cases).`,
+            items: {
+              anyOf: [
+                {
+                  type: 'string',
+                },
+                {
+                  additionalProperties: false,
+                  properties: {
+                    comment: {
+                      type: 'string',
+                    },
+                    context: {
+                      type: 'string',
+                    },
+                    forceRequireReturn: {
+                      type: 'boolean',
+                    },
+                  },
+                  type: 'object',
+                },
+              ],
+            },
+            type: 'array',
+          },
+          enableFixer: {
+            description: `Whether to enable the fixer to add a blank \`@returns\`.
+Defaults to \`false\`.`,
+            type: 'boolean',
+          },
+          exemptedBy: {
+            description: `Array of tags (e.g., \`['type']\`) whose presence on the
+document block avoids the need for a \`@returns\`. Defaults to an array
+with \`inheritdoc\`. If you set this array, it will overwrite the default,
+so be sure to add back \`inheritdoc\` if you wish its presence to cause
+exemption of the rule.`,
+            items: {
+              type: 'string',
+            },
+            type: 'array',
+          },
+          forceRequireReturn: {
+            default: false,
+            description: `Set to \`true\` to always insist on
+\`@returns\` documentation regardless of implicit or explicit \`return\`'s
+in the function. May be desired to flag that a project is aware of an
+\`undefined\`/\`void\` return. Defaults to \`false\`.`,
+            type: 'boolean',
+          },
+          forceReturnsWithAsync: {
+            default: false,
+            description: `By default \`async\` functions that do not explicitly
+return a value pass this rule as an \`async\` function will always return a
+\`Promise\`, even if the \`Promise\` resolves to void. You can force all
+\`async\` functions (including ones with an explicit \`Promise\` but no
+detected non-\`undefined\` \`resolve\` value) to require \`@return\`
+documentation by setting \`forceReturnsWithAsync\` to \`true\` on the options
+object. This may be useful for flagging that there has been consideration
+of return type. Defaults to \`false\`.`,
+            type: 'boolean',
+          },
+          publicOnly: {
+            description: `This option will insist that missing \`@returns\` are only reported for
+function bodies / class declarations that are exported from the module.
+May be a boolean or object. If set to \`true\`, the defaults below will be
+used. If unset, \`@returns\` reporting will not be limited to exports.
+
+This object supports the following optional boolean keys (\`false\` unless
+otherwise noted):
+
+- \`ancestorsOnly\` - Optimization to only check node ancestors to check if node is exported
+- \`esm\` - ESM exports are checked for \`@returns\` JSDoc comments (Defaults to \`true\`)
+- \`cjs\` - CommonJS exports are checked for \`@returns\` JSDoc comments  (Defaults to \`true\`)
+- \`window\` - Window global exports are checked for \`@returns\` JSDoc comments`,
+            oneOf: [
+              {
+                default: false,
+                type: 'boolean',
+              },
+              {
+                additionalProperties: false,
+                default: {},
+                properties: {
+                  ancestorsOnly: {
+                    type: 'boolean',
+                  },
+                  cjs: {
+                    type: 'boolean',
+                  },
+                  esm: {
+                    type: 'boolean',
+                  },
+                  window: {
+                    type: 'boolean',
+                  },
+                },
+                type: 'object',
+              },
+            ],
+          },
+        },
+        type: 'object',
+      },
+    ],
+    type: 'suggestion',
+  },
+});

package/src/rules/requireReturnsCheck.js

@@ -0,0 +1,180 @@
+import iterateJsdoc from '../iterateJsdoc.js';
+import {
+  strictNativeTypes,
+} from '../jsdocUtils.js';
+
+/**
+ * @param {import('../iterateJsdoc.js').Utils} utils
+ * @param {import('../iterateJsdoc.js').Settings} settings
+ * @returns {boolean}
+ */
+const canSkip = (utils, settings) => {
+  const voidingTags = [
+    // An abstract function is by definition incomplete
+    // so it is perfectly fine if a return is documented but
+    // not present within the function.
+    // A subclass may inherit the doc and implement the
+    // missing return.
+    'abstract',
+    'virtual',
+
+    // A constructor function returns `this` by default, so may be `@returns`
+    //   tag indicating this but no explicit return
+    'class',
+    'constructor',
+    'interface',
+  ];
+
+  if (settings.mode === 'closure') {
+    // Structural Interface in GCC terms, equivalent to @interface tag as far as this rule is concerned
+    voidingTags.push('record');
+  }
+
+  return utils.hasATag(voidingTags) ||
+    utils.isConstructor() ||
+    utils.classHasTag('interface') ||
+    settings.mode === 'closure' && utils.classHasTag('record');
+};
+
+export default iterateJsdoc(({
+  context,
+  node,
+  report,
+  settings,
+  utils,
+}) => {
+  const {
+    exemptAsync = true,
+    exemptGenerators = settings.mode === 'typescript',
+    noNativeTypes = true,
+    reportMissingReturnForUndefinedTypes = false,
+  } = context.options[0] || {};
+
+  if (canSkip(utils, settings)) {
+    return;
+  }
+
+  const isAsync = utils.isAsync();
+  if (exemptAsync && isAsync) {
+    return;
+  }
+
+  const tagName = /** @type {string} */ (utils.getPreferredTagName({
+    tagName: 'returns',
+  }));
+  if (!tagName) {
+    return;
+  }
+
+  const tags = utils.getTags(tagName);
+
+  if (tags.length === 0) {
+    return;
+  }
+
+  if (tags.length > 1) {
+    report(`Found more than one @${tagName} declaration.`);
+
+    return;
+  }
+
+  const [
+    tag,
+  ] = tags;
+
+  const type = tag.type.trim();
+
+  // https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html#assertion-functions
+  if (/asserts\s/v.test(type)) {
+    return;
+  }
+
+  const returnNever = type === 'never';
+
+  if (returnNever && utils.hasValueOrExecutorHasNonEmptyResolveValue(false)) {
+    report(`JSDoc @${tagName} declaration set with "never" but return expression is present in function.`);
+
+    return;
+  }
+
+  if (noNativeTypes && isAsync && strictNativeTypes.includes(type)) {
+    report('Function is async or otherwise returns a Promise but the return type is a native type.');
+    return;
+  }
+
+  // In case a return value is declared in JSDoc, we also expect one in the code.
+  if (
+    !returnNever &&
+    (
+      reportMissingReturnForUndefinedTypes ||
+      !utils.mayBeUndefinedTypeTag(tag)
+    ) &&
+    (tag.type === '' && !utils.hasValueOrExecutorHasNonEmptyResolveValue(
+      exemptAsync,
+    ) ||
+    tag.type !== '' && !utils.hasValueOrExecutorHasNonEmptyResolveValue(
+      exemptAsync,
+      true,
+    )) &&
+    Boolean(
+      !exemptGenerators || !node ||
+      !('generator' in /** @type {import('../iterateJsdoc.js').Node} */ (node)) ||
+      !(/** @type {import('@typescript-eslint/types').TSESTree.FunctionDeclaration} */ (node)).generator,
+    )
+  ) {
+    report(`JSDoc @${tagName} declaration present but return expression not available in function.`);
+  }
+}, {
+  meta: {
+    docs: {
+      description: 'Requires a return statement in function body if a `@returns` tag is specified in JSDoc comment(and reports if multiple `@returns` tags are present).',
+      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-returns-check.md#repos-sticky-header',
+    },
+    schema: [
+      {
+        additionalProperties: false,
+        properties: {
+          exemptAsync: {
+            default: true,
+            description: `By default, functions which return a \`Promise\` that are not
+detected as resolving with a non-\`undefined\` value and \`async\` functions
+(even ones that do not explicitly return a value, as these are returning a
+\`Promise\` implicitly) will be exempted from reporting by this rule.
+If you wish to insist that only \`Promise\`'s which resolve to
+non-\`undefined\` values or \`async\` functions with explicit \`return\`'s will
+be exempted from reporting (i.e., that \`async\` functions can be reported
+if they lack an explicit (non-\`undefined\`) \`return\` when a \`@returns\` is
+present), you can set \`exemptAsync\` to \`false\` on the options object.`,
+            type: 'boolean',
+          },
+          exemptGenerators: {
+            description: `Because a generator might be labeled as having a
+\`IterableIterator\` \`@returns\` value (along with an iterator type
+corresponding to the type of any \`yield\` statements), projects might wish to
+leverage \`@returns\` in generators even without a \`return\` statement. This
+option is therefore \`true\` by default in \`typescript\` mode (in "jsdoc" mode,
+one might be more likely to take advantage of \`@yields\`). Set it to \`false\`
+if you wish for a missing \`return\` to be flagged regardless.`,
+            type: 'boolean',
+          },
+          noNativeTypes: {
+            description: `Whether to check that async functions do not
+indicate they return non-native types. Defaults to \`true\`.`,
+            type: 'boolean',
+          },
+          reportMissingReturnForUndefinedTypes: {
+            default: false,
+            description: `If \`true\` and no return or
+resolve value is found, this setting will even insist that reporting occur
+with \`void\` or \`undefined\` (including as an indicated \`Promise\` type).
+Unlike \`require-returns\`, with this option in the rule, one can
+*discourage* the labeling of \`undefined\` types. Defaults to \`false\`.`,
+            type: 'boolean',
+          },
+        },
+        type: 'object',
+      },
+    ],
+    type: 'suggestion',
+  },
+});

package/src/rules/requireReturnsDescription.js

@@ -0,0 +1,73 @@
+import iterateJsdoc from '../iterateJsdoc.js';
+
+export default iterateJsdoc(({
+  report,
+  utils,
+}) => {
+  utils.forEachPreferredTag('returns', (jsdocTag, targetTagName) => {
+    const type = jsdocTag.type && jsdocTag.type.trim();
+
+    if ([
+      'Promise<undefined>', 'Promise<void>', 'undefined', 'void',
+    ].includes(type)) {
+      return;
+    }
+
+    if (!jsdocTag.description.trim()) {
+      report(`Missing JSDoc @${targetTagName} description.`, null, jsdocTag);
+    }
+  });
+}, {
+  contextDefaults: true,
+  meta: {
+    docs: {
+      description: 'Requires that the `@returns` tag has a `description` value (not including `void`/`undefined` type returns).',
+      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-returns-description.md#repos-sticky-header',
+    },
+    schema: [
+      {
+        additionalProperties: false,
+        properties: {
+          contexts: {
+            description: `Set this to an array of strings representing the AST context (or an object with
+optional \`context\` and \`comment\` properties) where you wish the rule to be applied.
+
+\`context\` defaults to \`any\` and \`comment\` defaults to no specific comment context.
+
+Overrides the default contexts (\`ArrowFunctionExpression\`, \`FunctionDeclaration\`,
+\`FunctionExpression\`). Set to \`"any"\` if you want
+the rule to apply to any JSDoc block throughout your files (as is necessary
+for finding function blocks not attached to a function declaration or
+expression, i.e., \`@callback\` or \`@function\` (or its aliases \`@func\` or
+\`@method\`) (including those associated with an \`@interface\`).
+
+See the ["AST and Selectors"](../#advanced-ast-and-selectors)
+section of our Advanced docs for more on the expected format.`,
+            items: {
+              anyOf: [
+                {
+                  type: 'string',
+                },
+                {
+                  additionalProperties: false,
+                  properties: {
+                    comment: {
+                      type: 'string',
+                    },
+                    context: {
+                      type: 'string',
+                    },
+                  },
+                  type: 'object',
+                },
+              ],
+            },
+            type: 'array',
+          },
+        },
+        type: 'object',
+      },
+    ],
+    type: 'suggestion',
+  },
+});

package/src/rules/requireReturnsType.js

@@ -0,0 +1,65 @@
+import iterateJsdoc from '../iterateJsdoc.js';
+
+export default iterateJsdoc(({
+  report,
+  utils,
+}) => {
+  utils.forEachPreferredTag('returns', (jsdocTag, targetTagName) => {
+    if (!jsdocTag.type) {
+      report(`Missing JSDoc @${targetTagName} type.`, null, jsdocTag);
+    }
+  });
+}, {
+  contextDefaults: true,
+  meta: {
+    docs: {
+      description: 'Requires that `@returns` tag has type value (in curly brackets).',
+      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-returns-type.md#repos-sticky-header',
+    },
+    schema: [
+      {
+        additionalProperties: false,
+        properties: {
+          contexts: {
+            description: `Set this to an array of strings representing the AST context (or an object with
+optional \`context\` and \`comment\` properties) where you wish the rule to be applied.
+
+\`context\` defaults to \`any\` and \`comment\` defaults to no specific comment context.
+
+Overrides the default contexts (\`ArrowFunctionExpression\`, \`FunctionDeclaration\`,
+\`FunctionExpression\`). Set to \`"any"\` if you want
+the rule to apply to any JSDoc block throughout your files (as is necessary
+for finding function blocks not attached to a function declaration or
+expression, i.e., \`@callback\` or \`@function\` (or its aliases \`@func\` or
+\`@method\`) (including those associated with an \`@interface\`).
+
+See the ["AST and Selectors"](../#advanced-ast-and-selectors)
+section of our Advanced docs for more on the expected format.`,
+            items: {
+              anyOf: [
+                {
+                  type: 'string',
+                },
+                {
+                  additionalProperties: false,
+                  properties: {
+                    comment: {
+                      type: 'string',
+                    },
+                    context: {
+                      type: 'string',
+                    },
+                  },
+                  type: 'object',
+                },
+              ],
+            },
+            type: 'array',
+          },
+        },
+        type: 'object',
+      },
+    ],
+    type: 'suggestion',
+  },
+});

package/src/rules/requireTags.js

@@ -0,0 +1,85 @@
+import {
+  buildForbidRuleDefinition,
+} from '../buildForbidRuleDefinition.js';
+
+export default buildForbidRuleDefinition({
+  description: 'Requires tags be present, optionally for specific contexts',
+  getContexts (context, report) {
+    // Transformed options to this option in `modifyContext`:
+    if (!context.options[0].contexts) {
+      report('Rule `require-tags` is missing a `tags` option.');
+      return false;
+    }
+
+    const {
+      contexts,
+    } = context.options[0];
+
+    return contexts;
+  },
+  modifyContext (context) {
+    const tags = /** @type {(string|{tag: string, context: string})[]} */ (
+      context.options?.[0]?.tags
+    );
+
+    const cntxts = tags?.map((tag) => {
+      const tagName = typeof tag === 'string' ? tag : tag.tag;
+      return {
+        comment: `JsdocBlock:not(*:has(JsdocTag[tag=${
+          tagName
+        }]))`,
+        context: typeof tag === 'string' ? 'any' : tag.context,
+        message: `Missing required tag "${tagName}"`,
+      };
+    });
+
+    // Reproduce context object with our own `contexts`
+    const propertyDescriptors = Object.getOwnPropertyDescriptors(context);
+    return Object.create(
+      Object.getPrototypeOf(context),
+      {
+        ...propertyDescriptors,
+        options: {
+          ...propertyDescriptors.options,
+          value: [
+            {
+              contexts: cntxts,
+            },
+          ],
+        },
+      },
+    );
+  },
+  schema: [
+    {
+      additionalProperties: false,
+      properties: {
+        tags: {
+          description: `May be an array of either strings or objects with
+a string \`tag\` property and \`context\` string property.`,
+          items: {
+            anyOf: [
+              {
+                type: 'string',
+              },
+              {
+                properties: {
+                  context: {
+                    type: 'string',
+                  },
+                  tag: {
+                    type: 'string',
+                  },
+                },
+                type: 'object',
+              },
+            ],
+          },
+          type: 'array',
+        },
+      },
+      type: 'object',
+    },
+  ],
+  url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-tags.md#repos-sticky-header',
+});