src/third_party/closure_compiler/runner/src/com/google/javascript/jscomp/ChromePass.java

   1 // Copyright 2014 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 package com.google.javascript.jscomp;
   6
   7 import com.google.javascript.jscomp.NodeTraversal.AbstractPostOrderCallback;
   8 import com.google.javascript.rhino.IR;
   9 import com.google.javascript.rhino.JSDocInfoBuilder;
  10 import com.google.javascript.rhino.JSTypeExpression;
  11 import com.google.javascript.rhino.Node;
  12 import com.google.javascript.rhino.Token;
  13
  14 import java.util.ArrayList;
  15 import java.util.Arrays;
  16 import java.util.HashMap;
  17 import java.util.HashSet;
  18 import java.util.List;
  19 import java.util.Map;
  20 import java.util.Set;
  21
  22 /**
  23  * Compiler pass for Chrome-specific needs. It handles the following Chrome JS features:
  24  * <ul>
  25  * <li>namespace declaration using {@code cr.define()},
  26  * <li>unquoted property declaration using {@code {cr|Object}.defineProperty()}.
  27  * </ul>
  28  *
  29  * <p>For the details, see tests inside ChromePassTest.java.
  30  */
  31 public class ChromePass extends AbstractPostOrderCallback implements CompilerPass {
  32     final AbstractCompiler compiler;
  33
  34     private Set<String> createdObjects;
  35
  36     private static final String CR_DEFINE = "cr.define";
  37     private static final String CR_EXPORT_PATH = "cr.exportPath";
  38     private static final String OBJECT_DEFINE_PROPERTY = "Object.defineProperty";
  39     private static final String CR_DEFINE_PROPERTY = "cr.defineProperty";
  40     private static final String CR_MAKE_PUBLIC = "cr.makePublic";
  41
  42     private static final String CR_DEFINE_COMMON_EXPLANATION = "It should be called like this:"
  43             + " cr.define('name.space', function() '{ ... return {Export: Internal}; }');";
  44
  45     static final DiagnosticType CR_DEFINE_WRONG_NUMBER_OF_ARGUMENTS =
  46             DiagnosticType.error("JSC_CR_DEFINE_WRONG_NUMBER_OF_ARGUMENTS",
  47                     "cr.define() should have exactly 2 arguments. " + CR_DEFINE_COMMON_EXPLANATION);
  48
  49     static final DiagnosticType CR_EXPORT_PATH_WRONG_NUMBER_OF_ARGUMENTS =
  50             DiagnosticType.error("JSC_CR_EXPORT_PATH_WRONG_NUMBER_OF_ARGUMENTS",
  51                     "cr.exportPath() should have exactly 1 argument: namespace name.");
  52
  53     static final DiagnosticType CR_DEFINE_INVALID_FIRST_ARGUMENT =
  54             DiagnosticType.error("JSC_CR_DEFINE_INVALID_FIRST_ARGUMENT",
  55                     "Invalid first argument for cr.define(). " + CR_DEFINE_COMMON_EXPLANATION);
  56
  57     static final DiagnosticType CR_DEFINE_INVALID_SECOND_ARGUMENT =
  58             DiagnosticType.error("JSC_CR_DEFINE_INVALID_SECOND_ARGUMENT",
  59                     "Invalid second argument for cr.define(). " + CR_DEFINE_COMMON_EXPLANATION);
  60
  61     static final DiagnosticType CR_DEFINE_INVALID_RETURN_IN_FUNCTION =
  62             DiagnosticType.error("JSC_CR_DEFINE_INVALID_RETURN_IN_SECOND_ARGUMENT",
  63                     "Function passed as second argument of cr.define() should return the"
  64                     + " dictionary in its last statement. " + CR_DEFINE_COMMON_EXPLANATION);
  65
  66     static final DiagnosticType CR_DEFINE_PROPERTY_INVALID_PROPERTY_KIND =
  67             DiagnosticType.error("JSC_CR_DEFINE_PROPERTY_INVALID_PROPERTY_KIND",
  68                     "Invalid cr.PropertyKind passed to cr.defineProperty(): expected ATTR,"
  69                     + " BOOL_ATTR or JS, found \"{0}\".");
  70
  71     static final DiagnosticType CR_MAKE_PUBLIC_HAS_NO_JSDOC =
  72             DiagnosticType.error("JSC_CR_MAKE_PUBLIC_HAS_NO_JSDOC",
  73                     "Private method exported by cr.makePublic() has no JSDoc.");
  74
  75     static final DiagnosticType CR_MAKE_PUBLIC_MISSED_DECLARATION =
  76             DiagnosticType.error("JSC_CR_MAKE_PUBLIC_MISSED_DECLARATION",
  77                     "Method \"{1}_\" exported by cr.makePublic() on \"{0}\" has no declaration.");
  78
  79     static final DiagnosticType CR_MAKE_PUBLIC_INVALID_SECOND_ARGUMENT =
  80             DiagnosticType.error("JSC_CR_MAKE_PUBLIC_INVALID_SECOND_ARGUMENT",
  81                     "Invalid second argument passed to cr.makePublic(): should be array of " +
  82                     "strings.");
  83
  84     public ChromePass(AbstractCompiler compiler) {
  85         this.compiler = compiler;
  86         // The global variable "cr" is declared in ui/webui/resources/js/cr.js.
  87         this.createdObjects = new HashSet<>(Arrays.asList("cr"));
  88     }
  89
  90     @Override
  91     public void process(Node externs, Node root) {
  92         NodeTraversal.traverse(compiler, root, this);
  93     }
  94
  95     @Override
  96     public void visit(NodeTraversal t, Node node, Node parent) {
  97         if (node.isCall()) {
  98             Node callee = node.getFirstChild();
  99             if (callee.matchesQualifiedName(CR_DEFINE)) {
 100                 visitNamespaceDefinition(node, parent);
 101                 compiler.reportCodeChange();
 102             } else if (callee.matchesQualifiedName(CR_EXPORT_PATH)) {
 103                 visitExportPath(node, parent);
 104                 compiler.reportCodeChange();
 105             } else if (callee.matchesQualifiedName(OBJECT_DEFINE_PROPERTY) ||
 106                     callee.matchesQualifiedName(CR_DEFINE_PROPERTY)) {
 107                 visitPropertyDefinition(node, parent);
 108                 compiler.reportCodeChange();
 109             } else if (callee.matchesQualifiedName(CR_MAKE_PUBLIC)) {
 110                 if (visitMakePublic(node, parent)) {
 111                     compiler.reportCodeChange();
 112                 }
 113             }
 114         }
 115     }
 116
 117     private void visitPropertyDefinition(Node call, Node parent) {
 118         Node callee = call.getFirstChild();
 119         String target = call.getChildAtIndex(1).getQualifiedName();
 120         if (callee.matchesQualifiedName(CR_DEFINE_PROPERTY) && !target.endsWith(".prototype")) {
 121             target += ".prototype";
 122         }
 123
 124         Node property = call.getChildAtIndex(2);
 125
 126         Node getPropNode = NodeUtil.newQualifiedNameNode(compiler.getCodingConvention(),
 127                 target + "." + property.getString()).srcrefTree(call);
 128
 129         if (callee.matchesQualifiedName(CR_DEFINE_PROPERTY)) {
 130             setJsDocWithType(getPropNode, getTypeByCrPropertyKind(call.getChildAtIndex(3)));
 131         } else {
 132             setJsDocWithType(getPropNode, new Node(Token.QMARK));
 133         }
 134
 135         Node definitionNode = IR.exprResult(getPropNode).srcref(parent);
 136
 137         parent.getParent().addChildAfter(definitionNode, parent);
 138     }
 139
 140     private Node getTypeByCrPropertyKind(Node propertyKind) {
 141         if (propertyKind == null || propertyKind.matchesQualifiedName("cr.PropertyKind.JS")) {
 142             return new Node(Token.QMARK);
 143         }
 144         if (propertyKind.matchesQualifiedName("cr.PropertyKind.ATTR")) {
 145             return IR.string("string");
 146         }
 147         if (propertyKind.matchesQualifiedName("cr.PropertyKind.BOOL_ATTR")) {
 148             return IR.string("boolean");
 149         }
 150         compiler.report(JSError.make(propertyKind, CR_DEFINE_PROPERTY_INVALID_PROPERTY_KIND,
 151                 propertyKind.getQualifiedName()));
 152         return null;
 153     }
 154
 155     private void setJsDocWithType(Node target, Node type) {
 156         JSDocInfoBuilder builder = new JSDocInfoBuilder(false);
 157         builder.recordType(new JSTypeExpression(type, ""));
 158         target.setJSDocInfo(builder.build(target));
 159     }
 160
 161     private boolean visitMakePublic(Node call, Node exprResult) {
 162         boolean changesMade = false;
 163         Node scope = exprResult.getParent();
 164         String className = call.getChildAtIndex(1).getQualifiedName();
 165         String prototype = className  + ".prototype";
 166         Node methods = call.getChildAtIndex(2);
 167
 168         if (methods == null || !methods.isArrayLit()) {
 169             compiler.report(JSError.make(exprResult, CR_MAKE_PUBLIC_INVALID_SECOND_ARGUMENT));
 170             return changesMade;
 171         }
 172
 173         Set<String> methodNames = new HashSet<>();
 174         for (Node methodName: methods.children()) {
 175             if (!methodName.isString()) {
 176                 compiler.report(JSError.make(methodName, CR_MAKE_PUBLIC_INVALID_SECOND_ARGUMENT));
 177                 return changesMade;
 178             }
 179             methodNames.add(methodName.getString());
 180         }
 181
 182         for (Node child: scope.children()) {
 183             if (isAssignmentToPrototype(child, prototype)) {
 184                 Node objectLit = child.getFirstChild().getChildAtIndex(1);
 185                 for (Node stringKey : objectLit.children()) {
 186                     String field = stringKey.getString();
 187                     changesMade |= maybeAddPublicDeclaration(field, methodNames, className,
 188                                                              stringKey, scope, exprResult);
 189                 }
 190             } else if (isAssignmentToPrototypeMethod(child, prototype)) {
 191                 Node assignNode = child.getFirstChild();
 192                 String qualifiedName = assignNode.getFirstChild().getQualifiedName();
 193                 String field = qualifiedName.substring(qualifiedName.lastIndexOf('.') + 1);
 194                 changesMade |= maybeAddPublicDeclaration(field, methodNames, className,
 195                                                          assignNode, scope, exprResult);
 196             } else if (isDummyPrototypeMethodDeclaration(child, prototype)) {
 197                 String qualifiedName = child.getFirstChild().getQualifiedName();
 198                 String field = qualifiedName.substring(qualifiedName.lastIndexOf('.') + 1);
 199                 changesMade |= maybeAddPublicDeclaration(field, methodNames, className,
 200                                                          child.getFirstChild(), scope, exprResult);
 201             }
 202         }
 203
 204         for (String missedDeclaration : methodNames) {
 205             compiler.report(JSError.make(exprResult, CR_MAKE_PUBLIC_MISSED_DECLARATION, className,
 206                     missedDeclaration));
 207         }
 208
 209         return changesMade;
 210     }
 211
 212     private boolean isAssignmentToPrototype(Node node, String prototype) {
 213         Node assignNode;
 214         return node.isExprResult() && (assignNode = node.getFirstChild()).isAssign() &&
 215                 assignNode.getFirstChild().getQualifiedName().equals(prototype);
 216     }
 217
 218     private boolean isAssignmentToPrototypeMethod(Node node, String prototype) {
 219         Node assignNode;
 220         return node.isExprResult() && (assignNode = node.getFirstChild()).isAssign() &&
 221                 assignNode.getFirstChild().getQualifiedName().startsWith(prototype + ".");
 222     }
 223
 224     private boolean isDummyPrototypeMethodDeclaration(Node node, String prototype) {
 225         Node getPropNode;
 226         return node.isExprResult() && (getPropNode = node.getFirstChild()).isGetProp() &&
 227                 getPropNode.getQualifiedName().startsWith(prototype + ".");
 228     }
 229
 230     private boolean maybeAddPublicDeclaration(String field, Set<String> publicAPIStrings,
 231             String className, Node jsDocSourceNode, Node scope, Node exprResult) {
 232         boolean changesMade = false;
 233         if (field.endsWith("_")) {
 234             String publicName = field.substring(0, field.length() - 1);
 235             if (publicAPIStrings.contains(publicName)) {
 236                 Node methodDeclaration = NodeUtil.newQualifiedNameNode(
 237                         compiler.getCodingConvention(), className + "." + publicName);
 238                 if (jsDocSourceNode.getJSDocInfo() != null) {
 239                     methodDeclaration.setJSDocInfo(jsDocSourceNode.getJSDocInfo());
 240                     scope.addChildBefore(
 241                             IR.exprResult(methodDeclaration).srcrefTree(exprResult),
 242                             exprResult);
 243                     changesMade = true;
 244                 } else {
 245                     compiler.report(JSError.make(jsDocSourceNode, CR_MAKE_PUBLIC_HAS_NO_JSDOC));
 246                 }
 247                 publicAPIStrings.remove(publicName);
 248             }
 249         }
 250         return changesMade;
 251     }
 252
 253     private void visitExportPath(Node crExportPathNode, Node parent) {
 254         if (crExportPathNode.getChildCount() != 2) {
 255             compiler.report(JSError.make(crExportPathNode,
 256                     CR_EXPORT_PATH_WRONG_NUMBER_OF_ARGUMENTS));
 257             return;
 258         }
 259
 260         createAndInsertObjectsForQualifiedName(parent,
 261                 crExportPathNode.getChildAtIndex(1).getString());
 262     }
 263
 264     private void createAndInsertObjectsForQualifiedName(Node scriptChild, String namespace) {
 265         List<Node> objectsForQualifiedName = createObjectsForQualifiedName(namespace);
 266         for (Node n : objectsForQualifiedName) {
 267             scriptChild.getParent().addChildBefore(n, scriptChild);
 268         }
 269     }
 270
 271     private void visitNamespaceDefinition(Node crDefineCallNode, Node parent) {
 272         if (crDefineCallNode.getChildCount() != 3) {
 273             compiler.report(JSError.make(crDefineCallNode, CR_DEFINE_WRONG_NUMBER_OF_ARGUMENTS));
 274         }
 275
 276         Node namespaceArg = crDefineCallNode.getChildAtIndex(1);
 277         Node function = crDefineCallNode.getChildAtIndex(2);
 278
 279         if (!namespaceArg.isString()) {
 280             compiler.report(JSError.make(namespaceArg, CR_DEFINE_INVALID_FIRST_ARGUMENT));
 281             return;
 282         }
 283
 284         // TODO(vitalyp): Check namespace name for validity here. It should be a valid chain of
 285         // identifiers.
 286         String namespace = namespaceArg.getString();
 287
 288         createAndInsertObjectsForQualifiedName(parent, namespace);
 289
 290         if (!function.isFunction()) {
 291             compiler.report(JSError.make(namespaceArg, CR_DEFINE_INVALID_SECOND_ARGUMENT));
 292             return;
 293         }
 294
 295         Node returnNode, objectLit;
 296         Node functionBlock = function.getLastChild();
 297         if ((returnNode = functionBlock.getLastChild()) == null ||
 298                 !returnNode.isReturn() ||
 299                 (objectLit = returnNode.getFirstChild()) == null ||
 300                 !objectLit.isObjectLit()) {
 301             compiler.report(JSError.make(namespaceArg, CR_DEFINE_INVALID_RETURN_IN_FUNCTION));
 302             return;
 303         }
 304
 305         Map<String, String> exports = objectLitToMap(objectLit);
 306
 307         NodeTraversal.traverse(compiler, functionBlock, new RenameInternalsToExternalsCallback(
 308                 namespace, exports, functionBlock));
 309     }
 310
 311     private Map<String, String> objectLitToMap(Node objectLit) {
 312         Map<String, String> res = new HashMap<String, String>();
 313
 314         for (Node keyNode : objectLit.children()) {
 315             String key = keyNode.getString();
 316
 317             // TODO(vitalyp): Can dict value be other than a simple NAME? What if NAME doesn't
 318             // refer to a function/constructor?
 319             String value = keyNode.getFirstChild().getString();
 320
 321             res.put(value, key);
 322         }
 323
 324         return res;
 325     }
 326
 327     /**
 328      * For a string "a.b.c" produce the following JS IR:
 329      *
 330      * <p><pre>
 331      * var a = a || {};
 332      * a.b = a.b || {};
 333      * a.b.c = a.b.c || {};</pre>
 334      */
 335     private List<Node> createObjectsForQualifiedName(String namespace) {
 336         List<Node> objects = new ArrayList<>();
 337         String[] parts = namespace.split("\\.");
 338
 339         createObjectIfNew(objects, parts[0], true);
 340
 341         if (parts.length >= 2) {
 342             StringBuilder currPrefix = new StringBuilder().append(parts[0]);
 343             for (int i = 1; i < parts.length; ++i) {
 344                 currPrefix.append(".").append(parts[i]);
 345                 createObjectIfNew(objects, currPrefix.toString(), false);
 346             }
 347         }
 348
 349         return objects;
 350     }
 351
 352     private void createObjectIfNew(List<Node> objects, String name, boolean needVar) {
 353         if (!createdObjects.contains(name)) {
 354             objects.add(createJsNode((needVar ? "var " : "") + name + " = " + name + " || {};"));
 355             createdObjects.add(name);
 356         }
 357     }
 358
 359     private Node createJsNode(String code) {
 360         // The parent node after parseSyntheticCode() is SCRIPT node, we need to get rid of it.
 361         return compiler.parseSyntheticCode(code).removeFirstChild();
 362     }
 363
 364     private class RenameInternalsToExternalsCallback extends AbstractPostOrderCallback {
 365         private final String namespaceName;
 366         private final Map<String, String> exports;
 367         private final Node namespaceBlock;
 368
 369         public RenameInternalsToExternalsCallback(String namespaceName,
 370                 Map<String, String> exports, Node namespaceBlock) {
 371             this.namespaceName = namespaceName;
 372             this.exports = exports;
 373             this.namespaceBlock = namespaceBlock;
 374         }
 375
 376         @Override
 377         public void visit(NodeTraversal t, Node n, Node parent) {
 378             if (n.isFunction() && parent == this.namespaceBlock &&
 379                     this.exports.containsKey(n.getFirstChild().getString())) {
 380                 // It's a top-level function/constructor definition.
 381                 //
 382                 // Change
 383                 //
 384                 //   /** Some doc */
 385                 //   function internalName() {}
 386                 //
 387                 // to
 388                 //
 389                 //   /** Some doc */
 390                 //   my.namespace.name.externalName = function internalName() {};
 391                 //
 392                 // by looking up in this.exports for internalName to find the correspondent
 393                 // externalName.
 394                 Node functionTree = n.cloneTree();
 395                 Node exprResult = IR.exprResult(
 396                             IR.assign(buildQualifiedName(n.getFirstChild()), functionTree).srcref(n)
 397                         ).srcref(n);
 398
 399                 if (n.getJSDocInfo() != null) {
 400                     exprResult.getFirstChild().setJSDocInfo(n.getJSDocInfo());
 401                     functionTree.removeProp(Node.JSDOC_INFO_PROP);
 402                 }
 403                 this.namespaceBlock.replaceChild(n, exprResult);
 404             } else if (n.isName() && this.exports.containsKey(n.getString()) &&
 405                     !parent.isFunction()) {
 406                 if (parent.isVar()) {
 407                     if (parent.getParent() == this.namespaceBlock) {
 408                         // It's a top-level exported variable definition (maybe without an
 409                         // assignment).
 410                         // Change
 411                         //
 412                         //   var enum = { 'one': 1, 'two': 2 };
 413                         //
 414                         // to
 415                         //
 416                         //   my.namespace.name.enum = { 'one': 1, 'two': 2 };
 417                         Node varContent = n.removeFirstChild();
 418                         Node exprResult;
 419                         if (varContent == null) {
 420                             exprResult = IR.exprResult(buildQualifiedName(n)).srcref(parent);
 421                         } else {
 422                             exprResult = IR.exprResult(
 423                                         IR.assign(buildQualifiedName(n), varContent).srcref(parent)
 424                                     ).srcref(parent);
 425                         }
 426                         if (parent.getJSDocInfo() != null) {
 427                             exprResult.getFirstChild().setJSDocInfo(parent.getJSDocInfo().clone());
 428                         }
 429                         this.namespaceBlock.replaceChild(parent, exprResult);
 430                     }
 431                 } else {
 432                     // It's a local name referencing exported entity. Change to its global name.
 433                     Node newNode = buildQualifiedName(n);
 434                     if (n.getJSDocInfo() != null) {
 435                         newNode.setJSDocInfo(n.getJSDocInfo().clone());
 436                     }
 437
 438                     // If we alter the name of a called function, then it gets an explicit "this"
 439                     // value.
 440                     if (parent.isCall()) {
 441                         parent.putBooleanProp(Node.FREE_CALL, false);
 442                     }
 443
 444                     parent.replaceChild(n, newNode);
 445                 }
 446             }
 447         }
 448
 449         private Node buildQualifiedName(Node internalName) {
 450             String externalName = this.exports.get(internalName.getString());
 451             return NodeUtil.newQualifiedNameNode(compiler.getCodingConvention(),
 452                     this.namespaceName + "." + externalName).srcrefTree(internalName);
 453         }
 454     }
 455 }