/*
    * SPDX-FileCopyrightText: Copyright (c) 2011-2026 Yegor Bugayenko
    * SPDX-License-Identifier: MIT
    */
   package com.qulice.checkstyle;
   
   import java.util.HashMap;
   import java.util.Map;
   import java.util.regex.Matcher;
  import java.util.regex.Pattern;
  
  /**
   * Check the required JavaDoc tag in the lines.
   * <p>Correct format is the following (of a class javadoc):
   *
   * <pre>
   * &#47;**
   *  * This is my new class.
   *  *
   *  * &#64;since 0.3
   *  *&#47;
   * public final class Foo {
   *     &#47;**
   *      * This is my other class.
   *      *
   *      *    &#64;since    0.3
   *      *&#47;
   *     public final class Boo {
   *     // ...
   * </pre>
   *
   * @since 0.23.1
   */
  final class RequiredJavaDocTag {
  
      /**
       * Tag name.
       */
      private final String name;
  
      /**
       * Pattern for searching a tag in a string.
       */
      private final Pattern tag;
  
      /**
       * Pattern for checking the contents of a tag in a string.
       */
      private final Pattern content;
  
      /**
       * Reference to a method for writing a message to the log.
       */
      private final Reporter reporter;
  
      /**
       * Ctor.
       * @param cname Tag name
       * @param ptag Pattern for searching a tag in a string
       * @param patt Pattern for checking the contents of a tag in a string
       * @param rep Reference to a method for writing a message to the log
       * @checkstyle ParameterNumberCheck (3 lines)
       */
      RequiredJavaDocTag(
          final String cname,
          final Pattern ptag,
          final Pattern patt,
          final Reporter rep
      ) {
          this.name = cname;
          this.tag = ptag;
          this.content = patt;
          this.reporter = rep;
      }
  
      /**
       * Check if the tag text matches the format from pattern.
       * @param lines List of all lines
       * @param start Line number where comment starts
       * @param end Line number where comment ends
       */
      void matchTagFormat(
          final String[] lines,
          final int start,
          final int end
      ) {
          final Pattern loose = Pattern.compile(
              String.format("@%s\\b", this.name)
          );
          Integer looseline = null;
          final Map<Integer, String> found = new HashMap<>(1);
          for (int pos = start; pos <= end; pos += 1) {
              final String line = lines[pos];
              final Matcher matcher = this.tag.matcher(line);
              if (RequiredJavaDocTag.tagFound(matcher)) {
                  found.put(pos, matcher.group("cont"));
                  break;
              }
              if (looseline == null && loose.matcher(line).find()) {
                 looseline = pos;
             }
         }
         if (found.isEmpty()) {
             this.logMissing(start, looseline);
         } else {
             this.logMismatches(found);
         }
     }
 
     /**
      * Log either "missing" or "malformed" depending on whether a loose
      * match was found in the comment.
      * @param start Line number where the comment starts
      * @param looseline Line number where a loose match was found, or
      *  {@code null} if none was found
      */
     private void logMissing(final int start, final Integer looseline) {
         if (looseline == null) {
             this.reporter.log(
                 start + 1,
                 "Missing ''@{0}'' tag in class/interface comment",
                 this.name
             );
         } else {
             this.reporter.log(
                 looseline + 1,
                 "Malformed ''@{0}'' tag, expected '' * @{0} <value>'' format",
                 this.name
             );
         }
     }
 
     /**
      * Log a violation for every tag whose text does not match the
      * configured pattern.
      * @param found Map of line number to tag text
      */
     private void logMismatches(final Map<Integer, String> found) {
         for (final Map.Entry<Integer, String> item : found.entrySet()) {
             if (!this.content.matcher(item.getValue()).matches()) {
                 this.reporter.log(
                     item.getKey() + 1,
                     "Tag text ''{0}'' does not match the pattern ''{1}''",
                     item.getValue(),
                     this.content.toString()
                 );
             }
         }
     }
 
     /**
      * Finds the tag name and the following sentences.
      * @param matcher Tag name matcher
      * @return True if the tag and its clauses are found
      */
     private static boolean tagFound(final Matcher matcher) {
         return matcher.matches()
             && !RequiredJavaDocTag.empty(matcher.group("name"))
             && !RequiredJavaDocTag.empty(matcher.group("cont"));
     }
 
     /**
      * Checks for an empty string.
      * @param str Line to check
      * @return True if str is empty
      */
     private static boolean empty(final String str) {
         return str == null || str.chars().allMatch(Character::isWhitespace);
     }
 
     /**
      * Logger.
      * @see com.puppycrawl.tools.checkstyle.api.AbstractCheck#log(int, String, Object...)
      * @since 0.23.1
      */
     @FunctionalInterface
     interface Reporter {
 
         /**
          * Log a message that has no column information.
          * @param line The line number where the audit event was found
          * @param msg The message that describes the audit event
          * @param args The details of the message
          * @see java.text.MessageFormat
          */
         void log(int line, String msg, Object... args);
     }
 }