Merge "apilint: decorator-based verifier registration" am: 6e16eb10

    noticed[clazz.fullname] = hash(clazz)

verifiers = {}

def verifier(f):

    verifiers[f.__name__] = f

    return f

@verifier

def verify_constants(clazz):

    """All static final constants must be FOO_NAME style."""

    if re.match("android\.R\.[a-z]+", clazz.fullname): return

            if f.typ in req and f.value is None:

                error(clazz, f, None, "All constants must be defined at compile time")

@verifier

def verify_enums(clazz):

    """Enums are bad, mmkay?"""

    if clazz.extends == "java.lang.Enum" or "enum" in clazz.split:

        error(clazz, None, "F5", "Enums are not allowed")

@verifier

def verify_class_names(clazz):

    """Try catching malformed class names like myMtp or MTPUser."""

    if clazz.fullname.startswith("android.opengl"): return

        error(clazz, None, None, "Don't expose your implementation details")

@verifier

def verify_method_names(clazz):

    """Try catching malformed method names, like Foo() or getMTU()."""

    if clazz.fullname.startswith("android.opengl"): return

            error(clazz, m, "S1", "Method name must start with lowercase char")

@verifier

def verify_callbacks(clazz):

    """Verify Callback classes.

    All callback classes must be abstract.

                error(clazz, m, "L1", "Callback method names must be onFoo() style")

@verifier

def verify_listeners(clazz):

    """Verify Listener classes.

    All Listener classes must be interface.

                error(clazz, m, "L1", "Single listener method name must match class name")

@verifier

def verify_actions(clazz):

    """Verify intent actions.

    All action names must be named ACTION_FOO.

                        error(clazz, f, "C4", "Inconsistent action value; expected '%s'" % (expected))

@verifier

def verify_extras(clazz):

    """Verify intent extras.

    All extra names must be named EXTRA_FOO.

                        error(clazz, f, "C4", "Inconsistent extra value; expected '%s'" % (expected))

@verifier

def verify_equals(clazz):

    """Verify that equals() and hashCode() must be overridden together."""

    eq = False

        error(clazz, None, "M8", "Must override both equals and hashCode; missing one")

@verifier

def verify_parcelable(clazz):

    """Verify that Parcelable objects aren't hiding required bits."""

    if clazz.implements == "android.os.Parcelable":

                error(clazz, c, "FW3", "Parcelable inflation is exposed through CREATOR, not raw constructors")

@verifier

def verify_protected(clazz):

    """Verify that no protected methods or fields are allowed."""

    for m in clazz.methods:

            error(clazz, f, "M7", "Protected fields not allowed; must be public")

@verifier

def verify_fields(clazz):

    """Verify that all exposed fields are final.

    Exposed fields must follow myName style.

                error(clazz, f, "C2", "Constants must be marked static final")

@verifier

def verify_register(clazz):

    """Verify parity of registration methods.

    Callback objects use register/unregister methods.

                error(clazz, m, "L3", "Listener methods should be named add/remove")

@verifier

def verify_sync(clazz):

    """Verify synchronized methods aren't exposed."""

    for m in clazz.methods:

            error(clazz, m, "M5", "Internal locks must not be exposed")

@verifier

def verify_intent_builder(clazz):

    """Verify that Intent builders are createFooIntent() style."""

    if clazz.name == "Intent": return

                warn(clazz, m, "FW1", "Methods creating an Intent should be named createFooIntent()")

@verifier

def verify_helper_classes(clazz):

    """Verify that helper classes are named consistently with what they extend.

    All developer extendable methods should be named onFoo()."""

                    warn(clazz, m, None, "If implemented by developer, should be named onFoo(); otherwise consider marking final")

@verifier

def verify_builder(clazz):

    """Verify builder classes.

    Methods should return the builder to enable chaining."""

        error(clazz, None, None, "Builder should be final")

@verifier

def verify_aidl(clazz):

    """Catch people exposing raw AIDL."""

    if clazz.extends == "android.os.Binder" or clazz.implements == "android.os.IInterface":

        error(clazz, None, None, "Raw AIDL interfaces must not be exposed")

@verifier

def verify_internal(clazz):

    """Catch people exposing internal classes."""

    if clazz.pkg.name.startswith("com.android"):

    "android.util"

])

@verifier

def verify_layering(clazz):

    """Catch package layering violations.

    For example, something in android.os depending on android.app."""

                warn(clazz, m, "FW6", "Method argument type violates package layering")

@verifier

def verify_boolean(clazz):

    """Verifies that boolean accessors are named correctly.

    For example, hasFoo() and setHasFoo()."""

                error_if_exists(sets, m.name, expected, "has" + target)

@verifier

def verify_collections(clazz):

    """Verifies that collection types are interfaces."""

    if clazz.fullname == "android.os.Bundle": return

            if arg in bad:

                error(clazz, m, "CL2", "Argument is concrete collection; must be higher-level interface")

@verifier

def verify_uris(clazz):

    bad = ["java.net.URL", "java.net.URI", "android.net.URL"]

            if arg in bad:

                error(clazz, m, None, "Argument must take android.net.Uri instead of " + arg)

@verifier

def verify_flags(clazz):

    """Verifies that flags are non-overlapping."""

    known = collections.defaultdict(int)

            known[scope] |= val

@verifier

def verify_exception(clazz):

    """Verifies that methods don't throw generic exceptions."""

    for m in clazz.methods:

            if len(m.args) == 0 and t in ["java.lang.IllegalArgumentException", "java.lang.NullPointerException"]:

                warn(clazz, m, "S1", "Methods taking no arguments should throw IllegalStateException")

GOOGLE_IGNORECASE = re.compile("google", re.IGNORECASE)

# Not marked as @verifier, because it is only conditionally applied.

def verify_google(clazz):

    """Verifies that APIs never reference Google."""

                error(clazz, t, None, "Must never reference Google")

@verifier

def verify_bitset(clazz):

    """Verifies that we avoid using heavy BitSet."""

                error(clazz, m, None, "Argument type must not be heavy BitSet")

@verifier

def verify_manager(clazz):

    """Verifies that FooManager is only obtained from Context."""

            error(clazz, m, None, "Managers must always be obtained from Context")

@verifier

def verify_boxed(clazz):

    """Verifies that methods avoid boxed primitives."""

                error(clazz, m, "M11", "Must avoid boxed primitives")

@verifier

def verify_static_utils(clazz):

    """Verifies that helper classes can't be constructed."""

    if clazz.fullname.startswith("android.opengl"): return

        error(clazz, None, None, "Fully-static utility classes must not have constructor")

# @verifier  # Disabled for now

def verify_overload_args(clazz):

    """Verifies that method overloads add new arguments at the end."""

    if clazz.fullname.startswith("android.opengl"): return

                error(clazz, m, "M2", "Expected consistent argument ordering between overloads: %s..." % (", ".join(locked_sig)))

@verifier

def verify_callback_handlers(clazz):

    """Verifies that methods adding listener/callback have overload

    for specifying delivery thread."""

            warn(clazz, f, "L1", "Registration methods should have overload that accepts delivery Executor")

@verifier

def verify_context_first(clazz):

    """Verifies that methods accepting a Context keep it the first argument."""

    examine = clazz.ctors + clazz.methods

                error(clazz, m, "M3", "ContentResolver is distinct, so it must be the first argument")

@verifier

def verify_listener_last(clazz):

    """Verifies that methods accepting a Listener or Callback keep them as last arguments."""

    examine = clazz.ctors + clazz.methods

                warn(clazz, m, "M3", "Listeners should always be at end of argument list")

@verifier

def verify_resource_names(clazz):

    """Verifies that resource names have consistent case."""

    if not re.match("android\.R\.[a-z]+", clazz.fullname): return

            error(clazz, f, "C7", "Expected resource name in this class to be FooBar_Baz style")

@verifier

def verify_files(clazz):

    """Verifies that methods accepting File also accept streams."""

            warn(clazz, m, "M10", "Methods accepting File should also accept FileDescriptor or streams")

@verifier

def verify_manager_list(clazz):

    """Verifies that managers return List<? extends Parcelable> instead of arrays."""

            warn(clazz, m, None, "Methods should return List<? extends Parcelable> instead of Parcelable[] to support ParceledListSlice under the hood")

@verifier

def verify_abstract_inner(clazz):

    """Verifies that abstract inner classes are static."""

            warn(clazz, None, None, "Abstract inner classes should be static to improve testability")

@verifier

def verify_runtime_exceptions(clazz):

    """Verifies that runtime exceptions aren't listed in throws."""

                error(clazz, m, None, "Methods must not mention RuntimeException subclasses in throws clauses")

@verifier

def verify_error(clazz):

    """Verifies that we always use Exception instead of Error."""

    if not clazz.extends: return

        error(clazz, None, None, "Exceptions must be named FooException")

@verifier

def verify_units(clazz):

    """Verifies that we use consistent naming for units."""

            error(clazz, m, None, "Percentage must use ints")

@verifier

def verify_closable(clazz):

    """Verifies that classes are AutoClosable."""

    if "java.lang.AutoCloseable" in clazz.implements_all: return

            return

@verifier

def verify_member_name_not_kotlin_keyword(clazz):

    """Prevent method names which are keywords in Kotlin."""

            error(clazz, f, None, "Field name must not be a Kotlin keyword")

@verifier

def verify_method_name_not_kotlin_operator(clazz):

    """Warn about method names which become operators in Kotlin."""

            unique_binary_op(m, m.name[:-6])  # Remove 'Assign' suffix

@verifier

def verify_collections_over_arrays(clazz):

    """Warn that [] should be Collections."""

                warn(clazz, m, None, "Method argument should be Collection<> (or subclass) instead of raw array")

@verifier

def verify_user_handle(clazz):

    """Methods taking UserHandle should be ForUser or AsUser."""

    if clazz.name.endswith("Listener") or clazz.name.endswith("Callback") or clazz.name.endswith("Callbacks"): return

                 "or 'queryFooForUser'")

@verifier

def verify_params(clazz):

    """Parameter classes should be 'Params'."""

    if clazz.name.endswith("Params"): return

            error(clazz, None, None, "Classes holding a set of parameters should be called 'FooParams'")

@verifier

def verify_services(clazz):

    """Service name should be FOO_BAR_SERVICE = 'foo_bar'."""

    if clazz.fullname != "android.content.Context": return

                error(clazz, f, "C4", "Inconsistent service value; expected '%s'" % (expected))

@verifier

def verify_tense(clazz):

    """Verify tenses of method names."""

    if clazz.fullname.startswith("android.opengl"): return

            warn(clazz, m, None, "Unexpected tense; probably meant 'enabled'")

@verifier

def verify_icu(clazz):

    """Verifies that richer ICU replacements are used."""

    better = {

                warn(clazz, m, None, "Type %s should be replaced with richer ICU type %s" % (arg, better[arg]))

@verifier

def verify_clone(clazz):

    """Verify that clone() isn't implemented; see EJ page 61."""

    for m in clazz.methods:

            error(clazz, m, None, "Provide an explicit copy constructor instead of implementing clone()")

@verifier

def verify_pfd(clazz):

    """Verify that android APIs use PFD over FD."""

    if clazz.fullname == "android.os.FileUtils" or clazz.fullname == "android.system.Os":

            error(clazz, f, "FW11", "Must use ParcelFileDescriptor")

@verifier

def verify_numbers(clazz):

    """Discourage small numbers types like short and byte."""

            if arg in discouraged:

                warn(clazz, m, "FW12", "Should avoid odd sized primitives; use int instead")

PRIMITIVES = {"void", "int", "float", "boolean", "short", "char", "byte", "long", "double"}

@verifier

def verify_nullability(clazz):

    """Catches missing nullability annotations"""

def has_nullability(annotations):

    return "@NonNull" in annotations or "@Nullable" in annotations

@verifier

def verify_singleton(clazz):

    """Catch singleton objects with constructors."""

    if not is_interesting(clazz): return

    verify_constants(clazz)

    verify_enums(clazz)

    verify_class_names(clazz)

    verify_method_names(clazz)

    verify_callbacks(clazz)

    verify_listeners(clazz)

    verify_actions(clazz)

    verify_extras(clazz)

    verify_equals(clazz)

    verify_parcelable(clazz)

    verify_protected(clazz)

    verify_fields(clazz)

    verify_register(clazz)

    verify_sync(clazz)

    verify_intent_builder(clazz)

    verify_helper_classes(clazz)

    verify_builder(clazz)

    verify_aidl(clazz)

    verify_internal(clazz)

    verify_layering(clazz)

    verify_boolean(clazz)

    verify_collections(clazz)

    verify_uris(clazz)

    verify_flags(clazz)

    verify_exception(clazz)

    for v in verifiers.itervalues():

        v(clazz)

    if not ALLOW_GOOGLE: verify_google(clazz)

    verify_bitset(clazz)

    verify_manager(clazz)

    verify_boxed(clazz)

    verify_static_utils(clazz)

    # verify_overload_args(clazz)

    verify_callback_handlers(clazz)

    verify_context_first(clazz)

    verify_listener_last(clazz)

    verify_resource_names(clazz)

    verify_files(clazz)

    verify_manager_list(clazz)

    verify_abstract_inner(clazz)

    verify_runtime_exceptions(clazz)

    verify_error(clazz)

    verify_units(clazz)

    verify_closable(clazz)

    verify_member_name_not_kotlin_keyword(clazz)

    verify_method_name_not_kotlin_operator(clazz)

    verify_collections_over_arrays(clazz)

    verify_user_handle(clazz)

    verify_params(clazz)

    verify_services(clazz)

    verify_tense(clazz)

    verify_icu(clazz)

    verify_clone(clazz)

    verify_pfd(clazz)

    verify_numbers(clazz)

    verify_singleton(clazz)

    verify_nullability(clazz)

def examine_stream(stream, base_stream=None, in_classes_with_base=[], out_classes_with_base=None):