///////////////////////////////////////////////////////////////////////////////////////////////
// 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.ArrayDeque;
import java.util.Deque;
import java.util.HashMap;
import java.util.HashSet;
import java.util.Map;
import java.util.Set;

import com.puppycrawl.tools.checkstyle.FileStatefulCheck;
import com.puppycrawl.tools.checkstyle.api.DetailAST;
import com.puppycrawl.tools.checkstyle.api.DetailNode;
import com.puppycrawl.tools.checkstyle.api.FullIdent;
import com.puppycrawl.tools.checkstyle.api.JavadocCommentsTokenTypes;
import com.puppycrawl.tools.checkstyle.api.TokenTypes;
import com.puppycrawl.tools.checkstyle.utils.JavadocUtil;
import com.puppycrawl.tools.checkstyle.utils.NullUtil;

/**
 * <div>
 * Checks that in Javadoc comments, each API name is linked with
 * {@code {@link}} or {@code {@linkplain}} only on its first occurrence.
 * Subsequent links to the same API name in the same comment are flagged.
 * </div>
 *
 * <p>
 * Rationale: From the
 * <a href="https://www.oracle.com/technical-resources/articles/java/javadoc-tool.html">
 * Documentation Comments style guide</a>, links call attention to
 * themselves by their color and underline in HTML, and by their length
 * in source code doc comments. Linking the same name multiple times is redundant.
 * </p>
 *
 * <p>
 * Two links are considered to reference the same API name if they resolve to
 * the same canonical name. Simple names are resolved through explicit imports,
 * types declared in the current file, star imports and the
 * {@code java.lang} package. Names containing dots are resolved through
 * imports of their outermost segment; otherwise they are compared as written.
 * </p>
 *
 * @since 14.1.0
 */
@FileStatefulCheck
public class JavadocLinkFirstOccurrenceCheck extends AbstractJavadocCheck {

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

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

    /**
     * Tokens of type declarations.
     */
    private static final Set<Integer> TYPE_DECLARATION_TOKENS = Set.of(
            TokenTypes.CLASS_DEF,
            TokenTypes.INTERFACE_DEF,
            TokenTypes.ENUM_DEF,
            TokenTypes.RECORD_DEF,
            TokenTypes.ANNOTATION_DEF
    );

    /**
     * Set of reference keys already seen in the current Javadoc comment.
     */
    private final Set<String> linkedNames = new HashSet<>();

    /**
     * Map of imported simple names to fully qualified names.
     */
    private Map<String, String> importedNames;

    /**
     * Set of star import base packages.
     */
    private Set<String> starImports;

    /**
     * Set of simple names of types declared in the current file.
     */
    private Set<String> declaredTypeNames;

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

    @Override
    public int[] getRequiredTokens() {
        return new int[] {
            TokenTypes.BLOCK_COMMENT_BEGIN,
            TokenTypes.IMPORT,
        };
    }

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

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

    @Override
    public void beginTree(DetailAST rootAST) {
        super.beginTree(rootAST);
        importedNames = new HashMap<>();
        starImports = new HashSet<>();
        declaredTypeNames = new HashSet<>();
        if (rootAST != null) {
            collectDeclaredTypeNames(rootAST);
        }
    }

    @Override
    public void beginJavadocTree(DetailNode rootAst) {
        linkedNames.clear();
    }

    @Override
    public void visitToken(DetailAST ast) {
        if (ast.getType() == TokenTypes.IMPORT) {
            handleImport(ast);
        }
        else {
            super.visitToken(ast);
        }
    }

    @Override
    public void visitJavadocToken(DetailNode ast) {
        final DetailNode reference = JavadocUtil.findFirstToken(ast,
                JavadocCommentsTokenTypes.REFERENCE);
        final String originalReference = getNodeText(reference);
        final String resolvedKey = resolveReference(originalReference);
        if (!linkedNames.add(resolvedKey)) {
            log(ast, MSG_KEY, originalReference);
        }
    }

    /**
     * Processes import statements and records imported names.
     *
     * @param ast import node
     */
    private void handleImport(DetailAST ast) {
        final String importText = FullIdent.createFullIdentBelow(ast).getText();
        if (importText.endsWith(".*")) {
            starImports.add(importText.substring(0, importText.length() - 2));
        }
        else {
            final int lastDot = importText.lastIndexOf(DOT);
            final String simple = importText.substring(lastDot + 1);
            importedNames.put(simple, importText);
        }
    }

    /**
     * Records the simple names of all type declarations.
     * The whole tree is scanned so that types declared after their
     * references are also taken into account.
     *
     * @param rootAST the root of the tree to scan
     */
    private void collectDeclaredTypeNames(DetailAST rootAST) {
        final Deque<DetailAST> stack = new ArrayDeque<>();
        stack.push(rootAST);
        while (!stack.isEmpty()) {
            final DetailAST ast = stack.pop();
            if (TYPE_DECLARATION_TOKENS.contains(ast.getType())) {
                final DetailAST ident =
                        NullUtil.notNull(ast.findFirstToken(TokenTypes.IDENT));
                declaredTypeNames.add(ident.getText());
            }
            DetailAST child = ast.getFirstChild();
            while (child != null) {
                stack.push(child);
                child = child.getNextSibling();
            }
        }
    }

    /**
     * Resolves a reference text to a canonical key for identity comparison.
     * The class part of the reference is resolved through imports and
     * types declared in the current file.
     *
     * @param reference the raw reference text
     * @return the resolved identity key
     */
    private String resolveReference(String reference) {
        final int hashIndex = reference.indexOf('#');
        final String className;
        final String memberPart;
        if (hashIndex == -1) {
            className = reference;
            memberPart = "";
        }
        else {
            className = reference.substring(0, hashIndex);
            memberPart = reference.substring(hashIndex);
        }
        final String resolved = resolveClass(className);
        return resolved + memberPart;
    }

    /**
     * Resolves a class name to its canonical name through imports,
     * types declared in the current file, star imports and the
     * {@code java.lang} package. Names containing dots have only their
     * outermost segment resolved; otherwise they are returned unchanged.
     *
     * @param name the class name
     * @return the resolved canonical name
     */
    private String resolveClass(String name) {
        final int dotIndex = name.indexOf(DOT);
        final String result;
        if (dotIndex == -1) {
            result = resolveSimpleClassName(name);
        }
        else {
            result = resolveOuterSegment(name, dotIndex);
        }
        return result;
    }

    /**
     * Resolves a simple class name through imports, types declared in the
     * current file, star imports and the {@code java.lang} package.
     *
     * @param name the simple class name
     * @return the resolved canonical name
     */
    private String resolveSimpleClassName(String name) {
        final String importCandidate = importedNames.get(name);
        final String result;
        if (importCandidate != null) {
            result = importCandidate;
        }
        else if (declaredTypeNames.contains(name)) {
            result = name;
        }
        else if (starImports.isEmpty()) {
            result = "java.lang." + name;
        }
        else {
            result = starImports.iterator().next() + DOT + name;
        }
        return result;
    }

    /**
     * Resolves the outermost segment of a dotted class name through imports,
     * keeping the remainder unchanged.
     *
     * @param name the dotted class name
     * @param dotIndex the index of the first dot in the name
     * @return the resolved canonical name
     */
    private String resolveOuterSegment(String name, int dotIndex) {
        final String outer = name.substring(0, dotIndex);
        final String importCandidate = importedNames.get(outer);
        final String result;
        if (importCandidate != null) {
            final String remainder = name.substring(dotIndex);
            result = importCandidate + remainder;
        }
        else {
            result = name;
        }
        return result;
    }

    /**
     * Recursively builds the full text of a node by concatenating
     * the text of all its leaf descendants.
     *
     * @param node the node to get text from
     * @return the concatenated text, or null if the node is null
     */
    private static String getNodeText(DetailNode node) {
        final StringBuilder sb = new StringBuilder(256);
        DetailNode child = node.getFirstChild();
        while (child != null) {
            sb.append(getNodeText(child));
            child = child.getNextSibling();
        }
        final String text;
        if (sb.isEmpty()) {
            text = node.getText();
        }
        else {
            text = sb.toString();
        }
        return text;
    }

}