v5.6.20

This reverts commit 420492388b.

.travis.yml

@@ -3,6 +3,7 @@ cache:
   directories:
   - node_modules
 node_js:
+- "0.10"
 - "0.12"
 - iojs
 
@@ -30,4 +31,5 @@ deploy:
 after_deploy:
 - make publish-cli
 - make publish-runtime
-- make rebuild-website
+- make build-website
+- make comment-issues

CHANGELOG.md

@@ -13,6 +13,35 @@ _Note: Gaps between patch versions are faulty, broken or test releases._
 
 See [CHANGELOG - 6to5](CHANGELOG-6to5.md) for the pre-4.0.0 version changelog.
 
+## 5.6.17
+
+ * **Bug Fix**
+  * Fix `CodeGenerator.findCommonStringDelimiter` causing a stack overflow.
+
+## 5.6.16
+
+ * **Internal**
+  * Fix `recast` version to avoid pulling in a newer version.
+ * **New Feature**
+  * Add support for functions in `util.shouldIgnore`.
+ * **Polish**
+  * Strip flow directives in flow transformer.
+  * Add a check for out of bounds default parameters, drastically improving performance and removes engine deoptimisations.
+  * Various performance optimisations by [@samccone](https://github.com/samccone) 💅✨
+  * Delay `this` assignment when referencing this inside an arrow function pre-bare super in derived class constructors.
+  * Split up class body pushing if the constructor is in the wrong order.
+ * **Bug Fix**
+  * Fix hoisting of `ForInStatement` `init` variables in `system` module formatter.
+  * `PathHoister`: Don't hoist to the same function as their original paths function parent.
+  * `PathHoister`: Push each violation paths ancestry to the breakOnScopePaths collection to avoid constant hoisting to nested paths.fix tail call recursion on functions with less arguments than parameters.
+  * Disallow `super.*` before `super()` in derived class constructors.
+  * Properly regenerate scope for replaced nodes. Thanks [@loganfsmyth](https://github.com/loganfsmyth)!
+  * Move up template literal simplification logic to avoid breaking on single elements.
+
+## 5.6.13-5.6.15
+
+ * Setting up automatic Travis releases.
+
 ## 5.6.12
 
  * **Bug Fix**

CONTRIBUTING.md

@@ -143,8 +143,11 @@ your [`$PATH`](http://unix.stackexchange.com/questions/26047/how-to-correctly-ad
 
 + [trim-right](http://ghub.io/trim-right) Trims the rightside whitespace.
 
-+ [user-home](http://ghub.io/user-home) Gets the users home directory. This is used to resolve the babel-node/babel/register cache.
++ [path-exists](https://www.npmjs.com/package/path-exists) Checks if a path exists. (replaces the deprecated `fs.exists` methods)
 
++ [home-or-tmp](https://github.com/sindresorhus/home-or-tmp) Gets the user home directory with fallback to the system temporary directory. This is used to resolve the babel-node/babel/register cache.
+
++ [resolve](https://www.npmjs.com/package/resolve) Implements the [`require.resolve()` algorithm](http://nodejs.org/docs/v0.12.0/api/all.html#all_require_resolve) such that we can `require.resolve()` on behalf of a file asynchronously and synchronously.
 
 #### Code Standards
 

Makefile

@@ -108,6 +108,9 @@ publish-cli:
 build-website:
 	@./tools/build-website.sh
 
+comment-issues:
+	@./tools/comment-issues.sh
+
 bootstrap:
 	npm list --global --depth 1 babel >/dev/null 2>&1 && npm uninstall -g babel || true
 	npm install

README.md

@@ -1,6 +1,6 @@
 <p align="center">
   <a href="https://babeljs.io/">
-    <img alt="babel" src="https://raw.githubusercontent.com/babel/logo/master/logo.png" width="546">
+    <img alt="babel" src="https://raw.githubusercontent.com/babel/logo/master/babel.png" width="546">
   </a>
 </p>
 
@@ -10,16 +10,19 @@
 
 <p align="center">
   <a href="https://travis-ci.org/babel/babel"><img alt="Build Status" src="https://img.shields.io/travis/babel/babel.svg?style=flat"></a>
-  <a href="http://issuestats.com/github/babel/babel"><img alt="Issue Stats" src="http://issuestats.com/github/babel/babel/badge/pr?style=flat"></a>
-  <a href="http://issuestats.com/github/babel/babel"><img alt="Issue Stats" src="http://issuestats.com/github/babel/babel/badge/issue?style=flat"></a>
   <a href="http://badge.fury.io/js/babel-core"><img alt="npm version" src="https://badge.fury.io/js/babel-core.svg"></a>
   <a href="https://npmjs.org/package/babel-core"><img alt="Downloads" src="http://img.shields.io/npm/dm/babel-core.svg"></a>
 </p>
 
+<p align="center">
+  <a href="http://issuestats.com/github/babel/babel"><img alt="Issue Stats" src="http://issuestats.com/github/babel/babel/badge/pr?style=flat"></a>
+  <a href="http://issuestats.com/github/babel/babel"><img alt="Issue Stats" src="http://issuestats.com/github/babel/babel/badge/issue?style=flat"></a>
+</p>
+
 ----
 
 <p align="center">
-  For questions and support please visit the <a href="https://babel-slack.herokuapp.com">slack channel</a> or <a href="http://stackoverflow.com/questions/tagged/babeljs">StackOverflow</a>. The Babel issue tracker is <strong>exclusively</strong> for bug reports and feature requests.
+  For questions and support please visit the <a href="https://babel-slack.herokuapp.com">Slack community</a> or <a href="http://stackoverflow.com/questions/tagged/babeljs">StackOverflow</a>. The Babel issue tracker is <strong>exclusively</strong> for bug reports and feature requests.
 </p>
 
 <p align="center">

doc/node-props.md

@@ -1,5 +1,5 @@
 # Properties of nodes
-These are properties babel stores in AST node objects for internal use, as opposed to properties that are part of the AST spec (ESTree at the time of this writing).
+These are properties babel stores in AST node objects for internal use, as opposed to properties that are part of the AST spec ([ESTree](https://github.com/estree/estree) at the time of this writing).
 
 ## `_blockHoist`
 `node._blockHoist != null` triggers the [block-hoist transformer](/src/babel/transformation/transformers/internal/block-hoist.js). Value should be `true` or an integer in the range `0..3`. `true` is equivalent to `2`. The value indicates whether the node should be hoisted and to what degree. See the source code for more detailed information.
@@ -8,4 +8,4 @@ These are properties babel stores in AST node objects for internal use, as oppos
 Stores a representation of a node's position in the tree and relationship to other nodes.
 
 ## `shadow`
-A truthy value on a function node triggers the [shadow-functions transformer](/src/babel/transformation/transformers/internal/shadow-functions.js), which transforms the node so that it references (or inherits) `arguments` and `this` from the parent scope. It is invoked for arrow functions, for example.
+A truthy value on a function node triggers the [shadow-functions transformer](/src/babel/transformation/transformers/internal/shadow-functions.js), which transforms the node so that it references (or inherits) `arguments` and the `this` context from the parent scope. It is invoked for arrow functions, for example.

package.json

@@ -1,7 +1,7 @@
 {
   "name": "babel-core",
   "description": "A compiler for writing next generation JavaScript",
-  "version": "5.6.15",
+  "version": "5.6.20",
   "author": "Sebastian McKenzie <sebmck@gmail.com>",
   "homepage": "https://babeljs.io/",
   "license": "MIT",
@@ -28,7 +28,6 @@
   },
   "dependencies": {
     "acorn-jsx": "^1.0.0",
-    "ast-types": "~0.7.0",
     "babel-plugin-constant-folding": "^1.0.1",
     "babel-plugin-dead-code-elimination": "^1.0.2",
     "babel-plugin-eval": "^1.0.1",
@@ -63,7 +62,7 @@
     "path-exists": "^1.0.0",
     "path-is-absolute": "^1.0.0",
     "private": "^0.1.6",
-    "regenerator": "0.8.31",
+    "regenerator": "0.8.34",
     "regexpu": "^1.1.2",
     "repeating": "^1.1.2",
     "resolve": "^1.1.6",

packages/babel-cli/bin/_babel-node

@@ -18,9 +18,9 @@ program.option("-p, --print [code]", "Evaluate script and print result");
 program.option("-i, --ignore [regex]", "Ignore all files that match this regex when using the require hook");
 program.option("-x, --extensions [extensions]", "List of extensions to hook into [.es6,.js,.es,.jsx]");
 program.option("-r, --stage [stage]", "Enable support for specific ECMAScript stages");
-program.option("-w, --whitelist [whitelist]", "Whitelist of transformers to ONLY use", util.list);
-program.option("-b, --blacklist [blacklist]", "Blacklist of transformers to NOT use", util.list);
-program.option("-o, --optional [optional]", "List of optional transformers to enable", util.list);
+program.option("-w, --whitelist [whitelist]", "Whitelist of transformers separated by comma to ONLY use", util.list);
+program.option("-b, --blacklist [blacklist]", "Blacklist of transformers separated by comma to NOT use", util.list);
+program.option("-o, --optional [optional]", "List of optional transformers separated by comma to enable", util.list);
 
 var pkg = require("../package.json");
 program.version(pkg.version);
@@ -41,6 +41,7 @@ babel.register({
 //
 
 var _eval = function (code, filename) {
+  code = code.trim();
   if (!code) return undefined;
 
   code = babel.transform(code, {

packages/babel-cli/bin/babel/dir.js

@@ -28,7 +28,7 @@ module.exports = function (commander, filenames) {
 
     outputFileSync(dest, data.code);
 
-    console.log(src + " -> " + dest);
+    util.log(src + " -> " + dest);
   };
 
   var handleFile = function (src, filename) {

packages/babel-cli/bin/babel/file.js

@@ -135,7 +135,7 @@ module.exports = function (commander, filenames, opts) {
         ignoreInitial: true
       }).on("all", function (type, filename) {
         if (type === "add" || type === "change") {
-          console.log(type, filename);
+          util.log(type + " " + filename);
           try {
             walk();
           } catch (err) {

packages/babel-cli/bin/babel/index.js

@@ -45,6 +45,7 @@ commander.option("-w, --watch", "Recompile files on changes");
 commander.option("-o, --out-file [out]", "Compile all input files into a single file");
 commander.option("-d, --out-dir [out]", "Compile an input directory of modules into an output directory");
 commander.option("-D, --copy-files", "When compiling a directory copy over non-compilable files");
+commander.option("-q, --quiet", "Don't log anything");
 
 commander.on("--help", function () {
   var outKeys = function (title, obj) {
@@ -67,7 +68,7 @@ commander.on("--help", function () {
 });
 
 var pkg = require("../../package.json");
-commander.version(pkg.version);
+commander.version(pkg.version + " (babel-core " + require("babel-core").version + ")");
 commander.usage("[options] <files ...>");
 commander.parse(process.argv);
 

packages/babel-cli/bin/babel/util.js

@@ -25,6 +25,10 @@ exports.addSourceMappingUrl = function (code, loc) {
   return code + "\n//# sourceMappingURL=" + path.basename(loc);
 };
 
+exports.log = function (msg) {
+  if (!commander.quiet) console.log(msg);
+};
+
 exports.transform = function (filename, code, opts) {
   opts = _.defaults(opts || {}, index.opts);
   opts.filename = filename;

packages/build-runtime.js

@@ -73,7 +73,6 @@ each(File.helpers, function (helperName) {
 writeFile("regenerator/index.js", readFile("regenerator/runtime-module", true));
 writeFile("regenerator/runtime.js", selfContainify(readFile("regenerator/runtime")));
 
-//
 
 var coreDefinitions = require("babel-plugin-runtime/lib/definitions");
 
@@ -93,6 +92,5 @@ each(paths, function (path) {
   writeFile("core-js/" + path + ".js", defaultify('require("core-js/library/fn/' + path + '")'));
 });
 
-//
 
 updatePackage();

src/README.md

@@ -0,0 +1,27 @@
+## Welcome to the Babel Codebase
+
+Babel is broken down into three parts:
+
+- Parsing
+- [Transformation](babel/transformation/)
+- [Generation](babel/generation/)
+
+**Parsing** is the process of turning a piece of code into an [ESTree spec](https://github.com/estree/estree) compatible AST (Abstract
+Syntax Tree) which is a tree-like object of nodes that _describes_ the code.
+This makes it easier to transform the code over direct string manpulation.
+
+**Transformation** is the process of taking an AST and manipulating it into
+a new one. For example, Babel might take an ES2015 ArrowFunction and transform
+it into a normal Function which will work in ES5 environments.
+
+**Generation** is the process of turning an AST back into code. After Babel is
+done transforming the AST, the generation takes over to return normal code.
+
+---
+
+Babel's parsing step is done by [Acorn](https://github.com/marijnh/acorn). However, because Babel is implementing
+future standards it maintains a [fork of Acorn](acorn/) in order to do it's job. You can
+see that fork in the "acorn" folder.
+
+The transformation and generation steps are both handled inside of the Babel
+codebase itself, which is in the "babel" folder here.

src/acorn/plugins/flow.js

@@ -1,4 +1,3 @@
-Error.stackTraceLimit = Infinity;
 var acorn = require("../src/index")
 
 var pp = acorn.Parser.prototype
@@ -792,16 +791,15 @@ acorn.plugins.flow = function (instance) {
 
   instance.extend("parseImportSpecifiers", function (inner) {
     return function (node) {
-      node.isType = false
-      if (this.isContextual("type")) {
-        var start = this.markPosition()
-        var typeId = this.parseIdent()
-        if ((this.type === tt.name && this.value !== "from") || this.type === tt.braceL || this.type === tt.star) {
-          node.isType = true
-        } else {
-          node.specifiers.push(this.parseImportSpecifierDefault(typeId, start))
-          if (this.isContextual("from")) return
-          this.eat(tt.comma)
+      node.importKind = "value"
+      var kind =
+        (this.type === tt._typeof ? "typeof" :
+        (this.isContextual("type") ? "type" : null))
+      if (kind) {
+        var lh = this.lookahead()
+        if ((lh.type === tt.name && lh.value !== "from") || lh.type === tt.braceL || lh.type === tt.star) {
+          this.next()
+          node.importKind = kind
         }
       }
       inner.call(this, node)

src/acorn/src/options.js

@@ -1,4 +1,4 @@
-import {has, isArray} from "./util"
+import {has} from "./util"
 import {SourceLocation} from "./location"
 
 // A second optional argument can be given to further configure
@@ -94,11 +94,11 @@ export function getOptions(opts) {
   for (let opt in defaultOptions)
     options[opt] = opts && has(opts, opt) ? opts[opt] : defaultOptions[opt]
 
-  if (isArray(options.onToken)) {
+  if (Array.isArray(options.onToken)) {
     let tokens = options.onToken
     options.onToken = (token) => tokens.push(token)
   }
-  if (isArray(options.onComment))
+  if (Array.isArray(options.onComment))
     options.onComment = pushComment(options, options.onComment)
 
   return options

src/acorn/src/util.js

@@ -1,7 +1,3 @@
-export function isArray(obj) {
-  return Object.prototype.toString.call(obj) === "[object Array]"
-}
-
 // Checks if an object has a property.
 
 export function has(obj, propName) {

src/babel/README.md

@@ -0,0 +1,4 @@
+## Diving into Babel
+
+If you look around in the various directories in here you'll find some details
+about the organization of the Babel codebase.

src/babel/api/README.md

@@ -0,0 +1,18 @@
+## API
+
+In this directory you'll find all the public interfaces to using Babel for both
+node and the browser.
+
+### Node
+
+There are two ways people use Babel within Node, they either are manipulating
+strings of code with `babel.transform` or `babel.parse`, they also might be
+running their code through Babel before execution via `register` or `polyfill`.
+
+### Browser
+
+Usage of Babel in the browser is extremely uncommon and in most cases
+considered A Bad Idea™. However it works by loading `<script>`'s with XHR,
+transforming them and then executing them. These `<script>`'s need to have a
+`type` of "text/ecmascript-6", "text/babel", or "module" ("text/6to5" exists as
+well for legacy reasons).

src/babel/api/browser.js

@@ -3,16 +3,32 @@
 require("./node");
 var transform = module.exports = require("../transformation");
 
+/**
+ * Add `options` and `version` to `babel` global.
+ */
+
 transform.options = require("../transformation/file/options");
 transform.version = require("../../../package").version;
 
+/**
+ * Add `transform` api to `babel` global.
+ */
+
 transform.transform = transform;
 
+/**
+ * Tranform and execute script, adding in inline sourcemaps.
+ */
+
 transform.run = function (code, opts = {}) {
   opts.sourceMaps = "inline";
   return new Function(transform(code, opts).code)();
 };
 
+/**
+ * Load scripts via xhr, and `transform` when complete (optional).
+ */
+
 transform.load = function (url, callback, opts = {}, hold) {
   opts.filename = opts.filename || url;
 
@@ -20,6 +36,10 @@ transform.load = function (url, callback, opts = {}, hold) {
   xhr.open("GET", url, true);
   if ("overrideMimeType" in xhr) xhr.overrideMimeType("text/plain");
 
+  /**
+   * When successfully loaded, transform (optional), and call `callback`.
+   */
+
   xhr.onreadystatechange = function () {
     if (xhr.readyState !== 4) return;
 
@@ -36,11 +56,22 @@ transform.load = function (url, callback, opts = {}, hold) {
   xhr.send(null);
 };
 
+/**
+ * Load and transform all scripts of `types`.
+ *
+ * @example
+ * <script type="module"></script>
+ */
+
 var runScripts = function () {
   var scripts = [];
   var types   = ["text/ecmascript-6", "text/6to5", "text/babel", "module"];
   var index   = 0;
 
+  /**
+   * Transform and execute script. Ensures correct load order.
+   */
+
   var exec = function () {
     var param = scripts[index];
     if (param instanceof Array) {
@@ -50,6 +81,10 @@ var runScripts = function () {
     }
   };
 
+  /**
+   * Load, transform, and execute all scripts.
+   */
+
   var run = function (script, i) {
     var opts = {};
 
@@ -64,7 +99,9 @@ var runScripts = function () {
     }
   };
 
-  var _scripts = global.document .getElementsByTagName("script");
+  // Collect scripts with Babel `types`.
+
+  var _scripts = global.document.getElementsByTagName("script");
 
   for (var i = 0; i < _scripts.length; ++i) {
     var _script = _scripts[i];
@@ -78,6 +115,10 @@ var runScripts = function () {
   exec();
 };
 
+/**
+ * Register load event to transform and execute scripts.
+ */
+
 if (global.addEventListener) {
   global.addEventListener("DOMContentLoaded", runScripts, false);
 } else if (global.attachEvent) {

src/babel/api/node.js

@@ -19,16 +19,28 @@ export { version } from "../../../package";
 import * as t from "../types";
 export { t as types };
 
+/**
+ * Register Babel and polyfill globally.
+ */
+
 export function register(opts?: Object) {
   var callback = require("./register/node-polyfill");
   if (opts != null) callback(opts);
   return callback;
 }
 
+/**
+ * Register polyfill globally.
+ */
+
 export function polyfill() {
   require("../polyfill");
 }
 
+/**
+ * Asynchronously transform `filename` with optional `opts`, calls `callback` when complete.
+ */
+
 export function transformFile(filename: string, opts?: Object, callback: Function) {
   if (isFunction(opts)) {
     callback = opts;
@@ -52,11 +64,19 @@ export function transformFile(filename: string, opts?: Object, callback: Functio
   });
 }
 
+/**
+ * Synchronous form of `transformFile`.
+ */
+
 export function transformFileSync(filename: string, opts?: Object = {}) {
   opts.filename = filename;
   return transform(fs.readFileSync(filename, "utf8"), opts);
 }
 
+/**
+ * Parse script with Babel's parser.
+ */
+
 export function parse(code, opts = {}) {
   opts.allowHashBang = true;
   opts.sourceType = "module";

src/babel/api/register/cache.js

@@ -6,10 +6,18 @@ import pathExists from "path-exists";
 const FILENAME = process.env.BABEL_CACHE_PATH || path.join(homeOrTmp, ".babel.json");
 var data = {};
 
+/**
+ * Write stringified cache to disk.
+ */
+
 export function save() {
   fs.writeFileSync(FILENAME, JSON.stringify(data, null, "  "));
 }
 
+/**
+ * Load cache from disk and parse.
+ */
+
 export function load() {
   if (process.env.BABEL_DISABLE_CACHE) return;
 
@@ -25,6 +33,10 @@ export function load() {
   }
 }
 
+/**
+ * Retrieve data from cache.
+ */
+
 export function get() {
   return data;
 }

src/babel/api/register/node.js

@@ -1,6 +1,6 @@
 import sourceMapSupport from "source-map-support";
 import * as registerCache from "./cache";
-import resolveRc from "../../transformation/file/options/resolve-rc";
+import OptionManager from "../../transformation/file/options/option-manager";
 import extend from "lodash/object/extend";
 import * as babel from "../node";
 import each from "lodash/collection/each";
@@ -8,6 +8,10 @@ import * as util from  "../../util";
 import fs from "fs";
 import path from "path";
 
+/**
+ * Install sourcemaps into node.
+ */
+
 sourceMapSupport.install({
   handleUncaughtExceptions: false,
   retrieveSourceMap(source) {
@@ -23,12 +27,16 @@ sourceMapSupport.install({
   }
 });
 
-//
+/**
+ * Load and setup cache.
+ */
 
 registerCache.load();
 var cache = registerCache.get();
 
-//
+/**
+ * Store options.
+ */
 
 var transformOpts = {};
 
@@ -40,22 +48,32 @@ var maps          = {};
 
 var cwd = process.cwd();
 
+/**
+ * Get path from `filename` relative to the current working directory.
+ */
+
 var getRelativePath = function (filename){
   return path.relative(cwd, filename);
 };
 
+/**
+ * Get last modified time for a `filename`.
+ */
+
 var mtime = function (filename) {
   return +fs.statSync(filename).mtime;
 };
 
+/**
+ * Compile a `filename` with optional `opts`.
+ */
+
 var compile = function (filename, opts = {}) {
   var result;
 
-  opts = extend(opts, transformOpts);
-
-  // this will be done when the file is transformed anyway but we need all
-  // the options so we can generate the cache key
-  resolveRc(filename, opts);
+  var optsManager = new OptionManager;
+  optsManager.mergeOptions(transformOpts);
+  opts = optsManager.init(opts);
 
   var cacheKey = `${filename}:${JSON.stringify(opts)}:${babel.version}`;
 
@@ -86,6 +104,10 @@ var compile = function (filename, opts = {}) {
   return result.code;
 };
 
+/**
+ * Test if a `filename` should be ignored by Babel.
+ */
+
 var shouldIgnore = function (filename) {
   if (!ignore && !only) {
     return getRelativePath(filename).split(path.sep).indexOf("node_modules") >= 0;
@@ -94,6 +116,10 @@ var shouldIgnore = function (filename) {
   }
 };
 
+/**
+ * Monkey patch istanbul if it is running so that it works properly.
+ */
+
 var istanbulMonkey = {};
 
 if (process.env.running_under_istanbul) {
@@ -115,15 +141,27 @@ if (process.env.running_under_istanbul) {
   };
 }
 
+/**
+ * Replacement for the loader for istanbul.
+ */
+
 var istanbulLoader = function (m, filename, old) {
   istanbulMonkey[filename] = true;
   old(m, filename);
 };
 
+/**
+ * Default loader.
+ */
+
 var normalLoader = function (m, filename) {
   m._compile(compile(filename), filename);
 };
 
+/**
+ * Register a loader for an extension.
+ */
+
 var registerExtension = function (ext) {
   var old = oldHandlers[ext] || oldHandlers[".js"] || require.extensions[".js"];
 
@@ -139,6 +177,10 @@ var registerExtension = function (ext) {
   };
 };
 
+/**
+ * Register loader for given extensions.
+ */
+
 var hookExtensions = function (_exts) {
   each(oldHandlers, function (old, ext) {
     if (old === undefined) {
@@ -156,8 +198,16 @@ var hookExtensions = function (_exts) {
   });
 };
 
+/**
+ * Register loader for default extensions.
+ */
+
 hookExtensions(util.canCompile.EXTENSIONS);
 
+/**
+ * Update options at runtime.
+ */
+
 export default function (opts = {}) {
   if (opts.only != null) only = util.arrayify(opts.only, util.regexify);
   if (opts.ignore != null) ignore = util.arrayify(opts.ignore, util.regexify);

src/babel/generation/README.md

@@ -0,0 +1,16 @@
+## Generation
+
+Here is Babel's code generator, here you'll find all of the code to turn an AST
+back into a string of code.
+
+[TBD: To Be Documented:]
+
+- Code Generator
+- Buffer
+- Source Maps
+  - Position
+- Printer
+- Code Style
+  - Whitespace
+  - Parenthesis
+- Generators

src/babel/generation/buffer.js

@@ -4,6 +4,10 @@ import isBoolean from "lodash/lang/isBoolean";
 import includes from "lodash/collection/includes";
 import isNumber from "lodash/lang/isNumber";
 
+/**
+ * Buffer for collecting generated output.
+ */
+
 export default class Buffer {
   constructor(position, format) {
     this.position = position;
@@ -12,10 +16,18 @@ export default class Buffer {
     this.buf      = "";
   }
 
+  /**
+   * Get the current trimmed buffer.
+   */
+
   get() {
     return trimRight(this.buf);
   }
 
+  /**
+   * Get the current indent.
+   */
+
   getIndent() {
     if (this.format.compact || this.format.concise) {
       return "";
@@ -24,36 +36,68 @@ export default class Buffer {
     }
   }
 
+  /**
+   * Get the current indent size.
+   */
+
   indentSize() {
     return this.getIndent().length;
   }
 
+  /**
+   * Increment indent size.
+   */
+
   indent() {
     this._indent++;
   }
 
+  /**
+   * Decrement indent size.
+   */
+
   dedent() {
     this._indent--;
   }
 
+  /**
+   * Add a semicolon to the buffer.
+   */
+
   semicolon() {
     this.push(";");
   }
 
+  /**
+   * Ensure last character is a semicolon.
+   */
+
   ensureSemicolon() {
     if (!this.isLast(";")) this.semicolon();
   }
 
+  /**
+   * Add a right brace to the buffer.
+   */
+
   rightBrace() {
     this.newline(true);
     this.push("}");
   }
 
+  /**
+   * Add a keyword to the buffer.
+   */
+
   keyword(name) {
     this.push(name);
     this.space();
   }
 
+  /**
+   * Add a space to the buffer unless it is compact (override with force).
+   */
+
   space(force?) {
     if (!force && this.format.compact) return;
 
@@ -62,6 +106,10 @@ export default class Buffer {
     }
   }
 
+  /**
+   * Remove the last character.
+   */
+
   removeLast(cha) {
     if (this.format.compact) return;
     if (!this.isLast(cha)) return;
@@ -70,6 +118,11 @@ export default class Buffer {
     this.position.unshift(cha);
   }
 
+  /**
+   * Add a newline (or many newlines), maintaining formatting.
+   * Strips multiple newlines if removeLast is true.
+   */
+
   newline(i, removeLast) {
     if (this.format.compact || this.format.retainLines) return;
 
@@ -100,6 +153,10 @@ export default class Buffer {
     this._newline(removeLast);
   }
 
+  /**
+   * Adds a newline unless there is already two previous newlines.
+   */
+
   _newline(removeLast) {
     // never allow more than two lines
     if (this.endsWith("\n\n")) return;
@@ -136,6 +193,10 @@ export default class Buffer {
     }
   }
 
+  /**
+   * Push a string to the buffer, maintaining indentation and newlines.
+   */
+
   push(str, noIndent) {
     if (!this.format.compact && this._indent && !noIndent && str !== "\n") {
       // we have an indent level and we aren't pushing a newline
@@ -151,11 +212,19 @@ export default class Buffer {
     this._push(str);
   }
 
+  /**
+   * Push a string to the buffer.
+   */
+
   _push(str) {
     this.position.push(str);
     this.buf += str;
   }
 
+  /**
+   * Test if the buffer ends with a string.
+   */
+
   endsWith(str, buf = this.buf) {
     if (str.length === 1) {
       return buf[buf.length - 1] === str;
@@ -164,6 +233,10 @@ export default class Buffer {
     }
   }
 
+  /**
+   * Test if a character is last in the buffer.
+   */
+
   isLast(cha) {
     if (this.format.compact) return false;
 

src/babel/generation/generators/README.md

@@ -0,0 +1,10 @@
+## Generators
+
+Code generation in Babel is broken down into generators by node type, they all
+live in this directory.
+
+[TBD: To Be Documented:]
+
+- How generators work
+- How to print a node
+- How generators related to one another

src/babel/generation/generators/base.js

@@ -1,11 +1,23 @@
+/**
+ * Print File.program
+ */
+
 export function File(node, print) {
   print.plain(node.program);
 }
 
+/**
+ * Print all nodes in a Program.body.
+ */
+
 export function Program(node, print) {
   print.sequence(node.body);
 }
 
+/**
+ * Print BlockStatement, collapses empty blocks, prints body.
+ */
+
 export function BlockStatement(node, print) {
   if (node.body.length === 0) {
     this.push("{}");
@@ -18,6 +30,13 @@ export function BlockStatement(node, print) {
   }
 }
 
+/**
+ * What is my purpose?
+ * Why am I here?
+ * Why are any of us here?
+ * Does any of this really matter?
+ */
+
 export function Noop() {
 
 }

src/babel/generation/generators/classes.js

@@ -1,3 +1,7 @@
+/**
+ * Print ClassDeclaration, prints decorators, typeParameters, extends, implements, and body.
+ */
+
 export function ClassDeclaration(node, print) {
   print.list(node.decorators, { separator: "" });
   this.push("class");
@@ -24,8 +28,16 @@ export function ClassDeclaration(node, print) {
   print.plain(node.body);
 }
 
+/**
+ * Alias ClassDeclaration printer as ClassExpression.
+ */
+
 export { ClassDeclaration as ClassExpression };
 
+/**
+ * Print ClassBody, collapses empty blocks, prints body.
+ */
+
 export function ClassBody(node, print) {
   if (node.body.length === 0) {
     this.push("{}");
@@ -41,6 +53,10 @@ export function ClassBody(node, print) {
   }
 }
 
+/**
+ * Print ClassProperty, prints decorators, static, key, typeAnnotation, and value.
+ * Also: semicolons, deal with it.
+ */
 
 export function ClassProperty(node, print) {
   print.list(node.decorators, { separator: "" });
@@ -57,6 +73,10 @@ export function ClassProperty(node, print) {
   this.semicolon();
 }
 
+/**
+ * Print MethodDefinition, prints decorations, static, and method.
+ */
+
 export function MethodDefinition(node, print) {
   print.list(node.decorators, { separator: "" });
 

src/babel/generation/generators/comprehensions.js

@@ -1,3 +1,7 @@
+/**
+ * Prints ComprehensionBlock, prints left and right.
+ */
+
 export function ComprehensionBlock(node, print) {
   this.keyword("for");
   this.push("(");
@@ -7,6 +11,10 @@ export function ComprehensionBlock(node, print) {
   this.push(")");
 }
 
+/**
+ * Prints ComprehensionExpression, prints blocks, filter, and body. Handles generators.
+ */
+
 export function ComprehensionExpression(node, print) {
   this.push(node.generator ? "(" : "[");
 

src/babel/generation/generators/expressions.js

@@ -1,6 +1,10 @@
 import isNumber from "lodash/lang/isNumber";
 import * as t from "../../types";
 
+/**
+ * Prints UnaryExpression, prints operator and argument.
+ */
+
 export function UnaryExpression(node, print) {
   var needsSpace = /[a-z]$/.test(node.operator);
   var arg = node.argument;
@@ -18,18 +22,30 @@ export function UnaryExpression(node, print) {
   print.plain(node.argument);
 }
 
+/**
+ * Prints DoExpression, prints body.
+ */
+
 export function DoExpression(node, print) {
   this.push("do");
   this.space();
   print.plain(node.body);
 }
 
+/**
+ * Prints ParenthesizedExpression, prints expression.
+ */
+
 export function ParenthesizedExpression(node, print) {
   this.push("(");
   print.plain(node.expression);
   this.push(")");
 }
 
+/**
+ * Prints UpdateExpression, prints operator and argument.
+ */
+
 export function UpdateExpression(node, print) {
   if (node.prefix) {
     this.push(node.operator);
@@ -40,6 +56,10 @@ export function UpdateExpression(node, print) {
   }
 }
 
+/**
+ * Prints ConditionalExpression, prints test, consequent, and alternate.
+ */
+
 export function ConditionalExpression(node, print) {
   print.plain(node.test);
   this.space();
@@ -52,6 +72,10 @@ export function ConditionalExpression(node, print) {
   print.plain(node.alternate);
 }
 
+/**
+ * Prints NewExpression, prints callee and arguments.
+ */
+
 export function NewExpression(node, print) {
   this.push("new ");
   print.plain(node.callee);
@@ -60,24 +84,44 @@ export function NewExpression(node, print) {
   this.push(")");
 }
 
+/**
+ * Prints SequenceExpression.expressions.
+ */
+
 export function SequenceExpression(node, print) {
   print.list(node.expressions);
 }
 
+/**
+ * Prints ThisExpression.
+ */
+
 export function ThisExpression() {
   this.push("this");
 }
 
+/**
+ * Prints Super.
+ */
+
 export function Super() {
   this.push("super");
 }
 
+/**
+ * Prints Decorator, prints expression.
+ */
+
 export function Decorator(node, print) {
   this.push("@");
   print.plain(node.expression);
   this.newline();
 }
 
+/**
+ * Prints CallExpression, prints callee and arguments.
+ */
+
 export function CallExpression(node, print) {
   print.plain(node.callee);
 
@@ -102,6 +146,11 @@ export function CallExpression(node, print) {
   this.push(")");
 }
 
+/**
+ * Builds yield or await expression printer.
+ * Prints delegate, all, and argument.
+ */
+
 var buildYieldAwait = function (keyword) {
   return function (node, print) {
     this.push(keyword);
@@ -117,24 +166,44 @@ var buildYieldAwait = function (keyword) {
   };
 };
 
+/**
+ * Create YieldExpression and AwaitExpression printers.
+ */
+
 export var YieldExpression = buildYieldAwait("yield");
 export var AwaitExpression = buildYieldAwait("await");
 
+/**
+ * Prints EmptyStatement.
+ */
+
 export function EmptyStatement() {
   this.semicolon();
 }
 
+/**
+ * Prints ExpressionStatement, prints expression.
+ */
+
 export function ExpressionStatement(node, print) {
   print.plain(node.expression);
   this.semicolon();
 }
 
+/**
+ * Prints AssignmentPattern, prints left and right.
+ */
+
 export function AssignmentPattern(node, print) {
   print.plain(node.left);
   this.push(" = ");
   print.plain(node.right);
 }
 
+/**
+ * Prints AssignmentExpression, prints left, operator, and right.
+ */
+
 export function AssignmentExpression(node, print) {
   // todo: add cases where the spaces can be dropped when in compact mode
   print.plain(node.left);
@@ -158,17 +227,30 @@ export function AssignmentExpression(node, print) {
   print.plain(node.right);
 }
 
+/**
+ * Prints BindExpression, prints object and callee.
+ */
+
 export function BindExpression(node, print) {
   print.plain(node.object);
   this.push("::");
   print.plain(node.callee);
 }
 
+/**
+ * Alias ClassDeclaration printer as ClassExpression,
+ * and AssignmentExpression printer as LogicalExpression.
+ */
+
 export {
   AssignmentExpression as BinaryExpression,
   AssignmentExpression as LogicalExpression
 };
 
+/**
+ * Print MemberExpression, prints object, property, and value. Handles computed.
+ */
+
 export function MemberExpression(node, print) {
   var obj = node.object;
   print.plain(obj);
@@ -192,6 +274,10 @@ export function MemberExpression(node, print) {
   }
 }
 
+/**
+ * Print MetaProperty, prints meta and property.
+ */
+
 export function MetaProperty(node, print) {
   print.plain(node.meta);
   this.push(".");

src/babel/generation/generators/flow.js

@@ -1,24 +1,44 @@
 import * as t from "../../types";
 
+/**
+ * Prints AnyTypeAnnotation.
+ */
+
 export function AnyTypeAnnotation() {
   this.push("any");
 }
 
+/**
+ * Prints ArrayTypeAnnotation, prints elementType.
+ */
+
 export function ArrayTypeAnnotation(node, print) {
   print.plain(node.elementType);
   this.push("[");
   this.push("]");
 }
 
+/**
+ * Prints BooleanTypeAnnotation.
+ */
+
 export function BooleanTypeAnnotation(node) {
   this.push("bool");
 }
 
+/**
+ * Prints DeclareClass, prints node.
+ */
+
 export function DeclareClass(node, print) {
   this.push("declare class ");
   this._interfaceish(node, print);
 }
 
+/**
+ * Prints DeclareFunction, prints id and id.typeAnnotation.
+ */
+
 export function DeclareFunction(node, print) {
   this.push("declare function ");
   print.plain(node.id);
@@ -26,6 +46,10 @@ export function DeclareFunction(node, print) {
   this.semicolon();
 }
 
+/**
+ * Prints DeclareModule, prints id and body.
+ */
+
 export function DeclareModule(node, print) {
   this.push("declare module ");
   print.plain(node.id);
@@ -33,6 +57,10 @@ export function DeclareModule(node, print) {
   print.plain(node.body);
 }
 
+/**
+ * Prints DeclareVariable, prints id and id.typeAnnotation.
+ */
+
 export function DeclareVariable(node, print) {
   this.push("declare var ");
   print.plain(node.id);
@@ -40,6 +68,10 @@ export function DeclareVariable(node, print) {
   this.semicolon();
 }
 
+/**
+ * Prints FunctionTypeAnnotation, prints typeParameters, params, and rest.
+ */
+
 export function FunctionTypeAnnotation(node, print, parent) {
   print.plain(node.typeParameters);
   this.push("(");
@@ -68,6 +100,10 @@ export function FunctionTypeAnnotation(node, print, parent) {
   print.plain(node.returnType);
 }
 
+/**
+ * Prints FunctionTypeParam, prints name and typeAnnotation, handles optional.
+ */
+
 export function FunctionTypeParam(node, print) {
   print.plain(node.name);
   if (node.optional) this.push("?");
@@ -76,13 +112,26 @@ export function FunctionTypeParam(node, print) {
   print.plain(node.typeAnnotation);
 }
 
+/**
+ * Prints InterfaceExtends, prints id and typeParameters.
+ */
+
 export function InterfaceExtends(node, print) {
   print.plain(node.id);
   print.plain(node.typeParameters);
 }
 
+/**
+ * Alias InterfaceExtends printer as ClassImplements,
+ * and InterfaceExtends printer as GenericTypeAnnotation.
+ */
+
 export { InterfaceExtends as ClassImplements, InterfaceExtends as GenericTypeAnnotation };
 
+/**
+ * Prints interface-like node, prints id, typeParameters, extends, and body.
+ */
+
 export function _interfaceish(node, print) {
   print.plain(node.id);
   print.plain(node.typeParameters);
@@ -94,47 +143,87 @@ export function _interfaceish(node, print) {
   print.plain(node.body);
 }
 
+/**
+ * Prints InterfaceDeclaration, prints node.
+ */
+
 export function InterfaceDeclaration(node, print) {
   this.push("interface ");
   this._interfaceish(node, print);
 }
 
+/**
+ * Prints IntersectionTypeAnnotation, prints types.
+ */
+
 export function IntersectionTypeAnnotation(node, print) {
   print.join(node.types, { separator: " & " });
 }
 
+/**
+ * Prints MixedTypeAnnotation.
+ */
+
 export function MixedTypeAnnotation() {
   this.push("mixed");
 }
 
+/**
+ * Prints NullableTypeAnnotation, prints typeAnnotation.
+ */
+
 export function NullableTypeAnnotation(node, print) {
   this.push("?");
   print.plain(node.typeAnnotation);
 }
 
+/**
+ * Prints NumberTypeAnnotation.
+ */
+
 export function NumberTypeAnnotation() {
   this.push("number");
 }
 
+/**
+ * Prints StringLiteralTypeAnnotation, prints value.
+ */
+
 export function StringLiteralTypeAnnotation(node) {
   this._stringLiteral(node.value);
 }
 
+/**
+ * Prints StringTypeAnnotation.
+ */
+
 export function StringTypeAnnotation() {
   this.push("string");
 }
 
+/**
+ * Prints TupleTypeAnnotation, prints types.
+ */
+
 export function TupleTypeAnnotation(node, print) {
   this.push("[");
   print.join(node.types, { separator: ", " });
   this.push("]");
 }
 
+/**
+ * Prints TypeofTypeAnnotation, prints argument.
+ */
+
 export function TypeofTypeAnnotation(node, print) {
   this.push("typeof ");
   print.plain(node.argument);
 }
 
+/**
+ * Prints TypeAlias, prints id, typeParameters, and right.
+ */
+
 export function TypeAlias(node, print) {
   this.push("type ");
   print.plain(node.id);
@@ -146,6 +235,10 @@ export function TypeAlias(node, print) {
   this.semicolon();
 }
 
+/**
+ * Prints TypeAnnotation, prints typeAnnotation, handles optional.
+ */
+
 export function TypeAnnotation(node, print) {
   this.push(":");
   this.space();
@@ -153,14 +246,26 @@ export function TypeAnnotation(node, print) {
   print.plain(node.typeAnnotation);
 }
 
+/**
+ * Prints TypeParameterInstantiation, prints params.
+ */
+
 export function TypeParameterInstantiation(node, print) {
   this.push("<");
   print.join(node.params, { separator: ", " });
   this.push(">");
 }
 
+/**
+ * Alias TypeParameterInstantiation printer as TypeParameterDeclaration
+ */
+
 export { TypeParameterInstantiation as TypeParameterDeclaration };
 
+/**
+ * Prints ObjectTypeAnnotation, prints properties, callProperties, and indexers.
+ */
+
 export function ObjectTypeAnnotation(node, print) {
   this.push("{");
   var props = node.properties.concat(node.callProperties, node.indexers);
@@ -185,11 +290,19 @@ export function ObjectTypeAnnotation(node, print) {
   this.push("}");
 }
 
+/**
+ * Prints ObjectTypeCallProperty, prints value, handles static.
+ */
+
 export function ObjectTypeCallProperty(node, print) {
   if (node.static) this.push("static ");
   print.plain(node.value);
 }
 
+/**
+ * Prints ObjectTypeIndexer, prints id, key, and value, handles static.
+ */
+
 export function ObjectTypeIndexer(node, print) {
   if (node.static) this.push("static ");
   this.push("[");
@@ -203,6 +316,10 @@ export function ObjectTypeIndexer(node, print) {
   print.plain(node.value);
 }
 
+/**
+ * Prints ObjectTypeProperty, prints static, key, and value.
+ */
+
 export function ObjectTypeProperty(node, print) {
   if (node.static) this.push("static ");
   print.plain(node.key);
@@ -214,16 +331,28 @@ export function ObjectTypeProperty(node, print) {
   print.plain(node.value);
 }
 
+/**
+ * Prints QualifiedTypeIdentifier, prints qualification and id.
+ */
+
 export function QualifiedTypeIdentifier(node, print) {
   print.plain(node.qualification);
   this.push(".");
   print.plain(node.id);
 }
 
+/**
+ * Prints UnionTypeAnnotation, prints types.
+ */
+
 export function UnionTypeAnnotation(node, print) {
   print.join(node.types, { separator: " | " });
 }
 
+/**
+ * Prints TypeCastExpression, prints expression and typeAnnotation.
+ */
+
 export function TypeCastExpression(node, print) {
   this.push("(");
   print.plain(node.expression);
@@ -231,6 +360,10 @@ export function TypeCastExpression(node, print) {
   this.push(")");
 }
 
+/**
+ * Prints VoidTypeAnnotation.
+ */
+
 export function VoidTypeAnnotation(node) {
   this.push("void");
 }

src/babel/generation/generators/jsx.js

@@ -1,5 +1,9 @@
 import * as t from "../../types";
 
+/**
+ * Prints JSXAttribute, prints name and value.
+ */
+
 export function JSXAttribute(node, print) {
   print.plain(node.name);
   if (node.value) {
@@ -8,34 +12,58 @@ export function JSXAttribute(node, print) {
   }
 }
 
+/**
+ * Prints JSXIdentifier, prints name.
+ */
+
 export function JSXIdentifier(node) {
   this.push(node.name);
 }
 
+/**
+ * Prints JSXNamespacedName, prints namespace and name.
+ */
+
 export function JSXNamespacedName(node, print) {
   print.plain(node.namespace);
   this.push(":");
   print.plain(node.name);
 }
 
+/**
+ * Prints JSXMemberExpression, prints object and property.
+ */
+
 export function JSXMemberExpression(node, print) {
   print.plain(node.object);
   this.push(".");
   print.plain(node.property);
 }
 
+/**
+ * Prints JSXSpreadAttribute, prints argument.
+ */
+
 export function JSXSpreadAttribute(node, print) {
   this.push("{...");
   print.plain(node.argument);
   this.push("}");
 }
 
+/**
+ * Prints JSXExpressionContainer, prints expression.
+ */
+
 export function JSXExpressionContainer(node, print) {
   this.push("{");
   print.plain(node.expression);
   this.push("}");
 }
 
+/**
+ * Prints JSXElement, prints openingElement, children, and closingElement.
+ */
+
 export function JSXElement(node, print) {
   var open = node.openingElement;
   print.plain(open);
@@ -54,6 +82,10 @@ export function JSXElement(node, print) {
   print.plain(node.closingElement);
 }
 
+/**
+ * Prints JSXOpeningElement, prints name and attributes, handles selfClosing.
+ */
+
 export function JSXOpeningElement(node, print) {
   this.push("<");
   print.plain(node.name);
@@ -64,10 +96,18 @@ export function JSXOpeningElement(node, print) {
   this.push(node.selfClosing ? " />" : ">");
 }
 
+/**
+ * Prints JSXClosingElement, prints name.
+ */
+
 export function JSXClosingElement(node, print) {
   this.push("</");
   print.plain(node.name);
   this.push(">");
 }
 
+/**
+ * Prints JSXEmptyExpression.
+ */
+
 export function JSXEmptyExpression() {}

src/babel/generation/generators/methods.js

@@ -1,5 +1,9 @@
 import * as t from "../../types";
 
+/**
+ * Prints nodes with params, prints typeParameters, params, and returnType, handles optional params.
+ */
+
 export function _params(node, print) {
   print.plain(node.typeParameters);
   this.push("(");
@@ -16,6 +20,10 @@ export function _params(node, print) {
   }
 }
 
+/**
+ * Prints method-like nodes, prints key, value, and body, handles async, generator, computed, and get or set.
+ */
+
 export function _method(node, print) {
   var value = node.value;
   var kind  = node.kind;
@@ -46,6 +54,10 @@ export function _method(node, print) {
   print.plain(value.body);
 }
 
+/**
+ * Prints FunctionExpression, prints id and body, handles async and generator.
+ */
+
 export function FunctionExpression(node, print) {
   if (node.async) this.push("async ");
   this.push("function");
@@ -63,8 +75,17 @@ export function FunctionExpression(node, print) {
   print.plain(node.body);
 }
 
+/**
+ * Alias FunctionExpression printer as FunctionDeclaration.
+ */
+
 export { FunctionExpression as FunctionDeclaration };
 
+/**
+ * Prints ArrowFunctionExpression, prints params and body, handles async.
+ * Leaves out parentheses when single param.
+ */
+
 export function ArrowFunctionExpression(node, print) {
   if (node.async) this.push("async ");
 

src/babel/generation/generators/modules.js

@@ -1,5 +1,9 @@
 import * as t from "../../types";
 
+/**
+ * Prints ImportSpecifier, prints imported and local.
+ */
+
 export function ImportSpecifier(node, print) {
   print.plain(node.imported);
   if (node.local && node.local.name !== node.imported.name) {
@@ -8,14 +12,26 @@ export function ImportSpecifier(node, print) {
   }
 }
 
+/**
+ * Prints ImportDefaultSpecifier, prints local.
+ */
+
 export function ImportDefaultSpecifier(node, print) {
   print.plain(node.local);
 }
 
+/**
+ * Prints ExportDefaultSpecifier, prints exported.
+ */
+
 export function ExportDefaultSpecifier(node, print) {
   print.plain(node.exported);
 }
 
+/**
+ * Prints ExportSpecifier, prints local and exported.
+ */
+
 export function ExportSpecifier(node, print) {
   print.plain(node.local);
   if (node.exported && node.local.name !== node.exported.name) {
@@ -24,11 +40,19 @@ export function ExportSpecifier(node, print) {
   }
 }
 
+/**
+ * Prints ExportNamespaceSpecifier, prints exported.
+ */
+
 export function ExportNamespaceSpecifier(node, print) {
   this.push("* as ");
   print.plain(node.exported);
 }
 
+/**
+ * Prints ExportAllDeclaration, prints exported and source.
+ */
+
 export function ExportAllDeclaration(node, print) {
   this.push("export *");
   if (node.exported) {
@@ -40,16 +64,28 @@ export function ExportAllDeclaration(node, print) {
   this.semicolon();
 }
 
+/**
+ * Prints ExportNamedDeclaration, delegates to ExportDeclaration.
+ */
+
 export function ExportNamedDeclaration(node, print) {
   this.push("export ");
   ExportDeclaration.call(this, node, print);
 }
 
+/**
+ * Prints ExportDefaultDeclaration, delegates to ExportDeclaration.
+ */
+
 export function ExportDefaultDeclaration(node, print) {
   this.push("export default ");
   ExportDeclaration.call(this, node, print);
 }
 
+/**
+ * Prints ExportDeclaration, prints specifiers, declration, and source.
+ */
+
 function ExportDeclaration(node, print) {
   var specifiers = node.specifiers;
 
@@ -87,11 +123,15 @@ function ExportDeclaration(node, print) {
   this.ensureSemicolon();
 }
 
+/**
+ * Prints ImportDeclaration, prints specifiers and source, handles isType.
+ */
+
 export function ImportDeclaration(node, print) {
   this.push("import ");
 
-  if (node.isType) {
-    this.push("type ");
+  if (node.importKind === "type" || node.importKind === "typeof") {
+    this.push(node.importKind + " ");
   }
 
   var specfiers = node.specifiers;
@@ -119,6 +159,10 @@ export function ImportDeclaration(node, print) {
   this.semicolon();
 }
 
+/**
+ * Prints ImportNamespaceSpecifier, prints local.
+ */
+
 export function ImportNamespaceSpecifier(node, print) {
   this.push("* as ");
   print.plain(node.local);

src/babel/generation/generators/statements.js

@@ -1,6 +1,10 @@
 import repeating from "repeating";
 import * as t from "../../types";
 
+/**
+ * Prints WithStatement, prints object and body.
+ */
+
 export function WithStatement(node, print) {
   this.keyword("with");
   this.push("(");
@@ -9,6 +13,10 @@ export function WithStatement(node, print) {
   print.block(node.body);
 }
 
+/**
+ * Prints IfStatement, prints test, consequent, and alternate.
+ */
+
 export function IfStatement(node, print) {
   this.keyword("if");
   this.push("(");
@@ -25,6 +33,10 @@ export function IfStatement(node, print) {
   }
 }
 
+/**
+ * Prints ForStatement, prints init, test, update, and body.
+ */
+
 export function ForStatement(node, print) {
   this.keyword("for");
   this.push("(");
@@ -47,6 +59,10 @@ export function ForStatement(node, print) {
   print.block(node.body);
 }
 
+/**
+ * Prints WhileStatement, prints test and body.
+ */
+
 export function WhileStatement(node, print) {
   this.keyword("while");
   this.push("(");
@@ -55,6 +71,11 @@ export function WhileStatement(node, print) {
   print.block(node.body);
 }
 
+/**
+ * Builds ForIn or ForOf statement printers.
+ * Prints left, right, and body.
+ */
+
 var buildForXStatement = function (op) {
   return function (node, print) {
     this.keyword("for");
@@ -67,9 +88,17 @@ var buildForXStatement = function (op) {
   };
 };
 
+/**
+ * Create ForInStatement and ForOfStatement printers.
+ */
+
 export var ForInStatement = buildForXStatement("in");
 export var ForOfStatement = buildForXStatement("of");
 
+/**
+ * Prints DoWhileStatement, prints body and test.
+ */
+
 export function DoWhileStatement(node, print) {
   this.push("do ");
   print.plain(node.body);
@@ -80,6 +109,11 @@ export function DoWhileStatement(node, print) {
   this.push(");");
 }
 
+/**
+ * Builds continue, return, or break statement printers.
+ * Prints label (or key).
+ */
+
 var buildLabelStatement = function (prefix, key) {
   return function (node, print) {
     this.push(prefix);
@@ -94,16 +128,28 @@ var buildLabelStatement = function (prefix, key) {
   };
 };
 
+/**
+ * Create ContinueStatement, ReturnStatement, and BreakStatement printers.
+ */
+
 export var ContinueStatement = buildLabelStatement("continue");
 export var ReturnStatement   = buildLabelStatement("return", "argument");
 export var BreakStatement    = buildLabelStatement("break");
 
+/**
+ * Prints LabeledStatement, prints label and body.
+ */
+
 export function LabeledStatement(node, print) {
   print.plain(node.label);
   this.push(": ");
   print.plain(node.body);
 }
 
+/**
+ * Prints TryStatement, prints block, handlers, and finalizer.
+ */
+
 export function TryStatement(node, print) {
   this.keyword("try");
   print.plain(node.block);
@@ -125,6 +171,10 @@ export function TryStatement(node, print) {
   }
 }
 
+/**
+ * Prints CatchClause, prints param and body.
+ */
+
 export function CatchClause(node, print) {
   this.keyword("catch");
   this.push("(");
@@ -133,12 +183,20 @@ export function CatchClause(node, print) {
   print.plain(node.body);
 }
 
+/**
+ * Prints ThrowStatement, prints argument.
+ */
+
 export function ThrowStatement(node, print) {
   this.push("throw ");
   print.plain(node.argument);
   this.semicolon();
 }
 
+/**
+ * Prints SwitchStatement, prints discriminant and cases.
+ */
+
 export function SwitchStatement(node, print) {
   this.keyword("switch");
   this.push("(");
@@ -157,6 +215,10 @@ export function SwitchStatement(node, print) {
   this.push("}");
 }
 
+/**
+ * Prints SwitchCase, prints test and consequent.
+ */
+
 export function SwitchCase(node, print) {
   if (node.test) {
     this.push("case ");
@@ -172,10 +234,18 @@ export function SwitchCase(node, print) {
   }
 }
 
+/**
+ * Prints DebuggerStatement.
+ */
+
 export function DebuggerStatement() {
   this.push("debugger;");
 }
 
+/**
+ * Prints VariableDeclaration, prints declarations, handles kind and format.
+ */
+
 export function VariableDeclaration(node, print, parent) {
   this.push(node.kind + " ");
 
@@ -219,6 +289,10 @@ export function VariableDeclaration(node, print, parent) {
   this.semicolon();
 }
 
+/**
+ * Prints VariableDeclarator, handles id, id.typeAnnotation, and init.
+ */
+
 export function VariableDeclarator(node, print) {
   print.plain(node.id);
   print.plain(node.id.typeAnnotation);

src/babel/generation/generators/template-literals.js

@@ -1,12 +1,24 @@
+/**
+ * Prints TaggedTemplateExpression, prints tag and quasi.
+ */
+
 export function TaggedTemplateExpression(node, print) {
   print.plain(node.tag);
   print.plain(node.quasi);
 }
 
+/**
+ * Prints TemplateElement, prints value.
+ */
+
 export function TemplateElement(node) {
   this._push(node.value.raw);
 }
 
+/**
+ * Prints TemplateLiteral, prints quasis, and expressions.
+ */
+
 export function TemplateLiteral(node, print) {
   this.push("`");
 

src/babel/generation/generators/types.js

@@ -3,17 +3,34 @@
 import isInteger from "is-integer";
 import * as t from "../../types";
 
+/**
+ * Prints Identifier, prints name.
+ */
+
 export function Identifier(node) {
   this.push(node.name);
 }
 
+/**
+ * Prints RestElement, prints argument.
+ */
+
 export function RestElement(node, print) {
   this.push("...");
   print.plain(node.argument);
 }
 
+/**
+ * Alias RestElement printer as SpreadElement,
+ * and RestElement printer as SpreadProperty.
+ */
+
 export { RestElement as SpreadElement, RestElement as SpreadProperty };
 
+/**
+ * Prints ObjectExpression, prints properties.
+ */
+
 export function ObjectExpression(node, print) {
   var props = node.properties;
 
@@ -30,8 +47,16 @@ export function ObjectExpression(node, print) {
   }
 }
 
+/**
+ * Alias ObjectExpression printer as ObjectPattern.
+ */
+
 export { ObjectExpression as ObjectPattern };
 
+/**
+ * Prints Property, prints decorators, key, and value, handles kind, computed, and shorthand.
+ */
+
 export function Property(node, print) {
   print.list(node.decorators, { separator: "" });
 
@@ -66,6 +91,10 @@ export function Property(node, print) {
   }
 }
 
+/**
+ * Prints ArrayExpression, prints elements.
+ */
+
 export function ArrayExpression(node, print) {
   var elems = node.elements;
   var len   = elems.length;
@@ -91,10 +120,22 @@ export function ArrayExpression(node, print) {
   this.push("]");
 }
 
+/**
+ * Alias ArrayExpression printer as ArrayPattern.
+ */
+
 export { ArrayExpression as ArrayPattern };
 
+/**
+ * RegExp for testing scientific notation in literals.
+ */
+
 const SCIENTIFIC_NOTATION = /e/i;
 
+/**
+ * Prints Literal, prints value, regex, raw, handles val type.
+ */
+
 export function Literal(node, print, parent) {
   var val  = node.value;
   var type = typeof val;
@@ -125,6 +166,10 @@ export function Literal(node, print, parent) {
   }
 }
 
+/**
+ * Prints string literals, handles format.
+ */
+
 export function _stringLiteral(val) {
   val = JSON.stringify(val);
 

src/babel/generation/index.js

@@ -11,6 +11,11 @@ import each from "lodash/collection/each";
 import n from "./node";
 import * as t from "../types";
 
+/**
+ * Babel's code generator, turns an ast into code, maintaining sourcemaps,
+ * user preferences, and valid output.
+ */
+
 class CodeGenerator {
   constructor(ast, opts, code) {
     opts = opts || {};
@@ -27,6 +32,13 @@ class CodeGenerator {
     this.buffer     = new Buffer(this.position, this.format);
   }
 
+  /**
+   * Normalize generator options, setting defaults.
+   *
+   * - Detects code indentation.
+   * - If `opts.compact = "auto"` and the code is over 100KB, `compact` will be set to `true`.
+   */
+
   static normalizeOptions(code, opts, tokens) {
     var style = "  ";
     if (code) {
@@ -57,6 +69,9 @@ class CodeGenerator {
     return format;
   }
 
+  /**
+   * Determine if input code uses more single or double quotes.
+   */
   static findCommonStringDelimiter(code, tokens) {
     var occurences = {
       single: 0,
@@ -79,7 +94,6 @@ class CodeGenerator {
       checked++;
       if (checked >= 3) break;
     }
-
     if (occurences.single > occurences.double) {
       return "single";
     } else {
@@ -87,6 +101,10 @@ class CodeGenerator {
     }
   }
 
+  /**
+   * All node generators.
+   */
+
   static generators = {
     templateLiterals: require("./generators/template-literals"),
     comprehensions:   require("./generators/comprehensions"),
@@ -101,6 +119,12 @@ class CodeGenerator {
     jsx:              require("./generators/jsx")
   };
 
+  /**
+   * Generate code and sourcemap from ast.
+   *
+   * Appends comments that weren't attached to any node to the end of the generated output.
+   */
+
   generate() {
     var ast = this.ast;
 
@@ -120,10 +144,18 @@ class CodeGenerator {
     };
   }
 
+  /**
+   * Build NodePrinter.
+   */
+
   buildPrint(parent) {
     return new NodePrinter(this, parent);
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   catchUp(node, parent, leftParenPrinted) {
     // catch up to this nodes newline if we're behind
     if (node.loc && this.format.retainLines && this.buffer.buf) {
@@ -140,6 +172,10 @@ class CodeGenerator {
     return false;
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   _printNewline(leading, node, parent, opts) {
     if (!opts.statement && !n.isUserWhitespacable(node, parent)) {
       return;
@@ -170,6 +206,10 @@ class CodeGenerator {
     this.newline(lines);
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   print(node, parent, opts = {}) {
     if (!node) return;
 
@@ -219,6 +259,10 @@ class CodeGenerator {
     }
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   printJoin(print, nodes, opts = {}) {
     if (!nodes || !nodes.length) return;
 
@@ -248,6 +292,10 @@ class CodeGenerator {
     if (opts.indent) this.dedent();
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   printAndIndentOnComments(print, node) {
     var indent = !!node.leadingComments;
     if (indent) this.indent();
@@ -255,6 +303,10 @@ class CodeGenerator {
     if (indent) this.dedent();
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   printBlock(print, node) {
     if (t.isEmptyStatement(node)) {
       this.semicolon();
@@ -264,6 +316,10 @@ class CodeGenerator {
     }
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   generateComment(comment) {
     var val = comment.value;
     if (comment.type === "CommentLine") {
@@ -274,14 +330,26 @@ class CodeGenerator {
     return val;
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   printTrailingComments(node, parent) {
     this._printComments(this.getComments("trailingComments", node, parent));
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   printLeadingComments(node, parent) {
     this._printComments(this.getComments("leadingComments", node, parent));
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   getComments(key, node, parent) {
     if (t.isExpressionStatement(parent)) {
       return [];
@@ -301,10 +369,18 @@ class CodeGenerator {
     return comments;
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   _getComments(key, node) {
     return (node && node[key]) || [];
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   _printComments(comments) {
     if (this.format.compact) return;
     if (!this.format.comments) return;
@@ -372,16 +448,28 @@ class CodeGenerator {
   }
 }
 
+/**
+ * [Please add a description.]
+ */
+
 each(Buffer.prototype, function (fn, key) {
   CodeGenerator.prototype[key] = function () {
     return fn.apply(this.buffer, arguments);
   };
 });
 
+/**
+ * [Please add a description.]
+ */
+
 each(CodeGenerator.generators, function (generator) {
   extend(CodeGenerator.prototype, generator);
 });
 
+/**
+ * [Please add a description.]
+ */
+
 module.exports = function (ast, opts, code) {
   var gen = new CodeGenerator(ast, opts, code);
   return gen.generate();

src/babel/generation/node/index.js

@@ -4,6 +4,16 @@ import each from "lodash/collection/each";
 import some from "lodash/collection/some";
 import * as t from "../../types";
 
+/**
+ * Test if node matches a set of type-matcher pairs.
+ * @example
+ * find({
+ *   VariableDeclaration(node, parent) {
+ *     return true;
+ *   }
+ * }, node, parent);
+ */
+
 var find = function (obj, node, parent) {
   if (!obj) return;
   var result;
@@ -22,16 +32,28 @@ var find = function (obj, node, parent) {
   return result;
 };
 
+/**
+ * Whitespace and Parenthesis related methods for nodes.
+ */
+
 export default class Node {
   constructor(node, parent) {
     this.parent = parent;
     this.node   = node;
   }
 
+  /**
+   * Test if `node` can have whitespace set by the user.
+   */
+
   static isUserWhitespacable(node) {
     return t.isUserWhitespacable(node);
   }
 
+  /**
+   * Test if a `node` requires whitespace.
+   */
+
   static needsWhitespace(node, parent, type) {
     if (!node) return 0;
 
@@ -54,14 +76,26 @@ export default class Node {
     return (linesInfo && linesInfo[type]) || 0;
   }
 
+  /**
+   * Test if a `node` requires whitespace before it.
+   */
+
   static needsWhitespaceBefore(node, parent) {
     return Node.needsWhitespace(node, parent, "before");
   }
 
+  /**
+   * Test if a `note` requires whitespace after it.
+   */
+
   static needsWhitespaceAfter(node, parent) {
     return Node.needsWhitespace(node, parent, "after");
   }
 
+  /**
+   * Test if a `node` needs parentheses around it.
+   */
+
   static needsParens(node, parent) {
     if (!parent) return false;
 
@@ -77,6 +111,10 @@ export default class Node {
     return find(parens, node, parent);
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   static needsParensNoLineTerminator(node, parent) {
     if (!parent) return false;
 
@@ -89,6 +127,10 @@ export default class Node {
   }
 }
 
+/**
+ * Add all static methods from `Node` to `Node.prototype`.
+ */
+
 each(Node, function (fn, key) {
   Node.prototype[key] = function () {
     // Avoid leaking arguments to prevent deoptimization

src/babel/generation/node/parentheses.js

@@ -1,6 +1,12 @@
 import each from "lodash/collection/each";
 import * as t from "../../types";
 
+/**
+ * Create a mapping of operators to precendence.
+ *
+ * @example
+ * { "==": 6, "+": 9 }
+ */
 const PRECEDENCE = {};
 
 each([
@@ -21,12 +27,24 @@ each([
   });
 });
 
+/**
+ * Test if NullableTypeAnnotation needs parentheses.
+ */
+
 export function NullableTypeAnnotation(node, parent) {
   return t.isArrayTypeAnnotation(parent);
 }
 
+/**
+ * Alias NullableTypeAnnotation test as FunctionTypeAnnotation.
+ */
+
 export { NullableTypeAnnotation as FunctionTypeAnnotation };
 
+/**
+ * Test if UpdateExpression needs parentheses.
+ */
+
 export function UpdateExpression(node, parent) {
   if (t.isMemberExpression(parent) && parent.object === node) {
     // (foo++).test()
@@ -34,6 +52,10 @@ export function UpdateExpression(node, parent) {
   }
 }
 
+/**
+ * Test if ObjectExpression needs parentheses.
+ */
+
 export function ObjectExpression(node, parent) {
   if (t.isExpressionStatement(parent)) {
     // ({ foo: "bar" });
@@ -48,6 +70,10 @@ export function ObjectExpression(node, parent) {
   return false;
 }
 
+/**
+ * Test if Binary needs parentheses.
+ */
+
 export function Binary(node, parent) {
   if ((t.isCallExpression(parent) || t.isNewExpression(parent)) && parent.callee === node) {
     return true;
@@ -78,6 +104,10 @@ export function Binary(node, parent) {
   }
 }
 
+/**
+ * Test if BinaryExpression needs parentheses.
+ */
+
 export function BinaryExpression(node, parent) {
   if (node.operator === "in") {
     // var i = (1 in []);
@@ -92,6 +122,10 @@ export function BinaryExpression(node, parent) {
   }
 }
 
+/**
+ * Test if SequenceExpression needs parentheses.
+ */
+
 export function SequenceExpression(node, parent) {
   if (t.isForStatement(parent)) {
     // Although parentheses wouldn't hurt around sequence
@@ -110,6 +144,10 @@ export function SequenceExpression(node, parent) {
   return true;
 }
 
+/**
+ * Test if YieldExpression needs parentheses.
+ */
+
 export function YieldExpression(node, parent) {
   return t.isBinary(parent) ||
          t.isUnaryLike(parent) ||
@@ -120,14 +158,26 @@ export function YieldExpression(node, parent) {
          t.isYieldExpression(parent);
 }
 
+/**
+ * Test if ClassExpression needs parentheses.
+ */
+
 export function ClassExpression(node, parent) {
   return t.isExpressionStatement(parent);
 }
 
+/**
+ * Test if UnaryLike needs parentheses.
+ */
+
 export function UnaryLike(node, parent) {
   return t.isMemberExpression(parent) && parent.object === node;
 }
 
+/**
+ * Test if FunctionExpression needs parentheses.
+ */
+
 export function FunctionExpression(node, parent) {
   // function () {};
   if (t.isExpressionStatement(parent)) {
@@ -145,6 +195,10 @@ export function FunctionExpression(node, parent) {
   }
 }
 
+/**
+ * Test if ConditionalExpression needs parentheses.
+ */
+
 export function ConditionalExpression(node, parent) {
   if (t.isUnaryLike(parent)) {
     return true;
@@ -171,6 +225,10 @@ export function ConditionalExpression(node, parent) {
   return false;
 }
 
+/**
+ * Test if AssignmentExpression needs parentheses.
+ */
+
 export function AssignmentExpression(node) {
   if (t.isObjectPattern(node.left)) {
     return true;

src/babel/generation/node/printer.js

@@ -1,22 +1,42 @@
+/**
+ * Printer for nodes, needs a `generator` and a `parent`.
+ */
+
 export default class NodePrinter {
   constructor(generator, parent) {
     this.generator = generator;
     this.parent = parent;
   }
 
+  /**
+   * Print a plain node.
+   */
+
   plain(node, opts) {
     return this.generator.print(node, this.parent, opts);
   }
 
+  /**
+   * Print a sequence of nodes as statements.
+   */
+
   sequence(nodes, opts = {}) {
     opts.statement = true;
     return this.generator.printJoin(this, nodes, opts);
   }
 
+  /**
+   * Print a sequence of nodes as expressions.
+   */
+
   join(nodes, opts) {
     return this.generator.printJoin(this, nodes, opts);
   }
 
+  /**
+   * Print a list of nodes, with a customizable separator (defaults to ",").
+   */
+
   list(items, opts = {}) {
     if (opts.separator == null) {
       opts.separator = ",";
@@ -26,10 +46,18 @@ export default class NodePrinter {
     return this.join(items, opts);
   }
 
+  /**
+   * Print a block-like node.
+   */
+
   block(node) {
     return this.generator.printBlock(this, node);
   }
 
+  /**
+   * Print node and indent comments.
+   */
+
   indentOnComments(node) {
     return this.generator.printAndIndentOnComments(this, node);
   }

src/babel/generation/node/whitespace.js

@@ -3,6 +3,14 @@ import each from "lodash/collection/each";
 import map from "lodash/collection/map";
 import * as t from "../../types";
 
+/**
+ * Crawl a node to test if it contains a CallExpression, a Function, or a Helper.
+ *
+ * @example
+ * crawl(node)
+ * // { hasCall: false, hasFunction: true, hasHelper: false }
+ */
+
 function crawl(node, state = {}) {
   if (t.isMemberExpression(node)) {
     crawl(node.object, state);
@@ -22,6 +30,10 @@ function crawl(node, state = {}) {
   return state;
 }
 
+/**
+ * Test if a node is or has a helper.
+ */
+
 function isHelper(node) {
   if (t.isMemberExpression(node)) {
     return isHelper(node.object) || isHelper(node.property);
@@ -36,12 +48,25 @@ function isHelper(node) {
   }
 }
 
+/**
+ * [Please add a description.]
+ */
+
 function isType(node) {
   return t.isLiteral(node) || t.isObjectExpression(node) || t.isArrayExpression(node) ||
          t.isIdentifier(node) || t.isMemberExpression(node);
 }
 
+/**
+ * Tests for node types that need whitespace.
+ */
+
 exports.nodes = {
+
+  /**
+   * Test if AssignmentExpression needs whitespace.
+   */
+
   AssignmentExpression(node) {
     var state = crawl(node.right);
     if ((state.hasCall && state.hasHelper) || state.hasFunction) {
@@ -52,12 +77,20 @@ exports.nodes = {
     }
   },
 
+  /**
+   * Test if SwitchCase needs whitespace.
+   */
+
   SwitchCase(node, parent) {
     return {
       before: node.consequent.length || parent.cases[0] === node
     };
   },
 
+  /**
+   * Test if LogicalExpression needs whitespace.
+   */
+
   LogicalExpression(node) {
     if (t.isFunction(node.left) || t.isFunction(node.right)) {
       return {
@@ -66,6 +99,10 @@ exports.nodes = {
     }
   },
 
+  /**
+   * Test if Literal needs whitespace.
+   */
+
   Literal(node) {
     if (node.value === "use strict") {
       return {
@@ -74,6 +111,10 @@ exports.nodes = {
     }
   },
 
+  /**
+   * Test if CallExpression needs whitespace.
+   */
+
   CallExpression(node) {
     if (t.isFunction(node.callee) || isHelper(node)) {
       return {
@@ -83,6 +124,10 @@ exports.nodes = {
     }
   },
 
+  /**
+   * Test if VariableDeclaration needs whitespace.
+   */
+
   VariableDeclaration(node) {
     for (var i = 0; i < node.declarations.length; i++) {
       var declar = node.declarations[i];
@@ -102,6 +147,10 @@ exports.nodes = {
     }
   },
 
+  /**
+   * Test if IfStatement needs whitespace.
+   */
+
   IfStatement(node) {
     if (t.isBlockStatement(node.consequent)) {
       return {
@@ -112,6 +161,10 @@ exports.nodes = {
   }
 };
 
+/**
+ * Test if Property or SpreadProperty needs whitespace.
+ */
+
 exports.nodes.Property =
 exports.nodes.SpreadProperty = function (node, parent) {
   if (parent.properties[0] === node) {
@@ -121,20 +174,41 @@ exports.nodes.SpreadProperty = function (node, parent) {
   }
 };
 
+/**
+ * Returns lists from node types that need whitespace.
+ */
+
 exports.list = {
+
+  /**
+   * Return VariableDeclaration declarations init properties.
+   */
+
   VariableDeclaration(node) {
     return map(node.declarations, "init");
   },
 
+  /**
+   * Return VariableDeclaration elements.
+   */
+
   ArrayExpression(node) {
     return node.elements;
   },
 
+  /**
+   * Return VariableDeclaration properties.
+   */
+
   ObjectExpression(node) {
     return node.properties;
   }
 };
 
+/**
+ * Add whitespace tests for nodes and their aliases.
+ */
+
 each({
   Function: true,
   Class: true,

src/babel/generation/position.js

@@ -1,9 +1,17 @@
+/**
+ * Track current position in code generation.
+ */
+
 export default class Position {
   constructor() {
     this.line = 1;
     this.column = 0;
   }
 
+  /**
+   * Push a string to the current position, mantaining the current line and column.
+   */
+
   push(str) {
     for (var i = 0; i < str.length; i++) {
       if (str[i] === "\n") {
@@ -15,6 +23,10 @@ export default class Position {
     }
   }
 
+  /**
+   * Unshift a string from the current position, mantaining the current line and column.
+   */
+
   unshift(str) {
     for (var i = 0; i < str.length; i++) {
       if (str[i] === "\n") {

src/babel/generation/source-map.js

@@ -1,6 +1,10 @@
 import sourceMap from "source-map";
 import * as t from "../types";
 
+/**
+ * Build a sourcemap.
+ */
+
 export default class SourceMap {
   constructor(position, opts, code) {
     this.position = position;
@@ -18,6 +22,10 @@ export default class SourceMap {
     }
   }
 
+  /**
+   * Get the sourcemap.
+   */
+
   get() {
     var map = this.map;
     if (map) {
@@ -27,6 +35,10 @@ export default class SourceMap {
     }
   }
 
+  /**
+   * Mark a node's generated position, and add it to the sourcemap.
+   */
+
   mark(node, type) {
     var loc = node.loc;
     if (!loc) return; // no location info

src/babel/generation/whitespace.js

@@ -18,6 +18,10 @@ function getLookupIndex(i, base, max) {
   return i;
 }
 
+/**
+ * Get whitespace around tokens.
+ */
+
 export default class Whitespace {
   constructor(tokens) {
     this.tokens = tokens;
@@ -34,6 +38,10 @@ export default class Whitespace {
     this._lastFoundIndex = 0;
   }
 
+  /**
+   * Count all the newlines before a node.
+   */
+
   getNewlinesBefore(node) {
     var startToken;
     var endToken;
@@ -57,6 +65,10 @@ export default class Whitespace {
     return this.getNewlinesBetween(startToken, endToken);
   }
 
+  /**
+   * Count all the newlines after a node.
+   */
+
   getNewlinesAfter(node) {
     var startToken;
     var endToken;
@@ -91,6 +103,10 @@ export default class Whitespace {
     }
   }
 
+  /**
+   * Count all the newlines between two tokens.
+   */
+
   getNewlinesBetween(startToken, endToken) {
     if (!endToken || !endToken.loc) return 0;
 

src/babel/helpers/README.md

@@ -0,0 +1,4 @@
+## Helpers
+
+Utilities for Babel, which is just another way to say "helpers", but I wrote it
+anyways, so– deal with it.

src/babel/helpers/code-frame.js

@@ -4,6 +4,10 @@ import jsTokens from "js-tokens";
 import esutils from "esutils";
 import chalk from "chalk";
 
+/**
+ * Chalk styles for token types.
+ */
+
 var defs = {
   string:     chalk.red,
   punctuator: chalk.bold,
@@ -17,8 +21,16 @@ var defs = {
   invalid:    chalk.inverse
 };
 
+/**
+ * RegExp to test for newlines in terminal.
+ */
+
 const NEWLINE = /\r\n|[\n\r\u2028\u2029]/;
 
+/**
+ * Get the type of token, specifying punctuator type.
+ */
+
 function getTokenType(match) {
   var token = jsTokens.matchToToken(match);
   if (token.type === "name" && esutils.keyword.isReservedWordES6(token.value)) {
@@ -42,6 +54,10 @@ function getTokenType(match) {
   return token.type;
 }
 
+/**
+ * Highlight `text`.
+ */
+
 function highlight(text) {
   return text.replace(jsTokens, function (...args) {
     var type = getTokenType(args);
@@ -54,6 +70,10 @@ function highlight(text) {
   });
 }
 
+/**
+ * Create a code frame, adding line numbers, code highlighting, and pointing to a given position.
+ */
+
 export default function (lines: number, lineNumber: number, colNumber: number, opts = {}): string {
   colNumber = Math.max(colNumber, 0);
 

src/babel/helpers/merge.js

@@ -1,10 +1,14 @@
 import merge from "lodash/object/merge";
 
+/**
+ * Merge options.
+ */
+
 export default function (dest, src) {
   if (!dest || !src) return;
 
-  return merge(dest, src, function(a, b) {
-    if (Array.isArray(a)) {
+  return merge(dest, src, function (a, b) {
+    if (b && Array.isArray(a)) {
       var c = a.slice(0);
       for (var v of b) {
         if (a.indexOf(v) < 0) {

src/babel/helpers/normalize-ast.js

@@ -1,5 +1,11 @@
 import * as t from "../types";
 
+/**
+ * Normalize an AST.
+ *
+ * - Wrap `Program` node with a `File` node.
+ */
+
 export default function (ast, comments, tokens) {
   if (ast && ast.type === "Program") {
     return t.file(ast, comments || [], tokens || []);

src/babel/helpers/object.js

@@ -1,3 +1,7 @@
+/**
+ * Create an object with a `null` prototype.
+ */
+
 export default function () {
   return Object.create(null);
 }

src/babel/helpers/parse.js

@@ -2,6 +2,10 @@ import normalizeAst from "./normalize-ast";
 import estraverse from "estraverse";
 import * as acorn from "../../acorn";
 
+/**
+ * Parse `code` with normalized options, collecting tokens and comments.
+ */
+
 export default function (code, opts = {}) {
   var commentsAndTokens = [];
   var comments          = [];
@@ -21,11 +25,17 @@ export default function (code, opts = {}) {
     ranges:                      true
   };
 
+  /**
+   * Collect all tokens.
+   */
   parseOpts.onToken = function (token) {
     tokens.push(token);
     commentsAndTokens.push(token);
   };
 
+  /**
+   * Collection all comments.
+   */
   parseOpts.onComment = function (block, text, start, end, startLoc, endLoc) {
     var comment = {
       type: block ? "CommentBlock" : "CommentLine",

src/babel/messages.js

@@ -1,7 +1,12 @@
 import * as util from  "util";
 
+/**
+ * Mapping of messages to be used in Babel.
+ * Messages can include $0-style placeholders.
+ */
+
 export const MESSAGES = {
-  tailCallReassignmentDeopt: "Function reference has been reassigned so it's probably be dereferenced so we can't optimise this with confidence",
+  tailCallReassignmentDeopt: "Function reference has been reassigned, so it will probably be dereferenced, therefore we can't optimise this with confidence",
   JSXNamespacedTags: "Namespace tags are not supported. ReactJSX is not XML.",
   classesIllegalBareSuper: "Illegal use of bare super",
   classesIllegalSuperCall: "Direct super call is illegal in non-constructor, use super.$1() instead",
@@ -17,7 +22,7 @@ export const MESSAGES = {
   missingTemplatesDirectory: "no templates directory - this is most likely the result of a broken `npm publish`. Please report to https://github.com/babel/babel/issues",
   unsupportedOutputType: "Unsupported output type $1",
   illegalMethodName: "Illegal method name $1",
-  lostTrackNodePath: "We lost track of this nodes position, likely because the AST was directly manipulated",
+  lostTrackNodePath: "We lost track of this node's position, likely because the AST was directly manipulated",
 
   modulesIllegalExportName: "Illegal export $1",
   modulesDuplicateDeclarations: "Duplicate module declarations with the same source but in different scopes",
@@ -26,7 +31,7 @@ export const MESSAGES = {
   undeclaredVariableType: "Referencing a type alias outside of a type annotation",
   undeclaredVariableSuggestion: "Reference to undeclared variable $1 - did you mean $2?",
 
-  traverseNeedsParent: "Must pass a scope and parentPath unless traversing a Program/File got a $1 node",
+  traverseNeedsParent: "You must pass a scope and parentPath unless traversing a Program/File got a $1 node",
   traverseVerifyRootFunction: "You passed `traverse()` a function when it expected a visitor object, are you sure you didn't mean `{ enter: Function }`?",
   traverseVerifyVisitorProperty: "You passed `traverse()` a visitor object with the property $1 that has the invalid property $2",
   traverseVerifyNodeType: "You gave us a visitor for the node type $1 but it's not a valid type",
@@ -37,21 +42,41 @@ export const MESSAGES = {
   pluginNotTransformer: "The plugin $1 didn't export a Plugin instance",
   pluginUnknown: "Unknown plugin $1",
 
-  pluginNotFile: "Plugin $1 is resolving to a different Babel version to what is doing the actual transformation..."
+  pluginNotFile: "Plugin $1 is resolving to a different Babel version than what is performing the transformation.",
+
+  pluginInvalidProperty: "Plugin $1 provided an invalid property of $2.",
+  pluginInvalidPropertyVisitor: `Define your visitor methods inside a \`visitor\` property like so:
+
+  new Plugin("foobar", {
+    visitor: {
+      // define your visitor methods here!
+    }
+  });
+`
 };
 
-export function get(key: String, ...args) {
+/**
+ * Get a message with $0 placeholders replaced by arguments.
+ */
+
+export function get(key: string, ...args): string {
   var msg = MESSAGES[key];
   if (!msg) throw new ReferenceError(`Unknown message ${JSON.stringify(key)}`);
 
+  // stringify args
   args = parseArgs(args);
 
+  // replace $0 placeholders with args
   return msg.replace(/\$(\d+)/g, function (str, i) {
     return args[--i];
   });
 }
 
-export function parseArgs(args: Array<any>) {
+/**
+ * Stingify arguments to be used inside messages.
+ */
+
+export function parseArgs(args: Array<any>): Array<string> {
   return args.map(function (val) {
     if (val != null && val.inspect) {
       return val.inspect();

src/babel/patch.js

@@ -1,83 +1,7 @@
 import estraverse from "estraverse";
 import extend from "lodash/object/extend";
-import types from "ast-types";
 import * as t from "./types";
 
 // estraverse
 
 extend(estraverse.VisitorKeys, t.VISITOR_KEYS);
-
-// regenerator/ast-types
-
-var def = types.Type.def;
-var or  = types.Type.or;
-
-//def("File")
-//  .bases("Node")
-//  .build("program")
-//  .field("program", def("Program"));
-
-def("Noop");
-
-def("AssignmentPattern")
-  .bases("Pattern")
-  .build("left", "right")
-  .field("left", def("Pattern"))
-  .field("right", def("Expression"));
-
-def("RestElement")
-  .bases("Pattern")
-  .build("argument")
-  .field("argument", def("expression"));
-
-def("DoExpression")
-  .bases("Expression")
-  .build("body")
-  .field("body", [def("Statement")]);
-
-def("Super")
-  .bases("Expression");
-
-def("ExportDefaultDeclaration")
-  .bases("Declaration")
-  .build("declaration")
-  .field("declaration", or(
-    def("Declaration"),
-    def("Expression"),
-    null
-  ));
-
-def("ExportNamedDeclaration")
-  .bases("Declaration")
-  .build("declaration")
-  .field("declaration", or(
-    def("Declaration"),
-    def("Expression"),
-    null
-  ))
-  .field("specifiers", [or(
-    def("ExportSpecifier")
-  )])
-  .field("source", or(def("ModuleSpecifier"), null));
-
-def("ExportNamespaceSpecifier")
-  .bases("Specifier")
-  .field("exported", def("Identifier"));
-
-def("ExportDefaultSpecifier")
-  .bases("Specifier")
-  .field("exported", def("Identifier"));
-
-def("ExportAllDeclaration")
-  .bases("Declaration")
-  .build("exported", "source")
-  .field("exported", def("Identifier"))
-  .field("source", def("Literal"));
-
-def("BindExpression")
-  .bases("Expression")
-  .build("object", "callee")
-  .field("object", or(def("Expression"), null))
-  .field("callee", def("Expression"));
-
-types.finalize();

src/babel/tools/README.md

@@ -0,0 +1,15 @@
+## Tools
+
+> This directory is best browsed while listening to
+> https://www.youtube.com/watch?v=hglVqACd1C8.
+
+### Protect Babel
+
+The protect script seen here is to throw errors if someone ever tries to
+include internal babel files in their script. If you need something to be
+exposed, you should ask for it, not try to hack your way into getting it.
+
+### External Helpers
+
+You'll also find the script for building the external helpers file, this is
+the Babel "runtime" where all helper functions go instead of the top of a file.

src/babel/tools/build-external-helpers.js

@@ -5,6 +5,10 @@ import File from "../transformation/file";
 import each from "lodash/collection/each";
 import * as t from "../types";
 
+/**
+ * [Please add a description.]
+ */
+
 function buildGlobal(namespace, builder) {
   var body      = [];
   var container = t.functionExpression(null, [t.identifier("global")], t.blockStatement(body));
@@ -22,6 +26,10 @@ function buildGlobal(namespace, builder) {
   return tree;
 }
 
+/**
+ * [Please add a description.]
+ */
+
 function buildUmd(namespace, builder) {
   var body = [];
   body.push(t.variableDeclaration("var", [
@@ -41,6 +49,10 @@ function buildUmd(namespace, builder) {
   return t.program([container]);
 }
 
+/**
+ * [Please add a description.]
+ */
+
 function buildVar(namespace, builder) {
   var body = [];
   body.push(t.variableDeclaration("var", [
@@ -50,6 +62,10 @@ function buildVar(namespace, builder) {
   return t.program(body);
 }
 
+/**
+ * [Please add a description.]
+ */
+
 function buildHelpers(body, namespace, whitelist) {
   each(File.helpers, function (name) {
     if (whitelist && whitelist.indexOf(name) === -1) return;
@@ -61,6 +77,10 @@ function buildHelpers(body, namespace, whitelist) {
   });
 }
 
+/**
+ * [Please add a description.]
+ */
+
 export default function (whitelist, outputType = "global") {
   var namespace = t.identifier("babelHelpers");
 

src/babel/tools/protect.js

@@ -2,6 +2,11 @@ import path from "path";
 
 var root = path.resolve(__dirname, "../../../");
 
+/**
+ * Protect Babel internals from being hotlinked by other tools.
+ * Sorry, not sorry.
+ */
+
 export default function (module) {
   if (module.parent && module.parent.filename.indexOf(root) !== 0) {
     throw new Error("Don't hotlink internal Babel files.");

src/babel/transformation/README.md

@@ -0,0 +1,3 @@
+## Transformation
+
+This is the Transformation directory.

src/babel/transformation/file/README.md

@@ -0,0 +1,3 @@
+## File Transformation
+
+This is the File Transformation directory.

src/babel/transformation/file/index.js

@@ -1,30 +1,28 @@
-import { validateOption, normaliseOptions, config as optionsConfig } from "./options";
 import convertSourceMap from "convert-source-map";
 import moduleFormatters from "../modules";
+import OptionManager from "./options/option-manager";
 import PluginManager from "./plugin-manager";
 import shebangRegex from "shebang-regex";
 import NodePath from "../../traversal/path";
 import isFunction from "lodash/lang/isFunction";
-import isAbsolute from "path-is-absolute";
-import resolveRc from "./options/resolve-rc";
 import sourceMap from "source-map";
 import generate from "../../generation";
 import codeFrame from "../../helpers/code-frame";
 import defaults from "lodash/object/defaults";
 import includes from "lodash/collection/includes";
 import traverse from "../../traversal";
-import assign from "lodash/object/assign";
 import Logger from "./logger";
 import Plugin from "../plugin";
 import parse from "../../helpers/parse";
-import merge from "../../helpers/merge";
-import slash from "slash";
-import clone from "lodash/lang/clone";
 import Hub from "../../traversal/hub";
 import * as util from  "../../util";
 import path from "path";
 import * as t from "../../types";
 
+/**
+ * [Please add a description.]
+ */
+
 export default class File {
   constructor(opts = {}, pipeline) {
     this.transformerDependencies = {};
@@ -50,15 +48,18 @@ export default class File {
 
     this.pipeline = pipeline;
     this.log      = new Logger(this, opts.filename || "unknown");
+    this.opts     = this.initOptions(opts);
     this.ast      = {};
 
-    this.normaliseOptions(opts);
-
     this.buildTransformers();
 
     this.hub = new Hub(this);
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   static helpers = [
     "inherits",
     "defaults",
@@ -93,72 +94,27 @@ export default class File {
     "instanceof",
 
     // legacy
-    "interop-require",
+    "interop-require"
   ];
 
+  /**
+   * [Please add a description.]
+   */
+
   static soloHelpers = [];
 
-  static options = optionsConfig;
 
-  normaliseOptions(opts: Object) {
-    opts = this.opts = normaliseOptions(assign({}, opts));
+  /**
+   * [Please add a description.]
+   */
 
-    // resolve babelrc
-    if (opts.filename) {
-      var rcFilename = opts.filename;
-      if (!isAbsolute(rcFilename)) rcFilename = path.join(process.cwd(), rcFilename);
-      opts = resolveRc(rcFilename, opts);
-    }
-
-    // check for unknown options
-    for (let key in opts) {
-      if (key[0] === "_") continue;
-
-      let option = File.options[key];
-      if (!option) this.log.error(`Unknown option: ${key}`, ReferenceError);
-    }
-
-    // merge in environment options
-    var envKey = process.env.BABEL_ENV || process.env.NODE_ENV || "development";
-    if (opts.env) merge(opts, normaliseOptions(opts.env[envKey]));
-
-    // normalise options
-    for (let key in File.options) {
-      let option = File.options[key];
-      var val    = opts[key];
-
-      // optional
-      if (!val && option.optional) continue;
-
-      // deprecated
-      if (val && option.deprecated) {
-        this.log.deprecate("Deprecated option " + key + ": " + option.deprecated);
-      }
-
-      // default
-      if (val == null) val = clone(option.default);
-
-      // validate
-      if (val) val = validateOption(key, val, this.pipeline);
-
-      // aaliases
-      if (option.alias) {
-        opts[option.alias] = opts[option.alias] || val;
-      } else {
-        opts[key] = val;
-      }
-    }
+  initOptions(opts) {
+    opts = new OptionManager(this.log, this.pipeline).init(opts);
 
     if (opts.inputSourceMap) {
       opts.sourceMaps = true;
     }
 
-    // normalize windows path separators to unix
-    opts.filename = slash(opts.filename);
-    if (opts.sourceRoot) {
-      opts.sourceRoot = slash(opts.sourceRoot);
-    }
-
     if (opts.moduleId) {
       opts.moduleIds = true;
     }
@@ -167,9 +123,7 @@ export default class File {
 
     opts.ignore = util.arrayify(opts.ignore, util.regexify);
 
-    if (opts.only) {
-      opts.only = util.arrayify(opts.only, util.regexify);
-    }
+    if (opts.only) opts.only = util.arrayify(opts.only, util.regexify);
 
     defaults(opts, {
       moduleRoot: opts.sourceRoot
@@ -195,12 +149,20 @@ export default class File {
     }
 
     return opts;
-  };
+  }
+
+  /**
+   * [Please add a description.]
+   */
 
   isLoose(key: string) {
     return includes(this.opts.loose, key);
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   buildTransformers() {
     var file = this;
 
@@ -255,6 +217,10 @@ export default class File {
     this.transformerStack = this.collapseStack(stack);
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   collapseStack(_stack) {
     var stack  = [];
     var ignore = [];
@@ -291,14 +257,26 @@ export default class File {
     return stack;
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   set(key: string, val): any {
     return this.data[key] = val;
-  };
+  }
+
+  /**
+   * [Please add a description.]
+   */
 
   setDynamic(key: string, fn: Function) {
     this.dynamicData[key] = fn;
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   get(key: string): any {
     var data = this.data[key];
     if (data) {
@@ -311,12 +289,20 @@ export default class File {
     }
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   resolveModuleSource(source: string): string {
     var resolveModuleSource = this.opts.resolveModuleSource;
     if (resolveModuleSource) source = resolveModuleSource(source, this.opts.filename);
     return source;
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   addImport(source: string, name?: string, type?: string): Object {
     name = name || source;
     var id = this.dynamicImportIds[name];
@@ -345,6 +331,10 @@ export default class File {
     return id;
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   attachAuxiliaryComment(node: Object): Object {
     var beforeComment = this.opts.auxiliaryCommentBefore;
     if (beforeComment) {
@@ -367,6 +357,10 @@ export default class File {
     return node;
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   addHelper(name: string): Object {
     var isSolo = includes(File.soloHelpers, name);
 
@@ -413,6 +407,10 @@ export default class File {
     return uid;
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   errorWithNode(node, msg, Error = SyntaxError) {
     var err;
     if (node && node.loc) {
@@ -426,6 +424,10 @@ export default class File {
     return err;
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   mergeSourceMap(map: Object) {
     var opts = this.opts;
 
@@ -448,6 +450,9 @@ export default class File {
     return map;
   }
 
+  /**
+   * [Please add a description.]
+   */
 
   getModuleFormatter(type: string) {
     if (isFunction(type) || !moduleFormatters[type]) {
@@ -468,6 +473,10 @@ export default class File {
     return new ModuleFormatter(this);
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   parse(code: string) {
     var opts = this.opts;
 
@@ -496,6 +505,10 @@ export default class File {
     return tree;
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   _addAst(ast) {
     this.path = NodePath.get({
       hub: this.hub,
@@ -508,6 +521,10 @@ export default class File {
     this.ast   = ast;
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   addAst(ast) {
     this.log.debug("Start set AST");
     this._addAst(ast);
@@ -521,6 +538,10 @@ export default class File {
     this.log.debug("End module formatter init");
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   transform() {
     this.call("pre");
     for (var pass of (this.transformerStack: Array)) {
@@ -531,6 +552,10 @@ export default class File {
     return this.generate();
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   wrap(code, callback) {
     code = code + "";
 
@@ -568,22 +593,38 @@ export default class File {
     }
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   addCode(code: string) {
     code = (code || "") + "";
     code = this.parseInputSourceMap(code);
     this.code = code;
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   parseCode() {
     this.parseShebang();
     this.addAst(this.parse(this.code));
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   shouldIgnore() {
     var opts = this.opts;
     return util.shouldIgnore(opts.filename, opts.ignore, opts.only);
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   call(key: string) {
     for (var pass of (this.uncollapsedTransformerStack: Array)) {
       var fn = pass.plugin[key];
@@ -591,6 +632,10 @@ export default class File {
     }
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   parseInputSourceMap(code: string) {
     var opts = this.opts;
 
@@ -605,6 +650,10 @@ export default class File {
     return code;
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   parseShebang() {
     var shebangMatch = shebangRegex.exec(this.code);
     if (shebangMatch) {
@@ -613,6 +662,10 @@ export default class File {
     }
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   makeResult({ code, map = null, ast, ignored }) {
     var result = {
       metadata: null,
@@ -638,6 +691,10 @@ export default class File {
     return result;
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   generate() {
     var opts = this.opts;
     var ast  = this.ast;

src/babel/transformation/file/logger.js

@@ -6,26 +6,46 @@ var generalDebug = buildDebug("babel");
 
 var seenDeprecatedMessages = [];
 
+/**
+ * [Please add a description.]
+ */
+
 export default class Logger {
   constructor(file: File, filename: string) {
     this.filename = filename;
     this.file     = file;
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   _buildMessage(msg: string): string {
     var parts = `[BABEL] ${this.filename}`;
     if (msg) parts += `: ${msg}`;
     return parts;
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   warn(msg) {
     console.warn(this._buildMessage(msg));
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   error(msg: string, Constructor = Error) {
     throw new Constructor(this._buildMessage(msg));
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   deprecate(msg) {
     if (this.file.opts.suppressDeprecationMessages) return;
 
@@ -40,14 +60,26 @@ export default class Logger {
     console.error(msg);
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   verbose(msg: string) {
     if (verboseDebug.enabled) verboseDebug(this._buildMessage(msg));
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   debug(msg: string) {
     if (generalDebug.enabled) generalDebug(this._buildMessage(msg));
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   deopt(node: Object, msg: string) {
     this.debug(msg);
   }

src/babel/transformation/file/options/README.md

@@ -0,0 +1,3 @@
+## File Options
+
+This is the File Options directory.

src/babel/transformation/file/options/config.json

@@ -1,6 +1,6 @@
 {
   "filename": {
-    "type": "string",
+    "type": "filename",
     "description": "filename to use when reading from stdin - this will be used in source-maps, errors etc",
     "default": "unknown",
     "shorthand": "f"
@@ -236,12 +236,12 @@
   },
 
   "sourceRoot": {
-    "type": "string",
+    "type": "filename",
     "description": "the root from which all sources are relative"
   },
 
   "moduleRoot": {
-    "type": "string",
+    "type": "filename",
     "description": "optional prefix for the AMD module formatter that will be prepend to the filename on module definitions"
   },
 
@@ -253,7 +253,7 @@
   },
 
   "babelrc": {
-    "hidden": true,
-    "description": "do not load the same .babelrc file twice"
+    "description": "Specify a custom list of babelrc files to use",
+    "type": "list"
   }
 }

src/babel/transformation/file/options/index.js

@@ -3,6 +3,10 @@ import config from "./config";
 
 export { config };
 
+/**
+ * Validate an option.
+ */
+
 export function validateOption(key, val, pipeline) {
   var opt = config[key];
   var parser = opt && parsers[opt.type];
@@ -13,6 +17,10 @@ export function validateOption(key, val, pipeline) {
   }
 }
 
+/**
+ * Normalize all options.
+ */
+
 export function normaliseOptions(options = {}) {
   for (var key in options) {
     var val = options[key];

src/babel/transformation/file/options/option-manager.js

@@ -0,0 +1,170 @@
+import { validateOption, normaliseOptions } from "./index";
+import stripJsonComments from "strip-json-comments";
+import isAbsolute from "path-is-absolute";
+import pathExists from "path-exists";
+import clone from "lodash/lang/clone";
+import merge from "../../../helpers/merge";
+import config from "./config";
+import path from "path";
+import fs from "fs";
+
+var existsCache = {};
+var jsonCache   = {};
+
+const CONFIG_FILENAME = ".babelrc";
+
+function exists(filename) {
+  var cached = existsCache[filename];
+  if (cached != null) {
+    return cached;
+  } else {
+    return existsCache[filename] = pathExists.sync(filename);
+  }
+}
+
+export default class OptionManager {
+  constructor(log, pipeline) {
+    this.resolvedConfigs = [];
+    this.options         = OptionManager.createBareOptions();
+    this.pipeline        = pipeline;
+    this.log             = log;
+  }
+
+  /**
+   * [Please add a description.]
+   */
+
+  static createBareOptions() {
+    var opts = {};
+
+    for (var key in config) {
+      var opt = config[key];
+      opts[key] = clone(opt.default);
+    }
+
+    return opts;
+  }
+
+  /**
+   * [Please add a description.]
+   */
+
+  addConfig(loc) {
+    if (this.resolvedConfigs.indexOf(loc) >= 0) return;
+
+    var content = fs.readFileSync(loc, "utf8");
+    var opts;
+
+    try {
+      opts = jsonCache[content] = jsonCache[content] || JSON.parse(stripJsonComments(content));
+    } catch (err) {
+      err.message = `${loc}: ${err.message}`;
+      throw err;
+    }
+
+    this.mergeOptions(opts, loc);
+    this.resolvedConfigs.push(loc);
+  }
+
+  /**
+   * [Please add a description.]
+   */
+
+  mergeOptions(opts, alias = "foreign") {
+    if (!opts) return;
+
+    for (let key in opts) {
+      if (key[0] === "_") continue;
+
+      let option = config[key];
+
+      // check for an unknown option
+      if (!option) this.log.error(`Unknown option: ${alias}.${key}`, ReferenceError);
+    }
+
+    // normalise options
+    normaliseOptions(opts);
+
+    // merge them into this current files options
+    merge(this.options, opts);
+  }
+
+  /**
+   * [Please add a description.]
+   */
+
+  findConfigs(loc) {
+    if (!loc) return;
+
+    if (!isAbsolute(loc)) {
+      loc = path.join(process.cwd(), loc);
+    }
+
+    while (loc !== (loc = path.dirname(loc))) {
+      if (this.options.breakConfig) return;
+
+      var configLoc = path.join(loc, CONFIG_FILENAME);
+      if (exists(configLoc)) this.addConfig(configLoc);
+    }
+  }
+
+  /**
+   * [Please add a description.]
+   */
+
+  normaliseOptions() {
+    var opts = this.options;
+
+    for (let key in config) {
+      var option = config[key];
+      var val    = opts[key];
+
+      // optional
+      if (!val && option.optional) continue;
+
+      // deprecated
+      if (this.log && val && option.deprecated) {
+        this.log.deprecate(`Deprecated option ${key}: ${option.deprecated}`);
+      }
+
+      // validate
+      if (this.pipeline && val) {
+        val = validateOption(key, val, this.pipeline);
+      }
+
+      // aaliases
+      if (option.alias) {
+        opts[option.alias] = opts[option.alias] || val;
+      } else {
+        opts[key] = val;
+      }
+    }
+  }
+
+  /**
+   * [Please add a description.]
+   */
+
+  init(opts) {
+    this.mergeOptions(opts, "direct");
+
+    // babelrc option
+    if (opts.babelrc) {
+      for (var loc of (opts.babelrc: Array)) this.addConfig(loc);
+    }
+
+    // resolve all .babelrc files
+    this.findConfigs(opts.filename);
+
+    // merge in env
+    var envKey = process.env.BABEL_ENV || process.env.NODE_ENV || "development";
+    if (this.options.env) {
+      this.mergeOptions(this.options.env[envKey], `direct.env.${envKey}`);
+    }
+
+    // normalise
+    this.normaliseOptions(opts);
+
+    return this.options;
+  }
+}

src/babel/transformation/file/options/parsers.js

@@ -1,9 +1,18 @@
+import slash from "slash";
 import * as util from "../../../util";
 
+/**
+ * Get a transformer list from a value.
+ */
+
 export function transformerList(val) {
   return util.arrayify(val);
 }
 
+/**
+ * Validate transformer list. Maps "all" to all transformer names.
+ */
+
 transformerList.validate = function (key, val, pipeline) {
   if (val.indexOf("all") >= 0 || val.indexOf(true) >= 0) {
     val = Object.keys(pipeline.transformers);
@@ -12,18 +21,40 @@ transformerList.validate = function (key, val, pipeline) {
   return pipeline._ensureTransformerNames(key, val);
 };
 
+/**
+ * Cast a value to a number.
+ */
+
 export function number(val) {
   return +val;
 }
 
+/**
+ * Cast a value to a boolean.
+ */
+
+export var filename = slash;
+
+/**
+ * [Please add a description.]
+ */
+
 export function boolean(val) {
   return !!val;
 }
 
+/**
+ * Cast a boolean-like string to a boolean.
+ */
+
 export function booleanString(val) {
   return util.booleanify(val);
 }
 
+/**
+ * Cast a value to an array, splitting strings by ",".
+ */
+
 export function list(val) {
   return util.list(val);
 }

src/babel/transformation/file/options/resolve-rc.js

@@ -1,61 +0,0 @@
-import stripJsonComments from "strip-json-comments";
-import { normaliseOptions } from "./index";
-import merge from "../../../helpers/merge";
-import path from "path";
-import fs from "fs";
-import pathExists from "path-exists";
-
-var cache = {};
-var jsons = {};
-
-function exists(filename) {
-  var cached = cache[filename];
-  if (cached != null) return cached;
-  return cache[filename] = pathExists.sync(filename);
-}
-
-export default function (loc, opts = {}) {
-  var rel = ".babelrc";
-
-  if (!opts.babelrc) {
-    opts.babelrc = [];
-  }
-
-  function find(start, rel) {
-    var file = path.join(start, rel);
-
-    if (opts.babelrc.indexOf(file) >= 0) {
-      return;
-    }
-
-    if (exists(file)) {
-      var content = fs.readFileSync(file, "utf8");
-      var json;
-
-      try {
-        json = jsons[content] = jsons[content] || JSON.parse(stripJsonComments(content));
-        normaliseOptions(json);
-      } catch (err) {
-        err.message = `${file}: ${err.message}`;
-        throw err;
-      }
-
-      opts.babelrc.push(file);
-
-      if (json.breakConfig) return;
-
-      merge(opts, json);
-    }
-
-    var up = path.dirname(start);
-    if (up !== start) { // root
-      find(up, rel);
-    }
-  }
-
-  if (opts.babelrc.indexOf(loc) < 0 && opts.breakConfig !== true) {
-    find(loc, rel);
-  }
-
-  return opts;
-}

src/babel/transformation/file/plugin-manager.js

@@ -2,9 +2,13 @@ import Transformer from "../transformer";
 import Plugin from "../plugin";
 import * as types from "../../types";
 import * as messages from "../../messages";
-import traverse from "../../types";
+import traverse from "../../traversal";
 import parse from "../../helpers/parse";
 
+/**
+ * [Please add a description.]
+ */
+
 var context = {
   messages,
   Transformer,
@@ -16,9 +20,22 @@ var context = {
 
 import * as util from  "../../util";
 
+/**
+ * [Please add a description.]
+ */
+
 export default class PluginManager {
+
+  /**
+   * [Please add a description.]
+   */
+
   static memoisedPlugins = [];
 
+  /**
+   * [Please add a description.]
+   */
+
   static memoisePluginContainer(fn) {
     for (var i = 0; i < PluginManager.memoisedPlugins.length; i++) {
       var plugin = PluginManager.memoisedPlugins[i];
@@ -33,8 +50,16 @@ export default class PluginManager {
     return transformer;
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   static positions = ["before", "after"];
 
+  /**
+   * [Please add a description.]
+   */
+
   constructor({ file, transformers, before, after } = { transformers: {}, before: [], after: [] }) {
     this.transformers = transformers;
     this.file         = file;
@@ -42,6 +67,10 @@ export default class PluginManager {
     this.after        = after;
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   subnormaliseString(name, position) {
     // this is a plugin in the form of "foobar" or "foobar:after"
     // where the optional colon is the delimiter for plugin position in the transformer stack
@@ -61,6 +90,10 @@ export default class PluginManager {
     }
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   validate(name, plugin) {
     // validate transformer key
     var key = plugin.key;
@@ -77,6 +110,10 @@ export default class PluginManager {
     plugin.metadata.plugin = true;
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   add(name) {
     var position;
     var plugin;

src/babel/transformation/helpers/README.md

@@ -0,0 +1,3 @@
+## Transformation Helpers
+
+This is the Transformation Helpers directory.

src/babel/transformation/helpers/build-binary-assignment-operator-transformer.js

@@ -1,17 +1,33 @@
 import explode from "./explode-assignable-expression";
 import * as t from "../../types";
 
+/**
+ * [Please add a description.]
+ */
+
 export default function (opts) {
   var exports = {};
 
+  /**
+   * [Please add a description.]
+   */
+
   var isAssignment = function (node) {
     return node.operator === opts.operator + "=";
   };
 
+  /**
+   * [Please add a description.]
+   */
+
   var buildAssignment = function (left, right) {
     return t.assignmentExpression("=", left, right);
   };
 
+  /**
+   * [Please add a description.]
+   */
+
   exports.ExpressionStatement = function (node, parent, scope, file) {
     // hit the `AssignmentExpression` one below
     if (this.isCompletionRecord()) return;
@@ -29,6 +45,10 @@ export default function (opts) {
     return nodes;
   };
 
+  /**
+   * [Please add a description.]
+   */
+
   exports.AssignmentExpression = function (node, parent, scope, file) {
     if (!isAssignment(node)) return;
 
@@ -38,6 +58,10 @@ export default function (opts) {
     return nodes;
   };
 
+  /**
+   * [Please add a description.]
+   */
+
   exports.BinaryExpression = function (node) {
     if (node.operator !== opts.operator) return;
     return opts.build(node.left, node.right);

src/babel/transformation/helpers/build-comprehension.js

@@ -1,5 +1,9 @@
 import * as t from "../../types";
 
+/**
+ * [Please add a description.]
+ */
+
 export default function build(node, buildBody) {
   var self = node.blocks.shift();
   if (!self) return;

src/babel/transformation/helpers/build-conditional-assignment-operator-transformer.js

@@ -1,11 +1,24 @@
 import explode from "./explode-assignable-expression";
 import * as t from "../../types";
 
+/**
+ * [Please add a description.]
+ */
+
 export default function (exports, opts) {
+
+  /**
+   * [Please add a description.]
+   */
+
   var buildAssignment = function (left, right) {
     return t.assignmentExpression("=", left, right);
   };
 
+  /**
+   * [Please add a description.]
+   */
+
   exports.ExpressionStatement = function (node, parent, scope, file) {
     // hit the `AssignmentExpression` one below
     if (this.isCompletionRecord()) return;
@@ -25,6 +38,10 @@ export default function (exports, opts) {
     return nodes;
   };
 
+  /**
+   * [Please add a description.]
+   */
+
   exports.AssignmentExpression = function (node, parent, scope, file) {
     if (!opts.is(node, file)) return;
 

src/babel/transformation/helpers/build-react-transformer.js

@@ -9,9 +9,17 @@ import esutils from "esutils";
 import * as react from "./react";
 import * as t from "../../types";
 
+/**
+ * [Please add a description.]
+ */
+
 export default function (opts) {
   var visitor = {};
 
+  /**
+   * [Please add a description.]
+   */
+
   visitor.JSXIdentifier = function (node) {
     if (node.name === "this" && this.isReferenced()) {
       return t.thisExpression();
@@ -22,10 +30,18 @@ export default function (opts) {
     }
   };
 
+  /**
+   * [Please add a description.]
+   */
+
   visitor.JSXNamespacedName = function () {
     throw this.errorWithNode(messages.get("JSXNamespacedTags"));
   };
 
+  /**
+   * [Please add a description.]
+   */
+
   visitor.JSXMemberExpression = {
     exit(node) {
       node.computed = t.isLiteral(node.property);
@@ -33,10 +49,18 @@ export default function (opts) {
     }
   };
 
+  /**
+   * [Please add a description.]
+   */
+
   visitor.JSXExpressionContainer = function (node) {
     return node.expression;
   };
 
+  /**
+   * [Please add a description.]
+   */
+
   visitor.JSXAttribute = {
     enter(node) {
       var value = node.value;
@@ -51,6 +75,10 @@ export default function (opts) {
     }
   };
 
+  /**
+   * [Please add a description.]
+   */
+
   visitor.JSXOpeningElement = {
     exit(node, parent, scope, file) {
       parent.children = react.buildChildren(parent);
@@ -141,6 +169,10 @@ export default function (opts) {
     return attribs;
   };
 
+  /**
+   * [Please add a description.]
+   */
+
   visitor.JSXElement = {
     exit(node) {
       var callExpr = node.openingElement;

src/babel/transformation/helpers/call-delegate.js

@@ -1,6 +1,15 @@
 import * as t from "../../types";
 
+/**
+ * [Please add a description.]
+ */
+
 var visitor = {
+
+  /**
+   * [Please add a description.]
+   */
+
   enter(node, parent, scope, state) {
     if (this.isThisExpression() || this.isReferencedIdentifier({ name: "arguments" })) {
       state.found = true;
@@ -8,11 +17,19 @@ var visitor = {
     }
   },
 
+  /**
+   * [Please add a description.]
+   */
+
   Function() {
     this.skip();
   }
 };
 
+/**
+ * [Please add a description.]
+ */
+
 export default function (node, scope) {
   var container = t.functionExpression(null, [], node.body, node.generator, node.async);
 

src/babel/transformation/helpers/define-map.js

@@ -2,6 +2,10 @@ import each from "lodash/collection/each";
 import has from "lodash/object/has";
 import * as t from "../../types";
 
+/**
+ * [Please add a description.]
+ */
+
 export function push(mutatorMap, node, kind, file) {
   var alias = t.toKeyAlias(node);
 
@@ -43,6 +47,10 @@ export function push(mutatorMap, node, kind, file) {
   return map;
 }
 
+/**
+ * [Please add a description.]
+ */
+
 export function hasComputed(mutatorMap) {
   for (var key in mutatorMap) {
     if (mutatorMap[key]._computed) {
@@ -52,6 +60,10 @@ export function hasComputed(mutatorMap) {
   return false;
 }
 
+/**
+ * [Please add a description.]
+ */
+
 export function toComputedObjectFromClass(obj) {
   var objExpr = t.arrayExpression([]);
 
@@ -65,6 +77,10 @@ export function toComputedObjectFromClass(obj) {
   return objExpr;
 }
 
+/**
+ * [Please add a description.]
+ */
+
 export function toClassObject(mutatorMap) {
   var objExpr = t.objectExpression([]);
 
@@ -92,6 +108,10 @@ export function toClassObject(mutatorMap) {
   return objExpr;
 }
 
+/**
+ * [Please add a description.]
+ */
+
 export function toDefineObject(mutatorMap) {
   each(mutatorMap, function (map) {
     if (map.value) map.writable = t.literal(true);

src/babel/transformation/helpers/explode-assignable-expression.js

@@ -1,5 +1,9 @@
 import * as t from "../../types";
 
+/**
+ * [Please add a description.]
+ */
+
 var getObjRef = function (node, nodes, file, scope) {
   var ref;
   if (t.isIdentifier(node)) {
@@ -33,6 +37,10 @@ var getObjRef = function (node, nodes, file, scope) {
   return temp;
 };
 
+/**
+ * [Please add a description.]
+ */
+
 var getPropRef = function (node, nodes, file, scope) {
   var prop = node.property;
   var key = t.toComputedKey(node, prop);
@@ -45,6 +53,10 @@ var getPropRef = function (node, nodes, file, scope) {
   return temp;
 };
 
+/**
+ * [Please add a description.]
+ */
+
 export default function (node, nodes, file, scope, allowedSingleIdent) {
   var obj;
   if (t.isIdentifier(node) && allowedSingleIdent) {

src/babel/transformation/helpers/get-function-arity.js

@@ -1,5 +1,9 @@
 import * as t from "../../types";
 
+/**
+ * [Please add a description.]
+ */
+
 export default function (node) {
   var lastNonDefault = 0;
   for (var i = 0; i < node.params.length; i++) {

src/babel/transformation/helpers/memoise-decorators.js

@@ -1,5 +1,9 @@
 import * as t from "../../types";
 
+/**
+ * [Please add a description.]
+ */
+
 export default function (decorators, scope) {
   for (var i = 0; i < decorators.length; i++) {
     var decorator = decorators[i];

src/babel/transformation/helpers/name-method.js

@@ -2,6 +2,10 @@ import getFunctionArity from "./get-function-arity";
 import * as util from  "../../util";
 import * as t from "../../types";
 
+/**
+ * [Please add a description.]
+ */
+
 function visitIdentifier(context, node, scope, state) {
   // check if this node matches our function id
   if (node.name !== state.name) return;
@@ -15,16 +19,33 @@ function visitIdentifier(context, node, scope, state) {
   context.stop();
 }
 
+/**
+ * [Please add a description.]
+ */
+
 var visitor = {
+
+  /**
+   * [Please add a description.]
+   */
+
   ReferencedIdentifier(node, parent, scope, state) {
     visitIdentifier(this, node, scope, state);
   },
 
+  /**
+   * [Please add a description.]
+   */
+
   BindingIdentifier(node, parent, scope, state) {
     visitIdentifier(this, node, scope, state);
   }
 };
 
+/**
+ * [Please add a description.]
+ */
+
 var wrap = function (state, method, id, scope) {
   if (state.selfReference) {
     if (scope.hasBinding(id.name) && !scope.hasGlobal(id.name)) {
@@ -56,6 +77,10 @@ var wrap = function (state, method, id, scope) {
   scope.getProgramParent().references[id.name] = true;
 };
 
+/**
+ * [Please add a description.]
+ */
+
 var visit = function (node, name, scope) {
   var state = {
     selfAssignment: false,
@@ -102,11 +127,19 @@ var visit = function (node, name, scope) {
   return state;
 };
 
+/**
+ * [Please add a description.]
+ */
+
 export function custom(node, id, scope) {
   var state = visit(node, id.name, scope);
   return wrap(state, node, id, scope);
 }
 
+/**
+ * [Please add a description.]
+ */
+
 export function property(node, file, scope) {
   var key = t.toComputedKey(node, node.key);
   if (!t.isLiteral(key)) return; // we can't set a function id with this
@@ -119,6 +152,10 @@ export function property(node, file, scope) {
   node.value = wrap(state, method, id, scope) || method;
 }
 
+/**
+ * [Please add a description.]
+ */
+
 export function bare(node, parent, scope) {
   // has an `id` so we don't need to infer one
   if (node.id) return;

src/babel/transformation/helpers/react.js

@@ -2,10 +2,18 @@ import * as t from "../../types";
 
 export var isReactComponent = t.buildMatchMemberExpression("React.Component");
 
+/**
+ * [Please add a description.]
+ */
+
 export function isCompatTag(tagName) {
   return tagName && /^[a-z]|\-/.test(tagName);
 }
 
+/**
+ * [Please add a description.]
+ */
+
 function cleanJSXElementLiteralChild(child, args) {
   var lines = child.value.split(/\r\n|\n|\r/);
 
@@ -51,6 +59,10 @@ function cleanJSXElementLiteralChild(child, args) {
   if (str) args.push(t.literal(str));
 }
 
+/**
+ * [Please add a description.]
+ */
+
 export function buildChildren(node) {
   var elems = [];
 

src/babel/transformation/helpers/regex.js

@@ -1,10 +1,18 @@
 import pull from "lodash/array/pull";
 import * as t from "../../types";
 
+/**
+ * [Please add a description.]
+ */
+
 export function is(node, flag) {
   return t.isLiteral(node) && node.regex && node.regex.flags.indexOf(flag) >= 0;
 }
 
+/**
+ * [Please add a description.]
+ */
+
 export function pullFlag(node, flag) {
   var flags = node.regex.flags.split("");
   if (node.regex.flags.indexOf(flag) < 0) return;

src/babel/transformation/helpers/remap-async-to-generator.js

@@ -1,10 +1,23 @@
 import * as t from "../../types";
 
+/**
+ * [Please add a description.]
+ */
+
 var awaitVisitor = {
+
+  /**
+   * [Please add a description.]
+   */
+
   Function() {
     this.skip();
   },
 
+  /**
+   * [Please add a description.]
+   */
+
   AwaitExpression(node) {
     node.type = "YieldExpression";
 
@@ -16,7 +29,16 @@ var awaitVisitor = {
   }
 };
 
+/**
+ * [Please add a description.]
+ */
+
 var referenceVisitor = {
+
+  /**
+   * [Please add a description.]
+   */
+
   ReferencedIdentifier(node, parent, scope, state) {
     var name = state.id.name;
     if (node.name === name && scope.bindingIdentifierEquals(name, state.id)) {
@@ -25,6 +47,10 @@ var referenceVisitor = {
   }
 };
 
+/**
+ * [Please add a description.]
+ */
+
 export default function (path, callId) {
   var node = path.node;
 

src/babel/transformation/helpers/replace-supers.js

@@ -2,6 +2,10 @@ import type NodePath from "../../traversal/path";
 import * as messages from "../../messages";
 import * as t from "../../types";
 
+/**
+ * [Please add a description.]
+ */
+
 function isIllegalBareSuper(node, parent) {
   if (!t.isSuper(node)) return false;
   if (t.isMemberExpression(parent, { computed: false })) return false;
@@ -9,11 +13,24 @@ function isIllegalBareSuper(node, parent) {
   return true;
 }
 
+/**
+ * [Please add a description.]
+ */
+
 function isMemberExpressionSuper(node) {
   return t.isMemberExpression(node) && t.isSuper(node.object);
 }
 
+/**
+ * [Please add a description.]
+ */
+
 var visitor = {
+
+  /**
+   * [Please add a description.]
+   */
+
   enter(node, parent, scope, state) {
     var topLevel = state.topLevel;
     var self = state.self;
@@ -44,12 +61,11 @@ var visitor = {
   }
 };
 
+/**
+ * [Please add a description.]
+ */
+
 export default class ReplaceSupers {
-
-  /**
-   * Description
-   */
-
   constructor(opts: Object, inClass?: boolean = false) {
     this.topLevelThisReference = opts.topLevelThisReference;
     this.methodPath            = opts.methodPath;
@@ -64,6 +80,10 @@ export default class ReplaceSupers {
     this.opts                  = opts;
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   getObjectRef() {
     return this.opts.objectRef || this.opts.getObjectRef();
   }
@@ -120,7 +140,7 @@ export default class ReplaceSupers {
   }
 
   /**
-   * Description
+   * [Please add a description.]
    */
 
   replace() {
@@ -128,7 +148,7 @@ export default class ReplaceSupers {
   }
 
   /**
-   * Description
+   * [Please add a description.]
    */
 
   traverseLevel(path: NodePath, topLevel: boolean) {
@@ -137,7 +157,7 @@ export default class ReplaceSupers {
   }
 
   /**
-   * Description
+   * [Please add a description.]
    */
 
   getThisReference() {
@@ -153,7 +173,7 @@ export default class ReplaceSupers {
   }
 
   /**
-   * Description
+   * [Please add a description.]
    */
 
   getLooseSuperProperty(id: Object, parent: Object) {
@@ -196,7 +216,7 @@ export default class ReplaceSupers {
   }
 
   /**
-   * Description
+   * [Please add a description.]
    */
 
   looseHandle(path: NodePath, getThisReference: Function) {
@@ -216,7 +236,7 @@ export default class ReplaceSupers {
   }
 
   /**
-   * Description
+   * [Please add a description.]
    */
 
   specHandleAssignmentExpression(ref, path, node, getThisReference) {
@@ -238,7 +258,7 @@ export default class ReplaceSupers {
   }
 
   /**
-   * Description
+   * [Please add a description.]
    */
 
   specHandle(path: NodePath, getThisReference: Function) {

src/babel/transformation/index.js

@@ -1,8 +1,14 @@
 import Pipeline from "./pipeline";
 
+/**
+ * [Please add a description.]
+ */
+
 var pipeline = new Pipeline;
 
-//
+/**
+ * [Please add a description.]
+ */
 
 import transformers from "./transformers";
 
@@ -17,17 +23,23 @@ for (var key in transformers) {
 
 pipeline.addTransformers(transformers);
 
-//
+/**
+ * [Please add a description.]
+ */
 
 import deprecated from "./transformers/deprecated";
 pipeline.addDeprecated(deprecated);
 
-//
+/**
+ * [Please add a description.]
+ */
 
 import aliases from "./transformers/aliases";
 pipeline.addAliases(aliases);
 
-//
+/**
+ * [Please add a description.]
+ */
 
 import * as filters from "./transformers/filters";
 pipeline.addFilter(filters.internal);
@@ -36,7 +48,9 @@ pipeline.addFilter(filters.whitelist);
 pipeline.addFilter(filters.stage);
 pipeline.addFilter(filters.optional);
 
-//
+/**
+ * [Please add a description.]
+ */
 
 var transform = pipeline.transform.bind(pipeline);
 transform.fromAst = pipeline.transformFromAst.bind(pipeline);

src/babel/transformation/modules/README.md

@@ -0,0 +1,3 @@
+## Module Transformation
+
+This is the Module Transformation directory.

src/babel/transformation/modules/_default.js

@@ -5,7 +5,16 @@ import object from "../../helpers/object";
 import * as util from  "../../util";
 import * as t from "../../types";
 
+/**
+ * [Please add a description.]
+ */
+
 var metadataVisitor = {
+
+  /**
+   * [Please add a description.]
+   */
+
   ModuleDeclaration: {
     enter(node, parent, scope, formatter) {
       if (node.source) {
@@ -15,6 +24,10 @@ var metadataVisitor = {
     }
   },
 
+  /**
+   * [Please add a description.]
+   */
+
   ImportDeclaration: {
     exit(node, parent, scope, formatter) {
       formatter.hasLocalImports = true;
@@ -63,6 +76,10 @@ var metadataVisitor = {
     }
   },
 
+  /**
+   * [Please add a description.]
+   */
+
   ExportDeclaration(node, parent, scope, formatter) {
     formatter.hasLocalExports = true;
 
@@ -156,6 +173,10 @@ var metadataVisitor = {
     }
   },
 
+  /**
+   * [Please add a description.]
+   */
+
   Scope(node, parent, scope, formatter) {
     if (!formatter.isLoose()) {
       this.skip();
@@ -163,6 +184,10 @@ var metadataVisitor = {
   }
 };
 
+/**
+ * [Please add a description.]
+ */
+
 export default class DefaultFormatter {
   constructor(file) {
     // object containg all module sources with the scope that they're contained in
@@ -190,6 +215,10 @@ export default class DefaultFormatter {
     this.getMetadata();
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   addScope(path) {
     var source = path.node.source && path.node.source.value;
     if (!source) return;
@@ -202,19 +231,35 @@ export default class DefaultFormatter {
     this.sourceScopes[source] = path.scope;
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   isModuleType(node, type) {
     var modules = this.file.dynamicImportTypes[type];
     return modules && modules.indexOf(node) >= 0;
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   transform() {
     this.remapAssignments();
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   doDefaultExportInterop(node) {
     return (t.isExportDefaultDeclaration(node) || t.isSpecifierDefault(node)) && !this.noInteropRequireExport && !this.hasNonDefaultExports;
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   getMetadata() {
     var has = false;
     for (var node of (this.file.ast.program.body: Array)) {
@@ -228,12 +273,20 @@ export default class DefaultFormatter {
     }
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   remapAssignments() {
     if (this.hasLocalExports || this.hasLocalImports) {
       this.remaps.run();
     }
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   remapExportAssignment(node, exported) {
     var assign = node;
 
@@ -248,6 +301,10 @@ export default class DefaultFormatter {
     return assign;
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   _addExport(name, exported) {
     var info = this.localExports[name] = this.localExports[name] || {
       binding: this.scope.getBindingIdentifier(name),
@@ -256,6 +313,10 @@ export default class DefaultFormatter {
     info.exported.push(exported);
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   getExport(node, scope) {
     if (!t.isIdentifier(node)) return;
 
@@ -265,6 +326,10 @@ export default class DefaultFormatter {
     }
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   getModuleName() {
     var opts = this.file.opts;
     // moduleId is n/a if a `getModuleId()` is provided
@@ -307,6 +372,10 @@ export default class DefaultFormatter {
     }
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   _pushStatement(ref, nodes) {
     if (t.isClass(ref) || t.isFunction(ref)) {
       if (ref.id) {
@@ -318,6 +387,10 @@ export default class DefaultFormatter {
     return ref;
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   _hoistExport(declar, assign, priority) {
     if (t.isFunctionDeclaration(declar)) {
       assign._blockHoist = priority || 2;
@@ -326,6 +399,10 @@ export default class DefaultFormatter {
     return assign;
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   getExternalReference(node, nodes) {
     var ids = this.ids;
     var id = node.source.value;
@@ -337,21 +414,37 @@ export default class DefaultFormatter {
     }
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   checkExportIdentifier(node) {
     if (t.isIdentifier(node, { name: "__esModule" })) {
       throw this.file.errorWithNode(node, messages.get("modulesIllegalExportName", node.name));
     }
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   exportAllDeclaration(node, nodes) {
     var ref = this.getExternalReference(node, nodes);
     nodes.push(this.buildExportsWildcard(ref, node));
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   isLoose() {
     return this.file.isLoose("es6.modules");
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   exportSpecifier(specifier, node, nodes) {
     if (node.source) {
       var ref = this.getExternalReference(node, nodes);
@@ -376,6 +469,10 @@ export default class DefaultFormatter {
     }
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   buildExportsWildcard(objectIdentifier) {
     return t.expressionStatement(t.callExpression(this.file.addHelper("defaults"), [
       t.identifier("exports"),
@@ -383,6 +480,10 @@ export default class DefaultFormatter {
     ]));
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   buildExportsFromAssignment(id, init) {
     this.checkExportIdentifier(id);
     return util.template("exports-from-assign", {
@@ -391,6 +492,10 @@ export default class DefaultFormatter {
     }, true);
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   buildExportsAssignment(id, init) {
     this.checkExportIdentifier(id);
     return util.template("exports-assign", {
@@ -399,6 +504,10 @@ export default class DefaultFormatter {
     }, true);
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   exportDeclaration(node, nodes) {
     var declar = node.declaration;
 

src/babel/transformation/modules/_strict.js

@@ -1,5 +1,9 @@
 import * as util from "../../util";
 
+/**
+ * [Please add a description.]
+ */
+
 export default function (Parent) {
   var Constructor = function () {
     this.noInteropRequireImport = true;

src/babel/transformation/modules/amd-strict.js

@@ -1,3 +1,8 @@
 import AMDFormatter from "./amd";
 import buildStrict from "./_strict";
+
+/**
+ * [Please add a description.]
+ */
+
 export default buildStrict(AMDFormatter);

src/babel/transformation/modules/amd.js

@@ -5,11 +5,24 @@ import values from "lodash/object/values";
 import * as util from  "../../util";
 import * as t from "../../types";
 
+/**
+ * [Please add a description.]
+ */
+
 export default class AMDFormatter extends DefaultFormatter {
+
+  /**
+   * [Please add a description.]
+   */
+
   setup() {
     CommonFormatter.prototype._setup.call(this, this.hasNonDefaultExports);
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   buildDependencyLiterals() {
     var names = [];
     for (var name in this.ids) {
@@ -64,14 +77,26 @@ export default class AMDFormatter extends DefaultFormatter {
     }
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   _getExternalReference(node) {
     return this.scope.generateUidIdentifier(node.source.value);
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   importDeclaration(node) {
     this.getExternalReference(node);
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   importSpecifier(specifier, node, nodes, scope) {
     var key = node.source.value;
     var ref = this.getExternalReference(node);
@@ -105,6 +130,10 @@ export default class AMDFormatter extends DefaultFormatter {
     this.remaps.add(scope, specifier.local.name, ref);
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   exportSpecifier(specifier, node, nodes) {
     if (this.doDefaultExportInterop(specifier)) {
       this.passModuleArg = true;
@@ -120,6 +149,10 @@ export default class AMDFormatter extends DefaultFormatter {
     CommonFormatter.prototype.exportSpecifier.apply(this, arguments);
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   exportDeclaration(node, nodes) {
     if (this.doDefaultExportInterop(node)) {
       this.passModuleArg = true;

src/babel/transformation/modules/common-strict.js

@@ -1,3 +1,8 @@
 import CommonFormatter from "./common";
 import buildStrict from "./_strict";
+
+/**
+ * [Please add a description.]
+ */
+
 export default buildStrict(CommonFormatter);

src/babel/transformation/modules/common.js

@@ -2,11 +2,24 @@ import DefaultFormatter from "./_default";
 import * as util from  "../../util";
 import * as t from "../../types";
 
+/**
+ * [Please add a description.]
+ */
+
 export default class CommonJSFormatter extends DefaultFormatter {
+
+  /**
+   * [Please add a description.]
+   */
+
   setup() {
     this._setup(this.hasLocalExports);
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   _setup(conditional) {
     var file  = this.file;
     var scope = file.scope;
@@ -23,6 +36,10 @@ export default class CommonJSFormatter extends DefaultFormatter {
     }
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   transform(program) {
     DefaultFormatter.prototype.transform.apply(this, arguments);
 
@@ -37,6 +54,10 @@ export default class CommonJSFormatter extends DefaultFormatter {
     }
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   importSpecifier(specifier, node, nodes, scope) {
     var variableName = specifier.local;
 
@@ -76,6 +97,10 @@ export default class CommonJSFormatter extends DefaultFormatter {
     }
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   importDeclaration(node, nodes) {
     // import "foo";
     nodes.push(util.template("require", {
@@ -83,6 +108,10 @@ export default class CommonJSFormatter extends DefaultFormatter {
     }, true));
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   exportSpecifier(specifier) {
     if (this.doDefaultExportInterop(specifier)) {
       this.hasDefaultOnlyExport = true;
@@ -91,6 +120,10 @@ export default class CommonJSFormatter extends DefaultFormatter {
     DefaultFormatter.prototype.exportSpecifier.apply(this, arguments);
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   exportDeclaration(node) {
     if (this.doDefaultExportInterop(node)) {
       this.hasDefaultOnlyExport = true;
@@ -99,6 +132,10 @@ export default class CommonJSFormatter extends DefaultFormatter {
     DefaultFormatter.prototype.exportDeclaration.apply(this, arguments);
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   _getExternalReference(node, nodes) {
     var call = t.callExpression(t.identifier("require"), [node.source]);
     var uid;

src/babel/transformation/modules/ignore.js

@@ -1,12 +1,25 @@
 import DefaultFormatter from "./_default";
 import * as t from "../../types";
 
+/**
+ * [Please add a description.]
+ */
+
 export default class IgnoreFormatter extends DefaultFormatter {
+
+  /**
+   * [Please add a description.]
+   */
+
   exportDeclaration(node, nodes) {
     var declar = t.toStatement(node.declaration, true);
     if (declar) nodes.push(t.inherits(declar, node));
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   exportAllDeclaration() {}
   importDeclaration() {}
   importSpecifier() {}

src/babel/transformation/modules/index.js

@@ -1,3 +1,7 @@
+/**
+ * [Please add a description.]
+ */
+
 export default {
   commonStrict: require("./common-strict"),
   amdStrict:    require("./amd-strict"),

src/babel/transformation/modules/lib/remaps.js

@@ -1,12 +1,25 @@
 import * as t from "../../../types";
 
+/**
+ * [Please add a description.]
+ */
+
 var remapVisitor = {
+
+  /**
+   * [Please add a description.]
+   */
+
   enter(node) {
     if (node._skipModulesRemap) {
       return this.skip();
     }
   },
 
+  /**
+   * [Please add a description.]
+   */
+
   ReferencedIdentifier(node, parent, scope, remaps) {
     var { formatter } = remaps;
 
@@ -23,6 +36,10 @@ var remapVisitor = {
     }
   },
 
+  /**
+   * [Please add a description.]
+   */
+
   AssignmentExpression: {
     exit(node, parent, scope, { formatter }) {
       if (!node._ignoreModulesRemap) {
@@ -34,6 +51,10 @@ var remapVisitor = {
     }
   },
 
+  /**
+   * [Please add a description.]
+   */
+
   UpdateExpression(node, parent, scope, { formatter }) {
     var exported = formatter.getExport(node.argument, scope);
     if (!exported) return;
@@ -65,24 +86,45 @@ var remapVisitor = {
     return t.sequenceExpression(nodes);
   }
 };
+
+/**
+ * [Please add a description.]
+ */
+
 export default class Remaps {
   constructor(file, formatter) {
     this.formatter = formatter;
     this.file      = file;
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   run() {
     this.file.path.traverse(remapVisitor, this);
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   _getKey(name) {
     return `${name}:moduleRemap`;
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   get(scope, name) {
     return scope.getData(this._getKey(name));
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   add(scope, name, val) {
     if (this.all) {
       this.all.push({
@@ -95,6 +137,10 @@ export default class Remaps {
     return scope.setData(this._getKey(name), val);
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   remove(scope, name) {
     return scope.removeData(this._getKey(name));
   }
@@ -109,6 +155,10 @@ export default class Remaps {
     return this.all;
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   clearAll() {
     if (this.all) {
       for (var remap of (this.all: Array)) {

src/babel/transformation/modules/system.js

@@ -5,12 +5,25 @@ import last from "lodash/array/last";
 import map from "lodash/collection/map";
 import * as t from "../../types";
 
+/**
+ * [Please add a description.]
+ */
+
 var hoistVariablesVisitor = {
+
+  /**
+   * [Please add a description.]
+   */
+
   Function() {
     // nothing inside is accessible
     this.skip();
   },
 
+  /**
+   * [Please add a description.]
+   */
+
   VariableDeclaration(node, parent, scope, state) {
     if (node.kind !== "var" && !t.isProgram(parent)) { // let, const
       // can't be accessed
@@ -33,8 +46,7 @@ var hoistVariablesVisitor = {
     }
 
     // for (var i in test)
-    // for (var i = 0;;)
-    if (t.isFor(parent) && (parent.left === node || parent.init === node)) {
+    if (t.isFor(parent) && parent.left === node) {
       return node.declarations[0].id;
     }
 
@@ -42,11 +54,24 @@ var hoistVariablesVisitor = {
   }
 };
 
+/**
+ * [Please add a description.]
+ */
+
 var hoistFunctionsVisitor = {
+
+  /**
+   * [Please add a description.]
+   */
+
   Function() {
     this.skip();
   },
 
+  /**
+   * [Please add a description.]
+   */
+
   enter(node, parent, scope, state) {
     if (t.isFunctionDeclaration(node) || state.formatter._canHoist(node)) {
       state.handlerBody.push(node);
@@ -55,7 +80,16 @@ var hoistFunctionsVisitor = {
   }
 };
 
+/**
+ * [Please add a description.]
+ */
+
 var runnerSettersVisitor = {
+
+  /**
+   * [Please add a description.]
+   */
+
   enter(node, parent, scope, state) {
     if (node._importSource === state.source) {
       if (t.isVariableDeclaration(node)) {
@@ -74,10 +108,15 @@ var runnerSettersVisitor = {
   }
 };
 
+/**
+ * [Please add a description.]
+ */
+
 export default class SystemFormatter extends AMDFormatter {
   constructor(file) {
     super(file);
 
+    this._setters = null;
     this.exportIdentifier = file.scope.generateUidIdentifier("export");
     this.noInteropRequireExport = true;
     this.noInteropRequireImport = true;
@@ -85,11 +124,19 @@ export default class SystemFormatter extends AMDFormatter {
     this.remaps.clearAll();
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   _addImportSource(node, exportNode) {
     if (node) node._importSource = exportNode.source && exportNode.source.value;
     return node;
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   buildExportsWildcard(objectIdentifier, node) {
     var leftIdentifier = this.scope.generateUidIdentifier("key");
     var valIdentifier  = t.memberExpression(objectIdentifier, leftIdentifier, true);
@@ -107,15 +154,27 @@ export default class SystemFormatter extends AMDFormatter {
     return this._addImportSource(t.forInStatement(left, right, block), node);
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   buildExportsAssignment(id, init, node) {
     var call = this._buildExportCall(t.literal(id.name), init, true);
     return this._addImportSource(call, node);
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   buildExportsFromAssignment() {
     return this.buildExportsAssignment(...arguments);
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   remapExportAssignment(node, exported) {
     var assign = node;
 
@@ -126,6 +185,10 @@ export default class SystemFormatter extends AMDFormatter {
     return assign;
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   _buildExportCall(id, init, isStatement) {
     var call = t.callExpression(this.exportIdentifier, [id, init]);
     if (isStatement) {
@@ -135,6 +198,10 @@ export default class SystemFormatter extends AMDFormatter {
     }
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   importSpecifier(specifier, node, nodes) {
     AMDFormatter.prototype.importSpecifier.apply(this, arguments);
 
@@ -149,6 +216,10 @@ export default class SystemFormatter extends AMDFormatter {
     this._addImportSource(last(nodes), node);
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   _buildRunnerSetters(block, hoistDeclarators) {
     var scope = this.file.scope;
 
@@ -165,10 +236,18 @@ export default class SystemFormatter extends AMDFormatter {
     }));
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   _canHoist(node) {
     return node._blockHoist && !this.file.dynamicImports.length;
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   transform(program) {
     DefaultFormatter.prototype.transform.apply(this, arguments);
 
@@ -178,11 +257,14 @@ export default class SystemFormatter extends AMDFormatter {
 
     var block = t.blockStatement(program.body);
 
+    var setterListNode = this._buildRunnerSetters(block, hoistDeclarators);
+    this._setters = setterListNode;
+
     var runner = util.template("system", {
       MODULE_DEPENDENCIES: t.arrayExpression(this.buildDependencyLiterals()),
       EXPORT_IDENTIFIER:   this.exportIdentifier,
       MODULE_NAME:         moduleNameLiteral,
-      SETTERS:             this._buildRunnerSetters(block, hoistDeclarators),
+      SETTERS:             setterListNode,
       EXECUTE:             t.functionExpression(null, [], block)
     }, true);
 

src/babel/transformation/modules/umd-strict.js

@@ -1,3 +1,8 @@
 import UMDFormatter from "./umd";
 import buildStrict from "./_strict";
+
+/**
+ * [Please add a description.]
+ */
+
 export default buildStrict(UMDFormatter);

src/babel/transformation/modules/umd.js

@@ -5,7 +5,16 @@ import path from "path";
 import * as util from  "../../util";
 import * as t from "../../types";
 
+/**
+ * [Please add a description.]
+ */
+
 export default class UMDFormatter extends AMDFormatter {
+
+  /**
+   * [Please add a description.]
+   */
+
   transform(program) {
     DefaultFormatter.prototype.transform.apply(this, arguments);
 

src/babel/transformation/pipeline.js

@@ -5,6 +5,10 @@ import assign from "lodash/object/assign";
 import object from "../helpers/object";
 import File from "./file";
 
+/**
+ * [Please add a description.]
+ */
+
 export default class Pipeline {
   constructor() {
     this.transformers = object();
@@ -14,6 +18,10 @@ export default class Pipeline {
     this.filters      = [];
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   addTransformers(transformers) {
     for (var key in transformers) {
       this.addTransformer(key, transformers[key]);
@@ -21,6 +29,10 @@ export default class Pipeline {
     return this;
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   addTransformer(key, plugin) {
     if (this.transformers[key]) throw new Error(); // todo: error
 
@@ -44,21 +56,37 @@ export default class Pipeline {
     this.transformers[key] = plugin;
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   addAliases(names) {
     assign(this.aliases, names);
     return this;
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   addDeprecated(names) {
     assign(this.deprecated, names);
     return this;
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   addFilter(filter: Function) {
     this.filters.push(filter);
     return this;
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   canTransform(plugin, fileOpts) {
     if (plugin.metadata.plugin) {
       return true;
@@ -72,11 +100,19 @@ export default class Pipeline {
     return true;
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   analyze(code: string, opts?: Object = {}) {
     opts.code = false;
     return this.transform(code, opts);
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   pretransform(code: string, opts?: Object) {
     var file = new File(opts, this);
     return file.wrap(code, function () {
@@ -86,6 +122,10 @@ export default class Pipeline {
     });
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   transform(code: string, opts?: Object) {
     var file = new File(opts, this);
     return file.wrap(code, function () {
@@ -95,6 +135,10 @@ export default class Pipeline {
     });
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   transformFromAst(ast, code, opts) {
     ast = normalizeAst(ast);
 
@@ -106,6 +150,10 @@ export default class Pipeline {
     });
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   _ensureTransformerNames(type: string, rawKeys: Array<string>) {
     var keys = [];
 

src/babel/transformation/plugin-pass.js

@@ -20,11 +20,19 @@ export default class PluginPass {
     }
   }
 
+  /**
+ * [Please add a description.]
+ */
+
   canTransform(): boolean {
     return this.file.transformerDependencies[this.key] ||
            this.file.pipeline.canTransform(this.plugin, this.file.opts);
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   transform() {
     var file = this.file;
     file.log.debug(`Start transformer ${this.key}`);

src/babel/transformation/plugin.js

@@ -1,13 +1,34 @@
 import PluginPass from "./plugin-pass";
 import * as messages from "../messages";
-import isFunction from "lodash/lang/isFunction";
 import traverse from "../traversal";
 import assign from "lodash/object/assign";
 import clone from "lodash/lang/clone";
 import File from "./file";
+import * as t from "../types";
+
+const VALID_PLUGIN_PROPERTIES = [
+  "visitor", "metadata",
+  "manipulateOptions",
+  "post", "pre"
+];
+
+const VALID_METADATA_PROPERTES = [
+  "dependencies",
+  "optional",
+  "stage",
+  "group",
+  "experimental",
+  "secondPass"
+];
+
+/**
+ * [Please add a description.]
+ */
 
 export default class Plugin {
   constructor(key: string, plugin: Object) {
+    Plugin.validate(key, plugin);
+
     plugin = assign({}, plugin);
 
     var take = function (key) {
@@ -34,16 +55,40 @@ export default class Plugin {
     this.key     = key;
   }
 
-  normalize(visitor: Object): Object {
-    if (isFunction(visitor)) {
-      visitor = { ast: visitor };
+  /**
+   * [Please add a description.]
+   */
+
+  static validate(name, plugin) {
+    for (let key in plugin) {
+      if (key[0] === "_") continue;
+      if (VALID_PLUGIN_PROPERTIES.indexOf(key) >= 0) continue;
+
+      var msgType = "pluginInvalidProperty";
+      if (t.TYPES.indexOf(key) >= 0) msgType = "pluginInvalidPropertyVisitor";
+      throw new Error(messages.get(msgType, name, key));
     }
 
-    traverse.explode(visitor);
+    for (let key in plugin.metadata) {
+      if (VALID_METADATA_PROPERTES.indexOf(key) >= 0) continue;
 
+      throw new Error(messages.get("pluginInvalidProperty", name, `metadata.${key}`));
+    }
+  }
+
+  /**
+   * [Please add a description.]
+   */
+
+  normalize(visitor: Object): Object {
+    traverse.explode(visitor);
     return visitor;
   }
 
+  /**
+   * [Please add a description.]
+   */
+
   buildPass(file: File): PluginPass {
     // validate Transformer instance
     if (!(file instanceof File)) {

src/babel/transformation/templates/default-parameter.js

@@ -1 +1 @@
-let VARIABLE_NAME = ARGUMENTS[ARGUMENT_KEY] === undefined ? DEFAULT_VALUE : ARGUMENTS[ARGUMENT_KEY];
+let VARIABLE_NAME = ARGUMENTS.length <= ARGUMENT_KEY || ARGUMENTS[ARGUMENT_KEY] === undefined ? DEFAULT_VALUE : ARGUMENTS[ARGUMENT_KEY];