New: unicode-bom rule to allow or disallow BOM (fixes #5502) (#6230)

conf/eslint.json

@@ -207,6 +207,7 @@
         "spaced-comment": "off",
         "strict": "off",
         "template-curly-spacing": "off",
+        "unicode-bom": "off",
         "use-isnan": "error",
         "valid-jsdoc": "off",
         "valid-typeof": "error",

docs/rules/README.md

@@ -220,6 +220,7 @@ These rules relate to style guidelines, and are therefore quite subjective:
 * [space-infix-ops](space-infix-ops.md): require spacing around operators (fixable)
 * [space-unary-ops](space-unary-ops.md): enforce consistent spacing before or after unary operators (fixable)
 * [spaced-comment](spaced-comment.md): enforce consistent spacing after the `//` or `/*` in a comment (fixable)
+* [unicode-bom](unicode-bom.md): require or disallow the Unicode BOM (fixable)
 * [wrap-regex](wrap-regex.md): require parenthesis around regex literals
 
 ## ECMAScript 6

docs/rules/unicode-bom.md

@@ -0,0 +1,65 @@
+# Require or disallow the Unicode Byte Order Mark (BOM) (unicode-bom)
+
+(fixable) The `--fix` option on the [command line](../user-guide/command-line-interface#fix) automatically fixes problems reported by this rule.
+
+The Unicode Byte Order Mark (BOM) is used to specify whether code units are big
+endian or little endian. That is, whether the most significant or least
+significant bytes come first. UTF-8 does not require a BOM because byte ordering
+does not matter when characters are a single byte. Since UTF-8 is the dominant
+encoding of the web, we make `"never"` the default option.
+
+## Rule Details
+
+If the `"always"` option is used, this rule requires that files always begin
+with the Unicode BOM character U+FEFF. If `"never"` is used, files must never
+begin with U+FEFF.
+
+## Options
+
+This rule has a string option:
+
+* `"always"` files must begin with the Unicode BOM
+* `"never"` (default) files must not begin with the Unicode BOM
+
+### always
+
+Example of **correct** code for this rule with the `"always"` option:
+
+```js
+/*eslint unicode-bom: "error"*/
+
+U+FEFF
+var abc;
+```
+
+Example of **incorrect** code for this rule with the `"always"` option:
+
+```js
+/*eslint unicode-bom: "error"*/
+
+var abc;
+```
+
+### never
+
+Example of **correct** code for this rule with the default `"never"` option:
+
+```js
+/*eslint unicode-bom: ["error", "never"]*/
+
+var abc;
+```
+
+Example of **incorrect** code for this rule with the `"never"` option:
+
+```js
+/*eslint unicode-bom: ["error", "never"]*/
+
+U+FEFF
+var abc;
+```
+
+## When Not To Use It
+
+If you use some UTF-16 or UTF-32 files and you want to allow a file to
+optionally begin with a Unicode BOM, you should turn this rule off.

lib/rules/unicode-bom.js

@@ -0,0 +1,66 @@
+/**
+ * @fileoverview Require or disallow Unicode BOM
+ * @author Andrew Johnston <https://github.com/ehjay>
+ */
+"use strict";
+
+//------------------------------------------------------------------------------
+// Rule Definition
+//------------------------------------------------------------------------------
+
+module.exports = {
+    meta: {
+        docs: {
+            description: "require or disallow Unicode BOM",
+            category: "Stylistic Issues",
+            recommended: false
+        },
+
+        fixable: "whitespace",
+
+        schema: [
+            {
+                enum: ["always", "never"]
+            }
+        ]
+    },
+
+    create: function(context) {
+
+        //--------------------------------------------------------------------------
+        // Public
+        //--------------------------------------------------------------------------
+
+        return {
+
+            Program: function checkUnicodeBOM(node) {
+
+                var sourceCode = context.getSourceCode(),
+                    location = {column: 0, line: 1},
+                    requireBOM = context.options[0] || "never";
+
+                if (!sourceCode.hasBOM && (requireBOM === "always")) {
+                    context.report({
+                        node: node,
+                        loc: location,
+                        message: "Expected Unicode BOM (Byte Order Mark).",
+                        fix: function(fixer) {
+                            return fixer.insertTextBefore(node, "\uFEFF");
+                        }
+                    });
+                } else if (sourceCode.hasBOM && (requireBOM === "never")) {
+                    context.report({
+                        node: node,
+                        loc: location,
+                        message: "Unexpected Unicode BOM (Byte Order Mark).",
+                        fix: function(fixer) {
+                            return fixer.removeRange([-1, 0]);
+                        }
+                    });
+                }
+            }
+
+        };
+
+    }
+};

tests/lib/rules/unicode-bom.js

@@ -0,0 +1,56 @@
+/**
+ * @fileoverview Check that the Unicode BOM can be required and disallowed
+ * @author Andrew Johnston <https://github.com/ehjay>
+ */
+"use strict";
+
+//------------------------------------------------------------------------------
+// Requirements
+//------------------------------------------------------------------------------
+
+var rule = require("../../../lib/rules/unicode-bom"),
+    RuleTester = require("../../../lib/testers/rule-tester");
+
+//------------------------------------------------------------------------------
+// Tests
+//------------------------------------------------------------------------------
+
+var ruleTester = new RuleTester();
+
+ruleTester.run("unicode-bom", rule, {
+
+    valid: [
+        {
+            code: "\uFEFF var a = 123;",
+            options: ["always"]
+        },
+        {
+            code: "var a = 123;",
+            options: ["never"]
+        },
+        {
+            code: "var a = 123; \uFEFF",
+            options: ["never"]
+        }
+    ],
+
+    invalid: [
+        {
+            code: "var a = 123;",
+            errors: [{ message: "Expected Unicode BOM (Byte Order Mark).", type: "Program" }],
+            options: ["always"],
+            output: "\uFEFFvar a = 123;"
+        },
+        {
+            code: "\uFEFF var a = 123;",
+            errors: [{ message: "Unexpected Unicode BOM (Byte Order Mark).", type: "Program" }],
+            output: " var a = 123;"
+        },
+        {
+            code: "\uFEFF var a = 123;",
+            errors: [{ message: "Unexpected Unicode BOM (Byte Order Mark).", type: "Program" }],
+            options: ["never"],
+            output: " var a = 123;"
+        }
+    ]
+});