/*
    * 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;
  
  /**
   * Check for text on the first line of a multi-line Javadoc.
   *
   * <p>You can't have a description on the same line as the opening
   * {@code /**}. Either keep the whole Javadoc on a single line, or move
   * the text to a new line under the opening.</p>
   *
   * <p>The following red line will be reported as a violation.</p>
   * <pre>
   * <span style="color:red" >&#47;** Some text</span>
   *  *&#47;
   * public void method() {
   * }
   * </pre>
   *
   * @since 0.24.1
   */
  public final class JavadocFirstLineCheck extends AbstractCheck {
  
      /**
       * Default constructor.
       */
      public JavadocFirstLineCheck() {
          // nothing to initialize
      }
  
      @Override
      public int[] getDefaultTokens() {
          return new int[] {
              TokenTypes.PACKAGE_DEF,
              TokenTypes.CLASS_DEF,
              TokenTypes.INTERFACE_DEF,
              TokenTypes.ANNOTATION_DEF,
              TokenTypes.ANNOTATION_FIELD_DEF,
              TokenTypes.ENUM_DEF,
              TokenTypes.ENUM_CONSTANT_DEF,
              TokenTypes.VARIABLE_DEF,
              TokenTypes.CTOR_DEF,
              TokenTypes.METHOD_DEF,
          };
      }
  
      @Override
      public int[] getAcceptableTokens() {
          return this.getDefaultTokens();
      }
  
      @Override
      public int[] getRequiredTokens() {
          return this.getDefaultTokens();
      }
  
      @Override
      public void visitToken(final DetailAST ast) {
          final String[] lines = this.getLines();
          final int start = JavadocFirstLineCheck.findOpeningLine(
              lines, ast.getLineNo() - 1
          );
          if (start >= 0 && JavadocFirstLineCheck.belongsToNode(ast, start)
              && JavadocFirstLineCheck.hasTextAfterOpening(lines[start])
              && !JavadocFirstLineCheck.hasClosingOnSameLine(lines[start])) {
              this.log(start + 1, "No text allowed on the first line of Javadoc");
          }
      }
  
      private static int findOpeningLine(final String[] lines, final int below) {
          int found = -1;
          for (int pos = below - 1; pos >= 0; pos -= 1) {
              final String trimmed = lines[pos].trim();
              if (trimmed.startsWith("/**")) {
                  found = pos;
                  break;
              }
              if (!trimmed.isEmpty() && !trimmed.startsWith("*")
                  && !trimmed.endsWith("*/")) {
                  break;
              }
          }
          return found;
      }
  
      private static boolean belongsToNode(final DetailAST node, final int start) {
          final DetailAST previous = node.getPreviousSibling();
          boolean owns = true;
          if (previous != null) {
              owns = start + 1 > previous.getLineNo();
          }
          return owns;
      }
 
     private static boolean hasTextAfterOpening(final String line) {
         final String trimmed = line.trim();
         final String rest = trimmed.substring("/**".length()).trim();
         return !rest.isEmpty() && !"/".equals(rest);
     }
 
     private static boolean hasClosingOnSameLine(final String line) {
         return line.trim().endsWith("*/");
     }
 }