/*
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 */
package org.eclipse.aether.tools;

import javax.lang.model.SourceVersion;
import javax.lang.model.element.AnnotationMirror;
import javax.lang.model.element.AnnotationValue;
import javax.lang.model.element.Element;
import javax.lang.model.element.ElementKind;
import javax.lang.model.element.ExecutableElement;
import javax.lang.model.element.Modifier;
import javax.lang.model.element.ModuleElement;
import javax.lang.model.element.PackageElement;
import javax.lang.model.element.TypeElement;
import javax.lang.model.element.VariableElement;
import javax.lang.model.type.DeclaredType;
import javax.lang.model.type.PrimitiveType;
import javax.lang.model.type.TypeMirror;
import javax.lang.model.util.ElementFilter;
import javax.lang.model.util.Elements;
import javax.lang.model.util.SimpleElementVisitor14;
import javax.lang.model.util.SimpleTypeVisitor14;
import javax.lang.model.util.Types;
import javax.tools.Diagnostic;

import java.io.IOException;
import java.io.PrintWriter;
import java.io.Writer;
import java.net.URI;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.InvalidPathException;
import java.nio.file.Path;
import java.nio.file.Paths;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Collection;
import java.util.Collections;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Locale;
import java.util.Map;
import java.util.Objects;
import java.util.Optional;
import java.util.Properties;
import java.util.Set;

import com.sun.source.doctree.DeprecatedTree;
import com.sun.source.doctree.DocCommentTree;
import com.sun.source.doctree.DocTree;
import com.sun.source.doctree.EntityTree;
import com.sun.source.doctree.LinkTree;
import com.sun.source.doctree.LiteralTree;
import com.sun.source.doctree.ReferenceTree;
import com.sun.source.doctree.SeeTree;
import com.sun.source.doctree.SinceTree;
import com.sun.source.doctree.SystemPropertyTree;
import com.sun.source.doctree.TextTree;
import com.sun.source.doctree.UnknownBlockTagTree;
import com.sun.source.doctree.ValueTree;
import com.sun.source.tree.ExpressionTree;
import com.sun.source.tree.IdentifierTree;
import com.sun.source.tree.MemberSelectTree;
import com.sun.source.tree.VariableTree;
import com.sun.source.util.DocTreePath;
import com.sun.source.util.DocTrees;
import com.sun.source.util.SimpleDocTreeVisitor;
import jdk.javadoc.doclet.Doclet;
import jdk.javadoc.doclet.DocletEnvironment;
import jdk.javadoc.doclet.Reporter;
import org.apache.maven.tools.plugin.javadoc.FullyQualifiedJavadocReference;
import org.apache.maven.tools.plugin.javadoc.FullyQualifiedJavadocReference.MemberType;
import org.apache.maven.tools.plugin.javadoc.JavadocLinkGenerator;

/**
 * A custom Javadoc {@link Doclet} that scans constant fields for configuration metadata declared via custom Javadoc
 * block tags (e.g. {@code @configurationSource}) and writes the discovered keys into an intermediate
 * {@link Properties} file. That file is subsequently consumed by {@link CollectConfiguration} to render the
 * documentation via Velocity templates.
 * <p>
 * The intermediate file uses an indexed layout:
 * <pre>
 * keys.count=N
 * keys.0.key=...
 * keys.0.description=...
 * ...
 * </pre>
 */
public class ConfigurationCollectorDoclet implements Doclet {

    /**
     * Fully qualified name of the Maven annotation that marks a configuration key when scanning Maven sources.
     */
    private static final String MAVEN_CONFIG_ANNOTATION = "org.apache.maven.api.annotations.Config";

    private static final MethodReference METHOD_REFERENCE_SESSION_CONFIGURATION =
            new MethodReference("org.eclipse.aether.RepositorySystemSession", "getConfigProperties", List.of());
    private static final MethodReference METHOD_REFERENCE_SYSTEM_PROPERTY =
            new MethodReference("java.lang.System", "getProperty", List.of("java.lang.String", "java.lang.String"));

    private Reporter reporter;

    private Path output;

    private URI internalJavadocUrl = URI.create("apidocs/");

    private String internalJavadocVersion = "21";

    private final List<URI> externalJavadocUrls = new ArrayList<>();

    private final List<Path> internalJavadocSourceRoots = new ArrayList<>();

    private enum Mode {
        RESOLVER,
        MAVEN
    }

    private record ConfigurationEntry(
            String key,
            String description,
            String defaultValue,
            String fqName,
            String since,
            String source,
            String type,
            String typeJavadocUrl,
            boolean supportsRepoIdSuffix,
            // is empty if not deprecated
            String deprecated,
            // see also section
            Collection<String> see) {

        public ConfigurationEntry {
            Objects.requireNonNull(key);
            Objects.requireNonNull(description);
        }
    }

    private record ConfigurationType(String name, String javadocUrl) {}

    /**
     * The scanning mode; either {@code resolver} (Javadoc block tags) or {@code maven} (the {@code @Config}
     * annotation). Defaults to {@code resolver}.
     */
    private Mode mode = Mode.RESOLVER;

    private DocTrees docTrees;

    private Elements elements;

    private Types types;

    private JavadocLinkGenerator javadocLinkGenerator;

    @Override
    public void init(Locale locale, Reporter reporter) {
        this.reporter = reporter;
    }

    @Override
    public String getName() {
        return "ConfigurationCollector";
    }

    @Override
    public Set<? extends Option> getSupportedOptions() {
        return Set.of(
                new SingleArgumentOption(
                        List.of("--output", "-o"),
                        "The intermediate properties file to write discovered keys to",
                        "<file>",
                        arg -> {
                            try {
                                output = Paths.get(arg);
                            } catch (InvalidPathException e) {
                                throw new IllegalArgumentException("Invalid output file path: " + arg, e);
                            }
                        }),
                new SingleArgumentOption(
                        List.of("--mode", "-m"), "The scanning mode, either 'resolver' or 'maven'", "<mode>", arg -> {
                            try {
                                mode = Mode.valueOf(arg.toUpperCase(Locale.ROOT));
                            } catch (IllegalArgumentException e) {
                                throw new IllegalArgumentException(
                                        "Invalid mode: " + arg + ". Must be one of (case-insensitive): "
                                                + String.join(
                                                        ", ",
                                                        Arrays.stream(Mode.values())
                                                                .map(Enum::name)
                                                                .toArray(String[]::new)));
                            }
                        }),
                new SingleArgumentOption(
                        List.of("--internal-javadoc-url"),
                        "The base URL for Javadoc generated by this project",
                        "<url>",
                        arg -> internalJavadocUrl = parseJavadocUrl(arg)),
                new SingleArgumentOption(
                        List.of("--internal-javadoc-version"),
                        "The Javadoc tool version used to generate the internal site",
                        "<version>",
                        arg -> internalJavadocVersion = arg),
                new SingleArgumentOption(
                        List.of("--internal-javadoc-source-root"),
                        "A source root whose public API is included in the internal Javadoc site",
                        "<directory>",
                        arg -> internalJavadocSourceRoots.add(
                                Paths.get(arg).toAbsolutePath().normalize())),
                new SingleArgumentOption(
                        List.of("--external-javadoc-url"),
                        "An external Javadoc base URL used for validated links",
                        "<url>",
                        arg -> externalJavadocUrls.add(parseJavadocUrl(arg))));
    }

    @Override
    public SourceVersion getSupportedSourceVersion() {
        return SourceVersion.latest();
    }

    @Override
    public boolean run(DocletEnvironment environment) {
        try {
            return doRun(environment);
        } catch (RuntimeException e) {
            // catch all runtime exception, as the default javadoc tool emits a confusing message about reporting
            // something with Oracle
            reportError("Error running ConfigurationCollectorDoclet", e);
            return false;
        }
    }

    private boolean doRun(DocletEnvironment environment) {
        if (output == null) {
            reportError("Missing required --output option");
            return false;
        }
        docTrees = environment.getDocTrees();
        elements = environment.getElementUtils();
        types = environment.getTypeUtils();
        javadocLinkGenerator =
                new JavadocLinkGenerator(internalJavadocUrl, internalJavadocVersion, externalJavadocUrls, null);
        List<ConfigurationEntry> configurationEntries = new ArrayList<>();

        Set<TypeElement> includedTypes = ElementFilter.typesIn(environment.getIncludedElements());
        for (TypeElement type : includedTypes) {
            for (VariableElement field : ElementFilter.fieldsIn(type.getEnclosedElements())) {
                // check if relevant metadata is present before processing the field, so that we can skip any fields
                // that don't have a constant value or Javadoc
                if (field.getConstantValue() == null) {
                    continue;
                }
                DocCommentTree docComment = docTrees.getDocCommentTree(field);
                if (docComment == null) {
                    // javadoc is mandatory for configuration keys, so skip any fields that don't have a doc comment
                    continue;
                }
                DocTreePath rootPath = new DocTreePath(docTrees.getPath(field), docComment);
                try {
                    ConfigurationEntry entry;
                    switch (mode) {
                        case MAVEN:
                            entry = processMavenField(rootPath, field);
                            break;
                        case RESOLVER:
                            entry = processResolverField(rootPath, field);
                            break;
                        default:
                            throw new IllegalStateException("Unknown mode: " + mode);
                    }
                    if (entry != null) {
                        configurationEntries.add(entry);
                    }
                } catch (DocTreePathAwareRuntimeException e) {
                    reportError(e.getDocTreePath(), e.getMessage());
                } catch (IllegalArgumentException e) {
                    reportError(rootPath, e.getMessage());
                } catch (RuntimeException e) {
                    // log with stacktrace for unexpected errors, but continue
                    reportError(rootPath, e);
                }
            }
        }

        try {
            writeProperties(configurationEntries);
        } catch (IOException e) {
            reportError("Failed to write properties file: " + e.getMessage());
            return false;
        }
        return true;
    }

    /**
     * Reports an error message at a specific DocTreePath location.
     *
     * @param path the DocTreePath where the error occurred
     * @param message the error message
     */
    private void reportError(DocTreePath path, Throwable throwable) {
        reportError(path, throwable.getMessage());
        reportError(throwable);
    }

    private void reportError(Throwable throwable) {
        // also emit stack trace
        PrintWriter pw = reporter.getDiagnosticWriter();
        if (pw == null) {
            pw = new PrintWriter(System.err);
        }
        throwable.printStackTrace(pw);
    }

    /**
     * Reports an error message at a specific DocTreePath location.
     *
     * @param path the DocTreePath where the error occurred
     * @param message the error message
     */
    private void reportError(DocTreePath path, String message) {
        if (path != null) {
            reporter.print(Diagnostic.Kind.ERROR, path, message);
        } else {
            reportError(message);
        }
    }

    /**
     * Reports a global error message without location information.
     *
     * @param message the error message
     * @param throwable the exception whose stack trace is printed
     */
    private void reportError(String message, Throwable throwable) {
        reporter.print(Diagnostic.Kind.ERROR, message);
        reportError(throwable);
    }

    /**
     * Reports a global error message without location information.
     *
     * @param message the error message
     */
    private void reportError(String message) {
        reporter.print(Diagnostic.Kind.ERROR, message);
    }

    /**
     * Processes a configuration key field declared in Javadoc sources.
     * @param path
     * @param field
     * @return the extracted configuration entry (or {@code null})
     */
    private ConfigurationEntry processResolverField(DocTreePath path, VariableElement field) {
        Objects.requireNonNull(path);
        Objects.requireNonNull(field);
        Map<String, UnknownBlockTagTree> blockTags = collectBlockTags(path.getDocComment());
        if (!blockTags.containsKey("configurationSource")) {
            return null;
        }
        ConfigurationType configurationType = getConfigurationType(path, blockTags);
        return new ConfigurationEntry(
                String.valueOf(field.getConstantValue()),
                getFullBodyContent(path),
                resolveDefaultValue(path, blockTags).orElse(""),
                getFullyQualifiedName(field),
                getSince(path).orElse(""),
                getConfigurationSource(path, blockTags).orElse(""),
                configurationType.name(),
                configurationType.javadocUrl(),
                isSupportsRepoIdSuffix(path, blockTags),
                getDeprecated(path, field).orElse(""),
                getSee(path));
    }

    private Optional<String> getDeprecated(DocTreePath path, Element element) {
        Objects.requireNonNull(path, "path must not be null");
        Objects.requireNonNull(element, "field must not be null");

        // first check for deprecated annotation
        if (element.getAnnotation(Deprecated.class) == null) {
            // if not existing check enclosing elements recursively
            return getDeprecated(element.getEnclosingElement());
        }
        Optional<? extends DocTree> deprecatedTag = path.getDocComment().getBlockTags().stream()
                .filter(t -> com.sun.source.doctree.DocTree.Kind.DEPRECATED == t.getKind())
                .findFirst();
        if (deprecatedTag.isPresent()) {
            return Optional.of(renderContent(DocTreePath.getPath(path, deprecatedTag.get()), RenderMode.HTML, true));
        }
        return Optional.of("");
    }

    private Optional<String> getDeprecated(Element element) {
        if (element == null) {
            return Optional.empty();
        }
        DocCommentTree docCommentTree = docTrees.getDocCommentTree(element);
        if (docCommentTree == null) {
            if (element.getAnnotation(Deprecated.class) != null) {
                return Optional.of("");
            }
            // traverse to enclosing element
            return getDeprecated(element.getEnclosingElement());
        } else {
            return getDeprecated(new DocTreePath(docTrees.getPath(element), docCommentTree), element);
        }
    }

    private Collection<String> getSee(DocTreePath path) {
        Objects.requireNonNull(path, "path must not be null");

        return path.getDocComment().getBlockTags().stream()
                .filter(t -> com.sun.source.doctree.DocTree.Kind.SEE == t.getKind())
                .map(seeTag -> renderContent(DocTreePath.getPath(path, seeTag), RenderMode.HTML, true))
                .toList();
    }

    private boolean isSupportsRepoIdSuffix(DocTreePath path, Map<String, UnknownBlockTagTree> blockTags) {
        UnknownBlockTagTree repoIdTag = blockTags.get("configurationRepoIdSuffix");
        if (repoIdTag != null) {
            String content = renderContent(DocTreePath.getPath(path, repoIdTag), RenderMode.PLAIN, true);
            return "yes".equalsIgnoreCase(content) || "true".equalsIgnoreCase(content);
        }
        return false;
    }

    /**
     * Processes a constant field declared in Maven sources. Maven declares configuration keys via the
     * {@code org.apache.maven.api.annotations.Config} annotation (rather than the custom Javadoc block tags used by
     * Resolver), so the metadata is read from that annotation's attributes.
     * @return the extracted configuration entry (or {@code null} if the field is not annotated with {@code @Config})
     */
    // TODO: move to Maven repository module and use the Maven annotation type directly (currently we don't have a
    // dependency on Maven API)
    private ConfigurationEntry processMavenField(DocTreePath path, VariableElement field) {
        AnnotationMirror config = getAnnotation(field, MAVEN_CONFIG_ANNOTATION);
        if (config == null) {
            return null;
        }

        String source = "USER_PROPERTIES";
        String defaultValue = "";
        String configurationType = "java.lang.String";
        for (Map.Entry<? extends ExecutableElement, ? extends AnnotationValue> attribute :
                config.getElementValues().entrySet()) {
            String name = attribute.getKey().getSimpleName().toString();
            Object value = attribute.getValue().getValue();
            switch (name) {
                case "source":
                    source = value instanceof VariableElement variableElement
                            ? variableElement.getSimpleName().toString()
                            : String.valueOf(value);
                    break;
                case "defaultValue":
                    defaultValue = String.valueOf(value);
                    break;
                case "type":
                    configurationType = String.valueOf(value);
                    break;
                default:
                    break;
            }
        }

        source = source.toLowerCase(Locale.ROOT);
        switch (source) {
            case "model":
                source = "Model properties";
                break;
            case "user_properties":
                source = "User properties";
                break;
            case "system_properties":
                source = "System properties";
                break;
            default:
                break;
        }

        if (configurationType.startsWith("java.lang.")) {
            configurationType = configurationType.substring("java.lang.".length());
        } else if (configurationType.startsWith("java.util.")) {
            configurationType = configurationType.substring("java.util.".length());
        }
        return new ConfigurationEntry(
                String.valueOf(field.getConstantValue()),
                path.getDocComment() != null ? getFullBodyContent(path) : "",
                Objects.toString(defaultValue, ""),
                getFullyQualifiedName(field),
                getSince(path).orElse(""),
                source,
                configurationType,
                "",
                false,
                getDeprecated(path, field).orElse(""),
                getSee(path));
    }

    private AnnotationMirror getAnnotation(Element element, String fqName) {
        for (AnnotationMirror annotation : element.getAnnotationMirrors()) {
            Element annotationElement = annotation.getAnnotationType().asElement();
            if (annotationElement instanceof TypeElement
                    && ((TypeElement) annotationElement).getQualifiedName().contentEquals(fqName)) {
                return annotation;
            }
        }
        return null;
    }

    private void writeProperties(List<ConfigurationEntry> configurationEntries) throws IOException {
        Properties properties = new Properties();
        properties.setProperty("keys.count", String.valueOf(configurationEntries.size()));
        for (int i = 0; i < configurationEntries.size(); i++) {
            ConfigurationEntry entry = configurationEntries.get(i);
            writeEntry(properties, entry, "keys." + i + ".");
        }
        if (output.getParent() != null) {
            Files.createDirectories(output.getParent());
        }
        try (Writer writer = Files.newBufferedWriter(output, StandardCharsets.UTF_8)) {
            properties.store(writer, "Generated by ConfigurationCollectorDoclet - DO NOT EDIT");
        }
    }

    private void writeEntry(Properties properties, ConfigurationEntry entry, String prefix) {
        properties.setProperty(prefix + "key", entry.key());
        properties.setProperty(prefix + "defaultValue", entry.defaultValue());
        properties.setProperty(prefix + "fqName", entry.fqName());
        properties.setProperty(prefix + "description", entry.description());
        properties.setProperty(prefix + "since", entry.since());
        properties.setProperty(prefix + "configurationSource", entry.source());
        properties.setProperty(prefix + "configurationType", entry.type());
        properties.setProperty(prefix + "configurationTypeJavadocUrl", entry.typeJavadocUrl());
        properties.setProperty(prefix + "supportRepoIdSuffix", toYesNo(entry.supportsRepoIdSuffix()));
        properties.setProperty(prefix + "deprecated", entry.deprecated());
        properties.setProperty(prefix + "see", String.join(", ", entry.see()));
    }

    // --- Javadoc extraction helpers -------------------------------------------------------------------------------

    private Map<String, UnknownBlockTagTree> collectBlockTags(DocCommentTree docComment) {
        Map<String, UnknownBlockTagTree> result = new LinkedHashMap<>();
        if (docComment == null) {
            return result;
        }
        for (DocTree tag : docComment.getBlockTags()) {
            if (tag instanceof UnknownBlockTagTree unknownBlockTree) {
                result.put(unknownBlockTree.getTagName(), unknownBlockTree);
            }
        }
        return result;
    }

    private String getFullBodyContent(DocTreePath path) {
        return renderContent(path, RenderMode.HTML, true, path.getDocComment().getFullBody());
    }

    private Optional<String> resolveDefaultValue(DocTreePath path, Map<String, UnknownBlockTagTree> blockTags) {
        UnknownBlockTagTree defaultValueTag = blockTags.get("configurationDefaultValue");
        if (defaultValueTag == null) {
            return Optional.empty();
        }
        DocTreePath defaultValuePath = DocTreePath.getPath(path, defaultValueTag);
        for (DocTree tree : defaultValueTag.getContent()) {
            if (tree instanceof LinkTree link) {
                String signature = link.getReference().getSignature();
                DocTreePath linkTreePath = DocTreePath.getPath(path, tree);
                // resolve the referenced constant using the fully qualified signature, so that references
                // to constants declared in other types (e.g. {@link OtherType#CONSTANT}) can be resolved
                VariableElement referenced = resolveReferencedField(linkTreePath, link.getReference());
                String value = referenced != null ? lookupConstant(referenced) : null;
                if (value == null) {
                    // hard fail: default value constants must be resolvable; report at the precise
                    // link-reference location if we can resolve a path to it, otherwise at the block tag
                    DocTreePath linkRefPath = DocTreePath.getPath(linkTreePath, link.getReference());
                    throw new DocTreePathAwareRuntimeException(
                            linkRefPath != null ? linkRefPath : linkTreePath,
                            "Could not resolve link to determine default value: " + signature);
                }
                return Optional.ofNullable(value);
            }
        }
        // fallback: render the content of the block tag as-is (e.g. if it contains a literal value rather than a {@code
        // {@link ...}} reference)
        return Optional.of(renderContent(defaultValuePath, RenderMode.PLAIN, true));
    }

    /**
     * Resolves the {@link VariableElement} a {@code {@link ...}} reference points to using the fully qualified
     * signature (so references into other types are supported). Returns {@code null} if the reference cannot be
     * resolved to a field.
     */
    private VariableElement resolveReferencedField(DocTreePath path, ReferenceTree reference) {
        DocTreePath refPath = DocTreePath.getPath(path, reference);
        if (refPath == null) {
            return null;
        }
        Element element = docTrees.getElement(refPath);
        return element instanceof VariableElement variableElement ? variableElement : null;
    }

    private String lookupConstant(VariableElement field) {
        if (field.getConstantValue() != null) {
            Object value = field.getConstantValue();
            if (value instanceof String) {
                return "\"" + value + "\"";
            } else {
                return String.valueOf(field.getConstantValue());
            }
        }
        // enum constants don't expose a constant value, fall back to the enum value's name
        if (field.getKind() == ElementKind.ENUM_CONSTANT) {
            return field.getSimpleName().toString();
        }
        // the field may indirectly reference an enum variable, e.g. "SomeEnum.VALUE";
        // resolve it from the field's initializer
        return resolveEnumReference(field);
    }

    /**
     * Resolves an enum constant that a field is initialized with, including the enum type in the result
     * (e.g. a field declared as {@code SomeEnum FOO = SomeEnum.VALUE} resolves to {@code SomeEnum.VALUE}).
     * Returns {@code null} if the field's initializer is not a simple enum reference.
     */
    private String resolveEnumReference(VariableElement field) {
        if (!(docTrees.getTree(field) instanceof VariableTree variableTree)) {
            return null;
        }
        ExpressionTree initializer = variableTree.getInitializer();
        String enumConstant = null;
        if (initializer instanceof MemberSelectTree memberSelectTree) {
            // e.g. SomeEnum.VALUE -> VALUE
            enumConstant = memberSelectTree.getIdentifier().toString();
        } else if (initializer instanceof IdentifierTree identifierTree) {
            // e.g. statically imported VALUE -> VALUE
            enumConstant = identifierTree.getName().toString();
        }
        if (enumConstant == null) {
            return null;
        }
        return enumConstant;
    }

    private Optional<LinkTree> getFirstLinkInBlockTag(UnknownBlockTagTree tag) {
        for (DocTree tree : tag.getContent()) {
            if (tree instanceof LinkTree link) {
                return Optional.of(link);
            }
        }
        return Optional.empty();
    }

    /**
     * Resolves the fully qualified type name a {@code {@link ...}} reference points to.
     * @param path the path of the given inline link tag
     * @param link the inline link tag
     * @return
     */
    private String getType(DocTreePath path, LinkTree link) {
        String signature = link.getReference().getSignature();
        if (signature.contains("#")) {
            // report at the precise link reference node within the block tag
            DocTreePath linkRefPath = DocTreePath.getPath(path, link.getReference());
            throw new DocTreePathAwareRuntimeException(
                    linkRefPath != null ? linkRefPath : path,
                    "Expected a class link, but got a member reference: " + signature);
        }
        // resolve the referenced type and return its fully qualified name, falling back to the raw signature if it
        // cannot be resolved
        return resolveReferencedType(path, link.getReference())
                .map(t -> t.getQualifiedName().toString())
                .orElse(signature);
    }

    /**
     * Resolves the fully qualified class name a {@code {@link ...}} class reference points to (so that simple names
     * declared via imports are expanded). Falls back to the raw signature if the reference cannot be resolved to a
     * type.
     */
    private Optional<TypeElement> resolveReferencedType(DocTreePath path, ReferenceTree reference) {
        // TODO: try to resolve from type outside the current compilation unit (e.g. from imports)
        DocTreePath refPath = DocTreePath.getPath(path, reference);
        if (refPath == null) {
            return Optional.empty();
        }
        Element element = docTrees.getElement(refPath);
        return element instanceof TypeElement typeElement ? Optional.of(typeElement) : Optional.empty();
    }

    enum RenderMode {
        /** Render the content as plain text. Stripping any rich text markup */
        PLAIN,
        /** Render the content as HTML, escaping special characters and rendering inline tags. */
        HTML
    }

    private String renderContent(DocTreePath docTreePath, RenderMode mode, boolean trim) {
        return renderContent(docTreePath, mode, trim, null);
    }

    /**
     * Renders the content of a Javadoc tag into an HTML string, escaping HTML special characters and rendering inline tags.
     *
     * @param docTreePath encapsulates the doc comment tree and the path to the content being rendered.
     * The latter is used for resolving {@code {@link ...}} references and emitting error messages.
     * @param trim if true, trims the result string (may destroy {@code <pre> </pre>} formatting).
     * @param docTrees the doc trees for which to render the content. If {@code null}, the leaf of the {@code docTreePath} is rendered.
     * @return the rendered content (never {@code null})
     * @see <a href="https://docs.oracle.com/en/java/javase/25/docs/specs/javadoc/doc-comment-spec.html#standard-tags">Javadoc tags</a>
     * @see <a href="https://docs.oracle.com/en/java/javase/25/docs/api/jdk.compiler/com/sun/source/doctree/InlineTagTree.html">InlineTagTree (common superinterface of all inline tags)</a>
     */
    private String renderContent(
            DocTreePath docTreePath, RenderMode mode, boolean trim, Collection<? extends DocTree> docTreesToRender) {
        Objects.requireNonNull(docTreePath, "docTreePath must not be null");
        StringBuilder sb = new StringBuilder();
        SimpleDocTreeVisitor<String, Void> visitor = new SimpleDocTreeVisitor<String, Void>() {
            @Override
            public String visitText(TextTree node, Void p) {
                return escape(mode, node.getBody());
            }

            @Override
            public String visitLink(LinkTree node, Void p) {
                List<? extends DocTree> labelTrees = node.getLabel();
                String label = (labelTrees != null && !labelTrees.isEmpty())
                        ? renderContent(docTreePath, mode, false, labelTrees)
                        : "";
                return renderReference(node.getReference(), node.getKind() == DocTree.Kind.LINK_PLAIN, label);
            }

            @Override
            public String visitLiteral(LiteralTree node, Void p) {
                if (node.getKind() == DocTree.Kind.CODE) {
                    return renderAsCode(node.getBody().getBody());
                } else {
                    return escape(mode, node.getBody().getBody());
                }
            }

            @Override
            public String visitSystemProperty(SystemPropertyTree node, Void p) {
                return renderAsCode(node.getPropertyName().toString());
            }

            private String renderAsCode(String text) {
                if (mode == RenderMode.HTML) {
                    return "<code>" + escape(mode, text) + "</code>";
                } else {
                    return escape(mode, text);
                }
            }

            @Override
            public String visitValue(ValueTree node, Void p) {
                if (node.getReference() != null) {
                    DocTreePath refPath = DocTreePath.getPath(docTreePath, node.getReference());
                    if (refPath != null) {
                        Element element = docTrees.getElement(refPath);
                        if (element instanceof VariableElement ve) {
                            String value = lookupConstant(ve);
                            if (value != null) {
                                return renderAsCode(value);
                            }
                        }
                    }
                }
                // fall back to showing the reference signature
                String ref = node.getReference() != null ? node.getReference().getSignature() : "";
                return renderAsCode(ref);
            }

            @Override
            public String visitEntity(EntityTree node, Void p) {
                return "&" + node.getName() + ";";
            }

            @Override
            public String visitUnknownBlockTag(UnknownBlockTagTree node, Void p) {
                StringBuilder sb = new StringBuilder();
                node.getContent().forEach(child -> sb.append(child.accept(this, p)));
                return sb.toString();
            }

            @Override
            public String visitSince(SinceTree node, Void p) {
                return escape(mode, node.getBody().toString());
            }

            @Override
            public String visitDeprecated(DeprecatedTree node, Void p) {
                StringBuilder sb = new StringBuilder();
                node.getBody().forEach(child -> sb.append(child.accept(this, p)));
                return sb.toString();
            }

            @Override
            public String visitSee(SeeTree node, Void p) {
                // if the first reference is of type REFERENCE, the label may follow afterwards
                if (!node.getReference().isEmpty() && node.getReference().get(0) instanceof ReferenceTree reference) {
                    String label = renderContent(
                            docTreePath,
                            mode,
                            trim,
                            node.getReference().subList(1, node.getReference().size()));
                    return renderReference(reference, false, label);
                } else {
                    return renderContent(docTreePath, mode, trim, node.getReference());
                }
            }

            /**
             * Used from {@link #visitLink(LinkTree, Void)} and {@link #visitSee(SeeTree, Void)} to render a reference to a field or type (optionally with a label).
             * @param node the reference node
             * @param isPlain true if it should be emitted outside of a code block, false otherwise
             * @param label may be empty, in which case the reference signature is used as the label
             * @return the rendered reference (never {@code null})
             */
            private String renderReference(ReferenceTree node, boolean isPlain, String label) {
                String effectiveLabel = label.isEmpty() ? node.getSignature() : label;
                String escapedLabel = isPlain ? escape(mode, effectiveLabel) : renderAsCode(effectiveLabel);
                if (mode == RenderMode.HTML) {
                    VariableElement referenced = resolveReferencedField(docTreePath, node);
                    String configurationKey = getConfigurationKey(referenced);
                    if (configurationKey != null) {
                        if (label.isEmpty()) {
                            // override the effective label with the configuration key
                            escapedLabel = isPlain ? escape(mode, configurationKey) : renderAsCode(configurationKey);
                        }
                        return "<a href=\"#" + escape(mode, configurationKey) + "\">" + escapedLabel + "</a>";
                    }
                    Optional<String> javadocUrl = getJavadocUrl(docTreePath, node);
                    if (javadocUrl.isPresent()) {
                        return "<a href=\"" + javadocUrl.get() + "\">" + escapedLabel + "</a>";
                    }
                }
                return escapedLabel;
            }

            @Override
            protected String defaultAction(DocTree node, Void p) {
                // the default action internally calls node.toString(), which uses
                // com.sun.tools.javac.tree.DCTree.toString() which relies on com.sun.tools.javac.tree.DocPretty to
                // render the node
                return node.toString();
            }
        };
        if (docTreesToRender == null) {
            docTreesToRender = Collections.singleton(docTreePath.getLeaf());
        }
        for (DocTree docTreeToRender : docTreesToRender) {
            sb.append(docTreeToRender.accept(visitor, null));
        }

        if (trim) {
            // normalize whitespace not relevant for HTML rendering,
            // trimming behaviour already differs between different Javadoc
            // versions (Java > 21 trims leading whitespace per line)
            return sb.toString().trim().replaceAll("\\s+", " ");
        } else {
            return sb.toString();
        }
    }

    private static String escape(RenderMode mode, String text) {
        if (mode == RenderMode.HTML) {
            return text.replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;");
        } else {
            return text;
        }
    }

    private Optional<String> getSince(DocTreePath path) {
        String since = getSinceTag(path);
        if (since == null && path.getTreePath().getParentPath() != null) {
            // get the @since tag from the enclosing element (e.g. the enclosing class or package)
            return getSince(docTrees.getElement(path.getTreePath().getParentPath()));
        }
        return Optional.ofNullable(since);
    }

    private Optional<String> getSince(Element element) {
        if (element == null) {
            return Optional.empty();
        }
        DocCommentTree docComment = docTrees.getDocCommentTree(element);
        if (docComment != null) {
            DocTreePath path = new DocTreePath(docTrees.getPath(element), docComment);
            Optional<String> since = getSince(path);
            if (since.isPresent()) {
                return since;
            }
        }
        // traverse up the enclosing elements to find a @since tag in the closest enclosing type or package
        return getSince(element.getEnclosingElement());
    }

    private String getSinceTag(DocTreePath path) {
        if (path == null) {
            // may be non existent
            return null;
        }
        for (DocTree tag : path.getDocComment().getBlockTags()) {
            if (tag instanceof SinceTree) {
                return renderContent(DocTreePath.getPath(path, tag), RenderMode.PLAIN, true);
            }
        }
        return null;
    }

    private ConfigurationType getConfigurationType(DocTreePath path, Map<String, UnknownBlockTagTree> blockTags) {
        UnknownBlockTagTree typeTag = blockTags.get("configurationType");
        if (typeTag == null) {
            throw new IllegalStateException("Missing block tag @configurationType");
        }
        DocTreePath configurationTypePath = DocTreePath.getPath(path, typeTag);
        LinkTree linkTree = getFirstLinkInBlockTag(typeTag)
                .orElseThrow(() -> new DocTreePathAwareRuntimeException(
                        configurationTypePath, "No valid {@link ...} reference found in @" + typeTag.getTagName()));

        String type = getType(configurationTypePath, linkTree);
        String javadocUrl =
                getJavadocUrl(configurationTypePath, linkTree.getReference()).orElse("");
        String javaLangPackage = "java.lang.";
        if (type.startsWith(javaLangPackage)) {
            type = type.substring(javaLangPackage.length());
        }
        return new ConfigurationType(type, javadocUrl);
    }

    private String getConfigurationKey(VariableElement field) {
        if (field == null || !(field.getConstantValue() instanceof String key)) {
            return null;
        }
        if (mode == Mode.MAVEN) {
            return getAnnotation(field, MAVEN_CONFIG_ANNOTATION) != null ? key : null;
        }
        DocCommentTree docComment = docTrees.getDocCommentTree(field);
        return docComment != null && collectBlockTags(docComment).containsKey("configurationSource") ? key : null;
    }

    private Optional<String> getJavadocUrl(DocTreePath path, ReferenceTree reference) {
        if (reference == null) {
            return Optional.empty();
        }
        DocTreePath referencePath = DocTreePath.getPath(path, reference);
        if (referencePath == null) {
            return Optional.empty();
        }
        Element element = docTrees.getElement(referencePath);
        if (element == null) {
            return Optional.empty();
        }
        return createJavadocReference(element).flatMap(javadocReference -> {
            try {
                return Optional.of(
                        javadocLinkGenerator.createLink(javadocReference).toString());
            } catch (IllegalArgumentException e) {
                return Optional.empty();
            }
        });
    }

    private Optional<FullyQualifiedJavadocReference> createJavadocReference(Element element) {
        boolean external = !isInternalJavadocElement(element);
        if (element instanceof ModuleElement moduleElement) {
            return Optional.of(new FullyQualifiedJavadocReference(
                    Optional.of(moduleElement.getQualifiedName().toString()),
                    Optional.empty(),
                    Optional.empty(),
                    Optional.empty(),
                    Optional.empty(),
                    Optional.empty(),
                    external));
        }

        Optional<String> moduleName = external ? Optional.empty() : getModuleName(element);
        if (element instanceof PackageElement packageElement) {
            return Optional.of(new FullyQualifiedJavadocReference(
                    moduleName,
                    Optional.of(packageElement.getQualifiedName().toString()),
                    Optional.empty(),
                    Optional.empty(),
                    Optional.empty(),
                    Optional.empty(),
                    external));
        }

        TypeElement declaringType;
        Optional<String> member = Optional.empty();
        Optional<MemberType> memberType = Optional.empty();
        if (element instanceof TypeElement typeElement) {
            declaringType = typeElement;
        } else if (element instanceof VariableElement variableElement
                && variableElement.getEnclosingElement() instanceof TypeElement typeElement) {
            declaringType = typeElement;
            member = Optional.of(variableElement.getSimpleName().toString());
            memberType = Optional.of(MemberType.FIELD);
        } else if (element instanceof ExecutableElement executableElement
                && executableElement.getEnclosingElement() instanceof TypeElement typeElement) {
            declaringType = typeElement;
            String executableName = executableElement.getKind() == ElementKind.CONSTRUCTOR
                    ? typeElement.getSimpleName().toString()
                    : executableElement.getSimpleName().toString();
            String parameterTypes = String.join(
                    ",",
                    executableElement.getParameters().stream()
                            .map(parameter -> getFullyQualifiedName(types.erasure(parameter.asType())))
                            .toList());
            member = Optional.of(executableName + "(" + parameterTypes + ")");
            memberType = Optional.of(
                    executableElement.getKind() == ElementKind.CONSTRUCTOR
                            ? MemberType.CONSTRUCTOR
                            : MemberType.METHOD);
        } else {
            return Optional.empty();
        }

        PackageElement packageElement = elements.getPackageOf(declaringType);
        String packageName = packageElement.getQualifiedName().toString();
        String qualifiedName = declaringType.getQualifiedName().toString();
        String className = packageName.isEmpty() ? qualifiedName : qualifiedName.substring(packageName.length() + 1);
        return Optional.of(new FullyQualifiedJavadocReference(
                moduleName,
                Optional.of(packageName),
                Optional.of(className),
                member,
                memberType,
                Optional.empty(),
                external));
    }

    private Optional<String> getModuleName(Element element) {
        ModuleElement module = elements.getModuleOf(element);
        return module != null && !module.isUnnamed()
                ? Optional.of(module.getQualifiedName().toString())
                : Optional.empty();
    }

    private boolean isInternalJavadocElement(Element element) {
        if (element instanceof ModuleElement) {
            return docTrees.getPath(element) != null;
        }
        if (element instanceof PackageElement packageElement) {
            return docTrees.getPath(element) != null || isPackageInInternalSourceTree(packageElement);
        }

        TypeElement topLevelType = null;
        for (Element current = element;
                current != null && !(current instanceof PackageElement) && !(current instanceof ModuleElement);
                current = current.getEnclosingElement()) {
            if (current instanceof TypeElement typeElement) {
                topLevelType = typeElement;
            }
            if (isJavadocDeclaration(current)
                    && !current.getModifiers().contains(Modifier.PUBLIC)
                    && !current.getModifiers().contains(Modifier.PROTECTED)) {
                return false;
            }
        }
        return topLevelType != null
                && (docTrees.getPath(topLevelType) != null || isTypeInInternalSourceTree(topLevelType));
    }

    private boolean isPackageInInternalSourceTree(PackageElement packageElement) {
        Path packagePath = getPackagePath(packageElement);
        return internalJavadocSourceRoots.stream()
                .map(sourceRoot -> sourceRoot.resolve(packagePath))
                .anyMatch(Files::isDirectory);
    }

    private boolean isTypeInInternalSourceTree(TypeElement topLevelType) {
        Path packagePath = getPackagePath(elements.getPackageOf(topLevelType));
        Path sourceFile = packagePath.resolve(topLevelType.getSimpleName() + ".java");
        return internalJavadocSourceRoots.stream()
                .map(sourceRoot -> sourceRoot.resolve(sourceFile))
                .anyMatch(Files::isRegularFile);
    }

    private static Path getPackagePath(PackageElement packageElement) {
        String packageName = packageElement.getQualifiedName().toString();
        return packageName.isEmpty() ? Path.of("") : Path.of(packageName.replace('.', '/'));
    }

    private static boolean isJavadocDeclaration(Element element) {
        ElementKind kind = element.getKind();
        return kind.isClass()
                || kind.isInterface()
                || kind == ElementKind.FIELD
                || kind == ElementKind.ENUM_CONSTANT
                || kind == ElementKind.METHOD
                || kind == ElementKind.CONSTRUCTOR;
    }

    private Optional<String> getConfigurationSource(DocTreePath path, Map<String, UnknownBlockTagTree> blockTags) {
        UnknownBlockTagTree configurationSourceTag = blockTags.get("configurationSource");
        if (configurationSourceTag == null) {
            return Optional.empty();
        }
        DocTreePath configurationSourcePath = DocTreePath.getPath(path, configurationSourceTag);
        LinkTree linkTree = getFirstLinkInBlockTag(configurationSourceTag)
                .orElseThrow(() -> new DocTreePathAwareRuntimeException(
                        configurationSourcePath,
                        "No valid {@link ...} reference found in @" + configurationSourceTag.getTagName()));

        // javadoc signature is not normalized, use the resolved reference (leveraging ReferenceParser) to get a unique
        // canonical representation of the referenced method
        MethodReference methodReference = getReferencedMethod(configurationSourcePath, linkTree);
        if (methodReference.equals(METHOD_REFERENCE_SESSION_CONFIGURATION)) {
            return Optional.of("Session Configuration");
        } else if (methodReference.equals(METHOD_REFERENCE_SYSTEM_PROPERTY)) {
            return Optional.of("Java System Properties");
        } else {
            reporter.print(
                    Diagnostic.Kind.WARNING,
                    path,
                    "Unknown configuration source: " + linkTree.getReference().getSignature()
                            + ", using raw signature as source");
            return Optional.of(linkTree.getReference().getSignature());
        }
    }

    /**
     * Represents a reference to a method, including the fully qualified class name, method name, and parameter types.
     * This is supposed to be unique as well as canonical.
     * The signature within a Javadoc link is not normalized (e.g. may contain spaces or not, may contain argument names or not)
     * so we need to resolve the reference to get a unique representation of the method.
     * @param fullyQualifiedClassName the fully qualified name of the class containing the method
     * @param methodName the name of the method
     * @param fullyQualifiedParameterTypes a list of fully qualified names (for declared types) or simple names (for primitive types) of the parameter types of the method
     */
    protected record MethodReference(
            String fullyQualifiedClassName, String methodName, List<String> fullyQualifiedParameterTypes) {}

    private MethodReference getReferencedMethod(DocTreePath path, LinkTree link) {
        ExecutableElement ee = getReferencedExecutableElement(path, link);
        String fullyQualifiedClassName =
                ((TypeElement) ee.getEnclosingElement()).getQualifiedName().toString();
        String methodName = ee.getSimpleName().toString();
        List<String> parameterTypes = ee.getParameters().stream()
                .map(p -> getFullyQualifiedName(p.asType()))
                .toList();
        return new MethodReference(fullyQualifiedClassName, methodName, parameterTypes);
    }

    static String getFullyQualifiedName(Element e) {
        return new SimpleElementVisitor14<String, Void>() {
            @Override
            public String visitModule(ModuleElement e, Void p) {
                return e.getQualifiedName().toString();
            }

            @Override
            public String visitPackage(PackageElement e, Void p) {
                return e.getQualifiedName().toString();
            }

            @Override
            public String visitType(TypeElement e, Void p) {
                return e.getQualifiedName().toString();
            }

            @Override
            protected String defaultAction(Element e, Void p) {
                return visit(e.getEnclosingElement()) + "." + e.getSimpleName();
            }
        }.visit(e);
    }

    static String getFullyQualifiedName(TypeMirror e) {
        return new SimpleTypeVisitor14<String, Void>() {
            @Override
            public String visitDeclared(DeclaredType t, Void p) {
                Element e = t.asElement();
                if (e instanceof TypeElement typeElement) {
                    return typeElement.getQualifiedName().toString();
                }
                return super.visitDeclared(t, p);
            }

            @Override
            public String visitPrimitive(PrimitiveType t, Void p) {
                return t.toString();
            }

            @Override
            protected String defaultAction(TypeMirror e, Void p) {
                return e.toString();
            }
        }.visit(e);
    }

    private ExecutableElement getReferencedExecutableElement(DocTreePath path, LinkTree link) {
        DocTreePath linkRefPath = DocTreePath.getPath(path, link.getReference());
        if (linkRefPath == null) {
            throw new DocTreePathAwareRuntimeException(
                    path,
                    "Could not resolve link reference: " + link.getReference().getSignature());
        }
        Element element = docTrees.getElement(linkRefPath);
        if (element instanceof ExecutableElement ee) {
            return ee;
        } else {
            throw new DocTreePathAwareRuntimeException(
                    linkRefPath, "Expected an executable element, but got: " + element);
        }
    }

    private static String toYesNo(boolean value) {
        return value ? "Yes" : "No";
    }

    private static URI parseJavadocUrl(String value) {
        URI uri = URI.create(value);
        if (uri.getQuery() != null || uri.getFragment() != null) {
            throw new IllegalArgumentException("Javadoc base URL must not contain a query or fragment: " + value);
        }
        return value.endsWith("/") ? uri : URI.create(value + "/");
    }

    /**
     * Minimal {@link Option} implementation.
     */
    private static final class SingleArgumentOption implements Option {
        private final List<String> names;
        private final String description;
        private final String parameters;
        private final java.util.function.Consumer<String> processor;

        SingleArgumentOption(
                List<String> names,
                String description,
                String parameters,
                java.util.function.Consumer<String> processor) {
            this.names = names;
            this.description = description;
            this.parameters = parameters;
            this.processor = processor;
        }

        @Override
        public int getArgumentCount() {
            return 1;
        }

        @Override
        public String getDescription() {
            return description;
        }

        @Override
        public Kind getKind() {
            return Kind.STANDARD;
        }

        @Override
        public List<String> getNames() {
            return names;
        }

        @Override
        public String getParameters() {
            return parameters;
        }

        @Override
        public boolean process(String option, List<String> arguments) {
            processor.accept(arguments.get(0));
            // returning false just leads to a very generic error message (not even exposing the affected option) so
            // rather rely on custom runtime exceptions for validation errors
            return true;
        }
    }
}