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

package/src/rules/sortTags.js

@@ -0,0 +1,766 @@
+import defaultTagOrder from '../defaultTagOrder.js';
+import iterateJsdoc from '../iterateJsdoc.js';
+
+export default iterateJsdoc(({
+  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,
+    } = 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',
+  },
+});