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

package/dist/rules/sortTags.cjs

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