chrome/browser/web_dev_style/js_checker.py

   1 # Copyright (c) 2012 The Chromium Authors. All rights reserved.
   2 # Use of this source code is governed by a BSD-style license that can be
   3 # found in the LICENSE file.
   4
   5 """Presubmit script for Chromium JS resources.
   6
   7 See chrome/browser/PRESUBMIT.py
   8 """
   9
  10 import regex_check
  11
  12
  13 class JSChecker(object):
  14   def __init__(self, input_api, output_api, file_filter=None):
  15     self.input_api = input_api
  16     self.output_api = output_api
  17     self.file_filter = file_filter
  18
  19   def RegexCheck(self, line_number, line, regex, message):
  20     return regex_check.RegexCheck(
  21         self.input_api.re, line_number, line, regex, message)
  22
  23   def ChromeSendCheck(self, i, line):
  24     """Checks for a particular misuse of 'chrome.send'."""
  25     return self.RegexCheck(i, line, r"chrome\.send\('[^']+'\s*(, \[\])\)",
  26         'Passing an empty array to chrome.send is unnecessary')
  27
  28   def ConstCheck(self, i, line):
  29     """Check for use of the 'const' keyword."""
  30     if self.input_api.re.search(r'\*\s+@const', line):
  31       # Probably a JsDoc line
  32       return ''
  33
  34     return self.RegexCheck(i, line, r'(?:^|\s|\()(const)\s',
  35         'Use /** @const */ var varName; instead of const varName;')
  36
  37   def EndJsDocCommentCheck(self, i, line):
  38     msg = 'End JSDoc comments with */ instead of **/'
  39     def _check(regex):
  40       return self.RegexCheck(i, line, regex, msg)
  41     return _check(r'^\s*(\*\*/)\s*$') or _check(r'/\*\* @[a-zA-Z]+.* (\*\*/)')
  42
  43   def ExtraDotInGenericCheck(self, i, line):
  44     return self.RegexCheck(i, line, r"((?:Array|Object|Promise)\.<)",
  45         "Don't use a dot after generics (Object.<T> should be Object<T>).")
  46
  47   def GetElementByIdCheck(self, i, line):
  48     """Checks for use of 'document.getElementById' instead of '$'."""
  49     return self.RegexCheck(i, line, r"(document\.getElementById)\('",
  50         "Use $('id'), from chrome://resources/js/util.js, instead of "
  51         "document.getElementById('id')")
  52
  53   def InheritDocCheck(self, i, line):
  54     """Checks for use of '@inheritDoc' instead of '@override'."""
  55     return self.RegexCheck(i, line, r"\* (@inheritDoc)",
  56         "@inheritDoc is deprecated, use @override instead")
  57
  58   def WrapperTypeCheck(self, i, line):
  59     """Check for wrappers (new String()) instead of builtins (string)."""
  60     return self.RegexCheck(i, line,
  61         r"(?:/\*)?\*.*?@(?:param|return|type) ?"     # /** @param/@return/@type
  62         r"{[^}]*\b(String|Boolean|Number)\b[^}]*}",  # {(Boolean|Number|String)}
  63         "Don't use wrapper types (i.e. new String() or @type {String})")
  64
  65   def VarNameCheck(self, i, line):
  66     """See the style guide. http://goo.gl/uKir6"""
  67     return self.RegexCheck(i, line,
  68         r"var (?!g_\w+)([a-z]*[_$][\w_$]*)(?<! \$)",
  69         "Please use var namesLikeThis <http://goo.gl/uKir6>")
  70
  71   def _GetErrorHighlight(self, start, length):
  72     """Takes a start position and a length, and produces a row of '^'s to
  73        highlight the corresponding part of a string.
  74     """
  75     return start * ' ' + length * '^'
  76
  77   def _MakeErrorOrWarning(self, error_text, filename):
  78     """Takes a few lines of text indicating a style violation and turns it into
  79        a PresubmitError (if |filename| is in a directory where we've already
  80        taken out all the style guide violations) or a PresubmitPromptWarning
  81        (if it's in a directory where we haven't done that yet).
  82     """
  83     # TODO(tbreisacher): Once we've cleaned up the style nits in all of
  84     # resources/ we can get rid of this function.
  85     path = self.input_api.os_path
  86     resources = path.join(self.input_api.PresubmitLocalPath(), 'resources')
  87     dirs = (
  88         path.join(resources, 'bookmark_manager'),
  89         path.join(resources, 'extensions'),
  90         path.join(resources, 'file_manager'),
  91         path.join(resources, 'help'),
  92         path.join(resources, 'history'),
  93         path.join(resources, 'memory_internals'),
  94         path.join(resources, 'net_export'),
  95         path.join(resources, 'net_internals'),
  96         path.join(resources, 'network_action_predictor'),
  97         path.join(resources, 'ntp4'),
  98         path.join(resources, 'options'),
  99         path.join(resources, 'password_manager_internals'),
 100         path.join(resources, 'print_preview'),
 101         path.join(resources, 'profiler'),
 102         path.join(resources, 'sync_promo'),
 103         path.join(resources, 'tracing'),
 104         path.join(resources, 'uber'),
 105     )
 106     if filename.startswith(dirs):
 107       return self.output_api.PresubmitError(error_text)
 108     else:
 109       return self.output_api.PresubmitPromptWarning(error_text)
 110
 111   def ClosureLint(self, file_to_lint, source=None):
 112     """Lints |file_to_lint| and returns the errors."""
 113
 114     import sys
 115     import warnings
 116     old_path = sys.path
 117     old_filters = warnings.filters
 118
 119     try:
 120       closure_linter_path = self.input_api.os_path.join(
 121           self.input_api.change.RepositoryRoot(),
 122           "third_party",
 123           "closure_linter")
 124       gflags_path = self.input_api.os_path.join(
 125           self.input_api.change.RepositoryRoot(),
 126           "third_party",
 127           "python_gflags")
 128
 129       sys.path.insert(0, closure_linter_path)
 130       sys.path.insert(0, gflags_path)
 131
 132       warnings.filterwarnings('ignore', category=DeprecationWarning)
 133
 134       from closure_linter import errors, runner
 135       from closure_linter.common import errorhandler
 136       import gflags
 137
 138     finally:
 139       sys.path = old_path
 140       warnings.filters = old_filters
 141
 142     class ErrorHandlerImpl(errorhandler.ErrorHandler):
 143       """Filters out errors that don't apply to Chromium JavaScript code."""
 144
 145       def __init__(self, re):
 146         self._errors = []
 147         self.re = re
 148
 149       def HandleFile(self, filename, first_token):
 150         self._filename = filename
 151
 152       def HandleError(self, error):
 153         if (self._valid(error)):
 154           error.filename = self._filename
 155           self._errors.append(error)
 156
 157       def GetErrors(self):
 158         return self._errors
 159
 160       def HasErrors(self):
 161         return bool(self._errors)
 162
 163       def _valid(self, error):
 164         """Check whether an error is valid. Most errors are valid, with a few
 165            exceptions which are listed here.
 166         """
 167
 168         is_grit_statement = bool(
 169             self.re.search("</?(include|if)", error.token.line))
 170
 171         # Ignore missing spaces before "(" until Promise#catch issue is solved.
 172         # http://crbug.com/338301
 173         if (error.code == errors.MISSING_SPACE and error.token.string == '(' and
 174            'catch(' in error.token.line):
 175           return False
 176
 177         # Ignore "}.bind(" errors. http://crbug.com/397697
 178         if (error.code == errors.MISSING_SEMICOLON_AFTER_FUNCTION and
 179             '}.bind(' in error.token.line):
 180           return False
 181
 182         return not is_grit_statement and error.code not in [
 183             errors.COMMA_AT_END_OF_LITERAL,
 184             errors.JSDOC_ILLEGAL_QUESTION_WITH_PIPE,
 185             errors.LINE_TOO_LONG,
 186             errors.MISSING_JSDOC_TAG_THIS,
 187         ]
 188
 189     # Whitelist Polymer-specific JsDoc tags.
 190     gflags.FLAGS.custom_jsdoc_tags = ('group', 'element', 'attribute',
 191                                       'default')
 192     error_handler = ErrorHandlerImpl(self.input_api.re)
 193     runner.Run(file_to_lint, error_handler, source=source)
 194     return error_handler.GetErrors()
 195
 196   def RunChecks(self):
 197     """Check for violations of the Chromium JavaScript style guide. See
 198        http://chromium.org/developers/web-development-style-guide#TOC-JavaScript
 199     """
 200     results = []
 201
 202     affected_files = self.input_api.change.AffectedFiles(
 203         file_filter=self.file_filter,
 204         include_deletes=False)
 205     affected_js_files = filter(lambda f: f.LocalPath().endswith('.js'),
 206                                affected_files)
 207     for f in affected_js_files:
 208       error_lines = []
 209
 210       # Check for the following:
 211       # * document.getElementById()
 212       # * the 'const' keyword
 213       # * Passing an empty array to 'chrome.send()'
 214       for i, line in enumerate(f.NewContents(), start=1):
 215         error_lines += filter(None, [
 216             self.ChromeSendCheck(i, line),
 217             self.ConstCheck(i, line),
 218             self.GetElementByIdCheck(i, line),
 219             self.EndJsDocCommentCheck(i, line),
 220             self.ExtraDotInGenericCheck(i, line),
 221             self.InheritDocCheck(i, line),
 222             self.WrapperTypeCheck(i, line),
 223             self.VarNameCheck(i, line),
 224         ])
 225
 226       # Use closure linter to check for several different errors.
 227       lint_errors = self.ClosureLint(self.input_api.os_path.join(
 228           self.input_api.change.RepositoryRoot(), f.LocalPath()))
 229
 230       for error in lint_errors:
 231         highlight = self._GetErrorHighlight(
 232             error.token.start_index, error.token.length)
 233         error_msg = '  line %d: E%04d: %s\n%s\n%s' % (
 234             error.token.line_number,
 235             error.code,
 236             error.message,
 237             error.token.line.rstrip(),
 238             highlight)
 239         error_lines.append(error_msg)
 240
 241       if error_lines:
 242         error_lines = [
 243             'Found JavaScript style violations in %s:' %
 244             f.LocalPath()] + error_lines
 245         results.append(self._MakeErrorOrWarning(
 246             '\n'.join(error_lines), f.AbsoluteLocalPath()))
 247
 248     if results:
 249       results.append(self.output_api.PresubmitNotifyResult(
 250           'See the JavaScript style guide at '
 251           'http://www.chromium.org/developers/web-development-style-guide'
 252           '#TOC-JavaScript and if you have any feedback about the JavaScript '
 253           'PRESUBMIT check, contact tbreisacher@chromium.org or '
 254           'dbeam@chromium.org'))
 255
 256     return results