///////////////////////////////////////////////////////////////////////////////////////////////
   // 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.ArrayList;
  import java.util.Arrays;
  import java.util.BitSet;
  import java.util.HashMap;
  import java.util.List;
  import java.util.Locale;
  import java.util.Map;
  
  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.JavadocCommentsTokenTypes;
  import com.puppycrawl.tools.checkstyle.api.TokenTypes;
  import com.puppycrawl.tools.checkstyle.utils.JavadocUtil;
  import com.puppycrawl.tools.checkstyle.utils.TokenUtil;
  
  /**
   * <div>
   * Checks that multiple {@code @see} tags are ordered in a predictable way,
   * roughly following the order in which their arguments are searched for by javadoc,
   * from nearest to farthest access, from least-qualified to fully-qualified.
   * </div>
   *
   * <p>The order of {@code @see} tags should be:</p>
   * <ol>
   *   <li>local members first</li>
   *   <li>simple class references after local members</li>
   *   <li>simple class member references after simple class references</li>
   *   <li>qualified class references after simple class member references</li>
   *   <li>qualified class member references after qualified class references</li>
   *   <li>package references last</li>
   * </ol>
   *
   * <p>Inside each member group, fields come first, then constructors, then
   * methods. Overloaded constructors and methods with the same name must be
   * grouped together and ordered by the number of parameters, with the fewest
   * parameters first.</p>
   *
   * <p>For example, this is the order recommended by the OpenJDK documentation
   * comments style guide:</p>
   * <div class="wrapper"><pre>
   * &#64;see #field
   * &#64;see #Constructor(Type, Type...)
   * &#64;see #Constructor(Type id, Type id...)
   * &#64;see #method(Type, Type,...)
   * &#64;see #method(Type id, Type, id...)
   * &#64;see Class
   * &#64;see Class#field
   * &#64;see Class#Constructor(Type, Type...)
   * &#64;see Class#Constructor(Type id, Type id)
   * &#64;see Class#method(Type, Type,...)
   * &#64;see Class#method(Type id, Type id,...)
   * &#64;see package.Class
   * &#64;see package.Class#field
   * &#64;see package.Class#Constructor(Type, Type...)
   * &#64;see package.Class#Constructor(Type id, Type id)
   * &#64;see package.Class#method(Type, Type,...)
   * &#64;see package.Class#method(Type id, Type, id)
   * &#64;see package
   * </pre></div>
   *
   * <p>References that are not in a recognizable structured form (for example
   * {@code @see "Effective Java"}, or an HTML anchor) are ignored for ordering
   * purposes, so the check only reports violations when it is confident about
   * the correct order. References using the {@code Type##fragment} syntax to
   * link to a named fragment within a page (rather than to a member) are
   * intentionally ignored as well, since such fragments are not javadoc type
   * or member references and cannot be meaningfully compared to one.</p>
   *
   * @since 14.2.0
   */
  @FileStatefulCheck
  public class JavadocSeeTagOrderCheck extends AbstractJavadocCheck {
  
      /**
       * A key is pointing to the warning message text in "messages.properties" file.
       */
      public static final String MSG_KEY = "javadoc.seeTagOrder";
 
     /** Dot. */
     private static final char DOT = '.';
 
     /** Hash sign used to separate a type name from its member. */
     private static final char HASH = '#';
 
     /** Number of {@link Kind} values, used to combine category and kind into one key. */
     private static final int KIND_COUNT = 3;
 
     /** Token types that represent a type declaration. */
     private static final BitSet TYPE_DEFINITION_TOKENS = TokenUtil.asBitSet(
             TokenTypes.CLASS_DEF, TokenTypes.INTERFACE_DEF, TokenTypes.ENUM_DEF,
             TokenTypes.RECORD_DEF, TokenTypes.ANNOTATION_DEF);
 
     /** The most distant structural position seen so far in the current Javadoc tree. */
     private SeeReference maxReference;
 
     /** The reference that immediately precedes the current one. */
     private SeeReference previousReference;
 
     /** The most recent reference for each member name within the current Javadoc tree. */
     private Map<String, SeeReference> lastByName;
 
     /** Simple name of the type that most closely encloses the current Javadoc comment. */
     private String enclosingTypeName;
 
     /**
      * Creates a new {@code JavadocSeeTagOrderCheck} instance.
      */
     public JavadocSeeTagOrderCheck() {
         // no code by default
     }
 
     @Override
     public int[] getDefaultJavadocTokens() {
         return getRequiredJavadocTokens();
     }
 
     @Override
     public int[] getRequiredJavadocTokens() {
         return new int[] {
             JavadocCommentsTokenTypes.SEE_BLOCK_TAG,
         };
     }
 
     @Override
     public void beginJavadocTree(DetailNode rootAst) {
         maxReference = null;
         lastByName = new HashMap<>();
         enclosingTypeName = findEnclosingTypeName(getBlockCommentAst());
     }
 
     /**
      * Finds the simple name of the type declaration that most closely encloses the
      * given block comment, so that local {@code @see #Name()} references can be
      * recognized as referring to a constructor of that type.
      *
      * @param commentBlock the block comment to start searching from
      * @return the enclosing type's simple name, or an empty string if none is found
      */
     private static String findEnclosingTypeName(DetailAST commentBlock) {
         DetailAST current = commentBlock;
         while (current != null && !isTypeDefinition(current)) {
             current = current.getParent();
         }
         String result = "";
         if (current != null) {
             result = current.findFirstToken(TokenTypes.IDENT).getText();
         }
         return result;
     }
 
     /**
      * Checks whether the given node is a type declaration.
      *
      * @param ast the node to check
      * @return {@code true} if the node is a class, interface, enum, record, or
      *     annotation declaration
      */
     private static boolean isTypeDefinition(DetailAST ast) {
         return TYPE_DEFINITION_TOKENS.get(ast.getType());
     }
 
     @Override
     public void visitJavadocToken(DetailNode ast) {
         final SeeReference current = SeeReference.from(ast, enclosingTypeName);
         if (current != null) {
             if (maxReference == null) {
                 maxReference = current;
             }
             else if (isStructuralViolation(current, maxReference)) {
                 log(ast, MSG_KEY, current.text(), maxReference.text());
             }
             else if (isTelescopingViolation(current)) {
                 log(ast, MSG_KEY, current.text(), lastByName.get(lastByKey(current)).text());
             }
             else if (isGroupingViolation(current)) {
                 log(ast, MSG_KEY, current.text(), previousReference.text());
             }
             if (current.structurallyAfterThan(maxReference)) {
                 maxReference = current;
             }
             previousReference = current;
             lastByName.put(lastByKey(current), current);
         }
     }
 
     /**
      * Checks whether the current reference breaks the structural order
      * (category and field-before-constructor-before-method).
      *
      * @param current the current reference
      * @param maximum the greatest structural reference seen so far
      * @return {@code true} if the structural order is violated
      */
     private static boolean isStructuralViolation(SeeReference current, SeeReference maximum) {
         return current.structuralKey() < maximum.structuralKey();
     }
 
     /**
      * Checks whether the current reference breaks the telescoping order of an
      * overloaded constructor or method with the same name.
      *
      * @param current the current reference
      * @return {@code true} if the telescoping order is violated
      */
     private boolean isTelescopingViolation(SeeReference current) {
         final SeeReference sameName = lastByName.get(lastByKey(current));
         return sameName != null
                 && current.parameterCount() < sameName.parameterCount();
     }
 
     /**
      * Checks whether the current reference breaks the grouping of overloaded
      * members with the same name.
      *
      * @param current the current reference
      * @return {@code true} if the grouping is violated
      */
     private boolean isGroupingViolation(SeeReference current) {
         return lastByName.containsKey(lastByKey(current))
                 && previousReference.kind() == current.kind()
                 && !previousReference.name().equals(current.name());
     }
 
     /**
      * Returns the map key that scopes a member name to its owning type and category
      * group, so that grouping and telescoping checks only apply to overloads of the
      * same member on the same type.
      *
      * @param reference the reference
      * @return the map key
      */
     private static String lastByKey(SeeReference reference) {
         return reference.category() + ":" + reference.qualifier() + "#" + reference.name();
     }
 
     /**
      * Category of a {@code @see} reference, ordered from the closest to the most
      * distant access.
      */
     private enum Category {
         /** Local member such as {@code #field} or {@code #method()}. */
         LOCAL(0),
         /** Simple type reference such as {@code OtherClass}. */
         SIMPLE_TYPE(1),
         /** Simple type member such as {@code OtherClass#field}. */
         SIMPLE_MEMBER(2),
         /** Qualified type reference such as {@code java.util.List}. */
         QUALIFIED_TYPE(3),
         /** Qualified type member such as {@code java.util.List#size()}. */
         QUALIFIED_MEMBER(4),
         /** Package reference such as {@code java.util}. */
         PACKAGE(5);
 
         /** Explicit structural order, independent of the enum's declaration order. */
         private final int structuralOrder;
 
         /**
          * Creates a new {@code Category} instance.
          *
          * @param order the explicit structural order
          */
         Category(int order) {
             structuralOrder = order;
         }
 
         /**
          * Returns the explicit structural order.
          *
          * @return the structural order
          */
         /* package */ int order() {
             return structuralOrder;
         }
 
     }
 
     /**
      * Kind of a member {@code @see} reference, ordered from the closest to the most
      * distant access. Type and package references are not members and are always
      * classified as {@link #METHOD}, since that kind never needs to be compared
      * against another kind within their own category.
      */
     private enum Kind {
         /** A field reference such as {@code #field}. */
         FIELD(0),
         /** A constructor reference such as {@code #Example()}. */
         CONSTRUCTOR(1),
         /** A method or type/package reference such as {@code #getName()}. */
         METHOD(2);
 
         /** Explicit structural order, independent of the enum's declaration order. */
         private final int structuralOrder;
 
         /**
          * Creates a new {@code Kind} instance.
          *
          * @param order the explicit structural order
          */
         Kind(int order) {
             structuralOrder = order;
         }
 
         /**
          * Returns the explicit structural order.
          *
          * @return the structural order
          */
         /* package */ int order() {
             return structuralOrder;
         }
 
     }
 
     /**
      * Represents a parsed {@code @see} reference together with the ordering
      * information needed to validate the order.
      *
      * @param category category that defines the primary structural ordering
      * @param kind whether the reference is a field, constructor, or method
      * @param qualifier owning type name, or an empty string for local and
      *     non-member references
      * @param name simple member or type name used for grouping
      * @param parameterCount number of parameters, used to order overloaded methods
      * @param text full reference text used for messages
      */
     private record SeeReference(
             Category category,
             Kind kind,
             String qualifier,
             String name,
             int parameterCount,
             String text) {
 
         /**
          * Parses a {@code @see} block tag into a {@code SeeReference}, or returns
          * {@code null} if the reference is not in a form that can be confidently ordered.
          *
          * @param seeBlock the {@code @see} block tag
          * @param enclosingTypeName simple name of the type that most closely encloses
          *     the Javadoc comment, used to recognize local constructor references
          * @return the parsed reference, or {@code null} if it cannot be classified
          */
         private static SeeReference from(DetailNode seeBlock, String enclosingTypeName) {
             final DetailNode reference = JavadocUtil.findFirstToken(
                     seeBlock, JavadocCommentsTokenTypes.REFERENCE);
             SeeReference result = null;
             if (reference != null && !isFragmentReference(reference)) {
                 final DetailNode firstChild = reference.getFirstChild();
                 final int firstType = firstChild.getType();
 
                 if (firstType == JavadocCommentsTokenTypes.HASH) {
                     final DetailNode member = JavadocUtil.findFirstToken(
                             reference, JavadocCommentsTokenTypes.MEMBER_REFERENCE);
                     result = parseMember(member, "", Category.LOCAL, enclosingTypeName);
                 }
                 else {
                     result = parseIdentifierReference(reference, firstChild);
                 }
             }
             return result;
         }
 
         /**
          * Checks whether the given reference uses the {@code Type##fragment} syntax to
          * link to a named fragment within a page, recognizable by two consecutive hash
          * signs among its children. Such references are not javadoc type or member
          * references and cannot be meaningfully compared to one.
          *
          * @param reference the reference node
          * @return {@code true} if the reference contains two consecutive hash signs
          */
         private static boolean isFragmentReference(DetailNode reference) {
             boolean sawHash = false;
             boolean result = false;
             DetailNode child = reference.getFirstChild();
             while (child != null) {
                 if (child.getType() == JavadocCommentsTokenTypes.HASH) {
                     if (sawHash) {
                         result = true;
                         break;
                     }
                     sawHash = true;
                 }
                 child = child.getNextSibling();
             }
             return result;
         }
 
         /**
          * Parses an identifier-based reference (simple or qualified type, member,
          * or package reference).
          *
          * @param reference the reference node
          * @param identifierNode the identifier node
          * @return the parsed reference, or {@code null} if it cannot be classified
          */
         private static SeeReference parseIdentifierReference(DetailNode reference,
                 DetailNode identifierNode) {
             final String typeName = identifierNode.getText();
             final DetailNode member = JavadocUtil.findFirstToken(
                     reference, JavadocCommentsTokenTypes.MEMBER_REFERENCE);
             SeeReference result = null;
             if (member != null) {
                 final Category category;
                 if (typeName.indexOf(DOT) == -1) {
                     category = Category.SIMPLE_MEMBER;
                 }
                 else {
                     category = Category.QUALIFIED_MEMBER;
                 }
                 result = parseMember(member, typeName, category, lastIdentifier(typeName));
             }
             else if (isTypeReference(typeName)) {
                 final Category category;
                 if (typeName.indexOf(DOT) == -1) {
                     category = Category.SIMPLE_TYPE;
                 }
                 else {
                     category = Category.QUALIFIED_TYPE;
                 }
                 result = new SeeReference(category, Kind.METHOD, "",
                         lastIdentifier(typeName), 0, typeName);
             }
             else if (typeName.indexOf(DOT) != -1 && isPackageReference(typeName)) {
                 result = new SeeReference(Category.PACKAGE, Kind.METHOD, "",
                         typeName, 0, typeName);
             }
             return result;
         }
 
         /**
          * Parses a member reference (local member or class member).
          *
          * @param member the member reference node
          * @param qualifier the owning type name, or an empty string for local members
          * @param category category of the reference
          * @param ownerSimpleName simple name of the owning type, compared against the
          *     member name to recognize constructor references
          * @return the parsed member reference
          */
         private static SeeReference parseMember(DetailNode member, String qualifier,
                 Category category, String ownerSimpleName) {
             final DetailNode identifier = JavadocUtil.findFirstToken(
                     member, JavadocCommentsTokenTypes.IDENTIFIER);
             final boolean callable = JavadocUtil.findFirstToken(
                     member, JavadocCommentsTokenTypes.LPAREN) != null;
             final String memberName = identifier.getText();
             final List<String> parameterTypes = parameterTypes(member);
             final StringBuilder text = new StringBuilder(qualifier)
                     .append(HASH);
             if (callable) {
                 text.append(memberName).append('(');
                 for (int ind = 0; ind < parameterTypes.size(); ind++) {
                     if (ind > 0) {
                         text.append(", ");
                     }
                     text.append(parameterTypes.get(ind));
                 }
                 text.append(')');
             }
             else {
                 text.append(memberName);
             }
             final Kind kind;
             if (callable) {
                 if (memberName.equals(ownerSimpleName)) {
                     kind = Kind.CONSTRUCTOR;
                 }
                 else {
                     kind = Kind.METHOD;
                 }
             }
             else {
                 kind = Kind.FIELD;
             }
             return new SeeReference(category, kind, qualifier, memberName,
                     parameterTypes.size(), text.toString());
         }
 
         /**
          * Returns the parameter type texts of a member reference.
          *
          * @param member the member reference node
          * @return the list of parameter type texts
          */
         private static List<String> parameterTypes(DetailNode member) {
             final DetailNode parameterList = JavadocUtil.findFirstToken(
                     member, JavadocCommentsTokenTypes.PARAMETER_TYPE_LIST);
             final List<String> parameterTypes = new ArrayList<>();
             if (parameterList != null) {
                 DetailNode node = parameterList.getFirstChild();
                 while (node != null) {
                     if (node.getType() == JavadocCommentsTokenTypes.PARAMETER_TYPE) {
                         parameterTypes.add(node.getText());
                     }
                     node = node.getNextSibling();
                 }
             }
             return parameterTypes;
         }
 
         /**
          * Checks whether the given text looks like a type reference (last segment
          * starts with an uppercase letter).
          *
          * @param referenceText the reference text to check
          * @return {@code true} if the text is a type reference
          */
         private static boolean isTypeReference(String referenceText) {
             final String lastSegment = lastIdentifier(referenceText);
             return Character.isUpperCase(lastSegment.charAt(0));
         }
 
         /**
          * Checks whether the given text looks like a package reference (all lowercase
          * segments and contains at least one dot).
          *
          * @param referenceText the reference text to check
          * @return {@code true} if the text is a package reference
          */
         private static boolean isPackageReference(String referenceText) {
             return Arrays.stream(referenceText.split("\\" + DOT, -1))
                     .allMatch(segment -> segment.toLowerCase(Locale.ROOT).equals(segment));
         }
 
         /**
          * Returns the last identifier segment of a dotted name.
          *
          * @param name the dotted name
          * @return the last segment
          */
         private static String lastIdentifier(String name) {
             return name.substring(name.lastIndexOf(DOT) + 1);
         }
 
         /**
          * Returns the structural ordering key combining the category and, for member
          * references, whether the reference is a field, constructor, or method.
          *
          * @return the structural ordering key
          */
         /* package */ int structuralKey() {
             return category.order() * KIND_COUNT + kind.order();
         }
 
         /**
          * Checks whether this reference is structurally after the given reference.
          *
          * @param other the reference to compare to
          * @return {@code true} if this reference is structurally after the other
          */
         /* package */ boolean structurallyAfterThan(SeeReference other) {
             return structuralKey() >= other.structuralKey();
         }
 
     }
 
 }