New: report-message-format rule

Author: not-an-aardvark

Diff for: README.md

@@ -57,3 +57,4 @@ Additionally, you can enable all recommended rules from this plugin:
 🛠 indicates that a rule is fixable.
 
 * ✔️ 🛠 [no-deprecated-report-api](https://github.com/not-an-aardvark/eslint-plugin-eslint-plugin/blob/master/docs/rules/no-deprecated-report-api.md): Prohibits the deprecated `context.report(node, message)` API
+[report-message-format](https://github.com/not-an-aardvark/eslint-plugin-eslint-plugin/blob/master/docs/rules/report-message-format.md): Enforces a consistent format for report messages

Diff for: docs/rules/report-message-format.md

@@ -0,0 +1,67 @@
+# enforce a consistent format for rule report messages (report-message-format)
+
+It is sometimes desirable to maintain consistent formatting for all report messages. For example, you might want to mandate that all report messages begin with a capital letter and end with a period.
+
+## Rule Details
+
+This rule aims to enforce a consistent format for rule report messages.
+
+### Options
+
+This rule has a string option. The string should be a regular expression that all report messages must match.
+
+For example, in order to mandate that all report messages begin with a capital letter and end with a period, you can use the following configuration:
+
+```json
+{
+    "rules": {
+        "eslint-plugin/report-message-format": ["error", "^[A-Z].*\\.$"]
+    },
+    "plugins": [
+        "eslint-plugin"
+    ]
+}
+```
+
+Note that since this rule uses static analysis and does not actually run your code, it will attempt to match report messages *before* placeholders are inserted.
+
+The following patterns are considered warnings:
+
+```js
+/* eslint eslint-plugin/report-message-format: ["error", "^[A-Z].*\\.$"] */
+
+module.exports = {
+  meta: {},
+  create(context) {
+
+    context.report(node, 'this message does not match the regular expression.');
+
+    context.report(node, 'Neither does this one');
+
+    context.report(node, 'This will get reported, regardless of the value of the {{placeholder}}', { placeholder: foo })
+
+  }
+};
+
+```
+
+The following patterns are not warnings:
+
+```js
+
+module.exports = {
+  meta: {},
+  create(context) {
+
+    context.report(node, 'This message matches the regular expression.');
+
+    context.report(node, 'So does this one.');
+
+  }
+};
+
+```
+
+## When Not To Use It
+
+If you don't want to enforce consistent formatting for your report messages, you can turn off this rule.

Diff for: lib/rules/report-message-format.js

@@ -0,0 +1,66 @@
+/**
+ * @fileoverview enforce a consistent format for rule report messages
+ * @author Teddy Katz
+ */
+
+'use strict';
+
+const utils = require('../utils');
+
+// ------------------------------------------------------------------------------
+// Rule Definition
+// ------------------------------------------------------------------------------
+
+module.exports = {
+  meta: {
+    docs: {
+      description: 'enforce a consistent format for rule report messages',
+      category: 'Rules',
+      recommended: false,
+    },
+    fixable: null,
+    schema: [
+      { type: 'string' },
+    ],
+  },
+
+  create (context) {
+    const pattern = new RegExp(context.options[0] || '');
+    let contextIdentifiers;
+
+    // ----------------------------------------------------------------------
+    // Public
+    // ----------------------------------------------------------------------
+
+    return {
+      Program (node) {
+        contextIdentifiers = utils.getContextIdentifiers(context, node);
+      },
+      CallExpression (node) {
+        if (
+          node.callee.type === 'MemberExpression' &&
+          contextIdentifiers.has(node.callee.object) &&
+          node.callee.property.type === 'Identifier' && node.callee.property.name === 'report'
+        ) {
+          if (node.arguments.length === 1 && node.arguments[0].type !== 'ObjectExpression') {
+            return;
+          }
+
+          const message = node.arguments.length === 1
+            ? node.arguments[0].properties.find(prop =>
+              (prop.key.type === 'Literal' && prop.key.value === 'message') ||
+              (prop.key.type === 'Identifier' && prop.key.name === 'message')
+            ).value
+            : node.arguments[1];
+
+          if (
+            (message.type === 'Literal' && typeof message.value === 'string' && !pattern.test(message.value)) ||
+            (message.type === 'TemplateLiteral' && message.quasis.length === 1 && !pattern.test(message.quasis[0].value.cooked))
+          ) {
+            context.report({ node, message: `Report message does not match the pattern '${context.options[0] || ''}'.` });
+          }
+        }
+      },
+    };
+  },
+};

Diff for: lib/utils.js

@@ -85,4 +85,26 @@ module.exports = {
       ? Object.assign({ isNewStyle: !exportsIsFunction, meta: null }, exportNodes)
       : null;
   },
+
+  /**
+  * Gets all the identifiers referring to the `context` variable in a rule source file. Note that this function will
+  * only work correctly after traversing the AST has started (e.g. in the first `Program` node).
+  * @param {RuleContext} context The `context` variable for the source file itself
+  * @param {ASTNode} ast The `Program` node for the file
+  * @returns {Set<ASTNode>} A Set of all `Identifier` nodes that are references to the `context` value for the file
+  */
+  getContextIdentifiers (context, ast) {
+    const ruleInfo = module.exports.getRuleInfo(ast);
+
+    if (!ruleInfo || !ruleInfo.create.params.length || ruleInfo.create.params[0].type !== 'Identifier') {
+      return new Set();
+    }
+
+    return new Set(
+      context.getDeclaredVariables(ruleInfo.create)
+        .find(variable => variable.name === ruleInfo.create.params[0].name)
+        .references
+        .map(ref => ref.identifier)
+    );
+  },
 };

Diff for: package.json

@@ -30,6 +30,7 @@
   "devDependencies": {
     "chai": "^3.5.0",
     "dirty-chai": "^1.2.2",
+    "escope": "^3.6.0",
     "eslint": "^3.12.1",
     "eslint-config-not-an-aardvark": "^2.0.0",
     "eslint-plugin-node": "^3.0.5",

Diff for: tests/lib/rules/report-message-format.js

@@ -0,0 +1,184 @@
+/**
+ * @fileoverview enforce a consistent format for rule report messages
+ * @author Teddy Katz
+ */
+
+'use strict';
+
+// ------------------------------------------------------------------------------
+// Requirements
+// ------------------------------------------------------------------------------
+
+const rule = require('../../../lib/rules/report-message-format');
+const RuleTester = require('eslint').RuleTester;
+
+
+// ------------------------------------------------------------------------------
+// Tests
+// ------------------------------------------------------------------------------
+
+const ruleTester = new RuleTester({ parserOptions: { ecmaVersion: 6 } });
+ruleTester.run('report-message-format', rule, {
+
+  valid: [
+    // with no configuration, everything is allowed
+    'module.exports = context => context.report(node, "foo");',
+    {
+      code: `
+        module.exports = {
+          create(context) {
+            context.report(node, 'foo');
+          }
+        };
+      `,
+      options: ['foo'],
+    },
+    {
+      code: `
+        module.exports = {
+          create(context) {
+            context.report(node, 'foo');
+          }
+        };
+      `,
+      options: ['f'],
+    },
+    {
+      code: `
+        module.exports = {
+          create(context) {
+            context.report(node, message);
+          }
+        };
+      `,
+      options: ['foo'],
+    },
+    {
+      code: `
+        module.exports = {
+          create(context) {
+            context.report(node, 'not foo' + message);
+          }
+        };
+      `,
+      options: ['^foo$'],
+    },
+    {
+      code: `
+        module.exports = {
+          create(context) {
+            context.report(node, 'not foo' + message);
+          }
+        };
+      `,
+      options: ['^foo$'],
+    },
+    {
+      code: `
+        module.exports = {
+          create(context) {
+            context.report({node, message: 'foo'});
+          }
+        };
+      `,
+      options: ['^foo$'],
+    },
+    {
+      code: `
+        module.exports = {
+          create(context) {
+            context.report({node, message: 'foo'});
+          }
+        };
+      `,
+      options: ['^foo$'],
+    },
+    {
+      code: `
+        module.exports = {
+          create(context) {
+            context.report({node, message: 'foobarbaz'});
+          }
+        };
+      `,
+      options: ['bar'],
+    },
+    {
+      code: `
+        module.exports = {
+          create(context) {
+            context.report({node, message: \`foobarbaz\`});
+          }
+        };
+      `,
+      options: ['bar'],
+    },
+  ],
+
+  invalid: [
+    {
+      code: `
+        module.exports = {
+          create(context) {
+            context.report(node, 'bar');
+          }
+        };
+      `,
+      options: ['foo'],
+    },
+    {
+      code: `
+        module.exports = {
+          create(context) {
+            context.report(node, 'foobar');
+          }
+        };
+      `,
+      options: ['^foo$'],
+    },
+    {
+      code: `
+        module.exports = {
+          create(context) {
+            context.report(node, 'FOO');
+          }
+        };
+      `,
+      options: ['foo'],
+    },
+    {
+      code: `
+        module.exports = {
+          create(context) {
+            context.report(node, \`FOO\`);
+          }
+        };
+      `,
+      options: ['foo'],
+    },
+    {
+      code: `
+        module.exports = {
+          create(context) {
+            context.report({node, message: 'FOO'});
+          }
+        };
+      `,
+      options: ['foo'],
+    },
+    {
+      code: `
+        module.exports = {
+          create(context) {
+            context.report({node, message: \`FOO\`});
+          }
+        };
+      `,
+      options: ['foo'],
+    },
+  ].map(invalidCase => {
+    return Object.assign({
+      errors: [{ message: `Report message does not match the pattern '${invalidCase.options[0]}'.` }],
+    }, invalidCase);
+  }),
+});