/*
    * SPDX-FileCopyrightText: Copyright (c) 2011-2026 Yegor Bugayenko
    * SPDX-License-Identifier: MIT
    */
   package com.qulice.checkstyle;
   
   import com.puppycrawl.tools.checkstyle.api.AbstractCheck;
   import com.puppycrawl.tools.checkstyle.api.DetailAST;
   import com.puppycrawl.tools.checkstyle.api.TokenTypes;
  import java.util.ArrayList;
  import java.util.Arrays;
  import java.util.Collection;
  import java.util.List;
  import java.util.regex.Pattern;
  
  /**
   * Check that the class/interface javadoc does not contain prohibited
   * {@code author} or {@code version} tags and has a properly formatted
   * {@code since} tag.
   *
   * <p>Correct format is the following (of a class javadoc):</p>
   *
   * <pre>
   * &#47;**
   *  * This is my new class.
   *  *
   *  * &#64;since 0.3
   *  *&#47;
   * public final class Foo {
   *     // ...
   * </pre>
   *
   * @since 0.3
   */
  public final class JavadocTagsCheck extends AbstractCheck {
  
      /**
       * Javadoc tags that are not allowed.
       */
      private static final Collection<String> PROHIBITED =
          Arrays.asList("author", "version");
  
      /**
       * Map of tag and its pattern.
       */
      private final List<RequiredJavaDocTag> required;
  
      /**
       * Default constructor.
       */
      public JavadocTagsCheck() {
          this.required = new ArrayList<>(1);
      }
  
      @Override
      public int[] getDefaultTokens() {
          return new int[]{
              TokenTypes.CLASS_DEF,
              TokenTypes.INTERFACE_DEF,
          };
      }
  
      @Override
      public int[] getAcceptableTokens() {
          return this.getDefaultTokens();
      }
  
      @Override
      public int[] getRequiredTokens() {
          return this.getDefaultTokens();
      }
  
      @Override
      public void init() {
          this.required.add(
              new RequiredJavaDocTag(
                  "since",
                  Pattern.compile("(?<name>^ +\\* +@since)( +)(?<cont>.*)"),
                  Pattern.compile(
                  "^\\d+(\\.\\d+){1,2}(\\.[0-9A-Za-z-]+(\\.[0-9A-Za-z-]+)*)?$"
                  ),
                  this::log
              )
          );
      }
  
      @Override
      public void visitToken(final DetailAST ast) {
          final String[] lines = this.getLines();
          final int start = ast.getLineNo();
          final int cstart = JavadocTagsCheck.findCommentStart(lines, start);
          final int cend = JavadocTagsCheck.findCommentEnd(lines, start);
          if (cend > cstart && cstart >= 0) {
              for (final String tag : JavadocTagsCheck.PROHIBITED) {
                  this.findProhibited(lines, start, cstart, cend, tag);
              }
              for (final RequiredJavaDocTag tag : this.required) {
                  tag.matchTagFormat(lines, cstart, cend);
              }
         } else {
             this.log(0, "Problem finding class/interface comment");
         }
     }
 
     private static int findTrimmedTextUp(
         final String[] lines,
         final int start,
         final String text
     ) {
         int found = -1;
         for (int pos = start - 1; pos >= 0; pos -= 1) {
             if (lines[pos].trim().equals(text)) {
                 found = pos;
                 break;
             }
         }
         return found;
     }
 
     private static int findCommentStart(final String[] lines, final int start) {
         return JavadocTagsCheck.findTrimmedTextUp(lines, start, "/**");
     }
 
     private static int findCommentEnd(final String[] lines, final int start) {
         return JavadocTagsCheck.findTrimmedTextUp(lines, start, "*/");
     }
 
     private void findProhibited(
         final String[] lines,
         final int start,
         final int cstart,
         final int cend,
         final String tag
     ) {
         final List<Integer> found =
             this.findTagLineNum(lines, cstart, cend, tag);
         if (!found.isEmpty()) {
             this.log(
                 start + 1,
                 "Prohibited ''@{0}'' tag in class/interface comment",
                 tag
             );
         }
     }
 
     private List<Integer> findTagLineNum(
         final String[] lines,
         final int start,
         final int end,
         final String tag
     ) {
         final String prefix = String.format(" * @%s ", tag);
         final List<Integer> found = new ArrayList<>(1);
         for (int pos = start; pos <= end; pos += 1) {
             final String line = lines[pos];
             if (line.contains(String.format("@%s ", tag))) {
                 if (!line.trim().startsWith(prefix.trim())) {
                     this.log(
                         start + pos + 1,
                         "Line with ''@{0}'' does not start with a ''{1}''",
                         tag,
                         prefix
                     );
                     break;
                 }
                 found.add(pos);
             }
         }
         return found;
     }
 }