eslint-plugin-jsdoc 52.0.1 → 52.0.3

package/src/rules/noBlankBlocks.js

@@ -1,53 +0,0 @@
-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

@@ -1,85 +0,0 @@
-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

@@ -1,195 +0,0 @@
-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

@@ -1,134 +0,0 @@
-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

@@ -1,91 +0,0 @@
-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

@@ -1,93 +0,0 @@
-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.isIteratingFunction() && !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',
-  },
-});