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

package/src/rules/noBlankBlockDescriptions.js

@@ -0,0 +1,69 @@
+import iterateJsdoc from '../iterateJsdoc.js';
+
+const anyWhitespaceLines = /^\s*$/v;
+const atLeastTwoLinesWhitespace = /^[ \t]*\n[ \t]*\n\s*$/v;
+
+export default iterateJsdoc(({
+  jsdoc,
+  utils,
+}) => {
+  const {
+    description,
+    descriptions,
+    lastDescriptionLine,
+  } = utils.getDescription();
+
+  const regex = jsdoc.tags.length ?
+    anyWhitespaceLines :
+    atLeastTwoLinesWhitespace;
+
+  if (descriptions.length && regex.test(description)) {
+    if (jsdoc.tags.length) {
+      utils.reportJSDoc(
+        'There should be no blank lines in block descriptions followed by tags.',
+        {
+          line: lastDescriptionLine,
+        },
+        () => {
+          utils.setBlockDescription(() => {
+            // Remove all lines
+            return [];
+          });
+        },
+      );
+    } else {
+      utils.reportJSDoc(
+        'There should be no extra blank lines in block descriptions not followed by tags.',
+        {
+          line: lastDescriptionLine,
+        },
+        () => {
+          utils.setBlockDescription((info, seedTokens) => {
+            return [
+              // Keep the starting line
+              {
+                number: 0,
+                source: '',
+                tokens: seedTokens({
+                  ...info,
+                  description: '',
+                }),
+              },
+            ];
+          });
+        },
+      );
+    }
+  }
+}, {
+  iterateAllJsdocs: true,
+  meta: {
+    docs: {
+      description: 'If tags are present, this rule will prevent empty lines in the block description. If no tags are present, this rule will prevent extra empty lines in the block description.',
+      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/no-blank-block-descriptions.md#repos-sticky-header',
+    },
+    fixable: 'whitespace',
+    schema: [],
+    type: 'layout',
+  },
+});

package/src/rules/noBlankBlocks.js

@@ -0,0 +1,55 @@
+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);
+    } : 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: {
+            description: 'Whether or not to auto-remove the blank block. Defaults to `false`.',
+            type: 'boolean',
+          },
+        },
+        type: 'object',
+      },
+    ],
+    type: 'suggestion',
+  },
+});

package/src/rules/noDefaults.js

@@ -0,0 +1,104 @@
+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: {
+            description: `Set this to an array of strings representing the AST context (or an object with
+optional \`context\` and \`comment\` properties) where you wish the rule to be applied.
+
+\`context\` defaults to \`any\` and \`comment\` defaults to no specific comment context.
+
+Overrides the default contexts (\`ArrowFunctionExpression\`, \`FunctionDeclaration\`,
+\`FunctionExpression\`). Set to \`"any"\` if you want
+the rule to apply to any JSDoc block throughout your files (as is necessary
+for finding function blocks not attached to a function declaration or
+expression, i.e., \`@callback\` or \`@function\` (or its aliases \`@func\` or
+\`@method\`) (including those associated with an \`@interface\`).
+
+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',
+                    },
+                  },
+                  type: 'object',
+                },
+              ],
+            },
+            type: 'array',
+          },
+          noOptionalParamNames: {
+            description: `Set this to \`true\` to report the presence of optional parameters. May be
+used if the project is insisting on optionality being indicated by
+the presence of ES6 default parameters (bearing in mind that such
+"defaults" are only applied when the supplied value is missing or
+\`undefined\` but not for \`null\` or other "falsey" values).`,
+            type: 'boolean',
+          },
+        },
+        type: 'object',
+      },
+    ],
+    type: 'suggestion',
+  },
+});

package/src/rules/noMissingSyntax.js

@@ -0,0 +1,215 @@
+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',
+    },
+    schema: [
+      {
+        additionalProperties: false,
+        properties: {
+          contexts: {
+            description: `Set this to an array of strings representing the AST context (or an object with
+optional \`context\` and \`comment\` properties) where you wish the rule to be applied.
+
+\`context\` defaults to \`any\` and \`comment\` defaults to no specific comment context.
+
+Use the \`minimum\` property (defaults to 1) to indicate how many are required
+for the rule to be reported.
+
+Use the \`message\` property to indicate the specific error to be shown when an
+error is reported for that context being found missing. You may use
+\`{{context}}\` and \`{{comment}}\` with such messages. Defaults to
+\`"Syntax is required: {{context}}"\`, or with a comment, to
+\`"Syntax is required: {{context}} with {{comment}}"\`.
+
+Set to \`"any"\` if you want the rule to apply to any JSDoc block throughout
+your files (as is necessary for finding function blocks not attached to a
+function declaration or expression, i.e., \`@callback\` or \`@function\` (or its
+aliases \`@func\` or \`@method\`) (including those associated with an \`@interface\`).
+
+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',
+                    },
+                    minimum: {
+                      type: 'integer',
+                    },
+                  },
+                  type: 'object',
+                },
+              ],
+            },
+            type: 'array',
+          },
+        },
+        type: 'object',
+      },
+    ],
+    type: 'suggestion',
+  },
+});

package/src/rules/noMultiAsterisks.js

@@ -0,0 +1,162 @@
+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;
+
+  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: {
+            description: `Set to \`true\` if you wish to allow asterisks after a space (as with Markdown):
+
+\`\`\`js
+/**
+ * *bold* text
+ */
+\`\`\`
+
+Defaults to \`false\`.`,
+            type: 'boolean',
+          },
+          preventAtEnd: {
+            description: `Prevent the likes of this:
+
+\`\`\`js
+/**
+ *
+ *
+ **/
+\`\`\`
+
+Defaults to \`true\`.`,
+            type: 'boolean',
+          },
+          preventAtMiddleLines: {
+            description: `Prevent the likes of this:
+
+\`\`\`js
+/**
+ *
+ **
+ */
+\`\`\`
+
+Defaults to \`true\`.`,
+            type: 'boolean',
+          },
+        },
+        type: 'object',
+      },
+    ],
+    type: 'suggestion',
+  },
+});

package/src/rules/noRestrictedSyntax.js

@@ -0,0 +1,72 @@
+import {
+  buildForbidRuleDefinition,
+} from '../buildForbidRuleDefinition.js';
+
+export default buildForbidRuleDefinition({
+  getContexts (context, report) {
+    if (!context.options.length) {
+      report('Rule `no-restricted-syntax` is missing a `contexts` option.');
+      return false;
+    }
+
+    const {
+      contexts,
+    } = context.options[0];
+
+    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.
+
+Use the \`message\` property to indicate the specific error to be shown when an
+error is reported for that context being found. Defaults to
+\`"Syntax is restricted: {{context}}"\`, or with a comment, to
+\`"Syntax is restricted: {{context}} with {{comment}}"\`.
+
+Set to \`"any"\` if you want the rule to apply to any JSDoc block throughout
+your files (as is necessary for finding function blocks not attached to a
+function declaration or expression, i.e., \`@callback\` or \`@function\` (or its
+aliases \`@func\` or \`@method\`) (including those associated with an \`@interface\`).
+
+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',
+                  },
+                },
+                type: 'object',
+              },
+            ],
+          },
+          type: 'array',
+        },
+      },
+      required: [
+        'contexts',
+      ],
+      type: 'object',
+    },
+  ],
+  url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/no-restricted-syntax.md#repos-sticky-header',
+});