Add note re: messaging linter line accuracy (#275)

* Add note re: messaging linter line accuracy

Line numbers in messaging linter warnings are not accurate if the
violation takes place in a partial. The issue is a bit complex and seems
to have to do with the way `remarkIncludes` manipulates the MDAST.
Before we can address #273, this change adds a note
that line numbers may not be correct for violations that take place
inside partials.

* Respond to avatus feedback

server/remark-lint-messaging.ts

@@ -81,12 +81,22 @@ function checkMessaging(
     const re = new RegExp(rule.incorrect);
     const badText = text.match(re);
     if (text.match(re)) {
+      let extras = "";
+      if (part == PageLocation.Body || part == PageLocation.Headers) {
+        extras +=
+          " (Note that the line number is not accurate if the issue occurs inside a partial.)";
+      }
+      if (part == PageLocation.Comments) {
+        extras +=
+          " (Note that the line number refers to the first line in the code snippet where the issue occurs, and is not accurate if the issue occurs inside a partial.)";
+      }
       file.message(
         `Incorrect messaging: "${badText[0]}" (${getReadableLocation(
           part
         )}). ` +
           `${rule.explanation}. You should ${rule.correct}. ` +
-          'Add "{/*lint ignore messaging*/}" above this line to bypass the linter.',
+          'Add "{/*lint ignore messaging*/}" above this line to bypass the linter.' +
+          extras,
         pos
       );
     }

uvu-tests/remark-messaging.test.ts

@@ -82,7 +82,8 @@ install these services when getting started with Teleport.
   const expectedErrors = [
     'Incorrect messaging: "auth and proxy" (in body text). ' +
       'You must capitalize product names. You should use "Auth and Proxy Services" instead. ' +
-      'Add "{/*lint ignore messaging*/}" above this line to bypass the linter.',
+      'Add "{/*lint ignore messaging*/}" above this line to bypass the linter.' +
+      " (Note that the line number is not accurate if the issue occurs inside a partial.)",
   ];
 
   assert.equal(getErrors(result), expectedErrors);
@@ -102,7 +103,8 @@ In this guide, we will explain how to set up Teleport to access Kubernetes.
     'Incorrect messaging: "Kubernetes Access" (in header). Focus our messaging ' +
       "on a single product, rather than multiple. You should use " +
       '"registering a Kubernetes cluster" instead. ' +
-      'Add "{/*lint ignore messaging*/}" above this line to bypass the linter.',
+      'Add "{/*lint ignore messaging*/}" above this line to bypass the linter. ' +
+      "(Note that the line number is not accurate if the issue occurs inside a partial.)",
   ];
 
   const result = transformer({
@@ -179,15 +181,22 @@ func myfunc(s string){
   const expectedErrors = [
     'Incorrect messaging: "auth and proxy" (in code comment). You must capitalize product ' +
       'names. You should use "Auth and Proxy Services" instead. ' +
-      'Add "{/*lint ignore messaging*/}" above this line to bypass the linter.',
+      'Add "{/*lint ignore messaging*/}" above this line to bypass the linter.' +
+      " (Note that the line number refers to the first line in the code snippet" +
+      " where the issue occurs, and is not accurate if the issue occurs inside a partial.)",
+
     'Incorrect messaging: "Kubernetes Access" (in code comment). Focus our messaging on a ' +
       'single product, rather than multiple. You should use "registering a ' +
       'Kubernetes cluster" instead. ' +
-      'Add "{/*lint ignore messaging*/}" above this line to bypass the linter.',
+      'Add "{/*lint ignore messaging*/}" above this line to bypass the linter.' +
+      " (Note that the line number refers to the first line in the code snippet" +
+      " where the issue occurs, and is not accurate if the issue occurs inside a partial.)",
     'Incorrect messaging: "machine id" (in code comment). See our Core Concepts page: ' +
       "https://goteleport.com/docs/core-concepts. " +
       "You should capitalize the names of Teleport services. " +
-      'Add "{/*lint ignore messaging*/}" above this line to bypass the linter.',
+      'Add "{/*lint ignore messaging*/}" above this line to bypass the linter.' +
+      " (Note that the line number refers to the first line in the code snippet" +
+      " where the issue occurs, and is not accurate if the issue occurs inside a partial.)",
   ];
 
   assert.equal(getErrors(result), expectedErrors);