eslint-plugin-jsdoc 37.6.2 → 37.8.0

package/dist/rules/sortTags.js

@@ -0,0 +1,165 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+
+var _defaultTagOrder = _interopRequireDefault(require("../defaultTagOrder"));
+
+var _iterateJsdoc = _interopRequireDefault(require("../iterateJsdoc"));
+
+function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
+
+var _default = (0, _iterateJsdoc.default)(({
+  context,
+  jsdoc,
+  utils
+}) => {
+  const {
+    tagSequence = _defaultTagOrder.default,
+    alphabetizeExtras = false
+  } = context.options[0] || {};
+  const otherPos = tagSequence.indexOf('-other');
+  const endPos = otherPos > -1 ? otherPos : tagSequence.length;
+  let ongoingCount = 0;
+
+  for (const [idx, tag] of jsdoc.tags.entries()) {
+    tag.originalIndex = idx;
+    ongoingCount += tag.source.length;
+    tag.originalLine = ongoingCount;
+  }
+
+  let firstChangedTagLine;
+  let firstChangedTagIndex;
+  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 = tagSequence.indexOf(tagNew);
+    const oldPos = tagSequence.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) {
+    return;
+  }
+
+  const firstLine = utils.getFirstLine();
+
+  const fix = () => {
+    const itemsToMoveRange = [...Array.from({
+      length: jsdoc.tags.length - 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 = firstLine + 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 + 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: ${tagSequence.join(', ')}`, jsdoc.tags[firstChangedTagIndex], fix, true);
+}, {
+  iterateAllJsdocs: true,
+  meta: {
+    docs: {
+      description: '',
+      url: 'https://github.com/gajus/eslint-plugin-jsdoc#eslint-plugin-jsdoc-rules-sort-tags'
+    },
+    fixable: 'code',
+    schema: [{
+      additionalProperies: false,
+      properties: {
+        alphabetizeExtras: {
+          type: 'boolean'
+        },
+        tagSequence: {
+          items: {
+            type: 'string'
+          },
+          type: 'array'
+        }
+      },
+      type: 'object'
+    }],
+    type: 'suggestion'
+  }
+});
+
+exports.default = _default;
+module.exports = exports.default;
+//# sourceMappingURL=sortTags.js.map

package/dist/rules/sortTags.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/rules/sortTags.js"],"names":["context","jsdoc","utils","tagSequence","defaultTagOrder","alphabetizeExtras","options","otherPos","indexOf","endPos","length","ongoingCount","idx","tag","tags","entries","originalIndex","source","originalLine","firstChangedTagLine","firstChangedTagIndex","sortedTags","JSON","parse","stringify","sort","tagNew","tagOld","checkOrSetFirstChanged","newPos","oldPos","preferredNewPos","preferredOldPos","undefined","firstLine","getFirstLine","fix","itemsToMoveRange","Array","from","keys","unchangedPriorTagDescriptions","slice","reduce","ct","initialOffset","removeTag","changedTags","extraTagCount","changedTag","addTag","tokens","end","addLine","reportJSDoc","join","iterateAllJsdocs","meta","docs","description","url","fixable","schema","additionalProperies","properties","type","items"],"mappings":"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","sourcesContent":["import defaultTagOrder from '../defaultTagOrder';\nimport iterateJsdoc from '../iterateJsdoc';\n\nexport default iterateJsdoc(({\n  context,\n  jsdoc,\n  utils,\n}) => {\n  const {\n    tagSequence = defaultTagOrder,\n    alphabetizeExtras = false,\n  } = context.options[0] || {};\n\n  const otherPos = tagSequence.indexOf('-other');\n  const endPos = otherPos > -1 ? otherPos : tagSequence.length;\n\n  let ongoingCount = 0;\n  for (const [\n    idx,\n    tag,\n  ] of jsdoc.tags.entries()) {\n    tag.originalIndex = idx;\n    ongoingCount += tag.source.length;\n    tag.originalLine = ongoingCount;\n  }\n\n  let firstChangedTagLine;\n  let firstChangedTagIndex;\n  const sortedTags = JSON.parse(JSON.stringify(jsdoc.tags));\n  sortedTags.sort(({\n    tag: tagNew,\n  }, {\n    originalIndex,\n    originalLine,\n    tag: tagOld,\n  }) => {\n    // Optimize: Just keep relative positions if the same tag name\n    if (tagNew === tagOld) {\n      return 0;\n    }\n\n    const checkOrSetFirstChanged = () => {\n      if (!firstChangedTagLine || originalLine < firstChangedTagLine) {\n        firstChangedTagLine = originalLine;\n        firstChangedTagIndex = originalIndex;\n      }\n    };\n\n    const newPos = tagSequence.indexOf(tagNew);\n    const oldPos = tagSequence.indexOf(tagOld);\n\n    const preferredNewPos = newPos === -1 ? endPos : newPos;\n    const preferredOldPos = oldPos === -1 ? endPos : oldPos;\n\n    if (preferredNewPos < preferredOldPos) {\n      checkOrSetFirstChanged();\n      return -1;\n    }\n\n    if (preferredNewPos > preferredOldPos) {\n      return 1;\n    }\n\n    // preferredNewPos === preferredOldPos\n    if (\n      !alphabetizeExtras ||\n\n      // Optimize: If tagNew (or tagOld which is the same) was found in the\n      //   priority array, it can maintain its relative position—without need\n      //   of alphabetizing (secondary sorting)\n      newPos >= 0\n    ) {\n      return 0;\n    }\n\n    if (tagNew < tagOld) {\n      checkOrSetFirstChanged();\n      return -1;\n    }\n\n    // tagNew > tagOld\n    return 1;\n  });\n\n  if (firstChangedTagLine === undefined) {\n    return;\n  }\n\n  const firstLine = utils.getFirstLine();\n\n  const fix = () => {\n    const itemsToMoveRange = [\n      ...Array.from({\n        length: jsdoc.tags.length - firstChangedTagIndex,\n      }).keys(),\n    ];\n\n    const unchangedPriorTagDescriptions = jsdoc.tags.slice(\n      0,\n      firstChangedTagIndex,\n    ).reduce((ct, {\n      source,\n    }) => {\n      return ct + source.length - 1;\n    }, 0);\n\n    // This offset includes not only the offset from where the first tag\n    //   must begin, and the additional offset of where the first changed\n    //   tag begins, but it must also account for prior descriptions\n    const initialOffset = firstLine + firstChangedTagIndex +\n\n      // May be the first tag, so don't try finding a prior one if so\n      unchangedPriorTagDescriptions;\n\n    // Use `firstChangedTagLine` for line number to begin reporting/splicing\n    for (const idx of itemsToMoveRange) {\n      utils.removeTag(idx + firstChangedTagIndex);\n    }\n\n    const changedTags = sortedTags.slice(firstChangedTagIndex);\n    let extraTagCount = 0;\n\n    for (const idx of itemsToMoveRange) {\n      const changedTag = changedTags[idx];\n\n      utils.addTag(\n        changedTag.tag,\n        extraTagCount + initialOffset + idx,\n        {\n          ...changedTag.source[0].tokens,\n\n          // `comment-parser` puts the `end` within the `tags` section, so\n          //   avoid adding another to jsdoc.source\n          end: '',\n        },\n      );\n\n      for (const {\n        tokens,\n      } of changedTag.source.slice(1)) {\n        if (!tokens.end) {\n          utils.addLine(\n            extraTagCount + initialOffset + idx + 1,\n            {\n              ...tokens,\n              end: '',\n            },\n          );\n          extraTagCount++;\n        }\n      }\n    }\n  };\n\n  utils.reportJSDoc(\n    `Tags are not in the prescribed order: ${tagSequence.join(', ')}`,\n    jsdoc.tags[firstChangedTagIndex],\n    fix,\n    true,\n  );\n}, {\n  iterateAllJsdocs: true,\n  meta: {\n    docs: {\n      description: '',\n      url: 'https://github.com/gajus/eslint-plugin-jsdoc#eslint-plugin-jsdoc-rules-sort-tags',\n    },\n    fixable: 'code',\n    schema: [\n      {\n        additionalProperies: false,\n        properties: {\n          alphabetizeExtras: {\n            type: 'boolean',\n          },\n          tagSequence: {\n            items: {\n              type: 'string',\n            },\n            type: 'array',\n          },\n        },\n        type: 'object',\n      },\n    ],\n    type: 'suggestion',\n  },\n});\n"],"file":"sortTags.js"}

package/package.json

@@ -5,7 +5,7 @@
     "url": "http://gajus.com"
   },
   "dependencies": {
-    "@es-joy/jsdoccomment": "~0.17.0",
+    "@es-joy/jsdoccomment": "~0.18.0",
     "comment-parser": "1.3.0",
     "debug": "^4.3.3",
     "escape-string-regexp": "^4.0.0",
@@ -16,30 +16,30 @@
   },
   "description": "JSDoc linting rules for ESLint.",
   "devDependencies": {
-    "@babel/cli": "^7.16.8",
-    "@babel/core": "^7.16.10",
-    "@babel/eslint-parser": "^7.16.5",
+    "@babel/cli": "^7.17.0",
+    "@babel/core": "^7.17.0",
+    "@babel/eslint-parser": "^7.17.0",
     "@babel/node": "^7.16.8",
     "@babel/plugin-syntax-class-properties": "^7.12.13",
     "@babel/plugin-transform-flow-strip-types": "^7.16.7",
     "@babel/preset-env": "^7.16.11",
-    "@babel/register": "^7.16.9",
+    "@babel/register": "^7.17.0",
     "@hkdobrev/run-if-changed": "^0.3.1",
-    "@typescript-eslint/parser": "^5.10.0",
+    "@typescript-eslint/parser": "^5.10.2",
     "babel-plugin-add-module-exports": "^1.0.4",
     "babel-plugin-istanbul": "^6.1.1",
     "camelcase": "^6.3.0",
-    "chai": "^4.3.4",
+    "chai": "^4.3.6",
     "cross-env": "^7.0.3",
     "decamelize": "^5.0.1",
-    "eslint": "^8.7.0",
+    "eslint": "^8.8.0",
     "eslint-config-canonical": "^33.0.1",
     "gitdown": "^3.1.4",
     "glob": "^7.2.0",
     "husky": "^7.0.4",
-    "lint-staged": "^12.2.2",
+    "lint-staged": "^12.3.3",
     "lodash.defaultsdeep": "^4.6.1",
-    "mocha": "^9.1.4",
+    "mocha": "^9.2.0",
     "nyc": "^15.1.0",
     "open-editor": "^3.0.0",
     "rimraf": "^3.0.2",
@@ -107,5 +107,5 @@
     "test-index": "cross-env BABEL_ENV=test mocha --recursive --require @babel/register --reporter progress --timeout 12000 test/rules/index.js",
     "test-no-cov": "cross-env BABEL_ENV=test mocha --reporter dot --recursive --require @babel/register --timeout 12000"
   },
-  "version": "37.6.2"
+  "version": "37.8.0"
 }