feat(required-tags): add new rule; fixes #1235

Author: brettz9

.README/rules/required-tags.md

@@ -0,0 +1,23 @@
+# `required-tags`
+
+Requires tags be present, optionally for specific contexts.
+
+## Options
+
+{"gitdown": "options"}
+
+|||
+|---|---|
+|Context|everywhere|
+|Tags|(Any)|
+|Recommended|false|
+|Settings||
+|Options|`tags`|
+
+## Failing examples
+
+<!-- assertions-failing requiredTags -->
+
+## Passing examples
+
+<!-- assertions-passing requiredTags -->

README.md

@@ -487,6 +487,7 @@ non-default-recommended fixer).
 |:heavy_check_mark:|| [require-yields-check](./docs/rules/require-yields-check.md#readme) | Ensures that if a `@yields` is present that a `yield` (or `yield` with a value) is present in the function body (or that if a `@next` is present that there is a yield with a return value present). |
 ||| [require-yields-description](./docs/rules/require-yields-description.md#readme) | Requires a description for `@yields` tags |
 |:heavy_check_mark:|| [require-yields-type](./docs/rules/require-yields-type.md#readme) | Requires a type for `@yields` tags |
+||| [required-tags](./docs/rules/required-tags.md#readme) | Requires tags be present, optionally for specific contexts |
 ||:wrench:| [sort-tags](./docs/rules/sort-tags.md#readme) | Sorts tags by a specified sequence according to tag name, optionally adding line breaks between tag groups. |
 |:heavy_check_mark:|:wrench:| [tag-lines](./docs/rules/tag-lines.md#readme) | Enforces lines (or no lines) between tags. |
 ||:wrench:| [text-escaping](./docs/rules/text-escaping.md#readme) | Auto-escape certain characters that are input within block and tag descriptions. |

docs/rules/required-tags.md

@@ -0,0 +1,85 @@
+<a name="user-content-required-tags"></a>
+<a name="required-tags"></a>
+# <code>required-tags</code>
+
+Requires tags be present, optionally for specific contexts.
+
+<a name="user-content-required-tags-options"></a>
+<a name="required-tags-options"></a>
+## Options
+
+A single options object has the following properties.
+
+<a name="user-content-required-tags-options-tags"></a>
+<a name="required-tags-options-tags"></a>
+### <code>tags</code>
+
+May be an array of either strings or objects with
+a string `tag` property and `context` string property.
+
+
+|||
+|---|---|
+|Context|everywhere|
+|Tags|(Any)|
+|Recommended|false|
+|Settings||
+|Options|`tags`|
+
+<a name="user-content-required-tags-failing-examples"></a>
+<a name="required-tags-failing-examples"></a>
+## Failing examples
+
+The following patterns are considered problems:
+
+````ts
+/**
+ *
+ */
+function quux () {}
+// "jsdoc/required-tags": ["error"|"warn", {"tags":["see"]}]
+// Message: Missing required tag "see"
+
+/**
+ *
+ */
+function quux () {}
+// "jsdoc/required-tags": ["error"|"warn", {"tags":[{"context":"FunctionDeclaration","tag":"see"}]}]
+// Message: Missing required tag "see"
+
+/**
+ * @type {SomeType}
+ */
+function quux () {}
+// "jsdoc/required-tags": ["error"|"warn", {"tags":[{"context":"FunctionDeclaration","tag":"see"}]}]
+// Message: Missing required tag "see"
+
+/**
+ * @type {SomeType}
+ */
+function quux () {}
+// Message: Rule `required-tags` is missing a `tags` option.
+````
+
+
+
+<a name="user-content-required-tags-passing-examples"></a>
+<a name="required-tags-passing-examples"></a>
+## Passing examples
+
+The following patterns are not considered problems:
+
+````ts
+/**
+ * @see
+ */
+function quux () {}
+// "jsdoc/required-tags": ["error"|"warn", {"tags":["see"]}]
+
+/**
+ *
+ */
+class Quux {}
+// "jsdoc/required-tags": ["error"|"warn", {"tags":[{"context":"FunctionDeclaration","tag":"see"}]}]
+````
+

src/bin/generateRule.js

@@ -117,6 +117,10 @@ export default iterateJsdoc(({
 
   const ruleReadmeTemplate = `# \`${ruleName}\`
 
+## Options
+
+{"gitdown": "options"}
+
 |||
 |---|---|
 |Context|everywhere|

src/buildForbidRuleDefinition.js

@@ -1,14 +1,24 @@
 import iterateJsdoc from './iterateJsdoc.js';
 
+/**
+ * @typedef {(string|{
+ *   comment: string,
+ *   context: string,
+ *   message?: string
+ * })[]} Contexts
+ */
+
 /**
  * @param {{
- *   contexts: (string|{
- *     comment: string,
- *     context: string,
- *     message: string
- *   })[],
+ *   contexts?: Contexts,
  *   description?: string,
- *   contextName?: string
+ *   getContexts?: (
+ *     ctxt: import('eslint').Rule.RuleContext,
+ *     report: import('./iterateJsdoc.js').Report
+ *   ) => Contexts|false,
+ *   contextName?: string,
+ *   modifyContext?: (context: import('eslint').Rule.RuleContext) => import('eslint').Rule.RuleContext,
+ *   schema?: import('eslint').Rule.RuleMetaData['schema']
  *   url?: string,
  * }} cfg
  * @returns {import('@eslint/core').RuleDefinition<
@@ -17,22 +27,35 @@ import iterateJsdoc from './iterateJsdoc.js';
  */
 export const buildForbidRuleDefinition = ({
   contextName,
-  contexts,
+  contexts: cntxts,
   description,
+  getContexts,
+  modifyContext,
+  schema,
   url,
 }) => {
   return iterateJsdoc(({
-    // context,
+    context,
     info: {
       comment,
     },
     report,
     utils,
   }) => {
+    /** @type {Contexts|boolean|undefined} */
+    let contexts = cntxts;
+
+    if (getContexts) {
+      contexts = getContexts(context, report);
+      if (!contexts) {
+        return;
+      }
+    }
+
     const {
       contextStr,
       foundContext,
-    } = utils.findContext(contexts, comment);
+    } = utils.findContext(/** @type {Contexts} */ (contexts), comment);
 
     // We are not on the *particular* matching context/comment, so don't assume
     //   we need reporting
@@ -59,10 +82,10 @@ export const buildForbidRuleDefinition = ({
         description: description ?? contextName ?? 'Reports when certain comment structures are present.',
         url: url ?? 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/advanced.md#user-content-advanced-creating-your-own-rules',
       },
-      schema: [],
+      schema: schema ?? [],
       type: 'suggestion',
     },
-    modifyContext: (context) => {
+    modifyContext: modifyContext ?? (getContexts ? undefined : (context) => {
       // Reproduce context object with our own `contexts`
       const propertyDescriptors = Object.getOwnPropertyDescriptors(context);
       return Object.create(
@@ -73,13 +96,13 @@ export const buildForbidRuleDefinition = ({
             ...propertyDescriptors.options,
             value: [
               {
-                contexts,
+                contexts: cntxts,
               },
             ],
           },
         },
       );
-    },
+    }),
     nonGlobalSettings: true,
   });
 };

src/index-cjs.js

@@ -40,6 +40,7 @@ import noUndefinedTypes from './rules/noUndefinedTypes.js';
 import requireAsteriskPrefix from './rules/requireAsteriskPrefix.js';
 import requireDescription from './rules/requireDescription.js';
 import requireDescriptionCompleteSentence from './rules/requireDescriptionCompleteSentence.js';
+import requiredTags from './rules/requiredTags.js';
 import requireExample from './rules/requireExample.js';
 import requireFileOverview from './rules/requireFileOverview.js';
 import requireHyphenBeforeParamDescription from './rules/requireHyphenBeforeParamDescription.js';
@@ -226,6 +227,7 @@ index.rules = {
     description: 'Requires a type for `@yields` tags',
     url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-yields-type.md#repos-sticky-header',
   }),
+  'required-tags': requiredTags,
   'sort-tags': sortTags,
   'tag-lines': tagLines,
   'text-escaping': textEscaping,
@@ -312,6 +314,7 @@ const createRecommendedRuleset = (warnOrError, flatName) => {
       'jsdoc/require-yields-check': warnOrError,
       'jsdoc/require-yields-description': 'off',
       'jsdoc/require-yields-type': warnOrError,
+      'jsdoc/required-tags': 'off',
       'jsdoc/sort-tags': 'off',
       'jsdoc/tag-lines': warnOrError,
       'jsdoc/text-escaping': 'off',

src/index.js

@@ -46,6 +46,7 @@ import noUndefinedTypes from './rules/noUndefinedTypes.js';
 import requireAsteriskPrefix from './rules/requireAsteriskPrefix.js';
 import requireDescription from './rules/requireDescription.js';
 import requireDescriptionCompleteSentence from './rules/requireDescriptionCompleteSentence.js';
+import requiredTags from './rules/requiredTags.js';
 import requireExample from './rules/requireExample.js';
 import requireFileOverview from './rules/requireFileOverview.js';
 import requireHyphenBeforeParamDescription from './rules/requireHyphenBeforeParamDescription.js';
@@ -232,6 +233,7 @@ index.rules = {
     description: 'Requires a type for `@yields` tags',
     url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-yields-type.md#repos-sticky-header',
   }),
+  'required-tags': requiredTags,
   'sort-tags': sortTags,
   'tag-lines': tagLines,
   'text-escaping': textEscaping,
@@ -318,6 +320,7 @@ const createRecommendedRuleset = (warnOrError, flatName) => {
       'jsdoc/require-yields-check': warnOrError,
       'jsdoc/require-yields-description': 'off',
       'jsdoc/require-yields-type': warnOrError,
+      'jsdoc/required-tags': 'off',
       'jsdoc/sort-tags': 'off',
       'jsdoc/tag-lines': warnOrError,
       'jsdoc/text-escaping': 'off',

src/rules.d.ts

@@ -2580,6 +2580,26 @@ export interface Rules {
   /** Requires a type for `@yields` tags */
   "jsdoc/require-yields-type": [];
 
+  /** Requires tags be present, optionally for specific contexts */
+  "jsdoc/required-tags": 
+    | []
+    | [
+        {
+          /**
+           * May be an array of either strings or objects with
+           * a string `tag` property and `context` string property.
+           */
+          tags?: (
+            | string
+            | {
+                context?: string;
+                tag?: string;
+                [k: string]: unknown;
+              }
+          )[];
+        }
+      ];
+
   /** Sorts tags by a specified sequence according to tag name, optionally adding line breaks between tag groups. */
   "jsdoc/sort-tags": 
     | []