///////////////////////////////////////////////////////////////////////////////////////////////
// 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.checks.naming;

import java.util.regex.Pattern;

import com.puppycrawl.tools.checkstyle.StatelessCheck;
import com.puppycrawl.tools.checkstyle.api.AbstractCheck;
import com.puppycrawl.tools.checkstyle.api.DetailAST;
import com.puppycrawl.tools.checkstyle.api.TokenTypes;
import com.puppycrawl.tools.checkstyle.utils.NullUtil;
import com.puppycrawl.tools.checkstyle.utils.ScopeUtil;

/**
 * <div>
 * Checks that non-constant field names conform to the
 * <a href=
 * "https://google.github.io/styleguide/javaguide.html#s5.2.5-non-constant-field-names">
 * Google Java Style Guide</a> for non-constant field naming.
 * </div>
 *
 * <p>
 * This check enforces Google's specific non-constant field naming requirements:
 * </p>
 * <ul>
 * <li>Non-constant field names must start with a lowercase letter and use uppercase letters
 * for word boundaries.</li>
 * <li>Underscores may be used to separate adjacent numbers (e.g., version
 * numbers like {@code guava33_4_5}), but NOT between letters and digits.</li>
 * </ul>
 *
 * <p>
 * Static fields are skipped because Checkstyle cannot determine type immutability
 * to distinguish constants from non-constants. Fields in interfaces and annotations
 * are also skipped because they are implicitly {@code public static final} (constants)
 * </p>
 *
 * @since 13.3.0
 */
@StatelessCheck
public class GoogleNonConstantFieldNameCheck extends AbstractCheck {

    /**
     * A key is pointing to the violation message text in "messages.properties" file.
     */
    public static final String MSG_KEY_INVALID_FORMAT = "google.non.constant.field.name.format";

    /**
     * Pattern for valid non-constant field name in Google style.
     * Format: start with lowercase, have at least 2 chars, optionally followed by numbering suffix.
     *
     * <p>
     * Explanation:
     * <ul>
     * <li>{@code ^(?![a-z]$)} - Negative lookahead: cannot be single lowercase char</li>
     * <li>{@code (?![a-z][A-Z])} - Negative lookahead: cannot be like "fO"</li>
     * <li>{@code [a-z]} - Must start with lowercase</li>
     * <li>{@code [a-z0-9]*+} - Followed by lowercase or digits</li>
     * <li>{@code (?:[A-Z][a-z0-9]*+)*+} - CamelCase humps (uppercase followed by lowercase)</li>
     * <li>{@code $} - End of string (numbering suffix validated separately)</li>
     * </ul>
     */
    private static final Pattern NON_CONSTANT_FIELD_NAME_PATTERN = Pattern
            .compile("^(?![a-z]$)(?![a-z][A-Z])[a-z][a-z0-9]*+(?:[A-Z][a-z0-9]*+)*+$");

    /**
     * Pattern to strip trailing numbering suffix (underscore followed by digits).
     */
    private static final Pattern NUMBERING_SUFFIX_PATTERN = Pattern.compile("(?:_[0-9]++)+$");

    /**
     * Pattern to detect invalid underscore usage: leading, trailing, consecutive,
     * or between letter-letter, letter-digit, or digit-letter combinations.
     */
    private static final Pattern INVALID_UNDERSCORE_PATTERN =
            Pattern.compile("^_|_$|__|[a-zA-Z]_[a-zA-Z]|[a-zA-Z]_\\d|\\d_[a-zA-Z]");

    @Override
    public int[] getDefaultTokens() {
        return getRequiredTokens();
    }

    @Override
    public int[] getAcceptableTokens() {
        return getRequiredTokens();
    }

    @Override
    public int[] getRequiredTokens() {
        return new int[] {TokenTypes.VARIABLE_DEF};
    }

    @Override
    public void visitToken(DetailAST ast) {
        if (shouldCheckFieldName(ast)) {
            final DetailAST nameAst = getIdent(ast);
            final String fieldName = nameAst.getText();

            validateNonConstantFieldName(nameAst, fieldName);
        }
    }

    /**
     * Returns the IDENT node of the given AST.
     *
     * @param ast the AST node
     * @return the IDENT child node
     */
    private static DetailAST getIdent(DetailAST ast) {
        return NullUtil.notNull(ast.findFirstToken(TokenTypes.IDENT));
    }

    /**
     * Checks if this field should be validated. Returns true for instance fields only.
     * Static fields are excluded because Checkstyle cannot determine type immutability.
     * Local variables and interface/annotation fields are also excluded.
     *
     * @param ast the VARIABLE_DEF AST node
     * @return true if this variable should be checked
     */
    private static boolean shouldCheckFieldName(DetailAST ast) {
        final DetailAST modifiersAST = getModifiers(ast);
        final boolean isStatic =
            modifiersAST.findFirstToken(TokenTypes.LITERAL_STATIC) != null;

        return !isStatic
            && !ScopeUtil.isInInterfaceOrAnnotationBlock(ast)
            && !ScopeUtil.isLocalVariableDef(ast);
    }

    /**
     * Returns the MODIFIERS node of the given AST.
     * The MODIFIERS node is always present in the AST for type, method, and field declarations,
     * even when no modifiers are explicitly written in code (e.g., {@code int x;} still
     * has an empty MODIFIERS node).
     *
     * @param ast the AST node
     * @return the MODIFIERS child node
     */
    private static DetailAST getModifiers(DetailAST ast) {
        return NullUtil.notNull(ast.findFirstToken(TokenTypes.MODIFIERS));
    }

    /**
     * Validates a non-constant field name according to Google style.
     *
     * @param nameAst    the IDENT AST node containing the field name
     * @param fieldName the field name string
     */
    private void validateNonConstantFieldName(DetailAST nameAst, String fieldName) {
        final String nameWithoutNumberingSuffix = NUMBERING_SUFFIX_PATTERN
                .matcher(fieldName).replaceAll("");

        if (INVALID_UNDERSCORE_PATTERN.matcher(fieldName).find()
                || !NON_CONSTANT_FIELD_NAME_PATTERN.matcher(nameWithoutNumberingSuffix).matches()) {
            log(nameAst, MSG_KEY_INVALID_FORMAT, fieldName);
        }
    }
}