Matchers.java

/*
 * Copyright 2014 The Closure Compiler Authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package com.google.javascript.refactoring;

import com.google.javascript.jscomp.NodeUtil;
import com.google.javascript.rhino.JSDocInfo;
import com.google.javascript.rhino.JSDocInfo.Visibility;
import com.google.javascript.rhino.Node;
import com.google.javascript.rhino.jstype.JSType;
import com.google.javascript.rhino.jstype.JSTypeNative;

/**
 * Class that contains common Matchers that are useful to everyone.
 *
 * @author mknichel@google.com (Mark Knichel)
 */
public final class Matchers {
  // TODO(mknichel): Make sure all this code works with goog.scope.

  /**
   * Returns a Matcher that matches every node.
   */
  public static Matcher anything() {
    return new Matcher() {
      @Override public boolean matches(Node node, NodeMetadata metadata) {
        return true;
      }
    };
  }

  /**
   * Returns a Matcher that returns true only if all of the provided
   * matchers match.
   */
  public static Matcher allOf(final Matcher... matchers) {
    return new Matcher() {
      @Override public boolean matches(Node node, NodeMetadata metadata) {
        for (Matcher m : matchers) {
          if (!m.matches(node, metadata)) {
            return false;
          }
        }
        return true;
      }
    };
  }

  /**
   * Returns a Matcher that returns true if any of the provided matchers match.
   */
  public static Matcher anyOf(final Matcher... matchers) {
    return new Matcher() {
      @Override public boolean matches(Node node, NodeMetadata metadata) {
        for (Matcher m : matchers) {
          if (m.matches(node, metadata)) {
            return true;
          }
        }
        return false;
      }
    };
  }

  /**
   * Returns a Matcher that matches the opposite of the provided matcher.
   */
  public static Matcher not(final Matcher matcher) {
    return new Matcher() {
      @Override public boolean matches(Node node, NodeMetadata metadata) {
        return !matcher.matches(node, metadata);
      }
    };
  }

  /**
   * Returns a matcher that matches any constructor definitions.
   */
  public static Matcher constructor() {
    return constructor(null);
  }

  /**
   * Returns a matcher that matches constructor definitions of the specified
   * name.
   * @param name The name of the class constructor to match.
   */
  public static Matcher constructor(final String name) {
    return new Matcher() {
      @Override public boolean matches(Node node, NodeMetadata metadata) {
        JSDocInfo info = node.getJSDocInfo();
        if (info != null && info.isConstructor()) {
          Node firstChild = node.getFirstChild();
          // TODO(mknichel): Make sure this works with the following cases:
          // ns = {
          //   /** @constructor */
          //   name: function() {}
          // }
          if (name == null) {
            return true;
          }
          if ((firstChild.isGetProp() || firstChild.isName())
              && firstChild.matchesQualifiedName(name)) {
            return true;
          }
        }
        return false;
      }
    };
  }

  /**
   * Returns a Matcher that matches constructing new objects. This will match
   * the NEW node of the JS Compiler AST.
   */
  public static Matcher newClass() {
    return new Matcher() {
      @Override public boolean matches(Node node, NodeMetadata metadata) {
        return node.isNew();
      }
    };
  }

  /**
   * Returns a Matcher that matches constructing objects of the provided class
   * name. This will match the NEW node of the JS Compiler AST.
   * @param className The name of the class to return matching NEW nodes.
   */
  public static Matcher newClass(final String className) {
    return new Matcher() {
      @Override public boolean matches(Node node, NodeMetadata metadata) {
        if (!node.isNew()) {
          return false;
        }
        JSType providedJsType = getJsType(metadata, className);
        if (providedJsType == null) {
          return false;
        }

        JSType jsType = node.getJSType();
        if (jsType == null) {
          return false;
        }
        jsType = jsType.restrictByNotNullOrUndefined();
        return areTypesEquivalentIgnoringGenerics(jsType, providedJsType);
      }
    };
  }

  /**
   * Returns a Matcher that matches any function call.
   */
  public static Matcher functionCall() {
    return functionCall(null);
  }

  /**
   * Returns a Matcher that matches any function call that has the given
   * number of arguments.
   */
  public static Matcher functionCallWithNumArgs(final int numArgs) {
    return new Matcher() {
      @Override public boolean matches(Node node, NodeMetadata metadata) {
        return node.isCall() && (node.getChildCount() - 1) == numArgs;
      }
    };
  }

  /**
   * Returns a Matcher that matches any function call that has the given
   * number of arguments and the given name.
   * @param name The name of the function to match. For non-static functions,
   *     this must be the fully qualified name that includes the type of the
   *     object. For instance: {@code ns.AppContext.prototype.get} will match
   *     {@code appContext.get} and {@code this.get} when called from the
   *     AppContext class.
   */
  public static Matcher functionCallWithNumArgs(final String name, final int numArgs) {
    return allOf(functionCallWithNumArgs(numArgs), functionCall(name));
  }

  /**
   * Returns a Matcher that matches all nodes that are function calls that match
   * the provided name.
   * @param name The name of the function to match. For non-static functions,
   *     this must be the fully qualified name that includes the type of the
   *     object. For instance: {@code ns.AppContext.prototype.get} will match
   *     {@code appContext.get} and {@code this.get} when called from the
   *     AppContext class.
   */
  public static Matcher functionCall(final String name) {
    return new Matcher() {
      @Override public boolean matches(Node node, NodeMetadata metadata) {
        // TODO(mknichel): Handle the case when functions are applied through .call or .apply.
        return node.isCall() && propertyAccess(name).matches(node.getFirstChild(), metadata);
      }
    };
  }

  public static Matcher googRequire(final String namespace) {
    return new Matcher() {
      @Override
      public boolean matches(Node node, NodeMetadata metadata) {
        return functionCall("goog.require").matches(node, metadata)
            && node.getSecondChild().isString()
            && node.getSecondChild().getString().equals(namespace);
      }
    };
  }

  public static Matcher googRequire() {
    return functionCall("goog.require");
  }

  public static Matcher googModuleOrProvide() {
    return anyOf(functionCall("goog.module"), functionCall("goog.provide"));
  }

  /**
   * Returns a Matcher that matches any property access.
   */
  public static Matcher propertyAccess() {
    return propertyAccess(null);
  }

  /**
   * Returns a Matcher that matches nodes representing a GETPROP access of
   * an object property.
   * @param name The name of the property to match. For non-static properties,
   *     this must be the fully qualified name that includes the type of the
   *     object. For instance: {@code ns.AppContext.prototype.root}
   *     will match {@code appContext.root} and {@code this.root} when accessed
   *     from the AppContext.
   */
  public static Matcher propertyAccess(final String name) {
    return new Matcher() {
      @Override
      public boolean matches(Node node, NodeMetadata metadata) {
        if (node.isGetProp()) {
          if (name == null) {
            return true;
          }
          if (node.matchesQualifiedName(name)) {
            return true;
          } else if (name.contains(".prototype.")) {
            return matchesPrototypeInstanceVar(node, metadata, name);
          }
        }
        return false;
      }
    };
  }

  /**
   * Returns a Matcher that matches definitions of any enum.
   */
  public static Matcher enumDefinition() {
    return new Matcher() {
      @Override public boolean matches(Node node, NodeMetadata metadata) {
        JSType jsType = node.getJSType();
        return jsType != null && jsType.isEnumType();
      }
    };
  }

  /**
   * Returns a Matcher that matches definitions of an enum of the given type.
   */
  public static Matcher enumDefinitionOfType(final String type) {
    return new Matcher() {
      @Override public boolean matches(Node node, NodeMetadata metadata) {
        JSType providedJsType = getJsType(metadata, type);
        if (providedJsType == null) {
          return false;
        }
        providedJsType = providedJsType.restrictByNotNullOrUndefined();

        JSType jsType = node.getJSType();
        return jsType != null && jsType.isEnumType() && providedJsType.isEquivalentTo(
            jsType.toMaybeEnumType().getElementsType().getPrimitiveType());
      }
    };
  }

  /**
   * Returns a Matcher that matches an ASSIGN node where the RHS of the assignment matches the given
   * rhsMatcher.
   */
  public static Matcher assignmentWithRhs(final Matcher rhsMatcher) {
    return new Matcher() {
      @Override public boolean matches(Node node, NodeMetadata metadata) {
        return node.isAssign() && rhsMatcher.matches(node.getLastChild(), metadata);
      }
    };
  }

  /**
   * Returns a Matcher that matches a declaration of a variable on the
   * prototype of a class.
   */
  public static Matcher prototypeVariableDeclaration() {
    return matcherForPrototypeDeclaration(false /* requireFunctionType */);
  }

  /**
   * Returns a Matcher that matches a declaration of a method on the
   * prototype of a class.
   */
  public static Matcher prototypeMethodDeclaration() {
    return matcherForPrototypeDeclaration(true /* requireFunctionType */);
  }

  /**
   * Returns a Matcher that matches nodes that contain JS Doc that specify the
   * {@code @type} annotation equivalent to the provided type.
   */
  public static Matcher jsDocType(final String type) {
    return new Matcher() {
      @Override public boolean matches(Node node, NodeMetadata metadata) {
        JSType providedJsType = getJsType(metadata, type);
        if (providedJsType == null) {
          return false;
        }
        providedJsType = providedJsType.restrictByNotNullOrUndefined();
        // The JSDoc for a var declaration is on the VAR node, but the type only
        // exists on the NAME node.
        // TODO(mknichel): Make NodeUtil.getBestJSDoc public and use that.
        JSDocInfo jsDoc = node.getParent().isVar()
            ? node.getParent().getJSDocInfo() : node.getJSDocInfo();
        JSType jsType = node.getJSType();
        return jsDoc != null && jsDoc.hasType() && jsType != null
            && providedJsType.isEquivalentTo(jsType.restrictByNotNullOrUndefined());
      }
    };
  }

  /**
   * Returns a Matcher that matches against properties that are declared in the constructor.
   */
  public static Matcher constructorPropertyDeclaration() {
    return new Matcher() {
      @Override public boolean matches(Node node, NodeMetadata metadata) {
        // This will match against code that looks like:
        // /** @constructor */
        // function constructor() {
        //   this.variable = 3;
        // }
        if (!node.isAssign()
            || !node.getFirstChild().isGetProp()
            || !node.getFirstFirstChild().isThis()) {
          return false;
        }
        while (node != null && !node.isFunction()) {
          node = node.getParent();
        }
        if (node != null && node.isFunction()) {
          JSDocInfo jsDoc = NodeUtil.getBestJSDocInfo(node);
          if (jsDoc != null) {
            return jsDoc.isConstructor();
          }
        }
        return false;
      }
    };
  }

  /**
   * Returns a Matcher that matches against nodes that are declared {@code @private}.
   */
  public static Matcher isPrivate() {
    return new Matcher() {
      @Override public boolean matches(Node node, NodeMetadata metadata) {
        JSDocInfo jsDoc = NodeUtil.getBestJSDocInfo(node);
        if (jsDoc != null) {
          return jsDoc.getVisibility() == Visibility.PRIVATE;
        }
        return false;
      }
    };
  }

  private static JSType getJsType(NodeMetadata metadata, String type) {
    return metadata.getCompiler().getTypeRegistry().getType(type);
  }

  private static JSType getJsType(NodeMetadata metadata, JSTypeNative nativeType) {
    return metadata.getCompiler().getTypeRegistry().getNativeType(nativeType);
  }

  private static boolean areTypesEquivalentIgnoringGenerics(JSType a, JSType b) {
    boolean equivalent = a.isEquivalentTo(b);
    if (equivalent) {
      return true;
    }
    if (a.isTemplatizedType()) {
      return a.toMaybeTemplatizedType().getReferencedType().isEquivalentTo(b);
    }
    return false;
  }

  /**
   * Checks to see if the node represents an access of an instance variable
   * on an object given a prototype declaration of an object. For instance,
   * {@code ns.AppContext.prototype.get} will match {@code appContext.get}
   * or {@code this.get} when accessed from within the AppContext object.
   */
  private static boolean matchesPrototypeInstanceVar(Node node, NodeMetadata metadata,
      String name) {
    String[] parts = name.split(".prototype.");
    String className = parts[0];
    String propertyName = parts[1];
    JSType providedJsType = getJsType(metadata, className);
    if (providedJsType == null) {
      return false;
    }
    JSType jsType = null;
    if (node.hasChildren()) {
      jsType = node.getFirstChild().getJSType();
    }
    if (jsType == null) {
      return false;
    }
    jsType = jsType.restrictByNotNullOrUndefined();
    if (!jsType.isUnknownType()
        && !jsType.isAllType()
        && jsType.isSubtype(providedJsType)) {
      if (node.isName() && propertyName.equals(node.getString())) {
        return true;
      } else if (node.isGetProp()
          && propertyName.equals(node.getLastChild().getString())) {
        return true;
      }
    }
    return false;
  }

  private static Matcher matcherForPrototypeDeclaration(final boolean requireFunctionType) {
    return new Matcher() {
      @Override public boolean matches(Node node, NodeMetadata metadata) {
        // TODO(mknichel): Figure out which node is the best to return for this
        // function: the GETPROP node, or the ASSIGN node when the property is
        // being assigned to.
        // TODO(mknichel): Support matching:
        // foo.prototype = {
        //   bar: 1
        // };
        Node firstChild = node.getFirstChild();
        if (node.isGetProp() && firstChild.isGetProp()
            && firstChild.getLastChild().isString()
            && "prototype".equals(firstChild.getLastChild().getString())) {
          JSType fnJsType = getJsType(metadata, JSTypeNative.FUNCTION_FUNCTION_TYPE);
          JSType jsType = node.getJSType();
          if (jsType == null) {
            return false;
          } else if (requireFunctionType) {
            return jsType.canCastTo(fnJsType);
          } else {
            return !jsType.canCastTo(fnJsType);
          }
        }
        return false;
      }
    };
  }

  // TODO(mknichel): Add matchers for:
  // - Constructor with argument types
  // - Function call with argument types
  // - Function definitions.
  // - Property definitions, references
  // - IsStatic
  // - JsDocMatcher

  /** Prevent instantiation. */
  private Matchers() {}
}