feat: text-escaping rule; fixes #864

Author: brettz9

.README/README.md

@@ -587,4 +587,5 @@ selector).
 {"gitdown": "include", "file": "./rules/require-yields-check.md"}
 {"gitdown": "include", "file": "./rules/sort-tags.md"}
 {"gitdown": "include", "file": "./rules/tag-lines.md"}
+{"gitdown": "include", "file": "./rules/text-escaping.md"}
 {"gitdown": "include", "file": "./rules/valid-types.md"}

.README/rules/text-escaping.md

@@ -0,0 +1,30 @@
+### `text-escaping`
+
+This rule can auto-escape certain characters that are input within block and
+tag descriptions.
+
+This rule may be desirable if your text is known not to contain HTML or
+Markdown and you therefore do not wish for it to be accidentally interpreted
+as such by the likes of Visual Studio Code or if you wish to view it escaped
+within it or your documentation.
+
+#### Options
+
+##### `escapeHTML`
+
+This option escapes all `<` and `&` characters (except those followed by
+whitespace which are treated as literals by Visual Studio Code).
+
+##### `escapeMarkdown`
+
+This option escapes the first backtick (`` ` ``) in a paired sequence.
+
+|||
+|---|---|
+|Context|everywhere|
+|Tags|``|
+|Recommended|false|
+|Settings||
+|Options||
+
+<!-- assertions textEscaping -->

README.md

@@ -72,6 +72,7 @@ JSDoc linting rules for ESLint.
         * [`require-yields-check`](#user-content-eslint-plugin-jsdoc-rules-require-yields-check)
         * [`sort-tags`](#user-content-eslint-plugin-jsdoc-rules-sort-tags)
         * [`tag-lines`](#user-content-eslint-plugin-jsdoc-rules-tag-lines)
+        * [`text-escaping`](#user-content-eslint-plugin-jsdoc-rules-text-escaping)
         * [`valid-types`](#user-content-eslint-plugin-jsdoc-rules-valid-types)
 
 
@@ -22100,6 +22101,155 @@ The following patterns are not considered problems:
 ````
 
 
+<a name="user-content-eslint-plugin-jsdoc-rules-text-escaping"></a>
+<a name="eslint-plugin-jsdoc-rules-text-escaping"></a>
+### <code>text-escaping</code>
+
+This rule can auto-escape certain characters that are input within block and
+tag descriptions.
+
+This rule may be desirable if your text is known not to contain HTML or
+Markdown and you therefore do not wish for it to be accidentally interpreted
+as such by the likes of Visual Studio Code or if you wish to view it escaped
+within it or your documentation.
+
+<a name="user-content-eslint-plugin-jsdoc-rules-text-escaping-options-42"></a>
+<a name="eslint-plugin-jsdoc-rules-text-escaping-options-42"></a>
+#### Options
+
+<a name="user-content-eslint-plugin-jsdoc-rules-text-escaping-options-42-escapehtml"></a>
+<a name="eslint-plugin-jsdoc-rules-text-escaping-options-42-escapehtml"></a>
+##### <code>escapeHTML</code>
+
+This option escapes all `<` and `&` characters (except those followed by
+whitespace which are treated as literals by Visual Studio Code).
+
+<a name="user-content-eslint-plugin-jsdoc-rules-text-escaping-options-42-escapemarkdown"></a>
+<a name="eslint-plugin-jsdoc-rules-text-escaping-options-42-escapemarkdown"></a>
+##### <code>escapeMarkdown</code>
+
+This option escapes the first backtick (`` ` ``) in a paired sequence.
+
+|||
+|---|---|
+|Context|everywhere|
+|Tags|``|
+|Recommended|false|
+|Settings||
+|Options||
+
+The following patterns are considered problems:
+
+````js
+/**
+ * Some things to escape: <a> and &gt; and `test`
+ */
+// Message: You must include either `escapeHTML` or `escapeMarkdown`
+
+/**
+ * Some things to escape: <a> and &gt; and &#xabc; and `test`
+ */
+// "jsdoc/text-escaping": ["error"|"warn", {"escapeHTML":true}]
+// Message: You have unescaped HTML characters < or &
+
+/**
+ * Some things to escape: <a> and &gt; and `test`
+ */
+// "jsdoc/text-escaping": ["error"|"warn", {"escapeMarkdown":true}]
+// Message: You have unescaped Markdown backtick sequences
+
+/**
+ * Some things to escape:
+ * <a> and &gt; and `test`
+ */
+// "jsdoc/text-escaping": ["error"|"warn", {"escapeHTML":true}]
+// Message: You have unescaped HTML characters < or &
+
+/**
+ * Some things to escape:
+ * <a> and &gt; and `test`
+ */
+// "jsdoc/text-escaping": ["error"|"warn", {"escapeMarkdown":true}]
+// Message: You have unescaped Markdown backtick sequences
+
+/**
+ * @param {SomeType} aName Some things to escape: <a> and &gt; and `test`
+ */
+// "jsdoc/text-escaping": ["error"|"warn", {"escapeHTML":true}]
+// Message: You have unescaped HTML characters < or & in a tag
+
+/**
+ * @param {SomeType} aName Some things to escape: <a> and &gt; and `test`
+ */
+// "jsdoc/text-escaping": ["error"|"warn", {"escapeMarkdown":true}]
+// Message: You have unescaped Markdown backtick sequences in a tag
+
+/**
+ * @param {SomeType} aName Some things to escape:
+ * <a> and &gt; and `test`
+ */
+// "jsdoc/text-escaping": ["error"|"warn", {"escapeHTML":true}]
+// Message: You have unescaped HTML characters < or & in a tag
+
+/**
+ * @param {SomeType} aName Some things to escape:
+ * <a> and &gt; and `test`
+ */
+// "jsdoc/text-escaping": ["error"|"warn", {"escapeMarkdown":true}]
+// Message: You have unescaped Markdown backtick sequences in a tag
+````
+
+The following patterns are not considered problems:
+
+````js
+/**
+ * Some things to escape: &lt;a> and &gt; and `test`
+ */
+// "jsdoc/text-escaping": ["error"|"warn", {"escapeHTML":true}]
+
+/**
+ * Some things to escape: <a> and &gt; and \`test`
+ */
+// "jsdoc/text-escaping": ["error"|"warn", {"escapeMarkdown":true}]
+
+/**
+ * Some things to escape: < and &
+ */
+// "jsdoc/text-escaping": ["error"|"warn", {"escapeHTML":true}]
+
+/**
+ * Some things to escape: `
+ */
+// "jsdoc/text-escaping": ["error"|"warn", {"escapeMarkdown":true}]
+
+/**
+ * @param {SomeType} aName Some things to escape: &lt;a> and &gt; and `test`
+ */
+// "jsdoc/text-escaping": ["error"|"warn", {"escapeHTML":true}]
+
+/**
+ * @param {SomeType} aName Some things to escape: <a> and &gt; and \`test`
+ */
+// "jsdoc/text-escaping": ["error"|"warn", {"escapeMarkdown":true}]
+
+/**
+ * @param {SomeType} aName Some things to escape: < and &
+ */
+// "jsdoc/text-escaping": ["error"|"warn", {"escapeHTML":true}]
+
+/**
+ * @param {SomeType} aName Some things to escape: `
+ */
+// "jsdoc/text-escaping": ["error"|"warn", {"escapeMarkdown":true}]
+
+/**
+ * Nothing
+ * to escape
+ */
+// "jsdoc/text-escaping": ["error"|"warn", {"escapeHTML":true}]
+````
+
+
 <a name="user-content-eslint-plugin-jsdoc-rules-valid-types"></a>
 <a name="eslint-plugin-jsdoc-rules-valid-types"></a>
 ### <code>valid-types</code>
@@ -22181,8 +22331,8 @@ for valid types (based on the tag's `type` value), and either portion checked
 for presence (based on `false` `name` or `type` values or their `required`
 value). See the setting for more details.
 
-<a name="user-content-eslint-plugin-jsdoc-rules-valid-types-options-42"></a>
-<a name="eslint-plugin-jsdoc-rules-valid-types-options-42"></a>
+<a name="user-content-eslint-plugin-jsdoc-rules-valid-types-options-43"></a>
+<a name="eslint-plugin-jsdoc-rules-valid-types-options-43"></a>
 #### Options
 
 - `allowEmptyNamepaths` (default: true) - Set to `false` to bulk disallow

src/index.js

@@ -46,6 +46,7 @@ import requireYields from './rules/requireYields';
 import requireYieldsCheck from './rules/requireYieldsCheck';
 import sortTags from './rules/sortTags';
 import tagLines from './rules/tagLines';
+import textEscaping from './rules/textEscaping';
 import validTypes from './rules/validTypes';
 
 export default {
@@ -103,6 +104,7 @@ export default {
         'jsdoc/require-yields-check': 'warn',
         'jsdoc/sort-tags': 'off',
         'jsdoc/tag-lines': 'warn',
+        'jsdoc/text-escaping': 'off',
         'jsdoc/valid-types': 'warn',
       },
     },
@@ -156,6 +158,7 @@ export default {
     'require-yields-check': requireYieldsCheck,
     'sort-tags': sortTags,
     'tag-lines': tagLines,
+    'text-escaping': textEscaping,
     'valid-types': validTypes,
   },
 };

src/iterateJsdoc.js

@@ -144,7 +144,7 @@ const getUtils = (
     return jsdocUtils.getRegexFromString(str, requiredFlags);
   };
 
-  utils.getTagDescription = (tg) => {
+  utils.getTagDescription = (tg, returnArray) => {
     const descriptions = [];
     tg.source.some(({
       tokens: {
@@ -179,7 +179,26 @@ const getUtils = (
       return false;
     });
 
-    return descriptions.join('\n');
+    return returnArray ? descriptions : descriptions.join('\n');
+  };
+
+  utils.setTagDescription = (tg, matcher, setter) => {
+    let finalIdx = 0;
+    tg.source.some(({
+      tokens: {
+        description,
+      },
+    }, idx) => {
+      if (description && matcher.test(description)) {
+        tg.source[idx].tokens.description = setter(description);
+        finalIdx = idx;
+        return true;
+      }
+
+      return false;
+    });
+
+    return finalIdx;
   };
 
   utils.getDescription = () => {
@@ -207,10 +226,37 @@ const getUtils = (
 
     return {
       description: descriptions.join('\n'),
+      descriptions,
       lastDescriptionLine,
     };
   };
 
+  utils.setDescriptionLines = (matcher, setter) => {
+    let finalIdx = 0;
+    jsdoc.source.some(({
+      tokens: {
+        description,
+        tag,
+        end,
+      },
+    }, idx) => {
+      // istanbul ignore if -- Already checked
+      if (idx && (tag || end)) {
+        return true;
+      }
+
+      if (description && matcher.test(description)) {
+        jsdoc.source[idx].tokens.description = setter(description);
+        finalIdx = idx;
+        return true;
+      }
+
+      return false;
+    });
+
+    return finalIdx;
+  };
+
   utils.changeTag = (tag, ...tokens) => {
     for (const [
       idx,

src/rules/textEscaping.js

@@ -0,0 +1,130 @@
+import iterateJsdoc from '../iterateJsdoc';
+
+// We could disallow raw gt, quot, and apos, but allow for parity; but we do
+//  not allow hex or decimal character references
+const htmlRegex = /(<|&(?!(?:amp|lt|gt|quot|apos);))(?=\S)/u;
+const markdownRegex = /(?<!\\)(`+)([^`]+)\1(?!`)/u;
+
+const htmlReplacer = (desc) => {
+  return desc.replace(new RegExp(htmlRegex, 'gu'), (_) => {
+    if (_ === '<') {
+      return '&lt;';
+    }
+
+    return '&amp;';
+  });
+};
+
+const markdownReplacer = (desc) => {
+  return desc.replace(new RegExp(markdownRegex, 'gu'), (_, backticks, encapsed) => {
+    const bookend = '`'.repeat(backticks.length);
+    return `\\${bookend}${encapsed}${bookend}`;
+  });
+};
+
+export default iterateJsdoc(({
+  context,
+  jsdoc,
+  utils,
+}) => {
+  const {
+    escapeHTML,
+    escapeMarkdown,
+  } = context.options[0] || {};
+
+  if (!escapeHTML && !escapeMarkdown) {
+    context.report({
+      loc: {
+        start: {
+          column: 1,
+          line: 1,
+        },
+      },
+      message: 'You must include either `escapeHTML` or `escapeMarkdown`',
+    });
+    return;
+  }
+
+  const {
+    descriptions,
+  } = utils.getDescription();
+
+  if (escapeHTML) {
+    if (descriptions.some((desc) => {
+      return htmlRegex.test(desc);
+    })) {
+      const line = utils.setDescriptionLines(htmlRegex, htmlReplacer);
+      utils.reportJSDoc('You have unescaped HTML characters < or &', {
+        line,
+      }, () => {}, true);
+      return;
+    }
+
+    for (const tag of jsdoc.tags) {
+      if (utils.getTagDescription(tag, true).some((desc) => {
+        return htmlRegex.test(desc);
+      })) {
+        const line = utils.setTagDescription(tag, htmlRegex, htmlReplacer) +
+          tag.source[0].number;
+        utils.reportJSDoc('You have unescaped HTML characters < or & in a tag', {
+          line,
+        }, () => {}, true);
+      }
+    }
+
+    return;
+  }
+
+  if (descriptions.some((desc) => {
+    return markdownRegex.test(desc);
+  })) {
+    const line = utils.setDescriptionLines(markdownRegex, markdownReplacer);
+    utils.reportJSDoc('You have unescaped Markdown backtick sequences', {
+      line,
+    }, () => {}, true);
+    return;
+  }
+
+  for (const tag of jsdoc.tags) {
+    if (utils.getTagDescription(tag, true).some((desc) => {
+      return markdownRegex.test(desc);
+    })) {
+      const line = utils.setTagDescription(
+        tag, markdownRegex, markdownReplacer,
+      ) + tag.source[0].number;
+      utils.reportJSDoc(
+        'You have unescaped Markdown backtick sequences in a tag',
+        {
+          line,
+        },
+        () => {},
+        true,
+      );
+    }
+  }
+}, {
+  iterateAllJsdocs: true,
+  meta: {
+    docs: {
+      description: '',
+      url: 'https://github.com/gajus/eslint-plugin-jsdoc#eslint-plugin-jsdoc-rules-text-escaping',
+    },
+    fixable: 'code',
+    schema: [
+      {
+        additionalProperies: false,
+        properties: {
+          // Option properties here (or remove the object)
+          escapeHTML: {
+            type: 'boolean',
+          },
+          escapeMarkdown: {
+            type: 'boolean',
+          },
+        },
+        type: 'object',
+      },
+    ],
+    type: 'suggestion',
+  },
+});

test/rules/assertions/textEscaping.js

@@ -0,0 +1,320 @@
+export default {
+  invalid: [
+    {
+      code: `
+        /**
+         * Some things to escape: <a> and &gt; and \`test\`
+         */
+      `,
+      errors: [
+        {
+          line: 1,
+          message: 'You must include either `escapeHTML` or `escapeMarkdown`',
+        },
+      ],
+    },
+    {
+      code: `
+        /**
+         * Some things to escape: <a> and &gt; and &#xabc; and \`test\`
+         */
+      `,
+      errors: [
+        {
+          line: 3,
+          message: 'You have unescaped HTML characters < or &',
+        },
+      ],
+      options: [
+        {
+          escapeHTML: true,
+        },
+      ],
+      output: `
+        /**
+         * Some things to escape: &lt;a> and &gt; and &amp;#xabc; and \`test\`
+         */
+      `,
+    },
+    {
+      code: `
+        /**
+         * Some things to escape: <a> and &gt; and \`test\`
+         */
+      `,
+      errors: [
+        {
+          line: 3,
+          message: 'You have unescaped Markdown backtick sequences',
+        },
+      ],
+      options: [
+        {
+          escapeMarkdown: true,
+        },
+      ],
+      output: `
+        /**
+         * Some things to escape: <a> and &gt; and \\\`test\`
+         */
+      `,
+    },
+    {
+      code: `
+        /**
+         * Some things to escape:
+         * <a> and &gt; and \`test\`
+         */
+      `,
+      errors: [
+        {
+          line: 4,
+          message: 'You have unescaped HTML characters < or &',
+        },
+      ],
+      options: [
+        {
+          escapeHTML: true,
+        },
+      ],
+      output: `
+        /**
+         * Some things to escape:
+         * &lt;a> and &gt; and \`test\`
+         */
+      `,
+    },
+    {
+      code: `
+        /**
+         * Some things to escape:
+         * <a> and &gt; and \`test\`
+         */
+      `,
+      errors: [
+        {
+          line: 4,
+          message: 'You have unescaped Markdown backtick sequences',
+        },
+      ],
+      options: [
+        {
+          escapeMarkdown: true,
+        },
+      ],
+      output: `
+        /**
+         * Some things to escape:
+         * <a> and &gt; and \\\`test\`
+         */
+      `,
+    },
+    {
+      code: `
+        /**
+         * @param {SomeType} aName Some things to escape: <a> and &gt; and \`test\`
+         */
+      `,
+      errors: [
+        {
+          line: 3,
+          message: 'You have unescaped HTML characters < or & in a tag',
+        },
+      ],
+      options: [
+        {
+          escapeHTML: true,
+        },
+      ],
+      output: `
+        /**
+         * @param {SomeType} aName Some things to escape: &lt;a> and &gt; and \`test\`
+         */
+      `,
+    },
+    {
+      code: `
+        /**
+         * @param {SomeType} aName Some things to escape: <a> and &gt; and \`test\`
+         */
+      `,
+      errors: [
+        {
+          line: 3,
+          message: 'You have unescaped Markdown backtick sequences in a tag',
+        },
+      ],
+      options: [
+        {
+          escapeMarkdown: true,
+        },
+      ],
+      output: `
+        /**
+         * @param {SomeType} aName Some things to escape: <a> and &gt; and \\\`test\`
+         */
+      `,
+    },
+    {
+      code: `
+        /**
+         * @param {SomeType} aName Some things to escape:
+         * <a> and &gt; and \`test\`
+         */
+      `,
+      errors: [
+        {
+          line: 4,
+          message: 'You have unescaped HTML characters < or & in a tag',
+        },
+      ],
+      options: [
+        {
+          escapeHTML: true,
+        },
+      ],
+      output: `
+        /**
+         * @param {SomeType} aName Some things to escape:
+         * &lt;a> and &gt; and \`test\`
+         */
+      `,
+    },
+    {
+      code: `
+        /**
+         * @param {SomeType} aName Some things to escape:
+         * <a> and &gt; and \`test\`
+         */
+      `,
+      errors: [
+        {
+          line: 4,
+          message: 'You have unescaped Markdown backtick sequences in a tag',
+        },
+      ],
+      options: [
+        {
+          escapeMarkdown: true,
+        },
+      ],
+      output: `
+        /**
+         * @param {SomeType} aName Some things to escape:
+         * <a> and &gt; and \\\`test\`
+         */
+      `,
+    },
+  ],
+  valid: [
+    {
+      code: `
+        /**
+         * Some things to escape: &lt;a> and &gt; and \`test\`
+         */
+      `,
+      options: [
+        {
+          escapeHTML: true,
+        },
+      ],
+    },
+    {
+      code: `
+        /**
+         * Some things to escape: <a> and &gt; and \\\`test\`
+         */
+      `,
+      options: [
+        {
+          escapeMarkdown: true,
+        },
+      ],
+    },
+    {
+      code: `
+        /**
+         * Some things to escape: < and &
+         */
+      `,
+      options: [
+        {
+          escapeHTML: true,
+        },
+      ],
+    },
+    {
+      code: `
+        /**
+         * Some things to escape: \`
+         */
+      `,
+      options: [
+        {
+          escapeMarkdown: true,
+        },
+      ],
+    },
+    {
+      code: `
+        /**
+         * @param {SomeType} aName Some things to escape: &lt;a> and &gt; and \`test\`
+         */
+      `,
+      options: [
+        {
+          escapeHTML: true,
+        },
+      ],
+    },
+    {
+      code: `
+        /**
+         * @param {SomeType} aName Some things to escape: <a> and &gt; and \\\`test\`
+         */
+      `,
+      options: [
+        {
+          escapeMarkdown: true,
+        },
+      ],
+    },
+    {
+      code: `
+        /**
+         * @param {SomeType} aName Some things to escape: < and &
+         */
+      `,
+      options: [
+        {
+          escapeHTML: true,
+        },
+      ],
+    },
+    {
+      code: `
+        /**
+         * @param {SomeType} aName Some things to escape: \`
+         */
+      `,
+      options: [
+        {
+          escapeMarkdown: true,
+        },
+      ],
+    },
+    {
+      code: `
+        /**
+         * Nothing
+         * to escape
+         */
+      `,
+      options: [
+        {
+          escapeHTML: true,
+        },
+      ],
+    },
+  ],
+};

test/rules/ruleNames.json

@@ -47,5 +47,6 @@
   "require-yields-check",
   "sort-tags",
   "tag-lines",
+  "text-escaping",
   "valid-types"
 ]