///////////////////////////////////////////////////////////////////////////////////////////////
   // 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.io.File;
  import java.io.IOException;
  import java.io.PrintWriter;
  import java.nio.charset.StandardCharsets;
  import java.nio.file.Files;
  import java.nio.file.Path;
  import java.util.ArrayList;
  import java.util.Arrays;
  import java.util.HashSet;
  import java.util.LinkedHashMap;
  import java.util.LinkedHashSet;
  import java.util.List;
  import java.util.Locale;
  import java.util.Map;
  import java.util.Set;
  import java.util.regex.Matcher;
  import java.util.regex.Pattern;
  import java.util.stream.Collectors;
  
  import javax.xml.parsers.DocumentBuilder;
  import javax.xml.parsers.DocumentBuilderFactory;
  import javax.xml.parsers.ParserConfigurationException;
  
  import org.w3c.dom.Document;
  import org.w3c.dom.Element;
  import org.w3c.dom.NodeList;
  import org.xml.sax.SAXException;
  
  /**
   * Generates {@code search-index.json} from the Checkstyle XDoc source files.
   *
   * <p>This is a plain Java {@code main()} class - no Maven plugin API required.
   * It is invoked by {@code exec-maven-plugin} during the {@code process-classes}
   * phase so the index is ready when Maven Site copies static resources.</p>
   *
   * <p>Output is written as a JSON file. The search widget fetches this file
   * using the fetch API and parses it to populate the search index.</p>
   *
   * <h2>Key design decisions</h2>
   * <ul>
   *   <li><b>No duplicates.</b> Only plain {@code .xml} files are processed for
   *       check/filter/filefilter directories. The {@code .xml.template} and
   *       {@code .xml.vm} siblings are pre-render source files that would produce
   *       identical URLs and duplicate entries. A secondary URL-keyed dedup guard
   *       is also applied across the entire output list.</li>
   *
   *   <li><b>Identifiable example titles.</b> Both {@code -config} and
   *       {@code -code} example paragraphs are indexed.  Their titles use the
   *       pattern {@code "<CheckName>: Example1 [config]"} and
   *       {@code "<CheckName>: Example1 [code]"} so users can distinguish a
   *       configuration snippet from its matching Java code example in search
   *       results.</li>
   *
   *   <li><b>Full general-page indexing.</b> Each meaningful {@code <section>}
   *       in general documentation pages (e.g. {@code config_system_properties},
   *       {@code writingchecks}, {@code cmdline}) is indexed as its own entry
   *       with the full section text used for keyword extraction - not just the
   *       first sentence. This makes page-internal headings discoverable.</li>
   *
   *   <li><b>Disambiguated generic titles.</b> Structural section names that are
   *       repeated across many pages (e.g. "Overview", "Debug", "Contributing")
   *       are prefixed with the page title, yielding e.g.
   *       "Eclipse IDE: Debug" instead of a bare "Debug" that collides with
   *       "IntelliJ IDE: Debug".</li>
   *
   *   <li><b>Junk pages excluded.</b> Release notes, auto-generated style
   *       coverage reports and bare category aggregator stubs are skipped.</li>
   * </ul>
   *
   * <p>Usage (called by exec-maven-plugin in pom.xml):</p>
   * <pre>
   *   java SearchIndexGenerator &lt;xdocsDir&gt; &lt;outputFilePath&gt;
   *   java SearchIndexGenerator src/site/xdoc target/site/search-index.json
   * </pre>
   */
  public final class SearchIndexGenerator {
  
      /** String literal for checks directory. */
     private static final String CHECKS = "checks";
 
     /** String literal for comma. */
     private static final String COMMA_STR = ",";
 
     /** String literal for space. */
     private static final String SPACE = " ";
 
     /** Character literal for space. */
     private static final char SPACE_CHAR = ' ';
 
     /** String literal for colon separator used in disambiguated titles. */
     private static final String TITLE_SEPARATOR = ": ";
 
     /** String literal for ellipsis. */
     private static final String ELLIPSIS = "...";
 
     /** String literal for external general entities feature. */
     private static final String EXTERNAL_GENERAL_ENTITIES =
             "http://xml.org/sax/features/external-general-entities";
 
     /** String literal for external parameter entities feature. */
     private static final String EXTERNAL_PARAMETER_ENTITIES =
             "http://xml.org/sax/features/external-parameter-entities";
 
     /** String literal for General category. */
     private static final String GENERAL = "General";
 
     /** String literal for Example document type. */
     private static final String EXAMPLE_TYPE = "Example";
 
     /** String literal for Property document type. */
     private static final String PROPERTY_TYPE = "Property";
 
     /** String literal for subsection element. */
     private static final String SUBSECTION = "subsection";
 
     /** String literal for name attribute. */
     private static final String NAME_ATTR = "name";
 
     /** String literal for id attribute. */
     private static final String ID_ATTR = "id";
 
     /** String literal for index.xml. */
     private static final String INDEX_XML = "index.xml";
 
     /** Constant for the filters directory. */
     private static final String FILTERS_DIR = "filters";
 
     /** Constant for the filefilters directory. */
     private static final String FILEFILTERS_DIR = "filefilters";
 
     /** Constant for the index file name. */
     private static final String INDEX_HTML = "index.html";
 
     /** String literal for Content. */
     private static final String CONTENT = "Content";
 
     /** String literal for the Examples subsection name. */
     private static final String EXAMPLES_SUBSECTION = "examples";
 
     /** String literal for body element. */
     private static final String BODY = "body";
 
     /** String literal for section element. */
     private static final String SECTION = "section";
 
     /** String literal for title element. */
     private static final String TITLE = "title";
 
     /** String literal for description element. */
     private static final String DESCRIPTION = "description";
 
     /** String literal for anchor separator. */
     private static final String ANCHOR_SEPARATOR = "#";
 
     /** String literal for path separator in URLs. */
     private static final String PATH_SEPARATOR = "/";
 
     /** String literal for the Properties subsection name fragment. */
     private static final String PROPERTIES_FRAGMENT = "propert";
 
     /** Exception message prefix used when an XDoc file fails to parse. */
     private static final String PARSE_FAILURE_MSG = "Failed to parse XDoc file: ";
 
     /**
      * Suffix label appended to example titles for configuration snippets.
      * Yields e.g. "AnnotationLocation: Example1 [config]".
      */
     private static final String EXAMPLE_LABEL_CONFIG = " [config]";
 
     /**
      * Suffix label appended to example titles for Java code examples.
      * Yields e.g. "AnnotationLocation: Example1 [code]".
      */
     private static final String EXAMPLE_LABEL_CODE = " [code]";
 
     /** Magic number for minimum word length. */
     private static final int MIN_WORD_LENGTH = 2;
 
     /** Magic number for maximum keywords. */
     private static final int MAX_KEYWORDS = 15;
 
     /** Magic number for maximum description length. */
     private static final int MAX_DESCRIPTION_LENGTH = 150;
 
     /** Whitespace pattern. */
     private static final Pattern WHITESPACE = Pattern.compile("\\s+");
 
     /** Non-alphanumeric pattern. */
     private static final Pattern NON_ALPHANUMERIC = Pattern.compile("[^a-z0-9]+");
 
     /**
      * Matches only plain {@code .xml} files (not {@code .xml.vm} or
      * {@code .xml.template}).  Used when scanning check/filter/filefilter
      * directories to avoid processing pre-render source templates and
      * producing duplicate index entries.
      */
     private static final Pattern PLAIN_XML = Pattern.compile("\\.xml$");
 
     /**
      * Matches {@code .xml}, {@code .xml.vm} and {@code .xml.template}.
      * Used only for URL building (stripping the extension to produce a
      * {@code .html} path) and for the general-pages scanner where we
      * want to exclude templates by name rather than by extension.
      */
     private static final Pattern DOC_EXTENSION =
             Pattern.compile("\\.xml$|\\.xml\\.vm$|\\.xml\\.template$");
 
     /**
      * Matches {@code config_<category>.xml} files that redirect to check category pages.
      * Captures the category name (e.g. "metrics" from "config_metrics.xml") in group 1.
      */
     private static final Pattern CONFIG_CATEGORY =
           Pattern.compile("^config_(.+)\\.xml$");
 
     /**
      * Matches an example paragraph {@code id} attribute that has a suffix of
      * either {@code -config} or {@code -code}, capturing the base label
      * (e.g. "Example1") in group 1 and the type ("config" or "code") in
      * group 2.
      *
      * <p>Example ids found in XDoc source:</p>
      * <ul>
      *   <li>{@code id="Example1-config"} -&gt; label "Example1", type "config"</li>
      *   <li>{@code id="Example1-code"}   -&gt; label "Example1", type "code"</li>
      * </ul>
      */
     private static final Pattern EXAMPLE_PARAGRAPH_ID =
             Pattern.compile("^(Example\\d+)-(config|code)$");
 
     /**
      * Generic section/subsection names that are structurally repeated across
      * many unrelated general pages (IDE setup guides, writing-* guides, etc).
      * On their own they are meaningless in search results ("Debug" appears
      * identically in eclipse.xml, idea.xml, and netbeans.xml) so when one of
      * these is used as a section title it is always disambiguated with the
      * source page's own title, e.g. "Eclipse IDE: Debug".
      */
     private static final Set<String> GENERIC_SECTION_NAMES = new HashSet<>(Arrays.asList(
             "overview", DESCRIPTION, EXAMPLES_SUBSECTION, "example", "debug",
             "contributing", "limitations", "parameters", "installation"
     ));
 
     /**
      * Display names for the check category subdirectories under
      * {@code checks/}, keyed by lowercase directory name. Every directory
      * that exists under {@code checks/} must have an entry here -
      * {@link #processChecksDirectory} fails fast if one is missing, so a
      * contributor adding a new category is forced to register its display
      * name instead of getting a guessed-at label.
      */
     private static final Map<String, String> CHECKS_CATEGORY_DISPLAY_NAMES = new LinkedHashMap<>();
 
     static {
         CHECKS_CATEGORY_DISPLAY_NAMES.put("annotation", "Annotations");
         CHECKS_CATEGORY_DISPLAY_NAMES.put("blocks", "Block Checks");
         CHECKS_CATEGORY_DISPLAY_NAMES.put("coding", "Coding");
         CHECKS_CATEGORY_DISPLAY_NAMES.put("design", "Class Design");
         CHECKS_CATEGORY_DISPLAY_NAMES.put("header", "Headers");
         CHECKS_CATEGORY_DISPLAY_NAMES.put("imports", "Imports");
         CHECKS_CATEGORY_DISPLAY_NAMES.put("javadoc", "Javadoc Comments");
         CHECKS_CATEGORY_DISPLAY_NAMES.put("metrics", "Metrics");
         CHECKS_CATEGORY_DISPLAY_NAMES.put("misc", "Miscellaneous");
         CHECKS_CATEGORY_DISPLAY_NAMES.put("modifier", "Modifiers");
         CHECKS_CATEGORY_DISPLAY_NAMES.put("naming", "Naming Conventions");
         CHECKS_CATEGORY_DISPLAY_NAMES.put("regexp", "Regexp");
         CHECKS_CATEGORY_DISPLAY_NAMES.put("sizes", "Size Violations");
         CHECKS_CATEGORY_DISPLAY_NAMES.put("whitespace", "Whitespace");
     }
 
     /** Stop words: too generic to be useful as search keywords. */
     private static final Set<String> STOP_WORDS = new HashSet<>(Arrays.asList(
             "a", "an", "the", "and", "or", "of", "to", "in", "is", "it",
             "that", "this", "for", "on", "with", "are", "be", "by", "at",
             "as", "if", "its", "from", "which", "whether", "can", "will",
             "has", "have", "not", "also", "only", "any", "all", "each",
             "more", "than", "when", "then", "into", "such", "use", "used",
             "check", CHECKS, "checkstyle"
     ));
 
     /** Accumulated search index entries. */
     private List<SearchIndexEntry> entries;
 
     /** Deduplication guard for URLs. */
     private Set<String> seenUrls;
 
     /** Prevent instantiation. */
     private SearchIndexGenerator() {
     }
 
     /**
      * Main entry point called by exec-maven-plugin.
      *
      * @param args args[0] = path to src/xdocs, args[1] = path to target/site
      * @throws IOException on file write failure
      * @throws IllegalArgumentException if args are missing
      * @throws IllegalStateException if xdocsDir is missing
      * @noinspectionreason UseOfSystemOutOrSystemErr - main method of a CLI utility
      */
     public static void main(String... args) throws IOException {
         new SearchIndexGenerator().execute(args);
     }
 
     /**
      * Internal execution method to avoid static context for the logger.
      *
      * @param args args[0] = path to src/xdocs, args[1] = output file path
      * @throws IOException on file write failure
      * @throws IllegalArgumentException if args are missing
      * @throws IllegalStateException if xdocsDir is missing
      */
     private void execute(String... args) throws IOException {
         if (args.length < 2) {
             throw new IllegalArgumentException(
                     "Usage: SearchIndexGenerator <xdocsDir> <outputFilePath>");
         }
 
         final Path xdocsPath = Path.of(args[0]);
         final Path outputFilePath = Path.of(args[1]);
         final File xdocsDir = xdocsPath.toFile();
 
         if (!Files.exists(xdocsPath)) {
             final String error = "[SearchIndex] ERROR: xdocsDir not found: "
                     + xdocsPath.toAbsolutePath();
             throw new IllegalStateException(error);
         }
 
         seenUrls = new LinkedHashSet<>();
         entries = new ArrayList<>();
 
         final Path checksPath = xdocsPath.resolve(CHECKS);
         if (Files.exists(checksPath)) {
             processChecksDirectory(checksPath.toFile(), xdocsDir);
         }
 
         final Path filtersPath = xdocsPath.resolve(FILTERS_DIR);
         if (Files.exists(filtersPath)) {
             processDirectory(filtersPath.toFile(), xdocsDir,
                     "Filters", "Filter");
         }
 
         final Path fileFiltersPath = xdocsPath.resolve(FILEFILTERS_DIR);
         if (Files.exists(fileFiltersPath)) {
             processDirectory(fileFiltersPath.toFile(), xdocsDir,
                     "File Filters", "File Filter");
         }
 
         processGeneralPages(xdocsDir);
         writeJson(entries, outputFilePath);
 
     }
 
     /**
      * Walks {@code src/xdocs/checks/} and processes each category subdirectory.
      *
      * <p>Every directory found here must have a corresponding entry in
      * {@link #CHECKS_CATEGORY_DISPLAY_NAMES}; an unmapped directory likely
      * means a new check category was added without registering its display
      * name, so this fails fast rather than guessing a label from the
      * directory name.</p>
      *
      * @param checksDir the checks root directory
      * @param xdocsDir  the xdocs root (used for URL building)
      * @throws IllegalStateException if {@code checksDir} cannot be listed, or
      *         if one of its subdirectories has no entry in
      *         {@link #CHECKS_CATEGORY_DISPLAY_NAMES}
      */
     private void processChecksDirectory(File checksDir, File xdocsDir) {
         final File[] categoryDirs = checksDir.listFiles(File::isDirectory);
         if (categoryDirs == null) {
             throw new IllegalStateException(
                     "Unable to list check category directories under: " + checksDir);
         }
 
         Arrays.sort(categoryDirs);
         for (File categoryDir : categoryDirs) {
             final String dirName = categoryDir.getName().toLowerCase(Locale.ROOT);
             final String category = CHECKS_CATEGORY_DISPLAY_NAMES.get(dirName);
             if (category == null) {
                 throw new IllegalStateException(
                         "No display name registered for check category directory '"
                                 + dirName + "' in CHECKS_CATEGORY_DISPLAY_NAMES. "
                                 + "Please add one.");
             }
             processDirectory(categoryDir, xdocsDir, category, "Check");
         }
     }
 
     /**
      * Processes all <b>plain</b> {@code .xml} files in a directory
      * (non-recursive). {@code index.xml} files and any file whose name ends
      * with {@code .xml.template} or {@code .xml.vm} are skipped.
      *
      * <p>Skipping templates is critical: every check page has a sibling
      * {@code *.xml.template} file that resolves to the <em>same</em> HTML
      * URL. Without this filter both files would be processed, producing two
      * identical (or near-identical) main entries plus doubled example and
      * property entries for every check.</p>
      *
      * <p>For each plain {@code .xml} file, the main check/filter entry,
      * per-example entries (both config and code), and per-property entries
      * are added.</p>
      *
      * @param dir      directory to scan
      * @param xdocsDir xdocs root (used for URL building)
      * @param category category label for all entries in this directory
      * @param type     document type ("Check", "Filter", "File Filter")
      */
     private void processDirectory(File dir, File xdocsDir,
                                   String category, String type) {
         final File[] xmlFiles = dir.listFiles(file -> {
             return file.isFile()
                     && PLAIN_XML.matcher(file.getName()).find()
                     && !INDEX_XML.equals(file.getName());
         });
 
         if (xmlFiles != null) {
             Arrays.sort(xmlFiles);
             for (File xmlFile : xmlFiles) {
                 processXmlFile(xmlFile, xdocsDir, category, type);
             }
         }
     }
 
     /**
      * Parses a single check/filter XDoc file and adds its main, example, and
      * property entries to the index.
      *
      * <p>A parse failure here means the source XDoc itself is malformed,
      * which is a real problem with the documentation rather than something
      * safe to skip - so this fails the build instead of logging a warning
      * and silently continuing.</p>
      *
      * @param xmlFile  the XDoc source file to process
      * @param xdocsDir xdocs root (used for URL building)
      * @param category category label for entries from this file
      * @param type     document type ("Check", "Filter", "File Filter")
      * @throws IllegalStateException if {@code xmlFile} cannot be parsed
      */
     private void processXmlFile(File xmlFile, File xdocsDir, String category, String type) {
         try {
             final Document doc = parseXml(xmlFile);
             final String baseUrl = buildUrl(xmlFile, xdocsDir);
 
             addIfNew(buildMainEntry(doc, xmlFile, category, type, baseUrl));
 
             for (SearchIndexEntry entry : extractExampleEntries(doc, baseUrl, category)) {
                 addIfNew(entry);
             }
             for (SearchIndexEntry entry : extractPropertyEntries(doc, baseUrl, category)) {
                 addIfNew(entry);
             }
         }
         catch (IOException | SAXException | ParserConfigurationException exception) {
             throw new IllegalStateException(PARSE_FAILURE_MSG + xmlFile, exception);
         }
     }
 
     /**
      * Adds entries for the top-level general documentation pages.
      *
      * <p>Each remaining page is indexed per top-level {@code <section>},
      * using the section's full text content for keyword extraction so
      * page-internal headings are fully discoverable. Generic structural
      * section names (see {@link #GENERIC_SECTION_NAMES}) are disambiguated
      * by prefixing the page's own title.</p>
      *
      * @param xdocsDir the xdocs root directory
      */
     private void processGeneralPages(File xdocsDir) {
         final File[] xmlFiles = xdocsDir.listFiles(file -> {
             final String name = file.getName();
             return file.isFile()
                     && PLAIN_XML.matcher(name).find();
         });
 
         if (xmlFiles != null) {
             Arrays.sort(xmlFiles);
             for (File xmlFile : xmlFiles) {
                 processGeneralPage(xmlFile);
             }
         }
     }
 
     /**
      * Parses a single general-documentation XDoc page and adds its
      * per-section entries to the index.
      *
      * <p>A parse failure here means the source XDoc itself is malformed, so
      * this fails the build instead of logging a warning and continuing.</p>
      *
      * @param xmlFile the XDoc source file to process
      * @throws IllegalStateException if {@code xmlFile} cannot be parsed
      */
     private void processGeneralPage(File xmlFile) {
         try {
             for (SearchIndexEntry entry : buildGeneralPageEntries(xmlFile)) {
                 addIfNew(entry);
             }
         }
         catch (IOException | SAXException | ParserConfigurationException exception) {
             throw new IllegalStateException(PARSE_FAILURE_MSG + xmlFile, exception);
         }
     }
 
     /**
      * Builds the main search entry representing an entire check/filter document.
      *
      * @param doc      the parsed XDoc document
      * @param xmlFile  the source file
      * @param category category label for this file's entry
      * @param type     document type ("Check", "Filter", etc.)
      * @param baseUrl  the page url without anchor
      * @return an entry representing the document
      */
     private static SearchIndexEntry buildMainEntry(Document doc, File xmlFile,
                                                    String category, String type,
                                                    String baseUrl) {
         final Element body = requireBody(doc, xmlFile.toString());
         final NodeList sections = body.getElementsByTagName(SECTION);
 
         final String title = extractTitle(doc, xmlFile, sections);
         final String description = extractAggregateDescription(sections);
         final String keywords = extractAggregateKeywords(title, sections);
 
         return new SearchIndexEntry(title, baseUrl, category, type, description, keywords);
     }
 
     /**
      * Builds one search entry per top-level {@code <section>} in a general
      * documentation page, using each section's full text for keyword
      * extraction so that page-internal content is fully discoverable.
      *
      * <p>Generic structural section names (see {@link #GENERIC_SECTION_NAMES})
      * are disambiguated as {@code "<page title>: <section name>"} to avoid
      * collisions across pages (e.g. "Eclipse IDE: Debug" vs
      * "IntelliJ IDE: Debug").</p>
      *
      * @param xmlFile the XDoc source file to parse
      * @return list of entries, one per top-level section found
      * @throws ParserConfigurationException on XML parser setup failure
      * @throws SAXException on XML parse error
      * @throws IOException on file read failure
      */
     private static List<SearchIndexEntry> buildGeneralPageEntries(File xmlFile)
             throws ParserConfigurationException, SAXException, IOException {
         final List<SearchIndexEntry> results = new ArrayList<>();
         final Document doc = parseXml(xmlFile);
         final Element body = requireBody(doc, xmlFile.toString());
         final NodeList sections = body.getElementsByTagName(SECTION);
         final String pageUrl = resolvePageUrl(xmlFile, xmlFile.getParentFile());
         final String pageTitle = derivePageTitle(doc, xmlFile);
 
         if (sections.getLength() == 0) {
             final String fullText = WHITESPACE.matcher(body.getTextContent())
                     .replaceAll(SPACE).trim();
             final String description = extractFirstSentenceOrTruncated(fullText);
             final String keywords = extractKeywordsFromText(
                     pageTitle + SPACE + fullText);
             results.add(new SearchIndexEntry(
                     pageTitle, pageUrl, GENERAL, GENERAL, description, keywords));
         }
         else {
             for (int index = 0; index < sections.getLength(); index++) {
                 final Element section = (Element) sections.item(index);
                 if (body.equals(section.getParentNode())) {
                     final String sectionName = section.getAttribute(NAME_ATTR).trim();
                     if (!sectionName.isEmpty() && !CONTENT.equalsIgnoreCase(sectionName)) {
 
                         final String entryTitle = disambiguateTitle(sectionName, pageTitle);
                         final String anchor = doxiaAnchorFor(sectionName);
                         final String url = pageUrl + ANCHOR_SEPARATOR + anchor;
 
                         final String sectionText = WHITESPACE.matcher(section.getTextContent())
                                 .replaceAll(SPACE).trim();
                         final String description = extractFirstSentenceOrTruncated(sectionText);
                         final String keywords = extractKeywordsFromText(
                                 pageTitle + SPACE + sectionName + SPACE + sectionText);
 
                         results.add(new SearchIndexEntry(
                                 entryTitle, url, GENERAL, GENERAL, description, keywords));
                     }
                 }
             }
         }
 
         return results;
     }
 
     /**
      * Extracts per-example search entries from a check/filter document.
      *
      * <p>Both {@code -config} and {@code -code} example paragraphs are
      * indexed so users can find both the configuration snippet and the
      * corresponding Java code example independently in search results.</p>
      *
      * <p>Titles use the pattern {@code "<CheckName>: Example1 [config]"} and
      * {@code "<CheckName>: Example1 [code]"} to make the type immediately
      * visible in search result listings without needing to open the page.</p>
      *
      * <p>Confirmed XDoc template structure for the Examples subsection:</p>
      * <pre>
      *   &lt;p id="Example1-config"&gt;To configure the check...&lt;/p&gt;
      *   &lt;macro name="example"&gt;&lt;param name="type" value="config"/&gt;&lt;/macro&gt;
      *   &lt;p id="Example1-code"&gt;Example:&lt;/p&gt;
      *   &lt;macro name="example"&gt;&lt;param name="type" value="code"/&gt;&lt;/macro&gt;
      * </pre>
      *
      * @param doc      the parsed XDoc document
      * @param baseUrl  the page url without anchor
      * @param category category label
      * @return list of per-example entries (both config and code); empty if
      *         none found
      */
     private static List<SearchIndexEntry> extractExampleEntries(Document doc,
                                                                 String baseUrl,
                                                                 String category) {
         final List<SearchIndexEntry> exampleEntries = new ArrayList<>();
         final Element body = requireBody(doc, baseUrl);
         final NodeList sections = body.getElementsByTagName(SECTION);
 
         for (int sectionIdx = 0; sectionIdx < sections.getLength(); sectionIdx++) {
             final Element section = (Element) sections.item(sectionIdx);
             final String checkName = section.getAttribute(NAME_ATTR).trim();
             final Element examplesSubsection =
                     findSubsectionByPrefix(section, EXAMPLES_SUBSECTION);
 
             if (examplesSubsection == null) {
                 continue;
             }
 
             final NodeList paragraphs = examplesSubsection.getElementsByTagName("p");
 
             for (int paragraphIndex = 0; paragraphIndex < paragraphs.getLength();
                  paragraphIndex++) {
                 final Element paragraph = (Element) paragraphs.item(paragraphIndex);
                 final SearchIndexEntry entry = buildExampleEntry(
                         paragraph, checkName, baseUrl, category);
                 if (entry != null) {
                     exampleEntries.add(entry);
                 }
             }
         }
 
         return exampleEntries;
     }
 
     /**
      * Builds a single example entry from a paragraph element.
      *
      * @param paragraph the paragraph element containing the example
      * @param checkName the name of the check
      * @param baseUrl the base URL for the page
      * @param category the category label
      * @return a SearchIndexEntry if the paragraph matches the example pattern,
      *         null otherwise
      */
     private static SearchIndexEntry buildExampleEntry(Element paragraph,
                                                        String checkName,
                                                        String baseUrl,
                                                        String category) {
         final String id = paragraph.getAttribute(ID_ATTR);
         final Matcher matcher = EXAMPLE_PARAGRAPH_ID.matcher(id);
         SearchIndexEntry result = null;
 
         if (matcher.matches()) {
             final String exampleLabel = matcher.group(1);
             final String exampleType = matcher.group(2);
 
             final String labelSuffix;
             if ("config".equals(exampleType)) {
                 labelSuffix = EXAMPLE_LABEL_CONFIG;
             }
             else {
                 labelSuffix = EXAMPLE_LABEL_CODE;
             }
 
             final String introText = WHITESPACE
                     .matcher(paragraph.getTextContent())
                     .replaceAll(SPACE).trim();
 
             final String title = checkName + TITLE_SEPARATOR
                     + exampleLabel + labelSuffix;
             final String url = baseUrl + ANCHOR_SEPARATOR + id;
             final String description =
                     truncate(introText, MAX_DESCRIPTION_LENGTH);
             final String keywords = extractKeywordsFromText(
                     checkName + SPACE + exampleLabel
                             + SPACE + exampleType + SPACE + introText);
 
             result = new SearchIndexEntry(
                     title, url, category, EXAMPLE_TYPE,
                     description, keywords);
         }
 
         return result;
     }
 
     /**
      * Extracts per-property search entries from a check/filter document.
      *
      * <p>Each row of the Properties table is indexed under the title
      * {@code "<CheckName>: <propertyName>"} and linked to the property's
      * own anchor on the page.</p>
      *
      * @param doc      the parsed XDoc document
      * @param baseUrl  the page url without anchor
      * @param category category label
      * @return list of per-property entries; empty if none found
      */
     private static List<SearchIndexEntry> extractPropertyEntries(Document doc,
                                                                  String baseUrl,
                                                                  String category) {
         final List<SearchIndexEntry> propertyEntries = new ArrayList<>();
         final Element body = requireBody(doc, baseUrl);
         final NodeList sections = body.getElementsByTagName(SECTION);
 
         for (int sectionIdx = 0; sectionIdx < sections.getLength(); sectionIdx++) {
             final Element section = (Element) sections.item(sectionIdx);
             final Element propertiesSubsection =
                     findSubsectionByPrefix(section, PROPERTIES_FRAGMENT);
 
             if (propertiesSubsection != null) {
                 final String checkName = section.getAttribute(NAME_ATTR).trim();
                 extractPropertiesFromRows(propertiesSubsection, checkName, baseUrl,
                         category, propertyEntries);
             }
         }
 
         return propertyEntries;
     }
 
     /**
      * Extracts property entries from table rows and adds them to the list.
      *
      * @param propertiesSubsection the properties subsection element
      * @param checkName the check name
      * @param baseUrl the page url without anchor
      * @param category category label
      * @param propertyEntries the list to add entries to
      */
     private static void extractPropertiesFromRows(Element propertiesSubsection,
                                                   String checkName,
                                                   String baseUrl,
                                                   String category,
                                                   List<SearchIndexEntry> propertyEntries) {
         final NodeList rows = propertiesSubsection.getElementsByTagName("tr");
 
         for (int rowIdx = 1; rowIdx < rows.getLength(); rowIdx++) {
             final Element row = (Element) rows.item(rowIdx);
             final NodeList cells = row.getElementsByTagName("td");
             if (cells.getLength() >= 2) {
                 processPropertyRow(cells, checkName, baseUrl, category, propertyEntries);
             }
         }
     }
 
     /**
      * Processes a single property row and adds an entry if valid.
      *
      * @param cells the table cells
      * @param checkName the check name
      * @param baseUrl the page url without anchor
      * @param category category label
      * @param propertyEntries the list to add entries to
      */
     private static void processPropertyRow(NodeList cells,
                                            String checkName,
                                            String baseUrl,
                                            String category,
                                            List<SearchIndexEntry> propertyEntries) {
         final String propName = WHITESPACE
                 .matcher(cells.item(0).getTextContent())
                 .replaceAll(SPACE).trim();
 
         if (!propName.isEmpty()) {
             final String propDesc = WHITESPACE
                     .matcher(cells.item(1).getTextContent())
                     .replaceAll(SPACE).trim();
 
             final String title = checkName + TITLE_SEPARATOR + propName;
             final String url = baseUrl + ANCHOR_SEPARATOR + propName;
             final String description = truncate(propDesc, MAX_DESCRIPTION_LENGTH);
             final String keywords = extractKeywordsFromText(
                     checkName + SPACE + propName + SPACE + propDesc);
 
             propertyEntries.add(new SearchIndexEntry(
                     title, url, category, PROPERTY_TYPE,
                     description, keywords));
         }
     }
 
     /**
      * Adds an entry to the output list only if its URL has not been seen
      * before. This is a secondary guard that catches any duplicates that
      * slip through the primary filter (only processing plain {@code .xml}
      * files), e.g. if a check has the same example paragraph id repeated
      * across two sections.
      *
      * @param entry the entry to conditionally add
      */
     private void addIfNew(SearchIndexEntry entry) {
         if (seenUrls.add(entry.url())) {
             entries.add(entry);
         }
     }
 
     /**
      * Finds a subsection within a section whose lowercased name contains the
      * given fragment (e.g. "examples" or "propert" to match "Properties").
      *
      * @param section  the section to search
      * @param fragment lowercase fragment to match against the subsection name
      * @return the matching subsection element, or {@code null} if not found
      */
     private static Element findSubsectionByPrefix(Element section, String fragment) {
         final NodeList subsections = section.getElementsByTagName(SUBSECTION);
         Element result = null;
         for (int index = 0; index < subsections.getLength(); index++) {
             final Element sub = (Element) subsections.item(index);
             if (sub.getAttribute(NAME_ATTR).trim()
                     .toLowerCase(Locale.ROOT).contains(fragment)) {
                 result = sub;
                 break;
             }
         }
         return result;
     }
 
     /**
      * Parses the XML file into a Document with external entity resolution
      * disabled for security.
      *
      * @param xmlFile the XDoc source file
      * @return the parsed Document
      * @throws ParserConfigurationException on XML parser setup failure
      * @throws SAXException on XML parse error
      * @throws IOException on file read failure
      */
     private static Document parseXml(File xmlFile)
             throws ParserConfigurationException, SAXException, IOException {
         final DocumentBuilderFactory factory = DocumentBuilderFactory.newInstance();
         factory.setFeature(EXTERNAL_GENERAL_ENTITIES, false);
         factory.setFeature(EXTERNAL_PARAMETER_ENTITIES, false);
 
         final DocumentBuilder builder = factory.newDocumentBuilder();
         builder.setErrorHandler(null);
 
         final Document doc = builder.parse(xmlFile);
         doc.getDocumentElement().normalize();
         return doc;
     }
 
     /**
      * Returns the document's {@code <body>} element, failing fast if it is
      * absent. Every XDoc page processed by this generator is expected to
      * have one; its absence indicates a malformed source file that should
      * be fixed rather than silently skipped or producing an empty entry.
      *
      * @param doc        the parsed document
      * @param identifier file path or URL used to identify the source in the
      *                   error message
      * @return the body element
      * @throws IllegalStateException if {@code doc} has no {@code <body>} element
      */
     private static Element requireBody(Document doc, String identifier) {
         final NodeList bodies = doc.getElementsByTagName(BODY);
         if (bodies.getLength() == 0) {
             throw new IllegalStateException(
                     "XDoc file is missing a <body> element: " + identifier);
         }
         final Element body = (Element) bodies.item(0);
         if (body == null) {
             throw new IllegalStateException(
                     "XDoc file has a null <body> element: " + identifier);
         }
         return body;
     }
 
     /**
      * Extracts the document title from the {@code <title>} element, falling
      * back to the first non-empty, non-"Content" section name, and finally
      * to a capitalised version of the file name.
      *
      * @param doc      the document
      * @param xmlFile  the source file
      * @param sections the list of sections
      * @return the title string, never empty
      */
     private static String extractTitle(Document doc, File xmlFile, NodeList sections) {
         final NodeList titles = doc.getElementsByTagName(TITLE);
         String title = "";
         if (titles.getLength() > 0) {
             title = titles.item(0).getTextContent().trim();
         }
 
         if ((title.isEmpty() || CONTENT.equalsIgnoreCase(title))
                 && sections.getLength() > 0) {
             final String firstSection =
                     ((Element) sections.item(0)).getAttribute(NAME_ATTR).trim();
             if (!firstSection.isEmpty() && !CONTENT.equalsIgnoreCase(firstSection)) {
                 title = firstSection;
             }
         }
 
         if (title.isEmpty() || CONTENT.equalsIgnoreCase(title)) {
             final String name =
                     xmlFile.getName().replaceFirst(DOC_EXTENSION.pattern(), "");
             title = capitalise(name.replace('_', ' '));
         }
         return title;
     }
 
     /**
      * Aggregates description from sections, taking the first non-empty
      * Description subsection found across all sections in the document.
      *
      * @param sections list of sections
      * @return description string, possibly empty
      */
     private static String extractAggregateDescription(NodeList sections) {
         String description = "";
         for (int index = 0; index < sections.getLength(); index++) {
             description = extractDescription((Element) sections.item(index));
             if (!description.isEmpty()) {
                 break;
             }
         }
         return description;
     }
 
     /**
      * Aggregates keywords from sections using all section text so that the
      * main check entry is discoverable by any term in the document.
      *
      * @param title    the document title
      * @param sections list of sections
      * @return keywords string
      */
     private static String extractAggregateKeywords(String title, NodeList sections) {
         final StringBuilder keywordSource = new StringBuilder(title);
         for (int index = 0; index < sections.getLength(); index++) {
             final Element section = (Element) sections.item(index);
             keywordSource.append(SPACE_CHAR)
                 .append(section.getAttribute(NAME_ATTR))
                 .append(SPACE_CHAR)
                 .append(section.getTextContent());
         }
         return extractKeywordsFromText(keywordSource.toString());
     }
 
     /**
      * Extracts the first sentence of the Description subsection.
      * Returns an empty string if no Description subsection is found.
      *
      * @param section the {@code <section>} element to search
      * @return first sentence of the description, or empty string
      */
     private static String extractDescription(Element section) {
         final Element sub = findSubsectionByPrefix(section, DESCRIPTION);
         String result = "";
         if (sub != null) {
             final String text = WHITESPACE.matcher(sub.getTextContent())
                     .replaceAll(SPACE).trim();
             result = extractFirstSentenceOrTruncated(text);
         }
         return result;
     }
 
     /**
      * Derives a fallback page title from the document's {@code <title>}
      * element or, failing that, from the filename.
      *
      * @param doc     the parsed document
      * @param xmlFile the source file
      * @return a non-empty title string
      */
     private static String derivePageTitle(Document doc, File xmlFile) {
         final NodeList titles = doc.getElementsByTagName(TITLE);
         String title = "";
         if (titles.getLength() > 0) {
             title = titles.item(0).getTextContent().trim();
         }
         if (title.isEmpty()) {
             final String name =
                     xmlFile.getName().replaceFirst(DOC_EXTENSION.pattern(), "");
             title = capitalise(name.replace('_', ' '));
         }
         return title;
     }
 
     /**
      * Disambiguates a section title when it is a generic, structurally
      * repeated header (see {@link #GENERIC_SECTION_NAMES}).
      * Non-generic section names are returned unchanged.
      *
      * @param sectionName the raw section name
      * @param pageTitle   the owning page's own title
      * @return either {@code sectionName} unchanged, or
      *         {@code "<pageTitle>: <sectionName>"} if generic
      */
     private static String disambiguateTitle(String sectionName, String pageTitle) {
         final String result;
         if (GENERIC_SECTION_NAMES.contains(sectionName.toLowerCase(Locale.ROOT))) {
             result = pageTitle + TITLE_SEPARATOR + sectionName;
         }
         else {
             result = sectionName;
         }
         return result;
     }
 
     /**
      * Converts a Doxia {@code <section name="...">} value into the anchor id
      * Doxia generates for it in the rendered HTML by replacing runs of
      * whitespace with single underscores.
      *
      * @param sectionName the raw {@code name} attribute value
      * @return the anchor id Doxia would render for this section name
      */
     private static String doxiaAnchorFor(String sectionName) {
         return WHITESPACE.matcher(sectionName.trim()).replaceAll("_");
     }
 
     /**
      * Returns the first sentence of the given text (up to and including the
      * first period), or the text truncated to {@link #MAX_DESCRIPTION_LENGTH}
      * with an ellipsis if no period is found within range.
      *
      * @param text the source text, already whitespace-normalised
      * @return first sentence or truncated text
      */
     private static String extractFirstSentenceOrTruncated(String text) {
         final String result;
         final int dot = text.indexOf('.');
         if (dot > 0) {
             result = text.substring(0, dot + 1).trim();
         }
         else {
             result = truncate(text, MAX_DESCRIPTION_LENGTH);
         }
         return result;
     }
 
     /**
      * Truncates text to the given max length, appending an ellipsis if
      * truncation occurred.
      *
      * @param text      the text to truncate
      * @param maxLength maximum length before truncation
      * @return original text if short enough, otherwise truncated with ellipsis
      */
     private static String truncate(String text, int maxLength) {
         final String result;
         if (text.length() > maxLength) {
             result = text.substring(0, maxLength) + ELLIPSIS;
         }
         else {
             result = text;
         }
         return result;
     }
 
     /**
      * Builds the root-relative URL for an XDoc file, without any anchor.
      * Always uses forward slashes regardless of OS.
      *
      * @param xmlFile  the source XDoc file
      * @param xdocsDir the xdocs root directory
      * @return root-relative URL string with no anchor
      */
     private static String buildUrl(File xmlFile, File xdocsDir) {
         return xdocsDir.toPath()
                 .relativize(xmlFile.toPath())
                 .toString()
                 .replace(File.separatorChar, '/')
                 .replaceFirst(DOC_EXTENSION.pattern(), ".html");
     }
 
     /**
      * Resolves the correct URL for a general page file. For {@code config_<category>.xml} files
      * that redirect to check category pages, maps to {@code checks/<category>/index.html} instead
      * of the file path.
      *
      * @param xmlFile  the source XDoc file
      * @param xdocsDir the xdocs root directory
      * @return the resolved URL
      */
     private static String resolvePageUrl(File xmlFile, File xdocsDir) {
         String url = buildUrl(xmlFile, xdocsDir);
         final Matcher matcher = CONFIG_CATEGORY.matcher(xmlFile.getName());
         if (matcher.find()) {
             final String category = matcher.group(1);
             if (CHECKS_CATEGORY_DISPLAY_NAMES.containsKey(category)) {
                 url = CHECKS + PATH_SEPARATOR + category + PATH_SEPARATOR + INDEX_HTML;
             }
             else if (FILTERS_DIR.equals(category) || FILEFILTERS_DIR.equals(category)) {
                 url = category + PATH_SEPARATOR + INDEX_HTML;
             }
         }
         return url;
     }
 
     /**
      * Extracts keywords from free-form text by splitting on non-word
      * characters and filtering short and stop words.
      *
      * @param text input text
      * @return comma-separated keyword string (up to {@link #MAX_KEYWORDS} words)
      */
     private static String extractKeywordsFromText(String text) {
         String result = "";
         if (text != null && !text.isEmpty()) {
             result = NON_ALPHANUMERIC.splitAsStream(text.toLowerCase(Locale.ROOT))
                     .filter(word -> {
                         return word.length() >= MIN_WORD_LENGTH
                                 && !STOP_WORDS.contains(word);
                     })
                     .distinct()
                     .limit(MAX_KEYWORDS)
                     .collect(Collectors.joining(COMMA_STR));
         }
         return result;
     }
 
     /**
      * Writes all index entries to the output file.
      *
      * @param indexEntries the list of entries to serialise
      * @param outputFilePath the full path to the output file
      * @throws IOException on file write failure
      */
     private static void writeJson(List<SearchIndexEntry> indexEntries, Path outputFilePath)
             throws IOException {
 
         final Path outputPath = outputFilePath.getParent();
         if (outputPath != null) {
             Files.createDirectories(outputPath);
         }
 
         try (PrintWriter writer = new PrintWriter(Files.newBufferedWriter(
                 outputFilePath, StandardCharsets.UTF_8))) {
             writer.println("[");
 
             final int size = indexEntries.size();
             for (int index = 0; index < size; index++) {
                 final String comma;
                 if (index < size - 1) {
                     comma = COMMA_STR;
                 }
                 else {
                     comma = "";
                 }
                 writer.println("  " + indexEntries.get(index).toJson() + comma);
             }
             writer.println("]");
         }
     }
 
     /**
      * Capitalises the first character of a string.
      *
      * @param input the string to capitalise
      * @return string with first character uppercased, or input unchanged if
      *         empty
      */
     private static String capitalise(String input) {
         String result = input;
         if (input != null && !input.isEmpty()) {
             result = Character.toUpperCase(input.charAt(0)) + input.substring(1);
         }
         return result;
     }
 }