node/tools/closure_linter/closure_linter/javascriptlintrules.py

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

"""Methods for checking JS files for common style guide violations.

These style guide violations should only apply to JavaScript and not an Ecma
scripting languages.
"""

__author__ = ('robbyw@google.com (Robert Walker)',
              'ajp@google.com (Andy Perelson)',
              'jacobr@google.com (Jacob Richman)')

import gflags as flags
from closure_linter import ecmalintrules
from closure_linter import errors
from closure_linter import javascripttokenizer
from closure_linter import javascripttokens
from closure_linter import tokenutil
from closure_linter.common import error
from closure_linter.common import position

FLAGS = flags.FLAGS
flags.DEFINE_list('closurized_namespaces', '',
                  'Namespace prefixes, used for testing of'
                  'goog.provide/require')
flags.DEFINE_list('ignored_extra_namespaces', '',
                  'Fully qualified namespaces that should be not be reported '
                  'as extra by the linter.')

# Shorthand
Error = error.Error
Position = position.Position
Type = javascripttokens.JavaScriptTokenType


class JavaScriptLintRules(ecmalintrules.EcmaScriptLintRules):
  """JavaScript lint rules that catch JavaScript specific style errors."""

  def HandleMissingParameterDoc(self, token, param_name):
    """Handle errors associated with a parameter missing a param tag."""
    self._HandleError(errors.MISSING_PARAMETER_DOCUMENTATION,
                      'Missing docs for parameter: "%s"' % param_name, token)

  def __ContainsRecordType(self, token):
    """Check whether the given token contains a record type.

    Args:
      token: The token being checked
    """
    # If we see more than one left-brace in the string of an annotation token,
    # then there's a record type in there.
    return (token and token.type == Type.DOC_FLAG and
        token.attached_object.type is not None and
        token.attached_object.type.find('{') != token.string.rfind('{'))


  def CheckToken(self, token, state):
    """Checks a token, given the current parser_state, for warnings and errors.

    Args:
      token: The current token under consideration
      state: parser_state object that indicates the current state in the page
    """
    if self.__ContainsRecordType(token):
      # We should bail out and not emit any warnings for this annotation.
      # TODO(nicksantos): Support record types for real.
      state.GetDocComment().Invalidate()
      return

    # Call the base class's CheckToken function.
    super(JavaScriptLintRules, self).CheckToken(token, state)

    # Store some convenience variables
    first_in_line = token.IsFirstInLine()
    last_in_line = token.IsLastInLine()
    type = token.type

    if type == Type.DOC_FLAG:
      flag = token.attached_object

      if flag.flag_type == 'param' and flag.name_token is not None:
        self._CheckForMissingSpaceBeforeToken(
            token.attached_object.name_token)

      if flag.flag_type in state.GetDocFlag().HAS_TYPE:
        # Check for both missing type token and empty type braces '{}'
        # Missing suppress types are reported separately and we allow enums
        # without types.
        if (flag.flag_type not in ('suppress', 'enum') and
            (flag.type == None or flag.type == '' or flag.type.isspace())):
          self._HandleError(errors.MISSING_JSDOC_TAG_TYPE,
                            'Missing type in %s tag' % token.string, token)

        elif flag.name_token and flag.type_end_token and tokenutil.Compare(
            flag.type_end_token, flag.name_token) > 0:
          self._HandleError(
              errors.OUT_OF_ORDER_JSDOC_TAG_TYPE,
              'Type should be immediately after %s tag' % token.string,
              token)

    elif type == Type.DOUBLE_QUOTE_STRING_START:
      next = token.next
      while next.type == Type.STRING_TEXT:
        if javascripttokenizer.JavaScriptTokenizer.SINGLE_QUOTE.search(
            next.string):
          break
        next = next.next
      else:
        self._HandleError(
            errors.UNNECESSARY_DOUBLE_QUOTED_STRING,
            'Single-quoted string preferred over double-quoted string.',
            token,
            Position.All(token.string))

    elif type == Type.END_DOC_COMMENT:
      if (FLAGS.strict and not self._is_html and state.InTopLevel() and
          not state.InBlock()):

        # Check if we're in a fileoverview or constructor JsDoc.
        doc_comment = state.GetDocComment()
        is_constructor = (doc_comment.HasFlag('constructor') or
            doc_comment.HasFlag('interface'))
        is_file_overview = doc_comment.HasFlag('fileoverview')

        # If the comment is not a file overview, and it does not immediately
        # precede some code, skip it.
        # NOTE: The tokenutil methods are not used here because of their
        # behavior at the top of a file.
        next = token.next
        if (not next or
            (not is_file_overview and next.type in Type.NON_CODE_TYPES)):
          return

        # Find the start of this block (include comments above the block, unless
        # this is a file overview).
        block_start = doc_comment.start_token
        if not is_file_overview:
          token = block_start.previous
          while token and token.type in Type.COMMENT_TYPES:
            block_start = token
            token = token.previous

        # Count the number of blank lines before this block.
        blank_lines = 0
        token = block_start.previous
        while token and token.type in [Type.WHITESPACE, Type.BLANK_LINE]:
          if token.type == Type.BLANK_LINE:
            # A blank line.
            blank_lines += 1
          elif token.type == Type.WHITESPACE and not token.line.strip():
            # A line with only whitespace on it.
            blank_lines += 1
          token = token.previous

        # Log errors.
        error_message = False
        expected_blank_lines = 0

        if is_file_overview and blank_lines == 0:
          error_message = 'Should have a blank line before a file overview.'
          expected_blank_lines = 1
        elif is_constructor and blank_lines != 3:
          error_message = ('Should have 3 blank lines before a constructor/'
              'interface.')
          expected_blank_lines = 3
        elif not is_file_overview and not is_constructor and blank_lines != 2:
          error_message = 'Should have 2 blank lines between top-level blocks.'
          expected_blank_lines = 2

        if error_message:
          self._HandleError(errors.WRONG_BLANK_LINE_COUNT, error_message,
              block_start, Position.AtBeginning(),
              expected_blank_lines - blank_lines)

    elif type == Type.END_BLOCK:
      if state.InFunction() and state.IsFunctionClose():
        is_immediately_called = (token.next and
                                 token.next.type == Type.START_PAREN)

        function = state.GetFunction()
        if not self._limited_doc_checks:
          if (function.has_return and function.doc and
              not is_immediately_called and
              not function.doc.HasFlag('return') and
              not function.doc.InheritsDocumentation() and
              not function.doc.HasFlag('constructor')):
            # Check for proper documentation of return value.
            self._HandleError(
                errors.MISSING_RETURN_DOCUMENTATION,
                'Missing @return JsDoc in function with non-trivial return',
                function.doc.end_token, Position.AtBeginning())
          elif (not function.has_return and function.doc and
                function.doc.HasFlag('return') and
                not state.InInterfaceMethod()):
            return_flag = function.doc.GetFlag('return')
            if (return_flag.type is None or (
                'undefined' not in return_flag.type and
                'void' not in return_flag.type and
                '*' not in return_flag.type)):
              self._HandleError(
                  errors.UNNECESSARY_RETURN_DOCUMENTATION,
                  'Found @return JsDoc on function that returns nothing',
                  return_flag.flag_token, Position.AtBeginning())

      if state.InFunction() and state.IsFunctionClose():
        is_immediately_called = (token.next and
                                 token.next.type == Type.START_PAREN)
        if (function.has_this and function.doc and
            not function.doc.HasFlag('this') and
            not function.is_constructor and
            not function.is_interface and
            '.prototype.' not in function.name):
          self._HandleError(
              errors.MISSING_JSDOC_TAG_THIS,
              'Missing @this JsDoc in function referencing "this". ('
              'this usually means you are trying to reference "this" in '
              'a static function, or you have forgotten to mark a '
              'constructor with @constructor)',
              function.doc.end_token, Position.AtBeginning())

    elif type == Type.IDENTIFIER:
      if token.string == 'goog.inherits' and not state.InFunction():
        if state.GetLastNonSpaceToken().line_number == token.line_number:
          self._HandleError(
              errors.MISSING_LINE,
              'Missing newline between constructor and goog.inherits',
              token,
              Position.AtBeginning())

        extra_space = state.GetLastNonSpaceToken().next
        while extra_space != token:
          if extra_space.type == Type.BLANK_LINE:
            self._HandleError(
                errors.EXTRA_LINE,
                'Extra line between constructor and goog.inherits',
                extra_space)
          extra_space = extra_space.next

        # TODO(robbyw): Test the last function was a constructor.
        # TODO(robbyw): Test correct @extends and @implements documentation.

    elif type == Type.OPERATOR:
      # If the token is unary and appears to be used in a unary context
      # it's ok.  Otherwise, if it's at the end of the line or immediately
      # before a comment, it's ok.
      # Don't report an error before a start bracket - it will be reported
      # by that token's space checks.
      if (not token.metadata.IsUnaryOperator() and not last_in_line
          and not token.next.IsComment()
          and not token.next.IsOperator(',')
          and not token.next.type in (Type.WHITESPACE, Type.END_PAREN,
                                      Type.END_BRACKET, Type.SEMICOLON,
                                      Type.START_BRACKET)):
        self._HandleError(
            errors.MISSING_SPACE,
            'Missing space after "%s"' % token.string,
            token,
            Position.AtEnd(token.string))
    elif type == Type.WHITESPACE:
      # Check whitespace length if it's not the first token of the line and
      # if it's not immediately before a comment.
      if not last_in_line and not first_in_line and not token.next.IsComment():
        # Ensure there is no space after opening parentheses.
        if (token.previous.type in (Type.START_PAREN, Type.START_BRACKET,
                                    Type.FUNCTION_NAME)
            or token.next.type == Type.START_PARAMETERS):
          self._HandleError(
              errors.EXTRA_SPACE,
              'Extra space after "%s"' % token.previous.string,
              token,
              Position.All(token.string))

  def Finalize(self, state, tokenizer_mode):
    """Perform all checks that need to occur after all lines are processed."""
    # Call the base class's Finalize function.
    super(JavaScriptLintRules, self).Finalize(state, tokenizer_mode)

    # Check for sorted requires statements.
    goog_require_tokens = state.GetGoogRequireTokens()
    requires = [require_token.string for require_token in goog_require_tokens]
    sorted_requires = sorted(requires)
    index = 0
    bad = False
    for item in requires:
      if item != sorted_requires[index]:
        bad = True
        break
      index += 1

    if bad:
      self._HandleError(
          errors.GOOG_REQUIRES_NOT_ALPHABETIZED,
          'goog.require classes must be alphabetized.  The correct code is:\n' +
          '\n'.join(map(lambda x: 'goog.require(\'%s\');' % x,
                        sorted_requires)),
          goog_require_tokens[index],
          position=Position.AtBeginning(),
          fix_data=goog_require_tokens)

    # Check for sorted provides statements.
    goog_provide_tokens = state.GetGoogProvideTokens()
    provides = [provide_token.string for provide_token in goog_provide_tokens]
    sorted_provides = sorted(provides)
    index = 0
    bad = False
    for item in provides:
      if item != sorted_provides[index]:
        bad = True
        break
      index += 1

    if bad:
      self._HandleError(
          errors.GOOG_PROVIDES_NOT_ALPHABETIZED,
          'goog.provide classes must be alphabetized.  The correct code is:\n' +
          '\n'.join(map(lambda x: 'goog.provide(\'%s\');' % x,
                        sorted_provides)),
          goog_provide_tokens[index],
          position=Position.AtBeginning(),
          fix_data=goog_provide_tokens)

    if FLAGS.closurized_namespaces:
      # Check that we provide everything we need.
      provided_namespaces = state.GetProvidedNamespaces()
      missing_provides = provided_namespaces - set(provides)
      if missing_provides:
        self._HandleError(
            errors.MISSING_GOOG_PROVIDE,
            'Missing the following goog.provide statements:\n' +
            '\n'.join(map(lambda x: 'goog.provide(\'%s\');' % x,
                          sorted(missing_provides))),
            state.GetFirstToken(), position=Position.AtBeginning(),
            fix_data=missing_provides)

      # Compose a set of all available namespaces. Explicitly omit goog
      # because if you can call goog.require, you already have goog.
      available_namespaces = (set(requires) | set(provides) | set(['goog']) |
                              provided_namespaces)

      # Check that we require everything we need.
      missing_requires = set()
      for namespace_variants in state.GetUsedNamespaces():
        # Namespace variants is a list of potential things to require. If we
        # find we're missing one, we are lazy and choose to require the first
        # in the sequence - which should be the namespace.
        if not set(namespace_variants) & available_namespaces:
          missing_requires.add(namespace_variants[0])

      if missing_requires:
        self._HandleError(
            errors.MISSING_GOOG_REQUIRE,
            'Missing the following goog.require statements:\n' +
            '\n'.join(map(lambda x: 'goog.require(\'%s\');' % x,
                          sorted(missing_requires))),
            state.GetFirstToken(), position=Position.AtBeginning(),
            fix_data=missing_requires)

      # Check that we don't require things we don't actually use.
      namespace_variants = state.GetUsedNamespaces()
      used_namespaces = set()
      for a, b in namespace_variants:
        used_namespaces.add(a)
        used_namespaces.add(b)

      extra_requires = set()
      for i in requires:
        baseNamespace = i.split('.')[0]
        if (i not in used_namespaces and
            baseNamespace in FLAGS.closurized_namespaces and
            i not in FLAGS.ignored_extra_namespaces):
          extra_requires.add(i)

      if extra_requires:
        self._HandleError(
            errors.EXTRA_GOOG_REQUIRE,
            'The following goog.require statements appear unnecessary:\n' +
            '\n'.join(map(lambda x: 'goog.require(\'%s\');' % x,
                          sorted(extra_requires))),
            state.GetFirstToken(), position=Position.AtBeginning(),
            fix_data=extra_requires)