///////////////////////////////////////////////////////////////////////////////////////////////
// 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.checks.javadoc;

import java.util.Arrays;
import java.util.Set;
import java.util.stream.Collectors;

import com.puppycrawl.tools.checkstyle.StatelessCheck;
import com.puppycrawl.tools.checkstyle.api.DetailNode;
import com.puppycrawl.tools.checkstyle.api.JavadocCommentsTokenTypes;
import com.puppycrawl.tools.checkstyle.utils.JavadocUtil;

/**
 * <div>
 * Checks that Javadoc comments avoid unnecessary {@code {@link}} and {@code {@linkplain}} tags
 * for APIs that are considered well-known. Linking well-known APIs can make comments harder to
 * read without adding much value for the reader.
 * </div>
 *
 * <p>
 * This check reports {@code {@link}} references to configured well-known APIs.
 * Two properties are supported:
 * {@code wellKnownQualifiedPackages} and {@code wellKnownSimpleNames}.
 * </p>
 *
 * <p>
 * Both properties are needed because Checkstyle does not resolve Javadoc link targets.
 * For example, {@code java.lang.String} contains the package name, so it can be
 * matched through {@code wellKnownQualifiedPackages}. However, {@code String}
 * only contains the simple name {@code String}, so it needs to be matched through
 * {@code wellKnownSimpleNames}. Resolution of imports is not a solution since
 * {@code java.lang} is implicitly imported.
 * </p>
 *
 * <p>
 * For {@code wellKnownQualifiedPackages}, only references to classes that are
 * direct members of a well-known package are reported. References to a member
 * (for example, {@code String#length()}), a nested class (for example,
 * {@code System.Logger}), a subpackage (for example, {@code java.lang.ref.WeakReference}),
 * and a package itself (for example, {@code java.lang.ref}) are not reported.
 * </p>
 *
 * @since 14.1.0
 */
@StatelessCheck
public class JavadocLinkWellKnownApiCheck extends AbstractJavadocCheck {

    /**
     * A key is pointing to the warning message text in "messages.properties"
     * file.
     */
    public static final String MSG_WELL_KNOWN_API = "javadoc.wellKnownApi";

    /**
     * A key is pointing to the warning message text in "messages.properties"
     * file.
     */
    public static final String MSG_WELL_KNOWN_PACKAGE = "javadoc.wellKnownPackage";

    /**
     * Dot.
     */
    private static final char DOT = '.';

    /**
     * Package names whose fully qualified API references should not be linked.
     */
    private Set<String> wellKnownQualifiedPackages = Set.of("java.lang");

    /**
     * Simple API names that should not be linked.
     */
    private Set<String> wellKnownSimpleNames = Set.of("String");

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

    @Override
    public int[] getDefaultJavadocTokens() {
        return getRequiredJavadocTokens();
    }

    @Override
    public int[] getRequiredJavadocTokens() {
        return new int[] {
            JavadocCommentsTokenTypes.LINK_INLINE_TAG,
            JavadocCommentsTokenTypes.LINKPLAIN_INLINE_TAG,
        };
    }

    /**
     * Setter to specify package names whose fully qualified API references should not be
     * linked.
     *
     * @param values user's values.
     * @since 14.1.0
     */
    public final void setWellKnownQualifiedPackages(String... values) {
        wellKnownQualifiedPackages = Arrays.stream(values).collect(Collectors.toUnmodifiableSet());
    }

    /**
     * Setter to specify simple API names that should not be linked.
     *
     * @param values user's values.
     * @since 14.1.0
     */
    public final void setWellKnownSimpleNames(String... values) {
        wellKnownSimpleNames = Arrays.stream(values).collect(Collectors.toUnmodifiableSet());
    }

    @Override
    public void visitJavadocToken(DetailNode ast) {
        final DetailNode referenceNode = JavadocUtil.findFirstToken(ast,
                JavadocCommentsTokenTypes.REFERENCE);
        if (JavadocUtil.findFirstToken(referenceNode,
                JavadocCommentsTokenTypes.MEMBER_REFERENCE) == null) {
            final String apiName = referenceNode.getFirstChild().getText();
            if (isWellKnownQualified(apiName)) {
                log(ast, MSG_WELL_KNOWN_PACKAGE, apiName);
            }
            else if (wellKnownSimpleNames.contains(apiName)) {
                log(ast, MSG_WELL_KNOWN_API, apiName);
            }
        }
    }

    /**
     * Checks whether the given API name belongs to a well-known qualified package.
     *
     * @param apiName the API name to check
     * @return true if the API name belongs to a well-known qualified package
     */
    private boolean isWellKnownQualified(String apiName) {
        boolean result = false;
        for (String packageName : wellKnownQualifiedPackages) {
            final String prefix = packageName + DOT;
            final int prefixLength = prefix.length();
            if (apiName.startsWith(prefix)
                    && apiName.length() > prefixLength
                    && Character.isUpperCase(apiName.charAt(prefixLength))
                    && apiName.indexOf(DOT, prefixLength) == -1) {
                result = true;
                break;
            }
        }
        return result;
    }

}