CheckstyleTestMakeupCheck.java

  1. ////////////////////////////////////////////////////////////////////////////////
  2. // checkstyle: Checks Java source code for adherence to a set of rules.
  3. // Copyright (C) 2001-2019 the original author or authors.
  4. //
  5. // This library is free software; you can redistribute it and/or
  6. // modify it under the terms of the GNU Lesser General Public
  7. // License as published by the Free Software Foundation; either
  8. // version 2.1 of the License, or (at your option) any later version.
  9. //
  10. // This library is distributed in the hope that it will be useful,
  11. // but WITHOUT ANY WARRANTY; without even the implied warranty of
  12. // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13. // Lesser General Public License for more details.
  14. //
  15. // You should have received a copy of the GNU Lesser General Public
  16. // License along with this library; if not, write to the Free Software
  17. // Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  18. ////////////////////////////////////////////////////////////////////////////////

  20. package com.github.sevntu.checkstyle.checks.design;

  22. import java.io.File;
  23. import java.util.HashMap;
  24. import java.util.HashSet;
  25. import java.util.Map;
  26. import java.util.Set;
  27. import java.util.regex.Pattern;

  29. import com.github.sevntu.checkstyle.SevntuUtil;
  30. import com.puppycrawl.tools.checkstyle.DefaultConfiguration;
  31. import com.puppycrawl.tools.checkstyle.api.AbstractCheck;
  32. import com.puppycrawl.tools.checkstyle.api.Configuration;
  33. import com.puppycrawl.tools.checkstyle.api.DetailAST;
  34. import com.puppycrawl.tools.checkstyle.api.TokenTypes;
  35. import com.puppycrawl.tools.checkstyle.utils.AnnotationUtil;
  36. import com.puppycrawl.tools.checkstyle.utils.ScopeUtil;

  38. /**
  39.  * <p>
  40.  * Custom check to ensure Checkstyle tests are designed correctly.
  41.  * </p>
  42.  *
  43.  * <p>Rationale: This check was made to ensure tests follow a specific design implementation
  44.  * so 3rd party utilities like the regression utility can parse the tests for information
  45.  * used in creating regression reports.
  46.  *
  47.  * <p>
  48.  * Check have following options:
  49.  * </p>
  50.  * <ul>
  51.  * <li>
  52.  * createMethodRegexp - Regular expression for matching a create configuration method by name. This
  53.  * is the name of the method that starts creating a custom module configuration to be used for
  54.  * verifying results for regression purposes.
  55.  * Default value is {@code create(Root|Module)Config|getModuleConfig}.</li>
  56.  *
  57.  * <li>
  58.  * verifyMethodRegexp - Regular expression for matching a verify method by name. This is the name
  59.  * of the method that verifies the execution results of the custom configuration created for
  60.  * regression. As such, it should accept the custom configuration as a parameter.
  61.  * Default value is {@code verify(Warns|Suppressed)?}.</li>
  62.  * </ul>
  63.  *
  64.  * <p>
  65.  * To configure the check to report incorrectly made checkstyle tests:
  66.  * </p>
  67.  *
  68.  * <pre>
  69.  * &lt;module name=&quot;CheckstyleTestMakeup&quot;/&gt;
  70.  * </pre>
  71.  *
  72.  * @author Richard Veach
  73.  * @since 1.25.0
  74.  */
  75. public class CheckstyleTestMakeupCheck extends AbstractCheck {

  77.     /** Violations message. */
  78.     public static final String MSG_KEY_CONFIG_NOT_ASSIGNED = "tester.config.not.assigned";
  79.     /** Violations message. */
  80.     public static final String MSG_KEY_CONFIG_NOT_ASSIGNED_WITH = "tester.config.not.assigned.with";
  81.     /** Violations message. */
  82.     public static final String MSG_KEY_CONFIG_NOT_ASSIGNED_PROPERLY =
  83.             "tester.config.not.assigned.properly";
  84.     /** Violations message. */
  85.     public static final String MSG_KEY_UNKNOWN_PROPERTY = "tester.unknown.property";
  86.     /** Violations message. */
  87.     public static final String MSG_KEY_CONFIG_NOT_FOUND = "tester.config.not.found";

  89.     /** Name of 'getPath' method. */
  90.     private static final String METHOD_GET_PATH = "getPath";

  92.     /** AST of method that is currently being examined. */
  93.     private DetailAST methodAst;
  94.     /** List of variable names that reference a file. */
  95.     private final Set<String> fileVariableNames = new HashSet<>();
  96.     /** List of variable names that reference a configuration. */
  97.     private final Set<String> checkConfigNames = new HashSet<>();
  98.     /** {@code true} if the 'verify' method was found in the method. */
  99.     private boolean foundVerify;

  101.     /** List of violations generated for a method. */
  102.     private final Map<DetailAST, String> violations = new HashMap<>();

  104.     /** Regular expression for matching a create method by name. */
  105.     private Pattern createMethodRegexp = Pattern
  106.             .compile("create(Root|Module)Config|getModuleConfig");

  108.     /** Regular expression for matching a verify method by name. */
  109.     private Pattern verifyMethodRegexp = Pattern.compile("verify(Warns|Suppressed)?");

  111.     /**
  112.      * Setter for {@link #createMethodRegexp}.
  113.      * @param createMethodRegexp The value to set.
  114.      */
  115.     public void setCreateMethodRegexp(Pattern createMethodRegexp) {
  116.         this.createMethodRegexp = createMethodRegexp;
  117.     }

  119.     /**
  120.      * Setter for {@link #verifyMethodRegexp}.
  121.      * @param verifyMethodRegexp The value to set.
  122.      */
  123.     public void setVerifyMethodRegexp(Pattern verifyMethodRegexp) {
  124.         this.verifyMethodRegexp = verifyMethodRegexp;
  125.     }

  127.     @Override
  128.     public int[] getDefaultTokens() {
  129.         return new int[] {
  130.             TokenTypes.METHOD_DEF,
  131.             TokenTypes.VARIABLE_DEF,
  132.             TokenTypes.METHOD_CALL,
  133.         };
  134.     }

  136.     @Override
  137.     public int[] getAcceptableTokens() {
  138.         return getDefaultTokens();
  139.     }

  141.     @Override
  142.     public int[] getRequiredTokens() {
  143.         return getDefaultTokens();
  144.     }

  146.     @Override
  147.     public void beginTree(DetailAST rootAST) {
  148.         resetInternalFields();
  149.     }

  151.     @Override
  152.     public void visitToken(DetailAST ast) {
  153.         switch (ast.getType()) {
  154.             case TokenTypes.METHOD_DEF:
  155.                 checkMethod(ast);
  156.                 break;
  157.             case TokenTypes.VARIABLE_DEF:
  158.                 checkVariable(ast);
  159.                 break;
  160.             case TokenTypes.METHOD_CALL:
  161.                 checkMethodCall(ast);
  162.                 break;
  163.             default:
  164.                 SevntuUtil.reportInvalidToken(ast.getType());
  165.                 break;
  166.         }
  167.     }

  169.     /**
  170.      * Examines the method to see if it is part of a Test.
  171.      * @param ast The method to examine.
  172.      */
  173.     private void checkMethod(DetailAST ast) {
  174.         if (methodAst == null && AnnotationUtil.containsAnnotation(ast, "Test")
  175.                 || AnnotationUtil.containsAnnotation(ast, "org.junit.Test")) {
  176.             methodAst = ast;
  177.         }
  178.     }

  180.     /**
  181.      * Examines the variable declaration to see if it is a specific variable type to track.
  182.      * Variables of type {@link Configuration} or {@link  DefaultConfiguration} need to be assigned
  183.      * a {@code null}, createModuleConfig, or createRootConfig and is tracked for future purposes.
  184.      * Variables of type {@link File} with the modifier {@code final} are tracked for future
  185.      * purposes.
  186.      * @param ast The variable to examine.
  187.      */
  188.     private void checkVariable(DetailAST ast) {
  189.         if (methodAst != null && ScopeUtil.isLocalVariableDef(ast)) {
  190.             final DetailAST type = ast.findFirstToken(TokenTypes.TYPE).findFirstToken(
  191.                     TokenTypes.IDENT);

  193.             if (type != null) {
  194.                 final String typeText = type.getText();

  196.                 if ("DefaultConfiguration".equals(typeText) || "Configuration".equals(typeText)) {
  197.                     checkConfigurationVariable(ast);
  198.                 }
  199.                 else if ("File".equals(typeText)
  200.                         && ast.findFirstToken(TokenTypes.MODIFIERS)
  201.                                 .findFirstToken(TokenTypes.FINAL) != null) {
  202.                     fileVariableNames.add(ast.findFirstToken(TokenTypes.IDENT).getText());
  203.                 }
  204.             }
  205.         }
  206.     }

  208.     /**
  209.      * Examines the configuration variable to see if it is defined as described in
  210.      * {@link #checkVariable(DetailAST)}.
  211.      * @param ast The variable to examine.
  212.      */
  213.     private void checkConfigurationVariable(DetailAST ast) {
  214.         checkConfigNames.add(ast.findFirstToken(TokenTypes.IDENT).getText());
  215.         final DetailAST assignment = ast.findFirstToken(TokenTypes.ASSIGN);

  217.         if (assignment == null) {
  218.             violations.put(ast, MSG_KEY_CONFIG_NOT_ASSIGNED);
  219.         }
  220.         else if (assignment.getFirstChild().getFirstChild().getType() == TokenTypes.METHOD_CALL) {
  221.             final DetailAST assignmentMethod = assignment.getFirstChild()
  222.                     .getFirstChild().findFirstToken(TokenTypes.IDENT);

  224.             if (assignmentMethod != null
  225.                     && !createMethodRegexp.matcher(assignmentMethod.getText()).matches()) {
  226.                 violations.put(assignment, MSG_KEY_CONFIG_NOT_ASSIGNED_WITH);
  227.             }
  228.         }
  229.         else if (assignment.getFirstChild().getFirstChild().getType() != TokenTypes.LITERAL_NULL) {
  230.             violations.put(ast, MSG_KEY_CONFIG_NOT_ASSIGNED_PROPERLY);
  231.         }
  232.     }

  234.     /**
  235.      * Examines the method call and verify it is defined correctly.
  236.      * addAttribute method which is called by one of the configurations found earlier, must have
  237.      * all it's parameters be acceptable to {@link #isValidMethodCallExpression(DetailAST)}.
  238.      * Any method that matches {@link #verifyMethodRegexp} are tracked for future purposes.
  239.      * @param ast The method call to examine.
  240.      */
  241.     private void checkMethodCall(DetailAST ast) {
  242.         if (methodAst != null) {
  243.             final DetailAST firstChild = ast.getFirstChild();
  244.             final String methodCallName = getMethodCallName(firstChild);
  245.             final String methodCallerName = getMethodCallerName(firstChild);

  247.             if ("addAttribute".equals(methodCallName)
  248.                     && checkConfigNames.contains(methodCallerName)) {
  249.                 final DetailAST elist = ast.findFirstToken(TokenTypes.ELIST);

  251.                 for (DetailAST expression = elist.getFirstChild(); expression != null;
  252.                         expression = expression.getNextSibling()) {
  253.                     if (expression.getType() == TokenTypes.EXPR
  254.                             && !isValidMethodCallExpression(expression.getFirstChild())) {
  255.                         violations.put(expression, MSG_KEY_UNKNOWN_PROPERTY);
  256.                     }
  257.                 }
  258.             }
  259.             else if (methodCallerName.equals(methodCallName)
  260.                     && ast.getParent().getParent().getType() != TokenTypes.METHOD_CALL
  261.                     && verifyMethodRegexp.matcher(methodCallName).matches()) {
  262.                 foundVerify = true;
  263.             }
  264.         }
  265.     }

  267.     /**
  268.      * Retrieves the name of the method being called.
  269.      * @param ast The method call token to examine.
  270.      * @return The name of the method.
  271.      */
  272.     private String getMethodCallName(DetailAST ast) {
  273.         final String result;
  274.         if (ast.getType() == TokenTypes.DOT) {
  275.             result = getMethodCallName(ast.getFirstChild().getNextSibling());
  276.         }
  277.         else {
  278.             result = ast.getText();
  279.         }
  280.         return result;
  281.     }

  283.     /**
  284.      * Retrieves the name of the variable calling the method.
  285.      * @param ast The method call token to examine.
  286.      * @return The name of who is calling the method.
  287.      */
  288.     private String getMethodCallerName(DetailAST ast) {
  289.         final String result;
  290.         if (ast.getType() == TokenTypes.DOT) {
  291.             result = getMethodCallName(ast.getFirstChild());
  292.         }
  293.         else {
  294.             result = ast.getText();
  295.         }
  296.         return result;
  297.     }

  299.     /**
  300.      * Identifies if the parameter of the method call is valid.
  301.      * Plain string literal is allowed.
  302.      * Adding multiple string literals is allowed because of line length limits.
  303.      * Plain {@code null} is allowed due to backward compatibility.
  304.      * Method calls are allowed only if they are any form of getPath, converting an enum to a
  305.      * string, or retrieving the path of a final {@link File} variable.
  306.      * @param expression The expression to examine.
  307.      * @return {@code true} if the method call is defined correctly.
  308.      */
  309.     private boolean isValidMethodCallExpression(DetailAST expression) {
  310.         boolean result = false;
  311.         final DetailAST firstChild = expression.getFirstChild();

  313.         switch (expression.getType()) {
  314.             case TokenTypes.STRING_LITERAL:
  315.                 result = true;
  316.                 break;
  317.             case TokenTypes.METHOD_CALL:
  318.                 result = isValidMethodCallExpressionMethodCall(firstChild);
  319.                 break;
  320.             case TokenTypes.PLUS:
  321.                 result = isValidMethodCallExpression(firstChild)
  322.                         && isValidMethodCallExpression(firstChild.getNextSibling());
  323.                 break;
  324.             case TokenTypes.LITERAL_NULL:
  325.                 result = true;
  326.                 break;
  327.             default:
  328.                 break;
  329.         }

  331.         return result;
  332.     }

  334.     /**
  335.      * Identifies if the inner method call of a method call is valid as defined in
  336.      * {@link #isValidMethodCallExpression(DetailAST)}.
  337.      * @param firstChild The first child of the method call.
  338.      * @return {@code true} if the method call is defined correctly.
  339.      */
  340.     private boolean isValidMethodCallExpressionMethodCall(DetailAST firstChild) {
  341.         boolean result = false;

  343.         if (firstChild.getType() == TokenTypes.DOT) {
  344.             if (firstChild.getFirstChild().getType() == TokenTypes.DOT) {
  345.                 result = isEnumerationCall(firstChild);
  346.             }
  347.             else if (isFileVariable(firstChild.getFirstChild())) {
  348.                 result = true;
  349.             }
  350.         }
  351.         else {
  352.             final String methodName = firstChild.getText();

  354.             if (isMethodGetPath(methodName)) {
  355.                 result = true;
  356.             }
  357.         }

  359.         return result;
  360.     }

  362.     /**
  363.      * Checks if the method call is calling toString, getName, or name on an enumeration.
  364.      * @param ast The AST to examine.
  365.      * @return {@code true} if the method call is on a enumeration.
  366.      */
  367.     private static boolean isEnumerationCall(DetailAST ast) {
  368.         boolean result = false;
  369.         final DetailAST firstChild = ast.getFirstChild();
  370.         final DetailAST methodCalled = firstChild.getNextSibling();
  371.         final DetailAST parameters = ast.getNextSibling();

  373.         if (firstChild.getFirstChild().getType() == TokenTypes.IDENT
  374.                 && ("toString".equals(methodCalled.getText())
  375.                         || "getName".equals(methodCalled.getText())
  376.                         || "name".equals(methodCalled.getText()))
  377.                 && parameters.getChildCount() == 0) {
  378.             result = true;
  379.         }

  381.         return result;
  382.     }

  384.     /**
  385.      * Checks if the method call is 'getPath' on a {@link File} variable.
  386.      * @param firstChild The AST to examine.
  387.      * @return {@code true} if the method call is on a file variable.
  388.      */
  389.     private boolean isFileVariable(DetailAST firstChild) {
  390.         return METHOD_GET_PATH.equals(firstChild.getNextSibling().getText())
  391.                 && fileVariableNames.contains(firstChild.getText());
  392.     }

  394.     /**
  395.      * Checks if the method name is a form of 'getPath'.
  396.      * @param methodName The name to examine.
  397.      * @return {@code true} if the method is of the form.
  398.      */
  399.     private static boolean isMethodGetPath(String methodName) {
  400.         return METHOD_GET_PATH.equals(methodName)
  401.                 || "getNonCompilablePath".equals(methodName)
  402.                 || "getUriString".equals(methodName)
  403.                 || "getResourcePath".equals(methodName);
  404.     }

  406.     @Override
  407.     public void leaveToken(DetailAST ast) {
  408.         if (ast == methodAst) {
  409.             if (foundVerify) {
  410.                 if (checkConfigNames.isEmpty()) {
  411.                     violations.put(ast, MSG_KEY_CONFIG_NOT_FOUND);
  412.                 }

  414.                 for (Map.Entry<DetailAST, String> entry : violations.entrySet()) {
  415.                     log(entry.getKey(), entry.getValue());
  416.                 }
  417.             }

  419.             resetInternalFields();
  420.         }
  421.     }

  423.     /** Resets the internal fields when a new file/method is to be processed. */
  424.     private void resetInternalFields() {
  425.         methodAst = null;
  426.         fileVariableNames.clear();
  427.         checkConfigNames.clear();
  428.         foundVerify = false;
  429.         violations.clear();
  430.     }

  432. }
Created with JaCoCo 0.7.1.201405082137