eslint-plugin-jsdoc 53.0.1 → 54.1.0

package/src/rules/matchDescription.js

@@ -0,0 +1,286 @@
+import iterateJsdoc from '../iterateJsdoc.js';
+
+// If supporting Node >= 10, we could loosen the default to this for the
+//   initial letter: \\p{Upper}
+const matchDescriptionDefault = '^\n?([A-Z`\\d_][\\s\\S]*[.?!`\\p{RGI_Emoji}]\\s*)?$';
+
+/**
+ * @param {string} value
+ * @param {string} userDefault
+ * @returns {string}
+ */
+const stringOrDefault = (value, userDefault) => {
+  return typeof value === 'string' ?
+    value :
+    userDefault || matchDescriptionDefault;
+};
+
+export default iterateJsdoc(({
+  context,
+  jsdoc,
+  report,
+  utils,
+}) => {
+  const {
+    mainDescription,
+    matchDescription,
+    message,
+    nonemptyTags = true,
+    tags = {},
+  } = context.options[0] || {};
+
+  /**
+   * @param {string} desc
+   * @param {import('comment-parser').Spec} [tag]
+   * @returns {void}
+   */
+  const validateDescription = (desc, tag) => {
+    let mainDescriptionMatch = mainDescription;
+    let errorMessage = message;
+    if (typeof mainDescription === 'object') {
+      mainDescriptionMatch = mainDescription.match;
+      errorMessage = mainDescription.message;
+    }
+
+    if (mainDescriptionMatch === false && (
+      !tag || !Object.hasOwn(tags, tag.tag))
+    ) {
+      return;
+    }
+
+    let tagValue = mainDescriptionMatch;
+    if (tag) {
+      const tagName = tag.tag;
+      if (typeof tags[tagName] === 'object') {
+        tagValue = tags[tagName].match;
+        errorMessage = tags[tagName].message;
+      } else {
+        tagValue = tags[tagName];
+      }
+    }
+
+    const regex = utils.getRegexFromString(
+      stringOrDefault(tagValue, matchDescription),
+    );
+
+    if (!regex.test(desc)) {
+      report(
+        errorMessage || 'JSDoc description does not satisfy the regex pattern.',
+        null,
+        tag || {
+          // Add one as description would typically be into block
+          line: jsdoc.source[0].number + 1,
+        },
+      );
+    }
+  };
+
+  const {
+    description,
+  } = utils.getDescription();
+  if (description) {
+    validateDescription(description);
+  }
+
+  /**
+   * @param {string} tagName
+   * @returns {boolean}
+   */
+  const hasNoTag = (tagName) => {
+    return !tags[tagName];
+  };
+
+  for (const tag of [
+    'description',
+    'summary',
+    'file',
+    'classdesc',
+  ]) {
+    utils.forEachPreferredTag(tag, (matchingJsdocTag, targetTagName) => {
+      const desc = (matchingJsdocTag.name + ' ' + utils.getTagDescription(matchingJsdocTag)).trim();
+      if (hasNoTag(targetTagName)) {
+        validateDescription(desc, matchingJsdocTag);
+      }
+    }, true);
+  }
+
+  if (nonemptyTags) {
+    for (const tag of [
+      'copyright',
+      'example',
+      'see',
+      'todo',
+    ]) {
+      utils.forEachPreferredTag(tag, (matchingJsdocTag, targetTagName) => {
+        const desc = (matchingJsdocTag.name + ' ' + utils.getTagDescription(matchingJsdocTag)).trim();
+
+        if (hasNoTag(targetTagName) && !(/.+/v).test(desc)) {
+          report(
+            'JSDoc description must not be empty.',
+            null,
+            matchingJsdocTag,
+          );
+        }
+      });
+    }
+  }
+
+  if (!Object.keys(tags).length) {
+    return;
+  }
+
+  /**
+   * @param {string} tagName
+   * @returns {boolean}
+   */
+  const hasOptionTag = (tagName) => {
+    return Boolean(tags[tagName]);
+  };
+
+  const whitelistedTags = utils.filterTags(({
+    tag: tagName,
+  }) => {
+    return hasOptionTag(tagName);
+  });
+  const {
+    tagsWithNames,
+    tagsWithoutNames,
+  } = utils.getTagsByType(whitelistedTags);
+
+  tagsWithNames.some((tag) => {
+    const desc = /** @type {string} */ (
+      utils.getTagDescription(tag)
+    ).replace(/^[\- ]*/v, '')
+      .trim();
+
+    return validateDescription(desc, tag);
+  });
+
+  tagsWithoutNames.some((tag) => {
+    const desc = (tag.name + ' ' + utils.getTagDescription(tag)).trim();
+
+    return validateDescription(desc, tag);
+  });
+}, {
+  contextDefaults: true,
+  meta: {
+    docs: {
+      description: 'Enforces a regular expression pattern on descriptions.',
+      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/match-description.md#repos-sticky-header',
+    },
+    schema: [
+      {
+        additionalProperties: false,
+        properties: {
+          contexts: {
+            items: {
+              anyOf: [
+                {
+                  type: 'string',
+                },
+                {
+                  additionalProperties: false,
+                  properties: {
+                    comment: {
+                      type: 'string',
+                    },
+                    context: {
+                      type: 'string',
+                    },
+                  },
+                  type: 'object',
+                },
+              ],
+            },
+            type: 'array',
+          },
+          mainDescription: {
+            oneOf: [
+              {
+                format: 'regex',
+                type: 'string',
+              },
+              {
+                type: 'boolean',
+              },
+              {
+                additionalProperties: false,
+                properties: {
+                  match: {
+                    oneOf: [
+                      {
+                        format: 'regex',
+                        type: 'string',
+                      },
+                      {
+                        type: 'boolean',
+                      },
+                    ],
+                  },
+                  message: {
+                    type: 'string',
+                  },
+                },
+                type: 'object',
+              },
+            ],
+          },
+          matchDescription: {
+            format: 'regex',
+            type: 'string',
+          },
+          message: {
+            type: 'string',
+          },
+          nonemptyTags: {
+            type: 'boolean',
+          },
+          tags: {
+            patternProperties: {
+              '.*': {
+                oneOf: [
+                  {
+                    format: 'regex',
+                    type: 'string',
+                  },
+                  {
+                    enum: [
+                      true,
+                    ],
+                    type: 'boolean',
+                  },
+                  {
+                    additionalProperties: false,
+                    properties: {
+                      match: {
+                        oneOf: [
+                          {
+                            format: 'regex',
+                            type: 'string',
+                          },
+                          {
+                            enum: [
+                              true,
+                            ],
+                            type: 'boolean',
+                          },
+                        ],
+                      },
+                      message: {
+                        type: 'string',
+                      },
+                    },
+                    type: 'object',
+                  },
+                ],
+              },
+            },
+            type: 'object',
+          },
+        },
+        type: 'object',
+      },
+    ],
+    type: 'suggestion',
+  },
+});

package/src/rules/matchName.js

@@ -0,0 +1,151 @@
+import iterateJsdoc from '../iterateJsdoc.js';
+
+// eslint-disable-next-line complexity
+export default iterateJsdoc(({
+  context,
+  info: {
+    lastIndex,
+  },
+  jsdoc,
+  report,
+  utils,
+}) => {
+  const {
+    match,
+  } = context.options[0] || {};
+  if (!match) {
+    report('Rule `no-restricted-syntax` is missing a `match` option.');
+
+    return;
+  }
+
+  const {
+    allowName,
+    disallowName,
+    replacement,
+    tags = [
+      '*',
+    ],
+  } = match[/** @type {import('../iterateJsdoc.js').Integer} */ (lastIndex)];
+
+  const allowNameRegex = allowName && utils.getRegexFromString(allowName);
+  const disallowNameRegex = disallowName && utils.getRegexFromString(disallowName);
+
+  let applicableTags = jsdoc.tags;
+  if (!tags.includes('*')) {
+    applicableTags = utils.getPresentTags(tags);
+  }
+
+  let reported = false;
+  for (const tag of applicableTags) {
+    const tagName = tag.name.replace(/^\[/v, '').replace(/(=.*)?\]$/v, '');
+    const allowed = !allowNameRegex || allowNameRegex.test(tagName);
+    const disallowed = disallowNameRegex && disallowNameRegex.test(tagName);
+    const hasRegex = allowNameRegex || disallowNameRegex;
+    if (hasRegex && allowed && !disallowed) {
+      continue;
+    }
+
+    if (!hasRegex && reported) {
+      continue;
+    }
+
+    const fixer = () => {
+      for (const src of tag.source) {
+        if (src.tokens.name) {
+          src.tokens.name = src.tokens.name.replace(
+            disallowNameRegex, replacement,
+          );
+          break;
+        }
+      }
+    };
+
+    let {
+      message,
+    } = match[/** @type {import('../iterateJsdoc.js').Integer} */ (lastIndex)];
+    if (!message) {
+      if (hasRegex) {
+        message = disallowed ?
+          `Only allowing names not matching \`${disallowNameRegex}\` but found "${tagName}".` :
+          `Only allowing names matching \`${allowNameRegex}\` but found "${tagName}".`;
+      } else {
+        message = `Prohibited context for "${tagName}".`;
+      }
+    }
+
+    utils.reportJSDoc(
+      message,
+      hasRegex ? tag : null,
+
+      // We could match up
+      disallowNameRegex && replacement !== undefined ?
+        fixer :
+        null,
+      false,
+      {
+        // Could also supply `context`, `comment`, `tags`
+        allowName,
+        disallowName,
+        name: tagName,
+      },
+    );
+    if (!hasRegex) {
+      reported = true;
+    }
+  }
+}, {
+  matchContext: true,
+  meta: {
+    docs: {
+      description: 'Reports the name portion of a JSDoc tag if matching or not matching a given regular expression.',
+      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/match-name.md#repos-sticky-header',
+    },
+    fixable: 'code',
+    schema: [
+      {
+        additionalProperties: false,
+        properties: {
+          match: {
+            items: {
+              additionalProperties: false,
+              properties: {
+                allowName: {
+                  type: 'string',
+                },
+                comment: {
+                  type: 'string',
+                },
+                context: {
+                  type: 'string',
+                },
+                disallowName: {
+                  type: 'string',
+                },
+                message: {
+                  type: 'string',
+                },
+                replacement: {
+                  type: 'string',
+                },
+                tags: {
+                  items: {
+                    type: 'string',
+                  },
+                  type: 'array',
+                },
+              },
+              type: 'object',
+            },
+            type: 'array',
+          },
+        },
+        required: [
+          'match',
+        ],
+        type: 'object',
+      },
+    ],
+    type: 'suggestion',
+  },
+});