Breaking: Switch to Acorn (fixes #200)

.eslintrc

@@ -1,20 +1,4 @@
 env:
     node: true
 
-rules:
-    brace-style: [2, "1tbs"]
-    comma-style: [2, "last"]
-    default-case: 2
-    func-style: [2, "declaration"]
-    guard-for-in: 2
-    no-floating-decimal: 2
-    no-nested-ternary: 2
-    no-undefined: 2
-    no-console: 2
-    quotes: [2, "double"]
-    radix: 2
-    space-after-keywords: [2, "always"]
-    space-before-blocks: 2
-    spaced-line-comment: [2, "always", { exceptions: ["-"]}]
-    valid-jsdoc: [2, { prefer: { "return": "returns"}}]
-    wrap-iife: 2
+extends: eslint

.gitignore

@@ -2,3 +2,5 @@ build
 coverage
 node_modules
 npm-debug.log
+_test.js
+

.travis.yml

@@ -3,5 +3,6 @@ sudo: false
 node_js:
     - "0.10"
     - "0.12"
+    - 4
 after_success:
     - npm run coveralls

Makefile.js

@@ -2,7 +2,7 @@
  * @fileoverview Build file
  * @author nzakas
  */
-/*global cat, cp, echo, exec, exit, find, mkdir, mv, rm, target, test*/
+/* global cat, cp, echo, exec, exit, find, mkdir, mv, rm, target, test */
 
 "use strict";
 
@@ -39,10 +39,10 @@ var NODE_MODULES = "./node_modules/",
 
     // Files
     MAKEFILE = "./Makefile.js",
-    /*eslint-disable no-use-before-define */
+    /* eslint-disable no-use-before-define */
     JS_FILES = find("lib/").filter(fileType("js")).join(" ") + " espree.js",
     TEST_FILES = find("tests/lib/").filter(fileType("js")).join(" ");
-    /*eslint-enable no-use-before-define */
+    /* eslint-enable no-use-before-define */
 
 //------------------------------------------------------------------------------
 // Helpers
@@ -103,6 +103,10 @@ function splitCommandResultToLines(result) {
     return result.trim().split("\n");
 }
 
+/**
+ * Gets an array of tags that represent versions.
+ * @returns {string[]} The array of tags.
+ */
 function getVersionTags() {
     var tags = splitCommandResultToLines(exec("git tag", { silent: true }).output);
 
@@ -230,6 +234,11 @@ target.changelog = function() {
 
 target.checkLicenses = function() {
 
+    /**
+     * Determines if a given dependency is permissible based on its license.
+     * @param {Object} dependency The dependency to check
+     * @returns {boolean} True if the dependency is ok, false if not.
+     */
     function isPermissible(dependency) {
         var licenses = dependency.licenses;
 
@@ -262,7 +271,7 @@ target.checkLicenses = function() {
         });
 
         if (impermissible.length) {
-            impermissible.forEach(function (dependency) {
+            impermissible.forEach(function(dependency) {
                 console.error("%s license for %s is impermissible.",
                     dependency.licenses,
                     dependency.name

README.md

@@ -1,16 +1,6 @@
 # Espree
 
-Espree is an actively-maintained fork Esprima, a high performance,
-standard-compliant [ECMAScript](http://www.ecma-international.org/publications/standards/Ecma-262.htm)
-parser written in ECMAScript (also popularly known as
-[JavaScript](http://en.wikipedia.org/wiki/JavaScript)).
-
-## Features
-
-- Full support for ECMAScript 5.1 ([ECMA-262](http://www.ecma-international.org/publications/standards/Ecma-262.htm))
-- Implements [ESTree](https://github.com/estree/estree) (both ES5 and ES6 specs) as the AST format.
-- Optional tracking of syntax node location (index-based and line-column)
-- Heavily tested and battle-hardened by inclusion in [ESLint](http://eslint.org)
+Espree started out as a fork of [Esprima](http://esprima.org) v1.2.2, the last stable published released of Esprima before work on ECMAScript 6 began. Espree is now built on top of [Acorn](https://github.com/ternjs/acorn), which has a modular architecture that allows extension of core functionality. The goal of Espree is to produce output that is similar to Esprima with a similar API so that it can be used in place of Esprima.
 
 ## Usage
 
@@ -113,14 +103,11 @@ var ast = espree.parse(code, {
         // enable parsing spread operator
         spread: true,
 
-        // enable super in functions
-        superInFunctions: true,
-
         // enable parsing classes
         classes: true,
 
         // enable parsing of new.target
-        newTarget: false,
+        newTarget: true,
 
         // enable parsing of modules
         modules: true,
@@ -137,30 +124,12 @@ var ast = espree.parse(code, {
 });
 ```
 
-## Plans
-
-Espree starts as a fork of Esprima v1.2.2, the last stable published released of Esprima before work on ECMAScript 6 began. Espree's first version is therefore v1.2.2 and is 100% compatible with Esprima v1.2.2 as a drop-in replacement. The version number will be incremented based on [semantic versioning](http://semver.org/) as features and bug fixes are added.
-
-The immediate plans are:
-
-1. Move away from giant files and move towards small, modular files that are easier to manage.
-1. Move towards CommonJS for all files and use browserify to create browser bundles.
-1. Support ECMAScript version filtering, allowing users to specify which version the parser should work in (similar to Acorn's `ecmaVersion` property).
-1. Add tests to track comment attachment.
-1. Add well-thought-out features that are useful for tools developers.
-1. Add full support for ECMAScript 6.
-1. Add optional parsing of JSX.
-
 ## Esprima Compatibility Going Forward
 
-The primary goal is to produce the exact same AST structure as Esprima and Acorn, and that takes precedence over anything else. (The AST structure being the ESTree API with JSX extensions.) Separate from that, Espree may deviate from what Esprima outputs in terms of where and how comments are attached, as well as what additional information is available on AST nodes. That is to say, Espree may add more things to the AST nodes than Esprima does but the overall AST structure produced will be the same.
+The primary goal is to produce the exact same AST structure and tokens as Esprima, and that takes precedence over anything else. (The AST structure being the [ESTree](https://github.com/estree/estree) API with JSX extensions.) Separate from that, Espree may deviate from what Esprima outputs in terms of where and how comments are attached, as well as what additional information is available on AST nodes. That is to say, Espree may add more things to the AST nodes than Esprima does but the overall AST structure produced will be the same.
 
 Espree may also deviate from Esprima in the interface it exposes.
 
-## Frequent and Incremental Releases
-
-Espree will not do giant releases. Releases will happen periodically as changes are made and incremental releases will be made towards larger goals. For instance, we will not have one big release for ECMAScript 6 support. Instead, we will implement ECMAScript 6, piece-by-piece, hiding those pieces behind an `ecmaFeatures` property that allows you to opt-in to use those features.
-
 ## Contributing
 
 Issues and pull requests will be triaged and responded to as quickly as possible. We operate under the [ESLint Contributor Guidelines](http://eslint.org/docs/developer-guide/contributing), so please be sure to read them before contributing. If you're not sure where to dig in, check out the [issues](https://github.com/eslint/espree/issues).
@@ -173,48 +142,52 @@ Espree is licensed under a permissive BSD 2-clause license.
 * `npm run lint` - run all linting
 * `npm run browserify` - creates a version of Espree that is usable in a browser
 
+## Differences from Espree 1.x
+
+* The `tokenize()` method does not use `ecmaFeatures`. Any string will be tokenized completely based on ECMAScript 6 semantics.
+* Trailing whitespace no longer is counted as part of a node.
+* `let` and `const` declarations are no longer parsed by default. You must opt-in using `ecmaFeatures.blockBindings`.
+
+
 ## Known Incompatibilities
 
 In an effort to help those wanting to transition from other parsers to Espree, the following is a list of noteworthy incompatibilities with other parsers. These are known differences that we do not intend to change.
 
 ### Esprima 1.2.2
 
-* None.
-
-### Esprima/Harmony Branch
+* Esprima counts trailing whitespace as part of each AST node while Espree does not. In Espree, the end of a node is where the last token occurs.
+* Espree does not parse `let` and `const` declarations by default.
+* Error messages returned for parsing errors are different.
+* There are two addition properties on every node and token: `start` and `end`. These represent the same data as `range` and are used internally by Acorn.
 
-* Esprima/Harmony uses a different comment attachment algorithm that results in some comments being added in different places than Espree. The algorithm Espree uses is the same one used in Esprima 1.2.2.
-* Espree uses ESTree format for the AST nodes whereas Esprima/Harmony uses a nonstandard format.
+### Esprima 2.x
 
-### Esprima-FB
-
-* All Esprima/Harmony incompatibilities.
+* Esprima 2.x uses a different comment attachment algorithm that results in some comments being added in different places than Espree. The algorithm Espree uses is the same one used in Esprima 1.2.2.
 
 ## Frequently Asked Questions
 
-### Why are you forking Esprima?
+### Why another parser
 
-[ESLint](http://eslint.org) has been relying on Esprima as its parser from the beginning. While that was fine when the JavaScript language was evolving slowly, the pace of development has increased dramatically and Esprima has fallen behind. ESLint, like many other tools reliant on Esprima, has been stuck in using new JavaScript language features until Esprima updates, and that has caused our users frustration.
+[ESLint](http://eslint.org) had been relying on Esprima as its parser from the beginning. While that was fine when the JavaScript language was evolving slowly, the pace of development increased dramatically and Esprima had fallen behind. ESLint, like many other tools reliant on Esprima, has been stuck in using new JavaScript language features until Esprima updates, and that caused our users frustration.
 
 We decided the only way for us to move forward was to create our own parser, bringing us inline with JSHint and JSLint, and allowing us to keep implementing new features as we need them. We chose to fork Esprima instead of starting from scratch in order to move as quickly as possible with a compatible API.
 
-### Have you tried working with Esprima?
+With Espree 2.0.0, we are no longer a fork of Esprima but rather a translation layer between Acorn and Esprima syntax. This allows us to put work back into a community-supported parser (Acorn) that is continuing to grow and evolve while maintaining an Esprima-compatible parser for those utilities still built on Esprima.
 
-Yes. Since the start of ESLint, we've regularly filed bugs and feature requests with Esprima. Unfortunately, we've been unable to make much progress towards getting our needs addressed.
-
-We are actively working with Esprima as part of its adoption by the jQuery Foundation. We are hoping to reconcile Espree with Esprima at some point in the future, but there are some different philosophies around how the projects work that need to be worked through. We're committed to a goal of merging Espree back into Esprima, or at the very least, to have Espree track Esprima as an upstream target so there's no duplication of effort. In the meantime, we will continue to update and maintain Espree.
-
-### Why don't you just use Facebook's Esprima fork?
+### Have you tried working with Esprima?
 
-`esprima-fb` is Facebook's Esprima fork that features JSX and Flow type annotations. We tried working with `esprima-fb` in our evaluation of how to support ECMAScript 6 and JSX in ESLint. Unfortunately, we were hampered by bugs that were part of Esprima (not necessarily Facebook's code). Since `esprima-fb` tracks the Esprima Harmony branch, that means we still were unable to get fixes or features we needed in a timely manner.
+Yes. Since the start of ESLint, we've regularly filed bugs and feature requests with Esprima and will continue to do so. However, there are some different philosophies around how the projects work that need to be worked through. The initial goal was to have Espree track Esprima and eventually merge the two back together, but we ultimately decided that building on top of Acorn was a better choice due to Acorn's plugin support.
 
 ### Why don't you just use Acorn?
 
 Acorn is a great JavaScript parser that produces an AST that is compatible with Esprima. Unfortunately, ESLint relies on more than just the AST to do its job. It relies on Esprima's tokens and comment attachment features to get a complete picture of the source code. We investigated switching to Acorn, but the inconsistencies between Esprima and Acorn created too much work for a project like ESLint.
 
-We expect there are other tools like ESLint that rely on more than just the AST produced by Esprima, and so a drop-in replacement will help those projects as well as ESLint.
+We are building on top of Acorn, however, so that we can contribute back and help make Acorn even better.
 
 ### What ECMAScript 6 features do you support?
 
 All of them.
 
+### How do you determine which experimental features to support?
+
+In general, we do not support experimental JavaScript features. We may make exceptions from time to time depending on the maturity of the features.