tools/apilint/apilint.py

   1 #!/usr/bin/env python
   2
   3 # Copyright (C) 2014 The Android Open Source Project
   4 #
   5 # Licensed under the Apache License, Version 2.0 (the 'License');
   6 # you may not use this file except in compliance with the License.
   7 # You may obtain a copy of the License at
   8 #
   9 #      http://www.apache.org/licenses/LICENSE-2.0
  10 #
  11 # Unless required by applicable law or agreed to in writing, software
  12 # distributed under the License is distributed on an 'AS IS' BASIS,
  13 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14 # See the License for the specific language governing permissions and
  15 # limitations under the License.
  16
  17 """
  18 Enforces common Android public API design patterns.  It ignores lint messages from
  19 a previous API level, if provided.
  20
  21 Usage: apilint.py current.txt
  22 Usage: apilint.py current.txt previous.txt
  23
  24 You can also splice in blame details like this:
  25 $ git blame api/current.txt -t -e > /tmp/currentblame.txt
  26 $ apilint.py /tmp/currentblame.txt previous.txt --no-color
  27 """
  28
  29 import re, sys, collections, traceback, argparse
  30
  31
  32 BLACK, RED, GREEN, YELLOW, BLUE, MAGENTA, CYAN, WHITE = range(8)
  33
  34 ALLOW_GOOGLE = False
  35 USE_COLOR = True
  36
  37 def format(fg=None, bg=None, bright=False, bold=False, dim=False, reset=False):
  38     # manually derived from http://en.wikipedia.org/wiki/ANSI_escape_code#Codes
  39     if not USE_COLOR: return ""
  40     codes = []
  41     if reset: codes.append("0")
  42     else:
  43         if not fg is None: codes.append("3%d" % (fg))
  44         if not bg is None:
  45             if not bright: codes.append("4%d" % (bg))
  46             else: codes.append("10%d" % (bg))
  47         if bold: codes.append("1")
  48         elif dim: codes.append("2")
  49         else: codes.append("22")
  50     return "\033[%sm" % (";".join(codes))
  51
  52
  53 class Field():
  54     def __init__(self, clazz, line, raw, blame):
  55         self.clazz = clazz
  56         self.line = line
  57         self.raw = raw.strip(" {;")
  58         self.blame = blame
  59
  60         raw = raw.split()
  61         self.split = list(raw)
  62
  63         for r in ["field", "volatile", "transient", "public", "protected", "static", "final", "deprecated"]:
  64             while r in raw: raw.remove(r)
  65
  66         self.typ = raw[0]
  67         self.name = raw[1].strip(";")
  68         if len(raw) >= 4 and raw[2] == "=":
  69             self.value = raw[3].strip(';"')
  70         else:
  71             self.value = None
  72
  73         self.ident = self.raw.replace(" deprecated ", " ")
  74
  75     def __repr__(self):
  76         return self.raw
  77
  78
  79 class Method():
  80     def __init__(self, clazz, line, raw, blame):
  81         self.clazz = clazz
  82         self.line = line
  83         self.raw = raw.strip(" {;")
  84         self.blame = blame
  85
  86         # drop generics for now
  87         raw = re.sub("<.+?>", "", raw)
  88
  89         raw = re.split("[\s(),;]+", raw)
  90         for r in ["", ";"]:
  91             while r in raw: raw.remove(r)
  92         self.split = list(raw)
  93
  94         for r in ["method", "public", "protected", "static", "final", "deprecated", "abstract"]:
  95             while r in raw: raw.remove(r)
  96
  97         self.typ = raw[0]
  98         self.name = raw[1]
  99         self.args = []
 100         for r in raw[2:]:
 101             if r == "throws": break
 102             self.args.append(r)
 103
 104         # identity for compat purposes
 105         ident = self.raw
 106         ident = ident.replace(" deprecated ", " ")
 107         ident = ident.replace(" synchronized ", " ")
 108         ident = re.sub("<.+?>", "", ident)
 109         if " throws " in ident:
 110             ident = ident[:ident.index(" throws ")]
 111         self.ident = ident
 112
 113     def __repr__(self):
 114         return self.raw
 115
 116
 117 class Class():
 118     def __init__(self, pkg, line, raw, blame):
 119         self.pkg = pkg
 120         self.line = line
 121         self.raw = raw.strip(" {;")
 122         self.blame = blame
 123         self.ctors = []
 124         self.fields = []
 125         self.methods = []
 126
 127         raw = raw.split()
 128         self.split = list(raw)
 129         if "class" in raw:
 130             self.fullname = raw[raw.index("class")+1]
 131         elif "interface" in raw:
 132             self.fullname = raw[raw.index("interface")+1]
 133         else:
 134             raise ValueError("Funky class type %s" % (self.raw))
 135
 136         if "extends" in raw:
 137             self.extends = raw[raw.index("extends")+1]
 138             self.extends_path = self.extends.split(".")
 139         else:
 140             self.extends = None
 141             self.extends_path = []
 142
 143         self.fullname = self.pkg.name + "." + self.fullname
 144         self.fullname_path = self.fullname.split(".")
 145
 146         self.name = self.fullname[self.fullname.rindex(".")+1:]
 147
 148     def __repr__(self):
 149         return self.raw
 150
 151
 152 class Package():
 153     def __init__(self, line, raw, blame):
 154         self.line = line
 155         self.raw = raw.strip(" {;")
 156         self.blame = blame
 157
 158         raw = raw.split()
 159         self.name = raw[raw.index("package")+1]
 160         self.name_path = self.name.split(".")
 161
 162     def __repr__(self):
 163         return self.raw
 164
 165
 166 def _parse_stream(f, clazz_cb=None):
 167     line = 0
 168     api = {}
 169     pkg = None
 170     clazz = None
 171     blame = None
 172
 173     re_blame = re.compile("^([a-z0-9]{7,}) \(<([^>]+)>.+?\) (.+?)$")
 174     for raw in f:
 175         line += 1
 176         raw = raw.rstrip()
 177         match = re_blame.match(raw)
 178         if match is not None:
 179             blame = match.groups()[0:2]
 180             raw = match.groups()[2]
 181         else:
 182             blame = None
 183
 184         if raw.startswith("package"):
 185             pkg = Package(line, raw, blame)
 186         elif raw.startswith("  ") and raw.endswith("{"):
 187             # When provided with class callback, we treat as incremental
 188             # parse and don't build up entire API
 189             if clazz and clazz_cb:
 190                 clazz_cb(clazz)
 191             clazz = Class(pkg, line, raw, blame)
 192             if not clazz_cb:
 193                 api[clazz.fullname] = clazz
 194         elif raw.startswith("    ctor"):
 195             clazz.ctors.append(Method(clazz, line, raw, blame))
 196         elif raw.startswith("    method"):
 197             clazz.methods.append(Method(clazz, line, raw, blame))
 198         elif raw.startswith("    field"):
 199             clazz.fields.append(Field(clazz, line, raw, blame))
 200
 201     # Handle last trailing class
 202     if clazz and clazz_cb:
 203         clazz_cb(clazz)
 204
 205     return api
 206
 207
 208 class Failure():
 209     def __init__(self, sig, clazz, detail, error, rule, msg):
 210         self.sig = sig
 211         self.error = error
 212         self.rule = rule
 213         self.msg = msg
 214
 215         if error:
 216             self.head = "Error %s" % (rule) if rule else "Error"
 217             dump = "%s%s:%s %s" % (format(fg=RED, bg=BLACK, bold=True), self.head, format(reset=True), msg)
 218         else:
 219             self.head = "Warning %s" % (rule) if rule else "Warning"
 220             dump = "%s%s:%s %s" % (format(fg=YELLOW, bg=BLACK, bold=True), self.head, format(reset=True), msg)
 221
 222         self.line = clazz.line
 223         blame = clazz.blame
 224         if detail is not None:
 225             dump += "\n    in " + repr(detail)
 226             self.line = detail.line
 227             blame = detail.blame
 228         dump += "\n    in " + repr(clazz)
 229         dump += "\n    in " + repr(clazz.pkg)
 230         dump += "\n    at line " + repr(self.line)
 231         if blame is not None:
 232             dump += "\n    last modified by %s in %s" % (blame[1], blame[0])
 233
 234         self.dump = dump
 235
 236     def __repr__(self):
 237         return self.dump
 238
 239
 240 failures = {}
 241
 242 def _fail(clazz, detail, error, rule, msg):
 243     """Records an API failure to be processed later."""
 244     global failures
 245
 246     sig = "%s-%s-%s" % (clazz.fullname, repr(detail), msg)
 247     sig = sig.replace(" deprecated ", " ")
 248
 249     failures[sig] = Failure(sig, clazz, detail, error, rule, msg)
 250
 251
 252 def warn(clazz, detail, rule, msg):
 253     _fail(clazz, detail, False, rule, msg)
 254
 255 def error(clazz, detail, rule, msg):
 256     _fail(clazz, detail, True, rule, msg)
 257
 258
 259 def verify_constants(clazz):
 260     """All static final constants must be FOO_NAME style."""
 261     if re.match("android\.R\.[a-z]+", clazz.fullname): return
 262
 263     for f in clazz.fields:
 264         if "static" in f.split and "final" in f.split:
 265             if re.match("[A-Z0-9_]+", f.name) is None:
 266                 error(clazz, f, "C2", "Constant field names must be FOO_NAME")
 267
 268
 269 def verify_enums(clazz):
 270     """Enums are bad, mmkay?"""
 271     if "extends java.lang.Enum" in clazz.raw:
 272         error(clazz, None, "F5", "Enums are not allowed")
 273
 274
 275 def verify_class_names(clazz):
 276     """Try catching malformed class names like myMtp or MTPUser."""
 277     if clazz.fullname.startswith("android.opengl"): return
 278     if clazz.fullname.startswith("android.renderscript"): return
 279     if re.match("android\.R\.[a-z]+", clazz.fullname): return
 280
 281     if re.search("[A-Z]{2,}", clazz.name) is not None:
 282         warn(clazz, None, "S1", "Class names with acronyms should be Mtp not MTP")
 283     if re.match("[^A-Z]", clazz.name):
 284         error(clazz, None, "S1", "Class must start with uppercase char")
 285
 286
 287 def verify_method_names(clazz):
 288     """Try catching malformed method names, like Foo() or getMTU()."""
 289     if clazz.fullname.startswith("android.opengl"): return
 290     if clazz.fullname.startswith("android.renderscript"): return
 291     if clazz.fullname == "android.system.OsConstants": return
 292
 293     for m in clazz.methods:
 294         if re.search("[A-Z]{2,}", m.name) is not None:
 295             warn(clazz, m, "S1", "Method names with acronyms should be getMtu() instead of getMTU()")
 296         if re.match("[^a-z]", m.name):
 297             error(clazz, m, "S1", "Method name must start with lowercase char")
 298
 299
 300 def verify_callbacks(clazz):
 301     """Verify Callback classes.
 302     All callback classes must be abstract.
 303     All methods must follow onFoo() naming style."""
 304     if clazz.fullname == "android.speech.tts.SynthesisCallback": return
 305
 306     if clazz.name.endswith("Callbacks"):
 307         error(clazz, None, "L1", "Callback class names should be singular")
 308     if clazz.name.endswith("Observer"):
 309         warn(clazz, None, "L1", "Class should be named FooCallback")
 310
 311     if clazz.name.endswith("Callback"):
 312         if "interface" in clazz.split:
 313             error(clazz, None, "CL3", "Callbacks must be abstract class to enable extension in future API levels")
 314
 315         for m in clazz.methods:
 316             if not re.match("on[A-Z][a-z]*", m.name):
 317                 error(clazz, m, "L1", "Callback method names must be onFoo() style")
 318
 319
 320 def verify_listeners(clazz):
 321     """Verify Listener classes.
 322     All Listener classes must be interface.
 323     All methods must follow onFoo() naming style.
 324     If only a single method, it must match class name:
 325         interface OnFooListener { void onFoo() }"""
 326
 327     if clazz.name.endswith("Listener"):
 328         if " abstract class " in clazz.raw:
 329             error(clazz, None, "L1", "Listeners should be an interface, or otherwise renamed Callback")
 330
 331         for m in clazz.methods:
 332             if not re.match("on[A-Z][a-z]*", m.name):
 333                 error(clazz, m, "L1", "Listener method names must be onFoo() style")
 334
 335         if len(clazz.methods) == 1 and clazz.name.startswith("On"):
 336             m = clazz.methods[0]
 337             if (m.name + "Listener").lower() != clazz.name.lower():
 338                 error(clazz, m, "L1", "Single listener method name must match class name")
 339
 340
 341 def verify_actions(clazz):
 342     """Verify intent actions.
 343     All action names must be named ACTION_FOO.
 344     All action values must be scoped by package and match name:
 345         package android.foo {
 346             String ACTION_BAR = "android.foo.action.BAR";
 347         }"""
 348     for f in clazz.fields:
 349         if f.value is None: continue
 350         if f.name.startswith("EXTRA_"): continue
 351         if f.name == "SERVICE_INTERFACE" or f.name == "PROVIDER_INTERFACE": continue
 352
 353         if "static" in f.split and "final" in f.split and f.typ == "java.lang.String":
 354             if "_ACTION" in f.name or "ACTION_" in f.name or ".action." in f.value.lower():
 355                 if not f.name.startswith("ACTION_"):
 356                     error(clazz, f, "C3", "Intent action constant name must be ACTION_FOO")
 357                 else:
 358                     if clazz.fullname == "android.content.Intent":
 359                         prefix = "android.intent.action"
 360                     elif clazz.fullname == "android.provider.Settings":
 361                         prefix = "android.settings"
 362                     elif clazz.fullname == "android.app.admin.DevicePolicyManager" or clazz.fullname == "android.app.admin.DeviceAdminReceiver":
 363                         prefix = "android.app.action"
 364                     else:
 365                         prefix = clazz.pkg.name + ".action"
 366                     expected = prefix + "." + f.name[7:]
 367                     if f.value != expected:
 368                         error(clazz, f, "C4", "Inconsistent action value; expected %s" % (expected))
 369
 370
 371 def verify_extras(clazz):
 372     """Verify intent extras.
 373     All extra names must be named EXTRA_FOO.
 374     All extra values must be scoped by package and match name:
 375         package android.foo {
 376             String EXTRA_BAR = "android.foo.extra.BAR";
 377         }"""
 378     if clazz.fullname == "android.app.Notification": return
 379     if clazz.fullname == "android.appwidget.AppWidgetManager": return
 380
 381     for f in clazz.fields:
 382         if f.value is None: continue
 383         if f.name.startswith("ACTION_"): continue
 384
 385         if "static" in f.split and "final" in f.split and f.typ == "java.lang.String":
 386             if "_EXTRA" in f.name or "EXTRA_" in f.name or ".extra" in f.value.lower():
 387                 if not f.name.startswith("EXTRA_"):
 388                     error(clazz, f, "C3", "Intent extra must be EXTRA_FOO")
 389                 else:
 390                     if clazz.pkg.name == "android.content" and clazz.name == "Intent":
 391                         prefix = "android.intent.extra"
 392                     elif clazz.pkg.name == "android.app.admin":
 393                         prefix = "android.app.extra"
 394                     else:
 395                         prefix = clazz.pkg.name + ".extra"
 396                     expected = prefix + "." + f.name[6:]
 397                     if f.value != expected:
 398                         error(clazz, f, "C4", "Inconsistent extra value; expected %s" % (expected))
 399
 400
 401 def verify_equals(clazz):
 402     """Verify that equals() and hashCode() must be overridden together."""
 403     methods = [ m.name for m in clazz.methods ]
 404     eq = "equals" in methods
 405     hc = "hashCode" in methods
 406     if eq != hc:
 407         error(clazz, None, "M8", "Must override both equals and hashCode; missing one")
 408
 409
 410 def verify_parcelable(clazz):
 411     """Verify that Parcelable objects aren't hiding required bits."""
 412     if "implements android.os.Parcelable" in clazz.raw:
 413         creator = [ i for i in clazz.fields if i.name == "CREATOR" ]
 414         write = [ i for i in clazz.methods if i.name == "writeToParcel" ]
 415         describe = [ i for i in clazz.methods if i.name == "describeContents" ]
 416
 417         if len(creator) == 0 or len(write) == 0 or len(describe) == 0:
 418             error(clazz, None, "FW3", "Parcelable requires CREATOR, writeToParcel, and describeContents; missing one")
 419
 420
 421 def verify_protected(clazz):
 422     """Verify that no protected methods or fields are allowed."""
 423     for m in clazz.methods:
 424         if "protected" in m.split:
 425             error(clazz, m, "M7", "Protected methods not allowed; must be public")
 426     for f in clazz.fields:
 427         if "protected" in f.split:
 428             error(clazz, f, "M7", "Protected fields not allowed; must be public")
 429
 430
 431 def verify_fields(clazz):
 432     """Verify that all exposed fields are final.
 433     Exposed fields must follow myName style.
 434     Catch internal mFoo objects being exposed."""
 435
 436     IGNORE_BARE_FIELDS = [
 437         "android.app.ActivityManager.RecentTaskInfo",
 438         "android.app.Notification",
 439         "android.content.pm.ActivityInfo",
 440         "android.content.pm.ApplicationInfo",
 441         "android.content.pm.FeatureGroupInfo",
 442         "android.content.pm.InstrumentationInfo",
 443         "android.content.pm.PackageInfo",
 444         "android.content.pm.PackageItemInfo",
 445         "android.os.Message",
 446         "android.system.StructPollfd",
 447     ]
 448
 449     for f in clazz.fields:
 450         if not "final" in f.split:
 451             if clazz.fullname in IGNORE_BARE_FIELDS:
 452                 pass
 453             elif clazz.fullname.endswith("LayoutParams"):
 454                 pass
 455             elif clazz.fullname.startswith("android.util.Mutable"):
 456                 pass
 457             else:
 458                 error(clazz, f, "F2", "Bare fields must be marked final, or add accessors if mutable")
 459
 460         if not "static" in f.split:
 461             if not re.match("[a-z]([a-zA-Z]+)?", f.name):
 462                 error(clazz, f, "S1", "Non-static fields must be named using myField style")
 463
 464         if re.match("[ms][A-Z]", f.name):
 465             error(clazz, f, "F1", "Internal objects must not be exposed")
 466
 467         if re.match("[A-Z_]+", f.name):
 468             if "static" not in f.split or "final" not in f.split:
 469                 error(clazz, f, "C2", "Constants must be marked static final")
 470
 471
 472 def verify_register(clazz):
 473     """Verify parity of registration methods.
 474     Callback objects use register/unregister methods.
 475     Listener objects use add/remove methods."""
 476     methods = [ m.name for m in clazz.methods ]
 477     for m in clazz.methods:
 478         if "Callback" in m.raw:
 479             if m.name.startswith("register"):
 480                 other = "unregister" + m.name[8:]
 481                 if other not in methods:
 482                     error(clazz, m, "L2", "Missing unregister method")
 483             if m.name.startswith("unregister"):
 484                 other = "register" + m.name[10:]
 485                 if other not in methods:
 486                     error(clazz, m, "L2", "Missing register method")
 487
 488             if m.name.startswith("add") or m.name.startswith("remove"):
 489                 error(clazz, m, "L3", "Callback methods should be named register/unregister")
 490
 491         if "Listener" in m.raw:
 492             if m.name.startswith("add"):
 493                 other = "remove" + m.name[3:]
 494                 if other not in methods:
 495                     error(clazz, m, "L2", "Missing remove method")
 496             if m.name.startswith("remove") and not m.name.startswith("removeAll"):
 497                 other = "add" + m.name[6:]
 498                 if other not in methods:
 499                     error(clazz, m, "L2", "Missing add method")
 500
 501             if m.name.startswith("register") or m.name.startswith("unregister"):
 502                 error(clazz, m, "L3", "Listener methods should be named add/remove")
 503
 504
 505 def verify_sync(clazz):
 506     """Verify synchronized methods aren't exposed."""
 507     for m in clazz.methods:
 508         if "synchronized" in m.split:
 509             error(clazz, m, "M5", "Internal locks must not be exposed")
 510
 511
 512 def verify_intent_builder(clazz):
 513     """Verify that Intent builders are createFooIntent() style."""
 514     if clazz.name == "Intent": return
 515
 516     for m in clazz.methods:
 517         if m.typ == "android.content.Intent":
 518             if m.name.startswith("create") and m.name.endswith("Intent"):
 519                 pass
 520             else:
 521                 warn(clazz, m, "FW1", "Methods creating an Intent should be named createFooIntent()")
 522
 523
 524 def verify_helper_classes(clazz):
 525     """Verify that helper classes are named consistently with what they extend.
 526     All developer extendable methods should be named onFoo()."""
 527     test_methods = False
 528     if "extends android.app.Service" in clazz.raw:
 529         test_methods = True
 530         if not clazz.name.endswith("Service"):
 531             error(clazz, None, "CL4", "Inconsistent class name; should be FooService")
 532
 533         found = False
 534         for f in clazz.fields:
 535             if f.name == "SERVICE_INTERFACE":
 536                 found = True
 537                 if f.value != clazz.fullname:
 538                     error(clazz, f, "C4", "Inconsistent interface constant; expected %s" % (clazz.fullname))
 539
 540     if "extends android.content.ContentProvider" in clazz.raw:
 541         test_methods = True
 542         if not clazz.name.endswith("Provider"):
 543             error(clazz, None, "CL4", "Inconsistent class name; should be FooProvider")
 544
 545         found = False
 546         for f in clazz.fields:
 547             if f.name == "PROVIDER_INTERFACE":
 548                 found = True
 549                 if f.value != clazz.fullname:
 550                     error(clazz, f, "C4", "Inconsistent interface constant; expected %s" % (clazz.fullname))
 551
 552     if "extends android.content.BroadcastReceiver" in clazz.raw:
 553         test_methods = True
 554         if not clazz.name.endswith("Receiver"):
 555             error(clazz, None, "CL4", "Inconsistent class name; should be FooReceiver")
 556
 557     if "extends android.app.Activity" in clazz.raw:
 558         test_methods = True
 559         if not clazz.name.endswith("Activity"):
 560             error(clazz, None, "CL4", "Inconsistent class name; should be FooActivity")
 561
 562     if test_methods:
 563         for m in clazz.methods:
 564             if "final" in m.split: continue
 565             if not re.match("on[A-Z]", m.name):
 566                 if "abstract" in m.split:
 567                     warn(clazz, m, None, "Methods implemented by developers should be named onFoo()")
 568                 else:
 569                     warn(clazz, m, None, "If implemented by developer, should be named onFoo(); otherwise consider marking final")
 570
 571
 572 def verify_builder(clazz):
 573     """Verify builder classes.
 574     Methods should return the builder to enable chaining."""
 575     if " extends " in clazz.raw: return
 576     if not clazz.name.endswith("Builder"): return
 577
 578     if clazz.name != "Builder":
 579         warn(clazz, None, None, "Builder should be defined as inner class")
 580
 581     has_build = False
 582     for m in clazz.methods:
 583         if m.name == "build":
 584             has_build = True
 585             continue
 586
 587         if m.name.startswith("get"): continue
 588         if m.name.startswith("clear"): continue
 589
 590         if m.name.startswith("with"):
 591             warn(clazz, m, None, "Builder methods names should use setFoo() style")
 592
 593         if m.name.startswith("set"):
 594             if not m.typ.endswith(clazz.fullname):
 595                 warn(clazz, m, "M4", "Methods must return the builder object")
 596
 597     if not has_build:
 598         warn(clazz, None, None, "Missing build() method")
 599
 600
 601 def verify_aidl(clazz):
 602     """Catch people exposing raw AIDL."""
 603     if "extends android.os.Binder" in clazz.raw or "implements android.os.IInterface" in clazz.raw:
 604         error(clazz, None, None, "Raw AIDL interfaces must not be exposed")
 605
 606
 607 def verify_internal(clazz):
 608     """Catch people exposing internal classes."""
 609     if clazz.pkg.name.startswith("com.android"):
 610         error(clazz, None, None, "Internal classes must not be exposed")
 611
 612
 613 def verify_layering(clazz):
 614     """Catch package layering violations.
 615     For example, something in android.os depending on android.app."""
 616     ranking = [
 617         ["android.service","android.accessibilityservice","android.inputmethodservice","android.printservice","android.appwidget","android.webkit","android.preference","android.gesture","android.print"],
 618         "android.app",
 619         "android.widget",
 620         "android.view",
 621         "android.animation",
 622         "android.provider",
 623         ["android.content","android.graphics.drawable"],
 624         "android.database",
 625         "android.graphics",
 626         "android.text",
 627         "android.os",
 628         "android.util"
 629     ]
 630
 631     def rank(p):
 632         for i in range(len(ranking)):
 633             if isinstance(ranking[i], list):
 634                 for j in ranking[i]:
 635                     if p.startswith(j): return i
 636             else:
 637                 if p.startswith(ranking[i]): return i
 638
 639     cr = rank(clazz.pkg.name)
 640     if cr is None: return
 641
 642     for f in clazz.fields:
 643         ir = rank(f.typ)
 644         if ir and ir < cr:
 645             warn(clazz, f, "FW6", "Field type violates package layering")
 646
 647     for m in clazz.methods:
 648         ir = rank(m.typ)
 649         if ir and ir < cr:
 650             warn(clazz, m, "FW6", "Method return type violates package layering")
 651         for arg in m.args:
 652             ir = rank(arg)
 653             if ir and ir < cr:
 654                 warn(clazz, m, "FW6", "Method argument type violates package layering")
 655
 656
 657 def verify_boolean(clazz):
 658     """Verifies that boolean accessors are named correctly.
 659     For example, hasFoo() and setHasFoo()."""
 660
 661     def is_get(m): return len(m.args) == 0 and m.typ == "boolean"
 662     def is_set(m): return len(m.args) == 1 and m.args[0] == "boolean"
 663
 664     gets = [ m for m in clazz.methods if is_get(m) ]
 665     sets = [ m for m in clazz.methods if is_set(m) ]
 666
 667     def error_if_exists(methods, trigger, expected, actual):
 668         for m in methods:
 669             if m.name == actual:
 670                 error(clazz, m, "M6", "Symmetric method for %s must be named %s" % (trigger, expected))
 671
 672     for m in clazz.methods:
 673         if is_get(m):
 674             if re.match("is[A-Z]", m.name):
 675                 target = m.name[2:]
 676                 expected = "setIs" + target
 677                 error_if_exists(sets, m.name, expected, "setHas" + target)
 678             elif re.match("has[A-Z]", m.name):
 679                 target = m.name[3:]
 680                 expected = "setHas" + target
 681                 error_if_exists(sets, m.name, expected, "setIs" + target)
 682                 error_if_exists(sets, m.name, expected, "set" + target)
 683             elif re.match("get[A-Z]", m.name):
 684                 target = m.name[3:]
 685                 expected = "set" + target
 686                 error_if_exists(sets, m.name, expected, "setIs" + target)
 687                 error_if_exists(sets, m.name, expected, "setHas" + target)
 688
 689         if is_set(m):
 690             if re.match("set[A-Z]", m.name):
 691                 target = m.name[3:]
 692                 expected = "get" + target
 693                 error_if_exists(sets, m.name, expected, "is" + target)
 694                 error_if_exists(sets, m.name, expected, "has" + target)
 695
 696
 697 def verify_collections(clazz):
 698     """Verifies that collection types are interfaces."""
 699     if clazz.fullname == "android.os.Bundle": return
 700
 701     bad = ["java.util.Vector", "java.util.LinkedList", "java.util.ArrayList", "java.util.Stack",
 702            "java.util.HashMap", "java.util.HashSet", "android.util.ArraySet", "android.util.ArrayMap"]
 703     for m in clazz.methods:
 704         if m.typ in bad:
 705             error(clazz, m, "CL2", "Return type is concrete collection; must be higher-level interface")
 706         for arg in m.args:
 707             if arg in bad:
 708                 error(clazz, m, "CL2", "Argument is concrete collection; must be higher-level interface")
 709
 710
 711 def verify_flags(clazz):
 712     """Verifies that flags are non-overlapping."""
 713     known = collections.defaultdict(int)
 714     for f in clazz.fields:
 715         if "FLAG_" in f.name:
 716             try:
 717                 val = int(f.value)
 718             except:
 719                 continue
 720
 721             scope = f.name[0:f.name.index("FLAG_")]
 722             if val & known[scope]:
 723                 warn(clazz, f, "C1", "Found overlapping flag constant value")
 724             known[scope] |= val
 725
 726
 727 def verify_exception(clazz):
 728     """Verifies that methods don't throw generic exceptions."""
 729     for m in clazz.methods:
 730         if "throws java.lang.Exception" in m.raw or "throws java.lang.Throwable" in m.raw or "throws java.lang.Error" in m.raw:
 731             error(clazz, m, "S1", "Methods must not throw generic exceptions")
 732
 733
 734 def verify_google(clazz):
 735     """Verifies that APIs never reference Google."""
 736
 737     if re.search("google", clazz.raw, re.IGNORECASE):
 738         error(clazz, None, None, "Must never reference Google")
 739
 740     test = []
 741     test.extend(clazz.ctors)
 742     test.extend(clazz.fields)
 743     test.extend(clazz.methods)
 744
 745     for t in test:
 746         if re.search("google", t.raw, re.IGNORECASE):
 747             error(clazz, t, None, "Must never reference Google")
 748
 749
 750 def verify_bitset(clazz):
 751     """Verifies that we avoid using heavy BitSet."""
 752
 753     for f in clazz.fields:
 754         if f.typ == "java.util.BitSet":
 755             error(clazz, f, None, "Field type must not be heavy BitSet")
 756
 757     for m in clazz.methods:
 758         if m.typ == "java.util.BitSet":
 759             error(clazz, m, None, "Return type must not be heavy BitSet")
 760         for arg in m.args:
 761             if arg == "java.util.BitSet":
 762                 error(clazz, m, None, "Argument type must not be heavy BitSet")
 763
 764
 765 def verify_manager(clazz):
 766     """Verifies that FooManager is only obtained from Context."""
 767
 768     if not clazz.name.endswith("Manager"): return
 769
 770     for c in clazz.ctors:
 771         error(clazz, c, None, "Managers must always be obtained from Context; no direct constructors")
 772
 773
 774 def verify_boxed(clazz):
 775     """Verifies that methods avoid boxed primitives."""
 776
 777     boxed = ["java.lang.Number","java.lang.Byte","java.lang.Double","java.lang.Float","java.lang.Integer","java.lang.Long","java.lang.Short"]
 778
 779     for c in clazz.ctors:
 780         for arg in c.args:
 781             if arg in boxed:
 782                 error(clazz, c, "M11", "Must avoid boxed primitives")
 783
 784     for f in clazz.fields:
 785         if f.typ in boxed:
 786             error(clazz, f, "M11", "Must avoid boxed primitives")
 787
 788     for m in clazz.methods:
 789         if m.typ in boxed:
 790             error(clazz, m, "M11", "Must avoid boxed primitives")
 791         for arg in m.args:
 792             if arg in boxed:
 793                 error(clazz, m, "M11", "Must avoid boxed primitives")
 794
 795
 796 def verify_static_utils(clazz):
 797     """Verifies that helper classes can't be constructed."""
 798     if clazz.fullname.startswith("android.opengl"): return
 799     if re.match("android\.R\.[a-z]+", clazz.fullname): return
 800
 801     if len(clazz.fields) > 0: return
 802     if len(clazz.methods) == 0: return
 803
 804     for m in clazz.methods:
 805         if "static" not in m.split:
 806             return
 807
 808     # At this point, we have no fields, and all methods are static
 809     if len(clazz.ctors) > 0:
 810         error(clazz, None, None, "Fully-static utility classes must not have constructor")
 811
 812
 813 def verify_overload_args(clazz):
 814     """Verifies that method overloads add new arguments at the end."""
 815     if clazz.fullname.startswith("android.opengl"): return
 816
 817     overloads = collections.defaultdict(list)
 818     for m in clazz.methods:
 819         if "deprecated" in m.split: continue
 820         overloads[m.name].append(m)
 821
 822     for name, methods in overloads.items():
 823         if len(methods) <= 1: continue
 824
 825         # Look for arguments common across all overloads
 826         def cluster(args):
 827             count = collections.defaultdict(int)
 828             res = set()
 829             for i in range(len(args)):
 830                 a = args[i]
 831                 res.add("%s#%d" % (a, count[a]))
 832                 count[a] += 1
 833             return res
 834
 835         common_args = cluster(methods[0].args)
 836         for m in methods:
 837             common_args = common_args & cluster(m.args)
 838
 839         if len(common_args) == 0: continue
 840
 841         # Require that all common arguments are present at start of signature
 842         locked_sig = None
 843         for m in methods:
 844             sig = m.args[0:len(common_args)]
 845             if not common_args.issubset(cluster(sig)):
 846                 warn(clazz, m, "M2", "Expected common arguments [%s] at beginning of overloaded method" % (", ".join(common_args)))
 847             elif not locked_sig:
 848                 locked_sig = sig
 849             elif locked_sig != sig:
 850                 error(clazz, m, "M2", "Expected consistent argument ordering between overloads: %s..." % (", ".join(locked_sig)))
 851
 852
 853 def verify_callback_handlers(clazz):
 854     """Verifies that methods adding listener/callback have overload
 855     for specifying delivery thread."""
 856
 857     # Ignore UI packages which assume main thread
 858     skip = [
 859         "animation",
 860         "view",
 861         "graphics",
 862         "transition",
 863         "widget",
 864         "webkit",
 865     ]
 866     for s in skip:
 867         if s in clazz.pkg.name_path: return
 868         if s in clazz.extends_path: return
 869
 870     # Ignore UI classes which assume main thread
 871     if "app" in clazz.pkg.name_path or "app" in clazz.extends_path:
 872         for s in ["ActionBar","Dialog","Application","Activity","Fragment","Loader"]:
 873             if s in clazz.fullname: return
 874     if "content" in clazz.pkg.name_path or "content" in clazz.extends_path:
 875         for s in ["Loader"]:
 876             if s in clazz.fullname: return
 877
 878     found = {}
 879     by_name = collections.defaultdict(list)
 880     for m in clazz.methods:
 881         if m.name.startswith("unregister"): continue
 882         if m.name.startswith("remove"): continue
 883         if re.match("on[A-Z]+", m.name): continue
 884
 885         by_name[m.name].append(m)
 886
 887         for a in m.args:
 888             if a.endswith("Listener") or a.endswith("Callback") or a.endswith("Callbacks"):
 889                 found[m.name] = m
 890
 891     for f in found.values():
 892         takes_handler = False
 893         for m in by_name[f.name]:
 894             if "android.os.Handler" in m.args:
 895                 takes_handler = True
 896         if not takes_handler:
 897             warn(clazz, f, "L1", "Registration methods should have overload that accepts delivery Handler")
 898
 899
 900 def verify_context_first(clazz):
 901     """Verifies that methods accepting a Context keep it the first argument."""
 902     examine = clazz.ctors + clazz.methods
 903     for m in examine:
 904         if len(m.args) > 1 and m.args[0] != "android.content.Context":
 905             if "android.content.Context" in m.args[1:]:
 906                 error(clazz, m, "M3", "Context is distinct, so it must be the first argument")
 907
 908
 909 def verify_listener_last(clazz):
 910     """Verifies that methods accepting a Listener or Callback keep them as last arguments."""
 911     examine = clazz.ctors + clazz.methods
 912     for m in examine:
 913         if "Listener" in m.name or "Callback" in m.name: continue
 914         found = False
 915         for a in m.args:
 916             if a.endswith("Callback") or a.endswith("Callbacks") or a.endswith("Listener"):
 917                 found = True
 918             elif found and a != "android.os.Handler":
 919                 warn(clazz, m, "M3", "Listeners should always be at end of argument list")
 920
 921
 922 def verify_resource_names(clazz):
 923     """Verifies that resource names have consistent case."""
 924     if not re.match("android\.R\.[a-z]+", clazz.fullname): return
 925
 926     # Resources defined by files are foo_bar_baz
 927     if clazz.name in ["anim","animator","color","dimen","drawable","interpolator","layout","transition","menu","mipmap","string","plurals","raw","xml"]:
 928         for f in clazz.fields:
 929             if re.match("[a-z1-9_]+$", f.name): continue
 930             error(clazz, f, None, "Expected resource name in this class to be foo_bar_baz style")
 931
 932     # Resources defined inside files are fooBarBaz
 933     if clazz.name in ["array","attr","id","bool","fraction","integer"]:
 934         for f in clazz.fields:
 935             if re.match("config_[a-z][a-zA-Z1-9]*$", f.name): continue
 936             if re.match("layout_[a-z][a-zA-Z1-9]*$", f.name): continue
 937             if re.match("state_[a-z_]*$", f.name): continue
 938
 939             if re.match("[a-z][a-zA-Z1-9]*$", f.name): continue
 940             error(clazz, f, "C7", "Expected resource name in this class to be fooBarBaz style")
 941
 942     # Styles are FooBar_Baz
 943     if clazz.name in ["style"]:
 944         for f in clazz.fields:
 945             if re.match("[A-Z][A-Za-z1-9]+(_[A-Z][A-Za-z1-9]+?)*$", f.name): continue
 946             error(clazz, f, "C7", "Expected resource name in this class to be FooBar_Baz style")
 947
 948
 949 def examine_clazz(clazz):
 950     """Find all style issues in the given class."""
 951     if clazz.pkg.name.startswith("java"): return
 952     if clazz.pkg.name.startswith("junit"): return
 953     if clazz.pkg.name.startswith("org.apache"): return
 954     if clazz.pkg.name.startswith("org.xml"): return
 955     if clazz.pkg.name.startswith("org.json"): return
 956     if clazz.pkg.name.startswith("org.w3c"): return
 957
 958     verify_constants(clazz)
 959     verify_enums(clazz)
 960     verify_class_names(clazz)
 961     verify_method_names(clazz)
 962     verify_callbacks(clazz)
 963     verify_listeners(clazz)
 964     verify_actions(clazz)
 965     verify_extras(clazz)
 966     verify_equals(clazz)
 967     verify_parcelable(clazz)
 968     verify_protected(clazz)
 969     verify_fields(clazz)
 970     verify_register(clazz)
 971     verify_sync(clazz)
 972     verify_intent_builder(clazz)
 973     verify_helper_classes(clazz)
 974     verify_builder(clazz)
 975     verify_aidl(clazz)
 976     verify_internal(clazz)
 977     verify_layering(clazz)
 978     verify_boolean(clazz)
 979     verify_collections(clazz)
 980     verify_flags(clazz)
 981     verify_exception(clazz)
 982     if not ALLOW_GOOGLE: verify_google(clazz)
 983     verify_bitset(clazz)
 984     verify_manager(clazz)
 985     verify_boxed(clazz)
 986     verify_static_utils(clazz)
 987     verify_overload_args(clazz)
 988     verify_callback_handlers(clazz)
 989     verify_context_first(clazz)
 990     verify_listener_last(clazz)
 991     verify_resource_names(clazz)
 992
 993
 994 def examine_stream(stream):
 995     """Find all style issues in the given API stream."""
 996     global failures
 997     failures = {}
 998     _parse_stream(stream, examine_clazz)
 999     return failures
1000
1001
1002 def examine_api(api):
1003     """Find all style issues in the given parsed API."""
1004     global failures
1005     failures = {}
1006     for key in sorted(api.keys()):
1007         examine_clazz(api[key])
1008     return failures
1009
1010
1011 def verify_compat(cur, prev):
1012     """Find any incompatible API changes between two levels."""
1013     global failures
1014
1015     def class_exists(api, test):
1016         return test.fullname in api
1017
1018     def ctor_exists(api, clazz, test):
1019         for m in clazz.ctors:
1020             if m.ident == test.ident: return True
1021         return False
1022
1023     def all_methods(api, clazz):
1024         methods = list(clazz.methods)
1025         if clazz.extends is not None:
1026             methods.extend(all_methods(api, api[clazz.extends]))
1027         return methods
1028
1029     def method_exists(api, clazz, test):
1030         methods = all_methods(api, clazz)
1031         for m in methods:
1032             if m.ident == test.ident: return True
1033         return False
1034
1035     def field_exists(api, clazz, test):
1036         for f in clazz.fields:
1037             if f.ident == test.ident: return True
1038         return False
1039
1040     failures = {}
1041     for key in sorted(prev.keys()):
1042         prev_clazz = prev[key]
1043
1044         if not class_exists(cur, prev_clazz):
1045             error(prev_clazz, None, None, "Class removed or incompatible change")
1046             continue
1047
1048         cur_clazz = cur[key]
1049
1050         for test in prev_clazz.ctors:
1051             if not ctor_exists(cur, cur_clazz, test):
1052                 error(prev_clazz, prev_ctor, None, "Constructor removed or incompatible change")
1053
1054         methods = all_methods(prev, prev_clazz)
1055         for test in methods:
1056             if not method_exists(cur, cur_clazz, test):
1057                 error(prev_clazz, test, None, "Method removed or incompatible change")
1058
1059         for test in prev_clazz.fields:
1060             if not field_exists(cur, cur_clazz, test):
1061                 error(prev_clazz, test, None, "Field removed or incompatible change")
1062
1063     return failures
1064
1065
1066 if __name__ == "__main__":
1067     parser = argparse.ArgumentParser(description="Enforces common Android public API design \
1068             patterns. It ignores lint messages from a previous API level, if provided.")
1069     parser.add_argument("current.txt", type=argparse.FileType('r'), help="current.txt")
1070     parser.add_argument("previous.txt", nargs='?', type=argparse.FileType('r'), default=None,
1071             help="previous.txt")
1072     parser.add_argument("--no-color", action='store_const', const=True,
1073             help="Disable terminal colors")
1074     parser.add_argument("--allow-google", action='store_const', const=True,
1075             help="Allow references to Google")
1076     args = vars(parser.parse_args())
1077
1078     if args['no_color']:
1079         USE_COLOR = False
1080
1081     if args['allow_google']:
1082         ALLOW_GOOGLE = True
1083
1084     current_file = args['current.txt']
1085     previous_file = args['previous.txt']
1086
1087     with current_file as f:
1088         cur_fail = examine_stream(f)
1089     if not previous_file is None:
1090         with previous_file as f:
1091             prev_fail = examine_stream(f)
1092
1093         # ignore errors from previous API level
1094         for p in prev_fail:
1095             if p in cur_fail:
1096                 del cur_fail[p]
1097
1098         """
1099         # NOTE: disabled because of memory pressure
1100         # look for compatibility issues
1101         compat_fail = verify_compat(cur, prev)
1102
1103         print "%s API compatibility issues %s\n" % ((format(fg=WHITE, bg=BLUE, bold=True), format(reset=True)))
1104         for f in sorted(compat_fail):
1105             print compat_fail[f]
1106             print
1107         """
1108
1109     print "%s API style issues %s\n" % ((format(fg=WHITE, bg=BLUE, bold=True), format(reset=True)))
1110     for f in sorted(cur_fail):
1111         print cur_fail[f]
1112         print