///////////////////////////////////////////////////////////////////////////////////////////////
// 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.ByteArrayOutputStream;
import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
import java.io.OutputStreamWriter;
import java.io.PrintWriter;
import java.io.StringWriter;
import java.net.URI;
import java.net.URISyntaxException;
import java.nio.charset.StandardCharsets;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Locale;
import java.util.Map;
import java.util.MissingResourceException;
import java.util.Objects;
import java.util.ResourceBundle;
import java.util.regex.Matcher;
import java.util.regex.Pattern;

import com.puppycrawl.tools.checkstyle.api.AuditEvent;
import com.puppycrawl.tools.checkstyle.api.AuditListener;
import com.puppycrawl.tools.checkstyle.api.AutomaticBean;
import com.puppycrawl.tools.checkstyle.api.SeverityLevel;
import com.puppycrawl.tools.checkstyle.meta.ModuleDetails;
import com.puppycrawl.tools.checkstyle.meta.XmlMetaReader;
import com.puppycrawl.tools.checkstyle.utils.CommonUtil;

/**
 * Simple SARIF logger.
 * SARIF stands for the static analysis results interchange format.
 * See <a href="https://sarifweb.azurewebsites.net/">reference</a>
 */
public final class SarifLogger extends AbstractAutomaticBean implements AuditListener {

    /** The length of unicode placeholder. */
    private static final int UNICODE_LENGTH = 4;

    /** Unicode escaping upper limit. */
    private static final int UNICODE_ESCAPE_UPPER_LIMIT = 0x1F;

    /** Input stream buffer size. */
    private static final int BUFFER_SIZE = 1024;

    /** The placeholder for message. */
    private static final String MESSAGE_PLACEHOLDER = "${message}";

    /** The placeholder for message text. */
    private static final String MESSAGE_TEXT_PLACEHOLDER = "${messageText}";

    /** The placeholder for message id. */
    private static final String MESSAGE_ID_PLACEHOLDER = "${messageId}";

    /** The placeholder for severity level. */
    private static final String SEVERITY_LEVEL_PLACEHOLDER = "${severityLevel}";

    /** The placeholder for uri. */
    private static final String URI_PLACEHOLDER = "${uri}";

    /** The placeholder for line. */
    private static final String LINE_PLACEHOLDER = "${line}";

    /** The placeholder for column. */
    private static final String COLUMN_PLACEHOLDER = "${column}";

    /** The placeholder for rule id. */
    private static final String RULE_ID_PLACEHOLDER = "${ruleId}";

    /** The placeholder for version. */
    private static final String VERSION_PLACEHOLDER = "${version}";

    /** The placeholder for results. */
    private static final String RESULTS_PLACEHOLDER = "${results}";

    /** The placeholder for rules. */
    private static final String RULES_PLACEHOLDER = "${rules}";

    /** Two backslashes to not duplicate strings. */
    private static final String TWO_BACKSLASHES = "\\\\";

    /** A pattern for two backslashes. */
    private static final Pattern TWO_BACKSLASHES_PATTERN = Pattern.compile(TWO_BACKSLASHES);

    /** A pattern to match a file with a Windows drive letter. */
    private static final Pattern WINDOWS_DRIVE_LETTER_PATTERN =
            Pattern.compile("\\A[A-Z]:", Pattern.CASE_INSENSITIVE);

    /** A pattern matching a template placeholder such as {@code ${uri}}. */
    private static final Pattern PLACEHOLDER_PATTERN = Pattern.compile("\\$\\{\\w+}");

    /** Comma and line separator. */
    private static final String COMMA_LINE_SEPARATOR = ",\n";

    /** Helper writer that allows easy encoding and printing. */
    private final PrintWriter writer;

    /** Close output stream in auditFinished. */
    private final boolean closeStream;

    /** The results. */
    private final List<String> results = new ArrayList<>();

    /** Map of all available module metadata by fully qualified name. */
    private final Map<String, ModuleDetails> allModuleMetadata = new HashMap<>();

    /** Map to store rule metadata by composite key (sourceName, moduleId). */
    private final Map<RuleKey, ModuleDetails> ruleMetadata = new LinkedHashMap<>();

    /** Content for the entire report. */
    private final String report;

    /** Content for result representing an error with source line and column. */
    private final String resultLineColumn;

    /** Content for result representing an error with source line only. */
    private final String resultLineOnly;

    /** Content for result representing an error with filename only and without source location. */
    private final String resultFileOnly;

    /** Content for result representing an error without filename or location. */
    private final String resultErrorOnly;

    /** Content for rule. */
    private final String rule;

    /** Content for messageStrings. */
    private final String messageStrings;

    /** Content for message with text only. */
    private final String messageTextOnly;

    /** Content for message with id. */
    private final String messageWithId;

    /**
     * Creates a new {@code SarifLogger} instance.
     *
     * @param outputStream where to log audit events
     * @param outputStreamOptions if {@code CLOSE} that should be closed in auditFinished()
     * @throws IOException if there is reading errors.
     * @throws IllegalArgumentException if outputStreamOptions is null
     * @noinspection deprecation
     * @noinspectionreason We are forced to keep AutomaticBean compatibility
     *     because of maven-checkstyle-plugin. Until #12873.
     */
    public SarifLogger(
        OutputStream outputStream,
        AutomaticBean.OutputStreamOptions outputStreamOptions)
                throws IOException {
        this(outputStream, OutputStreamOptions.valueOf(outputStreamOptions.name()));
    }

    /**
     * Creates a new {@code SarifLogger} instance.
     *
     * @param outputStream where to log audit events
     * @param outputStreamOptions if {@code CLOSE} that should be closed in auditFinished()
     * @throws IOException if there is reading errors.
     * @throws IllegalArgumentException if outputStreamOptions is null
     */
    public SarifLogger(
        OutputStream outputStream,
        OutputStreamOptions outputStreamOptions)
                throws IOException {
        if (outputStreamOptions == null) {
            throw new IllegalArgumentException("Parameter outputStreamOptions can not be null");
        }
        writer = new PrintWriter(new OutputStreamWriter(outputStream, StandardCharsets.UTF_8));
        closeStream = outputStreamOptions == OutputStreamOptions.CLOSE;
        loadModuleMetadata();
        report = readResource("/com/puppycrawl/tools/checkstyle/sarif/SarifReport.template");
        resultLineColumn =
            readResource("/com/puppycrawl/tools/checkstyle/sarif/ResultLineColumn.template");
        resultLineOnly =
            readResource("/com/puppycrawl/tools/checkstyle/sarif/ResultLineOnly.template");
        resultFileOnly =
            readResource("/com/puppycrawl/tools/checkstyle/sarif/ResultFileOnly.template");
        resultErrorOnly =
            readResource("/com/puppycrawl/tools/checkstyle/sarif/ResultErrorOnly.template");
        rule = readResource("/com/puppycrawl/tools/checkstyle/sarif/Rule.template");
        messageStrings =
            readResource("/com/puppycrawl/tools/checkstyle/sarif/MessageStrings.template");
        messageTextOnly =
            readResource("/com/puppycrawl/tools/checkstyle/sarif/MessageTextOnly.template");
        messageWithId =
            readResource("/com/puppycrawl/tools/checkstyle/sarif/MessageWithId.template");
    }

    /**
     * Loads all available module metadata from XML files.
     */
    private void loadModuleMetadata() {
        final List<ModuleDetails> allModules =
                XmlMetaReader.readAllModulesIncludingThirdPartyIfAny();
        for (ModuleDetails module : allModules) {
            allModuleMetadata.put(module.getFullQualifiedName(), module);
        }
    }

    @Override
    protected void finishLocalSetup() {
        // No code by default
    }

    @Override
    public void auditStarted(AuditEvent event) {
        // No code by default
    }

    @Override
    public void auditFinished(AuditEvent event) {
        String rendered = replaceVersionString(report);
        rendered = rendered
                .replace(RESULTS_PLACEHOLDER, String.join(COMMA_LINE_SEPARATOR, results))
                .replace(RULES_PLACEHOLDER, String.join(COMMA_LINE_SEPARATOR, generateRules()));
        writer.print(rendered);
        if (closeStream) {
            writer.close();
        }
        else {
            writer.flush();
        }
    }

    /**
     * Generates rules from cached rule metadata.
     *
     * @return list of rules
     */
    private List<String> generateRules() {
        final List<String> result = new ArrayList<>();
        for (Map.Entry<RuleKey, ModuleDetails> entry : ruleMetadata.entrySet()) {
            final RuleKey ruleKey = entry.getKey();
            final ModuleDetails module = entry.getValue();
            final String shortDescription;
            final String fullDescription;
            final String messageStringsFragment;
            if (module == null) {
                shortDescription = CommonUtil.baseClassName(ruleKey.sourceName());
                fullDescription = "No description available";
                messageStringsFragment = "";
            }
            else {
                shortDescription = module.getName();
                fullDescription = module.getDescription();
                messageStringsFragment = String.join(COMMA_LINE_SEPARATOR,
                        generateMessageStrings(module));
            }
            result.add(rule
                    .replace(RULE_ID_PLACEHOLDER, ruleKey.toRuleId())
                    .replace("${shortDescription}", shortDescription)
                    .replace("${fullDescription}", escape(fullDescription))
                    .replace("${messageStrings}", messageStringsFragment));
        }
        return result;
    }

    /**
     * Generates message strings for a given module.
     *
     * @param module the module
     * @return the generated message strings
     */
    private List<String> generateMessageStrings(ModuleDetails module) {
        final Map<String, String> messages = getMessages(module);
        return module.getViolationMessageKeys().stream()
                .filter(messages::containsKey)
                .map(key -> {
                    final String message = messages.get(key);
                    return messageStrings
                            .replace("${key}", key)
                            .replace("${text}", escape(message));
                })
                .toList();
    }

    /**
     * Gets a map of message keys to their message strings for a module.
     *
     * @param moduleDetails the module details
     * @return map of message keys to message strings
     */
    private static Map<String, String> getMessages(ModuleDetails moduleDetails) {
        final String fullQualifiedName = moduleDetails.getFullQualifiedName();
        final Map<String, String> result = new LinkedHashMap<>();
        try {
            final int lastDot = fullQualifiedName.lastIndexOf('.');
            final String packageName = fullQualifiedName.substring(0, lastDot);
            final String bundleName = packageName + ".messages";
            final Class<?> moduleClass = Class.forName(fullQualifiedName);
            final ResourceBundle bundle = ResourceBundle.getBundle(
                    bundleName,
                    Locale.ROOT,
                    moduleClass.getClassLoader()
            );
            for (String key : moduleDetails.getViolationMessageKeys()) {
                result.put(key, bundle.getString(key));
            }
        }
        catch (ClassNotFoundException | MissingResourceException ignored) {
            // Return empty map when module class or resource bundle is not on classpath.
            // Occurs with third-party modules that have XML metadata but missing implementation.
        }
        return result;
    }

    /**
     * Returns the version string.
     *
     * @param report report content where replace should happen
     * @return a version string based on the package implementation version
     */
    private static String replaceVersionString(String report) {
        final String version = SarifLogger.class.getPackage().getImplementationVersion();
        return report.replace(VERSION_PLACEHOLDER, Objects.toString(version, "null"));
    }

    @Override
    public void addError(AuditEvent event) {
        final RuleKey ruleKey = cacheRuleMetadata(event);
        final String message = generateMessage(ruleKey, event);
        if (event.getColumn() > 0) {
            results.add(fillTemplate(resultLineColumn, Map.of(
                SEVERITY_LEVEL_PLACEHOLDER, renderSeverityLevel(event.getSeverityLevel()),
                URI_PLACEHOLDER, renderFileNameUri(event.getFileName()),
                COLUMN_PLACEHOLDER, Integer.toString(event.getColumn()),
                LINE_PLACEHOLDER, Integer.toString(event.getLine()),
                MESSAGE_PLACEHOLDER, message,
                RULE_ID_PLACEHOLDER, ruleKey.toRuleId())));
        }
        else {
            results.add(fillTemplate(resultLineOnly, Map.of(
                SEVERITY_LEVEL_PLACEHOLDER, renderSeverityLevel(event.getSeverityLevel()),
                URI_PLACEHOLDER, renderFileNameUri(event.getFileName()),
                LINE_PLACEHOLDER, Integer.toString(event.getLine()),
                MESSAGE_PLACEHOLDER, message,
                RULE_ID_PLACEHOLDER, ruleKey.toRuleId())));
        }
    }

    /**
     * Caches rule metadata for a given audit event.
     *
     * @param event the audit event
     * @return the composite key for the rule
     */
    private RuleKey cacheRuleMetadata(AuditEvent event) {
        final String sourceName = event.getSourceName();
        final RuleKey key = new RuleKey(sourceName, event.getModuleId());
        final ModuleDetails module = allModuleMetadata.get(sourceName);
        ruleMetadata.putIfAbsent(key, module);
        return key;
    }

    /**
     * Generate message for the given rule key and audit event.
     *
     * @param ruleKey the rule key
     * @param event the audit event
     * @return the generated message
     */
    private String generateMessage(RuleKey ruleKey, AuditEvent event) {
        final String violationKey = event.getViolation().getKey();
        final ModuleDetails module = ruleMetadata.get(ruleKey);
        final String result;
        if (module != null && module.getViolationMessageKeys().contains(violationKey)) {
            result = messageWithId
                    .replace(MESSAGE_ID_PLACEHOLDER, violationKey)
                    .replace(MESSAGE_TEXT_PLACEHOLDER, escape(event.getMessage()));
        }
        else {
            result = messageTextOnly
                    .replace(MESSAGE_TEXT_PLACEHOLDER, escape(event.getMessage()));
        }
        return result;
    }

    @Override
    public void addException(AuditEvent event, Throwable throwable) {
        final StringWriter stringWriter = new StringWriter();
        final PrintWriter printer = new PrintWriter(stringWriter);
        throwable.printStackTrace(printer);
        final String message = messageTextOnly
                .replace(MESSAGE_TEXT_PLACEHOLDER, escape(stringWriter.toString()));
        if (event.getFileName() == null) {
            results.add(fillTemplate(resultErrorOnly, Map.of(
                SEVERITY_LEVEL_PLACEHOLDER, renderSeverityLevel(event.getSeverityLevel()),
                MESSAGE_PLACEHOLDER, message)));
        }
        else {
            results.add(fillTemplate(resultFileOnly, Map.of(
                SEVERITY_LEVEL_PLACEHOLDER, renderSeverityLevel(event.getSeverityLevel()),
                URI_PLACEHOLDER, renderFileNameUri(event.getFileName()),
                MESSAGE_PLACEHOLDER, message)));
        }
    }

    @Override
    public void fileStarted(AuditEvent event) {
        // No need to implement this method in this class
    }

    @Override
    public void fileFinished(AuditEvent event) {
        // No need to implement this method in this class
    }

    /**
     * Fill a template with its values in a single pass, so a value substituted for one
     * placeholder is never scanned again and taken for another. A file name or message that
     * happens to carry placeholder text is therefore kept verbatim instead of pulling
     * another value into it.
     *
     * @param template the template to fill
     * @param values the value to substitute for each placeholder
     * @return the filled template
     */
    private static String fillTemplate(String template, Map<String, String> values) {
        final Matcher matcher = PLACEHOLDER_PATTERN.matcher(template);
        final StringBuilder result = new StringBuilder(256);
        while (matcher.find()) {
            final String placeholder = matcher.group();
            final String value = values.getOrDefault(placeholder, placeholder);
            matcher.appendReplacement(result, Matcher.quoteReplacement(value));
        }
        matcher.appendTail(result);
        return result.toString();
    }

    /**
     * Render the file name URI for the given file name.
     *
     * @param fileName the file name to render the URI for
     * @return the rendered URI for the given file name
     * @throws IllegalArgumentException if the file name cannot be converted to a URI
     */
    private static String renderFileNameUri(final String fileName) {
        String normalized = TWO_BACKSLASHES_PATTERN.matcher(fileName).replaceAll("/");
        if (WINDOWS_DRIVE_LETTER_PATTERN.matcher(normalized).find()) {
            normalized = '/' + normalized;
        }
        try {
            return "file:" + new URI(null, null, normalized, null).toASCIIString();
        }
        catch (URISyntaxException exc) {
            throw new IllegalArgumentException("Invalid file name: " + fileName, exc);
        }
    }

    /**
     * Render the severity level into SARIF severity level.
     *
     * @param severityLevel the Severity level.
     * @return the rendered severity level in string.
     */
    private static String renderSeverityLevel(SeverityLevel severityLevel) {
        return switch (severityLevel) {
            case IGNORE -> "none";
            case INFO -> "note";
            case WARNING -> "warning";
            case ERROR -> "error";
        };
    }

    /**
     * Escape \b, \f, \n, \r, \t, \", \\ and U+0000 through U+001F.
     * See <a href="https://www.ietf.org/rfc/rfc4627.txt">reference</a> - 2.5. Strings
     *
     * @param value the value to escape.
     * @return the escaped value if necessary.
     */
    public static String escape(String value) {
        final int length = value.length();
        final StringBuilder sb = new StringBuilder(length);
        for (int index = 0; index < length; index++) {
            final char chr = value.charAt(index);
            final String replacement = switch (chr) {
                case '"' -> "\\\"";
                case '\\' -> TWO_BACKSLASHES;
                case '\b' -> "\\b";
                case '\f' -> "\\f";
                case '\n' -> "\\n";
                case '\r' -> "\\r";
                case '\t' -> "\\t";
                case '/' -> "\\/";
                default -> {
                    if (chr <= UNICODE_ESCAPE_UPPER_LIMIT) {
                        yield escapeUnicode1F(chr);
                    }
                    yield Character.toString(chr);
                }
            };
            sb.append(replacement);
        }

        return sb.toString();
    }

    /**
     * Escape the character between 0x00 to 0x1F in JSON.
     *
     * @param chr the character to be escaped.
     * @return the escaped string.
     */
    private static String escapeUnicode1F(char chr) {
        final String hexString = Integer.toHexString(chr);
        return "\\u"
                + "0".repeat(UNICODE_LENGTH - hexString.length())
                + hexString.toUpperCase(Locale.US);
    }

    /**
     * Read string from given resource.
     *
     * @param name name of the desired resource
     * @return the string content from the give resource
     * @throws IOException if there is reading errors
     */
    public static String readResource(String name) throws IOException {
        try (InputStream inputStream = SarifLogger.class.getResourceAsStream(name);
             ByteArrayOutputStream result = new ByteArrayOutputStream()) {
            if (inputStream == null) {
                throw new IOException("Cannot find the resource " + name);
            }
            final byte[] buffer = new byte[BUFFER_SIZE];
            int length = 0;
            while (length != -1) {
                result.write(buffer, 0, length);
                length = inputStream.read(buffer);
            }
            return result.toString(StandardCharsets.UTF_8);
        }
    }

    /**
     * Composite key for uniquely identifying a rule by source name and module ID.
     *
     * @param sourceName  The fully qualified source class name.
     * @param moduleId  The module ID from configuration (can be null).
     */
    private record RuleKey(String sourceName, String moduleId) {
        /**
         * Converts this key to a SARIF rule ID string.
         *
         * @return rule ID in format: sourceName[#moduleId]
         */
        private String toRuleId() {
            final String result;
            if (moduleId == null) {
                result = sourceName;
            }
            else {
                result = sourceName + '#' + moduleId;
            }
            return result;
        }
    }

}