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"""
18Enforces common Android public API design patterns.  It ignores lint messages from
19a previous API level, if provided.
20
21Usage: apilint.py current.txt
22Usage: apilint.py current.txt previous.txt
23
24You 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
29import re, sys, collections, traceback, argparse
30
31
32BLACK, RED, GREEN, YELLOW, BLUE, MAGENTA, CYAN, WHITE = range(8)
33
34ALLOW_GOOGLE = False
35USE_COLOR = True
36
37def 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
53class 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
79class 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
117class 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
152class 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
166def _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
208class 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
240failures = {}
241
242def _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
252def warn(clazz, detail, rule, msg):
253    _fail(clazz, detail, False, rule, msg)
254
255def error(clazz, detail, rule, msg):
256    _fail(clazz, detail, True, rule, msg)
257
258
259def 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
269def 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
275def 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
287def 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
300def 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
320def 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
341def 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
371def 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
401def 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
410def 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
421def 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
431def 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
472def 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
505def 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
512def 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
524def 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
572def 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
601def 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
607def 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
613def 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
657def 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
697def 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
711def 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
727def 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
734def 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
750def 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
765def 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
774def 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
796def 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
813def 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
853def 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
900def 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
909def 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
922def 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
949def 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
994def 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
1002def 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
1011def 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
1066if __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
1113