ImportControlCheck.java

////////////////////////////////////////////////////////////////////////////////

// checkstyle: Checks Java source code for adherence to a set of rules.

// Copyright (C) 2001-2021 the original author or authors.

//

// This library is free software; you can redistribute it and/or

// modify it under the terms of the GNU Lesser General Public

// License as published by the Free Software Foundation; either

// version 2.1 of the License, or (at your option) any later version.

//

// This library is distributed in the hope that it will be useful,

// but WITHOUT ANY WARRANTY; without even the implied warranty of

// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU

// Lesser General Public License for more details.

//

// You should have received a copy of the GNU Lesser General Public

// License along with this library; if not, write to the Free Software

// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

////////////////////////////////////////////////////////////////////////////////

package com.puppycrawl.tools.checkstyle.checks.imports;

import java.net.URI;

import java.util.Collections;

import java.util.Set;

import java.util.regex.Pattern;

import com.puppycrawl.tools.checkstyle.FileStatefulCheck;

import com.puppycrawl.tools.checkstyle.api.AbstractCheck;

import com.puppycrawl.tools.checkstyle.api.CheckstyleException;

import com.puppycrawl.tools.checkstyle.api.DetailAST;

import com.puppycrawl.tools.checkstyle.api.ExternalResourceHolder;

import com.puppycrawl.tools.checkstyle.api.FullIdent;

import com.puppycrawl.tools.checkstyle.api.TokenTypes;

/**

 * <p>

 * Controls what can be imported in each package and file. Useful for ensuring

 * that application layering rules are not violated, especially on large projects.

 * </p>

 * <p>

 * You can control imports based on the a package name or based on the file name.

 * When controlling packages, all files and sub-packages in the declared package

 * will be controlled by this check. To specify differences between a main package

 * and a sub-package, you must define the sub-package inside the main package.

 * When controlling file, only the file name is considered and only files processed by

 * <a href="https://checkstyle.org/config.html#TreeWalker">TreeWalker</a>.

 * The file's extension is ignored.

 * </p>

 * <p>

 * Short description of the behaviour:

 * </p>

 * <ul>

 * <li>

 * Check starts checking from the longest matching subpackage (later 'current subpackage') or

 * the first file name match described inside import control file to package defined in class file.

 * <ul>

 * <li>

 * The longest matching subpackage is found by starting with the root package and

 * examining if the any of the sub-packages or file definitions match the current

 * class' package or file name.

 * </li>

 * <li>

 * If a file name is matched first, that is considered the longest match and becomes

 * the current file/subpackage.

 * </li>

 * <li>

 * If another subpackage is matched, then it's subpackages and file names are examined

 * for the next longest match and the process repeats recursively.

 * </li>

 * <li>

 * If no subpackages or file names are matched, the current subpackage is then used.

 * </li>

 * </ul>

 * </li>

 * <li>

 * Order of rules in the same subpackage/root are defined by the order of declaration

 * in the XML file, which is from top (first) to bottom (last).

 * </li>

 * <li>

 * If there is matching allow/disallow rule inside the current file/subpackage

 * then the Check returns the first "allowed" or "disallowed" message.

 * </li>

 * <li>

 * If there is no matching allow/disallow rule inside the current file/subpackage

 * then it continues checking in the parent subpackage.

 * </li>

 * <li>

 * If there is no matching allow/disallow rule in any of the files/subpackages,

 * including the root level (import-control), then the import is disallowed by default.

 * </li>

 * </ul>

 * <p>

 * The DTD for a import control XML document is at

 * <a href="https://checkstyle.org/dtds/import_control_1_4.dtd">

 * https://checkstyle.org/dtds/import_control_1_4.dtd</a>.

 * It contains documentation on each of the elements and attributes.

 * </p>

 * <p>

 * The check validates a XML document when it loads the document. To validate against

 * the above DTD, include the following document type declaration in your XML document:

 * </p>

 * <pre>

 * <!DOCTYPE import-control PUBLIC

 *     "-//Checkstyle//DTD ImportControl Configuration 1.4//EN"

 *     "https://checkstyle.org/dtds/import_control_1_4.dtd">

 * </pre>

 * <ul>

 * <li>

 * Property {@code file} - Specify the location of the file containing the

 * import control configuration. It can be a regular file, URL or resource path.

 * It will try loading the path as a URL first, then as a file, and finally as a resource.

 * Type is {@code java.net.URI}.

 * Default value is {@code null}.

 * </li>

 * <li>

 * Property {@code path} - Specify the regular expression of file paths to which

 * this check should apply. Files that don't match the pattern will not be checked.

 * The pattern will be matched against the full absolute file path.

 * Type is {@code java.util.regex.Pattern}.

 * Default value is {@code ".*"}.

 * </li>

 * </ul>

 * <p>

 * To configure the check using an import control file called "config/import-control.xml",

 * then have the following:

 * </p>

 * <pre>

 * <module name="ImportControl">

 *   <property name="file" value="config/import-control.xml"/>

 * </module>

 * </pre>

 * <p>

 * To configure the check to only check the "src/main" directory using an import

 * control file called "config/import-control.xml", then have the following:

 * </p>

 * <pre>

 * <module name="ImportControl">

 *   <property name="file" value="config/import-control.xml"/>

 *   <property name="path" value="^.*[\\/]src[\\/]main[\\/].*$"/>

 * </module>

 * </pre>

 * <p>

 * In the example below access to package {@code com.puppycrawl.tools.checkstyle.checks}

 * and its subpackages is allowed from anywhere in {@code com.puppycrawl.tools.checkstyle}

 * except from the {@code filters} subpackage where access to all {@code check}'s

 * subpackages is disallowed. Two {@code java.lang.ref} classes are allowed by virtue

 * of one regular expression instead of listing them in two separate allow rules

 * (as it is done with the {@code Files} and {@code ClassPath} classes).

 * </p>

 * <pre>

 * <import-control pkg="com.puppycrawl.tools.checkstyle">

 *   <disallow pkg="sun"/>

 *   <allow pkg="com.puppycrawl.tools.checkstyle.api"/>

 *   <allow pkg="com.puppycrawl.tools.checkstyle.checks"/>

 *   <allow class="com.google.common.io.Files"/>

 *   <allow class="com.google.common.reflect.ClassPath"/>

 *   <subpackage name="filters">

 *     <allow class="java\.lang\.ref\.(Weak|Soft)Reference"

 *       regex="true"/>

 *     <disallow pkg="com\.puppycrawl\.tools\.checkstyle\.checks\.[^.]+"

 *       regex="true"/>

 *     <disallow pkg="com.puppycrawl.tools.checkstyle.ant"/>

 *     <disallow pkg="com.puppycrawl.tools.checkstyle.gui"/>

 *   </subpackage>

 *   <subpackage name="dao">

 *     <disallow pkg="javax.swing" exact-match="true"/>

 *   </subpackage>

 * </import-control>

 * </pre>

 * <p>

 * In the next example regular expressions are used to enforce a layering rule:

 * In all {@code dao} packages it is not allowed to access UI layer code ({@code ui},

 * {@code awt}, and {@code swing}). On the other hand it is not allowed to directly

 * access {@code dao} and {@code service} layer from {@code ui} packages.

 * The root package is also a regular expression that is used to handle old and

 * new domain name with the same rules.

 * </p>

 * <pre>

 * <import-control pkg="(de.olddomain|de.newdomain)\..*" regex="true">

 *   <subpackage pkg="[^.]+\.dao" regex="true">

 *     <disallow pkg=".*\.ui" regex="true"/>

 *     <disallow pkg=".*\.(awt|swing).\.*" regex="true"/>

 *   </subpackage>

 *   <subpackage pkg="[^.]+\.ui" regex="true">

 *     <disallow pkg=".*\.(dao|service)" regex="true"/>

 *   </subpackage>

 * </import-control>

 * </pre>

 * <p>

 * In the next examples usage of {@code strategyOnMismatch} property is shown.

 * This property defines strategy in a case when no matching allow/disallow rule was found.

 * Property {@code strategyOnMismatch} is attribute of {@code import-control} and

 * {@code subpackage} tags. Property can have following values for {@code import-control} tag:

 * </p>

 * <ul>

 * <li>

 * disallowed (default value) - if there is no matching allow/disallow rule in any of

 * the subpackages, including the root level (import-control), then the import is disallowed.

 * </li>

 * <li>

 * allowed - if there is no matching allow/disallow rule in any of the subpackages,

 * including the root level, then the import is allowed.

 * </li>

 * </ul>

 * <p>

 * And following values for {@code subpackage} tags:

 * </p>

 * <ul>

 * <li>

 * delegateToParent (default value) - if there is no matching allow/disallow rule

 * inside the current subpackage, then it continues checking in the parent subpackage.

 * </li>

 * <li>

 * allowed - if there is no matching allow/disallow rule inside the current subpackage,

 * then the import is allowed.

 * </li>

 * <li>

 * disallowed - if there is no matching allow/disallow rule inside the current subpackage,

 * then the import is disallowed.

 * </li>

 * </ul>

 * <p>

 * The following example demonstrates usage of {@code strategyOnMismatch}

 * property for {@code import-control} tag. Here all imports are allowed except

 * {@code java.awt.Image} and {@code java.io.File} classes.

 * </p>

 * <pre>

 * <import-control pkg="com.puppycrawl.tools.checkstyle.checks"

 *   strategyOnMismatch="allowed">

 *   <disallow class="java.awt.Image"/>

 *   <disallow class="java.io.File"/>

 * </import-control>

 * </pre>

 * <p>

 * In the example below, any import is disallowed inside

 * {@code com.puppycrawl.tools.checkstyle.checks.imports} package except imports

 * from package {@code javax.swing} and class {@code java.io.File}.

 * However, any import is allowed in the classes outside of

 * {@code com.puppycrawl.tools.checkstyle.checks.imports} package.

 * </p>

 * <pre>

 * <import-control pkg="com.puppycrawl.tools.checkstyle.checks"

 *   strategyOnMismatch="allowed">

 *   <subpackage name="imports" strategyOnMismatch="disallowed">

 *     <allow pkg="javax.swing"/>

 *     <allow class="java.io.File"/>

 *   </subpackage>

 * </import-control>

 * </pre>

 * <p>

 * When {@code strategyOnMismatch} has {@code allowed} or {@code disallowed}

 * value for {@code subpackage} tag, it makes {@code subpackage} isolated from

 * parent rules. In the next example, if no matching rule was found inside

 * {@code com.puppycrawl.tools.checkstyle.checks.filters} then it continues

 * checking in the parent subpackage, while for

 * {@code com.puppycrawl.tools.checkstyle.checks.imports} import will be allowed by default.

 * </p>

 * <pre>

 * <import-control pkg="com.puppycrawl.tools.checkstyle.checks">

 *   <allow class="java\.awt\.Image" regex="true"/>

 *   <allow class="java\..*\.File" local-only="true" regex="true"/>

 *   <subpackage name="imports" strategyOnMismatch="allowed">

 *     <allow pkg="javax\.swing" regex="true"/>

 *     <allow pkg="java\.io" exact-match="true"

 *       local-only="true" regex="true"/>

 *   </subpackage>

 *   <subpackage name="filters">

 *     <allow class="javax.util.Date"/>

 *   </subpackage>

 * </import-control>

 * </pre>

 * <p>

 * In the example below, only file names that end with "Panel", "View", or "Dialog"

 * in the package {@code gui} are disallowed to have imports from {@code com.mycompany.dao}

 * and any {@code jdbc} package. In addition, only the file name named "PresentationModel"

 * in the package {@code gui} are disallowed to have imports that match {@code javax.swing.J*}.

 * All other imports in the package are allowed.

 * </p>

 * <pre>

 * <import-control pkg="com.mycompany.billing">

 *   <subpackage name="gui" strategyOnMismatch="allowed">

 *     <file name=".*(Panel|View|Dialog)" regex="true">

 *       <disallow pkg="com.mycompany.dao"/>

 *       <disallow pkg=".*\.jdbc" regex="true"/>

 *     </file>

 *     <file name="PresentationModel">

 *       <disallow pkg="javax\.swing\.J.*" regex="true"/>

 *     </file>

 *   </subpackage>

 * </import-control>

 * </pre>

 * <p>

 * For a real-life import control file look at the file called

 * <a href="https://github.com/checkstyle/checkstyle/blob/master/config/import-control.xml">

 * import-control.xml</a> which is part of the Checkstyle distribution.

 * </p>

 * <p id="blacklist-example">Example of blacklist mode</p>

 * <p>

 * To have a <b>blacklist mode</b>, it is required to have disallows inside

 * subpackage and to have allow rule inside parent of the current subpackage

 * to catch classes and packages those are not in the blacklist.

 * </p>

 * <p>

 * In the example below any import from {@code java.util}({@code java.util.List},

 * {@code java.util.Date}) package is allowed except {@code java.util.Map}

 * inside subpackage {@code com.puppycrawl.tools.checkstyle.filters}.

 * </p>

 * <pre>

 * <import-control pkg="com.puppycrawl.tools.checkstyle">

 *   <allow pkg="java.util"/>

 *   <subpackage name="filters" >

 *     <disallow class="java.util.Map"/>

 *   </subpackage>

 * </import-control>

 * </pre>

 * <p>

 * In the next example imports {@code java.util.stream.Stream} and

 * {@code java.util.stream.Collectors} are disallowed inside

 * {@code com.puppycrawl.tools.checkstyle.checks.imports} package, but because of

 * {@code <allow pkg="java.util.stream"/>} every import from

 * {@code java.util.stream} is allowed except described ones.

 * </p>

 * <pre>

 * <import-control pkg="com.puppycrawl.tools.checkstyle.checks">

 *   <allow pkg="java.util.stream"/>

 *   <subpackage name="imports">

 *     <disallow class="java.util.stream.Stream"/>

 *     <disallow class="java.util.stream.Collectors"/>

 *   </subpackage>

 * </import-control>

 * </pre>

 * <pre>

 * package com.puppycrawl.tools.checkstyle.checks.imports;

 *

 * import java.util.stream.Stream;     // violation here

 * import java.util.stream.Collectors; // violation here

 * import java.util.stream.IntStream;

 * </pre>

 * <p>

 * In the following example, all imports are allowed except the classes

 * {@code java.util.Date}, {@code java.util.List} and package {@code sun}.

 * </p>

 * <pre>

 * <import-control pkg="com.puppycrawl.tools.checkstyle.checks">

 *   <allow pkg=".*" regex="true"/>

 *   <subpackage name="imports">

 *     <disallow class="java.util.Date"/>

 *     <disallow class="java.util.List"/>

 *     <disallow pkg="sun"/>

 *   </subpackage>

 * </import-control>

 * </pre>

 * <p>

 * In the following example, all imports of the {@code java.util} package are

 * allowed except the {@code java.util.Date} class.

 * </p>

 * <pre>

 * <import-control pkg="com.puppycrawl.tools.checkstyle.checks">

 *   <disallow class="java.util.Date"/>

 *

 *   <allow pkg="java.util"/>

 * </import-control>

 * </pre>

 * <p id="regex-notes">Notes on regular expressions</p>

 * <p>

 * Regular expressions in import rules have to match either Java packages or classes.

 * The language rules for packages and class names can be described by the following

 * complicated regular expression that takes into account that Java names may contain

 * any unicode letter, numbers, underscores, and dollar signs (see section 3.8 in the

 * <a href="https://docs.oracle.com/javase/specs/">Java specs</a>):

 * </p>

 * <ul>

 * <li>

 * {@code [\p{Letter}_$][\p{Letter}\p{Number}_$]*} or short {@code [\p{L}_$][\p{L}\p{N}_$]*}

 * for a class name or package component.

 * </li>

 * <li>

 * {@code ([\p{L}_$][\p{L}\p{N}_$]*\.)*[\p{L}_$][\p{L}\p{N}_$]*} for a fully qualified name.

 * </li>

 * </ul>

 * <p>

 * But it is not necessary to use these complicated expressions since no validation is required.

 * Differentiating between package separator '.' and others is sufficient.

 * Unfortunately '.' has a special meaning in regular expressions so one has to write {@code \.}

 * to match an actual dot.

 * </p>

 * <ul>

 * <li>

 * Use {@code [^.]+}(one or more "not a dot" characters) for a class name or package component.

 * </li>

 * <li>

 * Use {@code com\.google\.common\.[^.]+} to match any subpackage of {@code com.google.common}.

 * </li>

 * <li>

 * When matching concrete packages like {@code com.google.common} omitting the backslash before

 * the dots may improve readability and may be just exact enough: {@code com.google.common\.[^.]+}

 * matches not only subpackages of {@code com.google.common} but e.g. also of

 * {@code com.googleecommon} but you may not care for that.

 * </li>

 * <li>

 * Do not use {@code .*} unless you really do not care for what is matched.

 * Often you want to match only a certain package level instead.

 * </li>

 * </ul><p id="static-import-notes">Notes on static imports</p>

 * <p>

 * Static members (including methods, constants and static inner classes)

 * have to be explicitly allowed when they are imported, they are not automatically

 * allowed along with their enclosing class.

 * </p>

 * <p>

 * For example, to allow importing both {@code java.util.Map} and {@code java.util.Map.Entry}

 * use the following configuration:

 * </p>

 * <pre>

 * <import-control pkg="com.puppycrawl.tools.checkstyle">

 *   <allow class="java.util.Map"/>

 *   <allow class="java.util.Map.Entry"/>

 * </import-control>

 * </pre>

 * <p>

 * It is also possible to use a regex with a wildcard:

 * </p>

 * <pre>

 * <import-control pkg="com.puppycrawl.tools.checkstyle">

 *   <allow class="java.util.Map"/>

 *   <allow class="java.util.Map.*" regex="true" />

 * </import-control>

 * </pre>

 * <p>

 * Parent is {@code com.puppycrawl.tools.checkstyle.TreeWalker}

 * </p>

 * <p>

 * Violation Message Keys:

 * </p>

 * <ul>

 * <li>

 * {@code import.control.disallowed}

 * </li>

 * <li>

 * {@code import.control.missing.file}

 * </li>

 * <li>

 * {@code import.control.unknown.pkg}

 * </li>

 * </ul>

 *

 * @since 4.0

 */

@FileStatefulCheck

    /**

     * A key is pointing to the warning message text in "messages.properties"

     * file.

     */

    public static final String MSG_MISSING_FILE = "import.control.missing.file";

    /**

     * A key is pointing to the warning message text in "messages.properties"

     * file.

     */

    public static final String MSG_UNKNOWN_PKG = "import.control.unknown.pkg";

    /**

     * A key is pointing to the warning message text in "messages.properties"

     * file.

     */

    public static final String MSG_DISALLOWED = "import.control.disallowed";

    /**

     * A part of message for exception.

     */

    private static final String UNABLE_TO_LOAD = "Unable to load ";

    /**

     * Specify the location of the file containing the import control configuration.

     * It can be a regular file, URL or resource path. It will try loading the path

     * as a URL first, then as a file, and finally as a resource.

     */

    private URI file;

    /**

     * Specify the regular expression of file paths to which this check should apply.

     * Files that don't match the pattern will not be checked. The pattern will

     * be matched against the full absolute file path.

     */

    /** Whether to process the current file. */

    private boolean processCurrentFile;

    /** The root package controller. */

    private PkgImportControl root;

    /** The package doing the import. */

    private String packageName;

    /** The file name doing the import. */

    private String fileName;

    /**

     * The package controller for the current file. Used for performance

     * optimisation.

     */

    private AbstractImportControl currentImportControl;

    @Override

    public int[] getDefaultTokens() {

    }

    @Override

    public int[] getAcceptableTokens() {

    }

    @Override

    public int[] getRequiredTokens() {

    }

    @Override

    public void beginTree(DetailAST rootAST) {

        }

    @Override

    public void visitToken(DetailAST ast) {

                }

                else {

                    }

                }

            }

                        importText);

                }

            }

        }

    @Override

    public Set<String> getExternalResourceLocations() {

    }

    /**

     * Returns package text.

     *

     * @param ast PACKAGE_DEF ast node

     * @return String that represents full package name

     */

    private static String getPackageText(DetailAST ast) {

    }

    /**

     * Returns import text.

     *

     * @param ast ast node that represents import

     * @return String that represents importing class

     */

    private static String getImportText(DetailAST ast) {

        final FullIdent imp;

        }

        else {

            // know it is a static import

        }

    }

    /**

     * Setter to specify the location of the file containing the import control configuration.

     * It can be a regular file, URL or resource path. It will try loading the path

     * as a URL first, then as a file, and finally as a resource.

     *

     * @param uri the uri of the file to load.

     * @throws IllegalArgumentException on error loading the file.

     */

    public void setFile(URI uri) {

        // Handle empty param

            try {

            }

        }

    /**

     * Setter to specify the regular expression of file paths to which this check should apply.

     * Files that don't match the pattern will not be checked. The pattern will be matched

     * against the full absolute file path.

     *

     * @param pattern the file path regex this check should apply to.

     */

    public void setPath(Pattern pattern) {

}

Mutations