New: Support enhanced parsers (fixes #6974) (#6975)

Author: nzakas

lib/eslint.js

@@ -28,6 +28,18 @@ const assert = require("assert"),
     rules = require("./rules"),
     timing = require("./timing");
 
+//------------------------------------------------------------------------------
+// Typedefs
+//------------------------------------------------------------------------------
+
+/**
+ * The result of a parsing operation from parseForESLint()
+ * @typedef {Object} CustomParseResult
+ * @property {ASTNode} ast The ESTree AST Program node.
+ * @property {Object} services An object containing additional services related
+ *      to the parser.
+ */
+
 //------------------------------------------------------------------------------
 // Helpers
 //------------------------------------------------------------------------------
@@ -598,7 +610,8 @@ module.exports = (function() {
      * @param {string} text The text to parse.
      * @param {Object} config The ESLint configuration object.
      * @param {string} filePath The path to the file being parsed.
-     * @returns {ASTNode} The AST if successful or null if not.
+     * @returns {ASTNode|CustomParseResult} The AST or parse result if successful,
+     *      or null if not.
      * @private
      */
     function parse(text, config, filePath) {
@@ -642,7 +655,11 @@ module.exports = (function() {
          * problem that ESLint identified just like any other.
          */
         try {
-            return parser.parse(text, parserOptions);
+            if (typeof parser.parseForESLint === "function") {
+                return parser.parseForESLint(text, parserOptions);
+            } else {
+                return parser.parse(text, parserOptions);
+            }
         } catch (ex) {
 
             // If the message includes a leading line number, strip it:
@@ -738,6 +755,7 @@ module.exports = (function() {
     api.verify = function(textOrSourceCode, config, filenameOrOptions, saveState) {
         const text = (typeof textOrSourceCode === "string") ? textOrSourceCode : null;
         let ast,
+            parseResult,
             shebang,
             allowInlineConfig;
 
@@ -778,7 +796,7 @@ module.exports = (function() {
                 return messages;
             }
 
-            ast = parse(
+            parseResult = parse(
                 stripUnicodeBOM(text).replace(/^#!([^\r\n]+)/, function(match, captured) {
                     shebang = captured;
                     return `//${captured}`;
@@ -787,6 +805,14 @@ module.exports = (function() {
                 currentFilename
             );
 
+            // if this result is from a parseForESLint() method, normalize
+            if (parseResult && parseResult.ast) {
+                ast = parseResult.ast;
+            } else {
+                ast = parseResult;
+                parseResult = null;
+            }
+
             if (ast) {
                 sourceCode = new SourceCode(text, ast);
             }
@@ -832,7 +858,10 @@ module.exports = (function() {
                 try {
                     const ruleContext = new RuleContext(
                         key, api, severity, options,
-                        config.settings, config.parserOptions, config.parser, ruleCreator.meta);
+                        config.settings, config.parserOptions, config.parser,
+                        ruleCreator.meta,
+                        (parseResult && parseResult.services ? parseResult.services : {})
+                    );
 
                     const rule = ruleCreator.create ? ruleCreator.create(ruleContext) :
                         ruleCreator(ruleContext);

lib/rule-context.js

@@ -71,8 +71,9 @@ const PASSTHROUGHS = [
  * @param {Object} parserOptions The parserOptions settings passed from the config file.
  * @param {Object} parserPath The parser setting passed from the config file.
  * @param {Object} meta The metadata of the rule
+ * @param {Object} parserServices The parser services for the rule.
  */
-function RuleContext(ruleId, eslint, severity, options, settings, parserOptions, parserPath, meta) {
+function RuleContext(ruleId, eslint, severity, options, settings, parserOptions, parserPath, meta, parserServices) {
 
     // public.
     this.id = ruleId;
@@ -82,6 +83,9 @@ function RuleContext(ruleId, eslint, severity, options, settings, parserOptions,
     this.parserPath = parserPath;
     this.meta = meta;
 
+    // create a separate copy and freeze it (it's not nice to freeze other people's objects)
+    this.parserServices = Object.freeze(Object.assign({}, parserServices));
+
     // private.
     this.eslint = eslint;
     this.severity = severity;

tests/fixtures/parsers/enhanced-parser.js

@@ -0,0 +1,18 @@
+var espree = require("espree");
+
+exports.parseForESLint = function(code, options) {
+    return {
+        ast: espree.parse(code, options),
+        services: {
+            test: {
+                getMessage() {
+                    return "Hi!";
+                }
+            }
+        }
+    };
+};
+
+exports.parse = function() {
+    throw new Error("Use parseForESLint() instead.");
+};

tests/lib/eslint.js

@@ -1268,6 +1268,41 @@ describe("eslint", function() {
 
                 eslint.verify("0", config, filename);
             });
+
+            it("should use parseForESLint() in custom parser when custom parser is specified", function() {
+
+                const alternateParser = path.resolve(__dirname, "../fixtures/parsers/enhanced-parser.js");
+
+                eslint.reset();
+
+                const config = { rules: {}, parser: alternateParser };
+                const messages = eslint.verify("0", config, filename);
+
+                assert.equal(messages.length, 0);
+            });
+
+            it("should expose parser services when using parseForESLint() and services are specified", function() {
+
+                const alternateParser = path.resolve(__dirname, "../fixtures/parsers/enhanced-parser.js");
+
+                eslint.reset();
+                eslint.defineRule("test-service-rule", function(context) {
+                    return {
+                        Literal(node) {
+                            context.report({
+                                node,
+                                message: context.parserServices.test.getMessage()
+                            });
+                        }
+                    };
+                });
+
+                const config = { rules: { "test-service-rule": 2 }, parser: alternateParser };
+                const messages = eslint.verify("0", config, filename);
+
+                assert.equal(messages.length, 1);
+                assert.equal(messages[0].message, "Hi!");
+            });
         }
 
         it("should pass parser as parserPath to all rules when default parser is used", function() {

tests/lib/rule-context.js

@@ -10,6 +10,7 @@
 //------------------------------------------------------------------------------
 
 const sinon = require("sinon"),
+    assert = require("chai").assert,
     leche = require("leche"),
     realESLint = require("../../lib/eslint"),
     RuleContext = require("../../lib/rule-context");
@@ -95,4 +96,35 @@ describe("RuleContext", function() {
         });
     });
 
+    describe("parserServices", function() {
+
+        it("should pass through parserServices properties to context", function() {
+            const services = {
+                test: {}
+            };
+            const ruleContext = new RuleContext("fake-rule", {}, 2, {}, {}, {}, "espree", {}, services);
+
+            assert.equal(ruleContext.parserServices.test, services.test);
+        });
+
+        it("should copy parserServices properties to a new object", function() {
+            const services = {
+                test: {}
+            };
+            const ruleContext = new RuleContext("fake-rule", {}, 2, {}, {}, {}, "espree", {}, services);
+
+            assert.notEqual(ruleContext.parserServices, services);
+        });
+
+        it("should make context.parserServices a frozen object", function() {
+            const services = {
+                test: {}
+            };
+            const ruleContext = new RuleContext("fake-rule", {}, 2, {}, {}, {}, "espree", {}, services);
+
+            assert.ok(Object.isFrozen(ruleContext.parserServices));
+        });
+
+    });
+
 });