eslint-plugin-crisp 1.7.11 → 1.7.13

package/README.md

@@ -227,6 +227,7 @@ Each item has emojis denoting:
 | [crisp/vue-computed-order](https://github.com/crisp-oss/eslint-plugin-crisp/blob/master/rules/vue-computed-order.js) | Ensures computed properties are alphabetically ordered |  | 🟢 |
 | [crisp/vue-define-component](https://github.com/crisp-oss/eslint-plugin-crisp/blob/master/rules/vue-define-component.js) | Enforces mixins and components to use the `defineComponent` wrapper |  | 🟢 |
 | [crisp/vue-emits-order](https://github.com/crisp-oss/eslint-plugin-crisp/blob/master/rules/vue-emits-order.js) | Ensures emits properties are alphabetically ordered |  | 🟢 |
+| [crisp/vue-event-listener-jsdoc](https://github.com/crisp-oss/eslint-plugin-crisp/blob/master/rules/vue-event-listener-jsdoc.js) | Requires event listener method JSDoc descriptions to start with `Triggers on` |  | 🟢 |
 | [crisp/vue-header-check](https://github.com/crisp-oss/eslint-plugin-crisp/blob/master/rules/vue-header-check.js) | Ensures `script`, `template` and `style` tags start with corresponding comment block |  | 🟢 |
 | [crisp/vue-html-indent](https://github.com/crisp-oss/eslint-plugin-crisp/blob/master/rules/vue-html-indent.js) | Enforces consistent indentation in `template` (supports for Pug) |  | 🟢 |
 | [crisp/vue-html-quotes](https://github.com/crisp-oss/eslint-plugin-crisp/blob/master/rules/vue-html-quotes.js) | Enforces HTML attributes to be enclosed with double quotes |  | 🟢 |

package/index.js

@@ -50,6 +50,7 @@ import ruleVueComputedOrder from "./rules/vue-computed-order.js";
 import ruleVueDataComment from "./rules/vue-data-comment.js";
 import ruleVueDefineComponent from "./rules/vue-define-component.js";
 import ruleVueEmitsOrder from "./rules/vue-emits-order.js";
+import ruleVueEventListenerJsdoc from "./rules/vue-event-listener-jsdoc.js";
 import ruleVueHeaderCheck from "./rules/vue-header-check.js";
 import ruleVueHtmlIndent from "./rules/vue-html-indent.js";
 import ruleVueHtmlQuotes from "./rules/vue-html-quotes.js";
@@ -129,6 +130,7 @@ const plugin = {
     "vue-data-comment": ruleVueDataComment,
     "vue-define-component": ruleVueDefineComponent,
     "vue-emits-order": ruleVueEmitsOrder,
+    "vue-event-listener-jsdoc": ruleVueEventListenerJsdoc,
     "vue-header-check": ruleVueHeaderCheck,
     "vue-html-indent": ruleVueHtmlIndent,
     "vue-html-quotes": ruleVueHtmlQuotes,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-crisp",
-  "version": "1.7.11",
+  "version": "1.7.13",
   "description": "Custom ESLint Rules for Crisp",
   "author": "Crisp IM SAS",
   "main": "index.js",

package/recommended-vue.js

@@ -385,6 +385,7 @@ export default function configRecommendedVue(pluginCrisp) {
         "crisp/vue-data-comment": "error",
         "crisp/vue-define-component": "error",
         "crisp/vue-emits-order": "error",
+        "crisp/vue-event-listener-jsdoc": "error",
         "crisp/vue-header-check": "error",
         "crisp/vue-html-indent": "error",
         "crisp/vue-html-quotes": "error",

package/rules/vue-event-listener-jsdoc.js

@@ -0,0 +1,87 @@
+import doctrine from "doctrine";
+
+const EVENT_LISTENERS_SEPARATOR = "--> EVENT LISTENERS <--";
+const DESCRIPTION_PREFIX = "Triggers on ";
+
+export default {
+  meta: {
+    type: "suggestion",
+    docs: {
+      description:
+        "require event listener method descriptions to start with 'Triggers on'",
+      category: "Stylistic Issues",
+      recommended: false
+    },
+    fixable: null,
+    schema: [],
+    messages: {
+      invalidDescription:
+        "Event listener method JSDoc description must start with " +
+        "'Triggers on ...'.",
+      missingJsdoc: "Event listener methods must have a JSDoc comment."
+    }
+  },
+
+  create(context) {
+    const sourceCode = context.sourceCode;
+
+    function checkMethods(node) {
+      const properties = node.value.properties;
+
+      if (!properties) {
+        return;
+      }
+
+      let eventListenersStarted = false;
+
+      properties.forEach((property) => {
+        const comments = sourceCode.getCommentsBefore(property);
+
+        if (!eventListenersStarted) {
+          eventListenersStarted = comments.some((comment) => {
+            return (
+              comment.type === "Line" &&
+              comment.value.trim() === EVENT_LISTENERS_SEPARATOR
+            );
+          });
+        }
+
+        if (!eventListenersStarted || property.type !== "Property") {
+          return;
+        }
+
+        const jsdoc = [...comments].reverse().find((comment) => {
+          return comment.type === "Block" && comment.value.startsWith("*");
+        });
+
+        if (!jsdoc) {
+          context.report({
+            node: property,
+            messageId: "missingJsdoc"
+          });
+
+          return;
+        }
+
+        const description = doctrine.parse(
+          `/*${jsdoc.value}*/`,
+          { unwrap: true }
+        ).description.trim();
+
+        if (!description.startsWith(DESCRIPTION_PREFIX)) {
+          context.report({
+            node: jsdoc,
+            messageId: "invalidDescription"
+          });
+        }
+      });
+    }
+
+    return {
+      'ExportDefaultDeclaration > ObjectExpression > Property[key.name="methods"]':
+        checkMethods,
+      'ExportDefaultDeclaration > CallExpression[callee.name="defineComponent"] > ObjectExpression > Property[key.name="methods"]':
+        checkMethods
+    };
+  }
+};

package/rules/vue-methods-separator.js

@@ -18,7 +18,7 @@ export default {
       category: "Stylistic Issues",
       recommended: false
     },
-    fixable: null,
+    fixable: "code",
     schema: [],
     messages: {
       duplicateSeparator:
@@ -39,6 +39,114 @@ export default {
   create(context) {
     const sourceCode = context.sourceCode;
 
+    function createOrderFix(node, separatorEntries, properties) {
+      const objectEnd = node.value.range[1] - 1;
+      const sectionStarts = separatorEntries.map(({ comment }) => {
+        return sourceCode.getIndexFromLoc({
+          line: comment.loc.start.line,
+          column: 0
+        });
+      });
+
+      const hasInlineSeparator = separatorEntries.some(
+        ({ comment }, index) => {
+          return sourceCode.text
+            .slice(sectionStarts[index], comment.range[0])
+            .trim() !== "";
+        }
+      );
+
+      if (hasInlineSeparator) {
+        return null;
+      }
+
+      const sections = separatorEntries.map((entry, index) => {
+        const start = sectionStarts[index];
+        const end = sectionStarts[index + 1] ?? objectEnd;
+        const rawText = sourceCode.text.slice(start, end);
+        const text = rawText.trimEnd();
+        const nextEntry = separatorEntries[index + 1];
+        const sectionProperties = properties.filter((property) => {
+          return (
+            property.range[0] > entry.comment.range[1] &&
+            (!nextEntry || property.range[0] < nextEntry.comment.range[0])
+          );
+        });
+
+        return {
+          ...entry,
+          start,
+          end,
+          text,
+          trailingWhitespace: rawText.slice(text.length),
+          properties: sectionProperties
+        };
+      });
+
+      if (sections.some((section) => section.properties.length === 0)) {
+        return null;
+      }
+
+      const sectionGap = sections[0].trailingWhitespace;
+
+      if (!/[\r\n]/.test(sectionGap)) {
+        return null;
+      }
+
+      const suffix = sections.at(-1).trailingWhitespace;
+      const lastProperty = properties.at(-1);
+      const tokenAfterLastProperty = sourceCode.getTokenAfter(lastProperty);
+      const preserveTrailingComma = (
+        tokenAfterLastProperty?.value === "," &&
+        tokenAfterLastProperty.range[0] < objectEnd
+      );
+      const orderedSections = [...sections].sort((first, second) => {
+        return first.order - second.order;
+      });
+
+      const fixedSections = orderedSections.map((section, index) => {
+        const lastSectionProperty = section.properties.at(-1);
+        const tokenAfterProperty = sourceCode.getTokenAfter(
+          lastSectionProperty
+        );
+        const hasComma = (
+          tokenAfterProperty?.value === "," &&
+          tokenAfterProperty.range[0] < section.end
+        );
+        const needsComma = (
+          index < orderedSections.length - 1 ||
+          preserveTrailingComma
+        );
+        const propertyEnd = lastSectionProperty.range[1] - section.start;
+
+        if (needsComma && !hasComma) {
+          return (
+            section.text.slice(0, propertyEnd) +
+            "," +
+            section.text.slice(propertyEnd)
+          );
+        }
+
+        if (!needsComma && hasComma) {
+          const commaStart = tokenAfterProperty.range[0] - section.start;
+
+          return (
+            section.text.slice(0, commaStart) +
+            section.text.slice(commaStart + 1)
+          );
+        }
+
+        return section.text;
+      });
+
+      return (fixer) => {
+        return fixer.replaceTextRange(
+          [sectionStarts[0], objectEnd],
+          fixedSections.join(sectionGap) + suffix
+        );
+      };
+    }
+
     function checkMethods(node) {
       const properties = node.value.properties;
 
@@ -57,8 +165,10 @@ export default {
         }
       );
       const seenSeparators = new Set();
-      let lastSeparatorOrder = -1;
+      const separatorEntries = [];
       let separatorCount = 0;
+      let hasDuplicateSeparator = false;
+      let hasInvalidSeparator = false;
 
       comments.forEach((comment) => {
         if (comment.type !== "Line") {
@@ -70,6 +180,8 @@ export default {
 
         if (separatorOrder === undefined) {
           if (SEPARATOR_LIKE_PATTERN.test(separator)) {
+            hasInvalidSeparator = true;
+
             context.report({
               node: comment,
               messageId: "invalidSeparator"
@@ -82,6 +194,8 @@ export default {
         separatorCount++;
 
         if (seenSeparators.has(separator)) {
+          hasDuplicateSeparator = true;
+
           context.report({
             node: comment,
             messageId: "duplicateSeparator",
@@ -92,15 +206,37 @@ export default {
         }
 
         seenSeparators.add(separator);
+        separatorEntries.push({
+          comment,
+          order: separatorOrder
+        });
+      });
 
-        if (separatorOrder < lastSeparatorOrder) {
-          context.report({
-            node: comment,
-            messageId: "unorderedSeparator"
-          });
-        } else {
-          lastSeparatorOrder = separatorOrder;
+      let lastSeparatorOrder = -1;
+      const unorderedEntries = separatorEntries.filter((entry) => {
+        if (entry.order < lastSeparatorOrder) {
+          return true;
         }
+
+        lastSeparatorOrder = entry.order;
+
+        return false;
+      });
+
+      const orderFix = (
+        unorderedEntries.length > 0 &&
+        !hasDuplicateSeparator &&
+        !hasInvalidSeparator
+      )
+        ? createOrderFix(node, separatorEntries, properties)
+        : null;
+
+      unorderedEntries.forEach((entry, index) => {
+        context.report({
+          node: entry.comment,
+          messageId: "unorderedSeparator",
+          ...(index === 0 && orderFix ? { fix: orderFix } : {})
+        });
       });
 
       if (separatorCount === 0) {

package/tests/rules/vue-event-listener-jsdoc.test.js

@@ -0,0 +1,174 @@
+import rule from "../../rules/vue-event-listener-jsdoc.js";
+import { createVueRuleTester } from "../rule-tester.js";
+
+const ruleTester = createVueRuleTester();
+
+ruleTester.run("vue-event-listener-jsdoc", rule, {
+  valid: [
+    {
+      code: "export default { methods: {} };"
+    },
+    {
+      code: `
+        export default {
+          methods: {
+            // --> HELPERS <--
+            /**
+             * Handles formatting
+             */
+            format() {}
+          }
+        };
+      `
+    },
+    {
+      code: `
+        export default {
+          methods: {
+            // --> EVENT LISTENERS <--
+            /**
+             * Triggers on load more
+             * @public
+             * @param {object} $state
+             */
+            onLoadMore($state) {}
+          }
+        };
+      `
+    },
+    {
+      code: `
+        export default defineComponent({
+          methods: {
+            // --> ACTIONS <--
+            /**
+             * Saves content
+             */
+            save() {},
+            // --> HELPERS <--
+            /**
+             * Formats content
+             */
+            format() {},
+            // --> EVENT LISTENERS <--
+            /**
+             * Triggers on save
+             */
+            onSave() {},
+            /**
+             * Triggers on close
+             */
+            onClose: function() {}
+          }
+        });
+      `
+    },
+    {
+      filename: "Component.vue",
+      code: `
+        <script>
+        export default defineComponent({
+          methods: {
+            // --> EVENT LISTENERS <--
+            /**
+             * Triggers on load more
+             * @public
+             */
+            onLoadMore() {
+              this.loadMore(() => {
+                /**
+                 * Handles a nested callback
+                 */
+                return true;
+              });
+            }
+          }
+        });
+        </script>
+      `
+    }
+  ],
+
+  invalid: [
+    {
+      code: `
+        export default {
+          methods: {
+            // --> EVENT LISTENERS <--
+            /**
+             * Handles load more
+             * @public
+             */
+            onLoadMore() {}
+          }
+        };
+      `,
+      errors: [
+        {
+          messageId: "invalidDescription"
+        }
+      ]
+    },
+    {
+      code: `
+        export default {
+          methods: {
+            // --> EVENT LISTENERS <--
+            onLoadMore() {}
+          }
+        };
+      `,
+      errors: [
+        {
+          messageId: "missingJsdoc"
+        }
+      ]
+    },
+    {
+      code: `
+        export default {
+          methods: {
+            // --> EVENT LISTENERS <--
+            /**
+             * Triggers on
+             * @public
+             */
+            onLoadMore() {}
+          }
+        };
+      `,
+      errors: [
+        {
+          messageId: "invalidDescription"
+        }
+      ]
+    },
+    {
+      filename: "Component.vue",
+      code: `
+        <script>
+        export default defineComponent({
+          methods: {
+            // --> EVENT LISTENERS <--
+            /**
+             * Triggers when content is saved
+             * @public
+             */
+            onSave() {},
+            /**
+             * Triggers on close
+             * @public
+             */
+            onClose() {}
+          }
+        });
+        </script>
+      `,
+      errors: [
+        {
+          messageId: "invalidDescription"
+        }
+      ]
+    }
+  ]
+});

package/tests/rules/vue-methods-separator.test.js

@@ -149,12 +149,94 @@ ruleTester.run("vue-methods-separator", rule, {
           }
         };
       `,
+      output: `
+        export default {
+          methods: {
+            // --> ACTIONS <--
+            save() {},
+            // --> HELPERS <--
+            format() {}
+          }
+        };
+      `,
       errors: [
         {
           messageId: "unorderedSeparator"
         }
       ]
     },
+    {
+      code: `
+        export default {
+          methods: {
+            // --> EVENT LISTENERS <--
+
+            /**
+             * Triggers on save
+             */
+            onSave() {},
+
+            /**
+             * Triggers on close
+             */
+            onClose() {},
+
+            // --> ACTIONS <--
+
+            /**
+             * Saves content
+             */
+            save() {},
+
+            // --> HELPERS <--
+
+            /**
+             * Formats content
+             */
+            format() {}
+          }
+        };
+      `,
+      output: `
+        export default {
+          methods: {
+            // --> ACTIONS <--
+
+            /**
+             * Saves content
+             */
+            save() {},
+
+            // --> HELPERS <--
+
+            /**
+             * Formats content
+             */
+            format() {},
+
+            // --> EVENT LISTENERS <--
+
+            /**
+             * Triggers on save
+             */
+            onSave() {},
+
+            /**
+             * Triggers on close
+             */
+            onClose() {}
+          }
+        };
+      `,
+      errors: [
+        {
+          messageId: "unorderedSeparator"
+        },
+        {
+          messageId: "unorderedSeparator"
+        }
+      ]
+    },
     {
       code: `
         export default {
@@ -184,6 +266,16 @@ ruleTester.run("vue-methods-separator", rule, {
           }
         });
       `,
+      output: `
+        export default defineComponent({
+          methods: {
+            // --> HELPERS <--
+            format() {},
+            // --> EVENT LISTENERS <--
+            onSave() {}
+          }
+        });
+      `,
       errors: [
         {
           messageId: "unorderedSeparator"
@@ -220,6 +312,18 @@ ruleTester.run("vue-methods-separator", rule, {
         });
         </script>
       `,
+      output: `
+        <script>
+        export default defineComponent({
+          methods: {
+            // --> ACTIONS <--
+            save() {},
+            // --> EVENT LISTENERS <--
+            onSave() {}
+          }
+        });
+        </script>
+      `,
       errors: [
         {
           messageId: "unorderedSeparator"