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

package/src/rules/requireFileOverview.js

@@ -0,0 +1,213 @@
+import iterateJsdoc from '../iterateJsdoc.js';
+
+const defaultTags = {
+  file: {
+    initialCommentsOnly: true,
+    mustExist: true,
+    preventDuplicates: true,
+  },
+};
+
+/**
+ * @param {import('../iterateJsdoc.js').StateObject} state
+ * @returns {void}
+ */
+const setDefaults = (state) => {
+  // First iteration
+  if (!state.globalTags) {
+    state.globalTags = true;
+    state.hasDuplicates = {};
+    state.hasTag = {};
+    state.hasNonCommentBeforeTag = {};
+  }
+};
+
+export default iterateJsdoc(({
+  context,
+  jsdocNode,
+  state,
+  utils,
+}) => {
+  const {
+    tags = defaultTags,
+  } = context.options[0] || {};
+
+  setDefaults(state);
+
+  for (const tagName of Object.keys(tags)) {
+    const targetTagName = /** @type {string} */ (utils.getPreferredTagName({
+      tagName,
+    }));
+
+    const hasTag = Boolean(targetTagName && utils.hasTag(targetTagName));
+
+    state.hasTag[tagName] = hasTag || state.hasTag[tagName];
+
+    const hasDuplicate = state.hasDuplicates[tagName];
+
+    if (hasDuplicate === false) {
+      // Was marked before, so if a tag now, is a dupe
+      state.hasDuplicates[tagName] = hasTag;
+    } else if (!hasDuplicate && hasTag) {
+      // No dupes set before, but has first tag, so change state
+      //   from `undefined` to `false` so can detect next time
+      state.hasDuplicates[tagName] = false;
+      state.hasNonCommentBeforeTag[tagName] = state.hasNonComment &&
+        state.hasNonComment < jsdocNode.range[0];
+    }
+  }
+}, {
+  exit ({
+    context,
+    state,
+    utils,
+  }) {
+    setDefaults(state);
+    const {
+      tags = defaultTags,
+    } = context.options[0] || {};
+
+    for (const [
+      tagName,
+      {
+        initialCommentsOnly = false,
+        mustExist = false,
+        preventDuplicates = false,
+      },
+    ] of Object.entries(tags)) {
+      const obj = utils.getPreferredTagNameObject({
+        tagName,
+      });
+      if (obj && typeof obj === 'object' && 'blocked' in obj) {
+        utils.reportSettings(
+          `\`settings.jsdoc.tagNamePreference\` cannot block @${obj.tagName} ` +
+          'for the `require-file-overview` rule',
+        );
+      } else {
+        const targetTagName = (
+          obj && typeof obj === 'object' && obj.replacement
+        ) || obj;
+        if (mustExist && !state.hasTag[tagName]) {
+          utils.reportSettings(`Missing @${targetTagName}`);
+        }
+
+        if (preventDuplicates && state.hasDuplicates[tagName]) {
+          utils.reportSettings(
+            `Duplicate @${targetTagName}`,
+          );
+        }
+
+        if (initialCommentsOnly &&
+            state.hasNonCommentBeforeTag[tagName]
+        ) {
+          utils.reportSettings(
+            `@${targetTagName} should be at the beginning of the file`,
+          );
+        }
+      }
+    }
+  },
+  iterateAllJsdocs: true,
+  meta: {
+    docs: {
+      description: 'Checks that all files have one `@file`, `@fileoverview`, or `@overview` tag at the beginning of the file.',
+      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-file-overview.md#repos-sticky-header',
+    },
+    schema: [
+      {
+        additionalProperties: false,
+        properties: {
+          tags: {
+            description: `The keys of this object are tag names, and the values are configuration
+objects indicating what will be checked for these whole-file tags.
+
+Each configuration object has 3 potential boolean keys (which default
+to \`false\` when this option is supplied).
+
+1. \`mustExist\` - enforces that all files have a \`@file\`, \`@fileoverview\`, or \`@overview\` tag.
+2. \`preventDuplicates\` - enforces that duplicate file overview tags within a given file will be reported
+3. \`initialCommentsOnly\` - reports file overview tags which are not, as per
+  [the docs](https://jsdoc.app/tags-file.html), "at the beginning of
+  the file"–where beginning of the file is interpreted in this rule
+  as being when the overview tag is not preceded by anything other than
+  a comment.
+
+When no \`tags\` is present, the default is:
+
+\`\`\`json
+{
+  "file": {
+    "initialCommentsOnly": true,
+    "mustExist": true,
+    "preventDuplicates": true,
+  }
+}
+\`\`\`
+
+You can add additional tag names and/or override \`file\` if you supply this
+option, e.g., in place of or in addition to \`file\`, giving other potential
+file global tags like \`@license\`, \`@copyright\`, \`@author\`, \`@module\` or
+\`@exports\`, optionally restricting them to a single use or preventing them
+from being preceded by anything besides comments.
+
+For example:
+
+\`\`\`js
+{
+  "license": {
+    "mustExist": true,
+    "preventDuplicates": true,
+  }
+}
+\`\`\`
+
+This would require one and only one \`@license\` in the file, though because
+\`initialCommentsOnly\` is absent and defaults to \`false\`, the \`@license\`
+can be anywhere.
+
+In the case of \`@license\`, you can use this rule along with the
+\`check-values\` rule (with its \`allowedLicenses\` or \`licensePattern\` options),
+to enforce a license whitelist be present on every JS file.
+
+Note that if you choose to use \`preventDuplicates\` with \`license\`, you still
+have a way to allow multiple licenses for the whole page by using the SPDX
+"AND" expression, e.g., \`@license (MIT AND GPL-3.0)\`.
+
+Note that the tag names are the main JSDoc tag name, so you should use \`file\`
+in this configuration object regardless of whether you have configured
+\`fileoverview\` instead of \`file\` on \`tagNamePreference\` (i.e., \`fileoverview\`
+will be checked, but you must use \`file\` on the configuration object).`,
+            patternProperties: {
+              '.*': {
+                additionalProperties: false,
+                properties: {
+                  initialCommentsOnly: {
+                    type: 'boolean',
+                  },
+                  mustExist: {
+                    type: 'boolean',
+                  },
+                  preventDuplicates: {
+                    type: 'boolean',
+                  },
+                },
+                type: 'object',
+              },
+            },
+            type: 'object',
+          },
+        },
+        type: 'object',
+      },
+    ],
+    type: 'suggestion',
+  },
+  nonComment ({
+    node,
+    state,
+  }) {
+    if (!state.hasNonComment) {
+      state.hasNonComment = /** @type {[number, number]} */ (node.range)?.[0];
+    }
+  },
+});

package/src/rules/requireHyphenBeforeParamDescription.js

@@ -0,0 +1,210 @@
+import iterateJsdoc from '../iterateJsdoc.js';
+
+export default iterateJsdoc(({
+  context,
+  jsdoc,
+  utils,
+}) => {
+  const [
+    mainCircumstance,
+    {
+      tags = null,
+    } = {},
+  ] = context.options;
+
+  const tgs = /**
+               * @type {null|"any"|{[key: string]: "always"|"never"}}
+               */ (tags);
+
+  /**
+   * @param {import('@es-joy/jsdoccomment').JsdocTagWithInline} jsdocTag
+   * @param {string} targetTagName
+   * @param {"always"|"never"} [circumstance]
+   * @returns {void}
+   */
+  const checkHyphens = (jsdocTag, targetTagName, circumstance = mainCircumstance) => {
+    const always = !circumstance || circumstance === 'always';
+    const desc = /** @type {string} */ (utils.getTagDescription(jsdocTag));
+    if (!desc.trim()) {
+      return;
+    }
+
+    const startsWithHyphen = (/^\s*-/v).test(desc);
+    const hyphenNewline = (/^\s*-\n/v).test(desc);
+
+    let lines = 0;
+    for (const {
+      tokens,
+    } of jsdocTag.source) {
+      if (tokens.description) {
+        break;
+      }
+
+      lines++;
+    }
+
+    if (always && !hyphenNewline) {
+      if (!startsWithHyphen) {
+        let fixIt = true;
+        for (const {
+          tokens,
+        } of jsdocTag.source) {
+          if (tokens.description) {
+            tokens.description = tokens.description.replace(
+              /^(\s*)/v, '$1- ',
+            );
+            break;
+          }
+
+          // Linebreak after name since has no description
+          if (tokens.name) {
+            fixIt = false;
+            break;
+          }
+        }
+
+        if (fixIt) {
+          utils.reportJSDoc(
+            `There must be a hyphen before @${targetTagName} description.`,
+            {
+              line: jsdocTag.source[0].number + lines,
+            },
+            () => {},
+          );
+        }
+      }
+    } else if (startsWithHyphen) {
+      utils.reportJSDoc(
+        always ?
+          `There must be no hyphen followed by newline after the @${targetTagName} name.` :
+          `There must be no hyphen before @${targetTagName} description.`,
+        {
+          line: jsdocTag.source[0].number + lines,
+        },
+        () => {
+          for (const {
+            tokens,
+          } of jsdocTag.source) {
+            if (tokens.description) {
+              tokens.description = tokens.description.replace(
+                /^\s*-\s*/v, '',
+              );
+              if (hyphenNewline) {
+                tokens.postName = '';
+              }
+
+              break;
+            }
+          }
+        },
+        true,
+      );
+    }
+  };
+
+  utils.forEachPreferredTag('param', checkHyphens);
+  if (tgs) {
+    const tagEntries = Object.entries(tgs);
+    for (const [
+      tagName,
+      circumstance,
+    ] of tagEntries) {
+      if (tagName === '*') {
+        const preferredParamTag = utils.getPreferredTagName({
+          tagName: 'param',
+        });
+        for (const {
+          tag,
+        } of jsdoc.tags) {
+          if (tag === preferredParamTag || tagEntries.some(([
+            tagNme,
+          ]) => {
+            return tagNme !== '*' && tagNme === tag;
+          })) {
+            continue;
+          }
+
+          utils.forEachPreferredTag(tag, (jsdocTag, targetTagName) => {
+            checkHyphens(
+              jsdocTag,
+              targetTagName,
+              /** @type {"always"|"never"} */ (circumstance),
+            );
+          });
+        }
+
+        continue;
+      }
+
+      utils.forEachPreferredTag(tagName, (jsdocTag, targetTagName) => {
+        checkHyphens(
+          jsdocTag,
+          targetTagName,
+          /** @type {"always"|"never"} */ (circumstance),
+        );
+      });
+    }
+  }
+}, {
+  iterateAllJsdocs: true,
+  meta: {
+    docs: {
+      description: 'Requires a hyphen before the `@param` description (and optionally before `@property` descriptions).',
+      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-hyphen-before-param-description.md#repos-sticky-header',
+    },
+    fixable: 'code',
+    schema: [
+      {
+        description: `If the string is \`"always"\` then a problem is raised when there is no hyphen
+before the description. If it is \`"never"\` then a problem is raised when there
+is a hyphen before the description. The default value is \`"always"\`.
+
+Even if hyphens are set to "always" appear after the tag name, they will
+actually be forbidden in the event that they are followed immediately by
+the end of a line (this will otherwise cause Visual Studio Code to display
+incorrectly).`,
+        enum: [
+          'always', 'never',
+        ],
+        type: 'string',
+      },
+      {
+        additionalProperties: false,
+        description: `The options object may have the following property to indicate behavior for
+other tags besides the \`@param\` tag (or the \`@arg\` tag if so set).`,
+        properties: {
+          tags: {
+            anyOf: [
+              {
+                patternProperties: {
+                  '.*': {
+                    enum: [
+                      'always', 'never',
+                    ],
+                    type: 'string',
+                  },
+                },
+                type: 'object',
+              },
+              {
+                enum: [
+                  'any',
+                ],
+                type: 'string',
+              },
+            ],
+            description: `Object whose keys indicate different tags to check for the
+  presence or absence of hyphens; the key value should be "always" or "never",
+  indicating how hyphens are to be applied, e.g., \`{property: 'never'}\`
+  to ensure \`@property\` never uses hyphens. A key can also be set as \`*\`, e.g.,
+  \`'*': 'always'\` to apply hyphen checking to any tag (besides the preferred
+  \`@param\` tag which follows the main string option setting and besides any
+  other \`tags\` entries).`,
+          },
+        },
+        type: 'object',
+      },
+    ],
+    type: 'layout',
+  },
+});