///////////////////////////////////////////////////////////////////////////////////////////////
   // 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;
  
  import static com.google.common.truth.Truth.assertWithMessage;
  import static org.junit.jupiter.api.Assertions.assertDoesNotThrow;
  
  import java.io.File;
  import java.io.IOException;
  import java.lang.reflect.Method;
  import java.lang.reflect.Modifier;
  import java.nio.charset.StandardCharsets;
  import java.util.ArrayList;
  import java.util.Arrays;
  import java.util.List;
  import java.util.Set;
  import java.util.stream.Collectors;
  
  import org.antlr.v4.runtime.CharStream;
  import org.antlr.v4.runtime.CharStreams;
  import org.antlr.v4.runtime.CommonTokenStream;
  import org.junit.jupiter.api.Test;
  
  import com.puppycrawl.tools.checkstyle.api.DetailAST;
  import com.puppycrawl.tools.checkstyle.api.FileContents;
  import com.puppycrawl.tools.checkstyle.api.FileText;
  import com.puppycrawl.tools.checkstyle.api.TokenTypes;
  import com.puppycrawl.tools.checkstyle.grammar.java.JavaLanguageLexer;
  import com.puppycrawl.tools.checkstyle.grammar.java.JavaLanguageParser;
  import com.puppycrawl.tools.checkstyle.grammar.java.JavaLanguageParserBaseVisitor;
  import com.puppycrawl.tools.checkstyle.internal.utils.TestUtil;
  
  // -@cs[ClassDataAbstractionCoupling] No way to split up class usage.
  
  /**
   * Tests for {@code JavaAstVisitor}.
   *
   * <p>Verifies correct traversal and processing of Java AST nodes.</p>
   *
   * @noinspection JavadocReference References are valid in project context
   * @noinspectionreason JavadocReference - References are valid
   */
  public class JavaAstVisitorTest extends AbstractModuleTestSupport {
  
      /**
       * If a visit method is not overridden, we should explain why we do not 'visit' the
       * parse tree at this node and construct an AST. Reasons could include that we have
       * no terminal symbols (tokens) in the corresponding production rule, or that
       * we handle the construction of this particular AST in its parent node. If we
       * have a production rule where we have terminal symbols (tokens), but we do not build
       * an AST from tokens in the rule context, the rule is extraneous.
       */
      private static final Set<String> VISIT_METHODS_NOT_OVERRIDDEN = Set.of(
              // no tokens in production rule, so no AST to build
              "visitClassOrInterfaceOrPrimitiveType",
              "visitNonWildcardTypeArgs",
              "visitStat",
              "visitAnnotationConstantRest",
              "visitSwitchLabeledRule",
              "visitLocalVariableDeclaration",
              "visitTypes",
              "visitSwitchStat",
              "visitSwitchPrimary",
              "visitClassDef",
              "visitInterfaceMemberDeclaration",
              "visitMemberDeclaration",
              "visitCompactMember",
              "visitCompactMemberDeclaration",
              "visitLiteralPrimary",
              "visitPatternDefinition",
              "visitLocalType",
              "visitLocalTypeDeclaration",
              "visitRecordBodyDeclaration",
              "visitResource",
              "visitVariableInitializer",
              "visitLambdaBody",
              "visitPatternVariableDef",
              "visitConstructorBlockStatement",
  
              // AST built in parent rule
              "visitCreatedNameExtended",
              "visitSuperSuffixSimple",
             "visitFieldAccessNoIdent",
             "visitClassType",
             "visitClassOrInterfaceTypeExtended",
             "visitQualifiedNameExtended",
             "visitGuard"
     );
 
     @Override
     public String getPackageLocation() {
         return "com/puppycrawl/tools/checkstyle/javaastvisitor";
     }
 
     @Test
     public void testAllVisitMethodsAreOverridden() {
         final Method[] baseVisitMethods = JavaLanguageParserBaseVisitor
                 .class.getDeclaredMethods();
         final Method[] visitMethods = JavaAstVisitor.class.getDeclaredMethods();
 
         final Set<String> filteredBaseVisitMethodNames = Arrays.stream(baseVisitMethods)
                 .filter(method -> !VISIT_METHODS_NOT_OVERRIDDEN.contains(method.getName()))
                 .filter(method -> method.getName().contains("visit"))
                 .filter(method -> method.getModifiers() == Modifier.PUBLIC)
                 .map(Method::getName)
                 .collect(Collectors.toUnmodifiableSet());
 
         final Set<String> filteredVisitMethodNames = Arrays.stream(visitMethods)
                 .filter(method -> method.getName().contains("visit"))
                 // remove overridden 'visit' method from ParseTreeVisitor interface in
                 // JavaAstVisitor
                 .filter(method -> !"visit".equals(method.getName()))
                 .filter(method -> method.getModifiers() == Modifier.PUBLIC)
                 .map(Method::getName)
                 .collect(Collectors.toUnmodifiableSet());
 
         assertWithMessage(
             "Visit methods in 'JavaLanguageParserBaseVisitor' generated from production "
                 + "rules and labeled alternatives in 'JavaLanguageParser.g4' should be "
                 + "overridden in 'JavaAstVisitor' or be added to 'VISIT_METHODS_NOT_OVERRIDDEN' "
                         + "with comment explaining why.")
                 .that(filteredVisitMethodNames)
                 .containsExactlyElementsIn(filteredBaseVisitMethodNames);
     }
 
     @Test
     public void testOrderOfVisitMethodsAndProductionRules() throws Exception {
         // Order of BaseVisitor's generated 'visit' methods match the order of
         // production rules in 'JavaLanguageParser.g4'.
         final String baseVisitorFilename = "target/generated-sources/antlr/com/puppycrawl"
                 + "/tools/checkstyle/grammar/java/JavaLanguageParserBaseVisitor.java";
         final DetailAST baseVisitorAst = JavaParser.parseFile(new File(baseVisitorFilename),
                             JavaParser.Options.WITHOUT_COMMENTS);
 
         final String visitorFilename = "src/main/java/com/puppycrawl/tools/checkstyle"
                 + "/JavaAstVisitor.java";
         final DetailAST visitorAst = JavaParser.parseFile(new File(visitorFilename),
                             JavaParser.Options.WITHOUT_COMMENTS);
 
         final List<String> orderedBaseVisitorMethodNames =
                 getOrderedVisitMethodNames(baseVisitorAst);
         final List<String> orderedVisitorMethodNames =
                 getOrderedVisitMethodNames(visitorAst);
 
         orderedBaseVisitorMethodNames.removeAll(VISIT_METHODS_NOT_OVERRIDDEN);
 
         // remove overridden 'visit' method from ParseTreeVisitor interface in JavaAstVisitor
         orderedVisitorMethodNames.remove("visit");
 
         assertWithMessage("Visit methods in 'JavaAstVisitor' should appear in same order as "
                 + "production rules and labeled alternatives in 'JavaLanguageParser.g4'.")
                 .that(orderedVisitorMethodNames)
                 .containsExactlyElementsIn(orderedBaseVisitorMethodNames)
                 .inOrder();
     }
 
     /**
      * The reason we have this test is that we forgot to add the imaginary 'EXPR' node
      * to a production rule in the parser grammar (we should have used 'expression'
      * instead of 'expr'). This test is a reminder to question the usage of the 'expr' parser
      * rule in the parser grammar when we update the count to make sure we are not missing
      * an imaginary 'EXPR' node in the AST.
      *
      * @throws IOException if file does not exist
      */
     @Test
     public void countExprUsagesInParserGrammar() throws IOException {
         final String parserGrammarFilename = "src/main/resources/com/puppycrawl"
                 + "/tools/checkstyle/grammar/java/JavaLanguageParser.g4";
 
         final int actualExprCount = Arrays.stream(new FileText(new File(parserGrammarFilename),
                         StandardCharsets.UTF_8.name()).toLinesArray())
                 .mapToInt(JavaAstVisitorTest::countExprInLine)
                 .sum();
 
         // Any time we update this count, we should question why we are not building an imaginary
         // 'EXPR' node.
         final int expectedExprCount = 44;
 
         assertWithMessage("The 'expr' parser rule does not build an imaginary"
                 + " 'EXPR' node. Any usage of this rule should be questioned.")
                 .that(actualExprCount)
                 .isEqualTo(expectedExprCount);
 
     }
 
     private static int countExprInLine(String line) {
         return (int) Arrays.stream(line.split(" "))
                 .filter("expr"::equals)
                 .count();
     }
 
     /**
      * Finds all {@code visit...} methods in a source file, and collects
      * the method names into a list. This method counts on the simple structure
      * of 'JavaAstVisitor' and 'JavaLanguageParserBaseVisitor'.
      *
      * @param root the root of the AST to extract method names from
      * @return list of all {@code visit...} method names
      */
     private static List<String> getOrderedVisitMethodNames(DetailAST root) {
         final List<String> orderedVisitMethodNames = new ArrayList<>();
 
         DetailAST classDef = root.getFirstChild();
         while (classDef.getType() != TokenTypes.CLASS_DEF) {
             classDef = classDef.getNextSibling();
         }
 
         final DetailAST objBlock = classDef.findFirstToken(TokenTypes.OBJBLOCK);
         DetailAST objBlockChild = objBlock.findFirstToken(TokenTypes.METHOD_DEF);
         while (objBlockChild != null) {
             if (isVisitMethod(objBlockChild)) {
                 orderedVisitMethodNames.add(objBlockChild
                         .findFirstToken(TokenTypes.IDENT)
                         .getText());
             }
             objBlockChild = objBlockChild.getNextSibling();
         }
         return orderedVisitMethodNames;
     }
 
     /**
      * Checks if given AST is a visit method.
      *
      * @param objBlockChild AST to check
      * @return true if AST is a visit method
      */
     private static boolean isVisitMethod(DetailAST objBlockChild) {
         return objBlockChild.getType() == TokenTypes.METHOD_DEF
                 && objBlockChild.findFirstToken(TokenTypes.IDENT).getText().contains("visit");
     }
 
     @Test
     public void testNullSelfInAddLastSibling() {
         assertDoesNotThrow(() -> {
             TestUtil.invokeVoidStaticMethod(JavaAstVisitor.class, "addLastSibling",
                     null, null);
         }, "Method should not throw exception.");
     }
     /**
      * This test exists to kill surviving mutation from pitest removing expression AST building
      * optimization in {@link JavaAstVisitor#visitBinOp(JavaLanguageParser.BinOpContext)}.
      * We do not use {@link JavaParser#parse(FileContents)} here due to DFA clearing hack.
      *
      * <p>
      * Reason: we have iterative expression AST building to avoid stackoverflow
      * in {@link JavaAstVisitor#visitBinOp(JavaLanguageParser.BinOpContext)}. In actual
      * generated parser, we avoid stackoverflow thanks to the left recursive expression
      * rule (eliminating unnecessary recursive calls to hierarchical expression production rules).
      * However, ANTLR's ParserATNSimulator has no such optimization. So, the number of recursive
      * calls to ParserATNSimulator#closure when calling ParserATNSimulator#clearDFA causes a
      * StackOverflow error. We avoid this by using the single argument constructor (thus not
      * forcing DFA clearing) in this test.
      * </p>
      *
      * @throws Exception if input file does not exist
      */
 
     @Test
     public void testNoStackOverflowOnDeepStringConcat() throws Exception {
         final File file =
                 new File(getPath("InputJavaAstVisitorNoStackOverflowOnDeepStringConcat.java"));
         final FileText fileText = new FileText(file, StandardCharsets.UTF_8.name());
         final FileContents contents = new FileContents(fileText);
 
         final String fullText = contents.getText().getFullText().toString();
         final CharStream codePointCharStream = CharStreams.fromString(fullText);
         final JavaLanguageLexer lexer = new JavaLanguageLexer(codePointCharStream, true);
         lexer.setCommentListener(contents);
 
         final CommonTokenStream tokenStream = new CommonTokenStream(lexer);
         final JavaLanguageParser parser = new JavaLanguageParser(tokenStream);
 
         final JavaLanguageParser.CompilationUnitContext compilationUnit = parser.compilationUnit();
 
         // We restrict execution to use limited resources here, so that we can
         // kill surviving pitest mutation from removal of nested binary operation
         // optimization in JavaAstVisitor#visitBinOp. Limited resources (small stack size)
         // ensure that we throw a StackOverflowError if optimization is removed.
         final DetailAST root = TestUtil.getResultWithLimitedResources(
                 () -> new JavaAstVisitor(tokenStream).visit(compilationUnit)
         );
 
         assertWithMessage("File parsing and AST building should complete successfully.")
                 .that(root)
                 .isNotNull();
     }
 }