///////////////////////////////////////////////////////////////////////////////////////////////
   // 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.site;
  
  import java.beans.PropertyDescriptor;
  import java.io.File;
  import java.io.IOException;
  import java.lang.module.ModuleDescriptor.Version;
  import java.lang.reflect.Array;
  import java.lang.reflect.Field;
  import java.lang.reflect.InvocationTargetException;
  import java.lang.reflect.ParameterizedType;
  import java.net.URI;
  import java.nio.file.Files;
  import java.nio.file.Path;
  import java.util.ArrayList;
  import java.util.Arrays;
  import java.util.BitSet;
  import java.util.Collection;
  import java.util.Collections;
  import java.util.HashSet;
  import java.util.List;
  import java.util.Locale;
  import java.util.Map;
  import java.util.Optional;
  import java.util.Set;
  import java.util.TreeMap;
  import java.util.TreeSet;
  import java.util.regex.Pattern;
  import java.util.stream.Collectors;
  import java.util.stream.IntStream;
  import java.util.stream.Stream;
  
  import org.apache.commons.beanutils.PropertyUtils;
  import org.apache.maven.doxia.macro.MacroExecutionException;
  
  import com.puppycrawl.tools.checkstyle.Checker;
  import com.puppycrawl.tools.checkstyle.DefaultConfiguration;
  import com.puppycrawl.tools.checkstyle.ModuleFactory;
  import com.puppycrawl.tools.checkstyle.PackageNamesLoader;
  import com.puppycrawl.tools.checkstyle.PackageObjectFactory;
  import com.puppycrawl.tools.checkstyle.PropertyCacheFile;
  import com.puppycrawl.tools.checkstyle.PropertyType;
  import com.puppycrawl.tools.checkstyle.TreeWalker;
  import com.puppycrawl.tools.checkstyle.TreeWalkerFilter;
  import com.puppycrawl.tools.checkstyle.XdocsPropertyType;
  import com.puppycrawl.tools.checkstyle.api.AbstractCheck;
  import com.puppycrawl.tools.checkstyle.api.AbstractFileSetCheck;
  import com.puppycrawl.tools.checkstyle.api.BeforeExecutionFileFilter;
  import com.puppycrawl.tools.checkstyle.api.CheckstyleException;
  import com.puppycrawl.tools.checkstyle.api.DetailNode;
  import com.puppycrawl.tools.checkstyle.api.Filter;
  import com.puppycrawl.tools.checkstyle.api.JavadocCommentsTokenTypes;
  import com.puppycrawl.tools.checkstyle.checks.javadoc.AbstractJavadocCheck;
  import com.puppycrawl.tools.checkstyle.internal.annotation.PreserveOrder;
  import com.puppycrawl.tools.checkstyle.meta.JavadocMetadataScraperUtil;
  import com.puppycrawl.tools.checkstyle.utils.CommonUtil;
  import com.puppycrawl.tools.checkstyle.utils.JavadocUtil;
  import com.puppycrawl.tools.checkstyle.utils.TokenUtil;
  
  /**
   * Utility class for site generation.
   */
  public final class SiteUtil {
  
      /** The string 'tokens'. */
      public static final String TOKENS = "tokens";
      /** The string 'javadocTokens'. */
      public static final String JAVADOC_TOKENS = "javadocTokens";
      /** The string 'violateExecutionOnNonTightHtml'. */
      public static final String VIOLATE_EXECUTION_ON_NON_TIGHT_HTML =
              "violateExecutionOnNonTightHtml";
      /** The string '.'. */
      public static final String DOT = ".";
      /** The string ','. */
      public static final String COMMA = ",";
      /** The whitespace. */
      public static final String WHITESPACE = " ";
      /** The string ', '. */
      public static final String COMMA_SPACE = COMMA + WHITESPACE;
      /** The string 'TokenTypes'. */
      public static final String TOKEN_TYPES = "TokenTypes";
     /** The path to the TokenTypes.html file. */
     public static final String PATH_TO_TOKEN_TYPES =
             "apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html";
     /** The path to the JavadocTokenTypes.html file. */
     public static final String PATH_TO_JAVADOC_TOKEN_TYPES =
             "apidocs/com/puppycrawl/tools/checkstyle/api/JavadocTokenTypes.html";
     /** The string of JavaDoc module marking 'Since version'. */
     public static final String SINCE_VERSION = "Since version";
     /** The 'Check' pattern at the end of string. */
     public static final Pattern FINAL_CHECK = Pattern.compile("Check$");
     /** The string 'fileExtensions'. */
     public static final String FILE_EXTENSIONS = "fileExtensions";
     /** The string 'charset'. */
     public static final String CHARSET = "charset";
 
     /** Precompiled regex pattern to remove the "Setter to " prefix from strings. */
     private static final Pattern SETTER_PATTERN = Pattern.compile("^Setter to ");
 
     /** The url of the checkstyle website. */
     private static final String CHECKSTYLE_ORG_URL = "https://checkstyle.org/";
     /** The string 'checks'. */
     private static final String CHECKS = "checks";
     /** The string 'naming'. */
     private static final String NAMING = "naming";
     /** The string 'src'. */
     private static final String SRC = "src";
     /** Template file extension. */
     private static final String TEMPLATE_FILE_EXTENSION = ".xml.template";
 
     /** The precompiled pattern for a comma followed by a space. */
     private static final Pattern COMMA_SPACE_PATTERN = Pattern.compile(", ");
 
     /** The string '{}'. */
     private static final String EMPTY_CURLY_BRACES = "{}";
 
     /** The string 'null'. */
     private static final String NULL_STR = "null";
 
     /** Class name and their corresponding parent module name. */
     private static final Map<Class<?>, String> CLASS_TO_PARENT_MODULE = Map.ofEntries(
         Map.entry(AbstractCheck.class, TreeWalker.class.getSimpleName()),
         Map.entry(TreeWalkerFilter.class, TreeWalker.class.getSimpleName()),
         Map.entry(AbstractFileSetCheck.class, Checker.class.getSimpleName()),
         Map.entry(Filter.class, Checker.class.getSimpleName()),
         Map.entry(BeforeExecutionFileFilter.class, Checker.class.getSimpleName())
     );
 
     /** Set of properties that every check has. */
     private static final Set<String> CHECK_PROPERTIES =
             getProperties(AbstractCheck.class);
 
     /** Set of properties that every Javadoc check has. */
     private static final Set<String> JAVADOC_CHECK_PROPERTIES =
             getProperties(AbstractJavadocCheck.class);
 
     /** Set of properties that every FileSet check has. */
     private static final Set<String> FILESET_PROPERTIES =
             getProperties(AbstractFileSetCheck.class);
 
     /**
      * Check and property name.
      */
     private static final String HEADER_CHECK_HEADER = "HeaderCheck.header";
 
     /**
      * Check and property name.
      */
     private static final String REGEXP_HEADER_CHECK_HEADER = "RegexpHeaderCheck.header";
 
     /**
      * The string 'api'.
      */
     private static final String API = "api";
 
     /** Set of properties that are undocumented. Those are internal properties. */
     private static final Set<String> UNDOCUMENTED_PROPERTIES = Set.of(
         "SuppressWithNearbyCommentFilter.fileContents",
         "SuppressionCommentFilter.fileContents"
     );
 
     /** Properties that can not be gathered from class instance. */
     private static final Set<String> PROPERTIES_ALLOWED_GET_TYPES_FROM_METHOD = Set.of(
         // static field (all upper case)
         "SuppressWarningsHolder.aliasList",
         // loads string into memory similar to file
         HEADER_CHECK_HEADER,
         REGEXP_HEADER_CHECK_HEADER,
         // property is an int, but we cut off excess to accommodate old versions
         "RedundantModifierCheck.jdkVersion",
         // until https://github.com/checkstyle/checkstyle/issues/13376
         "CustomImportOrderCheck.customImportOrderRules"
     );
 
     /** Path to main source code folder. */
     private static final String MAIN_FOLDER_PATH = Path.of(
             SRC, "main", "java", "com", "puppycrawl", "tools", "checkstyle").toString();
 
     /** List of files who are superclasses and contain certain properties that checks inherit. */
     private static final List<Path> MODULE_SUPER_CLASS_PATHS = List.of(
         Path.of(MAIN_FOLDER_PATH, CHECKS, NAMING, "AbstractAccessControlNameCheck.java"),
         Path.of(MAIN_FOLDER_PATH, CHECKS, NAMING, "AbstractNameCheck.java"),
         Path.of(MAIN_FOLDER_PATH, CHECKS, "javadoc", "AbstractJavadocCheck.java"),
         Path.of(MAIN_FOLDER_PATH, API, "AbstractFileSetCheck.java"),
         Path.of(MAIN_FOLDER_PATH, API, "AbstractCheck.java"),
         Path.of(MAIN_FOLDER_PATH, CHECKS, "header", "AbstractHeaderCheck.java"),
         Path.of(MAIN_FOLDER_PATH, CHECKS, "metrics", "AbstractClassCouplingCheck.java"),
         Path.of(MAIN_FOLDER_PATH, CHECKS, "whitespace", "AbstractParenPadCheck.java")
     );
 
     /**
      * Private utility constructor.
      */
     private SiteUtil() {
     }
 
     /**
      * Get string values of the message keys from the given check class.
      *
      * @param module class to examine.
      * @return a set of checkstyle's module message keys.
      * @throws MacroExecutionException if extraction of message keys fails.
      */
     public static Set<String> getMessageKeys(Class<?> module)
             throws MacroExecutionException {
         final Set<Field> messageKeyFields = getCheckMessageKeysFields(module);
         final Set<String> messageKeys = new TreeSet<>();
         for (Field field : messageKeyFields) {
             messageKeys.add(getFieldValue(field, module).toString());
         }
         return messageKeys;
     }
 
     /**
      * Gets the check's messages keys.
      *
      * @param module class to examine.
      * @return a set of checkstyle's module message fields.
      *
      */
     private static Set<Field> getCheckMessageKeysFields(Class<?> module) {
         final Set<Field> checkstyleMessages = new HashSet<>();
 
         // get all fields from current class
         final Field[] fields = module.getDeclaredFields();
 
         for (Field field : fields) {
             if (field.getName().startsWith("MSG_")) {
                 checkstyleMessages.add(field);
             }
         }
 
         // deep scan class through hierarchy
         final Class<?> superModule = module.getSuperclass();
 
         if (superModule != null && superModule != Object.class) {
             checkstyleMessages.addAll(getCheckMessageKeysFields(superModule));
         }
 
         return checkstyleMessages;
     }
 
     /**
      * Returns the value of the given field.
      *
      * @param field the field.
      * @param instance the instance of the module.
      * @return the value of the field.
      * @throws MacroExecutionException if the value could not be retrieved.
      */
     public static Object getFieldValue(Field field, Object instance)
             throws MacroExecutionException {
         try {
             Object fieldValue = null;
 
             if (field != null) {
                 // required for package/private classes
                 field.trySetAccessible();
                 fieldValue = field.get(instance);
             }
 
             return fieldValue;
         }
         catch (IllegalAccessException exc) {
             throw new MacroExecutionException("Couldn't get field value", exc);
         }
     }
 
     /**
      * Returns the instance of the module with the given name.
      *
      * @param moduleName the name of the module.
      * @return the instance of the module.
      * @throws MacroExecutionException if the module could not be created.
      */
     public static Object getModuleInstance(String moduleName) throws MacroExecutionException {
         final ModuleFactory factory = getPackageObjectFactory();
         try {
             return factory.createModule(moduleName);
         }
         catch (CheckstyleException exc) {
             throw new MacroExecutionException("Couldn't find class: " + moduleName, exc);
         }
     }
 
     /**
      * Returns the default PackageObjectFactory with the default package names.
      *
      * @return the default PackageObjectFactory.
      * @throws MacroExecutionException if the PackageObjectFactory cannot be created.
      */
     private static PackageObjectFactory getPackageObjectFactory() throws MacroExecutionException {
         try {
             final ClassLoader cl = ViolationMessagesMacro.class.getClassLoader();
             final Set<String> packageNames = PackageNamesLoader.getPackageNames(cl);
             return new PackageObjectFactory(packageNames, cl);
         }
         catch (CheckstyleException exc) {
             throw new MacroExecutionException("Couldn't load checkstyle modules", exc);
         }
     }
 
     /**
      * Construct a string with a leading newline character and followed by
      * the given amount of spaces. We use this method only to match indentation in
      * regular xdocs and have minimal diff when parsing the templates.
      * This method exists until
      * <a href="https://github.com/checkstyle/checkstyle/issues/13426">13426</a>
      *
      * @param amountOfSpaces the amount of spaces to add after the newline.
      * @return the constructed string.
      */
     public static String getNewlineAndIndentSpaces(int amountOfSpaces) {
         return System.lineSeparator() + WHITESPACE.repeat(amountOfSpaces);
     }
 
     /**
      * Returns path to the template for the given module name or throws an exception if the
      * template cannot be found.
      *
      * @param moduleName the module whose template we are looking for.
      * @return path to the template.
      * @throws MacroExecutionException if the template cannot be found.
      */
     public static Path getTemplatePath(String moduleName) throws MacroExecutionException {
         final String fileNamePattern = ".*[\\\\/]"
                 + moduleName.toLowerCase(Locale.ROOT) + "\\..*";
         return getXdocsTemplatesFilePaths()
             .stream()
             .filter(path -> path.toString().matches(fileNamePattern))
             .findFirst()
             .orElse(null);
     }
 
     /**
      * Gets xdocs template file paths. These are files ending with .xml.template.
      * This method will be changed to gather .xml once
      * <a href="https://github.com/checkstyle/checkstyle/issues/13426">#13426</a> is resolved.
      *
      * @return a set of xdocs template file paths.
      * @throws MacroExecutionException if an I/O error occurs.
      */
     public static Set<Path> getXdocsTemplatesFilePaths() throws MacroExecutionException {
         final Path directory = Path.of("src/site/xdoc");
         try (Stream<Path> stream = Files.find(directory, Integer.MAX_VALUE,
                 (path, attr) -> {
                     return attr.isRegularFile()
                             && path.toString().endsWith(TEMPLATE_FILE_EXTENSION);
                 })) {
             return stream.collect(Collectors.toUnmodifiableSet());
         }
         catch (IOException ioException) {
             throw new MacroExecutionException("Failed to find xdocs templates", ioException);
         }
     }
 
     /**
      * Returns the parent module name for the given module class. Returns either
      * "TreeWalker" or "Checker". Returns null if the module class is null.
      *
      * @param moduleClass the module class.
      * @return the parent module name as a string.
      * @throws MacroExecutionException if the parent module cannot be found.
      */
     public static String getParentModule(Class<?> moduleClass)
                 throws MacroExecutionException {
         String parentModuleName = "";
         Class<?> parentClass = moduleClass.getSuperclass();
 
         while (parentClass != null) {
             parentModuleName = CLASS_TO_PARENT_MODULE.get(parentClass);
             if (parentModuleName != null) {
                 break;
             }
             parentClass = parentClass.getSuperclass();
         }
 
         // If parent class is not found, check interfaces
         if (parentModuleName == null || parentModuleName.isEmpty()) {
             final Class<?>[] interfaces = moduleClass.getInterfaces();
             for (Class<?> interfaceClass : interfaces) {
                 parentModuleName = CLASS_TO_PARENT_MODULE.get(interfaceClass);
                 if (parentModuleName != null) {
                     break;
                 }
             }
         }
         if (parentModuleName == null || parentModuleName.isEmpty()) {
             final String message = String.format(Locale.ROOT,
                     "Failed to find parent module for %s", moduleClass.getSimpleName());
             throw new MacroExecutionException(message);
         }
         return parentModuleName;
     }
 
     /**
      * Get a set of properties for the given class that should be documented.
      *
      * @param clss the class to get the properties for.
      * @param instance the instance of the module.
      * @return a set of properties for the given class.
      */
     public static Set<String> getPropertiesForDocumentation(Class<?> clss, Object instance) {
         final Set<String> properties =
                 getProperties(clss).stream()
                         .filter(prop -> {
                             return !isGlobalProperty(clss, prop)
                                     && !isUndocumentedProperty(clss, prop);
                         })
                         .collect(Collectors.toCollection(HashSet::new));
         properties.addAll(getNonExplicitProperties(instance, clss));
         return new TreeSet<>(properties);
     }
 
     /**
      * Gets the since version of the module.
      *
      * @param moduleClassName name of module class.
      * @param modulePath module's path.
      * @return since version of module.
      * @throws MacroExecutionException if an error occurs during processing.
      */
     public static String getModuleSinceVersion(String moduleClassName, Path modulePath)
             throws MacroExecutionException {
         processModule(moduleClassName, modulePath);
         return JavadocScraperResultUtil.getModuleSinceVersion();
     }
 
     /**
      * Get the property details of the module. If the property is not present in the
      * module, then the property details from the superclass(es) is used.
      *
      * <p>Superclass property data is built fresh on every call and never cached
      * statically, to prevent stale data from a previous Maven execution in the
      * same JVM from corrupting results.</p>
      *
      * @param properties the properties of the module.
      * @param moduleName the name of the module.
      * @param modulePath the module file path.
      * @param instance the instance of the module.
      * @return the property details of the module.
      * @throws MacroExecutionException if an error occurs during processing.
      */
     public static Map<String, PropertyDetails> buildPropertyDetails(Set<String> properties,
                                                              String moduleName, Path modulePath,
                                                              Object instance)
             throws MacroExecutionException {
         final Map<String, PropertyDetails> superClassPropertyData = buildSuperClassPropertyData();
         processModule(moduleName, modulePath, instance, properties);
 
         final Map<String, PropertyDetails> currentPropertiesDetails =
                 new TreeMap<>(JavadocScraperResultUtil.getPropertiesDetails());
 
         for (String property : properties) {
             if (!currentPropertiesDetails.containsKey(property)) {
                 processInheritedProperty(currentPropertiesDetails, property,
                         instance, moduleName, superClassPropertyData);
             }
         }
         assertAllPropertiesAreFound(properties, moduleName, currentPropertiesDetails);
         return Collections.unmodifiableMap(currentPropertiesDetails);
     }
 
     /**
      * Processes an inherited property and adds its details to the provided map.
      *
      * @param detailsMap the map to add the property details to.
      * @param property the name of the property.
      * @param instance the module instance.
      * @param moduleName the module name.
      * @param superClassPropertyData the superclass property data built for this invocation.
      * @throws MacroExecutionException if an error occurs.
      */
     private static void processInheritedProperty(
             Map<String, PropertyDetails> detailsMap,
             String property, Object instance,
             String moduleName,
             Map<String, PropertyDetails> superClassPropertyData)
             throws MacroExecutionException {
         final String moduleSince = JavadocScraperResultUtil.getModuleSinceVersion();
         final PropertyDetails inherited = superClassPropertyData.get(property);
         if (inherited != null) {
             final String description = inherited.getDescription();
             final String inheritedSince = inherited.getSinceVersion();
 
             final String since;
             if (inheritedSince.isEmpty()
                     || !moduleSince.isEmpty()
                     && isVersionAtLeast(moduleSince, inheritedSince)) {
                 if (moduleSince.isEmpty()) {
                     since = inheritedSince;
                 }
                 else {
                     since = moduleSince;
                 }
             }
             else {
                 since = inheritedSince;
             }
             final Field field = getField(instance.getClass(), property);
             final PropertyDetails.Builder builder = new PropertyDetails.Builder()
                     .name(property)
                     .description(description)
                     .sinceVersion(since);
             detailsMap.put(property, constructPropertyDetails(builder,
                     instance, field, property, moduleName));
         }
         else if (TOKENS.equals(property)
                 || JAVADOC_TOKENS.equals(property)
                 || VIOLATE_EXECUTION_ON_NON_TIGHT_HTML.equals(property)) {
             final String description = getPropertyDescriptionForXdoc(property, null,
                     moduleName);
             final String since = getPropertySinceVersion(moduleSince, null);
             final Field field = getField(instance.getClass(), property);
             final PropertyDetails.Builder builder = new PropertyDetails.Builder()
                     .name(property)
                     .description(description)
                     .sinceVersion(since);
             detailsMap.put(property, constructPropertyDetails(builder,
                     instance, field, property, moduleName));
         }
     }
 
     /**
      * Assert that each property has a corresponding detail object.
      *
      * @param properties the properties of the module.
      * @param moduleName the name of the module.
      * @param details the details of the properties of the module.
      * @throws MacroExecutionException if an error occurs during processing.
      */
     private static void assertAllPropertiesAreFound(
             Set<String> properties, String moduleName, Map<String, PropertyDetails> details)
             throws MacroExecutionException {
         for (String property : properties) {
             if (!details.containsKey(property)) {
                 throw new MacroExecutionException(String.format(Locale.ROOT,
                         "%s: Missing documentation for property '%s'.", moduleName, property));
             }
         }
     }
 
     /**
      * Builds a fresh map of superclass property data by scraping each superclass file.
      * This method is called once per {@link #buildPropertyDetails} invocation and returns
      * a new local map — it never populates any static field.
      *
      * @return map of property name to PropertyDetails for all known superclasses.
      * @throws MacroExecutionException if an error occurs during processing.
      */
     private static Map<String, PropertyDetails> buildSuperClassPropertyData()
             throws MacroExecutionException {
         final Map<String, PropertyDetails> result = new TreeMap<>();
         for (Path superclassPath : MODULE_SUPER_CLASS_PATHS) {
             final Path fileNamePath = superclassPath.getFileName();
             if (fileNamePath == null) {
                 throw new MacroExecutionException("Invalid superclass path: " + superclassPath);
             }
             final String superclassName = CommonUtil.getFileNameWithoutExtension(
                     fileNamePath.toString());
 
             final String pathString = superclassPath.toString().replace('\\', '/');
             final String marker = "com/puppycrawl/tools/checkstyle/";
             final String classPath = pathString.substring(pathString.indexOf(marker));
             final String classFullName = classPath
                     .substring(0, classPath.lastIndexOf(".java"))
                     .replace('/', '.');
             final Set<String> properties;
             try {
                 final Class<?> superClass = Class.forName(classFullName);
                 final Set<String> setterProperties = new TreeSet<>(getProperties(superClass));
                 if (AbstractFileSetCheck.class.isAssignableFrom(superClass)) {
                     setterProperties.add(FILE_EXTENSIONS);
                 }
                 if (AbstractJavadocCheck.class.isAssignableFrom(superClass)) {
                     setterProperties.add(VIOLATE_EXECUTION_ON_NON_TIGHT_HTML);
                 }
                 properties = setterProperties;
             }
             catch (ClassNotFoundException exc) {
                 throw new MacroExecutionException("Failed to find class: " + classFullName, exc);
             }
 
             processModule(superclassName, superclassPath, null, properties);
             result.putAll(JavadocScraperResultUtil.getPropertiesDetails());
         }
         return result;
     }
 
     /**
      * Scrape the Javadocs of the class and its properties setters.
      *
      * @param moduleName the name of the module.
      * @param modulePath the module Path.
      * @throws MacroExecutionException if an error occurs during processing.
      */
     public static void processModule(String moduleName, Path modulePath)
             throws MacroExecutionException {
         final Object instance = getModuleInstance(moduleName);
         final Set<String> properties = getPropertiesForDocumentation(instance.getClass(),
                 instance);
         processModule(moduleName, modulePath, instance, properties);
     }
 
     /**
      * Scrape the Javadocs of the class and its properties setters with
      * ClassAndPropertiesSettersJavadocScraper.
      *
      * @param moduleName the name of the module.
      * @param modulePath the module Path.
      * @param instance the instance of the module.
      * @param properties the properties of the module.
      * @throws MacroExecutionException if an error occurs during processing.
      */
     private static void processModule(String moduleName, Path modulePath, Object instance,
                                       Set<String> properties)
             throws MacroExecutionException {
         final Path resolvedPath = Path.of("").toAbsolutePath()
                 .resolve(modulePath.toString().replace('\\', '/'))
                 .normalize();
         if (!Files.isRegularFile(resolvedPath)) {
             final String message = String.format(Locale.ROOT,
                     "File %s is not a file. Please check the 'modulePath' property.", modulePath);
             throw new MacroExecutionException(message);
         }
         ClassAndPropertiesSettersJavadocScraper.initialize(moduleName, instance, properties);
         final Checker checker = new Checker();
         checker.setModuleClassLoader(Checker.class.getClassLoader());
         final DefaultConfiguration scraperCheckConfig =
                         new DefaultConfiguration(
                                 ClassAndPropertiesSettersJavadocScraper.class.getName());
         final DefaultConfiguration defaultConfiguration =
                 new DefaultConfiguration("configuration");
         final DefaultConfiguration treeWalkerConfig =
                 new DefaultConfiguration(TreeWalker.class.getName());
         defaultConfiguration.addProperty(CHARSET, "UTF-8");
         defaultConfiguration.addChild(treeWalkerConfig);
         treeWalkerConfig.addChild(scraperCheckConfig);
         try {
             checker.configure(defaultConfiguration);
             final List<File> filesToProcess = List.of(resolvedPath.toFile());
             checker.process(filesToProcess);
             checker.destroy();
         }
         catch (CheckstyleException checkstyleException) {
             final String message = String.format(Locale.ROOT, "Failed processing %s", moduleName);
             throw new MacroExecutionException(message, checkstyleException);
         }
     }
 
     /**
      * Constructs a PropertyDetails object for the given property.
      *
      * @param builder the builder already containing name, description, and since version.
      * @param instance the instance of the module.
      * @param field the field of the property.
      * @param propertyName the name of the property.
      * @param moduleName the name of the module.
      * @return the PropertyDetails object.
      * @throws MacroExecutionException if an error occurs.
      */
     public static PropertyDetails constructPropertyDetails(PropertyDetails.Builder builder,
                                                            Object instance, Field field,
                                                            String propertyName, String moduleName)
             throws MacroExecutionException {
         if (TOKENS.equals(propertyName)) {
             configureTokensDetails(builder, (AbstractCheck) instance);
         }
         else if (JAVADOC_TOKENS.equals(propertyName)) {
             configureJavadocTokensDetails(builder, (AbstractJavadocCheck) instance);
         }
         else {
             configureOtherPropertyDetails(builder, instance, field, propertyName, moduleName);
         }
         return builder.build();
     }
 
     /**
      * Configures the tokens details for a property.
      *
      * @param builder the property details builder.
      * @param check the check instance.
      */
     private static void configureTokensDetails(PropertyDetails.Builder builder,
                                                AbstractCheck check) {
         final int[] requiredTokens = check.getRequiredTokens();
         final int[] acceptableTokens = check.getAcceptableTokens();
         final int[] defaultTokens = check.getDefaultTokens();
         final int[] allTokenIds = TokenUtil.getAllTokenIds();
         if (requiredTokens.length == 0
                 && Arrays.equals(acceptableTokens, allTokenIds)) {
             builder.tokenPropertyType(PropertyDetails.TokenPropertyType.TOKEN_SET);
         }
         else {
             builder.tokenPropertyType(PropertyDetails.TokenPropertyType.TOKEN_SUBSET);
             builder.configurableTokens(getDifference(acceptableTokens,
                     requiredTokens).stream().map(TokenUtil::getTokenName).toList());
         }
         if (Arrays.equals(defaultTokens, allTokenIds)) {
             builder.defaultValueTokens(List.of(TOKEN_TYPES));
         }
         else {
             builder.defaultValueTokens(getDifference(defaultTokens,
                     requiredTokens).stream().map(TokenUtil::getTokenName).toList());
         }
     }
 
     /**
      * Configures the javadoc tokens details for a property.
      *
      * @param builder the property details builder.
      * @param check the javadoc check instance.
      */
     private static void configureJavadocTokensDetails(PropertyDetails.Builder builder,
                                                       AbstractJavadocCheck check) {
         builder.tokenPropertyType(PropertyDetails.TokenPropertyType.JAVADOC_TOKEN_SUBSET);
         builder.configurableTokens(getDifference(check.getAcceptableJavadocTokens(),
                 check.getRequiredJavadocTokens()).stream()
                 .map(JavadocUtil::getTokenName).toList());
         builder.defaultValueTokens(getDifference(check.getDefaultJavadocTokens(),
                 check.getRequiredJavadocTokens()).stream()
                 .map(JavadocUtil::getTokenName).toList());
     }
 
     /**
      * Configures the details for properties other than tokens and javadoc tokens.
      *
      * @param builder the property details builder.
      * @param instance the module instance.
      * @param field the field of the property.
      * @param propertyName the name of the property.
      * @param moduleName the name of the module.
      * @throws MacroExecutionException if an error occurs.
      */
     private static void configureOtherPropertyDetails(PropertyDetails.Builder builder,
                                                       Object instance, Field field,
                                                       String propertyName, String moduleName)
             throws MacroExecutionException {
         final Class<?> fieldClass = getFieldClass(field, propertyName, moduleName, instance);
         final String type;
         if (ModuleJavadocParsingUtil.isPropertySpecialTokenProp(field)) {
             type = "subset of tokens TokenTypes";
         }
         else {
             final String rawType = getType(field, propertyName, moduleName, instance);
             type = simplifyTypeName(rawType);
         }
         builder.type(type);
 
         String defaultValue;
         if (field != null) {
             defaultValue = getDefaultValue(propertyName, field, instance, moduleName);
         }
         else {
             final Class<?> propertyClass = getPropertyClass(propertyName, instance);
             if (propertyClass.isArray()) {
                 defaultValue = EMPTY_CURLY_BRACES;
             }
             else {
                 defaultValue = NULL_STR;
             }
         }
 
         if (defaultValue.isEmpty() && fieldClass.isArray()) {
             defaultValue = EMPTY_CURLY_BRACES;
         }
 
         if (ModuleJavadocParsingUtil.isPropertySpecialTokenProp(field)
                 && !EMPTY_CURLY_BRACES.equals(defaultValue)) {
             builder.defaultValueTokens(Arrays.asList(COMMA_SPACE_PATTERN.split(defaultValue)));
         }
         else {
             builder.defaultValue(defaultValue);
         }
     }
 
     /**
      * Get a set of properties for the given class.
      *
      * @param clss the class to get the properties for.
      * @return a set of properties for the given class.
      */
     public static Set<String> getProperties(Class<?> clss) {
         final Set<String> result = new TreeSet<>();
         final PropertyDescriptor[] propertyDescriptors = PropertyUtils.getPropertyDescriptors(clss);
 
         for (PropertyDescriptor propertyDescriptor : propertyDescriptors) {
             if (propertyDescriptor.getWriteMethod() != null) {
                 result.add(propertyDescriptor.getName());
             }
         }
 
         return result;
     }
 
     /**
      * Checks if the property is a global property. Global properties come from the base classes
      * and are common to all checks. For example id, severity, tabWidth, etc.
      *
      * @param clss the class of the module.
      * @param propertyName the name of the property.
      * @return true if the property is a global property.
      */
     private static boolean isGlobalProperty(Class<?> clss, String propertyName) {
         return AbstractCheck.class.isAssignableFrom(clss)
                     && CHECK_PROPERTIES.contains(propertyName)
                 || AbstractJavadocCheck.class.isAssignableFrom(clss)
                     && JAVADOC_CHECK_PROPERTIES.contains(propertyName)
                 || AbstractFileSetCheck.class.isAssignableFrom(clss)
                     && FILESET_PROPERTIES.contains(propertyName);
     }
 
     /**
      * Checks if the property is supposed to be documented.
      *
      * @param clss the class of the module.
      * @param propertyName the name of the property.
      * @return true if the property is supposed to be documented.
      */
     private static boolean isUndocumentedProperty(Class<?> clss, String propertyName) {
         return UNDOCUMENTED_PROPERTIES.contains(clss.getSimpleName() + DOT + propertyName);
     }
 
     /**
      * Gets properties that are not explicitly captured but should be documented if
      * certain conditions are met.
      *
      * @param instance the instance of the module.
      * @param clss the class of the module.
      * @return the non explicit properties.
      */
     private static Set<String> getNonExplicitProperties(
             Object instance, Class<?> clss) {
         final Set<String> result = new TreeSet<>();
         if (AbstractCheck.class.isAssignableFrom(clss)) {
             final AbstractCheck check = (AbstractCheck) instance;
 
             final int[] acceptableTokens = check.getAcceptableTokens();
             Arrays.sort(acceptableTokens);
             final int[] defaultTokens = check.getDefaultTokens();
             Arrays.sort(defaultTokens);
             final int[] requiredTokens = check.getRequiredTokens();
             Arrays.sort(requiredTokens);
 
             if (!Arrays.equals(acceptableTokens, defaultTokens)
                     || !Arrays.equals(acceptableTokens, requiredTokens)) {
                 result.add(TOKENS);
             }
         }
 
         if (AbstractJavadocCheck.class.isAssignableFrom(clss)) {
             final AbstractJavadocCheck check = (AbstractJavadocCheck) instance;
             result.add(VIOLATE_EXECUTION_ON_NON_TIGHT_HTML);
 
             final int[] acceptableJavadocTokens = check.getAcceptableJavadocTokens();
             Arrays.sort(acceptableJavadocTokens);
             final int[] defaultJavadocTokens = check.getDefaultJavadocTokens();
             Arrays.sort(defaultJavadocTokens);
             final int[] requiredJavadocTokens = check.getRequiredJavadocTokens();
             Arrays.sort(requiredJavadocTokens);
 
             if (!Arrays.equals(acceptableJavadocTokens, defaultJavadocTokens)
                     || !Arrays.equals(acceptableJavadocTokens, requiredJavadocTokens)) {
                 result.add(JAVADOC_TOKENS);
             }
         }
 
         if (AbstractFileSetCheck.class.isAssignableFrom(clss)) {
             result.add(FILE_EXTENSIONS);
         }
         return result;
     }
 
     /**
      * Get the description of the property.
      *
      * @param propertyName the name of the property.
      * @param javadoc the Javadoc of the property setter method.
      * @param moduleName the name of the module.
      * @return the description of the property.
      * @throws MacroExecutionException if the description could not be extracted.
      */
     public static String getPropertyDescriptionForXdoc(
             String propertyName, DetailNode javadoc, String moduleName)
             throws MacroExecutionException {
         final String description;
         if (TOKENS.equals(propertyName)) {
             description = "tokens to check";
         }
         else if (JAVADOC_TOKENS.equals(propertyName)) {
             description = "javadoc tokens to check";
         }
         else if (VIOLATE_EXECUTION_ON_NON_TIGHT_HTML.equals(propertyName)) {
             description = "Control when to print violations if the Javadoc being"
                     + " examined by this check violates the tight html rules defined at"
                     + " <a href=\"" + CHECKSTYLE_ORG_URL
                     + "writingjavadocchecks.html#Tight-HTML_rules\">"
                     + "Tight-HTML Rules</a>.";
         }
         else if (FILE_EXTENSIONS.equals(propertyName)) {
             description = "Specify the file extensions of the files to process.";
         }
         else {
             final String javadocDescription =
                     getDescriptionFromJavadocForXdoc(javadoc, moduleName);
             final String descriptionString = SETTER_PATTERN.matcher(javadocDescription)
                     .replaceFirst("");
 
             if (descriptionString.isEmpty()) {
                 description = "";
             }
             else {
                 final String firstLetterCapitalized = descriptionString.substring(0, 1)
                         .toUpperCase(Locale.ROOT);
                 description = firstLetterCapitalized + descriptionString.substring(1);
             }
         }
         return description;
     }
 
     /**
      * Get the since version of the property.
      *
      * <p>Note: the {@code moduleName} parameter has been removed because it was unused.
      * All call sites have been updated accordingly.</p>
      *
      * @param moduleSince the since version of the module.
      * @param propertyJavadoc the Javadoc of the property setter method.
      * @return the since version of the property.
      */
     public static String getPropertySinceVersion(String moduleSince,
                                                  DetailNode propertyJavadoc) {
         final String sinceVersion;
 
         final Optional<String> specifiedPropertyVersionInPropertyJavadoc =
                 getPropertyVersionFromItsJavadoc(propertyJavadoc);
 
         if (specifiedPropertyVersionInPropertyJavadoc.isPresent()) {
             sinceVersion = specifiedPropertyVersionInPropertyJavadoc.get();
         }
         else {
             String propertySetterSince = null;
             if (propertyJavadoc != null) {
                 propertySetterSince = getSinceVersionFromJavadoc(propertyJavadoc);
             }
 
             if (propertySetterSince != null
                     && (moduleSince == null || moduleSince.isEmpty()
                     || isVersionAtLeast(propertySetterSince, moduleSince))) {
                 sinceVersion = propertySetterSince;
             }
             else {
                 sinceVersion = Optional.ofNullable(moduleSince).orElse("");
             }
         }
 
         return sinceVersion;
     }
 
     /**
      * Extract the property since version from its Javadoc.
      *
      * @param propertyJavadoc the property Javadoc to extract the since version from.
      * @return the Optional of property version specified in its javadoc.
      */
     private static Optional<String> getPropertyVersionFromItsJavadoc(DetailNode propertyJavadoc) {
         Optional<String> result = Optional.empty();
 
         if (propertyJavadoc != null) {
             final Optional<DetailNode> propertyJavadocTag =
                     getPropertySinceJavadocTag(propertyJavadoc);
 
             result = propertyJavadocTag
                     .map(tag -> {
                         return JavadocUtil.findFirstToken(
                                 tag, JavadocCommentsTokenTypes.DESCRIPTION);
                     })
                     .map(description -> {
                         return JavadocUtil.findFirstToken(
                                 description, JavadocCommentsTokenTypes.TEXT);
                     })
                     .map(DetailNode::getText)
                     .map(String::trim);
         }
         return result;
     }
 
     /**
      * Find the propertySince Javadoc tag node in the given property Javadoc.
      *
      * @param javadoc the Javadoc to search.
      * @return the Optional of propertySince Javadoc tag node or null if not found.
      */
     private static Optional<DetailNode> getPropertySinceJavadocTag(DetailNode javadoc) {
         Optional<DetailNode> propertySinceJavadocTag = Optional.empty();
         if (javadoc != null) {
             DetailNode child = javadoc.getFirstChild();
 
             while (child != null) {
                 if (child.getType() == JavadocCommentsTokenTypes.JAVADOC_BLOCK_TAG) {
                     final DetailNode customBlockTag = JavadocUtil.findFirstToken(
                             child, JavadocCommentsTokenTypes.CUSTOM_BLOCK_TAG);
 
                     if (customBlockTag != null
                             && "propertySince".equals(JavadocUtil.findFirstToken(
                             customBlockTag,
                             JavadocCommentsTokenTypes.TAG_NAME).getText())) {
                         propertySinceJavadocTag = Optional.of(customBlockTag);
                         break;
                     }
                 }
                 child = child.getNextSibling();
             }
         }
         return propertySinceJavadocTag;
     }
 
     /**
      * Gets all javadoc nodes of selected type.
      *
      * @param allNodes Nodes to choose from.
      * @param neededType the Javadoc token type to select.
      * @return the List of DetailNodes of selected type.
      */
     public static List<DetailNode> getNodesOfSpecificType(DetailNode[] allNodes, int neededType) {
         return Arrays.stream(allNodes)
             .filter(child -> child.getType() == neededType)
             .toList();
     }
 
     /**
      * Extract the since version from the Javadoc.
      *
      * @param javadoc the Javadoc to extract the since version from.
      * @return the since version of the setter, or {@code null} if not found.
      */
     private static String getSinceVersionFromJavadoc(DetailNode javadoc) {
         String result = null;
 
         if (javadoc != null) {
             final DetailNode sinceJavadocTag = getSinceJavadocTag(javadoc);
             result = Optional.ofNullable(sinceJavadocTag)
                     .map(tag -> {
                         return JavadocUtil.findFirstToken(
                                 tag, JavadocCommentsTokenTypes.DESCRIPTION);
                     })
                     .map(description -> {
                         return JavadocUtil.findFirstToken(
                                 description, JavadocCommentsTokenTypes.TEXT);
                     })
                     .map(DetailNode::getText)
                     .map(String::trim)
                     .orElse(null);
         }
         return result;
     }
 
     /**
      * Find the since Javadoc tag node in the given Javadoc.
      *
      * @param javadoc the Javadoc to search.
      * @return the since Javadoc tag node or null if not found.
      */
     private static DetailNode getSinceJavadocTag(DetailNode javadoc) {
         DetailNode javadocTagWithSince = null;
 
         if (javadoc != null) {
             DetailNode child = javadoc.getFirstChild();
 
             while (child != null) {
                 if (child.getType() == JavadocCommentsTokenTypes.JAVADOC_BLOCK_TAG) {
                     final DetailNode sinceNode = JavadocUtil.findFirstToken(
                             child, JavadocCommentsTokenTypes.SINCE_BLOCK_TAG);
 
                     if (sinceNode != null) {
                         javadocTagWithSince = sinceNode;
                         break;
                     }
                 }
                 child = child.getNextSibling();
             }
         }
 
         return javadocTagWithSince;
     }
 
     /**
      * Returns {@code true} if {@code actualVersion} >= {@code requiredVersion}.
      * Both versions have any trailing "-SNAPSHOT" stripped before comparison.
      *
      * @param actualVersion   e.g. "8.3" or "8.3-SNAPSHOT"
      * @param requiredVersion e.g. "8.3"
      * @return {@code true} if actualVersion exists, and, numerically, is at least requiredVersion
      */
     private static boolean isVersionAtLeast(String actualVersion,
                                             String requiredVersion) {
         final Version actualVersionParsed = Version.parse(actualVersion);
         final Version requiredVersionParsed = Version.parse(requiredVersion);
 
         return actualVersionParsed.compareTo(requiredVersionParsed) >= 0;
     }
 
     /**
      * Get the type of the property.
      *
      * @param field the field to get the type of.
      * @param propertyName the name of the property.
      * @param moduleName the name of the module.
      * @param instance the instance of the module.
      * @return the type of the property.
      * @throws MacroExecutionException if an error occurs during getting the type.
      */
     public static String getType(Field field, String propertyName,
                                  String moduleName, Object instance)
             throws MacroExecutionException {
         final Class<?> fieldClass = getFieldClass(field, propertyName, moduleName, instance);
         return Optional.ofNullable(field)
                 .map(nonNullField -> nonNullField.getAnnotation(XdocsPropertyType.class))
                 .filter(propertyType -> propertyType.value() != PropertyType.TOKEN_ARRAY)
                 .map(propertyType -> propertyType.value().getDescription())
                 .orElseGet(fieldClass::getTypeName);
     }
 
     /**
      * Get the default value of the property.
      *
      * @param propertyName the name of the property.
      * @param field the field to get the default value of.
      * @param classInstance the instance of the class to get the default value of.
      * @param moduleName the name of the module.
      * @return the default value of the property.
      * @throws MacroExecutionException if an error occurs during getting the default value.
      */
     public static String getDefaultValue(String propertyName, Field field,
                                          Object classInstance, String moduleName)
             throws MacroExecutionException {
 
         final String result;
         if (classInstance instanceof PropertyCacheFile) {
             result = "null (no cache file)";
         }
         else {
             final Object value = getFieldValue(field, classInstance);
             final Class<?> fieldClass = getFieldClass(field, propertyName, moduleName,
                     classInstance);
 
             final String fieldValue = getFieldDefaultValue(field, fieldClass, value);
             result = Optional.ofNullable(fieldValue).orElse(NULL_STR);
         }
 
         return result;
     }
 
     /**
      * Gets the string representation of a field's default value based on its type.
      * Returns {@code null} if the field type is not recognized or the value is null.
      *
      * @param field the field to get the default value of.
      * @param fieldClass the class of the field.
      * @param value the current value of the field.
      * @return string form of the default value, or {@code null} if unrecognized.
      */
     private static String getFieldDefaultValue(Field field, Class<?> fieldClass, Object value) {
         String result = getScalarFieldDefaultValue(fieldClass, value);
         if (result == null) {
             result = getArrayFieldDefaultValue(field, fieldClass, value);
         }
         return result;
     }
 
     /**
      * Gets the default value string for scalar (non-array) field types.
      * Returns {@code null} if the field class is not a handled scalar type.
      *
      * @param fieldClass the class of the field.
      * @param value the current value of the field.
      * @return string form of the default value, or {@code null} if not a scalar type.
      */
     private static String getScalarFieldDefaultValue(Class<?> fieldClass, Object value) {
         final String result;
         if (fieldClass == boolean.class
                 || fieldClass == int.class
                 || fieldClass == URI.class
                 || fieldClass == String.class) {
             result = Optional.ofNullable(value).map(Object::toString).orElse(null);
         }
         else if (fieldClass == Pattern.class) {
             result = getPatternDefaultValue(value);
         }
         else if (fieldClass.isEnum()) {
             result = Optional.ofNullable(value)
                     .map(object -> object.toString().toLowerCase(Locale.ENGLISH))
                     .orElse(null);
         }
         else {
             result = null;
         }
         return result;
     }
 
     /**
      * Gets the default value string for array field types.
      * Returns {@code null} if the field class is not a handled array type.
      *
      * @param field the field (used for annotation checks).
      * @param fieldClass the class of the field.
      * @param value the current value of the field.
      * @return string form of the default value, or {@code null} if not an array type.
      */
     private static String getArrayFieldDefaultValue(Field field, Class<?> fieldClass,
                                                     Object value) {
         final String result;
 
         if (fieldClass == int[].class
                 || ModuleJavadocParsingUtil.isPropertySpecialTokenProp(field)) {
             result = getIntArrayPropertyValue(value);
         }
         else {
             result = switch (fieldClass.getSimpleName()) {
                 case "double[]" -> removeSquareBrackets(
                         Arrays.toString((double[]) value).replace(".0", ""));
                 case "String[]" -> getStringArrayPropertyValue(value,
                         hasPreserveOrderAnnotation(field));
                 case "Pattern[]" -> getPatternArrayPropertyValue(value);
                 case "AccessModifierOption[]" -> getAccessModifierDefaultValue(value);
                 case null, default -> null;
             };
         }
 
         return result;
     }
 
     /**
      * Gets the string representation of a Pattern field's default value.
      *
      * @param value the current value of the field.
      * @return string form of the Pattern default value, or {@code null} if value is null.
      */
     private static String getPatternDefaultValue(Object value) {
         final String result;
         if (value == null) {
             result = null;
         }
         else {
             result = value.toString()
                     .replace("\n", "\\n")
                     .replace("\t", "\\t")
                     .replace("\r", "\\r")
                     .replace("\f", "\\f");
         }
         return result;
     }
 
     /**
      * Gets the string representation of an AccessModifierOption array field's default value.
      *
      * @param value the current value of the field.
      * @return string form of the default value.
      */
     private static String getAccessModifierDefaultValue(Object value) {
         final String result;
         if (value != null && Array.getLength(value) > 0) {
             result = removeSquareBrackets(Arrays.toString((Object[]) value));
         }
         else {
             result = "";
         }
         return result;
     }
 
     /**
      * Checks if a field has the {@code PreserveOrder} annotation.
      *
      * @param field the field to check
      * @return true if the field has {@code PreserveOrder} annotation, false otherwise
      */
     private static boolean hasPreserveOrderAnnotation(Field field) {
         return field != null && field.isAnnotationPresent(PreserveOrder.class);
     }
 
     /**
      * Gets the name of the bean property's default value for the Pattern array class.
      *
      * @param fieldValue The bean property's value
      * @return String form of property's default value
      */
     private static String getPatternArrayPropertyValue(Object fieldValue) {
         Object value = fieldValue;
         if (value instanceof Collection<?> collection) {
             value = collection.stream()
                     .map(Pattern.class::cast)
                     .toArray(Pattern[]::new);
         }
 
         String result = "";
         if (value != null && Array.getLength(value) > 0) {
             result = removeSquareBrackets(
                     Arrays.stream((Pattern[]) value)
                     .map(Pattern::pattern)
                     .collect(Collectors.joining(COMMA_SPACE)));
         }
 
         return result;
     }
 
     /**
      * Removes square brackets [ and ] from the given string.
      *
      * @param value the string to remove square brackets from.
      * @return the string without square brackets.
      */
     private static String removeSquareBrackets(String value) {
         return value
                 .replace("[", "")
                 .replace("]", "");
     }
 
     /**
      * Gets the name of the bean property's default value for the string array class.
      *
      * @param value The bean property's value
      * @param preserveOrder whether to preserve the original order
      * @return String form of property's default value
      */
     private static String getStringArrayPropertyValue(Object value, boolean preserveOrder) {
         final String result;
         if (value == null) {
             result = "";
         }
         else {
             try (Stream<?> valuesStream = getValuesStream(value)) {
                 final List<String> stringList = valuesStream
                     .map(String.class::cast)
                     .collect(Collectors.toCollection(ArrayList<String>::new));
 
                 if (preserveOrder) {
                     result = String.join(COMMA_SPACE, stringList);
                 }
                 else {
                     result = stringList.stream()
                     .sorted()
                     .collect(Collectors.joining(COMMA_SPACE));
                 }
             }
         }
         return result;
     }
 
     /**
      * Generates a stream of values from the given value.
      *
      * @param value the value to generate the stream from.
      * @return the stream of values.
      */
     private static Stream<?> getValuesStream(Object value) {
         final Stream<?> valuesStream;
         if (value instanceof Collection<?> collection) {
             valuesStream = collection.stream();
         }
         else {
             final Object[] array = (Object[]) value;
             valuesStream = Arrays.stream(array);
         }
         return valuesStream;
     }
 
     /**
      * Returns the name of the bean property's default value for the int array class.
      *
      * @param value The bean property's value.
      * @return String form of property's default value.
      */
     private static String getIntArrayPropertyValue(Object value) {
         try (IntStream stream = getIntStream(value)) {
             return stream
                     .mapToObj(TokenUtil::getTokenName)
                     .sorted()
                     .collect(Collectors.joining(COMMA_SPACE));
         }
     }
 
     /**
      * Get the int stream from the given value.
      *
      * @param value the value to get the int stream from.
      * @return the int stream.
      * @throws IllegalArgumentException if parameter is null.
      */
     private static IntStream getIntStream(Object value) {
         return switch (value) {
             case null -> throw new IllegalArgumentException("value is null");
             case Collection<?> collection -> collection.stream()
                     .mapToInt(Integer.class::cast);
             case BitSet set -> set.stream();
             default -> Arrays.stream((int[]) value);
         };
     }
 
     /**
      * Gets the class of the given field.
      *
      * @param field the field to get the class of.
      * @param propertyName the name of the property.
      * @param moduleName the name of the module.
      * @param instance the instance of the module.
      * @return the class of the field.
      * @throws MacroExecutionException if an error occurs during getting the class.
      */
     // -@cs[CyclomaticComplexity] Splitting would not make the code more readable
     // -@cs[ForbidWildcardAsReturnType] Implied by design to return different types
     public static Class<?> getFieldClass(Field field, String propertyName,
                                           String moduleName, Object instance)
             throws MacroExecutionException {
         Class<?> result = null;
 
         if (PROPERTIES_ALLOWED_GET_TYPES_FROM_METHOD
                 .contains(moduleName + DOT + propertyName)) {
             result = getPropertyClass(propertyName, instance);
         }
         if (ModuleJavadocParsingUtil.isPropertySpecialTokenProp(field)) {
             result = String[].class;
         }
         if (field != null && result == null) {
             result = field.getType();
         }
 
         if (result == null) {
             throw new MacroExecutionException(
                     "Could not find field " + propertyName + " in class " + moduleName);
         }
 
         if (field != null && (result == List.class || result == Set.class)) {
             result = getParameterizedTypeClass(field);
         }
         else if (result == BitSet.class) {
             result = int[].class;
         }
 
         return result;
     }
 
     /**
      * Gets the class of the parameterized type for the given field.
      *
      * @param field the field to get the parameterized type class of.
      * @return the class of the parameterized type.
      * @throws MacroExecutionException if an error occurs.
      */
     private static Class<?> getParameterizedTypeClass(Field field) throws MacroExecutionException {
         final ParameterizedType type = (ParameterizedType) field.getGenericType();
         final Class<?> parameterClass = (Class<?>) type.getActualTypeArguments()[0];
         final Class<?> result;
 
         if (parameterClass == Integer.class) {
             result = int[].class;
         }
         else if (parameterClass == String.class) {
             result = String[].class;
         }
         else if (parameterClass == Pattern.class) {
             result = Pattern[].class;
         }
         else {
             final String message = "Unknown parameterized type: "
                     + parameterClass.getSimpleName();
             throw new MacroExecutionException(message);
         }
         return result;
     }
 
     /**
      * Gets the class of the given java property.
      *
      * @param propertyName the name of the property.
      * @param instance the instance of the module.
      * @return the class of the java property.
      * @throws MacroExecutionException if an error occurs during getting the class.
      */
     // -@cs[ForbidWildcardAsReturnType] Object is received as param, no prediction on type of field
     public static Class<?> getPropertyClass(String propertyName, Object instance)
             throws MacroExecutionException {
         final Class<?> result;
         try {
             final PropertyDescriptor descriptor = PropertyUtils.getPropertyDescriptor(instance,
                     propertyName);
             result = descriptor.getPropertyType();
         }
         catch (IllegalAccessException | InvocationTargetException | NoSuchMethodException exc) {
             throw new MacroExecutionException("Failed to retrieve property type", exc);
         }
         return result;
     }
 
     /**
      * Get the difference between two lists of tokens.
      *
      * @param tokens the list of tokens to remove from.
      * @param subtractions the tokens to remove.
      * @return the difference between the two lists.
      */
     public static List<Integer> getDifference(int[] tokens, int... subtractions) {
         final Set<Integer> subtractionsSet = Arrays.stream(subtractions)
                 .boxed()
                 .collect(Collectors.toUnmodifiableSet());
         return Arrays.stream(tokens)
                 .boxed()
                 .filter(token -> !subtractionsSet.contains(token))
                 .toList();
     }
 
     /**
      * Gets the field with the given name from the given class.
      *
      * @param fieldClass the class to get the field from.
      * @param propertyName the name of the field.
      * @return the field we are looking for.
      */
     public static Field getField(Class<?> fieldClass, String propertyName) {
         Field result = null;
         Class<?> currentClass = fieldClass;
 
         while (currentClass != Object.class) {
             try {
                 result = currentClass.getDeclaredField(propertyName);
                 result.trySetAccessible();
                 break;
             }
             catch (NoSuchFieldException ignored) {
                 currentClass = currentClass.getSuperclass();
             }
         }
 
         return result;
     }
 
     /**
      * Constructs string with relative link to the provided document.
      *
      * @param moduleName the name of the module.
      * @param document the path of the document.
      * @return relative link to the document.
      * @throws MacroExecutionException if link to the document cannot be constructed.
      */
     public static String getLinkToDocument(String moduleName, String document)
             throws MacroExecutionException {
         final Path templatePath = getTemplatePath(FINAL_CHECK.matcher(moduleName).replaceAll(""));
         if (templatePath == null) {
             throw new MacroExecutionException(
                     String.format(Locale.ROOT,
                             "Could not find template for %s", moduleName));
         }
         final Path templatePathParent = templatePath.getParent();
         if (templatePathParent == null) {
             throw new MacroExecutionException("Failed to get parent path for " + templatePath);
         }
         return templatePathParent
                 .relativize(Path.of(SRC, "site/xdoc", document))
                 .toString()
                 .replace(".xml", ".html")
                 .replace('\\', '/');
     }
 
     /**
      * Get all templates whose content contains properties macro.
      *
      * @return templates whose content contains properties macro.
      * @throws CheckstyleException if file could not be read.
      * @throws MacroExecutionException if template file is not found.
      */
     public static List<Path> getTemplatesThatContainPropertiesMacro()
             throws CheckstyleException, MacroExecutionException {
         final List<Path> result = new ArrayList<>();
         final Set<Path> templatesPaths = getXdocsTemplatesFilePaths();
         for (Path templatePath: templatesPaths) {
             final String content = getFileContents(templatePath);
             final String propertiesMacroDefinition = "<macro name=\"properties\"";
             if (content.contains(propertiesMacroDefinition)) {
                 result.add(templatePath);
             }
         }
         return result;
     }
 
     /**
      * Get file contents as string.
      *
      * @param pathToFile path to file.
      * @return file contents as string.
      * @throws CheckstyleException if file could not be read.
      */
     private static String getFileContents(Path pathToFile) throws CheckstyleException {
         final String content;
         try {
             content = Files.readString(pathToFile);
         }
         catch (IOException ioException) {
             final String message = String.format(Locale.ROOT, "Failed to read file: %s",
                     pathToFile);
             throw new CheckstyleException(message, ioException);
         }
         return content;
     }
 
     /**
      * Get the module name from the file. The module name is the file name without the extension.
      *
      * @param file file to extract the module name from.
      * @return module name.
      */
     public static String getModuleName(File file) {
         final String fullFileName = file.getName();
         return CommonUtil.getFileNameWithoutExtension(fullFileName);
     }
 
     /**
      * Extracts the description from the javadoc detail node. Performs a DFS traversal on the
      * detail node and extracts the text nodes. This description is additionally processed to
      * fit Xdoc format.
      *
      * @param javadoc the Javadoc to extract the description from.
      * @param moduleName the name of the module.
      * @return the description of the setter.
      * @throws MacroExecutionException if the description could not be extracted.
      */
     // -@cs[NPathComplexity] Splitting would not make the code more readable
     // -@cs[CyclomaticComplexity] Splitting would not make the code more readable.
     // -@cs[ExecutableStatementCount] Splitting would not make the code more readable.
     private static String getDescriptionFromJavadocForXdoc(DetailNode javadoc, String moduleName)
             throws MacroExecutionException {
         final List<DetailNode> descriptionNodes = getFirstJavadocParagraphNodes(javadoc);
         final StringBuilder description = new StringBuilder(128);
 
         if (!descriptionNodes.isEmpty()) {
             DetailNode node = descriptionNodes.getFirst();
             final DetailNode endNode = descriptionNodes.getLast();
 
             final DescriptionTraversalState state = new DescriptionTraversalState();
 
             while (node != null) {
                 processDescriptionNode(node, description, state, moduleName);
 
                 DetailNode toVisit = node.getFirstChild();
                 while (node != endNode && toVisit == null) {
                     toVisit = node.getNextSibling();
                     node = node.getParent();
                 }
 
                 node = toVisit;
             }
         }
 
         return description.toString().trim();
     }
 
     /**
      * Processes a single node during description extraction and updates the state.
      * Delegates href-attribute handling and non-href node handling to separate helpers
      * to keep cyclomatic complexity within limits.
      *
      * @param node the current node being visited.
      * @param description the description buffer to append to.
      * @param state the mutable traversal state.
      * @param moduleName the name of the module (used for internal link resolution).
      * @throws MacroExecutionException if an internal link cannot be resolved.
      */
     private static void processDescriptionNode(DetailNode node,
                                                StringBuilder description,
                                                DescriptionTraversalState state,
                                                String moduleName)
             throws MacroExecutionException {
         if (node.getType() == JavadocCommentsTokenTypes.TAG_ATTR_NAME
                 && "href".equals(node.getText())) {
             state.inHrefAttribute = true;
         }
         if (state.inHrefAttribute && node.getType()
                 == JavadocCommentsTokenTypes.ATTRIBUTE_VALUE) {
             processHrefAttributeValue(node, description, state, moduleName);
         }
         else {
             processNonHrefNode(node, description, state);
         }
     }
 
     /**
      * Handles an ATTRIBUTE_VALUE node that belongs to an href attribute.
      *
      * @param node the ATTRIBUTE_VALUE node.
      * @param description the description buffer to append to.
      * @param state the mutable traversal state.
      * @param moduleName the name of the module (used for internal link resolution).
      * @throws MacroExecutionException if an internal link cannot be resolved.
      */
     private static void processHrefAttributeValue(DetailNode node,
                                                   StringBuilder description,
                                                   DescriptionTraversalState state,
                                                   String moduleName)
             throws MacroExecutionException {
         final String href = node.getText();
         if (href.contains(CHECKSTYLE_ORG_URL)) {
             final String internalHref = href.replace(CHECKSTYLE_ORG_URL, "");
             final String path = internalHref.substring(1, internalHref.length() - 1);
             final String relativeHref = getLinkToDocument(moduleName, path);
 
             description.append('\"').append(relativeHref).append('\"');
         }
         else {
             description.append(href);
         }
         state.inHrefAttribute = false;
     }
 
     /**
      * Handles all nodes that are not an href ATTRIBUTE_VALUE, updating HTML-element
      * tracking, text content, and inline-tag (code/literal) tracking.
      *
      * @param node the current node.
      * @param description the description buffer to append to.
      * @param state the mutable traversal state.
      */
     private static void processNonHrefNode(DetailNode node,
                                            StringBuilder description,
                                            DescriptionTraversalState state) {
         processHtmlElementTracking(node, description, state);
         processTextContent(node, description, state);
         processInlineTagTracking(node, description, state);
     }
 
     /**
      * Updates HTML-element open/close tracking and appends closing tag text.
      *
      * @param node the current node.
      * @param description the description buffer to append to.
      * @param state the mutable traversal state.
      */
     private static void processHtmlElementTracking(DetailNode node,
                                                    StringBuilder description,
                                                    DescriptionTraversalState state) {
         if (node.getType() == JavadocCommentsTokenTypes.HTML_ELEMENT) {
             state.inHtmlElement = true;
         }
         if (node.getType() == JavadocCommentsTokenTypes.TAG_CLOSE
                 && node.getParent().getType()
                 == JavadocCommentsTokenTypes.HTML_TAG_END) {
             description.append(node.getText());
             state.inHtmlElement = false;
         }
     }
 
     /**
      * Appends text content from the node, escaping special characters when inside
      * a {@code @code} or {@code @literal} inline tag.
      *
      * @param node the current node.
      * @param description the description buffer to append to.
      * @param state the mutable traversal state.
      */
     private static void processTextContent(DetailNode node,
                                            StringBuilder description,
                                            DescriptionTraversalState state) {
         if (isTextContent(node, state.inHtmlElement)) {
             if (state.inCodeLiteral || state.inLiteralTag) {
                 description.append(node.getText().trim()
                         .replace("&", "&amp;")
                         .replace("<", "&lt;")
                         .replace(">", "&gt;"));
             }
             else {
                 description.append(node.getText());
             }
         }
     }
 
     /**
      * Updates {@code @code} and {@code @literal} inline-tag tracking and appends
      * the opening/closing {@code <code>} HTML tags as needed.
      *
      * @param node the current node.
      * @param description the description buffer to append to.
      * @param state the mutable traversal state.
      */
     private static void processInlineTagTracking(DetailNode node,
                                                  StringBuilder description,
                                                  DescriptionTraversalState state) {
         if (node.getType() == JavadocCommentsTokenTypes.TAG_NAME
                 && node.getParent().getType()
                 == JavadocCommentsTokenTypes.CODE_INLINE_TAG) {
             state.inCodeLiteral = true;
             description.append("<code>");
         }
         if (state.inCodeLiteral
                 && node.getType() == JavadocCommentsTokenTypes.JAVADOC_INLINE_TAG_END) {
             state.inCodeLiteral = false;
             description.append("</code>");
         }
         if (node.getType() == JavadocCommentsTokenTypes.TAG_NAME
                 && node.getParent().getType()
                 == JavadocCommentsTokenTypes.LITERAL_INLINE_TAG) {
             state.inLiteralTag = true;
         }
         if (state.inLiteralTag
                 && node.getType() == JavadocCommentsTokenTypes.JAVADOC_INLINE_TAG_END) {
             state.inLiteralTag = false;
         }
     }
 
     /**
      * Checks whether the node contains text content that should be written to the description.
      *
      * @param node the node to check.
      * @param isInHtmlElement whether we are inside an HTML element.
      * @return true if the node contains text content to write.
      */
     private static boolean isTextContent(DetailNode node, boolean isInHtmlElement) {
         return node.getType() == JavadocCommentsTokenTypes.TEXT
                 || isInHtmlElement && node.getFirstChild() == null
                 && node.getType() != JavadocCommentsTokenTypes.LEADING_ASTERISK;
     }
 
     /**
      * Get 1st paragraph from the Javadoc with no additional processing.
      *
      * @param javadoc the Javadoc to extract first paragraph from.
      * @return first paragraph of javadoc.
      */
     public static String getFirstParagraphFromJavadoc(DetailNode javadoc) {
         final String result;
         final List<DetailNode> firstParagraphNodes = getFirstJavadocParagraphNodes(javadoc);
         if (firstParagraphNodes.isEmpty()) {
             result = "";
         }
         else {
             final DetailNode startNode = firstParagraphNodes.getFirst();
             final DetailNode endNode = firstParagraphNodes.getLast();
             result = JavadocMetadataScraperUtil.constructSubTreeText(startNode, endNode);
         }
         return result;
     }
 
     /**
      * Extracts first paragraph nodes from javadoc.
      *
      * @param javadoc the Javadoc to extract the description from.
      * @return the first paragraph nodes of the setter.
      */
     public static List<DetailNode> getFirstJavadocParagraphNodes(DetailNode javadoc) {
         final List<DetailNode> firstParagraphNodes = new ArrayList<>();
 
         if (javadoc != null) {
             for (DetailNode child = javadoc.getFirstChild();
                  child != null; child = child.getNextSibling()) {
                 if (isEndOfFirstJavadocParagraph(child)) {
                     break;
                 }
                 firstParagraphNodes.add(child);
             }
         }
         return firstParagraphNodes;
     }
 
     /**
      * Determines if the given child index is the end of the first Javadoc paragraph. The end
      * of the description is defined as 4 consecutive nodes of type NEWLINE, LEADING_ASTERISK,
      * NEWLINE, LEADING_ASTERISK. This is an asterisk that is alone on a line. Just like the
      * one below this line.
      *
      * @param child the child to check.
      * @return true if the given child index is the end of the first javadoc paragraph.
      */
     public static boolean isEndOfFirstJavadocParagraph(DetailNode child) {
         final DetailNode nextSibling = child.getNextSibling();
         boolean result = false;
         if (nextSibling != null) {
             final DetailNode secondNextSibling = nextSibling.getNextSibling();
             if (secondNextSibling != null) {
                 final DetailNode thirdNextSibling = secondNextSibling.getNextSibling();
                 if (thirdNextSibling != null) {
                     result = child.getType() == JavadocCommentsTokenTypes.NEWLINE
                             && nextSibling.getType()
                             == JavadocCommentsTokenTypes.LEADING_ASTERISK
                             && secondNextSibling.getType()
                             == JavadocCommentsTokenTypes.NEWLINE
                             && thirdNextSibling.getType()
                             == JavadocCommentsTokenTypes.LEADING_ASTERISK;
                 }
             }
         }
         return result;
     }
 
     /**
      * Simplifies type name just to the name of the class, rather than entire package.
      *
      * @param fullTypeName full type name.
      * @return simplified type name, that is, name of the class.
      */
     public static String simplifyTypeName(String fullTypeName) {
         final int simplifiedStartIndex;
 
         if (fullTypeName.contains("$")) {
             simplifiedStartIndex = fullTypeName.lastIndexOf('$') + 1;
         }
         else {
             simplifiedStartIndex = fullTypeName.lastIndexOf('.') + 1;
         }
 
         return fullTypeName.substring(simplifiedStartIndex);
     }
 
     /**
      * Mutable state bag used during DFS traversal in
      * {@link #getDescriptionFromJavadocForXdoc(DetailNode, String)}.
      * Extracting these flags into a dedicated class reduces the cyclomatic complexity
      * of the traversal method without changing any logic.
      */
     private static final class DescriptionTraversalState {
         /** Whether we are currently inside a {@code @code ...} inline tag. */
         private boolean inCodeLiteral;
         /** Whether we are currently inside a {@code {@literal ...}} inline tag. */
         private boolean inLiteralTag;
         /** Whether we are currently inside an HTML element. */
         private boolean inHtmlElement;
         /** Whether the next ATTRIBUTE_VALUE token is the value of an href attribute. */
         private boolean inHrefAttribute;
 
         /**
          * Creates a new {@code DescriptionTraversalState} instance.
          */
         private DescriptionTraversalState() {
             // no code by default
         }
     }
 
 }