eslint-plugin-jsdoc 63.3.3 → 64.0.0

package/dist/rules/sortTags.cjs

@@ -1,656 +0,0 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.default = void 0;
-var _defaultTagOrder = _interopRequireDefault(require("../defaultTagOrder.cjs"));
-var _iterateJsdoc = _interopRequireDefault(require("../iterateJsdoc.cjs"));
-function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
-var _default = exports.default = (0, _iterateJsdoc.default)(({
-  context,
-  jsdoc,
-  utils
-  // eslint-disable-next-line complexity -- Temporary
-}) => {
-  const
-  /**
-   * @type {{
-   *   linesBetween: import('../iterateJsdoc.js').Integer,
-   *   tagExceptions: Record<string, number>,
-   *   tagSequence: {
-   *     tags: string[]
-   *   }[],
-   *   alphabetizeExtras: boolean,
-   *   reportTagGroupSpacing: boolean,
-   *   reportIntraTagGroupSpacing: boolean,
-   * }}
-   */
-  {
-    alphabetizeExtras = false,
-    linesBetween = 1,
-    reportIntraTagGroupSpacing = true,
-    reportTagGroupSpacing = true,
-    tagExceptions = {},
-    tagSequence = _defaultTagOrder.default
-  } = context.options[0] || {};
-  const tagList = tagSequence.flatMap(obj => {
-    /* typeof obj === 'string' ? obj : */
-    return obj.tags;
-  });
-  const otherPos = tagList.indexOf('-other');
-  const endPos = otherPos > -1 ? otherPos : tagList.length;
-  let ongoingCount = 0;
-  for (const [idx, tag] of
-  /**
-   * @type {(
-   *   import('@es-joy/jsdoccomment').JsdocTagWithInline & {
-   *     originalIndex: import('../iterateJsdoc.js').Integer,
-   *     originalLine: import('../iterateJsdoc.js').Integer,
-   *   }
-   * )[]}
-   */
-  jsdoc.tags.entries()) {
-    tag.originalIndex = idx;
-    ongoingCount += tag.source.length;
-    tag.originalLine = ongoingCount;
-  }
-
-  /** @type {import('../iterateJsdoc.js').Integer|undefined} */
-  let firstChangedTagLine;
-  /** @type {import('../iterateJsdoc.js').Integer|undefined} */
-  let firstChangedTagIndex;
-
-  /**
-   * @type {(import('comment-parser').Spec & {
-   *   originalIndex: import('../iterateJsdoc.js').Integer,
-   *   originalLine: import('../iterateJsdoc.js').Integer,
-   * })[]}
-   */
-  const sortedTags = JSON.parse(JSON.stringify(jsdoc.tags));
-  sortedTags.sort(({
-    tag: tagNew
-  }, {
-    originalIndex,
-    originalLine,
-    tag: tagOld
-  }) => {
-    // Optimize: Just keep relative positions if the same tag name
-    if (tagNew === tagOld) {
-      return 0;
-    }
-    const checkOrSetFirstChanged = () => {
-      if (!firstChangedTagLine || originalLine < firstChangedTagLine) {
-        firstChangedTagLine = originalLine;
-        firstChangedTagIndex = originalIndex;
-      }
-    };
-    const newPos = tagList.indexOf(tagNew);
-    const oldPos = tagList.indexOf(tagOld);
-    const preferredNewPos = newPos === -1 ? endPos : newPos;
-    const preferredOldPos = oldPos === -1 ? endPos : oldPos;
-    if (preferredNewPos < preferredOldPos) {
-      checkOrSetFirstChanged();
-      return -1;
-    }
-    if (preferredNewPos > preferredOldPos) {
-      return 1;
-    }
-
-    // preferredNewPos === preferredOldPos
-    if (!alphabetizeExtras ||
-    // Optimize: If tagNew (or tagOld which is the same) was found in the
-    //   priority array, it can maintain its relative position—without need
-    //   of alphabetizing (secondary sorting)
-    newPos >= 0) {
-      return 0;
-    }
-    if (tagNew < tagOld) {
-      checkOrSetFirstChanged();
-      return -1;
-    }
-
-    // tagNew > tagOld
-    return 1;
-  });
-  if (firstChangedTagLine === undefined) {
-    // Should be ordered by now
-
-    /**
-     * @type {import('comment-parser').Spec[]}
-     */
-    const lastTagsOfGroup = [];
-
-    /**
-     * @type {[
-     *   import('comment-parser').Spec,
-     *   import('../iterateJsdoc.js').Integer
-     * ][]}
-     */
-    const badLastTagsOfGroup = [];
-
-    /**
-     * @param {import('comment-parser').Spec} tag
-     */
-    const countTagEmptyLines = tag => {
-      return tag.source.reduce((acc, {
-        tokens: {
-          description,
-          end,
-          name,
-          tag: tg,
-          type
-        }
-      }) => {
-        const empty = !tg && !type && !name && !description;
-        // Reset the count so long as there is content
-        return empty ? acc + Number(empty && !end) : 0;
-      }, 0);
-    };
-    let idx = 0;
-    for (const {
-      tags
-    } of tagSequence) {
-      let innerIdx;
-      /** @type {import('comment-parser').Spec} */
-      let currentTag;
-      /** @type {import('comment-parser').Spec|undefined} */
-      let lastTag;
-      do {
-        currentTag = jsdoc.tags[idx];
-        if (!currentTag) {
-          idx++;
-          break;
-        }
-        innerIdx = tags.indexOf(currentTag.tag);
-        if (innerIdx === -1 && (
-        // eslint-disable-next-line no-loop-func -- Safe
-        !tags.includes('-other') || tagSequence.some(({
-          tags: tgs
-        }) => {
-          return tgs.includes(currentTag.tag);
-        }))) {
-          idx++;
-          break;
-        }
-        lastTag = currentTag;
-        idx++;
-      } while (true);
-      idx--;
-      if (lastTag) {
-        lastTagsOfGroup.push(lastTag);
-        const ct = countTagEmptyLines(lastTag);
-        if (ct !== linesBetween &&
-        // Use another rule for adding to end (should be of interest outside this rule)
-        jsdoc.tags[idx]) {
-          badLastTagsOfGroup.push([lastTag, ct]);
-        }
-      }
-    }
-    if (reportTagGroupSpacing && badLastTagsOfGroup.length) {
-      /**
-       * @param {import('comment-parser').Spec} tg
-       * @returns {() => void}
-       */
-      const fixer = tg => {
-        return () => {
-          // Due to https://github.com/syavorsky/comment-parser/issues/110 ,
-          //  we have to modify `jsdoc.source` rather than just modify tags
-          //  directly
-          for (const [currIdx, {
-            tokens
-          }] of jsdoc.source.entries()) {
-            if (tokens.tag !== '@' + tg.tag) {
-              continue;
-            }
-
-            // Cannot be `tokens.end`, as dropped off last tag, so safe to
-            //  go on
-            let newIdx = currIdx;
-            const emptyLine = () => {
-              return {
-                number: 0,
-                source: '',
-                tokens: utils.seedTokens({
-                  delimiter: '*',
-                  start: jsdoc.source[newIdx - 1].tokens.start
-                })
-              };
-            };
-            let existingEmptyLines = 0;
-            while (true) {
-              const nextTokens = jsdoc.source[++newIdx]?.tokens;
-
-              /* c8 ignore next 3 -- Guard */
-              if (!nextTokens) {
-                return;
-              }
-
-              // Should be no `nextTokens.end` to worry about since ignored
-              //  if not followed by tag
-
-              if (nextTokens.tag) {
-                // Haven't made it to last tag instance yet, so keep looking
-                if (nextTokens.tag === tokens.tag) {
-                  existingEmptyLines = 0;
-                  continue;
-                }
-                const lineDiff = linesBetween - existingEmptyLines;
-                if (lineDiff > 0) {
-                  const lines = Array.from({
-                    length: lineDiff
-                  }, () => {
-                    return emptyLine();
-                  });
-                  jsdoc.source.splice(newIdx, 0, ...lines);
-                } else {
-                  // lineDiff < 0
-                  jsdoc.source.splice(newIdx + lineDiff, -lineDiff);
-                }
-                break;
-              }
-              const empty = !nextTokens.type && !nextTokens.name && !nextTokens.description;
-              if (empty) {
-                existingEmptyLines++;
-              } else {
-                // Has content again, so reset empty line count
-                existingEmptyLines = 0;
-              }
-            }
-            break;
-          }
-          for (const [srcIdx, src] of jsdoc.source.entries()) {
-            src.number = srcIdx;
-          }
-        };
-      };
-      for (const [tg] of badLastTagsOfGroup) {
-        utils.reportJSDoc('Tag groups do not have the expected whitespace', tg, fixer(tg));
-      }
-      return;
-    }
-    if (!reportIntraTagGroupSpacing) {
-      return;
-    }
-    for (const [tagIdx, tag] of jsdoc.tags.entries()) {
-      if (!jsdoc.tags[tagIdx + 1] || lastTagsOfGroup.includes(tag)) {
-        continue;
-      }
-      const ct = countTagEmptyLines(tag);
-      if (ct && (!tagExceptions[tag.tag] || tagExceptions[tag.tag] < ct)) {
-        const fixer = () => {
-          let foundFirstTag = false;
-
-          /** @type {string|undefined} */
-          let currentTag;
-          for (const [currIdx, {
-            tokens: {
-              description,
-              end,
-              name,
-              tag: tg,
-              type
-            }
-          }] of jsdoc.source.entries()) {
-            if (tg) {
-              foundFirstTag = true;
-              currentTag = tg;
-            }
-            if (!foundFirstTag) {
-              continue;
-            }
-            if (currentTag && !tg && !type && !name && !description && !end) {
-              let nextIdx = currIdx;
-              let ignore = true;
-              // Even if a tag of the same name as the last tags in a group,
-              //  could still be an earlier tag in that group
-
-              // eslint-disable-next-line no-loop-func -- Safe
-              if (lastTagsOfGroup.some(lastTagOfGroup => {
-                return currentTag === '@' + lastTagOfGroup.tag;
-              })) {
-                while (true) {
-                  const nextTokens = jsdoc.source[++nextIdx]?.tokens;
-                  if (!nextTokens) {
-                    break;
-                  }
-                  if (!nextTokens.tag) {
-                    continue;
-                  }
-
-                  // Followed by the same tag name, so not actually last in group,
-                  //   and of interest
-                  if (nextTokens.tag === currentTag) {
-                    ignore = false;
-                  }
-                }
-              } else {
-                while (true) {
-                  const nextTokens = jsdoc.source[++nextIdx]?.tokens;
-                  if (!nextTokens || nextTokens.end) {
-                    break;
-                  }
-
-                  // Not the very last tag, so don't ignore
-                  if (nextTokens.tag) {
-                    ignore = false;
-                    break;
-                  }
-                }
-              }
-              if (!ignore) {
-                jsdoc.source.splice(currIdx, 1);
-                for (const [srcIdx, src] of jsdoc.source.entries()) {
-                  src.number = srcIdx;
-                }
-              }
-            }
-          }
-        };
-        utils.reportJSDoc('Intra-group tags have unexpected whitespace', tag, fixer);
-      }
-    }
-    return;
-  }
-  const firstLine = utils.getFirstLine();
-  const fix = () => {
-    const itemsToMoveRange = [...Array.from({
-      length: jsdoc.tags.length - (/** @type {import('../iterateJsdoc.js').Integer} */
-      firstChangedTagIndex)
-    }).keys()];
-    const unchangedPriorTagDescriptions = jsdoc.tags.slice(0, firstChangedTagIndex).reduce((ct, {
-      source
-    }) => {
-      return ct + source.length - 1;
-    }, 0);
-
-    // This offset includes not only the offset from where the first tag
-    //   must begin, and the additional offset of where the first changed
-    //   tag begins, but it must also account for prior descriptions
-    const initialOffset = /** @type {import('../iterateJsdoc.js').Integer} */firstLine + (/** @type {import('../iterateJsdoc.js').Integer} */firstChangedTagIndex) +
-    // May be the first tag, so don't try finding a prior one if so
-    unchangedPriorTagDescriptions;
-
-    // Use `firstChangedTagLine` for line number to begin reporting/splicing
-    for (const idx of itemsToMoveRange) {
-      utils.removeTag(idx + (/** @type {import('../iterateJsdoc.js').Integer} */
-      firstChangedTagIndex));
-    }
-    const changedTags = sortedTags.slice(firstChangedTagIndex);
-    let extraTagCount = 0;
-    for (const idx of itemsToMoveRange) {
-      const changedTag = changedTags[idx];
-      utils.addTag(changedTag.tag, extraTagCount + initialOffset + idx, {
-        ...changedTag.source[0].tokens,
-        // `comment-parser` puts the `end` within the `tags` section, so
-        //   avoid adding another to jsdoc.source
-        end: ''
-      });
-      for (const {
-        tokens
-      } of changedTag.source.slice(1)) {
-        if (!tokens.end) {
-          utils.addLine(extraTagCount + initialOffset + idx + 1, {
-            ...tokens,
-            end: ''
-          });
-          extraTagCount++;
-        }
-      }
-    }
-  };
-  utils.reportJSDoc(`Tags are not in the prescribed order: ${tagList.join(', ') || '(alphabetical)'}`, jsdoc.tags[(/** @type {import('../iterateJsdoc.js').Integer} */
-  firstChangedTagIndex)], fix, true);
-}, {
-  iterateAllJsdocs: true,
-  meta: {
-    docs: {
-      description: 'Sorts tags by a specified sequence according to tag name, optionally adding line breaks between tag groups.',
-      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/sort-tags.md#repos-sticky-header'
-    },
-    fixable: 'code',
-    schema: [{
-      additionalProperties: false,
-      properties: {
-        alphabetizeExtras: {
-          description: `Defaults to \`false\`. Alphabetizes any items not within \`tagSequence\` after any
-items within \`tagSequence\` (or in place of the special \`-other\` pseudo-tag)
-are sorted.
-
-If you want all your tags alphabetized, you can supply an empty array for
-\`tagSequence\` along with setting this option to \`true\`.`,
-          type: 'boolean'
-        },
-        linesBetween: {
-          description: `Indicates the number of lines to be added between tag groups. Defaults to 1.
-Do not set to 0 or 2+ if you are using \`tag-lines\` and \`"always"\` and do not
-set to 1+ if you are using \`tag-lines\` and \`"never"\`.`,
-          type: 'integer'
-        },
-        reportIntraTagGroupSpacing: {
-          description: `Whether to enable reporting and fixing of line breaks within tags of a given
-tag group. Defaults to \`true\` which will remove any line breaks at the end of
-such tags. Do not use with \`true\` if you are using \`tag-lines\` and \`always\`.`,
-          type: 'boolean'
-        },
-        reportTagGroupSpacing: {
-          description: `Whether to enable reporting and fixing of line breaks between tag groups
-as set by \`linesBetween\`. Defaults to \`true\`. Note that the very last tag
-will not have spacing applied regardless. For adding line breaks there, you
-may wish to use the \`endLines\` option of the \`tag-lines\` rule.`,
-          type: 'boolean'
-        },
-        tagExceptions: {
-          description: 'Allows specification by tag of a specific higher maximum number of lines. Keys are tags and values are the maximum number of lines allowed for such tags. Overrides `linesBetween`. Defaults to no special exceptions per tag.',
-          patternProperties: {
-            '.*': {
-              type: 'number'
-            }
-          },
-          type: 'object'
-        },
-        tagSequence: {
-          description: `An array of tag group objects indicating the preferred sequence for sorting tags.
-
-Each item in the array should be an object with a \`tags\` property set to an array
-of tag names.
-
-Tag names earlier in the list will be arranged first. The relative position of
-tags of the same name will not be changed.
-
-Earlier groups will also be arranged before later groups, but with the added
-feature that additional line breaks may be added between (or before or after)
-such groups (depending on the setting of \`linesBetween\`).
-
-Tag names not in the list will be grouped together at the end. The pseudo-tag
-\`-other\` can be used to place them anywhere else if desired. The tags will be
-placed in their order of appearance, or alphabetized if \`alphabetizeExtras\`
-is enabled, see more below about that option.
-
-Defaults to the array below (noting that it is just a single tag group with
-no lines between groups by default).
-
-Please note that this order is still experimental, so if you want to retain
-a fixed order that doesn't change into the future, supply your own
-\`tagSequence\`.
-
-\`\`\`js
-[{tags: [
-  // Brief descriptions
-  'summary',
-  'typeSummary',
-
-  // Module/file-level
-  'module',
-  'exports',
-  'file',
-  'fileoverview',
-  'overview',
-  'import',
-
-  // Identifying (name, type)
-  'typedef',
-  'interface',
-  'record',
-  'template',
-  'name',
-  'kind',
-  'type',
-  'alias',
-  'external',
-  'host',
-  'callback',
-  'func',
-  'function',
-  'method',
-  'class',
-  'constructor',
-
-  // Relationships
-  'modifies',
-  'mixes',
-  'mixin',
-  'mixinClass',
-  'mixinFunction',
-  'namespace',
-  'borrows',
-  'constructs',
-  'lends',
-  'implements',
-  'requires',
-
-  // Long descriptions
-  'desc',
-  'description',
-  'classdesc',
-  'tutorial',
-  'copyright',
-  'license',
-
-  // Simple annotations
-  'const',
-  'constant',
-  'final',
-  'global',
-  'readonly',
-  'abstract',
-  'virtual',
-  'var',
-  'member',
-  'memberof',
-  'memberof!',
-  'inner',
-  'instance',
-  'inheritdoc',
-  'inheritDoc',
-  'override',
-  'hideconstructor',
-
-  // Core function/object info
-  'param',
-  'arg',
-  'argument',
-  'prop',
-  'property',
-  'return',
-  'returns',
-
-  // Important behavior details
-  'async',
-  'generator',
-  'default',
-  'defaultvalue',
-  'enum',
-  'augments',
-  'extends',
-  'throws',
-  'exception',
-  'yield',
-  'yields',
-  'event',
-  'fires',
-  'emits',
-  'listens',
-  'this',
-
-  // Access
-  'static',
-  'private',
-  'protected',
-  'public',
-  'access',
-  'package',
-
-  '-other',
-
-  // Supplementary descriptions
-  'see',
-  'example',
-
-  // METADATA
-
-  // Other Closure (undocumented) metadata
-  'closurePrimitive',
-  'customElement',
-  'expose',
-  'hidden',
-  'idGenerator',
-  'meaning',
-  'ngInject',
-  'owner',
-  'wizaction',
-
-  // Other Closure (documented) metadata
-  'define',
-  'dict',
-  'export',
-  'externs',
-  'implicitCast',
-  'noalias',
-  'nocollapse',
-  'nocompile',
-  'noinline',
-  'nosideeffects',
-  'polymer',
-  'polymerBehavior',
-  'preserve',
-  'struct',
-  'suppress',
-  'unrestricted',
-
-  // @homer0/prettier-plugin-jsdoc metadata
-  'category',
-
-  // Non-Closure metadata
-  'ignore',
-  'author',
-  'version',
-  'variation',
-  'since',
-  'deprecated',
-  'todo',
-]}];
-\`\`\``,
-          items: {
-            additionalProperties: false,
-            properties: {
-              tags: {
-                description: 'See description on `tagSequence`.',
-                items: {
-                  type: 'string'
-                },
-                type: 'array'
-              }
-            },
-            type: 'object'
-          },
-          type: 'array'
-        }
-      },
-      type: 'object'
-    }],
-    type: 'suggestion'
-  }
-});
-module.exports = exports.default;
-//# sourceMappingURL=sortTags.cjs.map