///////////////////////////////////////////////////////////////////////////////////////////////
   // checkstyle: Checks Java source code and other text files for adherence to a set of rules.
   // Copyright (C) 2001-2025 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.site;
  
  import java.lang.reflect.Field;
  import java.util.Set;
  import java.util.regex.Pattern;
  
  import org.apache.maven.doxia.macro.MacroExecutionException;
  import org.apache.maven.doxia.sink.Sink;
  
  import com.puppycrawl.tools.checkstyle.PropertyType;
  import com.puppycrawl.tools.checkstyle.XdocsPropertyType;
  import com.puppycrawl.tools.checkstyle.api.DetailNode;
  import com.puppycrawl.tools.checkstyle.api.JavadocCommentsTokenTypes;
  import com.puppycrawl.tools.checkstyle.meta.JavadocMetadataScraperUtil;
  import com.puppycrawl.tools.checkstyle.utils.JavadocUtil;
  
  /**
   * Utility class for parsing javadocs of modules.
   */
  public final class ModuleJavadocParsingUtil {
      /** New line escape character. */
      public static final String NEWLINE = System.lineSeparator();
      /** A newline with 8 spaces of indentation. */
      public static final String INDENT_LEVEL_8 = SiteUtil.getNewlineAndIndentSpaces(8);
      /** A newline with 10 spaces of indentation. */
      public static final String INDENT_LEVEL_10 = SiteUtil.getNewlineAndIndentSpaces(10);
      /** A newline with 12 spaces of indentation. */
      public static final String INDENT_LEVEL_12 = SiteUtil.getNewlineAndIndentSpaces(12);
      /** A newline with 14 spaces of indentation. */
      public static final String INDENT_LEVEL_14 = SiteUtil.getNewlineAndIndentSpaces(14);
      /** A newline with 16 spaces of indentation. */
      public static final String INDENT_LEVEL_16 = SiteUtil.getNewlineAndIndentSpaces(16);
      /** A newline with 18 spaces of indentation. */
      public static final String INDENT_LEVEL_18 = SiteUtil.getNewlineAndIndentSpaces(18);
      /** A newline with 20 spaces of indentation. */
      public static final String INDENT_LEVEL_20 = SiteUtil.getNewlineAndIndentSpaces(20);
      /** A set of all html tags that need to be considered as text formatting for this macro. */
      public static final Set<String> HTML_TEXT_FORMAT_TAGS = Set.of("<code>", "<a", "</a>", "<b>",
          "</b>", "<strong>", "</strong>", "<i>", "</i>", "<em>", "</em>", "<small>", "</small>",
          "<ins>", "<sub>", "<sup>");
      /** "Notes:" javadoc marking. */
      public static final String NOTES = "Notes:";
      /** "Notes:" line. */
      public static final Pattern NOTES_LINE = Pattern.compile("\\s*" + NOTES + "$");
      /** "Notes:" line with new line accounted. */
      public static final Pattern NOTES_LINE_WITH_NEWLINE = Pattern.compile("\r?\n\\s?" + NOTES);
  
      /**
       * Private utility constructor.
       */
      private ModuleJavadocParsingUtil() {
      }
  
      /**
       * Gets properties of the specified module.
       *
       * @param moduleName name of module.
       * @return set of properties name if present, otherwise null.
       * @throws MacroExecutionException if the module could not be retrieved.
       */
      public static Set<String> getPropertyNames(String moduleName)
              throws MacroExecutionException {
          final Object instance = SiteUtil.getModuleInstance(moduleName);
          final Class<?> clss = instance.getClass();
  
          return SiteUtil.getPropertiesForDocumentation(clss, instance);
      }
  
      /**
       * Determines whether the given HTML node marks the start of the "Notes" section.
       *
       * @param htmlElement html element to check.
       * @return true if the element starts the "Notes" section, false otherwise.
       */
      private static boolean isStartOfNotesSection(DetailNode htmlElement) {
          final DetailNode htmlContentNode = JavadocUtil.findFirstToken(
              htmlElement, JavadocCommentsTokenTypes.HTML_CONTENT);
  
          return htmlContentNode != null && JavadocMetadataScraperUtil.isChildNodeTextMatches(
              htmlContentNode, NOTES_LINE);
     }
 
     /**
      * Writes the given javadoc chunk into xdoc.
      *
      * @param javadocPortion javadoc text.
      * @param sink sink of the macro.
      */
     public static void writeOutJavadocPortion(String javadocPortion, Sink sink) {
         final String[] javadocPortionLinesSplit = javadocPortion.split(NEWLINE
             .replace("\r", ""));
 
         sink.rawText(javadocPortionLinesSplit[0]);
         String lastHtmlTag = javadocPortionLinesSplit[0];
 
         for (int index = 1; index < javadocPortionLinesSplit.length; index++) {
             final String currentLine = javadocPortionLinesSplit[index].trim();
             final String processedLine;
 
             if (currentLine.isEmpty()) {
                 processedLine = NEWLINE;
             }
             else if (currentLine.startsWith("<")
                 && !startsWithTextFormattingHtmlTag(currentLine)) {
 
                 processedLine = INDENT_LEVEL_8 + currentLine;
                 lastHtmlTag = currentLine;
             }
             else if (lastHtmlTag.contains("<pre")) {
                 final String currentLineWithPreservedIndent = javadocPortionLinesSplit[index]
                     .substring(1);
 
                 processedLine = NEWLINE + currentLineWithPreservedIndent;
             }
             else {
                 processedLine = INDENT_LEVEL_10 + currentLine;
             }
 
             sink.rawText(processedLine);
         }
 
     }
 
     /**
      * Checks if given line starts with HTML text-formatting tag.
      *
      * @param line line to check on.
      * @return whether given line starts with HTML text-formatting tag.
      */
     public static boolean startsWithTextFormattingHtmlTag(String line) {
         boolean result = false;
 
         for (String tag : HTML_TEXT_FORMAT_TAGS) {
             if (line.startsWith(tag)) {
                 result = true;
                 break;
             }
         }
 
         return result;
     }
 
     /**
      * Gets the description of module from module javadoc.
      *
      * @param moduleJavadoc module javadoc.
      * @return module description.
      */
     public static String getModuleDescription(DetailNode moduleJavadoc) {
         final DetailNode descriptionEndNode = getDescriptionEndNode(moduleJavadoc);
 
         return JavadocMetadataScraperUtil.constructSubTreeText(moduleJavadoc, descriptionEndNode);
     }
 
     /**
      * Gets the end node of the description.
      *
      * @param moduleJavadoc javadoc of module.
      * @return the end index.
      */
     public static DetailNode getDescriptionEndNode(DetailNode moduleJavadoc) {
         final DetailNode descriptionEndNode;
 
         final DetailNode notesStartingNode =
             getNotesSectionStartNode(moduleJavadoc);
 
         if (notesStartingNode != null) {
             descriptionEndNode = notesStartingNode.getPreviousSibling();
         }
         else {
             descriptionEndNode = getModuleSinceVersionTagStartNode(
                                         moduleJavadoc).getPreviousSibling();
         }
 
         return descriptionEndNode;
     }
 
     /**
      * Gets the start node of the Notes section.
      *
      * @param moduleJavadoc javadoc of module.
      * @return start node.
      */
     public static DetailNode getNotesSectionStartNode(DetailNode moduleJavadoc) {
         DetailNode notesStartNode = null;
         DetailNode node = moduleJavadoc.getFirstChild();
 
         while (node != null) {
             if (node.getType() == JavadocCommentsTokenTypes.HTML_ELEMENT) {
                 boolean found = false;
                 if (JavadocUtil.isTag(node, "ul")) {
                     final DetailNode htmlContentNode = JavadocUtil.findFirstToken(
                         node, JavadocCommentsTokenTypes.HTML_CONTENT);
                     if (isStartOfNotesSection(htmlContentNode.getFirstChild())) {
                         notesStartNode = node;
                         found = true;
                     }
                 }
                 else if ((JavadocUtil.isTag(node, "p")
                             || JavadocUtil.isTag(node, "li"))
                             && isStartOfNotesSection(node)) {
                     notesStartNode = node;
                     found = true;
                 }
                 if (found) {
                     break;
                 }
             }
             node = node.getNextSibling();
         }
 
         return notesStartNode;
     }
 
     /**
      * Gets the node representing the start of the {@code @since} version tag
      * in the module's Javadoc.
      *
      * @param moduleJavadoc the root Javadoc node of the module
      * @return the {@code @since} tag start node, or {@code null} if not found
      */
     public static DetailNode getModuleSinceVersionTagStartNode(DetailNode moduleJavadoc) {
         return JavadocUtil.getAllNodesOfType(
                 moduleJavadoc, JavadocCommentsTokenTypes.JAVADOC_BLOCK_TAG).stream()
             .filter(javadocTag -> {
                 return javadocTag.getFirstChild().getType()
                         == JavadocCommentsTokenTypes.SINCE_BLOCK_TAG;
             })
             .findFirst()
             .orElse(null);
     }
 
     /**
      * Gets the Notes section of module from module javadoc.
      *
      * @param moduleJavadoc module javadoc.
      * @return Notes section of module.
      */
     public static String getModuleNotes(DetailNode moduleJavadoc) {
         final String result;
 
         final DetailNode notesStartNode = getNotesSectionStartNode(moduleJavadoc);
 
         if (notesStartNode == null) {
             result = "";
         }
         else {
             final DetailNode notesEndNode = getNotesEndNode(moduleJavadoc);
 
             final String unprocessedNotes =
                     JavadocMetadataScraperUtil.constructSubTreeText(
                         notesStartNode, notesEndNode);
             result = NOTES_LINE_WITH_NEWLINE.matcher(unprocessedNotes).replaceAll("");
         }
 
         return result;
     }
 
     /**
      * Gets the end node of the Notes.
      *
      * @param moduleJavadoc javadoc of module.
      * @return the end index.
      */
     public static DetailNode getNotesEndNode(DetailNode moduleJavadoc) {
         return getModuleSinceVersionTagStartNode(
                 moduleJavadoc).getPreviousSibling();
     }
 
     /**
      * Checks whether property is to contain tokens.
      *
      * @param propertyField property field.
      * @return true if property is to contain tokens, false otherwise.
      */
     public static boolean isPropertySpecialTokenProp(Field propertyField) {
         boolean result = false;
 
         if (propertyField != null) {
             final XdocsPropertyType fieldXdocAnnotation =
                 propertyField.getAnnotation(XdocsPropertyType.class);
 
             result = fieldXdocAnnotation != null
                 && fieldXdocAnnotation.value() == PropertyType.TOKEN_ARRAY;
         }
 
         return result;
     }
 
 }