///////////////////////////////////////////////////////////////////////////////////////////////
// checkstyle: Checks Java source code and other text files for adherence to a set of rules.
// Copyright (C) 2001-2026 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;

import java.io.File;
import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.ArrayList;
import java.util.List;
import java.util.Locale;
import java.util.Objects;
import java.util.Properties;
import java.util.logging.ConsoleHandler;
import java.util.logging.Filter;
import java.util.logging.Level;
import java.util.logging.LogRecord;
import java.util.logging.Logger;
import java.util.regex.Pattern;
import java.util.stream.Collectors;

import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;

import com.puppycrawl.tools.checkstyle.AbstractAutomaticBean.OutputStreamOptions;
import com.puppycrawl.tools.checkstyle.api.AuditEvent;
import com.puppycrawl.tools.checkstyle.api.AuditListener;
import com.puppycrawl.tools.checkstyle.api.CheckstyleException;
import com.puppycrawl.tools.checkstyle.api.Configuration;
import com.puppycrawl.tools.checkstyle.api.RootModule;
import com.puppycrawl.tools.checkstyle.utils.ChainedPropertyUtil;
import com.puppycrawl.tools.checkstyle.utils.CommonUtil;
import com.puppycrawl.tools.checkstyle.utils.XpathUtil;
import picocli.CommandLine;
import picocli.CommandLine.Command;
import picocli.CommandLine.Option;
import picocli.CommandLine.ParameterException;
import picocli.CommandLine.Parameters;
import picocli.CommandLine.ParseResult;

/**
 * Wrapper command line program for the Checker.
 */
public final class Main {

    /**
     * A key pointing to the error counter message in the "messages.properties" file.
     */
    public static final String ERROR_COUNTER = "Main.errorCounter";
    /**
     * A key pointing to the load properties exception message in the "messages.properties" file.
     */
    public static final String LOAD_PROPERTIES_EXCEPTION = "Main.loadProperties";
    /**
     * A key pointing to the create listener exception message in the "messages.properties" file.
     */
    public static final String CREATE_LISTENER_EXCEPTION = "Main.createListener";

    /** Logger for Main. */
    private static final Log LOG = LogFactory.getLog(Main.class);

    /** Exit code returned when user specified invalid command line arguments. */
    private static final int EXIT_WITH_INVALID_USER_INPUT_CODE = -1;

    /** Exit code returned when execution finishes with {@link CheckstyleException}. */
    private static final int EXIT_WITH_CHECKSTYLE_EXCEPTION_CODE = -2;

    /** Maximum exit code, so the number of errors can not wrap around to 0. */
    private static final int MAX_EXIT_CODE = 255;

    /**
     * Client code should not create instances of this class, but use
     * {@link #main(String[])} method instead.
     */
    private Main() {
    }

    /**
     * Loops over the files specified checking them for errors. The exit code
     * is the number of errors found in all the files, but no more than 255,
     * so it can not wrap around to 0 on a multiple of 256 errors.
     *
     * @param args the command line arguments.
     * @throws IOException if there is a problem with files access
     * @noinspection UseOfSystemOutOrSystemErr, CallToPrintStackTrace, CallToSystemExit
     * @noinspectionreason UseOfSystemOutOrSystemErr - driver class for Checkstyle requires
     *      usage of System.out and System.err
     * @noinspectionreason CallToPrintStackTrace - driver class for Checkstyle must be able to
     *      show all details in case of failure
     * @noinspectionreason CallToSystemExit - driver class must call exit
     */
    public static void main(String... args) throws IOException {

        final CliOptions cliOptions = new CliOptions();
        final CommandLine commandLine = new CommandLine(cliOptions);
        commandLine.setUsageHelpWidth(CliOptions.HELP_WIDTH);
        commandLine.setCaseInsensitiveEnumValuesAllowed(true);

        // provide proper exit code based on results.
        int exitStatus = 0;
        int errorCounter = 0;
        try {
            final ParseResult parseResult = commandLine.parseArgs(args);
            if (parseResult.isVersionHelpRequested()) {
                printVersionToSystemOutput();
            }
            else if (parseResult.isUsageHelpRequested()) {
                commandLine.usage(System.out);
            }
            else {
                exitStatus = execute(parseResult, cliOptions);
                errorCounter = exitStatus;
            }
        }
        catch (ParameterException exc) {
            exitStatus = EXIT_WITH_INVALID_USER_INPUT_CODE;
            System.err.println(exc.getMessage());
            System.err.println("Usage: checkstyle [OPTIONS]... file(s) or folder(s) ...");
            System.err.println("Try 'checkstyle --help' for more information.");
        }
        catch (CheckstyleException exc) {
            exitStatus = EXIT_WITH_CHECKSTYLE_EXCEPTION_CODE;
            errorCounter = 1;
            exc.printStackTrace();
        }
        finally {
            // return exit code base on validation of Checker
            if (errorCounter > 0) {
                final LocalizedMessage errorCounterViolation = new LocalizedMessage(
                        Definitions.CHECKSTYLE_BUNDLE, Main.class,
                        ERROR_COUNTER, String.valueOf(errorCounter));
                // print error count statistic to error output stream,
                // output stream might be used by validation report content
                System.err.println(errorCounterViolation.getMessage());
            }
        }
        Runtime.getRuntime().exit(Math.min(exitStatus, MAX_EXIT_CODE));
    }

    /**
     * Prints version string when the user requests version help (--version or -V).
     *
     * @noinspection UseOfSystemOutOrSystemErr
     * @noinspectionreason UseOfSystemOutOrSystemErr - driver class for Checkstyle requires
     *      usage of System.out and System.err
     */
    private static void printVersionToSystemOutput() {
        System.out.println("Checkstyle version: " + getVersionString());
    }

    /**
     * Returns the version string printed when the user requests version help (--version or -V).
     *
     * @return a version string based on the package implementation version
     */
    private static String getVersionString() {
        return Main.class.getPackage().getImplementationVersion();
    }

    /**
     * Validates the user input and returns {@value #EXIT_WITH_INVALID_USER_INPUT_CODE} if
     * invalid, otherwise executes CheckStyle and returns the number of violations.
     *
     * @param parseResult generic access to options and parameters found on the command line
     * @param options encapsulates options and parameters specified on the command line
     * @return number of violations
     * @throws CheckstyleException if something happens processing the files.
     * @throws IOException if a file could not be read.
     * @noinspection UseOfSystemOutOrSystemErr
     * @noinspectionreason UseOfSystemOutOrSystemErr - driver class for Checkstyle requires
     *      usage of System.out and System.err
     */
    private static int execute(ParseResult parseResult, CliOptions options)
            throws IOException, CheckstyleException {

        final int exitStatus;

        // return error if something is wrong in arguments
        final List<File> filesToProcess = getFilesToProcess(options);
        final List<String> messages = options.validateCli(parseResult, filesToProcess);
        final boolean hasMessages = !messages.isEmpty();
        if (hasMessages) {
            messages.forEach(System.out::println);
            exitStatus = EXIT_WITH_INVALID_USER_INPUT_CODE;
        }
        else {
            exitStatus = runCli(options, filesToProcess);
        }
        return exitStatus;
    }

    /**
     * Determines the files to process.
     *
     * @param options the user-specified options
     * @return list of files to process
     */
    private static List<File> getFilesToProcess(CliOptions options) {
        final List<Pattern> patternsToExclude = options.getExclusions();

        final List<File> result = new ArrayList<>();
        for (File file : options.files) {
            result.addAll(listFiles(file, patternsToExclude));
        }
        return result;
    }

    /**
     * Traverses a specified node looking for files to check. Found files are added to
     * a specified list. Subdirectories are also traversed.
     *
     * @param node
     *        the node to process
     * @param patternsToExclude The list of patterns to exclude from searching or being added as
     *        files.
     * @return found files
     */
    private static List<File> listFiles(File node, List<Pattern> patternsToExclude) {
        // could be replaced with org.apache.commons.io.FileUtils.list() method
        // if only we add commons-io library
        final List<File> result = new ArrayList<>();

        if (node.canRead() && !isPathExcluded(node.getAbsolutePath(), patternsToExclude)) {
            if (node.isDirectory()) {
                final File[] files = node.listFiles();
                // listFiles() can return null, so we need to check it
                if (files != null) {
                    for (File element : files) {
                        result.addAll(listFiles(element, patternsToExclude));
                    }
                }
            }
            else if (node.isFile()) {
                result.add(node);
            }
        }
        return result;
    }

    /**
     * Checks if a directory/file {@code path} should be excluded based on if it matches one of the
     * patterns supplied.
     *
     * @param path The path of the directory/file to check
     * @param patternsToExclude The collection of patterns to exclude from searching
     *        or being added as files.
     * @return True if the directory/file matches one of the patterns.
     */
    private static boolean isPathExcluded(String path, Iterable<Pattern> patternsToExclude) {
        boolean result = false;

        for (Pattern pattern : patternsToExclude) {
            if (pattern.matcher(path).find()) {
                result = true;
                break;
            }
        }

        return result;
    }

    /**
     * Do execution of CheckStyle based on Command line options.
     *
     * @param options user-specified options
     * @param filesToProcess the list of files whose style to check
     * @return number of violations
     * @throws CheckstyleException if something happens processing the files.
     * @throws IOException if a file could not be read.
     * @noinspection UseOfSystemOutOrSystemErr
     * @noinspectionreason UseOfSystemOutOrSystemErr - driver class for Checkstyle requires
     *      usage of System.out and System.err
     */
    private static int runCli(CliOptions options, List<File> filesToProcess)
            throws IOException, CheckstyleException {
        int result = 0;
        final boolean hasSuppressionLineColumnNumber = options.suppressionLineColumnNumber != null;

        // create config helper object
        if (options.printAst) {
            // print AST
            final File file = filesToProcess.getFirst();
            final String stringAst = AstTreeStringPrinter.printFileAst(file,
                    JavaParser.Options.WITHOUT_COMMENTS);
            System.out.print(stringAst);
        }
        else if (Objects.nonNull(options.xpath)) {
            final String branch =
                    XpathUtil.printXpathBranch(options.xpath, filesToProcess.getFirst());
            System.out.print(branch);
        }
        else if (options.printAstWithComments) {
            final File file = filesToProcess.getFirst();
            final String stringAst = AstTreeStringPrinter.printFileAst(file,
                    JavaParser.Options.WITH_COMMENTS);
            System.out.print(stringAst);
        }
        else if (options.printJavadocTree) {
            final File file = filesToProcess.getFirst();
            final String stringAst = DetailNodeTreeStringPrinter.printFileAst(file);
            System.out.print(stringAst);
        }
        else if (options.printTreeWithJavadoc) {
            final File file = filesToProcess.getFirst();
            final String stringAst = AstTreeStringPrinter.printJavaAndJavadocTree(file);
            System.out.print(stringAst);
        }
        else if (hasSuppressionLineColumnNumber) {
            final File file = filesToProcess.getFirst();
            final String stringSuppressions =
                    SuppressionsStringPrinter.printSuppressions(file,
                            options.suppressionLineColumnNumber, options.tabWidth);
            System.out.print(stringSuppressions);
        }
        else {
            if (options.debug) {
                final Logger parentLogger = Logger.getLogger(Main.class.getName()).getParent();
                final ConsoleHandler handler = new ConsoleHandler();
                handler.setLevel(Level.FINEST);
                handler.setFilter(new OnlyCheckstyleLoggersFilter());
                parentLogger.addHandler(handler);
                parentLogger.setLevel(Level.FINEST);
            }
            if (LOG.isDebugEnabled()) {
                LOG.debug("Checkstyle debug logging enabled");
            }

            // run Checker
            result = runCheckstyle(options, filesToProcess);
        }

        return result;
    }

    /**
     * Executes required Checkstyle actions based on passed parameters.
     *
     * @param options user-specified options
     * @param filesToProcess the list of files whose style to check
     * @return number of violations of ERROR level
     * @throws CheckstyleException
     *         when properties file could not be loaded
     * @throws IOException
     *         when output file could not be found
     */
    private static int runCheckstyle(CliOptions options, List<File> filesToProcess)
            throws CheckstyleException, IOException {
        // setup the properties
        final Properties props;

        if (options.propertiesFile == null) {
            props = System.getProperties();
        }
        else {
            props = loadProperties(options.propertiesFile);
        }

        // create a configuration

        final ConfigurationLoader.IgnoredModulesOptions ignoredModulesOptions;
        if (options.executeIgnoredModules) {
            ignoredModulesOptions = ConfigurationLoader.IgnoredModulesOptions.EXECUTE;
        }
        else {
            ignoredModulesOptions = ConfigurationLoader.IgnoredModulesOptions.OMIT;
        }

        final ThreadModeSettings multiThreadModeSettings =
                new ThreadModeSettings(CliOptions.CHECKER_THREADS_NUMBER,
                CliOptions.TREE_WALKER_THREADS_NUMBER);
        final Configuration config = ConfigurationLoader.loadConfiguration(
                options.configurationFile, new PropertiesExpander(props),
                ignoredModulesOptions, multiThreadModeSettings);

        // create RootModule object and run it
        final int errorCounter;
        final ClassLoader moduleClassLoader = Checker.class.getClassLoader();
        final RootModule rootModule = getRootModule(config.getName(), moduleClassLoader);

        try {
            final AuditListener listener;
            if (options.generateXpathSuppressionsFile) {
                // create filter to print generated xpath suppressions file
                final Configuration treeWalkerConfig = getTreeWalkerConfig(config);
                if (treeWalkerConfig != null) {
                    final DefaultConfiguration moduleConfig =
                            new DefaultConfiguration(
                                    XpathFileGeneratorAstFilter.class.getName());
                    moduleConfig.addProperty(CliOptions.ATTRIB_TAB_WIDTH_NAME,
                            String.valueOf(options.tabWidth));
                    ((DefaultConfiguration) treeWalkerConfig).addChild(moduleConfig);
                }

                listener = new XpathFileGeneratorAuditListener(getOutputStream(options.outputPath),
                        getOutputStreamOptions(options.outputPath));
            }
            else if (options.generateCheckAndFileSuppressionsFile) {
                listener = new ChecksAndFilesSuppressionFileGeneratorAuditListener(
                        getOutputStream(options.outputPath),
                        getOutputStreamOptions(options.outputPath));
            }
            else {
                listener = createListener(options.format, options.outputPath);
            }

            rootModule.setModuleClassLoader(moduleClassLoader);
            rootModule.configure(config);
            rootModule.addListener(listener);

            // run RootModule
            errorCounter = rootModule.process(filesToProcess);
        }
        finally {
            rootModule.destroy();
        }

        return errorCounter;
    }

    /**
     * Loads properties from a File.
     *
     * @param file
     *        the properties file
     * @return the properties in file
     * @throws CheckstyleException
     *         when could not load properties file
     */
    private static Properties loadProperties(File file)
            throws CheckstyleException {
        final Properties properties = new Properties();

        try (InputStream stream = Files.newInputStream(file.toPath())) {
            properties.load(stream);
        }
        catch (final IOException exc) {
            final LocalizedMessage loadPropertiesExceptionMessage = new LocalizedMessage(
                    Definitions.CHECKSTYLE_BUNDLE, Main.class,
                    LOAD_PROPERTIES_EXCEPTION, file.getAbsolutePath());
            throw new CheckstyleException(loadPropertiesExceptionMessage.getMessage(), exc);
        }

        return ChainedPropertyUtil.getResolvedProperties(properties);
    }

    /**
     * Creates a new instance of the root module that will control and run Checkstyle.
     *
     * @param name The name of the module. This will either be a short name that
     *        will have to be found or the complete package name.
     * @param moduleClassLoader Class loader used to load the root module.
     * @return The new instance of the root module.
     * @throws CheckstyleException if no module can be instantiated from name
     */
    private static RootModule getRootModule(String name, ClassLoader moduleClassLoader)
            throws CheckstyleException {
        final ModuleFactory factory = new PackageObjectFactory(
                Checker.class.getPackage().getName(), moduleClassLoader);

        return (RootModule) factory.createModule(name);
    }

    /**
     * Returns {@code TreeWalker} module configuration.
     *
     * @param config The configuration object.
     * @return The {@code TreeWalker} module configuration.
     */
    private static Configuration getTreeWalkerConfig(Configuration config) {
        Configuration result = null;

        final Configuration[] children = config.getChildren();
        for (Configuration child : children) {
            if ("TreeWalker".equals(child.getName())) {
                result = child;
                break;
            }
        }
        return result;
    }

    /**
     * This method creates in AuditListener an open stream for validation data, it must be
     * closed by {@link RootModule} (default implementation is {@link Checker}) by calling
     * {@link AuditListener#auditFinished(AuditEvent)}.
     *
     * @param format format of the audit listener
     * @param outputLocation the location of output
     * @return a fresh new {@code AuditListener}
     * @throws IOException when provided output location is not found
     */
    private static AuditListener createListener(OutputFormat format, Path outputLocation)
            throws IOException {
        final OutputStream out = getOutputStream(outputLocation);
        final OutputStreamOptions closeOutputStreamOption =
                getOutputStreamOptions(outputLocation);
        return format.createListener(out, closeOutputStreamOption);
    }

    /**
     * Create output stream or return System.out.
     *
     * @param outputPath output location
     * @return output stream
     * @throws IOException might happen
     * @noinspection UseOfSystemOutOrSystemErr
     * @noinspectionreason UseOfSystemOutOrSystemErr - driver class for Checkstyle requires
     *      usage of System.out and System.err
     */
    @SuppressWarnings("resource")
    private static OutputStream getOutputStream(Path outputPath) throws IOException {
        final OutputStream result;
        if (outputPath == null) {
            result = System.out;
        }
        else {
            result = Files.newOutputStream(outputPath);
        }
        return result;
    }

    /**
     * Create {@link OutputStreamOptions} for the given location.
     *
     * @param outputPath output location
     * @return output stream options
     */
    private static OutputStreamOptions getOutputStreamOptions(Path outputPath) {
        final OutputStreamOptions result;
        if (outputPath == null) {
            result = OutputStreamOptions.NONE;
        }
        else {
            result = OutputStreamOptions.CLOSE;
        }
        return result;
    }

    /**
     * Enumeration over the possible output formats.
     *
     * @noinspection PackageVisibleInnerClass
     * @noinspectionreason PackageVisibleInnerClass - we keep this enum package visible for tests
     */
    /* package */ enum OutputFormat {

        /** XML output format. */
        XML,
        /** SARIF output format. */
        SARIF,
        /** Plain output format. */
        PLAIN;

        /**
         * Returns a new AuditListener for this OutputFormat.
         *
         * @param out the output stream
         * @param options the output stream options
         * @return a new AuditListener for this OutputFormat
         * @throws IOException if there is any IO exception during logger initialization
         */
        /* package */ AuditListener createListener(
            OutputStream out,
            OutputStreamOptions options)
                    throws IOException {
            final AuditListener result;
            if (this == XML) {
                result = new XMLLogger(out, options);
            }
            else if (this == SARIF) {
                result = new SarifLogger(out, options);
            }
            else {
                result = new DefaultLogger(out, options);
            }
            return result;
        }

        /**
         * Returns the name in lowercase.
         *
         * @return the enum name in lowercase
         */
        @Override
        public String toString() {
            return name().toLowerCase(Locale.ROOT);
        }

    }

    /** Log Filter used in debug mode. */
    private static final class OnlyCheckstyleLoggersFilter implements Filter {

        /** Name of the package used to filter on. */
        private final String packageName = Main.class.getPackage().getName();

        /**
         * Creates a new {@code OnlyCheckstyleLoggersFilter} instance.
         */
        private OnlyCheckstyleLoggersFilter() {
            // no code by default
        }

        /**
         * Returns whether the specified logRecord should be logged.
         *
         * @param logRecord the logRecord to log
         * @return true if the logger name is in the package of this class or a subpackage
         */
        @Override
        public boolean isLoggable(LogRecord logRecord) {
            return logRecord.getLoggerName().startsWith(packageName);
        }

    }

    /**
     * Command line options.
     *
     * @noinspection unused, FieldMayBeFinal, CanBeFinal,
     *              MismatchedQueryAndUpdateOfCollection, LocalCanBeFinal
     * @noinspectionreason FieldMayBeFinal - usage of picocli requires
     *      suppression of above inspections
     * @noinspectionreason CanBeFinal - usage of picocli requires suppression of above inspections
     * @noinspectionreason MismatchedQueryAndUpdateOfCollection - list of files is gathered and used
     *      via reflection by picocli library
     * @noinspectionreason LocalCanBeFinal - usage of picocli requires
     *      suppression of above inspections
     */
    @Command(name = "checkstyle", description = "Checkstyle verifies that the specified "
            + "source code files adhere to the specified rules. By default, violations are "
            + "reported to standard out in plain format. Checkstyle requires a configuration "
            + "XML file that configures the checks to apply.",
            mixinStandardHelpOptions = true)
    private static final class CliOptions {

        /** Width of CLI help option. */
        private static final int HELP_WIDTH = 100;

        /** The default number of threads to use for checker and the tree walker. */
        private static final int DEFAULT_THREAD_COUNT = 1;

        /** Name for the moduleConfig attribute 'tabWidth'. */
        private static final String ATTRIB_TAB_WIDTH_NAME = "tabWidth";

        /** Default output format. */
        private static final OutputFormat DEFAULT_OUTPUT_FORMAT = OutputFormat.PLAIN;

        /** Option name for output format. */
        private static final String OUTPUT_FORMAT_OPTION = "-f";

        /**
         * The checker threads number.
         * This option has been skipped for CLI options intentionally.
         *
         */
        private static final int CHECKER_THREADS_NUMBER = DEFAULT_THREAD_COUNT;

        /**
         * The tree walker threads number.
         *
         */
        private static final int TREE_WALKER_THREADS_NUMBER = DEFAULT_THREAD_COUNT;

        /** List of file to validate. */
        @Parameters(arity = "1..*", paramLabel = "<files or folders>",
                description = "One or more source files to verify")
        private List<File> files;

        /** Config file location. */
        @Option(names = "-c", description = "Specifies the location of the file that defines"
                + " the configuration modules. The location can either be a filesystem location"
                + ", or a name passed to the ClassLoader.getResource() method.")
        private String configurationFile;

        /** Output file location. */
        @Option(names = "-o", description = "Sets the output file. Defaults to stdout.")
        private Path outputPath;

        /** Properties file location. */
        @Option(names = "-p", description = "Sets the property files to load.")
        private File propertiesFile;

        /** LineNo and columnNo for the suppression. */
        @Option(names = "-s",
                description = "Prints xpath suppressions at the file's line and column position. "
                        + "Argument is the line and column number (separated by a : ) in the file "
                        + "that the suppression should be generated for. The option cannot be used "
                        + "with other options and requires exactly one file to run on to be "
                        + "specified. Note that the generated result will have few queries, joined "
                        + "by pipe(|). Together they will match all AST nodes on "
                        + "specified line and column. You need to choose only one and recheck "
                        + "that it works. Usage of all of them is also ok, but might result in "
                        + "undesirable matching and suppress other issues.")
        private String suppressionLineColumnNumber;

        /**
         * Tab character length.
         *
         * @noinspection CanBeFinal
         * @noinspectionreason CanBeFinal - we use picocli, and it uses
         *      reflection to manage such fields
         */
        @Option(names = {"-w", "--tabWidth"},
                description = "Sets the length of the tab character. "
                + "Used only with -s option. Default value is ${DEFAULT-VALUE}.")
        private int tabWidth = CommonUtil.DEFAULT_TAB_WIDTH;

        /** Switch whether to generate xpath suppressions file or not. */
        @Option(names = {"-g", "--generate-xpath-suppression"},
                description = "Generates an output xpath suppression XML to use to suppress all "
                        + "violations from user's config. Instead of printing every violation, "
                        + "all violations will be caught and single suppressions xml file will "
                        + "be printed out. Used only with -c option. Output "
                        + "location can be specified with -o option.")
        private boolean generateXpathSuppressionsFile;

        /** Switch whether to generate check and file suppressions file or not. */
        @Option(names = {"-G", "--generate-checks-and-files-suppression"},
                description = "Generates an output suppression XML that will have suppress "
                        + "elements with \"checks\" and \"files\" attributes only to use to "
                        + "suppress all violations from user's config. Instead of printing every "
                        + "violation, all violations will be caught and single suppressions xml "
                        + "file will be printed out. Used only with -c option. Output "
                        + "location can be specified with -o option.")
        private boolean generateCheckAndFileSuppressionsFile;

        /**
         * Output format.
         *
         * @noinspection CanBeFinal
         * @noinspectionreason CanBeFinal - we use picocli, and it uses
         *      reflection to manage such fields
         */
        @Option(names = "-f",
                description = "Specifies the output format. Valid values: "
                + "${COMPLETION-CANDIDATES} for XMLLogger, SarifLogger, "
                + "and DefaultLogger respectively. Defaults to ${DEFAULT-VALUE}.")
        private OutputFormat format = DEFAULT_OUTPUT_FORMAT;

        /** Option that controls whether to print the AST of the file. */
        @Option(names = {"-t", "--tree"},
                description = "This option is used to display the Abstract Syntax Tree (AST) "
                        + "without any comments of the specified file. It can only be used on "
                        + "a single file and cannot be combined with other options.")
        private boolean printAst;

        /** Option that controls whether to print the AST of the file including comments. */
        @Option(names = {"-T", "--treeWithComments"},
                description = "This option is used to display the Abstract Syntax Tree (AST) "
                        + "with comment nodes excluding Javadoc of the specified file. It can only"
                        + " be used on a single file and cannot be combined with other options.")
        private boolean printAstWithComments;

        /** Option that controls whether to print the parse tree of the javadoc comment. */
        @Option(names = {"-j", "--javadocTree"},
                description = "This option is used to print the Parse Tree of the Javadoc comment."
                        + " The file has to contain only Javadoc comment content "
                        + "excluding '/**' and '*/' at the beginning and at the end respectively. "
                        + "It can only be used on a single file and cannot be combined "
                        + "with other options.")
        private boolean printJavadocTree;

        /** Option that controls whether to print the full AST of the file. */
        @Option(names = {"-J", "--treeWithJavadoc"},
                description = "This option is used to display the Abstract Syntax Tree (AST) "
                        + "with Javadoc nodes of the specified file. It can only be used on a "
                        + "single file and cannot be combined with other options.")
        private boolean printTreeWithJavadoc;

        /** Option that controls whether to print debug info. */
        @Option(names = {"-d", "--debug"},
                description = "Prints all debug logging of CheckStyle utility.")
        private boolean debug;

        /**
         * Option that allows users to specify a list of paths to exclude.
         *
         * @noinspection CanBeFinal
         * @noinspectionreason CanBeFinal - we use picocli, and it uses
         *      reflection to manage such fields
         */
        @Option(names = {"-e", "--exclude"},
                description = "Directory/file to exclude from CheckStyle. The path can be the "
                        + "full, absolute path, or relative to the current path. Multiple "
                        + "excludes are allowed.")
        private List<File> exclude = new ArrayList<>();

        /**
         * Option that allows users to specify a regex of paths to exclude.
         *
         * @noinspection CanBeFinal
         * @noinspectionreason CanBeFinal - we use picocli, and it uses
         *      reflection to manage such fields
         */
        @Option(names = {"-x", "--exclude-regexp"},
                description = "Directory/file pattern to exclude from CheckStyle. Multiple "
                        + "excludes are allowed.")
        private List<Pattern> excludeRegex = new ArrayList<>();

        /** Switch whether to execute ignored modules or not. */
        @Option(names = {"-E", "--executeIgnoredModules"},
                description = "Allows ignored modules to be run.")
        private boolean executeIgnoredModules;

        /** Show AST branches that match xpath. */
        @Option(names = {"-b", "--branch-matching-xpath"},
            description = "Shows Abstract Syntax Tree(AST) branches that match given XPath query.")
        private String xpath;

        /**
         * Creates a new {@code CliOptions} instance.
         */
        private CliOptions() {
            // no code by default
        }

        /**
         * Gets the list of exclusions provided through the command line arguments.
         *
         * @return List of exclusion patterns.
         */
        private List<Pattern> getExclusions() {
            final List<Pattern> result = exclude.stream()
                    .map(File::getAbsolutePath)
                    .map(Pattern::quote)
                    .map(pattern -> Pattern.compile("^" + pattern + "$"))
                    .collect(Collectors.toCollection(ArrayList::new));
            result.addAll(excludeRegex);
            return result;
        }

        /**
         * Validates the user-specified command line options.
         *
         * @param parseResult used to verify if the format option was specified on the command line
         * @param filesToProcess the list of files whose style to check
         * @return list of violations
         */
        // -@cs[CyclomaticComplexity] Breaking apart will damage encapsulation
        private List<String> validateCli(ParseResult parseResult, List<File> filesToProcess) {
            final List<String> result = new ArrayList<>();
            final boolean hasConfigurationFile = configurationFile != null;
            final boolean hasSuppressionLineColumnNumber = suppressionLineColumnNumber != null;

            if (filesToProcess.isEmpty()) {
                result.add("Files to process must be specified, found 0.");
            }
            // ensure there is no conflicting options
            else if (printAst || printAstWithComments || printJavadocTree || printTreeWithJavadoc
                || xpath != null) {
                if (suppressionLineColumnNumber != null || configurationFile != null
                        || propertiesFile != null || outputPath != null
                        || parseResult.hasMatchedOption(OUTPUT_FORMAT_OPTION)) {
                    result.add("Option '-t' cannot be used with other options.");
                }
                else if (filesToProcess.size() > 1) {
                    result.add("Printing AST is allowed for only one file.");
                }
            }
            else if (hasSuppressionLineColumnNumber) {
                if (configurationFile != null || propertiesFile != null
                        || outputPath != null
                        || parseResult.hasMatchedOption(OUTPUT_FORMAT_OPTION)) {
                    result.add("Option '-s' cannot be used with other options.");
                }
                else if (filesToProcess.size() > 1) {
                    result.add("Printing xpath suppressions is allowed for only one file.");
                }
            }
            else if (hasConfigurationFile) {
                try {
                    // test location only
                    CommonUtil.getUriByFilename(configurationFile);
                }
                catch (CheckstyleException ignored) {
                    final String msg = "Could not find config XML file '%s'.";
                    result.add(String.format(Locale.ROOT, msg, configurationFile));
                }
                result.addAll(validateOptionalCliParametersIfConfigDefined());
            }
            else {
                result.add("Must specify a config XML file.");
            }

            return result;
        }

        /**
         * Validates optional command line parameters that might be used with config file.
         *
         * @return list of violations
         */
        private List<String> validateOptionalCliParametersIfConfigDefined() {
            final List<String> result = new ArrayList<>();
            if (propertiesFile != null && !propertiesFile.exists()) {
                result.add(String.format(Locale.ROOT,
                        "Could not find file '%s'.", propertiesFile));
            }
            return result;
        }

    }

}