Add commentPattern option to override the whole comment pattern (#2)

A new configuration to override the main comment pattern as a more flexible way of making this rule work with individual project requirements.

For instance, the [Atlassian for VS Code](https://marketplace.visualstudio.com/items?itemName=Atlassian.atlascode) extension resolves issues in comments with the following format: `TODO: [PROJ-123]`. Also, some VS Code extensions for highlighting `TODO`s require a colon after the term (e.g. `TODO: some text`).

Author: utluiz

docs/rules/ticket-ref.md

@@ -1,6 +1,6 @@
 # Require a ticket reference in the TODO comment (ticket-ref)
 
-Adding a `TODO` comment that will be addressed in the future should have a corresponding ticket (AKA issue) in the project backlog so the team doesn't lose track of the pending work.
+Adding a `TODO` comment that will be addressed in the future should have a corresponding ticket (AKA issue) in the project backlog, so the team doesn't lose track of the pending work.
 
 ## Fail 🛑
 
@@ -26,6 +26,20 @@ Examples of **correct** code for this rule:
 
 ## Options
 
+### commentPattern
+
+This option overrides the overall comment pattern that matches both term and ticket. When used, `term` and `pattern` options are ignored. Expects a regex string.
+
+For example, let's say your IDE or tooling expects a different comment pattern such as `TODO: [PROJ-123]`, you would configure this rule like:
+
+```json
+{
+  "rules": {
+    "todo-plz/ticket-ref": ["error", { "commentPattern": "TODO:\\s\\[(PROJ-[0-9]+[,\\s]*)+\\]" }]
+  }
+}
+```
+
 ### pattern
 
 This option controls what the ticket pattern is to match against. Expects a regex string.

lib/rules/ticket-ref.js

@@ -7,12 +7,17 @@
 const messages = {
   missingTicket:
     "{{ term }} comment doesn't reference a ticket number. Ticket pattern: {{ pattern }}",
+  missingTicketWithCommentPattern:
+    "{{ term }} comment doesn't reference a ticket number. Comment pattern: {{ commentPattern }}",
 };
 
 const schema = [
   {
     type: "object",
     properties: {
+      commentPattern: {
+        type: "string",
+      },
       pattern: {
         type: "string",
       },
@@ -27,7 +32,7 @@ const schema = [
 ];
 
 function create(context) {
-  const { pattern, terms } = {
+  const { commentPattern, pattern, terms } = {
     terms: ["TODO"],
     ...context.options[0],
   };
@@ -37,7 +42,7 @@ function create(context) {
 
   terms.forEach((term) => {
     termSearchPatterns[term] = new RegExp(
-      `${term}\\s?\\((${pattern}[,\\s]*)+\\)`,
+      commentPattern || `${term}\\s?\\((${pattern}[,\\s]*)+\\)`,
       "i"
     );
   });
@@ -59,8 +64,8 @@ function create(context) {
 
       context.report({
         loc: comment.loc,
-        messageId: "missingTicket",
-        data: { pattern, term },
+        messageId: commentPattern ? "missingTicketWithCommentPattern" : "missingTicket",
+        data: { commentPattern, pattern, term },
       });
     });
   }

tests/integration/.eslintrc

@@ -2,5 +2,13 @@
   "plugins": ["todo-plz"],
   "rules": {
     "todo-plz/ticket-ref": ["error", { "pattern": "PROJ-[0-9]+" }]
-  }
+  },
+  "overrides": [
+    {
+      "files": ["commentPattern.js"],
+      "rules": {
+        "todo-plz/ticket-ref": ["error", { "commentPattern": "TODO:\\s\\[(PROJ-[0-9]+[,\\s]*)+\\]" }]
+      }
+    }
+  ]
 }

tests/integration/commentPattern.js

@@ -0,0 +1,5 @@
+// TODO: [PROJ-1] Good
+console.log("[Rule] ticket-ref: This is fine.");
+
+// TODO (PROJ-1): Bad
+console.log("[Rule] ticket-ref: This is bad.");

tests/ticket-ref.js

@@ -5,6 +5,8 @@ const ruleTester = new RuleTester();
 const messages = {
   missingTodoTicket:
     "TODO comment doesn't reference a ticket number. Ticket pattern: PROJ-[0-9]+",
+  missingTodoTicketWithCommentPattern:
+    "TODO comment doesn't reference a ticket number. Comment pattern: TODO:\\s\\[(PROJ-[0-9]+[,\\s]*)+\\]",
   missingFixmeTicket:
     "FIXME comment doesn't reference a ticket number. Ticket pattern: PROJ-[0-9]+",
 };
@@ -13,6 +15,8 @@ const options = {
   jira: { pattern: "PROJ-[0-9]+" },
 };
 
+const commentPattern = "TODO:\\s\\[(PROJ-[0-9]+[,\\s]*)+\\]"
+
 ruleTester.run("ticket-ref", rule, {
   valid: [
     {
@@ -66,6 +70,18 @@ ruleTester.run("ticket-ref", rule, {
       code: "// FIXME (PROJ-2): Connect to the API",
       options: [{ pattern: "PROJ-[0-9]+", terms: ["FIXME"] }],
     },
+    {
+      code: "// TODO: [PROJ-2] Connect to the API",
+      options: [{ commentPattern }],
+    },
+    {
+      code: `/**
+              * Description
+              * TODO: [PROJ-123] Connect to the API
+              * @returns {string}
+              */`,
+      options: [{ commentPattern }],
+    },
   ],
 
   invalid: [
@@ -105,5 +121,10 @@ ruleTester.run("ticket-ref", rule, {
       errors: [{ message: messages.missingFixmeTicket }],
       options: [{ pattern: "PROJ-[0-9]+", terms: ["FIXME"] }],
     },
+    {
+      code: "// TODO (PROJ-123) Connect to the API",
+      errors: [{ message: messages.missingTodoTicketWithCommentPattern }],
+      options: [{ commentPattern }],
+    },
   ],
 });