eslint-plugin-jsdoc 59.0.1 → 59.1.0

package/src/rules/noRestrictedSyntax.js

@@ -1,59 +1,26 @@
-import iterateJsdoc from '../iterateJsdoc.js';
+import {
+  buildForbidRuleDefinition,
+} from '../buildForbidRuleDefinition.js';
 
-export default iterateJsdoc(({
-  context,
-  info: {
-    comment,
-  },
-  report,
-  utils,
-}) => {
-  if (!context.options.length) {
-    report('Rule `no-restricted-syntax` is missing a `contexts` option.');
-
-    return;
-  }
-
-  const {
-    contexts,
-  } = context.options[0];
+export default buildForbidRuleDefinition({
+  getContexts (context, report) {
+    if (!context.options.length) {
+      report('Rule `no-restricted-syntax` is missing a `contexts` option.');
+      return false;
+    }
 
-  const {
-    contextStr,
-    foundContext,
-  } = utils.findContext(contexts, comment);
+    const {
+      contexts,
+    } = context.options[0];
 
-  // We are not on the *particular* matching context/comment, so don't assume
-  //   we need reporting
-  if (!foundContext) {
-    return;
-  }
-
-  const message = /** @type {import('../iterateJsdoc.js').ContextObject} */ (
-    foundContext
-  )?.message ??
-    'Syntax is restricted: {{context}}' +
-      (comment ? ' with {{comment}}' : '');
-
-  report(message, null, null, comment ? {
-    comment,
-    context: contextStr,
-  } : {
-    context: contextStr,
-  });
-}, {
-  contextSelected: true,
-  meta: {
-    docs: {
-      description: 'Reports when certain comment structures are present.',
-      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/no-restricted-syntax.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
+    return contexts;
+  },
+  schema: [
+    {
+      additionalProperties: false,
+      properties: {
+        contexts: {
+          description: `Set this to an array of strings representing the AST context (or an object with
 \`context\` and \`comment\` properties) where you wish the rule to be applied.
 
 \`context\` defaults to \`any\` and \`comment\` defaults to no specific comment context.
@@ -70,38 +37,36 @@ aliases \`@func\` or \`@method\`) (including those associated with an \`@interfa
 
 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',
-                    },
-                    message: {
-                      type: 'string',
-                    },
+          items: {
+            anyOf: [
+              {
+                type: 'string',
+              },
+              {
+                additionalProperties: false,
+                properties: {
+                  comment: {
+                    type: 'string',
+                  },
+                  context: {
+                    type: 'string',
+                  },
+                  message: {
+                    type: 'string',
                   },
-                  type: 'object',
                 },
-              ],
-            },
-            type: 'array',
+                type: 'object',
+              },
+            ],
           },
+          type: 'array',
         },
-        required: [
-          'contexts',
-        ],
-        type: 'object',
       },
-    ],
-    type: 'suggestion',
-  },
-  nonGlobalSettings: true,
+      required: [
+        'contexts',
+      ],
+      type: 'object',
+    },
+  ],
+  url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/no-restricted-syntax.md#repos-sticky-header',
 });

package/src/rules/noUndefinedTypes.js

@@ -115,7 +115,7 @@ export default iterateJsdoc(({
   const allComments = sourceCode.getAllComments();
   const comments = allComments
     .filter((comment) => {
-      return (/^\*\s/v).test(comment.value);
+      return (/^\*(?!\*)/v).test(comment.value);
     })
     .map((commentNode) => {
       return parseComment(commentNode, '');

package/src/rules/requiredTags.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 `required-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/required-tags.md#repos-sticky-header',
+});

package/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": 
     | []