diff --git a/src/README.md b/src/README.md new file mode 100644 index 0000000000..0003bf4223 --- /dev/null +++ b/src/README.md @@ -0,0 +1,27 @@ +## Welcome to the Babel Codebase + +Babel is broken down into three parts: + +- Parsing +- Transformation +- Generation + +**Parsing** is the process of turning a piece of code into an 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. However, because Babel is implementing +future standards it maintains a fork of 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. diff --git a/src/babel/README.md b/src/babel/README.md new file mode 100644 index 0000000000..6831fbaa9b --- /dev/null +++ b/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. diff --git a/src/babel/api/README.md b/src/babel/api/README.md new file mode 100644 index 0000000000..f1816a11f0 --- /dev/null +++ b/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 ` + */ + 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) { diff --git a/src/babel/api/node.js b/src/babel/api/node.js index 77bfc1e24b..0229e228b5 100644 --- a/src/babel/api/node.js +++ b/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"; diff --git a/src/babel/api/register/cache.js b/src/babel/api/register/cache.js index 42434fd38c..73ab94b175 100644 --- a/src/babel/api/register/cache.js +++ b/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; } diff --git a/src/babel/api/register/node.js b/src/babel/api/register/node.js index 00310feded..9e0f332c8c 100644 --- a/src/babel/api/register/node.js +++ b/src/babel/api/register/node.js @@ -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,14 +48,26 @@ 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; @@ -84,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; @@ -92,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) { @@ -113,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"]; @@ -137,6 +177,10 @@ var registerExtension = function (ext) { }; }; +/** + * Register loader for given extensions. + */ + var hookExtensions = function (_exts) { each(oldHandlers, function (old, ext) { if (old === undefined) { @@ -154,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); diff --git a/src/babel/generation/README.md b/src/babel/generation/README.md new file mode 100644 index 0000000000..65b83452a5 --- /dev/null +++ b/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 diff --git a/src/babel/generation/buffer.js b/src/babel/generation/buffer.js index 5d6bb190ec..053fe8238e 100644 --- a/src/babel/generation/buffer.js +++ b/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; diff --git a/src/babel/generation/generators/README.md b/src/babel/generation/generators/README.md new file mode 100644 index 0000000000..787ebf90bf --- /dev/null +++ b/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 diff --git a/src/babel/generation/generators/base.js b/src/babel/generation/generators/base.js index 7f12f04f71..faeaf14e1b 100644 --- a/src/babel/generation/generators/base.js +++ b/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() { } diff --git a/src/babel/generation/generators/classes.js b/src/babel/generation/generators/classes.js index cc29b0115e..d66dd3b2a9 100644 --- a/src/babel/generation/generators/classes.js +++ b/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: "" }); diff --git a/src/babel/generation/generators/comprehensions.js b/src/babel/generation/generators/comprehensions.js index 29b7029cb1..1f3ddd8cd2 100644 --- a/src/babel/generation/generators/comprehensions.js +++ b/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 ? "(" : "["); diff --git a/src/babel/generation/generators/expressions.js b/src/babel/generation/generators/expressions.js index d18b57353f..3a1ba3c618 100644 --- a/src/babel/generation/generators/expressions.js +++ b/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("."); diff --git a/src/babel/generation/generators/flow.js b/src/babel/generation/generators/flow.js index 3685c076bc..5c061ce9a6 100644 --- a/src/babel/generation/generators/flow.js +++ b/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"); } diff --git a/src/babel/generation/generators/jsx.js b/src/babel/generation/generators/jsx.js index 8c9508dcd8..e3f695a99d 100644 --- a/src/babel/generation/generators/jsx.js +++ b/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(""); } +/** + * Prints JSXEmptyExpression. + */ + export function JSXEmptyExpression() {} diff --git a/src/babel/generation/generators/methods.js b/src/babel/generation/generators/methods.js index fc80d5659e..9b40fc5f21 100644 --- a/src/babel/generation/generators/methods.js +++ b/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 "); diff --git a/src/babel/generation/generators/modules.js b/src/babel/generation/generators/modules.js index 998eaa0c8d..bbbb814011 100644 --- a/src/babel/generation/generators/modules.js +++ b/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,6 +123,10 @@ function ExportDeclaration(node, print) { this.ensureSemicolon(); } +/** + * Prints ImportDeclaration, prints specifiers and source, handles isType. + */ + export function ImportDeclaration(node, print) { this.push("import "); @@ -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); diff --git a/src/babel/generation/generators/statements.js b/src/babel/generation/generators/statements.js index 5d8f46eb51..a03ab1b15d 100644 --- a/src/babel/generation/generators/statements.js +++ b/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); diff --git a/src/babel/generation/generators/template-literals.js b/src/babel/generation/generators/template-literals.js index 1bd78796dd..50174a581a 100644 --- a/src/babel/generation/generators/template-literals.js +++ b/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("`"); diff --git a/src/babel/generation/generators/types.js b/src/babel/generation/generators/types.js index ad7c452974..d38698c124 100644 --- a/src/babel/generation/generators/types.js +++ b/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); diff --git a/src/babel/generation/index.js b/src/babel/generation/index.js index bebe87050a..e2fd0db831 100644 --- a/src/babel/generation/index.js +++ b/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, @@ -86,6 +101,10 @@ class CodeGenerator { } } + /** + * All node generators. + */ + static generators = { templateLiterals: require("./generators/template-literals"), comprehensions: require("./generators/comprehensions"), @@ -100,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; @@ -119,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) { @@ -139,6 +172,10 @@ class CodeGenerator { return false; } + /** + * [Please add a description.] + */ + _printNewline(leading, node, parent, opts) { if (!opts.statement && !n.isUserWhitespacable(node, parent)) { return; @@ -169,6 +206,10 @@ class CodeGenerator { this.newline(lines); } + /** + * [Please add a description.] + */ + print(node, parent, opts = {}) { if (!node) return; @@ -218,6 +259,10 @@ class CodeGenerator { } } + /** + * [Please add a description.] + */ + printJoin(print, nodes, opts = {}) { if (!nodes || !nodes.length) return; @@ -247,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(); @@ -254,6 +303,10 @@ class CodeGenerator { if (indent) this.dedent(); } + /** + * [Please add a description.] + */ + printBlock(print, node) { if (t.isEmptyStatement(node)) { this.semicolon(); @@ -263,6 +316,10 @@ class CodeGenerator { } } + /** + * [Please add a description.] + */ + generateComment(comment) { var val = comment.value; if (comment.type === "CommentLine") { @@ -273,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 []; @@ -300,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; @@ -371,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(); diff --git a/src/babel/generation/node/index.js b/src/babel/generation/node/index.js index 70299d814f..906f723337 100644 --- a/src/babel/generation/node/index.js +++ b/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 diff --git a/src/babel/generation/node/parentheses.js b/src/babel/generation/node/parentheses.js index 1eafc81360..44201e11fb 100644 --- a/src/babel/generation/node/parentheses.js +++ b/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; diff --git a/src/babel/generation/node/printer.js b/src/babel/generation/node/printer.js index 03bf63f355..c3dd39988e 100644 --- a/src/babel/generation/node/printer.js +++ b/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); } diff --git a/src/babel/generation/node/whitespace.js b/src/babel/generation/node/whitespace.js index 6befad891c..0d828ebbcd 100644 --- a/src/babel/generation/node/whitespace.js +++ b/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, diff --git a/src/babel/generation/position.js b/src/babel/generation/position.js index c7ae9d1bed..9dc707b5d2 100644 --- a/src/babel/generation/position.js +++ b/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") { diff --git a/src/babel/generation/source-map.js b/src/babel/generation/source-map.js index f6e760a36f..197d1dbce9 100644 --- a/src/babel/generation/source-map.js +++ b/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 diff --git a/src/babel/generation/whitespace.js b/src/babel/generation/whitespace.js index 255fcf69a8..3718fbfb58 100644 --- a/src/babel/generation/whitespace.js +++ b/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; diff --git a/src/babel/helpers/README.md b/src/babel/helpers/README.md new file mode 100644 index 0000000000..6a5bf8df2d --- /dev/null +++ b/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. diff --git a/src/babel/helpers/code-frame.js b/src/babel/helpers/code-frame.js index 15ff566aca..176c1ca394 100644 --- a/src/babel/helpers/code-frame.js +++ b/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); diff --git a/src/babel/helpers/merge.js b/src/babel/helpers/merge.js index 82b2eec8f7..33f433dbd9 100644 --- a/src/babel/helpers/merge.js +++ b/src/babel/helpers/merge.js @@ -1,5 +1,9 @@ import merge from "lodash/object/merge"; +/** + * Merge options. + */ + export default function (dest, src) { if (!dest || !src) return; diff --git a/src/babel/helpers/normalize-ast.js b/src/babel/helpers/normalize-ast.js index 9ff0219df4..e2b4d4804c 100644 --- a/src/babel/helpers/normalize-ast.js +++ b/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 || []); diff --git a/src/babel/helpers/object.js b/src/babel/helpers/object.js index 6386e50a80..c488a53173 100644 --- a/src/babel/helpers/object.js +++ b/src/babel/helpers/object.js @@ -1,3 +1,7 @@ +/** + * Create an object with a `null` prototype. + */ + export default function () { return Object.create(null); } diff --git a/src/babel/helpers/parse.js b/src/babel/helpers/parse.js index 024c659de7..b54d0054e5 100644 --- a/src/babel/helpers/parse.js +++ b/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", diff --git a/src/babel/messages.js b/src/babel/messages.js index a12341245f..ef8f9689fd 100644 --- a/src/babel/messages.js +++ b/src/babel/messages.js @@ -1,5 +1,10 @@ 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 will probably be dereferenced, therefore we can't optimise this with confidence", JSXNamespacedTags: "Namespace tags are not supported. ReactJSX is not XML.", @@ -50,18 +55,28 @@ export const MESSAGES = { ` }; -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) { +/** + * Stingify arguments to be used inside messages. + */ + +export function parseArgs(args: Array): Array { return args.map(function (val) { if (val != null && val.inspect) { return val.inspect(); diff --git a/src/babel/tools/README.md b/src/babel/tools/README.md new file mode 100644 index 0000000000..8717420a33 --- /dev/null +++ b/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. diff --git a/src/babel/tools/build-external-helpers.js b/src/babel/tools/build-external-helpers.js index 8342d60127..4d0427b6f3 100644 --- a/src/babel/tools/build-external-helpers.js +++ b/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"); diff --git a/src/babel/tools/protect.js b/src/babel/tools/protect.js index 80b4b9dc2e..e2a8335ccf 100644 --- a/src/babel/tools/protect.js +++ b/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."); diff --git a/src/babel/transformation/README.md b/src/babel/transformation/README.md new file mode 100644 index 0000000000..637cff8d1c --- /dev/null +++ b/src/babel/transformation/README.md @@ -0,0 +1,3 @@ +## Transformation + +This is the Transformation directory. diff --git a/src/babel/transformation/file/README.md b/src/babel/transformation/file/README.md new file mode 100644 index 0000000000..d42ce5497e --- /dev/null +++ b/src/babel/transformation/file/README.md @@ -0,0 +1,3 @@ +## File Transformation + +This is the File Transformation directory. diff --git a/src/babel/transformation/file/index.js b/src/babel/transformation/file/index.js index ad4051d3d6..1ffdee6945 100644 --- a/src/babel/transformation/file/index.js +++ b/src/babel/transformation/file/index.js @@ -19,6 +19,10 @@ 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 = {}; @@ -52,6 +56,10 @@ export default class File { this.hub = new Hub(this); } + /** + * [Please add a description.] + */ + static helpers = [ "inherits", "defaults", @@ -89,8 +97,17 @@ export default class File { "interop-require" ]; + /** + * [Please add a description.] + */ + static soloHelpers = []; + + /** + * [Please add a description.] + */ + initOptions(opts) { opts = new OptionManager(this.log, this.pipeline).init(opts); @@ -134,10 +151,18 @@ 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; @@ -192,6 +217,10 @@ export default class File { this.transformerStack = this.collapseStack(stack); } + /** + * [Please add a description.] + */ + collapseStack(_stack) { var stack = []; var ignore = []; @@ -228,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) { @@ -248,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]; @@ -282,6 +331,10 @@ export default class File { return id; } + /** + * [Please add a description.] + */ + attachAuxiliaryComment(node: Object): Object { var beforeComment = this.opts.auxiliaryCommentBefore; if (beforeComment) { @@ -304,6 +357,10 @@ export default class File { return node; } + /** + * [Please add a description.] + */ + addHelper(name: string): Object { var isSolo = includes(File.soloHelpers, name); @@ -350,6 +407,10 @@ export default class File { return uid; } + /** + * [Please add a description.] + */ + errorWithNode(node, msg, Error = SyntaxError) { var err; if (node && node.loc) { @@ -363,6 +424,10 @@ export default class File { return err; } + /** + * [Please add a description.] + */ + mergeSourceMap(map: Object) { var opts = this.opts; @@ -385,6 +450,9 @@ export default class File { return map; } + /** + * [Please add a description.] + */ getModuleFormatter(type: string) { if (isFunction(type) || !moduleFormatters[type]) { @@ -405,6 +473,10 @@ export default class File { return new ModuleFormatter(this); } + /** + * [Please add a description.] + */ + parse(code: string) { var opts = this.opts; @@ -433,6 +505,10 @@ export default class File { return tree; } + /** + * [Please add a description.] + */ + _addAst(ast) { this.path = NodePath.get({ hub: this.hub, @@ -445,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); @@ -458,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)) { @@ -468,6 +552,10 @@ export default class File { return this.generate(); } + /** + * [Please add a description.] + */ + wrap(code, callback) { code = code + ""; @@ -505,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]; @@ -528,6 +632,10 @@ export default class File { } } + /** + * [Please add a description.] + */ + parseInputSourceMap(code: string) { var opts = this.opts; @@ -542,6 +650,10 @@ export default class File { return code; } + /** + * [Please add a description.] + */ + parseShebang() { var shebangMatch = shebangRegex.exec(this.code); if (shebangMatch) { @@ -550,6 +662,10 @@ export default class File { } } + /** + * [Please add a description.] + */ + makeResult({ code, map = null, ast, ignored }) { var result = { metadata: null, @@ -575,6 +691,10 @@ export default class File { return result; } + /** + * [Please add a description.] + */ + generate() { var opts = this.opts; var ast = this.ast; diff --git a/src/babel/transformation/file/logger.js b/src/babel/transformation/file/logger.js index 0618b66488..4deea6d718 100644 --- a/src/babel/transformation/file/logger.js +++ b/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); } diff --git a/src/babel/transformation/file/options/README.md b/src/babel/transformation/file/options/README.md new file mode 100644 index 0000000000..46cdbb6270 --- /dev/null +++ b/src/babel/transformation/file/options/README.md @@ -0,0 +1,3 @@ +## File Options + +This is the File Options directory. diff --git a/src/babel/transformation/file/options/index.js b/src/babel/transformation/file/options/index.js index 00e900b0fd..513670a972 100644 --- a/src/babel/transformation/file/options/index.js +++ b/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]; diff --git a/src/babel/transformation/file/options/option-manager.js b/src/babel/transformation/file/options/option-manager.js index 487b0320e3..a0848f4fc3 100644 --- a/src/babel/transformation/file/options/option-manager.js +++ b/src/babel/transformation/file/options/option-manager.js @@ -31,7 +31,7 @@ export default class OptionManager { } /** - * Description + * [Please add a description.] */ static createBareOptions() { @@ -46,7 +46,7 @@ export default class OptionManager { } /** - * Description + * [Please add a description.] */ addConfig(loc) { @@ -67,7 +67,7 @@ export default class OptionManager { } /** - * Description + * [Please add a description.] */ mergeOptions(opts, alias = "foreign") { @@ -90,7 +90,7 @@ export default class OptionManager { } /** - * Description + * [Please add a description.] */ findConfigs(loc) { @@ -109,7 +109,7 @@ export default class OptionManager { } /** - * Description + * [Please add a description.] */ normaliseOptions() { @@ -142,7 +142,7 @@ export default class OptionManager { } /** - * Description + * [Please add a description.] */ init(opts) { diff --git a/src/babel/transformation/file/options/parsers.js b/src/babel/transformation/file/options/parsers.js index 951a51bdc2..18e920b9c2 100644 --- a/src/babel/transformation/file/options/parsers.js +++ b/src/babel/transformation/file/options/parsers.js @@ -1,10 +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); @@ -13,20 +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); } diff --git a/src/babel/transformation/file/plugin-manager.js b/src/babel/transformation/file/plugin-manager.js index a60f198fd8..98255eff10 100644 --- a/src/babel/transformation/file/plugin-manager.js +++ b/src/babel/transformation/file/plugin-manager.js @@ -5,6 +5,10 @@ import * as messages from "../../messages"; 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; diff --git a/src/babel/transformation/helpers/README.md b/src/babel/transformation/helpers/README.md new file mode 100644 index 0000000000..79afe09210 --- /dev/null +++ b/src/babel/transformation/helpers/README.md @@ -0,0 +1,3 @@ +## Transformation Helpers + +This is the Transformation Helpers directory. diff --git a/src/babel/transformation/helpers/build-binary-assignment-operator-transformer.js b/src/babel/transformation/helpers/build-binary-assignment-operator-transformer.js index 6df5c773ae..616edb4fd6 100644 --- a/src/babel/transformation/helpers/build-binary-assignment-operator-transformer.js +++ b/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); diff --git a/src/babel/transformation/helpers/build-comprehension.js b/src/babel/transformation/helpers/build-comprehension.js index c19bbf8c18..98babab4be 100644 --- a/src/babel/transformation/helpers/build-comprehension.js +++ b/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; diff --git a/src/babel/transformation/helpers/build-conditional-assignment-operator-transformer.js b/src/babel/transformation/helpers/build-conditional-assignment-operator-transformer.js index f56e2ee889..52e97fae7a 100644 --- a/src/babel/transformation/helpers/build-conditional-assignment-operator-transformer.js +++ b/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; diff --git a/src/babel/transformation/helpers/build-react-transformer.js b/src/babel/transformation/helpers/build-react-transformer.js index 37d20b4cff..1086fe0532 100644 --- a/src/babel/transformation/helpers/build-react-transformer.js +++ b/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; diff --git a/src/babel/transformation/helpers/call-delegate.js b/src/babel/transformation/helpers/call-delegate.js index 1de7f5a956..7cf65446d6 100644 --- a/src/babel/transformation/helpers/call-delegate.js +++ b/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); diff --git a/src/babel/transformation/helpers/define-map.js b/src/babel/transformation/helpers/define-map.js index ca77074330..b578bb2fd6 100644 --- a/src/babel/transformation/helpers/define-map.js +++ b/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); diff --git a/src/babel/transformation/helpers/explode-assignable-expression.js b/src/babel/transformation/helpers/explode-assignable-expression.js index 4289f8f1f5..c108c52de5 100644 --- a/src/babel/transformation/helpers/explode-assignable-expression.js +++ b/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) { diff --git a/src/babel/transformation/helpers/get-function-arity.js b/src/babel/transformation/helpers/get-function-arity.js index e59d86aad4..35ba3ef46e 100644 --- a/src/babel/transformation/helpers/get-function-arity.js +++ b/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++) { diff --git a/src/babel/transformation/helpers/memoise-decorators.js b/src/babel/transformation/helpers/memoise-decorators.js index 17d2ae3234..670852132f 100644 --- a/src/babel/transformation/helpers/memoise-decorators.js +++ b/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]; diff --git a/src/babel/transformation/helpers/name-method.js b/src/babel/transformation/helpers/name-method.js index 78174301c0..0b48b8de3a 100644 --- a/src/babel/transformation/helpers/name-method.js +++ b/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; diff --git a/src/babel/transformation/helpers/react.js b/src/babel/transformation/helpers/react.js index 55eb56d694..b20f9408a5 100644 --- a/src/babel/transformation/helpers/react.js +++ b/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 = []; diff --git a/src/babel/transformation/helpers/regex.js b/src/babel/transformation/helpers/regex.js index 1d3d4c2a4c..fbf552606f 100644 --- a/src/babel/transformation/helpers/regex.js +++ b/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; diff --git a/src/babel/transformation/helpers/remap-async-to-generator.js b/src/babel/transformation/helpers/remap-async-to-generator.js index e0ca170036..4170cf362b 100644 --- a/src/babel/transformation/helpers/remap-async-to-generator.js +++ b/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; diff --git a/src/babel/transformation/helpers/replace-supers.js b/src/babel/transformation/helpers/replace-supers.js index fbe5ffef0f..f9b6f9c2aa 100644 --- a/src/babel/transformation/helpers/replace-supers.js +++ b/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) { diff --git a/src/babel/transformation/index.js b/src/babel/transformation/index.js index d369f52ba9..cd62db85a1 100644 --- a/src/babel/transformation/index.js +++ b/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); diff --git a/src/babel/transformation/modules/README.md b/src/babel/transformation/modules/README.md new file mode 100644 index 0000000000..75ededeec9 --- /dev/null +++ b/src/babel/transformation/modules/README.md @@ -0,0 +1,3 @@ +## Module Transformation + +This is the Module Transformation directory. diff --git a/src/babel/transformation/modules/_default.js b/src/babel/transformation/modules/_default.js index d563e51bb6..48c9af8331 100644 --- a/src/babel/transformation/modules/_default.js +++ b/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; diff --git a/src/babel/transformation/modules/_strict.js b/src/babel/transformation/modules/_strict.js index 02c8aba004..89adae51f5 100644 --- a/src/babel/transformation/modules/_strict.js +++ b/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; diff --git a/src/babel/transformation/modules/amd-strict.js b/src/babel/transformation/modules/amd-strict.js index bb7bc59663..53341c61de 100644 --- a/src/babel/transformation/modules/amd-strict.js +++ b/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); diff --git a/src/babel/transformation/modules/amd.js b/src/babel/transformation/modules/amd.js index a660373731..1d97e38393 100644 --- a/src/babel/transformation/modules/amd.js +++ b/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; diff --git a/src/babel/transformation/modules/common-strict.js b/src/babel/transformation/modules/common-strict.js index c5acc6a9a5..729348386c 100644 --- a/src/babel/transformation/modules/common-strict.js +++ b/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); diff --git a/src/babel/transformation/modules/common.js b/src/babel/transformation/modules/common.js index 9293d88b46..55aced378f 100644 --- a/src/babel/transformation/modules/common.js +++ b/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; diff --git a/src/babel/transformation/modules/ignore.js b/src/babel/transformation/modules/ignore.js index e293ae8b6c..33f909e274 100644 --- a/src/babel/transformation/modules/ignore.js +++ b/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() {} diff --git a/src/babel/transformation/modules/index.js b/src/babel/transformation/modules/index.js index 65c17b7cf9..82db428417 100644 --- a/src/babel/transformation/modules/index.js +++ b/src/babel/transformation/modules/index.js @@ -1,3 +1,7 @@ +/** + * [Please add a description.] + */ + export default { commonStrict: require("./common-strict"), amdStrict: require("./amd-strict"), diff --git a/src/babel/transformation/modules/lib/remaps.js b/src/babel/transformation/modules/lib/remaps.js index 17e4254b1a..5935ab9d77 100644 --- a/src/babel/transformation/modules/lib/remaps.js +++ b/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)) { diff --git a/src/babel/transformation/modules/system.js b/src/babel/transformation/modules/system.js index 83813e670f..6d4e82b11d 100644 --- a/src/babel/transformation/modules/system.js +++ b/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 @@ -41,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); @@ -54,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)) { @@ -73,6 +108,10 @@ var runnerSettersVisitor = { } }; +/** + * [Please add a description.] + */ + export default class SystemFormatter extends AMDFormatter { constructor(file) { super(file); @@ -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); diff --git a/src/babel/transformation/modules/umd-strict.js b/src/babel/transformation/modules/umd-strict.js index 1204b5503a..250a015037 100644 --- a/src/babel/transformation/modules/umd-strict.js +++ b/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); diff --git a/src/babel/transformation/modules/umd.js b/src/babel/transformation/modules/umd.js index 94f0c93d43..79c99e0c25 100644 --- a/src/babel/transformation/modules/umd.js +++ b/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); diff --git a/src/babel/transformation/pipeline.js b/src/babel/transformation/pipeline.js index ae74d9d0bc..0da9f4dff8 100644 --- a/src/babel/transformation/pipeline.js +++ b/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) { var keys = []; diff --git a/src/babel/transformation/plugin-pass.js b/src/babel/transformation/plugin-pass.js index be860f1deb..6f66b7d51b 100644 --- a/src/babel/transformation/plugin-pass.js +++ b/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}`); diff --git a/src/babel/transformation/plugin.js b/src/babel/transformation/plugin.js index 2a5ac25957..0b0182848c 100644 --- a/src/babel/transformation/plugin.js +++ b/src/babel/transformation/plugin.js @@ -21,6 +21,10 @@ const VALID_METADATA_PROPERTES = [ "secondPass" ]; +/** + * [Please add a description.] + */ + export default class Plugin { constructor(key: string, plugin: Object) { Plugin.validate(key, plugin); @@ -51,6 +55,10 @@ export default class Plugin { this.key = key; } + /** + * [Please add a description.] + */ + static validate(name, plugin) { for (let key in plugin) { if (key[0] === "_") continue; @@ -68,11 +76,19 @@ export default class Plugin { } } + /** + * [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)) { diff --git a/src/babel/transformation/templates/README.md b/src/babel/transformation/templates/README.md new file mode 100644 index 0000000000..db554fe0a4 --- /dev/null +++ b/src/babel/transformation/templates/README.md @@ -0,0 +1,3 @@ +## Transformation Templates + +This is the Transformation Templates directory. diff --git a/src/babel/transformation/transformer.js b/src/babel/transformation/transformer.js index 2077d9ea81..617d3408ce 100644 --- a/src/babel/transformation/transformer.js +++ b/src/babel/transformation/transformer.js @@ -1,5 +1,9 @@ import Plugin from "./plugin"; +/** + * [Please add a description.] + */ + export default class Transformer { constructor(key, obj) { var plugin = {}; diff --git a/src/babel/transformation/transformers/README.md b/src/babel/transformation/transformers/README.md new file mode 100644 index 0000000000..6005d15209 --- /dev/null +++ b/src/babel/transformation/transformers/README.md @@ -0,0 +1,3 @@ +## Transformers + +This is the Transformers directory. diff --git a/src/babel/transformation/transformers/es3/member-expression-literals.js b/src/babel/transformation/transformers/es3/member-expression-literals.js index ec0ea35db2..45c24acab9 100644 --- a/src/babel/transformation/transformers/es3/member-expression-literals.js +++ b/src/babel/transformation/transformers/es3/member-expression-literals.js @@ -4,7 +4,31 @@ export var metadata = { group: "builtin-trailing" }; +/** + * Turn member expression reserved word properties into literals. + * + * @example + * + * **In** + * + * ```javascript + * foo.catch; + * ``` + * + * **Out** + * + * ```javascript + * foo["catch"]; + * ``` + */ + export var visitor = { + + /** + * Look for non-computed properties with names that are not valid identifiers. + * Turn them into computed properties with literal names. + */ + MemberExpression: { exit(node) { var prop = node.property; diff --git a/src/babel/transformation/transformers/es3/property-literals.js b/src/babel/transformation/transformers/es3/property-literals.js index ff2040b572..47d1c3f0a2 100644 --- a/src/babel/transformation/transformers/es3/property-literals.js +++ b/src/babel/transformation/transformers/es3/property-literals.js @@ -4,7 +4,33 @@ export var metadata = { group: "builtin-trailing" }; +/** + * Turn reserved word properties into literals. + * + * **In** + * + * ```javascript + * var foo = { + * catch: function () {} + * }; + * ``` + * + * **Out** + * + * ```javascript + * var foo = { + * "catch": function () {} + * }; + * ``` + */ + export var visitor = { + + /** + * Look for non-computed keys with names that are not valid identifiers. + * Turn them into literals. + */ + Property: { exit(node) { var key = node.key; diff --git a/src/babel/transformation/transformers/es5/properties.mutators.js b/src/babel/transformation/transformers/es5/properties.mutators.js index 953527df25..fe69b65c00 100644 --- a/src/babel/transformation/transformers/es5/properties.mutators.js +++ b/src/babel/transformation/transformers/es5/properties.mutators.js @@ -1,7 +1,43 @@ import * as defineMap from "../../helpers/define-map"; import * as t from "../../../types"; +/** + * Turn [object initializer mutators](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Object_initializer#Method_definitions) + * into `Object.defineProperties`. + * + * **In** + * + * ```javascript + * var foo = { + * get bar() { + * return "bar"; + * } + * }; + * ``` + * + * **Out** + * + * ```javascript + * var foo = Object.defineProperties({}, { + * bar: { + * get: function () { + * return "bar"; + * }, + * enumerable: true, + * configurable: true + * } + * }); + * ``` + */ + export var visitor = { + + /** + * Look for getters and setters on an object. + * Filter them out and wrap the object with an `Object.defineProperties` that + * defines the getters and setters. + */ + ObjectExpression(node, parent, scope, file) { var hasAny = false; for (var prop of (node.properties: Array)) { diff --git a/src/babel/transformation/transformers/es6/arrow-functions.js b/src/babel/transformation/transformers/es6/arrow-functions.js index 0836c1d5f1..afd375b682 100644 --- a/src/babel/transformation/transformers/es6/arrow-functions.js +++ b/src/babel/transformation/transformers/es6/arrow-functions.js @@ -1,4 +1,29 @@ +/** + * Turn arrow functions into normal functions. + * + * @example + * + * **In** + * + * ```javascript + * arr.map(x => x * x); + * ``` + * + * **Out** + * + * ```javascript + * arr.map(function (x) { + * return x * x; + * }); + */ + export var visitor = { + + /** + * Look for arrow functions and mark them as "shadow functions". + * @see /transformation/transformers/internal/shadow-functions.js + */ + ArrowFunctionExpression(node) { this.ensureBlock(); node.expression = false; diff --git a/src/babel/transformation/transformers/es6/block-scoping.js b/src/babel/transformation/transformers/es6/block-scoping.js index b8c902a034..7f5dc6a18e 100644 --- a/src/babel/transformation/transformers/es6/block-scoping.js +++ b/src/babel/transformation/transformers/es6/block-scoping.js @@ -8,6 +8,10 @@ import * as t from "../../../types"; import values from "lodash/object/values"; import extend from "lodash/object/extend"; +/** + * [Please add a description.] + */ + function isLet(node, parent) { if (!t.isVariableDeclaration(node)) return false; if (node._let) return true; @@ -26,14 +30,26 @@ function isLet(node, parent) { return true; } +/** + * [Please add a description.] + */ + function isLetInitable(node, parent) { return !t.isFor(parent) || !t.isFor(parent, { left: node }); } +/** + * [Please add a description.] + */ + function isVar(node, parent) { return t.isVariableDeclaration(node, { kind: "var" }) && !isLet(node, parent); } +/** + * [Please add a description.] + */ + function standardizeLets(declars) { for (var declar of (declars: Array)) { delete declar._let; @@ -44,7 +60,16 @@ export var metadata = { group: "builtin-advanced" }; +/** + * [Please add a description.] + */ + export var visitor = { + + /** + * [Please add a description.] + */ + VariableDeclaration(node, parent, scope, file) { if (!isLet(node, parent)) return; @@ -67,6 +92,10 @@ export var visitor = { } }, + /** + * [Please add a description.] + */ + Loop(node, parent, scope, file) { var init = node.left || node.init; if (isLet(init, node)) { @@ -78,6 +107,10 @@ export var visitor = { return blockScoping.run(); }, + /** + * [Please add a description.] + */ + "BlockStatement|Program"(block, parent, scope, file) { if (!t.isLoop(parent)) { var blockScoping = new BlockScoping(null, this, parent, scope, file); @@ -86,6 +119,10 @@ export var visitor = { } }; +/** + * [Please add a description.] + */ + function replace(node, parent, scope, remaps) { var remap = remaps[node.name]; if (!remap) return; @@ -100,9 +137,17 @@ function replace(node, parent, scope, remaps) { } } +/** + * [Please add a description.] + */ + var replaceVisitor = { ReferencedIdentifier: replace, + /** + * [Please add a description.] + */ + AssignmentExpression(node, parent, scope, remaps) { var ids = this.getBindingIdentifiers(); for (var name in ids) { @@ -111,6 +156,10 @@ var replaceVisitor = { }, }; +/** + * [Please add a description.] + */ + function traverseReplace(node, parent, scope, remaps) { if (t.isIdentifier(node)) { replace(node, parent, scope, remaps); @@ -126,14 +175,32 @@ function traverseReplace(node, parent, scope, remaps) { scope.traverse(node, replaceVisitor, remaps); } +/** + * [Please add a description.] + */ + var letReferenceBlockVisitor = { + + /** + * [Please add a description.] + */ + Function(node, parent, scope, state) { this.traverse(letReferenceFunctionVisitor, state); return this.skip(); } }; +/** + * [Please add a description.] + */ + var letReferenceFunctionVisitor = { + + /** + * [Please add a description.] + */ + ReferencedIdentifier(node, parent, scope, state) { var ref = state.letReferences[node.name]; @@ -148,6 +215,10 @@ var letReferenceFunctionVisitor = { } }; +/** + * [Please add a description.] + */ + var hoistVarDeclarationsVisitor = { enter(node, parent, scope, self) { if (this.isForStatement()) { @@ -172,12 +243,20 @@ var hoistVarDeclarationsVisitor = { } }; +/** + * [Please add a description.] + */ + var loopLabelVisitor = { LabeledStatement(node, parent, scope, state) { state.innerLabels.push(node.label.name); } }; +/** + * [Please add a description.] + */ + var continuationVisitor = { enter(node, parent, scope, state) { if (this.isAssignmentExpression() || this.isUpdateExpression()) { @@ -190,6 +269,10 @@ var continuationVisitor = { } }; +/** + * [Please add a description.] + */ + var loopNodeTo = function (node) { if (t.isBreakStatement(node)) { return "break"; @@ -198,7 +281,16 @@ var loopNodeTo = function (node) { } }; +/** + * [Please add a description.] + */ + var loopVisitor = { + + /** + * [Please add a description.] + */ + Loop(node, parent, scope, state) { var oldIgnoreLabeless = state.ignoreLabeless; state.ignoreLabeless = true; @@ -207,10 +299,18 @@ var loopVisitor = { this.skip(); }, + /** + * [Please add a description.] + */ + Function() { this.skip(); }, + /** + * [Please add a description.] + */ + SwitchCase(node, parent, scope, state) { var oldInSwitchCase = state.inSwitchCase; state.inSwitchCase = true; @@ -219,6 +319,10 @@ var loopVisitor = { this.skip(); }, + /** + * [Please add a description.] + */ + enter(node, parent, scope, state) { var replace; var loopText = loopNodeTo(node); @@ -263,12 +367,11 @@ var loopVisitor = { } }; +/** + * [Please add a description.] + */ + class BlockScoping { - - /** - * Description - */ - constructor(loopPath?: NodePath, blockPath: NodePath, parent: Object, scope: Scope, file: File) { this.parent = parent; this.scope = scope; @@ -319,7 +422,7 @@ class BlockScoping { } /** - * Description + * [Please add a description.] */ remap() { @@ -366,7 +469,7 @@ class BlockScoping { } /** - * Description + * [Please add a description.] */ wrapClosure() { @@ -486,7 +589,7 @@ class BlockScoping { } /** - * Description + * [Please add a description.] */ getLetReferences() { @@ -599,7 +702,7 @@ class BlockScoping { } /** - * Description + * [Please add a description.] */ buildHas(ret: { type: "Identifier" }, call: { type: "CallExpression" }) { diff --git a/src/babel/transformation/transformers/es6/classes/index.js b/src/babel/transformation/transformers/es6/classes/index.js index d2373435f4..b03635a575 100644 --- a/src/babel/transformation/transformers/es6/classes/index.js +++ b/src/babel/transformation/transformers/es6/classes/index.js @@ -3,13 +3,26 @@ import VanillaTransformer from "./vanilla"; import * as t from "../../../../types"; import { bare } from "../../../helpers/name-method"; +/** + * [Please add a description.] + */ + export var visitor = { + + /** + * [Please add a description.] + */ + ClassDeclaration(node) { return t.variableDeclaration("let", [ t.variableDeclarator(node.id, t.toExpression(node)) ]); }, + /** + * [Please add a description.] + */ + ClassExpression(node, parent, scope, file) { var inferred = bare(node, parent, scope); if (inferred) return inferred; diff --git a/src/babel/transformation/transformers/es6/classes/loose.js b/src/babel/transformation/transformers/es6/classes/loose.js index 3c42f53074..2b4583537b 100644 --- a/src/babel/transformation/transformers/es6/classes/loose.js +++ b/src/babel/transformation/transformers/es6/classes/loose.js @@ -1,12 +1,20 @@ import VanillaTransformer from "./vanilla"; import * as t from "../../../../types"; +/** + * [Please add a description.] + */ + export default class LooseClassTransformer extends VanillaTransformer { constructor() { super(...arguments); this.isLoose = true; } + /** + * [Please add a description.] + */ + _processMethod(node) { if (!node.decorators) { // use assignments instead of define properties for loose classes diff --git a/src/babel/transformation/transformers/es6/classes/vanilla.js b/src/babel/transformation/transformers/es6/classes/vanilla.js index b4fe2675ed..eb3e05e20a 100644 --- a/src/babel/transformation/transformers/es6/classes/vanilla.js +++ b/src/babel/transformation/transformers/es6/classes/vanilla.js @@ -10,7 +10,16 @@ import * as t from "../../../../types"; const PROPERTY_COLLISION_METHOD_NAME = "__initializeProperties"; +/** + * [Please add a description.] + */ + var collectPropertyReferencesVisitor = { + + /** + * [Please add a description.] + */ + Identifier: { enter(node, parent, scope, state) { if (this.parentPath.isClassProperty({ key: node })) { @@ -24,15 +33,32 @@ var collectPropertyReferencesVisitor = { } }; +/** + * [Please add a description.] + */ + var verifyConstructorVisitor = { + + /** + * [Please add a description.] + */ + MethodDefinition() { this.skip(); }, + /** + * [Please add a description.] + */ + Property(node) { if (node.method) this.skip(); }, + /** + * [Please add a description.] + */ + CallExpression: { exit(node, parent, scope, state) { if (this.get("callee").isSuper()) { @@ -46,10 +72,18 @@ var verifyConstructorVisitor = { } }, + /** + * [Please add a description.] + */ + "FunctionDeclaration|FunctionExpression"() { this.skip(); }, + /** + * [Please add a description.] + */ + ThisExpression(node, parent, scope, state) { if (state.isDerived && !state.hasBareSuper) { if (this.inShadow()) { @@ -70,6 +104,10 @@ var verifyConstructorVisitor = { } }, + /** + * [Please add a description.] + */ + Super(node, parent, scope, state) { if (state.isDerived && !state.hasBareSuper && !this.parentPath.isCallExpression({ callee: node })) { throw this.errorWithNode("'super.*' is not allowed before super()"); @@ -77,12 +115,11 @@ var verifyConstructorVisitor = { } }; +/** + * [Please add a description.] + */ + export default class ClassTransformer { - - /** - * Description - */ - constructor(path: NodePath, file: File) { this.parent = path.parent; this.scope = path.scope; @@ -116,8 +153,7 @@ export default class ClassTransformer { } /** - * Description - * + * [Please add a description.] * @returns {Array} */ @@ -187,7 +223,7 @@ export default class ClassTransformer { } /** - * Description + * [Please add a description.] */ buildConstructor() { @@ -195,7 +231,7 @@ export default class ClassTransformer { } /** - * Description + * [Please add a description.] */ pushToMap(node, enumerable, kind = "value") { @@ -220,6 +256,7 @@ export default class ClassTransformer { } /** + * [Please add a description.] * https://www.youtube.com/watch?v=fWNaR-rxAic */ @@ -247,7 +284,7 @@ export default class ClassTransformer { } /** - * Description + * [Please add a description.] */ buildBody() { @@ -266,7 +303,7 @@ export default class ClassTransformer { } /** - * Description + * [Please add a description.] */ pushBody() { @@ -308,7 +345,7 @@ export default class ClassTransformer { } /** - * Description + * [Please add a description.] */ clearDescriptors() { @@ -320,7 +357,7 @@ export default class ClassTransformer { } /** - * Description + * [Please add a description.] */ pushDescriptors() { @@ -379,7 +416,7 @@ export default class ClassTransformer { } /** - * Description + * [Please add a description.] */ buildObjectAssignment(id) { @@ -389,7 +426,7 @@ export default class ClassTransformer { } /** - * Description + * [Please add a description.] */ placePropertyInitializers() { @@ -422,7 +459,7 @@ export default class ClassTransformer { } /** - * Description + * [Please add a description.] */ hasPropertyCollision(): boolean { @@ -438,7 +475,7 @@ export default class ClassTransformer { } /** - * Description + * [Please add a description.] */ verifyConstructor(path: NodePath) { @@ -483,12 +520,16 @@ export default class ClassTransformer { this.pushToMap(node); } + /** + * [Please add a description.] + */ + _processMethod() { return false; } /** - * Description + * [Please add a description.] */ pushProperty(node: { type: "ClassProperty" }, path: NodePath) { @@ -571,6 +612,10 @@ export default class ClassTransformer { this._pushConstructor(); } + /** + * [Please add a description.] + */ + _pushConstructor() { if (this.pushedConstructor) return; this.pushedConstructor = true; diff --git a/src/babel/transformation/transformers/es6/constants.js b/src/babel/transformation/transformers/es6/constants.js index 6355428cdc..def32a8321 100644 --- a/src/babel/transformation/transformers/es6/constants.js +++ b/src/babel/transformation/transformers/es6/constants.js @@ -1,6 +1,31 @@ import * as messages from "../../../messages"; +/** + * Turn constants into variables. + * Ensure there are no constant violations in any scope. + * + * @example + * + * **In** + * + * ```javascript + * const MULTIPLIER = 5; + * ``` + * + * **Out** + * + * ```javascript + * var MULTIPLIER = 5; + * ``` + */ + export var visitor = { + + /** + * Look for any constants (or modules) in scope. + * If they have any `constantViolations` throw an error. + */ + Scope(node, parent, scope) { for (var name in scope.bindings) { var binding = scope.bindings[name]; @@ -14,6 +39,11 @@ export var visitor = { } }, + /** + * Look for constants. + * Turn them into `let` variables. + */ + VariableDeclaration(node) { if (node.kind === "const") node.kind = "let"; } diff --git a/src/babel/transformation/transformers/es6/destructuring.js b/src/babel/transformation/transformers/es6/destructuring.js index c87c5f8214..a8587fecdb 100644 --- a/src/babel/transformation/transformers/es6/destructuring.js +++ b/src/babel/transformation/transformers/es6/destructuring.js @@ -5,7 +5,16 @@ export var metadata = { group: "builtin-advanced" }; +/** + * [Please add a description.] + */ + export var visitor = { + + /** + * [Please add a description.] + */ + ForXStatement(node, parent, scope, file) { var left = node.left; @@ -54,6 +63,10 @@ export var visitor = { block.body = nodes.concat(block.body); }, + /** + * [Please add a description.] + */ + Function(node, parent, scope, file) { var hasDestructuring = false; for (let pattern of (node.params: Array)) { @@ -98,6 +111,10 @@ export var visitor = { block.body = nodes.concat(block.body); }, + /** + * [Please add a description.] + */ + CatchClause(node, parent, scope, file) { var pattern = node.param; if (!t.isPattern(pattern)) return; @@ -118,6 +135,10 @@ export var visitor = { node.body.body = nodes.concat(node.body.body); }, + /** + * [Please add a description.] + */ + AssignmentExpression(node, parent, scope, file) { if (!t.isPattern(node.left)) return; @@ -152,6 +173,10 @@ export var visitor = { return nodes; }, + /** + * [Please add a description.] + */ + VariableDeclaration(node, parent, scope, file) { if (t.isForXStatement(parent)) return; if (!variableDeclarationHasPattern(node)) return; @@ -209,6 +234,10 @@ export var visitor = { } }; +/** + * Test if a VariableDeclaration's declarations contains any Patterns. + */ + function variableDeclarationHasPattern(node) { for (var i = 0; i < node.declarations.length; i++) { if (t.isPattern(node.declarations[i].id)) { @@ -218,6 +247,10 @@ function variableDeclarationHasPattern(node) { return false; } +/** + * Test if an ArrayPattern's elements contain any RestElements. + */ + function hasRest(pattern) { for (var i = 0; i < pattern.elements.length; i++) { if (t.isRestElement(pattern.elements[i])) { @@ -227,7 +260,16 @@ function hasRest(pattern) { return false; } +/** + * [Please add a description.] + */ + var arrayUnpackVisitor = { + + /** + * [Please add a description.] + */ + ReferencedIdentifier(node, parent, scope, state) { if (state.bindings[node.name]) { state.deopt = true; @@ -236,6 +278,10 @@ var arrayUnpackVisitor = { } }; +/** + * [Please add a description.] + */ + class DestructuringTransformer { constructor(opts) { this.blockHoist = opts.blockHoist; @@ -247,6 +293,10 @@ class DestructuringTransformer { this.kind = opts.kind; } + /** + * [Please add a description.] + */ + buildVariableAssignment(id, init) { var op = this.operator; if (t.isMemberExpression(id)) op = "="; @@ -266,6 +316,10 @@ class DestructuringTransformer { return node; } + /** + * [Please add a description.] + */ + buildVariableDeclaration(id, init) { var declar = t.variableDeclaration("var", [ t.variableDeclarator(id, init) @@ -274,6 +328,10 @@ class DestructuringTransformer { return declar; } + /** + * [Please add a description.] + */ + push(id, init) { if (t.isObjectPattern(id)) { this.pushObjectPattern(id, init); @@ -286,6 +344,10 @@ class DestructuringTransformer { } } + /** + * [Please add a description.] + */ + toArray(node, count) { if (this.file.isLoose("es6.destructuring") || (t.isIdentifier(node) && this.arrays[node.name])) { return node; @@ -294,6 +356,10 @@ class DestructuringTransformer { } } + /** + * [Please add a description.] + */ + pushAssignmentPattern(pattern, valueRef) { // we need to assign the current value of the assignment to avoid evaluating // it more than once @@ -328,6 +394,10 @@ class DestructuringTransformer { } } + /** + * [Please add a description.] + */ + pushObjectSpread(pattern, objRef, spreadProp, spreadPropIndex) { // get all the keys that appear in this object before the current spread @@ -356,6 +426,10 @@ class DestructuringTransformer { this.nodes.push(this.buildVariableAssignment(spreadProp.argument, value)); } + /** + * [Please add a description.] + */ + pushObjectProperty(prop, propRef) { if (t.isLiteral(prop.key)) prop.computed = true; @@ -369,6 +443,10 @@ class DestructuringTransformer { } } + /** + * [Please add a description.] + */ + pushObjectPattern(pattern, objRef) { // https://github.com/babel/babel/issues/681 @@ -400,6 +478,10 @@ class DestructuringTransformer { } } + /** + * [Please add a description.] + */ + canUnpackArrayPattern(pattern, arr) { // not an array so there's no way we can deal with this if (!t.isArrayExpression(arr)) return false; @@ -426,6 +508,10 @@ class DestructuringTransformer { return !state.deopt; } + /** + * [Please add a description.] + */ + pushUnpackedArrayPattern(pattern, arr) { for (var i = 0; i < pattern.elements.length; i++) { var elem = pattern.elements[i]; @@ -437,6 +523,10 @@ class DestructuringTransformer { } } + /** + * [Please add a description.] + */ + pushArrayPattern(pattern, arrayRef) { if (!pattern.elements) return; @@ -500,6 +590,10 @@ class DestructuringTransformer { } } + /** + * [Please add a description.] + */ + init(pattern, ref) { // trying to destructure a value that we can't evaluate more than once so we // need to save it to a variable diff --git a/src/babel/transformation/transformers/es6/for-of.js b/src/babel/transformation/transformers/es6/for-of.js index 9d41824820..7d13d146b5 100644 --- a/src/babel/transformation/transformers/es6/for-of.js +++ b/src/babel/transformation/transformers/es6/for-of.js @@ -2,7 +2,16 @@ import * as messages from "../../../messages"; import * as util from "../../../util"; import * as t from "../../../types"; +/** + * [Please add a description.] + */ + export var visitor = { + + /** + * [Please add a description.] + */ + ForOfStatement(node, parent, scope, file) { if (this.get("right").isArrayExpression()) { return _ForOfStatementArray.call(this, node, scope, file); @@ -39,6 +48,10 @@ export var visitor = { } }; +/** + * [Please add a description.] + */ + export function _ForOfStatementArray(node, scope, file) { var nodes = []; var right = node.right; @@ -81,6 +94,10 @@ export function _ForOfStatementArray(node, scope, file) { return nodes; } +/** + * [Please add a description.] + */ + var loose = function (node, parent, scope, file) { var left = node.left; var declar, id; @@ -124,6 +141,10 @@ var loose = function (node, parent, scope, file) { }; }; +/** + * [Please add a description.] + */ + var spec = function (node, parent, scope, file) { var left = node.left; var declar; diff --git a/src/babel/transformation/transformers/es6/modules.js b/src/babel/transformation/transformers/es6/modules.js index 5959ef1b81..becfea1747 100644 --- a/src/babel/transformation/transformers/es6/modules.js +++ b/src/babel/transformation/transformers/es6/modules.js @@ -12,7 +12,16 @@ export var metadata = { group: "builtin-modules" }; +/** + * [Please add a description.] + */ + export var visitor = { + + /** + * [Please add a description.] + */ + ImportDeclaration(node, parent, scope, file) { // flow type if (node.importKind === "type" || node.importKind === "typeof") return; @@ -35,6 +44,10 @@ export var visitor = { return nodes; }, + /** + * [Please add a description.] + */ + ExportAllDeclaration(node, parent, scope, file) { var nodes = []; file.moduleFormatter.exportAllDeclaration(node, nodes, scope); @@ -42,6 +55,10 @@ export var visitor = { return nodes; }, + /** + * [Please add a description.] + */ + ExportDefaultDeclaration(node, parent, scope, file) { var nodes = []; file.moduleFormatter.exportDeclaration(node, nodes, scope); @@ -49,6 +66,10 @@ export var visitor = { return nodes; }, + /** + * [Please add a description.] + */ + ExportNamedDeclaration(node, parent, scope, file) { // flow type if (this.get("declaration").isTypeAlias()) return; diff --git a/src/babel/transformation/transformers/es6/object-super.js b/src/babel/transformation/transformers/es6/object-super.js index a63e05cc25..14fffe476a 100644 --- a/src/babel/transformation/transformers/es6/object-super.js +++ b/src/babel/transformation/transformers/es6/object-super.js @@ -1,6 +1,10 @@ import ReplaceSupers from "../../helpers/replace-supers"; import * as t from "../../../types"; +/** + * [Please add a description.] + */ + function Property(path, node, scope, getObjectRef, file) { if (!node.method && node.kind === "init") return; if (!t.isFunction(node.value)) return; @@ -17,7 +21,16 @@ function Property(path, node, scope, getObjectRef, file) { replaceSupers.replace(); } +/** + * [Please add a description.] + */ + export var visitor = { + + /** + * [Please add a description.] + */ + ObjectExpression(node, parent, scope, file) { var objectRef; var getObjectRef = () => objectRef = objectRef || scope.generateUidIdentifier("obj"); diff --git a/src/babel/transformation/transformers/es6/parameters/default.js b/src/babel/transformation/transformers/es6/parameters/default.js index 6f6c8ea093..b370352b1d 100644 --- a/src/babel/transformation/transformers/es6/parameters/default.js +++ b/src/babel/transformation/transformers/es6/parameters/default.js @@ -3,6 +3,10 @@ import getFunctionArity from "../../../helpers/get-function-arity"; import * as util from "../../../../util"; import * as t from "../../../../types"; +/** + * [Please add a description.] + */ + var hasDefaults = function (node) { for (var i = 0; i < node.params.length; i++) { if (!t.isIdentifier(node.params[i])) return true; @@ -10,7 +14,16 @@ var hasDefaults = function (node) { return false; }; +/** + * [Please add a description.] + */ + var iifeVisitor = { + + /** + * [Please add a description.] + */ + ReferencedIdentifier(node, parent, scope, state) { if (node.name !== "eval") { if (!state.scope.hasOwnBinding(node.name)) return; @@ -22,7 +35,16 @@ var iifeVisitor = { } }; +/** + * [Please add a description.] + */ + export var visitor = { + + /** + * [Please add a description.] + */ + Function(node, parent, scope, file) { if (!hasDefaults(node)) return; diff --git a/src/babel/transformation/transformers/es6/parameters/index.js b/src/babel/transformation/transformers/es6/parameters/index.js index 24c5ebded3..3724e5a095 100644 --- a/src/babel/transformation/transformers/es6/parameters/index.js +++ b/src/babel/transformation/transformers/es6/parameters/index.js @@ -7,4 +7,8 @@ export var metadata = { group: "builtin-advanced" }; +/** + * [Please add a description.] + */ + export var visitor = visitors.merge([rest.visitor, def.visitor]); diff --git a/src/babel/transformation/transformers/es6/parameters/rest.js b/src/babel/transformation/transformers/es6/parameters/rest.js index 82c40e0d25..97a2430588 100644 --- a/src/babel/transformation/transformers/es6/parameters/rest.js +++ b/src/babel/transformation/transformers/es6/parameters/rest.js @@ -1,7 +1,16 @@ import * as util from "../../../../util"; import * as t from "../../../../types"; +/** + * [Please add a description.] + */ + var memberExpressionOptimisationVisitor = { + + /** + * [Please add a description.] + */ + Scope(node, parent, scope, state) { // check if this scope has a local binding that will shadow the rest parameter if (!scope.bindingIdentifierEquals(state.name, state.outerBinding)) { @@ -9,11 +18,19 @@ var memberExpressionOptimisationVisitor = { } }, + /** + * [Please add a description.] + */ + Flow() { // don't touch reference in type annotations this.skip(); }, + /** + * [Please add a description.] + */ + Function(node, parent, scope, state) { // skip over functions as whatever `arguments` we reference inside will refer // to the wrong function @@ -24,6 +41,10 @@ var memberExpressionOptimisationVisitor = { this.skip(); }, + /** + * [Please add a description.] + */ + ReferencedIdentifier(node, parent, scope, state) { // we can't guarantee the purity of arguments if (node.name === "arguments") { @@ -60,6 +81,10 @@ var memberExpressionOptimisationVisitor = { } }; +/** + * [Please add a description.] + */ + function optimiseMemberExpression(parent, offset) { if (offset === 0) return; @@ -75,11 +100,24 @@ function optimiseMemberExpression(parent, offset) { } } +/** + * [Please add a description.] + */ + function hasRest(node) { return t.isRestElement(node.params[node.params.length - 1]); } +/** + * [Please add a description.] + */ + export var visitor = { + + /** + * [Please add a description.] + */ + Function(node, parent, scope) { if (!hasRest(node)) return; diff --git a/src/babel/transformation/transformers/es6/properties.computed.js b/src/babel/transformation/transformers/es6/properties.computed.js index b1ce1939e3..ce5fd45b2d 100644 --- a/src/babel/transformation/transformers/es6/properties.computed.js +++ b/src/babel/transformation/transformers/es6/properties.computed.js @@ -1,5 +1,9 @@ import * as t from "../../../types"; +/** + * [Please add a description.] + */ + function loose(node, body, objId) { for (var prop of (node.properties: Array)) { body.push(t.expressionStatement( @@ -12,6 +16,10 @@ function loose(node, body, objId) { } } +/** + * [Please add a description.] + */ + function spec(node, body, objId, initProps, file) { // add a simple assignment for all Symbol member expressions due to symbol polyfill limitations // otherwise use Object.defineProperty @@ -45,7 +53,16 @@ function spec(node, body, objId, initProps, file) { } } +/** + * [Please add a description.] + */ + export var visitor = { + + /** + * [Please add a description.] + */ + ObjectExpression: { exit(node, parent, scope, file) { var hasComputed = false; diff --git a/src/babel/transformation/transformers/es6/properties.shorthand.js b/src/babel/transformation/transformers/es6/properties.shorthand.js index 57b7210122..b989d49e6e 100644 --- a/src/babel/transformation/transformers/es6/properties.shorthand.js +++ b/src/babel/transformation/transformers/es6/properties.shorthand.js @@ -1,4 +1,13 @@ +/** + * [Please add a description.] + */ + export var visitor = { + + /** + * [Please add a description.] + */ + Property(node) { if (node.method) { node.method = false; diff --git a/src/babel/transformation/transformers/es6/regex.sticky.js b/src/babel/transformation/transformers/es6/regex.sticky.js index 427b4c76a0..51e7e96834 100644 --- a/src/babel/transformation/transformers/es6/regex.sticky.js +++ b/src/babel/transformation/transformers/es6/regex.sticky.js @@ -1,7 +1,16 @@ import * as regex from "../../helpers/regex"; import * as t from "../../../types"; +/** + * [Please add a description.] + */ + export var visitor = { + + /** + * [Please add a description.] + */ + Literal(node) { if (!regex.is(node, "y")) return; return t.newExpression(t.identifier("RegExp"), [ diff --git a/src/babel/transformation/transformers/es6/regex.unicode.js b/src/babel/transformation/transformers/es6/regex.unicode.js index 0b26277bb9..94f6c9ae07 100644 --- a/src/babel/transformation/transformers/es6/regex.unicode.js +++ b/src/babel/transformation/transformers/es6/regex.unicode.js @@ -1,7 +1,16 @@ import rewritePattern from "regexpu/rewrite-pattern"; import * as regex from "../../helpers/regex"; +/** + * [Please add a description.] + */ + export var visitor = { + + /** + * [Please add a description.] + */ + Literal(node) { if (!regex.is(node, "u")) return; node.regex.pattern = rewritePattern(node.regex.pattern, node.regex.flags); diff --git a/src/babel/transformation/transformers/es6/spec.block-scoping.js b/src/babel/transformation/transformers/es6/spec.block-scoping.js index 337757bc64..39e223efb5 100644 --- a/src/babel/transformation/transformers/es6/spec.block-scoping.js +++ b/src/babel/transformation/transformers/es6/spec.block-scoping.js @@ -1,5 +1,9 @@ import * as t from "../../../types"; +/** + * [Please add a description.] + */ + function buildAssert(node, file) { return t.callExpression( file.addHelper("temporal-assert-defined"), @@ -7,6 +11,10 @@ function buildAssert(node, file) { ); } +/** + * [Please add a description.] + */ + function references(node, scope, state) { var declared = state.letRefs[node.name]; if (!declared) return false; @@ -15,7 +23,16 @@ function references(node, scope, state) { return scope.getBindingIdentifier(node.name) === declared; } +/** + * [Please add a description.] + */ + var refVisitor = { + + /** + * [Please add a description.] + */ + ReferencedIdentifier(node, parent, scope, state) { if (t.isFor(parent) && parent.left === node) return; @@ -33,6 +50,10 @@ var refVisitor = { } }, + /** + * [Please add a description.] + */ + AssignmentExpression: { exit(node, parent, scope, state) { if (node._ignoreBlockScopingTDZ) return; @@ -62,7 +83,16 @@ export var metadata = { group: "builtin-advanced" }; +/** + * [Please add a description.] + */ + export var visitor = { + + /** + * [Please add a description.] + */ + "Program|Loop|BlockStatement": { exit(node, parent, scope, file) { var letRefs = node._letReferences; diff --git a/src/babel/transformation/transformers/es6/spec.symbols.js b/src/babel/transformation/transformers/es6/spec.symbols.js index 8b228cd588..455fc4ac7e 100644 --- a/src/babel/transformation/transformers/es6/spec.symbols.js +++ b/src/babel/transformation/transformers/es6/spec.symbols.js @@ -4,7 +4,16 @@ export var metadata = { optional: true }; +/** + * [Please add a description.] + */ + export var visitor = { + + /** + * [Please add a description.] + */ + UnaryExpression(node, parent, scope, file) { if (node._ignoreSpecSymbols) return; @@ -25,12 +34,20 @@ export var visitor = { } }, + /** + * [Please add a description.] + */ + BinaryExpression(node, parent, scope, file) { if (node.operator === "instanceof") { return t.callExpression(file.addHelper("instanceof"), [node.left, node.right]); } }, + /** + * [Please add a description.] + */ + "VariableDeclaration|FunctionDeclaration"(node) { if (node._generated) this.skip(); } diff --git a/src/babel/transformation/transformers/es6/spec.template-literals.js b/src/babel/transformation/transformers/es6/spec.template-literals.js index 33f10ffa87..0efa159969 100644 --- a/src/babel/transformation/transformers/es6/spec.template-literals.js +++ b/src/babel/transformation/transformers/es6/spec.template-literals.js @@ -5,7 +5,16 @@ export var metadata = { group: "builtin-pre" }; +/** + * [Please add a description.] + */ + export var visitor = { + + /** + * [Please add a description.] + */ + TemplateLiteral(node, parent) { if (t.isTaggedTemplateExpression(parent)) return; diff --git a/src/babel/transformation/transformers/es6/spread.js b/src/babel/transformation/transformers/es6/spread.js index 3d5c3a3663..c25a5c7e7c 100644 --- a/src/babel/transformation/transformers/es6/spread.js +++ b/src/babel/transformation/transformers/es6/spread.js @@ -1,5 +1,9 @@ import * as t from "../../../types"; +/** + * [Please add a description.] + */ + function getSpreadLiteral(spread, scope) { if (scope.hub.file.isLoose("es6.spread") && !t.isIdentifier(spread.argument, { name: "arguments" })) { return spread.argument; @@ -8,6 +12,10 @@ function getSpreadLiteral(spread, scope) { } } +/** + * [Please add a description.] + */ + function hasSpread(nodes) { for (var i = 0; i < nodes.length; i++) { if (t.isSpreadElement(nodes[i])) { @@ -17,6 +25,10 @@ function hasSpread(nodes) { return false; } +/** + * [Please add a description.] + */ + function build(props, scope) { var nodes = []; @@ -47,7 +59,16 @@ export var metadata = { group: "builtin-advanced" }; +/** + * [Please add a description.] + */ + export var visitor = { + + /** + * [Please add a description.] + */ + ArrayExpression(node, parent, scope) { var elements = node.elements; if (!hasSpread(elements)) return; @@ -63,6 +84,10 @@ export var visitor = { return t.callExpression(t.memberExpression(first, t.identifier("concat")), nodes); }, + /** + * [Please add a description.] + */ + CallExpression(node, parent, scope) { var args = node.arguments; if (!hasSpread(args)) return; @@ -103,6 +128,10 @@ export var visitor = { node.arguments.unshift(contextLiteral); }, + /** + * [Please add a description.] + */ + NewExpression(node, parent, scope, file) { var args = node.arguments; if (!hasSpread(args)) return; diff --git a/src/babel/transformation/transformers/es6/tail-call.js b/src/babel/transformation/transformers/es6/tail-call.js index 15738db793..7a4ae6c37d 100644 --- a/src/babel/transformation/transformers/es6/tail-call.js +++ b/src/babel/transformation/transformers/es6/tail-call.js @@ -9,7 +9,16 @@ export var metadata = { group: "builtin-trailing" }; +/** + * [Please add a description.] + */ + export var visitor = { + + /** + * [Please add a description.] + */ + Function(node, parent, scope, file) { if (node.generator || node.async) return; var tailCall = new TailCallTransformer(this, scope, file); @@ -17,11 +26,24 @@ export var visitor = { } }; +/** + * [Please add a description.] + */ + function returnBlock(expr) { return t.blockStatement([t.returnStatement(expr)]); } +/** + * [Please add a description.] + */ + var visitor = { + + /** + * [Please add a description.] + */ + enter(node, parent) { if (t.isTryStatement(parent)) { if (node === parent.block) { @@ -32,18 +54,34 @@ var visitor = { } }, + /** + * [Please add a description.] + */ + ReturnStatement(node, parent, scope, state) { return state.subTransform(node.argument); }, + /** + * [Please add a description.] + */ + Function() { this.skip(); }, + /** + * [Please add a description.] + */ + VariableDeclaration(node, parent, scope, state) { state.vars.push(node); }, + /** + * [Please add a description.] + */ + ThisExpression(node, parent, scope, state) { if (!state.isShadowed) { state.needsThis = true; @@ -51,6 +89,10 @@ var visitor = { } }, + /** + * [Please add a description.] + */ + ReferencedIdentifier(node, parent, scope, state) { if (node.name === "arguments" && (!state.isShadowed || node._shadowedFunctionLiteral)) { state.needsArguments = true; @@ -59,6 +101,10 @@ var visitor = { } }; +/** + * [Please add a description.] + */ + class TailCallTransformer { constructor(path, scope, file) { this.hasTailRecursion = false; @@ -80,26 +126,50 @@ class TailCallTransformer { this.node = path.node; } + /** + * [Please add a description.] + */ + getArgumentsId() { return this.argumentsId = this.argumentsId || this.scope.generateUidIdentifier("arguments"); } + /** + * [Please add a description.] + */ + getThisId() { return this.thisId = this.thisId || this.scope.generateUidIdentifier("this"); } + /** + * [Please add a description.] + */ + getLeftId() { return this.leftId = this.leftId || this.scope.generateUidIdentifier("left"); } + /** + * [Please add a description.] + */ + getFunctionId() { return this.functionId = this.functionId || this.scope.generateUidIdentifier("function"); } + /** + * [Please add a description.] + */ + getAgainId() { return this.againId = this.againId || this.scope.generateUidIdentifier("again"); } + /** + * [Please add a description.] + */ + getParams() { var params = this.params; @@ -121,6 +191,10 @@ class TailCallTransformer { return this.params = params; } + /** + * [Please add a description.] + */ + hasDeopt() { // check if the ownerId has been reassigned, if it has then it's not safe to // perform optimisations @@ -128,6 +202,10 @@ class TailCallTransformer { return ownerIdInfo && !ownerIdInfo.constant; } + /** + * [Please add a description.] + */ + run() { var node = this.node; @@ -226,6 +304,10 @@ class TailCallTransformer { } } + /** + * [Please add a description.] + */ + subTransform(node) { if (!node) return; @@ -233,6 +315,10 @@ class TailCallTransformer { if (handler) return handler.call(this, node); } + /** + * [Please add a description.] + */ + subTransformConditionalExpression(node) { var callConsequent = this.subTransform(node.consequent); var callAlternate = this.subTransform(node.alternate); @@ -253,6 +339,10 @@ class TailCallTransformer { return [node]; } + /** + * [Please add a description.] + */ + subTransformLogicalExpression(node) { // only call in right-value of can be optimized var callRight = this.subTransform(node.right); @@ -273,6 +363,10 @@ class TailCallTransformer { return [t.ifStatement(testExpr, returnBlock(leftId))].concat(callRight); } + /** + * [Please add a description.] + */ + subTransformSequenceExpression(node) { var seq = node.expressions; @@ -291,6 +385,10 @@ class TailCallTransformer { return [t.expressionStatement(node)].concat(lastCall); } + /** + * [Please add a description.] + */ + subTransformCallExpression(node) { var callee = node.callee; var thisBinding, args; diff --git a/src/babel/transformation/transformers/es6/template-literals.js b/src/babel/transformation/transformers/es6/template-literals.js index 73ae1e88e4..83f35c5e89 100644 --- a/src/babel/transformation/transformers/es6/template-literals.js +++ b/src/babel/transformation/transformers/es6/template-literals.js @@ -6,16 +6,28 @@ export var metadata = { group: "builtin-pre" }; +/** + * [Please add a description.] + */ + function isString(node) { return t.isLiteral(node) && typeof node.value === "string"; } +/** + * [Please add a description.] + */ + function buildBinaryExpression(left, right) { var node = t.binaryExpression("+", left, right); node._templateLiteralProduced = true; return node; } +/** + * [Please add a description.] + */ + function crawl(path) { if (path.is("_templateLiteralProduced")) { crawl(path.get("left")); @@ -25,7 +37,16 @@ function crawl(path) { } } +/** + * [Please add a description.] + */ + export var visitor = { + + /** + * [Please add a description.] + */ + TaggedTemplateExpression(node, parent, scope, file) { var quasi = node.quasi; var args = []; @@ -50,6 +71,10 @@ export var visitor = { return t.callExpression(node.tag, args); }, + /** + * [Please add a description.] + */ + TemplateLiteral(node, parent, scope, file) { var nodes = []; diff --git a/src/babel/transformation/transformers/es7/comprehensions.js b/src/babel/transformation/transformers/es7/comprehensions.js index 4807341c1a..4df043d0ad 100644 --- a/src/babel/transformation/transformers/es7/comprehensions.js +++ b/src/babel/transformation/transformers/es7/comprehensions.js @@ -7,7 +7,16 @@ export var metadata = { stage: 0 }; +/** + * [Please add a description.] + */ + export var visitor = { + + /** + * [Please add a description.] + */ + ComprehensionExpression(node, parent, scope) { var callback = array; if (node.generator) callback = generator; @@ -15,6 +24,10 @@ export var visitor = { } }; +/** + * [Please add a description.] + */ + function generator(node) { var body = []; var container = t.functionExpression(null, [], t.blockStatement(body), true); @@ -27,6 +40,10 @@ function generator(node) { return t.callExpression(container, []); } +/** + * [Please add a description.] + */ + function array(node, parent, scope) { var uid = scope.generateUidIdentifierBasedOnNode(parent); diff --git a/src/babel/transformation/transformers/es7/decorators.js b/src/babel/transformation/transformers/es7/decorators.js index 2e56c01e32..4d968d83f3 100644 --- a/src/babel/transformation/transformers/es7/decorators.js +++ b/src/babel/transformation/transformers/es7/decorators.js @@ -8,7 +8,16 @@ export var metadata = { stage: 1 }; +/** + * [Please add a description.] + */ + export var visitor = { + + /** + * [Please add a description.] + */ + ObjectExpression(node, parent, scope, file) { var hasDecorators = false; for (let i = 0; i < node.properties.length; i++) { diff --git a/src/babel/transformation/transformers/es7/do-expressions.js b/src/babel/transformation/transformers/es7/do-expressions.js index 7f0fae85b7..823389ae0e 100644 --- a/src/babel/transformation/transformers/es7/do-expressions.js +++ b/src/babel/transformation/transformers/es7/do-expressions.js @@ -5,7 +5,16 @@ export var metadata = { stage: 0 }; +/** + * [Please add a description.] + */ + export var visitor = { + + /** + * [Please add a description.] + */ + DoExpression(node) { var body = node.body.body; if (body.length) { diff --git a/src/babel/transformation/transformers/es7/exponentiation-operator.js b/src/babel/transformation/transformers/es7/exponentiation-operator.js index 1f1ad5d62c..1ed8c62402 100644 --- a/src/babel/transformation/transformers/es7/exponentiation-operator.js +++ b/src/babel/transformation/transformers/es7/exponentiation-operator.js @@ -9,9 +9,17 @@ export var metadata = { var MATH_POW = t.memberExpression(t.identifier("Math"), t.identifier("pow")); +/** + * [Please add a description.] + */ + export var visitor = build({ operator: "**", + /** + * [Please add a description.] + */ + build(left, right) { return t.callExpression(MATH_POW, [left, right]); } diff --git a/src/babel/transformation/transformers/es7/export-extensions.js b/src/babel/transformation/transformers/es7/export-extensions.js index 204aaad140..3397ce1708 100644 --- a/src/babel/transformation/transformers/es7/export-extensions.js +++ b/src/babel/transformation/transformers/es7/export-extensions.js @@ -6,6 +6,10 @@ export var metadata = { stage: 1 }; +/** + * [Please add a description.] + */ + function build(node, nodes, scope) { var first = node.specifiers[0]; if (!t.isExportNamespaceSpecifier(first) && !t.isExportDefaultSpecifier(first)) return; @@ -26,7 +30,16 @@ function build(node, nodes, scope) { build(node, nodes, scope); } +/** + * [Please add a description.] + */ + export var visitor = { + + /** + * [Please add a description.] + */ + ExportNamedDeclaration(node, parent, scope) { var nodes = []; build(node, nodes, scope); diff --git a/src/babel/transformation/transformers/es7/function-bind.js b/src/babel/transformation/transformers/es7/function-bind.js index 8c7729e03f..0c10e17a02 100644 --- a/src/babel/transformation/transformers/es7/function-bind.js +++ b/src/babel/transformation/transformers/es7/function-bind.js @@ -7,6 +7,10 @@ export var metadata = { stage: 0 }; +/** + * [Please add a description.] + */ + function getTempId(scope) { var id = scope.path.getData("functionBind"); if (id) return id; @@ -15,11 +19,19 @@ function getTempId(scope) { return scope.path.setData("functionBind", id); } +/** + * [Please add a description.] + */ + function getStaticContext(bind, scope) { var object = bind.object || bind.callee.object; return scope.isStatic(object) && object; } +/** + * [Please add a description.] + */ + function inferBindContext(bind, scope) { var staticContext = getStaticContext(bind, scope); if (staticContext) return staticContext; @@ -36,7 +48,16 @@ function inferBindContext(bind, scope) { return tempId; } +/** + * [Please add a description.] + */ + export var visitor = { + + /** + * [Please add a description.] + */ + CallExpression(node, parent, scope) { var bind = node.callee; if (!t.isBindExpression(bind)) return; @@ -46,6 +67,10 @@ export var visitor = { node.arguments.unshift(context); }, + /** + * [Please add a description.] + */ + BindExpression(node, parent, scope) { var context = inferBindContext(node, scope); return t.callExpression(t.memberExpression(node.callee, t.identifier("bind")), [context]); diff --git a/src/babel/transformation/transformers/es7/object-rest-spread.js b/src/babel/transformation/transformers/es7/object-rest-spread.js index 07e8f6d4b1..d663b9efd9 100644 --- a/src/babel/transformation/transformers/es7/object-rest-spread.js +++ b/src/babel/transformation/transformers/es7/object-rest-spread.js @@ -7,6 +7,10 @@ export var metadata = { dependencies: ["es6.destructuring"] }; +/** + * [Please add a description.] + */ + var hasSpread = function (node) { for (var i = 0; i < node.properties.length; i++) { if (t.isSpreadProperty(node.properties[i])) { @@ -16,7 +20,16 @@ var hasSpread = function (node) { return false; }; +/** + * [Please add a description.] + */ + export var visitor = { + + /** + * [Please add a description.] + */ + ObjectExpression(node, parent, scope, file) { if (!hasSpread(node)) return; diff --git a/src/babel/transformation/transformers/filters.js b/src/babel/transformation/transformers/filters.js index 8218965441..6966f3b685 100644 --- a/src/babel/transformation/transformers/filters.js +++ b/src/babel/transformation/transformers/filters.js @@ -1,24 +1,44 @@ import includes from "lodash/collection/includes"; +/** + * [Please add a description.] + */ + export function internal(transformer, opts) { if (transformer.key[0] === "_") return true; } +/** + * [Please add a description.] + */ + export function blacklist(transformer, opts) { var blacklist = opts.blacklist; if (blacklist.length && includes(blacklist, transformer.key)) return false; } +/** + * [Please add a description.] + */ + export function whitelist(transformer, opts) { var whitelist = opts.whitelist; if (whitelist) return includes(whitelist, transformer.key); } +/** + * [Please add a description.] + */ + export function stage(transformer, opts) { var stage = transformer.metadata.stage; if (stage != null && stage >= opts.stage) return true; } +/** + * [Please add a description.] + */ + export function optional(transformer, opts) { if (transformer.metadata.optional && !includes(opts.optional, transformer.key)) return false; } diff --git a/src/babel/transformation/transformers/internal/block-hoist.js b/src/babel/transformation/transformers/internal/block-hoist.js index 9c3802fa8b..ef611fe7fd 100644 --- a/src/babel/transformation/transformers/internal/block-hoist.js +++ b/src/babel/transformation/transformers/internal/block-hoist.js @@ -4,14 +4,23 @@ export var metadata = { group: "builtin-trailing" }; -// Priority: -// -// - 0 We want this to be at the **very** bottom -// - 1 Default node position -// - 2 Priority over normal nodes -// - 3 We want this to be at the **very** top +/** + * [Please add a description.] + * + * Priority: + * + * - 0 We want this to be at the **very** bottom + * - 1 Default node position + * - 2 Priority over normal nodes + * - 3 We want this to be at the **very** top + */ export var visitor = { + + /** + * [Please add a description.] + */ + Block: { exit(node) { var hasChange = false; diff --git a/src/babel/transformation/transformers/internal/explode.js b/src/babel/transformation/transformers/internal/explode.js index 4bb6040a5d..a75d632a2f 100644 --- a/src/babel/transformation/transformers/internal/explode.js +++ b/src/babel/transformation/transformers/internal/explode.js @@ -5,6 +5,10 @@ export var metadata = { group: "builtin-pre" }; +/** + * [Please add a description.] + */ + function buildClone(bindingKey, refKey, check?) { return function (node) { if (node[bindingKey] === node[refKey] || (check && check(node))) { @@ -13,6 +17,10 @@ function buildClone(bindingKey, refKey, check?) { }; } +/** + * [Please add a description.] + */ + function buildListClone(listKey, bindingKey, refKey) { var clone = buildClone(bindingKey, refKey); @@ -25,10 +33,24 @@ function buildListClone(listKey, bindingKey, refKey) { }; } +/** + * [Please add a description.] + */ + export var visitor = { + + /** + * [Please add a description.] + */ + Property: buildClone("value", "key", function (node) { return t.isAssignmentPattern(node.value) && node.value.left === node.key; }), + + /** + * [Please add a description.] + */ + ExportDeclaration: buildListClone("specifiers", "local", "exported"), ImportDeclaration: buildListClone("specifiers", "local", "imported") }; diff --git a/src/babel/transformation/transformers/internal/hoist-directives.js b/src/babel/transformation/transformers/internal/hoist-directives.js index 4a5cdaa23f..c0ab685782 100644 --- a/src/babel/transformation/transformers/internal/hoist-directives.js +++ b/src/babel/transformation/transformers/internal/hoist-directives.js @@ -4,7 +4,16 @@ export var metadata = { group: "builtin-pre" }; +/** + * [Please add a description.] + */ + export var visitor = { + + /** + * [Please add a description.] + */ + Block: { exit(node) { for (var i = 0; i < node.body.length; i++) { diff --git a/src/babel/transformation/transformers/internal/module-formatter.js b/src/babel/transformation/transformers/internal/module-formatter.js index d767376582..27b34ac17c 100644 --- a/src/babel/transformation/transformers/internal/module-formatter.js +++ b/src/babel/transformation/transformers/internal/module-formatter.js @@ -2,7 +2,16 @@ export var metadata = { group: "builtin-modules" }; +/** + * [Please add a description.] + */ + export var visitor = { + + /** + * [Please add a description.] + */ + Program: { exit(program, parent, scope, file) { // ensure that these are at the top, just like normal imports diff --git a/src/babel/transformation/transformers/internal/modules.js b/src/babel/transformation/transformers/internal/modules.js index bcaaff3f1a..885fe6dcbb 100644 --- a/src/babel/transformation/transformers/internal/modules.js +++ b/src/babel/transformation/transformers/internal/modules.js @@ -7,6 +7,10 @@ import clone from "lodash/lang/clone"; import * as t from "../../../types"; +/** + * [Please add a description.] + */ + function getDeclar(node) { var declar = node.declaration; t.inheritsComments(declar, node); @@ -15,6 +19,10 @@ function getDeclar(node) { return declar; } +/** + * [Please add a description.] + */ + function buildExportSpecifier(id) { return t.exportSpecifier(clone(id), clone(id)); } @@ -23,7 +31,16 @@ export var metadata = { group: "builtin-pre" }; +/** + * [Please add a description.] + */ + export var visitor = { + + /** + * [Please add a description.] + */ + ExportDefaultDeclaration(node, parent, scope) { var declar = node.declaration; @@ -52,6 +69,10 @@ export var visitor = { } }, + /** + * [Please add a description.] + */ + ExportNamedDeclaration(node) { var declar = node.declaration; @@ -81,6 +102,10 @@ export var visitor = { } }, + /** + * [Please add a description.] + */ + Program: { enter(node) { var imports = []; diff --git a/src/babel/transformation/transformers/internal/shadow-functions.js b/src/babel/transformation/transformers/internal/shadow-functions.js index 0f401af035..207315462c 100644 --- a/src/babel/transformation/transformers/internal/shadow-functions.js +++ b/src/babel/transformation/transformers/internal/shadow-functions.js @@ -4,6 +4,10 @@ export var metadata = { group: "builtin-trailing" }; +/** + * [Please add a description.] + */ + function remap(path, key, create) { // ensure that we're shadowed var shadowPath = path.inShadow(); @@ -46,11 +50,24 @@ function remap(path, key, create) { return id; } +/** + * [Please add a description.] + */ + export var visitor = { + + /** + * [Please add a description.] + */ + ThisExpression() { return remap(this, "this", () => t.thisExpression()); }, + /** + * [Please add a description.] + */ + ReferencedIdentifier(node) { if (node.name === "arguments") { return remap(this, "arguments", () => t.identifier("arguments")); diff --git a/src/babel/transformation/transformers/internal/validation.js b/src/babel/transformation/transformers/internal/validation.js index 7e858c0c5e..c3279c48ec 100644 --- a/src/babel/transformation/transformers/internal/validation.js +++ b/src/babel/transformation/transformers/internal/validation.js @@ -5,7 +5,16 @@ export var metadata = { group: "builtin-pre" }; +/** + * [Please add a description.] + */ + export var visitor = { + + /** + * [Please add a description.] + */ + ForXStatement(node, parent, scope, file) { var left = node.left; if (t.isVariableDeclaration(left)) { @@ -14,6 +23,10 @@ export var visitor = { } }, + /** + * [Please add a description.] + */ + Property(node, parent, scope, file) { if (node.kind === "set") { var first = node.value.params[0]; diff --git a/src/babel/transformation/transformers/optimisation/flow.for-of.js b/src/babel/transformation/transformers/optimisation/flow.for-of.js index b5eeba6c62..d19e61800f 100644 --- a/src/babel/transformation/transformers/optimisation/flow.for-of.js +++ b/src/babel/transformation/transformers/optimisation/flow.for-of.js @@ -4,7 +4,16 @@ export var metadata = { optional: true }; +/** + * [Please add a description.] + */ + export var visitor = { + + /** + * [Please add a description.] + */ + ForOfStatement(node, parent, scope, file) { if (this.get("right").isGenericType("Array")) { return _ForOfStatementArray.call(this, node, scope, file); diff --git a/src/babel/transformation/transformers/optimisation/react.inline-elements.js b/src/babel/transformation/transformers/optimisation/react.inline-elements.js index eacf2c41d5..8c7c182ed4 100644 --- a/src/babel/transformation/transformers/optimisation/react.inline-elements.js +++ b/src/babel/transformation/transformers/optimisation/react.inline-elements.js @@ -5,6 +5,10 @@ export var metadata = { optional: true }; +/** + * [Please add a description.] + */ + function hasRefOrSpread(attrs) { for (var i = 0; i < attrs.length; i++) { var attr = attrs[i]; @@ -14,11 +18,23 @@ function hasRefOrSpread(attrs) { return false; } +/** + * [Please add a description.] + */ + function isJSXAttributeOfName(attr, name) { return t.isJSXAttribute(attr) && t.isJSXIdentifier(attr.name, { name: name }); } +/** + * [Please add a description.] + */ export var visitor = { + + /** + * [Please add a description.] + */ + JSXElement(node, parent, scope, file) { // filter var open = node.openingElement; diff --git a/src/babel/transformation/transformers/other/async-to-generator.js b/src/babel/transformation/transformers/other/async-to-generator.js index 844bfd0691..f00724319c 100644 --- a/src/babel/transformation/transformers/other/async-to-generator.js +++ b/src/babel/transformation/transformers/other/async-to-generator.js @@ -7,7 +7,16 @@ export var metadata = { dependencies: ["es7.asyncFunctions", "es6.classes"] }; +/** + * [Please add a description.] + */ + export var visitor = { + + /** + * [Please add a description.] + */ + Function(node, parent, scope, file) { if (!node.async || node.generator) return; diff --git a/src/babel/transformation/transformers/other/bluebird-coroutines.js b/src/babel/transformation/transformers/other/bluebird-coroutines.js index 0feae5c2fb..686d8f7c4f 100644 --- a/src/babel/transformation/transformers/other/bluebird-coroutines.js +++ b/src/babel/transformation/transformers/other/bluebird-coroutines.js @@ -1,6 +1,10 @@ import remapAsyncToGenerator from "../../helpers/remap-async-to-generator"; import * as t from "../../../types"; +/** + * [Please add a description.] + */ + export function manipulateOptions(opts) { opts.blacklist.push("regenerator"); } @@ -10,7 +14,16 @@ export var metadata = { dependencies: ["es7.asyncFunctions", "es6.classes"] }; +/** + * [Please add a description.] + */ + export var visitor = { + + /** + * [Please add a description.] + */ + Function(node, parent, scope, file) { if (!node.async || node.generator) return; diff --git a/src/babel/transformation/transformers/other/flow.js b/src/babel/transformation/transformers/other/flow.js index d8806dfecf..0cd45bbb54 100644 --- a/src/babel/transformation/transformers/other/flow.js +++ b/src/babel/transformation/transformers/other/flow.js @@ -4,7 +4,16 @@ export var metadata = { group: "builtin-trailing" }; +/** + * [Please add a description.] + */ + export var visitor = { + + /** + * [Please add a description.] + */ + Program(node, parent, scope, file) { for (var comment of (file.ast.comments: Array)) { if (comment.value.indexOf("@flow") >= 0) { @@ -13,19 +22,35 @@ export var visitor = { } }, + /** + * [Please add a description.] + */ + Flow() { this.dangerouslyRemove(); }, + /** + * [Please add a description.] + */ + ClassProperty(node) { node.typeAnnotation = null; if (!node.value) this.dangerouslyRemove(); }, + /** + * [Please add a description.] + */ + Class(node) { node.implements = null; }, + /** + * [Please add a description.] + */ + Function(node) { for (var i = 0; i < node.params.length; i++) { var param = node.params[i]; @@ -33,6 +58,10 @@ export var visitor = { } }, + /** + * [Please add a description.] + */ + TypeCastExpression(node) { do { node = node.expression; @@ -40,10 +69,18 @@ export var visitor = { return node; }, + /** + * [Please add a description.] + */ + ImportDeclaration(node) { if (node.importKind === "type" || node.importKind === "typeof") this.dangerouslyRemove(); }, + /** + * [Please add a description.] + */ + ExportDeclaration() { if (this.get("declaration").isTypeAlias()) this.dangerouslyRemove(); } diff --git a/src/babel/transformation/transformers/other/react-compat.js b/src/babel/transformation/transformers/other/react-compat.js index e7068a7fb6..f0d3442585 100644 --- a/src/babel/transformation/transformers/other/react-compat.js +++ b/src/babel/transformation/transformers/other/react-compat.js @@ -1,6 +1,10 @@ import * as react from "../../helpers/react"; import * as t from "../../../types"; +/** + * [Please add a description.] + */ + export function manipulateOptions(opts) { opts.blacklist.push("react"); } @@ -10,11 +14,24 @@ export var metadata = { group: "builtin-advanced" }; +/** + * [Please add a description.] + */ + export var visitor = require("../../helpers/build-react-transformer")({ + + /** + * [Please add a description.] + */ + pre(state) { state.callee = state.tagExpr; }, + /** + * [Please add a description.] + */ + post(state) { if (react.isCompatTag(state.tagName)) { state.call = t.callExpression( diff --git a/src/babel/transformation/transformers/other/react.js b/src/babel/transformation/transformers/other/react.js index 4b48568395..8da3b76a45 100644 --- a/src/babel/transformation/transformers/other/react.js +++ b/src/babel/transformation/transformers/other/react.js @@ -1,13 +1,26 @@ import * as react from "../../helpers/react"; import * as t from "../../../types"; +/** + * [Please add a description.] + */ + var JSX_ANNOTATION_REGEX = /^\*\s*@jsx\s+([^\s]+)/; export var metadata = { group: "builtin-advanced" }; +/** + * [Please add a description.] + */ + export var visitor = require("../../helpers/build-react-transformer")({ + + /** + * [Please add a description.] + */ + pre(state) { var tagName = state.tagName; var args = state.args; @@ -18,11 +31,18 @@ export var visitor = require("../../helpers/build-react-transformer")({ } }, + /** + * [Please add a description.] + */ + post(state, file) { state.callee = file.get("jsxIdentifier"); } }); +/** + * [Please add a description.] + */ visitor.Program = function (node, parent, scope, file) { var id = file.opts.jsxPragma; diff --git a/src/babel/transformation/transformers/other/regenerator.js b/src/babel/transformation/transformers/other/regenerator.js index dc5b8d4e24..7bd0a45cdb 100644 --- a/src/babel/transformation/transformers/other/regenerator.js +++ b/src/babel/transformation/transformers/other/regenerator.js @@ -11,7 +11,16 @@ export var metadata = { group: "builtin-advanced" }; +/** + * [Please add a description.] + */ + export var visitor = { + + /** + * [Please add a description.] + */ + Function: { exit(node) { if (node.async || node.generator) { diff --git a/src/babel/transformation/transformers/other/strict.js b/src/babel/transformation/transformers/other/strict.js index cf7347d619..79467ac27d 100644 --- a/src/babel/transformation/transformers/other/strict.js +++ b/src/babel/transformation/transformers/other/strict.js @@ -6,7 +6,16 @@ export var metadata = { const THIS_BREAK_KEYS = ["FunctionExpression", "FunctionDeclaration", "ClassExpression", "ClassDeclaration"]; +/** + * [Please add a description.] + */ + export var visitor = { + + /** + * [Please add a description.] + */ + Program: { enter(program) { var first = program.body[0]; @@ -26,6 +35,10 @@ export var visitor = { } }, + /** + * [Please add a description.] + */ + ThisExpression() { if (!this.findParent((path) => !path.is("shadow") && THIS_BREAK_KEYS.indexOf(path.type) >= 0)) { return t.identifier("undefined"); diff --git a/src/babel/transformation/transformers/spec/block-scoped-functions.js b/src/babel/transformation/transformers/spec/block-scoped-functions.js index a27a13a5a8..28241e22b1 100644 --- a/src/babel/transformation/transformers/spec/block-scoped-functions.js +++ b/src/babel/transformation/transformers/spec/block-scoped-functions.js @@ -1,5 +1,9 @@ import * as t from "../../../types"; +/** + * [Please add a description.] + */ + function statementList(key, path) { var paths = path.get(key); @@ -23,7 +27,16 @@ function statementList(key, path) { } } +/** + * [Please add a description.] + */ + export var visitor = { + + /** + * [Please add a description.] + */ + BlockStatement(node, parent) { if ((t.isFunction(parent) && parent.body === node) || t.isExportDeclaration(parent)) { return; @@ -32,6 +45,10 @@ export var visitor = { statementList("body", this); }, + /** + * [Please add a description.] + */ + SwitchCase() { statementList("consequent", this); } diff --git a/src/babel/transformation/transformers/spec/function-name.js b/src/babel/transformation/transformers/spec/function-name.js index 42dcaa21d0..423fe7c4eb 100644 --- a/src/babel/transformation/transformers/spec/function-name.js +++ b/src/babel/transformation/transformers/spec/function-name.js @@ -5,7 +5,17 @@ export var metadata = { }; // visit Property functions first - https://github.com/babel/babel/issues/1860 + +/** + * [Please add a description.] + */ + export var visitor = { + + /** + * [Please add a description.] + */ + "ArrowFunctionExpression|FunctionExpression": { exit() { if (!this.parentPath.isProperty()) { @@ -14,6 +24,10 @@ export var visitor = { } }, + /** + * [Please add a description.] + */ + ObjectExpression() { var props = this.get("properties"); for (var prop of (props: Array)) { diff --git a/src/babel/transformation/transformers/validation/react.js b/src/babel/transformation/transformers/validation/react.js index cefa71e64f..95e4af2e91 100644 --- a/src/babel/transformation/transformers/validation/react.js +++ b/src/babel/transformation/transformers/validation/react.js @@ -13,13 +13,26 @@ function check(source, file) { } } +/** + * [Please add a description.] + */ + export var visitor = { + + /** + * [Please add a description.] + */ + CallExpression(node, parent, scope, file) { if (this.get("callee").isIdentifier({ name: "require" }) && node.arguments.length === 1) { check(node.arguments[0], file); } }, + /** + * [Please add a description.] + */ + ModuleDeclaration(node, parent, scope, file) { check(node.source, file); } diff --git a/src/babel/traversal/README.md b/src/babel/traversal/README.md new file mode 100644 index 0000000000..69c1a8a4cd --- /dev/null +++ b/src/babel/traversal/README.md @@ -0,0 +1,3 @@ +## Traversal + +This is the Traversal directory. diff --git a/src/babel/traversal/context.js b/src/babel/traversal/context.js index 3706f1905c..d03335f138 100644 --- a/src/babel/traversal/context.js +++ b/src/babel/traversal/context.js @@ -1,6 +1,9 @@ import NodePath from "./path"; import * as t from "../types"; +/** + * [Please add a description.] + */ export default class TraversalContext { constructor(scope, opts, state, parentPath) { this.parentPath = parentPath; @@ -10,6 +13,9 @@ export default class TraversalContext { this.queue = null; } + /** + * [Please add a description.] + */ shouldVisit(node) { var opts = this.opts; if (opts.enter || opts.exit) return true; @@ -26,6 +32,9 @@ export default class TraversalContext { return false; } + /** + * [Please add a description.] + */ create(node, obj, key, listKey) { var path = NodePath.get({ parentPath: this.parentPath, @@ -38,6 +47,9 @@ export default class TraversalContext { return path; } + /** + * [Please add a description.] + */ visitMultiple(container, parent, listKey) { // nothing to traverse! if (container.length === 0) return false; @@ -77,6 +89,9 @@ export default class TraversalContext { return stop; } + /** + * [Please add a description.] + */ visitSingle(node, key) { if (this.shouldVisit(node[key])) { var path = this.create(node, node, key); @@ -85,6 +100,9 @@ export default class TraversalContext { } } + /** + * [Please add a description.] + */ visit(node, key) { var nodes = node[key]; if (!nodes) return; diff --git a/src/babel/traversal/hub.js b/src/babel/traversal/hub.js index 69f9406fc9..4eab4d299b 100644 --- a/src/babel/traversal/hub.js +++ b/src/babel/traversal/hub.js @@ -1,3 +1,7 @@ +/** + * [Please add a description.] + */ + export default class Hub { constructor(file) { this.file = file; diff --git a/src/babel/traversal/index.js b/src/babel/traversal/index.js index 58f854f0b9..ead8dce3ac 100644 --- a/src/babel/traversal/index.js +++ b/src/babel/traversal/index.js @@ -4,8 +4,13 @@ import * as messages from "../messages"; import includes from "lodash/collection/includes"; import * as t from "../types"; -export default function traverse(parent, opts, scope, state, parentPath) { +/** + * [Please add a description.] + */ + +export default function traverse(parent: Object, opts?: Object, scope?: Object, state: Object, parentPath: Object) { if (!parent) return; + if (!opts) opts = {}; if (!opts.noScope && !scope) { if (parent.type !== "Program" && parent.type !== "File") { @@ -13,8 +18,6 @@ export default function traverse(parent, opts, scope, state, parentPath) { } } - if (!opts) opts = {}; - visitors.explode(opts); // array of nodes @@ -31,7 +34,11 @@ traverse.visitors = visitors; traverse.verify = visitors.verify; traverse.explode = visitors.explode; -traverse.node = function (node, opts, scope, state, parentPath, skipKeys?) { +/** + * [Please add a description.] + */ + +traverse.node = function (node: Object, opts: Object, scope: Object, state: Object, parentPath: Object, skipKeys?) { var keys = t.VISITOR_KEYS[node.type]; if (!keys) return; @@ -42,39 +49,63 @@ traverse.node = function (node, opts, scope, state, parentPath, skipKeys?) { } }; +/** + * [Please add a description.] + */ + const CLEAR_KEYS = [ "trailingComments", "leadingComments", "extendedRange", "_scopeInfo", "_paths", "tokens", "range", "start", "end", "loc", "raw" ]; -traverse.clearNode = function (node) { +/** + * [Please add a description.] + */ + +traverse.clearNode = function (node: Object) { for (var i = 0; i < CLEAR_KEYS.length; i++) { let key = CLEAR_KEYS[i]; if (node[key] != null) node[key] = undefined; } }; +/** + * [Please add a description.] + */ + var clearVisitor = { noScope: true, exit: traverse.clearNode }; -traverse.removeProperties = function (tree) { +/** + * [Please add a description.] + */ + +traverse.removeProperties = function (tree: Object): Object { traverse(tree, clearVisitor); traverse.clearNode(tree); return tree; }; -function hasBlacklistedType(node, parent, scope, state) { +/** + * [Please add a description.] + */ + +function hasBlacklistedType(node: Object, parent: Object, scope: Object, state: Object) { if (node.type === state.type) { state.has = true; this.skip(); } } -traverse.hasType = function (tree, scope, type, blacklistTypes) { +/** + * [Please add a description.] + */ + +traverse.hasType = function (tree: Object, scope: Object, type: Object, blacklistTypes: Array): boolean { // the node we're searching in is blacklisted if (includes(blacklistTypes, tree.type)) return false; diff --git a/src/babel/traversal/path/README.md b/src/babel/traversal/path/README.md index d0d0a77af6..6459683030 100644 --- a/src/babel/traversal/path/README.md +++ b/src/babel/traversal/path/README.md @@ -1,3 +1,7 @@ +## Path Traversal + +This is the Path Traversal directory. + - `ancestry` - Methods that retrieve or validate anything related to the current paths ancestry. - `context` - Methods responsible for maintaing TraversalContexts. - `conversion` - Methods that convert the path node into another node or some other type of data. diff --git a/src/babel/traversal/path/ancestry.js b/src/babel/traversal/path/ancestry.js index 4a346ecb18..04285cd7b8 100644 --- a/src/babel/traversal/path/ancestry.js +++ b/src/babel/traversal/path/ancestry.js @@ -162,7 +162,7 @@ export function getAncestry() { } /** - * Description + * [Please add a description.] */ export function inType() { diff --git a/src/babel/traversal/path/comments.js b/src/babel/traversal/path/comments.js index 007040d5e1..dc7f0fcdaf 100644 --- a/src/babel/traversal/path/comments.js +++ b/src/babel/traversal/path/comments.js @@ -21,7 +21,7 @@ export function shareCommentsWithSiblings() { } /** - * Description + * [Please add a description.] */ export function addComment(type, content, line?) { diff --git a/src/babel/traversal/path/context.js b/src/babel/traversal/path/context.js index 64a68f66d5..66af435037 100644 --- a/src/babel/traversal/path/context.js +++ b/src/babel/traversal/path/context.js @@ -1,7 +1,7 @@ import traverse from "../index"; /** - * Description + * [Please add a description.] */ export function call(key) { @@ -39,7 +39,7 @@ export function call(key) { } /** - * Description + * [Please add a description.] */ export function isBlacklisted(): boolean { @@ -48,7 +48,7 @@ export function isBlacklisted(): boolean { } /** - * Description + * [Please add a description.] */ export function visit(): boolean { @@ -81,7 +81,7 @@ export function visit(): boolean { } /** - * Description + * [Please add a description.] */ export function skip() { @@ -89,7 +89,7 @@ export function skip() { } /** - * Description + * [Please add a description.] */ export function skipKey(key) { @@ -97,7 +97,7 @@ export function skipKey(key) { } /** - * Description + * [Please add a description.] */ export function stop() { @@ -106,7 +106,7 @@ export function stop() { } /** - * Description + * [Please add a description.] */ export function setScope() { @@ -118,7 +118,7 @@ export function setScope() { } /** - * Description + * [Please add a description.] */ export function setContext(context) { @@ -153,12 +153,20 @@ export function resync() { //this._resyncRemoved(); } +/** + * [Please add a description.] + */ + export function _resyncParent() { if (this.parentPath) { this.parent = this.parentPath.node; } } +/** + * [Please add a description.] + */ + export function _resyncKey() { if (!this.container) return; @@ -184,6 +192,10 @@ export function _resyncKey() { this.key = null; } +/** + * [Please add a description.] + */ + export function _resyncList() { var listKey = this.listKey; var parentPath = this.parentPath; @@ -201,6 +213,10 @@ export function _resyncList() { } } +/** + * [Please add a description.] + */ + export function _resyncRemoved() { if (this.key == null || !this.container || this.container[this.key] !== this.node) { this._markRemoved(); @@ -208,7 +224,7 @@ export function _resyncRemoved() { } /** - * Description + * [Please add a description.] */ export function shiftContext() { @@ -217,7 +233,7 @@ export function shiftContext() { } /** - * Description + * [Please add a description.] */ export function unshiftContext(context) { @@ -226,7 +242,7 @@ export function unshiftContext(context) { } /** - * Description + * [Please add a description.] */ export function setup(parentPath, container, listKey, key) { @@ -240,7 +256,7 @@ export function setup(parentPath, container, listKey, key) { } /** - * Description + * [Please add a description.] */ export function setKey(key) { @@ -250,7 +266,7 @@ export function setKey(key) { } /** - * Description + * [Please add a description.] */ export function queueNode(path) { diff --git a/src/babel/traversal/path/conversion.js b/src/babel/traversal/path/conversion.js index f13f78470e..d7444aa224 100644 --- a/src/babel/traversal/path/conversion.js +++ b/src/babel/traversal/path/conversion.js @@ -1,7 +1,7 @@ import * as t from "../../types"; /** - * Description + * [Please add a description.] */ export function toComputedKey(): Object { @@ -24,7 +24,7 @@ export function toComputedKey(): Object { } /** - * Description + * [Please add a description.] */ export function ensureBlock() { diff --git a/src/babel/traversal/path/family.js b/src/babel/traversal/path/family.js index 5be72686aa..f5bf682aef 100644 --- a/src/babel/traversal/path/family.js +++ b/src/babel/traversal/path/family.js @@ -3,7 +3,7 @@ import NodePath from "./index"; import * as t from "../../types"; /** - * Description + * [Please add a description.] */ export function getStatementParent(): ?NodePath { @@ -25,7 +25,7 @@ export function getStatementParent(): ?NodePath { } /** - * Description + * [Please add a description.] */ export function getOpposite() { @@ -37,7 +37,7 @@ export function getOpposite() { } /** - * Description + * [Please add a description.] */ export function getCompletionRecords(): Array { @@ -64,7 +64,7 @@ export function getCompletionRecords(): Array { } /** - * Description + * [Please add a description.] */ export function getSibling(key) { @@ -78,7 +78,7 @@ export function getSibling(key) { } /** - * Description + * [Please add a description.] */ export function get(key: string, context?: boolean | TraversalContext): NodePath { @@ -92,7 +92,7 @@ export function get(key: string, context?: boolean | TraversalContext): NodePath } /** - * Description + * [Please add a description.] */ export function _getKey(key, context?) { @@ -121,7 +121,7 @@ export function _getKey(key, context?) { } /** - * Description + * [Please add a description.] */ export function _getPattern(parts, context) { @@ -141,7 +141,7 @@ export function _getPattern(parts, context) { } /** - * Description + * [Please add a description.] */ export function getBindingIdentifiers(duplicates?) { diff --git a/src/babel/traversal/path/index.js b/src/babel/traversal/path/index.js index 28b53814da..9b3f2fb541 100644 --- a/src/babel/traversal/path/index.js +++ b/src/babel/traversal/path/index.js @@ -4,7 +4,16 @@ import assign from "lodash/object/assign"; import Scope from "../scope"; import * as t from "../../types"; +/** + * [Please add a description.] + */ + export default class NodePath { + + /** + * [Please add a description.] + */ + constructor(hub, parent) { this.contexts = []; this.parent = parent; @@ -31,7 +40,7 @@ export default class NodePath { } /** - * Description + * [Please add a description.] */ static get({ hub, parentPath, parent, container, listKey, key }) { @@ -62,7 +71,7 @@ export default class NodePath { } /** - * Description + * [Please add a description.] */ getScope(scope: Scope) { @@ -77,7 +86,7 @@ export default class NodePath { } /** - * Description + * [Please add a description.] */ setData(key, val) { @@ -85,7 +94,7 @@ export default class NodePath { } /** - * Description + * [Please add a description.] */ getData(key, def) { @@ -95,7 +104,7 @@ export default class NodePath { } /** - * Description + * [Please add a description.] */ errorWithNode(msg, Error = SyntaxError) { @@ -103,7 +112,7 @@ export default class NodePath { } /** - * Description + * [Please add a description.] */ traverse(visitor, state) { @@ -111,6 +120,10 @@ export default class NodePath { } } +/** + * [Please add a description.] + */ + assign(NodePath.prototype, require("./ancestry")); assign(NodePath.prototype, require("./inference")); assign(NodePath.prototype, require("./replacement")); diff --git a/src/babel/traversal/path/inference/README.md b/src/babel/traversal/path/inference/README.md new file mode 100644 index 0000000000..be4c8173da --- /dev/null +++ b/src/babel/traversal/path/inference/README.md @@ -0,0 +1,3 @@ +## Inference + +This is the Inference directory. diff --git a/src/babel/traversal/path/inference/index.js b/src/babel/traversal/path/inference/index.js index 71224af9bf..b5d27426bc 100644 --- a/src/babel/traversal/path/inference/index.js +++ b/src/babel/traversal/path/inference/index.js @@ -59,13 +59,17 @@ export function _getTypeAnnotation(): ?Object { } /** - * Description + * [Please add a description.] */ export function isBaseType(baseName: string, soft?): boolean { return _isBaseType(baseName, this.getTypeAnnotation(), soft); } +/** + * [Please add a description.] + */ + function _isBaseType(baseName: string, type?, soft?): boolean { if (baseName === "string") { return t.isStringTypeAnnotation(type); @@ -89,7 +93,7 @@ function _isBaseType(baseName: string, type?, soft?): boolean { } /** - * Description + * [Please add a description.] */ export function couldBeBaseType(name: string): boolean { @@ -109,7 +113,7 @@ export function couldBeBaseType(name: string): boolean { } /** - * Description + * [Please add a description.] */ export function baseTypeStrictlyMatches(right: NodePath) { @@ -122,7 +126,7 @@ export function baseTypeStrictlyMatches(right: NodePath) { } /** - * Description + * [Please add a description.] */ export function isGenericType(genericName: string): boolean { diff --git a/src/babel/traversal/path/inference/inferer-reference.js b/src/babel/traversal/path/inference/inferer-reference.js index c08b73e5d2..9fd4e1deae 100644 --- a/src/babel/traversal/path/inference/inferer-reference.js +++ b/src/babel/traversal/path/inference/inferer-reference.js @@ -1,5 +1,9 @@ import * as t from "../../../types"; +/** + * [Please add a description.] + */ + export default function (node) { if (!this.isReferenced()) return; @@ -24,6 +28,10 @@ export default function (node) { } } +/** + * [Please add a description.] + */ + function getTypeAnnotationBindingConstantViolations(path, name) { var binding = path.scope.getBinding(name); @@ -77,6 +85,10 @@ function getTypeAnnotationBindingConstantViolations(path, name) { } } +/** + * [Please add a description.] + */ + function getConstantViolationsBefore(binding, path, functions) { var violations = binding.constantViolations.slice(); violations.unshift(binding.path); @@ -88,6 +100,10 @@ function getConstantViolationsBefore(binding, path, functions) { }); } +/** + * [Please add a description.] + */ + function inferAnnotationFromBinaryExpression(name, path) { var operator = path.node.operator; @@ -139,6 +155,10 @@ function inferAnnotationFromBinaryExpression(name, path) { return t.createTypeAnnotationBasedOnTypeof(typePath.node.value); } +/** + * [Please add a description.] + */ + function getParentConditionalPath(path) { var parentPath; while (parentPath = path.parentPath) { @@ -154,6 +174,10 @@ function getParentConditionalPath(path) { } } +/** + * [Please add a description.] + */ + function getConditionalAnnotation(path, name) { var ifStatement = getParentConditionalPath(path); if (!ifStatement) return; diff --git a/src/babel/traversal/path/inference/inferers.js b/src/babel/traversal/path/inference/inferers.js index c2c2c077ba..7f10704317 100644 --- a/src/babel/traversal/path/inference/inferers.js +++ b/src/babel/traversal/path/inference/inferers.js @@ -2,7 +2,9 @@ import * as t from "../../../types"; export { default as Identifier } from "./inferer-reference"; -// +/** + * [Please add a description.] + */ export function VariableDeclarator() { var id = this.get("id"); @@ -14,7 +16,9 @@ export function VariableDeclarator() { } } -// +/** + * [Please add a description.] + */ export function TypeCastExpression(node) { return node.typeAnnotation; @@ -22,7 +26,9 @@ export function TypeCastExpression(node) { TypeCastExpression.validParent = true; -// +/** + * [Please add a description.] + */ export function NewExpression(node) { if (this.get("callee").isIdentifier()) { @@ -31,13 +37,17 @@ export function NewExpression(node) { } } -// +/** + * [Please add a description.] + */ export function TemplateLiteral() { return t.stringTypeAnnotation(); } -// +/** + * [Please add a description.] + */ export function UnaryExpression(node) { let operator = node.operator; @@ -53,7 +63,9 @@ export function UnaryExpression(node) { } } -// +/** + * [Please add a description.] + */ export function BinaryExpression(node) { let operator = node.operator; @@ -82,7 +94,9 @@ export function BinaryExpression(node) { } } -// +/** + * [Please add a description.] + */ export function LogicalExpression() { return t.createUnionTypeAnnotation([ @@ -91,7 +105,9 @@ export function LogicalExpression() { ]); } -// +/** + * [Please add a description.] + */ export function ConditionalExpression() { return t.createUnionTypeAnnotation([ @@ -100,19 +116,25 @@ export function ConditionalExpression() { ]); } -// +/** + * [Please add a description.] + */ export function SequenceExpression(node) { return this.get("expressions").pop().getTypeAnnotation(); } -// +/** + * [Please add a description.] + */ export function AssignmentExpression(node) { return this.get("right").getTypeAnnotation(); } -// +/** + * [Please add a description.] + */ export function UpdateExpression(node) { let operator = node.operator; @@ -121,7 +143,9 @@ export function UpdateExpression(node) { } } -// +/** + * [Please add a description.] + */ export function Literal(node) { var value = node.value; @@ -132,19 +156,25 @@ export function Literal(node) { if (node.regex) return t.genericTypeAnnotation(t.identifier("RegExp")); } -// +/** + * [Please add a description.] + */ export function ObjectExpression() { return t.genericTypeAnnotation(t.identifier("Object")); } -// +/** + * [Please add a description.] + */ export function ArrayExpression() { return t.genericTypeAnnotation(t.identifier("Array")); } -// +/** + * [Please add a description.] + */ export function RestElement() { return ArrayExpression(); @@ -152,7 +182,9 @@ export function RestElement() { RestElement.validParent = true; -// +/** + * [Please add a description.] + */ function Func() { return t.genericTypeAnnotation(t.identifier("Function")); @@ -160,16 +192,26 @@ function Func() { export { Func as Function, Func as Class }; -// +/** + * [Please add a description.] + */ export function CallExpression() { return resolveCall(this.get("callee")); } +/** + * [Please add a description.] + */ + export function TaggedTemplateExpression() { return resolveCall(this.get("tag")); } +/** + * [Please add a description.] + */ + function resolveCall(callee) { callee = callee.resolve(); diff --git a/src/babel/traversal/path/introspection.js b/src/babel/traversal/path/introspection.js index b843e32564..804e06d9d1 100644 --- a/src/babel/traversal/path/introspection.js +++ b/src/babel/traversal/path/introspection.js @@ -211,7 +211,7 @@ export function getSource() { } /** - * Description + * [Please add a description.] */ export function willIMaybeExecuteBefore(target) { @@ -280,6 +280,10 @@ export function resolve(dangerous, resolved) { return this._resolve(dangerous, resolved) || this; } +/** + * [Please add a description.] + */ + export function _resolve(dangerous?, resolved?): ?NodePath { // detect infinite recursion // todo: possibly have a max length on this just to be safe diff --git a/src/babel/traversal/path/lib/hoister.js b/src/babel/traversal/path/lib/hoister.js index a4e606fd4f..5b3736a405 100644 --- a/src/babel/traversal/path/lib/hoister.js +++ b/src/babel/traversal/path/lib/hoister.js @@ -1,7 +1,16 @@ import * as react from "../../../transformation/helpers/react"; import * as t from "../../../types"; +/** + * [Please add a description.] + */ + var referenceVisitor = { + + /** + * [Please add a description.] + */ + ReferencedIdentifier(node, parent, scope, state) { if (this.isJSXIdentifier() && react.isCompatTag(node.name)) { return; @@ -25,6 +34,10 @@ var referenceVisitor = { } }; +/** + * [Please add a description.] + */ + export default class PathHoister { constructor(path, scope) { this.breakOnScopePaths = []; @@ -34,6 +47,10 @@ export default class PathHoister { this.path = path; } + /** + * [Please add a description.] + */ + isCompatibleScope(scope) { for (var key in this.bindings) { var binding = this.bindings[key]; @@ -45,6 +62,10 @@ export default class PathHoister { return true; } + /** + * [Please add a description.] + */ + getCompatibleScopes() { var scope = this.path.scope; do { @@ -60,6 +81,10 @@ export default class PathHoister { } while(scope = scope.parent); } + /** + * [Please add a description.] + */ + getAttachmentPath() { var scopes = this.scopes; @@ -82,11 +107,19 @@ export default class PathHoister { } } + /** + * [Please add a description.] + */ + getNextScopeStatementParent() { var scope = this.scopes.pop(); if (scope) return scope.path.getStatementParent(); } + /** + * [Please add a description.] + */ + hasOwnParamBindings(scope) { for (var name in this.bindings) { if (!scope.hasOwnBinding(name)) continue; @@ -97,6 +130,10 @@ export default class PathHoister { return false; } + /** + * [Please add a description.] + */ + run() { var node = this.path.node; if (node._hoisted) return; diff --git a/src/babel/traversal/path/lib/removal-hooks.js b/src/babel/traversal/path/lib/removal-hooks.js index 2da9519ea7..75e01de83c 100644 --- a/src/babel/traversal/path/lib/removal-hooks.js +++ b/src/babel/traversal/path/lib/removal-hooks.js @@ -2,8 +2,16 @@ import * as t from "../../../types"; -// pre hooks should be used for either rejecting removal or delegating removal +/** + * Pre hooks should be used for either rejecting removal or delegating removal + */ + export var pre = [ + + /** + * [Please add a description.] + */ + function (self) { if (self.key === "body" && (self.isBlockStatement() || self.isClassBody())) { // function () NODE @@ -15,6 +23,10 @@ export var pre = [ } }, + /** + * [Please add a description.] + */ + function (self, parent) { var replace = false; @@ -33,8 +45,16 @@ export var pre = [ } ]; -// post hooks should be used for cleaning up parents +/** + * Post hooks should be used for cleaning up parents + */ + export var post = [ + + /** + * [Please add a description.] + */ + function (self, parent) { var removeParent = false; @@ -70,6 +90,10 @@ export var post = [ } }, + /** + * [Please add a description.] + */ + function (self, parent) { if (parent.isSequenceExpression() && parent.node.expressions.length === 1) { // (node, NODE); @@ -80,6 +104,10 @@ export var post = [ } }, + /** + * [Please add a description.] + */ + function (self, parent) { if (parent.isBinary()) { // left + NODE; diff --git a/src/babel/traversal/path/lib/virtual-types.js b/src/babel/traversal/path/lib/virtual-types.js index 4a0a9456e0..98e45b4091 100644 --- a/src/babel/traversal/path/lib/virtual-types.js +++ b/src/babel/traversal/path/lib/virtual-types.js @@ -1,6 +1,10 @@ import * as react from "../../../transformation/helpers/react"; import * as t from "../../../types"; +/** + * [Please add a description.] + */ + export var ReferencedIdentifier = { types: ["Identifier", "JSXIdentifier"], checkPath({ node, parent }, opts) { @@ -18,6 +22,10 @@ export var ReferencedIdentifier = { } }; +/** + * [Please add a description.] + */ + export var BindingIdentifier = { types: ["Identifier"], checkPath({ node, parent }) { @@ -25,6 +33,10 @@ export var BindingIdentifier = { } }; +/** + * [Please add a description.] + */ + export var Statement = { types: ["Statement"], checkPath({ node, parent }) { @@ -41,6 +53,10 @@ export var Statement = { } }; +/** + * [Please add a description.] + */ + export var Expression = { types: ["Expression"], checkPath(path) { @@ -52,6 +68,10 @@ export var Expression = { } }; +/** + * [Please add a description.] + */ + export var Scope = { types: ["Scopable"], checkPath(path) { @@ -59,18 +79,30 @@ export var Scope = { } }; +/** + * [Please add a description.] + */ + export var Referenced = { checkPath(path) { return t.isReferenced(path.node, path.parent); } }; +/** + * [Please add a description.] + */ + export var BlockScoped = { checkPath(path) { return t.isBlockScoped(path.node); } }; +/** + * [Please add a description.] + */ + export var Var = { types: ["VariableDeclaration"], checkPath(path) { diff --git a/src/babel/traversal/path/modification.js b/src/babel/traversal/path/modification.js index 44c09ed373..9048b64339 100644 --- a/src/babel/traversal/path/modification.js +++ b/src/babel/traversal/path/modification.js @@ -31,6 +31,10 @@ export function insertBefore(nodes) { return [this]; } +/** + * [Please add a description.] + */ + export function _containerInsert(from, nodes) { this.updateSiblingKeys(from, nodes.length); @@ -59,14 +63,26 @@ export function _containerInsert(from, nodes) { return paths; } +/** + * [Please add a description.] + */ + export function _containerInsertBefore(nodes) { return this._containerInsert(this.key, nodes); } +/** + * [Please add a description.] + */ + export function _containerInsertAfter(nodes) { return this._containerInsert(this.key + 1, nodes); } +/** + * [Please add a description.] + */ + export function _maybePopFromStatements(nodes) { var last = nodes[nodes.length - 1]; if (t.isExpressionStatement(last) && t.isIdentifier(last.expression) && !this.isCompletionRecord()) { @@ -123,7 +139,7 @@ export function updateSiblingKeys(fromIndex, incrementBy) { } /** - * Description + * [Please add a description.] */ export function _verifyNodeList(nodes) { @@ -148,7 +164,7 @@ export function _verifyNodeList(nodes) { } /** - * Description + * [Please add a description.] */ export function unshiftContainer(listKey, nodes) { @@ -172,7 +188,7 @@ export function unshiftContainer(listKey, nodes) { } /** - * Description + * [Please add a description.] */ export function pushContainer(listKey, nodes) { diff --git a/src/babel/traversal/path/removal.js b/src/babel/traversal/path/removal.js index c7b45a4582..4703465dd1 100644 --- a/src/babel/traversal/path/removal.js +++ b/src/babel/traversal/path/removal.js @@ -32,12 +32,20 @@ export function dangerouslyRemove() { this._callRemovalHooks("post"); } +/** + * [Please add a description.] + */ + export function _callRemovalHooks(position) { for (var fn of (removalHooks[position]: Array)) { if (fn(this, this.parentPath)) return true; } } +/** + * [Please add a description.] + */ + export function _remove() { if (Array.isArray(this.container)) { this.container.splice(this.key, 1); @@ -47,12 +55,20 @@ export function _remove() { } } +/** + * [Please add a description.] + */ + export function _markRemoved() { this.shouldSkip = true; this.removed = true; this.node = null; } +/** + * [Please add a description.] + */ + export function _assertUnremoved() { if (this.removed) { throw this.errorWithNode("NodePath has been removed so is read-only."); diff --git a/src/babel/traversal/path/replacement.js b/src/babel/traversal/path/replacement.js index 94456872dd..c949e14dd3 100644 --- a/src/babel/traversal/path/replacement.js +++ b/src/babel/traversal/path/replacement.js @@ -4,11 +4,24 @@ import traverse from "../index"; import * as t from "../../types"; import parse from "../../helpers/parse"; +/** + * [Please add a description.] + */ + var hoistVariablesVisitor = { + + /** + * [Please add a description.] + */ + Function() { this.skip(); }, + /** + * [Please add a description.] + */ + VariableDeclaration(node, parent, scope) { if (node.kind !== "var") return; @@ -197,7 +210,7 @@ export function replaceExpressionWithStatements(nodes: Array) { } /** - * Description + * [Please add a description.] */ export function replaceInline(nodes) { diff --git a/src/babel/traversal/scope/README.md b/src/babel/traversal/scope/README.md new file mode 100644 index 0000000000..e63b7d3d06 --- /dev/null +++ b/src/babel/traversal/scope/README.md @@ -0,0 +1,3 @@ +## Scope Traversal + +This is the Scope Traversal directory. diff --git a/src/babel/traversal/scope/binding.js b/src/babel/traversal/scope/binding.js index efc40358d2..c3e14bf4b6 100644 --- a/src/babel/traversal/scope/binding.js +++ b/src/babel/traversal/scope/binding.js @@ -1,3 +1,7 @@ +/** + * [Please add a description.] + */ + export default class Binding { constructor({ existing, identifier, scope, path, kind }) { this.constantViolations = []; @@ -11,9 +15,9 @@ export default class Binding { this.path = path; this.kind = kind; - this.hasValue = false; - this.hasDeoptedValue = false; - this.value = null; + this.hasValue = false; + this.hasDeoptedValue = false; + this.value = null; this.clearValue(); @@ -27,7 +31,7 @@ export default class Binding { } /** - * Description + * [Please add a description.] */ deoptValue() { @@ -36,17 +40,17 @@ export default class Binding { } /** - * Description + * [Please add a description.] */ - setValue(value) { + setValue(value: any) { if (this.hasDeoptedValue) return; this.hasValue = true; this.value = value; } /** - * Description + * [Please add a description.] */ clearValue() { @@ -56,16 +60,16 @@ export default class Binding { } /** - * Description + * [Please add a description.] */ - reassign(path) { + reassign(path: Object) { this.constant = false; this.constantViolations.push(path); } /** - * Description + * [Please add a description.] */ reference() { @@ -74,7 +78,7 @@ export default class Binding { } /** - * Description + * [Please add a description.] */ dereference() { @@ -83,7 +87,7 @@ export default class Binding { } /** - * Description + * [Please add a description.] */ isCompatibleWithType(): boolean { diff --git a/src/babel/traversal/scope/index.js b/src/babel/traversal/scope/index.js index 646666738c..7ef81af584 100644 --- a/src/babel/traversal/scope/index.js +++ b/src/babel/traversal/scope/index.js @@ -11,7 +11,16 @@ import extend from "lodash/object/extend"; import object from "../../helpers/object"; import * as t from "../../types"; +/** + * [Please add a description.] + */ + var collectorVisitor = { + + /** + * [Please add a description.] + */ + For(node, parent, scope) { for (var key of (t.FOR_INIT_KEYS: Array)) { var declar = this.get(key); @@ -19,6 +28,10 @@ var collectorVisitor = { } }, + /** + * [Please add a description.] + */ + Declaration(node, parent, scope) { // delegate block scope handling to the `blockVariableVisitor` if (this.isBlockScoped()) return; @@ -30,6 +43,10 @@ var collectorVisitor = { scope.getFunctionParent().registerDeclaration(this); }, + /** + * [Please add a description.] + */ + ReferencedIdentifier(node) { var binding = this.scope.getBinding(node.name); if (binding) { @@ -39,6 +56,10 @@ var collectorVisitor = { } }, + /** + * [Please add a description.] + */ + ForXStatement() { var left = this.get("left"); if (left.isPattern() || left.isIdentifier()) { @@ -46,6 +67,10 @@ var collectorVisitor = { } }, + /** + * [Please add a description.] + */ + ExportDeclaration: { exit(node) { var declar = node.declaration; @@ -62,11 +87,19 @@ var collectorVisitor = { } }, + /** + * [Please add a description.] + */ + LabeledStatement(node) { this.scope.getProgramParent().addGlobal(node); this.scope.getBlockParent().registerDeclaration(this); }, + /** + * [Please add a description.] + */ + AssignmentExpression() { // register undeclared bindings as globals var ids = this.getBindingIdentifiers(); @@ -82,24 +115,44 @@ var collectorVisitor = { this.scope.registerConstantViolation(this, this.get("left"), this.get("right")); }, + /** + * [Please add a description.] + */ + UpdateExpression(node, parent, scope) { scope.registerConstantViolation(this, this.get("argument"), null); }, + /** + * [Please add a description.] + */ + UnaryExpression(node, parent, scope) { if (node.operator === "delete") scope.registerConstantViolation(this, this.get("left"), null); }, + /** + * [Please add a description.] + */ + BlockScoped(node, parent, scope) { if (scope.path === this) scope = scope.parent; scope.getBlockParent().registerDeclaration(this); }, + /** + * [Please add a description.] + */ + ClassDeclaration(node, parent, scope) { var name = node.id.name; scope.bindings[name] = scope.getBinding(name); }, + /** + * [Please add a description.] + */ + Block(node, parent, scope) { var paths = this.get("body"); for (var path of (paths: Array)) { @@ -110,13 +163,26 @@ var collectorVisitor = { } }; +/** + * [Please add a description.] + */ + var renameVisitor = { + + /** + * [Please add a description.] + */ + ReferencedIdentifier(node, parent, scope, state) { if (node.name === state.oldName) { node.name = state.newName; } }, + /** + * [Please add a description.] + */ + Scope(node, parent, scope, state) { if (!scope.bindingIdentifierEquals(state.oldName, state.binding)) { this.skip(); @@ -124,6 +190,10 @@ var renameVisitor = { } }; +/** + * [Please add a description.] + */ + renameVisitor.AssignmentExpression = renameVisitor.Declaration = function (node, parent, scope, state) { var ids = this.getBindingIdentifiers(); @@ -133,6 +203,10 @@ renameVisitor.Declaration = function (node, parent, scope, state) { } }; +/** + * [Please add a description.] + */ + export default class Scope { /** @@ -160,8 +234,14 @@ export default class Scope { this.path = path; } + /** + * Globals. + */ static globals = flatten([globals.builtin, globals.browser, globals.node].map(Object.keys)); + /** + * Variables available in current context. + */ static contextVariables = [ "arguments", "undefined", @@ -170,7 +250,7 @@ export default class Scope { ]; /** - * Description + * Traverse node with current scope and path. */ traverse(node: Object, opts: Object, state?) { @@ -178,7 +258,7 @@ export default class Scope { } /** - * Description + * Generate a unique identifier and add it to the current scope. */ generateDeclaredUidIdentifier(name: string = "temp") { @@ -188,7 +268,7 @@ export default class Scope { } /** - * Description + * Generate a unique identifier. */ generateUidIdentifier(name: string) { @@ -196,7 +276,7 @@ export default class Scope { } /** - * Description + * Generate a unique `_id1` binding. */ generateUid(name: string) { @@ -217,14 +297,18 @@ export default class Scope { return uid; } + /** + * Generate an `_id1`. + */ + _generateUid(name, i) { var id = name; if (i > 1) id += i; return `_${id}`; } - /* - * Description + /** + * Generate a unique identifier based on a node. */ generateUidIdentifierBasedOnNode(parent: Object, defaultName?: String): Object { @@ -300,7 +384,7 @@ export default class Scope { } /** - * Description + * Possibly generate a memoised identifier if it is not static and has consequences. */ maybeGenerateMemoised(node: Object, dontPush?: boolean): ?Object { @@ -314,7 +398,7 @@ export default class Scope { } /** - * Description + * [Please add a description.] */ checkBlockScopedCollisions(local, kind: string, name: string, id: Object) { @@ -338,7 +422,7 @@ export default class Scope { } /** - * Description + * [Please add a description.] */ rename(oldName: string, newName: string, block?) { @@ -370,6 +454,10 @@ export default class Scope { } } + /** + * [Please add a description.] + */ + _renameFromMap(map, oldName, newName, value) { if (map[oldName]) { map[newName] = value; @@ -378,7 +466,7 @@ export default class Scope { } /** - * Description + * [Please add a description.] */ dump() { @@ -400,7 +488,7 @@ export default class Scope { } /** - * Description + * [Please add a description.] */ toArray(node: Object, i?: number) { @@ -432,7 +520,7 @@ export default class Scope { } /** - * Description + * [Please add a description.] */ registerDeclaration(path: NodePath) { @@ -457,7 +545,7 @@ export default class Scope { } /** - * Description + * [Please add a description.] */ registerConstantViolation(root: NodePath, left: NodePath, right: NodePath) { @@ -476,7 +564,7 @@ export default class Scope { } /** - * Description + * [Please add a description.] */ registerBinding(kind: string, path: NodePath) { @@ -521,7 +609,7 @@ export default class Scope { } /** - * Description + * [Please add a description.] */ addGlobal(node: Object) { @@ -529,7 +617,7 @@ export default class Scope { } /** - * Description + * [Please add a description.] */ hasUid(name): boolean { @@ -543,7 +631,7 @@ export default class Scope { } /** - * Description + * [Please add a description.] */ hasGlobal(name: string): boolean { @@ -557,7 +645,7 @@ export default class Scope { } /** - * Description + * [Please add a description.] */ hasReference(name: string): boolean { @@ -571,7 +659,7 @@ export default class Scope { } /** - * Description + * [Please add a description.] */ isPure(node, constantsOnly?: boolean) { @@ -621,6 +709,7 @@ export default class Scope { if (data != null) return data; } while(scope = scope.parent); } + /** * Recursively walk up scope tree looking for the data `key` and if it exists, * remove it. @@ -635,7 +724,7 @@ export default class Scope { } /** - * Description + * [Please add a description.] */ init() { @@ -643,7 +732,7 @@ export default class Scope { } /** - * Description + * [Please add a description.] */ crawl() { @@ -719,7 +808,7 @@ export default class Scope { } /** - * Description + * [Please add a description.] */ push(opts: Object) { @@ -841,7 +930,7 @@ export default class Scope { } /** - * Description + * [Please add a description.] */ bindingIdentifierEquals(name: string, node: Object): boolean { @@ -849,7 +938,7 @@ export default class Scope { } /** - * Description + * [Please add a description.] */ getBinding(name: string) { @@ -862,7 +951,7 @@ export default class Scope { } /** - * Description + * [Please add a description.] */ getOwnBinding(name: string) { @@ -870,7 +959,7 @@ export default class Scope { } /** - * Description + * [Please add a description.] */ getBindingIdentifier(name: string) { @@ -879,7 +968,7 @@ export default class Scope { } /** - * Description + * [Please add a description.] */ getOwnBindingIdentifier(name: string) { @@ -888,7 +977,7 @@ export default class Scope { } /** - * Description + * [Please add a description.] */ hasOwnBinding(name: string) { @@ -896,7 +985,7 @@ export default class Scope { } /** - * Description + * [Please add a description.] */ hasBinding(name: string, noGlobals?) { @@ -910,7 +999,7 @@ export default class Scope { } /** - * Description + * [Please add a description.] */ parentHasBinding(name: string, noGlobals?) { @@ -931,7 +1020,7 @@ export default class Scope { } /** - * Description + * [Please add a description.] */ removeOwnBinding(name: string) { @@ -939,7 +1028,7 @@ export default class Scope { } /** - * Description + * [Please add a description.] */ removeBinding(name: string) { diff --git a/src/babel/traversal/visitors.js b/src/babel/traversal/visitors.js index e934d8c3f0..0f5ef2b2ab 100644 --- a/src/babel/traversal/visitors.js +++ b/src/babel/traversal/visitors.js @@ -3,6 +3,10 @@ import * as messages from "../messages"; import * as t from "../types"; import clone from "lodash/lang/clone"; +/** + * [Please add a description.] + */ + export function explode(visitor) { if (visitor._exploded) return visitor; visitor._exploded = true; @@ -96,6 +100,10 @@ export function explode(visitor) { return visitor; } +/** + * [Please add a description.] + */ + export function verify(visitor) { if (visitor._verified) return; @@ -122,6 +130,10 @@ export function verify(visitor) { visitor._verified = true; } +/** + * [Please add a description.] + */ + export function merge(visitors) { var rootVisitor = {}; @@ -137,6 +149,10 @@ export function merge(visitors) { return rootVisitor; } +/** + * [Please add a description.] + */ + function ensureEntranceObjects(obj) { for (let key in obj) { if (shouldIgnoreKey(key)) continue; @@ -148,11 +164,19 @@ function ensureEntranceObjects(obj) { } } +/** + * [Please add a description.] + */ + function ensureCallbackArrays(obj){ if (obj.enter && !Array.isArray(obj.enter)) obj.enter = [obj.enter]; if (obj.exit && !Array.isArray(obj.exit)) obj.exit = [obj.exit]; } +/** + * [Please add a description.] + */ + function wrapCheck(wrapper, fn) { return function () { if (wrapper.checkPath(this)) { @@ -161,6 +185,10 @@ function wrapCheck(wrapper, fn) { }; } +/** + * [Please add a description.] + */ + function shouldIgnoreKey(key) { // internal/hidden key if (key[0] === "_") return true; @@ -174,6 +202,10 @@ function shouldIgnoreKey(key) { return false; } +/** + * [Please add a description.] + */ + function mergePair(dest, src) { for (var key in src) { dest[key] = [].concat(dest[key] || [], src[key]); diff --git a/src/babel/types/README.md b/src/babel/types/README.md new file mode 100644 index 0000000000..5d5968edaf --- /dev/null +++ b/src/babel/types/README.md @@ -0,0 +1,3 @@ +## Types + +This is the Types directory. diff --git a/src/babel/types/converters.js b/src/babel/types/converters.js index 89f9af206d..5bf1c02ac0 100644 --- a/src/babel/types/converters.js +++ b/src/babel/types/converters.js @@ -7,7 +7,7 @@ import type Scope from "../traversal/scope"; import * as t from "./index"; /** - * Description + * [Please add a description.] */ export function toComputedKey(node: Object, key: Object = node.key || node.property): Object { @@ -102,7 +102,7 @@ export function toSequenceExpression(nodes: Array, scope: Scope): Object } /** - * Description + * [Please add a description.] */ export function toKeyAlias(node: Object, key: Object = node.key) { @@ -127,8 +127,8 @@ export function toKeyAlias(node: Object, key: Object = node.key) { toKeyAlias.uid = 0; -/* - * Description +/** + * [Please add a description.] */ export function toIdentifier(name: string): string { @@ -154,8 +154,8 @@ export function toIdentifier(name: string): string { return name || "_"; } -/* - * Description +/** + * [Please add a description.] */ export function toBindingIdentifierName(name) { @@ -164,10 +164,8 @@ export function toBindingIdentifierName(name) { return name; } - /** - * Description - * + * [Please add a description.] * @returns {Object|Boolean} */ @@ -207,7 +205,7 @@ export function toStatement(node: Object, ignore?: boolean) { } /** - * Description + * [Please add a description.] */ export function toExpression(node: Object): Object { @@ -229,7 +227,7 @@ export function toExpression(node: Object): Object { } /** - * Description + * [Please add a description.] */ export function toBlock(node: Object, parent: Object): Object { @@ -257,7 +255,7 @@ export function toBlock(node: Object, parent: Object): Object { } /** - * Description + * [Please add a description.] */ export function valueToNode(value: any): Object { diff --git a/src/babel/types/flow.js b/src/babel/types/flow.js index ea813ae0ef..d76ea258b2 100644 --- a/src/babel/types/flow.js +++ b/src/babel/types/flow.js @@ -16,7 +16,7 @@ export function createUnionTypeAnnotation(types) { } /** - * Description + * Dedupe type annotations. */ export function removeTypeDuplicates(nodes) { @@ -96,7 +96,7 @@ export function removeTypeDuplicates(nodes) { } /** - * Description + * Create a type anotation based on typeof expression. */ export function createTypeAnnotationBasedOnTypeof(type) { diff --git a/src/babel/types/index.js b/src/babel/types/index.js index a419300887..8528af9e42 100644 --- a/src/babel/types/index.js +++ b/src/babel/types/index.js @@ -24,6 +24,10 @@ function registerType(type: string, skipAliasCheck?: boolean) { }; } +/** + * Constants. + */ + export const STATEMENT_OR_BLOCK_KEYS = ["consequent", "body", "alternate"]; export const FLATTENABLE_KEYS = ["body", "expressions"]; export const FOR_INIT_KEYS = ["left", "init"]; @@ -42,12 +46,20 @@ export const VISITOR_KEYS = require("./visitor-keys"); export const BUILDER_KEYS = require("./builder-keys"); export const ALIAS_KEYS = require("./alias-keys"); -t.FLIPPED_ALIAS_KEYS = {}; +/** + * Registers `is[Type]` and `assert[Type]` for all types. + */ each(t.VISITOR_KEYS, function (keys, type) { registerType(type, true); }); +/** + * Flip `ALIAS_KEYS` for faster access in the reverse direction. + */ + +t.FLIPPED_ALIAS_KEYS = {}; + each(t.ALIAS_KEYS, function (aliases, type) { each(aliases, function (alias) { var types = t.FLIPPED_ALIAS_KEYS[alias] = t.FLIPPED_ALIAS_KEYS[alias] || []; @@ -55,6 +67,10 @@ each(t.ALIAS_KEYS, function (aliases, type) { }); }); +/** + * Registers `is[Alias]` and `assert[Alias]` functions for all aliases. + */ + each(t.FLIPPED_ALIAS_KEYS, function (types, type) { t[type.toUpperCase() + "_TYPES"] = types; registerType(type, false); @@ -69,6 +85,7 @@ export const TYPES = Object.keys(t.VISITOR_KEYS).concat(Object.keys(t.FLIPPED_AL * Optionally, pass `skipAliasCheck` to directly compare `node.type` with `type`. */ +// @TODO should `skipAliasCheck` be removed? export function is(type: string, node: Object, opts?: Object, skipAliasCheck?: boolean): boolean { if (!node) return false; @@ -82,7 +99,11 @@ export function is(type: string, node: Object, opts?: Object, skipAliasCheck?: b } } -export function isType(nodeType, targetType) { +/** + * Test if a `nodeType` is a `targetType` or if `targetType` is an alias of `nodeType`. + */ + +export function isType(nodeType: string, targetType: string): boolean { if (nodeType === targetType) return true; var aliases = t.FLIPPED_ALIAS_KEYS[targetType]; @@ -97,6 +118,10 @@ export function isType(nodeType, targetType) { return false; } +/** + * [Please add a description.] + */ + each(t.VISITOR_KEYS, function (keys, type) { if (t.BUILDER_KEYS[type]) return; @@ -107,6 +132,10 @@ each(t.VISITOR_KEYS, function (keys, type) { t.BUILDER_KEYS[type] = defs; }); +/** + * [Please add a description.] + */ + each(t.BUILDER_KEYS, function (keys, type) { var builder = function () { var node = {}; @@ -128,8 +157,8 @@ each(t.BUILDER_KEYS, function (keys, type) { t[type[0].toLowerCase() + type.slice(1)] = builder; }); -/* - * Description +/** + * Test if an object is shallowly equal. */ export function shallowEqual(actual: Object, expected: Object): boolean { @@ -145,7 +174,7 @@ export function shallowEqual(actual: Object, expected: Object): boolean { } /** - * Description + * Append a node to a member expression. */ export function appendToMemberExpression(member: Object, append: Object, computed?: boolean): Object { @@ -156,16 +185,17 @@ export function appendToMemberExpression(member: Object, append: Object, compute } /** - * Description + * Prepend a node to a member expression. */ -export function prependToMemberExpression(member: Object, append: Object): Object { - member.object = t.memberExpression(append, member.object); +export function prependToMemberExpression(member: Object, prepend: Object): Object { + member.object = t.memberExpression(prepend, member.object); return member; } /** - * Description + * Ensure the `key` (defaults to "body") of a `node` is a block. + * Casting it to a block if it is not. */ export function ensureBlock(node: Object, key: string = "body") { @@ -173,7 +203,7 @@ export function ensureBlock(node: Object, key: string = "body") { } /** - * Description + * Create a shallow clone of a `node` excluding `_private` properties. */ export function clone(node: Object): Object { @@ -186,7 +216,8 @@ export function clone(node: Object): Object { } /** - * Description + * Create a deep clone of a `node` and all of it's child nodes + * exluding `_private` properties. */ export function cloneDeep(node: Object): Object { @@ -267,31 +298,31 @@ export function buildMatchMemberExpression(match:string, allowPartial?: boolean) } /** - * Description + * Remove comment properties from a node. */ -export function removeComments(child: Object): Object { +export function removeComments(node: Object): Object { for (var key of (COMMENT_KEYS: Array)) { - delete child[key]; + delete node[key]; } - return child; + return node; } /** - * Description + * Inherit all unique comments from `parent` node to `child` node. */ export function inheritsComments(child: Object, parent: Object): Object { if (child && parent) { for (var key of (COMMENT_KEYS: Array)) { - child[key] = uniq(compact([].concat(child[key], parent[key]))); + child[key] = uniq(compact([].concat(child[key], parent[key]))); } } return child; } /** - * Description + * Inherit all contextual properties from `parent` node to `child` node. */ export function inherits(child: Object, parent: Object): Object { @@ -312,9 +343,11 @@ export function inherits(child: Object, parent: Object): Object { return child; } +// Optimize property access. toFastProperties(t); toFastProperties(t.VISITOR_KEYS); +// Export all type checkers from other files. assign(t, require("./retrievers")); assign(t, require("./validators")); assign(t, require("./converters")); diff --git a/src/babel/types/retrievers.js b/src/babel/types/retrievers.js index 64eb1bdf60..fd8c4caf4f 100644 --- a/src/babel/types/retrievers.js +++ b/src/babel/types/retrievers.js @@ -34,6 +34,10 @@ export function getBindingIdentifiers(node: Object, duplicates?): Object { return ids; } +/** + * Mapping of types to their identifier keys. + */ + getBindingIdentifiers.keys = { DeclareClass: "id", DeclareFunction: "id", diff --git a/src/babel/types/validators.js b/src/babel/types/validators.js index 9db9a5d3b7..23fed2f132 100644 --- a/src/babel/types/validators.js +++ b/src/babel/types/validators.js @@ -3,7 +3,7 @@ import esutils from "esutils"; import * as t from "./index"; /** - * + * Check if the input `node` is a binding identifier. */ export function isBinding(node: Object, parent: Object): boolean { @@ -147,7 +147,7 @@ export function isValidIdentifier(name: string): boolean { } /** - * Description + * Check if the input `node` is a `let` variable declaration. */ export function isLet(node: Object): boolean { @@ -155,7 +155,7 @@ export function isLet(node: Object): boolean { } /** - * Description + * Check if the input `node` is block scoped. */ export function isBlockScoped(node: Object): boolean { @@ -163,7 +163,7 @@ export function isBlockScoped(node: Object): boolean { } /** - * Description + * Check if the input `node` is a variable declaration. */ export function isVar(node: Object): boolean { @@ -171,7 +171,7 @@ export function isVar(node: Object): boolean { } /** - * Description + * Check if the input `specifier` is a `default` import or export. */ export function isSpecifierDefault(specifier: Object): boolean { @@ -180,7 +180,7 @@ export function isSpecifierDefault(specifier: Object): boolean { } /** - * Description + * Check if the input `node` is a scope. */ export function isScope(node: Object, parent: Object): boolean { @@ -192,7 +192,7 @@ export function isScope(node: Object, parent: Object): boolean { } /** - * Description + * Check if the input `node` is definitely immutable. */ export function isImmutable(node: Object): boolean { diff --git a/src/babel/util.js b/src/babel/util.js index 37c36dad9b..a7fbacdc35 100644 --- a/src/babel/util.js +++ b/src/babel/util.js @@ -22,14 +22,26 @@ import pathExists from "path-exists"; export { inherits, inspect } from "util"; +/** + * Test if a filename ends with a compilable extension. + */ + export function canCompile(filename: string, altExts?: Array) { var exts = altExts || canCompile.EXTENSIONS; var ext = path.extname(filename); return contains(exts, ext); } +/** + * Default set of compilable extensions. + */ + canCompile.EXTENSIONS = [".js", ".jsx", ".es6", ".es"]; +/** + * Module resolver that swallows errors. + */ + export function resolve(loc: string) { try { return require.resolve(loc); @@ -40,6 +52,10 @@ export function resolve(loc: string) { var relativeMod; +/** + * Resolve a filename relative to the current working directory. + */ + export function resolveRelative(loc: string) { // we're in the browser, probably if (typeof Module === "object") return null; @@ -56,7 +72,11 @@ export function resolveRelative(loc: string) { } } -export function list(val: string): Array { +/** + * Create an array from any value, splitting strings by ",". + */ + +export function list(val?: string): Array { if (!val) { return []; } else if (Array.isArray(val)) { @@ -68,6 +88,10 @@ export function list(val: string): Array { } } +/** + * Create a RegExp from a string, array, or regexp. + */ + export function regexify(val: any): RegExp { if (!val) return new RegExp(/.^/); @@ -90,6 +114,10 @@ export function regexify(val: any): RegExp { throw new TypeError("illegal type for regexify"); } +/** + * Create an array from a boolean, string, or array, mapped by and optional function. + */ + export function arrayify(val: any, mapFn?: Function): Array { if (!val) return []; if (isBoolean(val)) return arrayify([val], mapFn); @@ -103,13 +131,21 @@ export function arrayify(val: any, mapFn?: Function): Array { return [val]; } -export function booleanify(val: any) { +/** + * Makes boolean-like strings into booleans. + */ + +export function booleanify(val: any): boolean { if (val === "true") return true; if (val === "false") return false; return val; } -export function shouldIgnore(filename, ignore, only) { +/** + * Tests if a filename should be ignored based on "ignore" and "only" options. + */ + +export function shouldIgnore(filename: string, ignore: Array, only): boolean { filename = slash(filename); if (only) { @@ -126,6 +162,10 @@ export function shouldIgnore(filename, ignore, only) { return false; } +/** + * [Please add a description.] + */ + function _shouldIgnore(pattern, filename) { if (typeof pattern === "function") { return pattern(filename); @@ -134,10 +174,18 @@ function _shouldIgnore(pattern, filename) { } } +/** + * A visitor for Babel templates, replaces placeholder references. + */ + var templateVisitor = { + + /** + * 360 NoScope PWNd + */ noScope: true, - enter(node, parent, scope, nodes) { + enter(node: Object, parent: Object, scope, nodes: Array) { if (t.isExpressionStatement(node)) { node = node.expression; } @@ -148,12 +196,14 @@ var templateVisitor = { } }, - exit(node) { + exit(node: Object) { traverse.clearNode(node); } }; -// +/** + * Create an instance of a template to use in a transformer. + */ export function template(name: string, nodes?: Array, keepExpression?: boolean): Object { var ast = exports.templates[name]; @@ -181,13 +231,21 @@ export function template(name: string, nodes?: Array, keepExpression?: b } } +/** + * Parse a template. + */ + export function parseTemplate(loc: string, code: string): Object { var ast = parse(code, { filename: loc, looseModules: true }).program; ast = traverse.removeProperties(ast); return ast; } -function loadTemplates() { +/** + * Load templates from transformation/templates directory. + */ + +function loadTemplates(): Object { var templates = {}; var templatesLoc = path.join(__dirname, "transformation/templates");