eslint-plugin-jsdoc 53.0.0 → 54.0.0

package/src/rules/noBlankBlocks.js

@@ -0,0 +1,53 @@
+import iterateJsdoc from '../iterateJsdoc.js';
+
+export default iterateJsdoc(({
+  context,
+  jsdoc,
+  utils,
+}) => {
+  if (jsdoc.tags.length) {
+    return;
+  }
+
+  const {
+    description,
+    lastDescriptionLine,
+  } = utils.getDescription();
+  if (description.trim()) {
+    return;
+  }
+
+  const {
+    enableFixer,
+  } = context.options[0] || {};
+
+  utils.reportJSDoc(
+    'No empty blocks',
+    {
+      line: lastDescriptionLine,
+    },
+    enableFixer ? () => {
+      jsdoc.source.splice(0, jsdoc.source.length);
+    } : null,
+  );
+}, {
+  iterateAllJsdocs: true,
+  meta: {
+    docs: {
+      description: 'Removes empty blocks with nothing but possibly line breaks',
+      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/no-blank-blocks.md#repos-sticky-header',
+    },
+    fixable: 'code',
+    schema: [
+      {
+        additionalProperties: false,
+        properties: {
+          enableFixer: {
+            type: 'boolean',
+          },
+        },
+      },
+    ],
+    type: 'suggestion',
+  },
+});

package/src/rules/noDefaults.js

@@ -0,0 +1,85 @@
+import iterateJsdoc from '../iterateJsdoc.js';
+
+export default iterateJsdoc(({
+  context,
+  utils,
+}) => {
+  const {
+    noOptionalParamNames,
+  } = context.options[0] || {};
+  const paramTags = utils.getPresentTags([
+    'param', 'arg', 'argument',
+  ]);
+  for (const tag of paramTags) {
+    if (noOptionalParamNames && tag.optional) {
+      utils.reportJSDoc(`Optional param names are not permitted on @${tag.tag}.`, tag, () => {
+        utils.changeTag(tag, {
+          name: tag.name.replace(/([^=]*)(=.+)?/v, '$1'),
+        });
+      });
+    } else if (tag.default) {
+      utils.reportJSDoc(`Defaults are not permitted on @${tag.tag}.`, tag, () => {
+        utils.changeTag(tag, {
+          name: tag.name.replace(/([^=]*)(=.+)?/v, '[$1]'),
+        });
+      });
+    }
+  }
+
+  const defaultTags = utils.getPresentTags([
+    'default', 'defaultvalue',
+  ]);
+  for (const tag of defaultTags) {
+    if (tag.description.trim()) {
+      utils.reportJSDoc(`Default values are not permitted on @${tag.tag}.`, tag, () => {
+        utils.changeTag(tag, {
+          description: '',
+          postTag: '',
+        });
+      });
+    }
+  }
+}, {
+  contextDefaults: true,
+  meta: {
+    docs: {
+      description: 'This rule reports defaults being used on the relevant portion of `@param` or `@default`.',
+      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/no-defaults.md#repos-sticky-header',
+    },
+    fixable: 'code',
+    schema: [
+      {
+        additionalProperties: false,
+        properties: {
+          contexts: {
+            items: {
+              anyOf: [
+                {
+                  type: 'string',
+                },
+                {
+                  additionalProperties: false,
+                  properties: {
+                    comment: {
+                      type: 'string',
+                    },
+                    context: {
+                      type: 'string',
+                    },
+                  },
+                  type: 'object',
+                },
+              ],
+            },
+            type: 'array',
+          },
+          noOptionalParamNames: {
+            type: 'boolean',
+          },
+        },
+        type: 'object',
+      },
+    ],
+    type: 'suggestion',
+  },
+});

package/src/rules/noMissingSyntax.js

@@ -0,0 +1,195 @@
+import iterateJsdoc from '../iterateJsdoc.js';
+
+/**
+ * @typedef {{
+ *   comment: string,
+ *   context: string,
+ *   message: string,
+ *   minimum: import('../iterateJsdoc.js').Integer
+ * }} ContextObject
+ */
+
+/**
+ * @typedef {string|ContextObject} Context
+ */
+
+/**
+ * @param {import('../iterateJsdoc.js').StateObject} state
+ * @returns {void}
+ */
+const setDefaults = (state) => {
+  if (!state.selectorMap) {
+    state.selectorMap = {};
+  }
+};
+
+/**
+ * @param {import('../iterateJsdoc.js').StateObject} state
+ * @param {string} selector
+ * @param {string} comment
+ * @returns {void}
+ */
+const incrementSelector = (state, selector, comment) => {
+  if (!state.selectorMap[selector]) {
+    state.selectorMap[selector] = {};
+  }
+
+  if (!state.selectorMap[selector][comment]) {
+    state.selectorMap[selector][comment] = 0;
+  }
+
+  state.selectorMap[selector][comment]++;
+};
+
+export default iterateJsdoc(({
+  context,
+  info: {
+    comment,
+  },
+  state,
+  utils,
+}) => {
+  if (!context.options[0]) {
+    // Handle error later
+    return;
+  }
+
+  /**
+   * @type {Context[]}
+   */
+  const contexts = context.options[0].contexts;
+
+  const {
+    contextStr,
+  } = utils.findContext(contexts, comment);
+
+  setDefaults(state);
+
+  incrementSelector(state, contextStr, String(comment));
+}, {
+  contextSelected: true,
+  exit ({
+    context,
+    settings,
+    state,
+  }) {
+    if (!context.options.length && !settings.contexts) {
+      context.report({
+        loc: {
+          end: {
+            column: 1,
+            line: 1,
+          },
+          start: {
+            column: 1,
+            line: 1,
+          },
+        },
+        message: 'Rule `no-missing-syntax` is missing a `contexts` option.',
+      });
+
+      return;
+    }
+
+    setDefaults(state);
+
+    /**
+     * @type {Context[]}
+     */
+    const contexts = (context.options[0] ?? {}).contexts ?? settings?.contexts;
+
+    // Report when MISSING
+    contexts.some((cntxt) => {
+      const contextStr = typeof cntxt === 'object' ? cntxt.context ?? 'any' : cntxt;
+      const comment = typeof cntxt === 'string' ? '' : cntxt?.comment;
+
+      const contextKey = contextStr === 'any' ? 'undefined' : contextStr;
+
+      if (
+        (!state.selectorMap[contextKey] ||
+        !state.selectorMap[contextKey][comment] ||
+        state.selectorMap[contextKey][comment] < (
+          // @ts-expect-error comment would need an object, not string
+          cntxt?.minimum ?? 1
+        )) &&
+        (contextStr !== 'any' || Object.values(state.selectorMap).every((cmmnt) => {
+          return !cmmnt[comment] || cmmnt[comment] < (
+            // @ts-expect-error comment would need an object, not string
+            cntxt?.minimum ?? 1
+          );
+        }))
+      ) {
+        const message = typeof cntxt === 'string' ?
+          'Syntax is required: {{context}}' :
+          cntxt?.message ?? ('Syntax is required: {{context}}' +
+            (comment ? ' with {{comment}}' : ''));
+        context.report({
+          data: {
+            comment,
+            context: contextStr,
+          },
+          loc: {
+            end: {
+              column: 1,
+              line: 1,
+            },
+            start: {
+              column: 1,
+              line: 1,
+            },
+          },
+          message,
+        });
+
+        return true;
+      }
+
+      return false;
+    });
+  },
+  matchContext: true,
+  meta: {
+    docs: {
+      description: 'Reports when certain comment structures are always expected.',
+      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/no-missing-syntax.md#repos-sticky-header',
+    },
+    fixable: 'code',
+    schema: [
+      {
+        additionalProperties: false,
+        properties: {
+          contexts: {
+            items: {
+              anyOf: [
+                {
+                  type: 'string',
+                },
+                {
+                  additionalProperties: false,
+                  properties: {
+                    comment: {
+                      type: 'string',
+                    },
+                    context: {
+                      type: 'string',
+                    },
+                    message: {
+                      type: 'string',
+                    },
+                    minimum: {
+                      type: 'integer',
+                    },
+                  },
+                  type: 'object',
+                },
+              ],
+            },
+            type: 'array',
+          },
+        },
+        type: 'object',
+      },
+    ],
+    type: 'suggestion',
+  },
+});

package/src/rules/noMultiAsterisks.js

@@ -0,0 +1,134 @@
+import iterateJsdoc from '../iterateJsdoc.js';
+
+const middleAsterisksBlockWS = /^([\t ]|\*(?!\*))+/v;
+const middleAsterisksNoBlockWS = /^\*+/v;
+
+const endAsterisksSingleLineBlockWS = /\*((?:\*|(?: |\t))*)\*$/v;
+const endAsterisksMultipleLineBlockWS = /((?:\*|(?: |\t))*)\*$/v;
+
+const endAsterisksSingleLineNoBlockWS = /\*(\**)\*$/v;
+const endAsterisksMultipleLineNoBlockWS = /(\**)\*$/v;
+
+export default iterateJsdoc(({
+  context,
+  jsdoc,
+  utils,
+}) => {
+  const {
+    allowWhitespace = false,
+    preventAtEnd = true,
+    preventAtMiddleLines = true,
+  } = context.options[0] || {};
+
+  const middleAsterisks = allowWhitespace ? middleAsterisksNoBlockWS : middleAsterisksBlockWS;
+
+  // eslint-disable-next-line complexity -- Todo
+  jsdoc.source.some(({
+    number,
+    tokens,
+  }) => {
+    const {
+      delimiter,
+      description,
+      end,
+      name,
+      postDelimiter,
+      tag,
+      type,
+    } = tokens;
+
+    if (
+      preventAtMiddleLines &&
+      !end && !tag && !type && !name &&
+      (
+        !allowWhitespace && middleAsterisks.test(description) ||
+        allowWhitespace && middleAsterisks.test(postDelimiter + description)
+      )
+    ) {
+      // console.log('description', JSON.stringify(description));
+      const fix = () => {
+        tokens.description = description.replace(middleAsterisks, '');
+      };
+
+      utils.reportJSDoc(
+        'Should be no multiple asterisks on middle lines.',
+        {
+          line: number,
+        },
+        fix,
+        true,
+      );
+
+      return true;
+    }
+
+    if (!preventAtEnd || !end) {
+      return false;
+    }
+
+    const isSingleLineBlock = delimiter === '/**';
+    const delim = isSingleLineBlock ? '*' : delimiter;
+    const endAsterisks = allowWhitespace ?
+      (isSingleLineBlock ? endAsterisksSingleLineNoBlockWS : endAsterisksMultipleLineNoBlockWS) :
+      (isSingleLineBlock ? endAsterisksSingleLineBlockWS : endAsterisksMultipleLineBlockWS);
+
+    const endingAsterisksAndSpaces = (
+      allowWhitespace ? postDelimiter + description + delim : description + delim
+    ).match(
+      endAsterisks,
+    );
+
+    if (
+      !endingAsterisksAndSpaces ||
+      !isSingleLineBlock && endingAsterisksAndSpaces[1] && !endingAsterisksAndSpaces[1].trim()
+    ) {
+      return false;
+    }
+
+    const endFix = () => {
+      if (!isSingleLineBlock) {
+        tokens.delimiter = '';
+      }
+
+      tokens.description = (description + delim).replace(endAsterisks, '');
+    };
+
+    utils.reportJSDoc(
+      'Should be no multiple asterisks on end lines.',
+      {
+        line: number,
+      },
+      endFix,
+      true,
+    );
+
+    return true;
+  });
+}, {
+  iterateAllJsdocs: true,
+  meta: {
+    docs: {
+      description: 'Prevents use of multiple asterisks at the beginning of lines.',
+      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/no-multi-asterisks.md#repos-sticky-header',
+    },
+    fixable: 'code',
+    schema: [
+      {
+        additionalProperties: false,
+        properties: {
+          allowWhitespace: {
+            type: 'boolean',
+          },
+          preventAtEnd: {
+            type: 'boolean',
+          },
+          preventAtMiddleLines: {
+            type: 'boolean',
+          },
+        },
+        type: 'object',
+      },
+    ],
+    type: 'suggestion',
+  },
+});

package/src/rules/noRestrictedSyntax.js

@@ -0,0 +1,91 @@
+import iterateJsdoc from '../iterateJsdoc.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];
+
+  const {
+    contextStr,
+    foundContext,
+  } = utils.findContext(contexts, comment);
+
+  // 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',
+    },
+    fixable: 'code',
+    schema: [
+      {
+        additionalProperties: false,
+        properties: {
+          contexts: {
+            items: {
+              anyOf: [
+                {
+                  type: 'string',
+                },
+                {
+                  additionalProperties: false,
+                  properties: {
+                    comment: {
+                      type: 'string',
+                    },
+                    context: {
+                      type: 'string',
+                    },
+                    message: {
+                      type: 'string',
+                    },
+                  },
+                  type: 'object',
+                },
+              ],
+            },
+            type: 'array',
+          },
+        },
+        required: [
+          'contexts',
+        ],
+        type: 'object',
+      },
+    ],
+    type: 'suggestion',
+  },
+  nonGlobalSettings: true,
+});

package/src/rules/noTypes.js

@@ -0,0 +1,93 @@
+import iterateJsdoc from '../iterateJsdoc.js';
+
+/**
+ * @param {import('comment-parser').Line} line
+ */
+const removeType = ({
+  tokens,
+}) => {
+  tokens.postTag = '';
+  tokens.type = '';
+};
+
+export default iterateJsdoc(({
+  node,
+  utils,
+}) => {
+  if (!utils.isIteratingFunctionOrVariable() && !utils.isVirtualFunction()) {
+    return;
+  }
+
+  const tags = utils.getPresentTags([
+    'param', 'arg', 'argument', 'returns', 'return',
+  ]);
+
+  for (const tag of tags) {
+    if (tag.type) {
+      utils.reportJSDoc(`Types are not permitted on @${tag.tag}.`, tag, () => {
+        for (const source of tag.source) {
+          removeType(source);
+        }
+      });
+    }
+  }
+
+  if (node?.type === 'ClassDeclaration') {
+    const propertyTags = utils.getPresentTags([
+      'prop', 'property',
+    ]);
+    for (const tag of propertyTags) {
+      if (tag.type) {
+        utils.reportJSDoc(`Types are not permitted on @${tag.tag} in the supplied context.`, tag, () => {
+          for (const source of tag.source) {
+            removeType(source);
+          }
+        });
+      }
+    }
+  }
+}, {
+  contextDefaults: [
+    'ArrowFunctionExpression', 'FunctionDeclaration', 'FunctionExpression', 'TSDeclareFunction',
+    // Add this to above defaults
+    'TSMethodSignature', 'ClassDeclaration',
+  ],
+  meta: {
+    docs: {
+      description: 'This rule reports types being used on `@param` or `@returns`.',
+      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/no-types.md#repos-sticky-header',
+    },
+    fixable: 'code',
+    schema: [
+      {
+        additionalProperties: false,
+        properties: {
+          contexts: {
+            items: {
+              anyOf: [
+                {
+                  type: 'string',
+                },
+                {
+                  additionalProperties: false,
+                  properties: {
+                    comment: {
+                      type: 'string',
+                    },
+                    context: {
+                      type: 'string',
+                    },
+                  },
+                  type: 'object',
+                },
+              ],
+            },
+            type: 'array',
+          },
+        },
+        type: 'object',
+      },
+    ],
+    type: 'suggestion',
+  },
+});