///////////////////////////////////////////////////////////////////////////////////////////////
   // 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.metrics;
  
  import java.util.ArrayDeque;
  import java.util.ArrayList;
  import java.util.Arrays;
  import java.util.Deque;
  import java.util.HashMap;
  import java.util.List;
  import java.util.Map;
  import java.util.Optional;
  import java.util.Set;
  import java.util.TreeSet;
  import java.util.function.Predicate;
  import java.util.regex.Pattern;
  
  import com.puppycrawl.tools.checkstyle.FileStatefulCheck;
  import com.puppycrawl.tools.checkstyle.api.AbstractCheck;
  import com.puppycrawl.tools.checkstyle.api.DetailAST;
  import com.puppycrawl.tools.checkstyle.api.FullIdent;
  import com.puppycrawl.tools.checkstyle.api.TokenTypes;
  import com.puppycrawl.tools.checkstyle.utils.CommonUtil;
  import com.puppycrawl.tools.checkstyle.utils.TokenUtil;
  
  /**
   * Base class for coupling calculation.
   *
   */
  @FileStatefulCheck
  public abstract class AbstractClassCouplingCheck extends AbstractCheck {
  
      /** A package separator - ".". */
      private static final char DOT = '.';
  
      /** Class names to ignore. */
      private static final Set<String> DEFAULT_EXCLUDED_CLASSES = Set.of(
          // reserved type name
          "var",
          // primitives
          "boolean", "byte", "char", "double", "float", "int",
          "long", "short", "void",
          // wrappers
          "Boolean", "Byte", "Character", "Double", "Float",
          "Integer", "Long", "Short", "Void",
          // java.lang.*
          "Object", "Class",
          "String", "StringBuffer", "StringBuilder",
          // Exceptions
          "ArrayIndexOutOfBoundsException", "Exception",
          "RuntimeException", "IllegalArgumentException",
          "IllegalStateException", "IndexOutOfBoundsException",
          "NullPointerException", "Throwable", "SecurityException",
          "UnsupportedOperationException",
          // java.util.*
          "List", "ArrayList", "Deque", "Queue", "LinkedList",
          "Set", "HashSet", "SortedSet", "TreeSet",
          "Map", "HashMap", "SortedMap", "TreeMap",
          "Override", "Deprecated", "SafeVarargs", "SuppressWarnings", "FunctionalInterface",
          "Collection", "EnumSet", "LinkedHashMap", "LinkedHashSet", "Optional",
          "OptionalDouble", "OptionalInt", "OptionalLong",
          // java.util.stream.*
          "DoubleStream", "IntStream", "LongStream", "Stream"
      );
  
      /** Package names to ignore. */
      private static final Set<String> DEFAULT_EXCLUDED_PACKAGES = Set.of();
  
      /** Pattern to match brackets in a full type name. */
      private static final Pattern BRACKET_PATTERN = Pattern.compile("\\[[^]]*]");
  
      /** Specify user-configured regular expressions to ignore classes. */
      private final List<Pattern> excludeClassesRegexps = new ArrayList<>();
  
      /** A map of {@literal (imported class name -> class name with package)} pairs. */
      private final Map<String, String> importedClassPackages = new HashMap<>();
  
      /** Stack of class contexts. */
      private final Deque<ClassContext> classesContexts = new ArrayDeque<>();
  
      /** Specify user-configured class names to ignore. */
      private Set<String> excludedClasses = DEFAULT_EXCLUDED_CLASSES;
 
     /**
      * Specify user-configured packages to ignore.
      */
     private Set<String> excludedPackages = DEFAULT_EXCLUDED_PACKAGES;
 
     /** Specify the maximum threshold allowed. */
     private int max;
 
     /** Current file package. */
     private String packageName;
 
     /**
      * Creates new instance of the check.
      *
      * @param defaultMax default value for allowed complexity.
      */
     protected AbstractClassCouplingCheck(int defaultMax) {
         max = defaultMax;
         excludeClassesRegexps.add(CommonUtil.createPattern("^$"));
     }
 
     /**
      * Returns message key we use for log violations.
      *
      * @return message key we use for log violations.
      */
     protected abstract String getLogMessageId();
 
     @Override
     public final int[] getDefaultTokens() {
         return getRequiredTokens();
     }
 
     /**
      * Setter to specify the maximum threshold allowed.
      *
      * @param max allowed complexity.
      */
     public final void setMax(int max) {
         this.max = max;
     }
 
     /**
      * Setter to specify user-configured class names to ignore.
      *
      * @param excludedClasses classes to ignore.
      */
     public void setExcludedClasses(String... excludedClasses) {
         this.excludedClasses = Set.of(excludedClasses);
     }
 
     /**
      * Setter to specify user-configured regular expressions to ignore classes.
      *
      * @param from array representing regular expressions of classes to ignore.
      */
     public void setExcludeClassesRegexps(Pattern... from) {
         excludeClassesRegexps.addAll(Arrays.asList(from));
     }
 
     /**
      * Setter to specify user-configured packages to ignore.
      *
      * @param excludedPackages packages to ignore.
      * @throws IllegalArgumentException if there are invalid identifiers among the packages.
      */
     public void setExcludedPackages(String... excludedPackages) {
         final List<String> invalidIdentifiers = Arrays.stream(excludedPackages)
             .filter(Predicate.not(CommonUtil::isName))
             .toList();
         if (!invalidIdentifiers.isEmpty()) {
             throw new IllegalArgumentException(
                 "the following values are not valid identifiers: " + invalidIdentifiers);
         }
 
         this.excludedPackages = Set.of(excludedPackages);
     }
 
     @Override
     public final void beginTree(DetailAST ast) {
         importedClassPackages.clear();
         classesContexts.clear();
         classesContexts.push(new ClassContext("", null));
         packageName = "";
     }
 
     @Override
     public void visitToken(DetailAST ast) {
         switch (ast.getType()) {
             case TokenTypes.PACKAGE_DEF -> visitPackageDef(ast);
             case TokenTypes.IMPORT -> registerImport(ast);
             case TokenTypes.CLASS_DEF,
                  TokenTypes.INTERFACE_DEF,
                  TokenTypes.ANNOTATION_DEF,
                  TokenTypes.ENUM_DEF,
                  TokenTypes.RECORD_DEF -> visitClassDef(ast);
             case TokenTypes.COMPACT_COMPILATION_UNIT -> visitCompactCompilationUnit(ast);
             case TokenTypes.EXTENDS_CLAUSE,
                  TokenTypes.IMPLEMENTS_CLAUSE,
                  TokenTypes.TYPE -> visitType(ast);
             case TokenTypes.LITERAL_NEW -> visitLiteralNew(ast);
             case TokenTypes.LITERAL_THROWS -> visitLiteralThrows(ast);
             case TokenTypes.ANNOTATION -> visitAnnotationType(ast);
             default -> throw new IllegalArgumentException("Unknown type: " + ast);
         }
     }
 
     @Override
     public void leaveToken(DetailAST ast) {
         if (TokenUtil.isTypeDeclaration(ast.getType())
                 || ast.getType() == TokenTypes.COMPACT_COMPILATION_UNIT) {
             leaveClassDef();
         }
     }
 
     /**
      * Stores package of current class we check.
      *
      * @param pkg package definition.
      */
     private void visitPackageDef(DetailAST pkg) {
         final FullIdent ident = FullIdent.createFullIdent(pkg.getLastChild().getPreviousSibling());
         packageName = ident.getText();
     }
 
     /**
      * Creates new context for a given class.
      *
      * @param classDef class definition node.
      */
     private void visitClassDef(DetailAST classDef) {
         final String className = classDef.findFirstToken(TokenTypes.IDENT).getText();
         createNewClassContext(className, classDef);
     }
 
     /**
      * Creates new context for the implicit class declared by a compact
      * compilation unit (JEP 512).
      *
      * @param compactCompilationUnit COMPACT_COMPILATION_UNIT node.
      */
     private void visitCompactCompilationUnit(DetailAST compactCompilationUnit) {
         createNewClassContext("", compactCompilationUnit);
     }
 
     /** Restores previous context. */
     private void leaveClassDef() {
         checkCurrentClassAndRestorePrevious();
     }
 
     /**
      * Registers given import. This allows us to track imported classes.
      *
      * @param imp import definition.
      */
     private void registerImport(DetailAST imp) {
         final FullIdent ident = FullIdent.createFullIdent(
             imp.getLastChild().getPreviousSibling());
         final String fullName = ident.getText();
         final int lastDot = fullName.lastIndexOf(DOT);
         importedClassPackages.put(fullName.substring(lastDot + 1), fullName);
     }
 
     /**
      * Creates new inner class context with given name and location.
      *
      * @param className The class name.
      * @param ast The class ast.
      */
     private void createNewClassContext(String className, DetailAST ast) {
         classesContexts.push(new ClassContext(className, ast));
     }
 
     /** Restores previous context. */
     private void checkCurrentClassAndRestorePrevious() {
         classesContexts.pop().checkCoupling();
     }
 
     /**
      * Visits type token for the current class context.
      *
      * @param ast TYPE token.
      */
     private void visitType(DetailAST ast) {
         classesContexts.peek().visitType(ast);
     }
 
     /**
      * Visits NEW token for the current class context.
      *
      * @param ast NEW token.
      */
     private void visitLiteralNew(DetailAST ast) {
         classesContexts.peek().visitLiteralNew(ast);
     }
 
     /**
      * Visits THROWS token for the current class context.
      *
      * @param ast THROWS token.
      */
     private void visitLiteralThrows(DetailAST ast) {
         classesContexts.peek().visitLiteralThrows(ast);
     }
 
     /**
      * Visit ANNOTATION literal and get its type to referenced classes of context.
      *
      * @param annotationAST Annotation ast.
      */
     private void visitAnnotationType(DetailAST annotationAST) {
         final DetailAST children = annotationAST.getFirstChild();
         final DetailAST type = children.getNextSibling();
         classesContexts.peek().addReferencedClassName(type.getText());
     }
 
     /**
      * Encapsulates information about class coupling.
      *
      */
     private final class ClassContext {
 
         /**
          * Set of referenced classes.
          * Sorted by name for predictable violation messages in unit tests.
          */
         private final Set<String> referencedClassNames = new TreeSet<>();
         /** Own class name. */
         private final String className;
         /* Location of own class. (Used to log violations) */
         /** AST of class definition. */
         private final DetailAST classAst;
 
         /**
          * Create new context associated with given class.
          *
          * @param className name of the given class.
          * @param ast ast of class definition.
          */
         private ClassContext(String className, DetailAST ast) {
             this.className = className;
             classAst = ast;
         }
 
         /**
          * Visits throws clause and collects all exceptions we throw.
          *
          * @param literalThrows throws to process.
          */
         /* package */ void visitLiteralThrows(DetailAST literalThrows) {
             for (DetailAST childAST = literalThrows.getFirstChild();
                  childAST != null;
                  childAST = childAST.getNextSibling()) {
                 if (childAST.getType() != TokenTypes.COMMA) {
                     addReferencedClassName(childAST);
                 }
             }
         }
 
         /**
          * Visits type.
          *
          * @param ast type to process.
          */
         /* package */ void visitType(DetailAST ast) {
             DetailAST child = ast.getFirstChild();
             while (child != null) {
                 if (TokenUtil.isOfType(child, TokenTypes.IDENT, TokenTypes.DOT)) {
                     final String fullTypeName = FullIdent.createFullIdent(child).getText();
                     final String trimmed = BRACKET_PATTERN
                             .matcher(fullTypeName).replaceAll("");
                     addReferencedClassName(trimmed);
                 }
                 child = child.getNextSibling();
             }
         }
 
         /**
          * Visits NEW.
          *
          * @param ast NEW to process.
          */
         /* package */ void visitLiteralNew(DetailAST ast) {
 
             if (ast.getParent().getType() == TokenTypes.METHOD_REF) {
                 addReferencedClassName(ast.getParent().getFirstChild());
             }
             else {
                 addReferencedClassName(ast);
             }
         }
 
         /**
          * Adds new referenced class.
          *
          * @param ast a node which represents referenced class.
          */
         private void addReferencedClassName(DetailAST ast) {
             final String fullIdentName = FullIdent.createFullIdent(ast).getText();
             final String trimmed = BRACKET_PATTERN
                     .matcher(fullIdentName).replaceAll("");
             addReferencedClassName(trimmed);
         }
 
         /**
          * Adds new referenced class.
          *
          * @param referencedClassName class name of the referenced class.
          */
         private void addReferencedClassName(String referencedClassName) {
             if (isSignificant(referencedClassName)) {
                 referencedClassNames.add(referencedClassName);
             }
         }
 
         /** Checks if coupling less than allowed or not. */
         /* package */ void checkCoupling() {
             referencedClassNames.remove(className);
             referencedClassNames.remove(packageName + DOT + className);
 
             if (referencedClassNames.size() > max) {
                 log(classAst, getLogMessageId(),
                         referencedClassNames.size(), max,
                         referencedClassNames.toString());
             }
         }
 
         /**
          * Checks if given class shouldn't be ignored and not from java.lang.
          *
          * @param candidateClassName class to check.
          * @return true if we should count this class.
          */
         private boolean isSignificant(String candidateClassName) {
             return !excludedClasses.contains(candidateClassName)
                 && !isFromExcludedPackage(candidateClassName)
                 && !isExcludedClassRegexp(candidateClassName);
         }
 
         /**
          * Checks if given class should be ignored as it belongs to excluded package.
          *
          * @param candidateClassName class to check
          * @return true if we should not count this class.
          */
         private boolean isFromExcludedPackage(String candidateClassName) {
             String classNameWithPackage = candidateClassName;
             if (candidateClassName.indexOf(DOT) == -1) {
                 classNameWithPackage = getClassNameWithPackage(candidateClassName)
                     .orElse("");
             }
             boolean isFromExcludedPackage = false;
             if (classNameWithPackage.indexOf(DOT) != -1) {
                 final int lastDotIndex = classNameWithPackage.lastIndexOf(DOT);
                 final String candidatePackageName =
                     classNameWithPackage.substring(0, lastDotIndex);
                 isFromExcludedPackage = candidatePackageName.startsWith("java.lang")
                     || excludedPackages.contains(candidatePackageName);
             }
             return isFromExcludedPackage;
         }
 
         /**
          * Retrieves class name with packages. Uses previously registered imports to
          * get the full class name.
          *
          * @param examineClassName Class name to be retrieved.
          * @return Class name with package name, if found, {@link Optional#empty()} otherwise.
          */
         private Optional<String> getClassNameWithPackage(String examineClassName) {
             return Optional.ofNullable(importedClassPackages.get(examineClassName));
         }
 
         /**
          * Checks if given class should be ignored as it belongs to excluded class regexp.
          *
          * @param candidateClassName class to check.
          * @return true if we should not count this class.
          */
         private boolean isExcludedClassRegexp(String candidateClassName) {
             boolean result = false;
             for (Pattern pattern : excludeClassesRegexps) {
                 if (pattern.matcher(candidateClassName).matches()) {
                     result = true;
                     break;
                 }
             }
             return result;
         }
     }
 
 }