Allow disable without enable when disable covers the whole file (#8)

* Move `lte` to `utils` for reuse
* Add `disable-enable-pair` `allowWholeFile` option
* Reimplement with "eslint@~3.1.0" compatibility in mind
* Add documentation of `allowWholeFile` option

Author: futpib

docs/rules/disable-enable-pair.md

@@ -41,3 +41,32 @@ var foo = bar()
 var foo = bar()
 /*eslint-enable*/
 ```
+
+## Options
+
+The `allowWholeFile` option lets you allow disabling rules for the entire file while still catching "open" `eslint-disable` directives in the middle of a file.
+
+```json
+{
+    "eslint-comments/disable-enable-pair": ["error", {"allowWholeFile": true}]
+}
+```
+
+Examples of :-1: **incorrect** code for this rule:
+
+```js
+/*eslint-disable no-undef */
+var foo = bar()
+/*eslint-disable no-unused-vars */
+var fizz = buzz()
+```
+
+Examples of :+1: **correct** code for this rule:
+
+```js
+/*eslint-disable no-undef */
+var foo = bar()
+/*eslint-disable no-unused-vars */
+var fizz = buzz()
+/*eslint-enable no-unused-vars */
+```

lib/disabled-area.js

@@ -5,6 +5,12 @@
  */
 "use strict"
 
+//------------------------------------------------------------------------------
+// Requirements
+//------------------------------------------------------------------------------
+
+const utils = require("./utils")
+
 //------------------------------------------------------------------------------
 // Helpers
 //------------------------------------------------------------------------------
@@ -13,18 +19,6 @@ const COMMENT_DIRECTIVE = /^\s*(eslint-(?:en|dis)able(?:(?:-next)?-line)?)\s*(?:
 const DELIMITER = /[\s,]+/g
 const pool = new WeakMap()
 
-/**
- * Checks `a` is less than `b` or `a` equals `b`.
- *
- * @param {{line: number, column: number}} a - A location to compare.
- * @param {{line: number, column: number}} b - Another location to compare.
- * @returns {boolean} `true` if `a` is less than `b` or `a` equals `b`.
- * @private
- */
-function lte(a, b) {
-    return a.line < b.line || (a.line === b.line && a.column <= b.column)
-}
-
 //------------------------------------------------------------------------------
 // Exports
 //------------------------------------------------------------------------------
@@ -171,8 +165,8 @@ module.exports = class DisabledArea {
             const area = this.areas[i]
 
             if ((area.ruleId === null || area.ruleId === ruleId) &&
-                lte(area.start, location) &&
-                (area.end === null || lte(location, area.end))
+                utils.lte(area.start, location) &&
+                (area.end === null || utils.lte(location, area.end))
             ) {
                 return area
             }

lib/rules/disable-enable-pair.js

@@ -12,6 +12,41 @@
 const DisabledArea = require("../disabled-area")
 const utils = require("../utils")
 
+//------------------------------------------------------------------------------
+// Helpers
+//------------------------------------------------------------------------------
+
+/**
+ * Checks whether `disabledArea` covers `node`.
+ *
+ * @param {DisabledArea} disabledArea - Disabled area in question.
+ * @param {Node} node - The node that might be covered.
+ * @returns {boolean} `true` if `disabledArea` covers `node`.
+ * @private
+ */
+function disabledAreaCoversNode(disabledArea, node) {
+    return utils.lte(disabledArea.start, node.loc.start) &&
+        (!disabledArea.end || utils.lte(node.loc.end, disabledArea.end))
+}
+
+/**
+ * Checks whether `disabledArea` covers `node`'s body.
+ *
+ * @param {DisabledArea} disabledArea - Disabled area in question.
+ * @param {Node} node - The node whose body may or may not be covered.
+ * Must have a `body` property (a Program or BlockStatement will do).
+ * @returns {boolean} `true` if `disabledArea` covers `node`'s body.
+ * @private
+ */
+function disabledAreaCoversNodeBody(disabledArea, node) {
+    const body = node.body
+    const first = body[0]
+    const last = body[body.length - 1]
+    return !first ||
+        (disabledAreaCoversNode(disabledArea, first) &&
+         disabledAreaCoversNode(disabledArea, last))
+}
+
 //------------------------------------------------------------------------------
 // Rule Definition
 //------------------------------------------------------------------------------
@@ -24,20 +59,39 @@ module.exports = {
             recommended: false,
         },
         fixable: false,
-        schema: [],
+        schema: [{
+            type: "object",
+            properties: {
+                allowWholeFile: {
+                    type: "boolean",
+                },
+            },
+            additionalProperties: false,
+        }],
     },
 
     create(context) {
+        const allowWholeFile = context.options[0] && context.options[0].allowWholeFile
+
         const sourceCode = context.getSourceCode()
         const disabledArea = DisabledArea.get(sourceCode)
 
+        const firstDisabledArea = disabledArea.areas[0]
+
         return {
-            Program() {
+            Program(node) {
                 for (const area of disabledArea.areas) {
                     if (area.end != null) {
                         continue
                     }
 
+                    if (allowWholeFile &&
+                        area === firstDisabledArea &&
+                        disabledAreaCoversNodeBody(area, node)
+                    ) {
+                        continue
+                    }
+
                     context.report({
                         loc: utils.toRuleIdLocation(area.comment, area.ruleId),
                         message: (area.ruleId) ?

lib/utils.js

@@ -93,4 +93,15 @@ module.exports = {
         /*istanbul ignore next : foolproof */
         return comment.loc
     },
+
+    /**
+     * Checks `a` is less than `b` or `a` equals `b`.
+     *
+     * @param {{line: number, column: number}} a - A location to compare.
+     * @param {{line: number, column: number}} b - Another location to compare.
+     * @returns {boolean} `true` if `a` is less than `b` or `a` equals `b`.
+     */
+    lte(a, b) {
+        return a.line < b.line || (a.line === b.line && a.column <= b.column)
+    },
 }

tests/lib/rules/disable-enable-pair.js

@@ -47,6 +47,38 @@ function foo() {
 /*eslint-enable*/
 /*eslint-enable*/
 `,
+        {
+            code: `
+console.log('This code does not even have any special comments')
+`,
+            options: [{ allowWholeFile: true }],
+        },
+        {
+            code: `
+/*eslint-disable*/
+`,
+            options: [{ allowWholeFile: true }],
+        },
+        {
+            code: `
+/*eslint-disable no-undef*/
+/*eslint-disable no-unused-vars*/
+/*eslint-enable*/
+`,
+            options: [{ allowWholeFile: true }],
+        },
+        {
+            code: `
+
+/**
+ * @file This test case makes sure comments and blank lines
+ * before "whole-file" eslint-disable are allowed.
+ */
+
+/*eslint-disable*/
+`,
+            options: [{ allowWholeFile: true }],
+        },
     ],
     invalid: [
         {
@@ -108,5 +140,55 @@ function foo() {
                 },
             ],
         },
+        {
+            code: `
+/*eslint-disable no-undef*/
+console.log();
+/*eslint-disable no-unused-vars*/
+`,
+            options: [{ allowWholeFile: true }],
+            errors: [
+                {
+                    message: "Requires 'eslint-enable' directive for 'no-unused-vars'.",
+                    line: 4,
+                    column: 18,
+                    endLine: 4,
+                    endColumn: 32,
+                },
+            ],
+        },
+        {
+            code: `
+console.log();
+/*eslint-disable no-unused-vars*/
+`,
+            options: [{ allowWholeFile: true }],
+            errors: [
+                {
+                    message: "Requires 'eslint-enable' directive for 'no-unused-vars'.",
+                    line: 3,
+                    column: 18,
+                    endLine: 3,
+                    endColumn: 32,
+                },
+            ],
+        },
+        {
+            code: `
+{
+/*eslint-disable no-unused-vars*/
+}
+`,
+            options: [{ allowWholeFile: true }],
+            errors: [
+                {
+                    message: "Requires 'eslint-enable' directive for 'no-unused-vars'.",
+                    line: 3,
+                    column: 18,
+                    endLine: 3,
+                    endColumn: 32,
+                },
+            ],
+        },
     ],
 })