Add rule require-throws

src/index.js

@@ -34,6 +34,7 @@ import requireReturns from './rules/requireReturns';
 import requireReturnsCheck from './rules/requireReturnsCheck';
 import requireReturnsDescription from './rules/requireReturnsDescription';
 import requireReturnsType from './rules/requireReturnsType';
+import requireThrows from './rules/requireThrows';
 import validTypes from './rules/validTypes';
 import requireJsdoc from './rules/requireJsdoc';
 
@@ -119,6 +120,7 @@ export default {
     'require-returns-check': requireReturnsCheck,
     'require-returns-description': requireReturnsDescription,
     'require-returns-type': requireReturnsType,
+    'require-throws': requireThrows,
     'valid-types': validTypes,
   },
 };

src/iterateJsdoc.js

@@ -325,6 +325,10 @@ const getUtils = (
     return jsdocUtils.hasReturnValue(node);
   };
 
+  utils.hasThrowValue = () => {
+    return jsdocUtils.hasThrowValue(node);
+  };
+
   utils.isAsync = () => {
     return node.async;
   };

src/jsdocUtils.js

@@ -556,6 +556,61 @@ const hasReturnValue = (node) => {
   }
 };
 
+/**
+ * Checks if a node has a throws statement.
+ *
+ * @param {object} node
+ * @returns {boolean}
+ */
+const hasThrowValue = (node) => {
+  if (!node) {
+    return false;
+  }
+  switch (node.type) {
+  case 'FunctionExpression':
+  case 'FunctionDeclaration':
+  case 'ArrowFunctionExpression': {
+    return node.expression || hasThrowValue(node.body);
+  }
+  case 'BlockStatement': {
+    return node.body.some((bodyNode) => {
+      return bodyNode.type !== 'FunctionDeclaration' && hasThrowValue(bodyNode);
+    });
+  }
+  case 'WhileStatement':
+  case 'DoWhileStatement':
+  case 'ForStatement':
+  case 'ForInStatement':
+  case 'ForOfStatement':
+  case 'WithStatement': {
+    return hasThrowValue(node.body);
+  }
+  case 'IfStatement': {
+    return hasThrowValue(node.consequent) || hasThrowValue(node.alternate);
+  }
+
+  // We only consider it to throw an error if the catch or finally blocks throw an error.
+  case 'TryStatement': {
+    return hasThrowValue(node.handler && node.handler.body) ||
+        hasThrowValue(node.finalizer);
+  }
+  case 'SwitchStatement': {
+    return node.cases.some(
+      (someCase) => {
+        return someCase.consequent.some(hasThrowValue);
+      },
+    );
+  }
+  case 'ThrowStatement': {
+    return true;
+  }
+
+  default: {
+    return false;
+  }
+  }
+};
+
 /** @param {string} tag */
 /*
 const isInlineTag = (tag) => {
@@ -668,6 +723,7 @@ export default {
   hasDefinedTypeReturnTag,
   hasReturnValue,
   hasTag,
+  hasThrowValue,
   isNamepathDefiningTag,
   isValidTag,
   parseClosureTemplateTag,

src/rules/requireThrows.js

@@ -0,0 +1,82 @@
+import iterateJsdoc from '../iterateJsdoc';
+
+/**
+ * We can skip checking for a throws value, in case the documentation is inherited
+ * or the method is either a constructor or an abstract method.
+ *
+ * @param {*} 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 necessary to document that they throw an error.
+    'abstract',
+    'virtual',
+  ]) ||
+    utils.avoidDocs();
+};
+
+export default iterateJsdoc(({
+  report,
+  utils,
+}) => {
+  // A preflight check. We do not need to run a deep check for abstract functions.
+  if (canSkip(utils)) {
+    return;
+  }
+
+  const tagName = utils.getPreferredTagName({tagName: 'throws'});
+  if (!tagName) {
+    return;
+  }
+
+  const tags = utils.getTags(tagName);
+  const iteratingFunction = utils.isIteratingFunction();
+
+  // In case the code returns something, we expect a return value in JSDoc.
+  const [tag] = tags;
+  const missingThrowsTag = typeof tag === 'undefined' || tag === null;
+
+  const shouldReport = () => {
+    if (!missingThrowsTag) {
+      return false;
+    }
+
+    return iteratingFunction && utils.hasThrowValue();
+  };
+
+  if (shouldReport()) {
+    report(`Missing JSDoc @${tagName} declaration.`);
+  }
+}, {
+  contextDefaults: true,
+  meta: {
+    schema: [
+      {
+        additionalProperties: false,
+        properties: {
+          contexts: {
+            items: {
+              type: 'string',
+            },
+            type: 'array',
+          },
+          exemptedBy: {
+            items: {
+              type: 'string',
+            },
+            type: 'array',
+          },
+        },
+        type: 'object',
+      },
+    ],
+    type: 'suggestion',
+  },
+});

test/rules/assertions/requireThrows.js

@@ -0,0 +1,204 @@
+export default {
+  invalid: [
+    {
+      code: `
+          /**
+           *
+           */
+          function quux (foo) {
+            throw new Error('err')
+          }
+      `,
+      errors: [
+        {
+          line: 2,
+          message: 'Missing JSDoc @throws declaration.',
+        },
+      ],
+    },
+    {
+      code: `
+          /**
+           *
+           */
+          function quux (foo) {
+            while(true) {
+              throw new Error('err')
+            }
+          }
+      `,
+      errors: [
+        {
+          line: 2,
+          message: 'Missing JSDoc @throws declaration.',
+        },
+      ],
+    },
+    {
+      code: `
+          /**
+           *
+           */
+          function quux (foo) {
+            if (true) {
+              throw new Error('err')
+            }
+          }
+      `,
+      errors: [
+        {
+          line: 2,
+          message: 'Missing JSDoc @throws declaration.',
+        },
+      ],
+    },
+    {
+      code: `
+          /**
+           *
+           */
+          function quux (foo) {
+            if (false) {
+              // do nothing
+            } else {
+              throw new Error('err')
+            }
+          }
+      `,
+      errors: [
+        {
+          line: 2,
+          message: 'Missing JSDoc @throws declaration.',
+        },
+      ],
+    },
+    {
+      code: `
+          /**
+           *
+           */
+          function quux (foo) {
+            try {
+              throw new Error('err')
+            } catch(e) {
+              throw new Error(e.message)
+            }
+          }
+      `,
+      errors: [
+        {
+          line: 2,
+          message: 'Missing JSDoc @throws declaration.',
+        },
+      ],
+    },
+    {
+      code: `
+          /**
+           *
+           */
+          function quux (foo) {
+            try {
+              // do nothing
+            } finally {
+              throw new Error(e.message)
+            }
+          }
+      `,
+      errors: [
+        {
+          line: 2,
+          message: 'Missing JSDoc @throws declaration.',
+        },
+      ],
+    },
+    {
+      code: `
+          /**
+           *
+           */
+          function quux (foo) {
+            const a = 'b'
+            switch(a) {
+              case 'b':
+                throw new Error('err')
+            }
+          }
+      `,
+      errors: [
+        {
+          line: 2,
+          message: 'Missing JSDoc @throws declaration.',
+        },
+      ],
+    },
+  ],
+  valid: [
+    {
+      code: `
+          /**
+           * @throws An error.
+           */
+          function quux () {
+            throw new Error('err')
+          }
+      `,
+    },
+    {
+      code: `
+          /**
+           *
+           */
+          function quux (foo) {
+            try {
+              throw new Error('err')
+            } catch(e) {}
+          }
+      `,
+    },
+    {
+      code: `
+          /**
+           * @inheritdoc
+           */
+          function quux (foo) {
+            throw new Error('err')
+          }
+      `,
+    },
+    {
+      code: `
+          /**
+           * @abstract
+           */
+          function quux (foo) {
+            throw new Error('err')
+          }
+      `,
+    },
+    {
+      code: `
+          /**
+           *
+           */
+          function quux (foo) {
+          }
+      `,
+    },
+    {
+      code: `
+          /**
+           * @type {MyCallback}
+           */
+          function quux () {
+            throw new Error('err')
+          }
+      `,
+      options: [
+        {
+          exemptedBy: ['type'],
+        },
+      ],
+    },
+  ],
+};

test/rules/index.js

@@ -44,6 +44,7 @@ const ruleTester = new RuleTester();
   'require-returns-check',
   'require-returns-description',
   'require-returns-type',
+  'require-throws',
   'valid-types',
 ]).forEach((ruleName) => {
   const rule = config.rules[ruleName];