///////////////////////////////////////////////////////////////////////////////////////////////
// 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.coding;

import java.util.ArrayDeque;
import java.util.ArrayList;
import java.util.Deque;
import java.util.HashMap;
import java.util.HashSet;
import java.util.List;
import java.util.Map;
import java.util.Set;
import java.util.regex.Pattern;
import java.util.stream.Collectors;

import com.puppycrawl.tools.checkstyle.FileStatefulCheck;
import com.puppycrawl.tools.checkstyle.api.AbstractCheck;
import com.puppycrawl.tools.checkstyle.api.DetailAST;
import com.puppycrawl.tools.checkstyle.api.FullIdent;
import com.puppycrawl.tools.checkstyle.api.TokenTypes;
import com.puppycrawl.tools.checkstyle.utils.AnnotationUtil;
import com.puppycrawl.tools.checkstyle.utils.CommonUtil;

/**
 * <div>
 * Check that a private field is declared, but never used. Fields with any other
 * visibility (package-private, protected, or public), including those declared in
 * an implicitly declared class (compact source file), are not checked.
 * </div>
 *
 * @since 14.1.0
 */
@FileStatefulCheck
public class UnusedPrivateFieldCheck extends AbstractCheck {

    /**
     * A key is pointing to the warning message text in "messages.properties".
     */
    public static final String MSG_PRIVATE_FIELD = "unused.private.field";

    /**
     * Stack of private field maps, one per class nesting level.
     */
    private final Deque<Map<String, DetailAST>> privateFields = new ArrayDeque<>();

    /**
     * Stack of currently open enclosing type names.
     */
    private final Deque<String> enclosingTypeNames = new ArrayDeque<>();

    /**
     * Recorded field-name usage occurrences.
     */
    private final List<FieldUsage> fieldUsages = new ArrayList<>();

    /**
     * Global set of field names accessed.
     */
    private final Set<String> globalUsedFields = new HashSet<>();

    /**
     * Accumulated pending fields, reported at finishTree.
     */
    private final List<PendingField> pendingFields = new ArrayList<>();

    /**
     * Scope stack tracking local variable and parameter names per block.
     */
    private final Deque<Map<String, String>> scopeStack = new ArrayDeque<>();

    /**
     * Snapshots of scope stack saved when entering a nested class,
     * restored when leaving it.
     */
    private final Deque<Deque<Map<String, String>>> scopeStackSnapshots = new ArrayDeque<>();

    /**
     * Recorded field-name accesses on a qualifier.
     */
    private final List<TypedUsage> typedUsages = new ArrayList<>();

    /**
     * Each class's private fields, keyed by simple type name, populated once
     * a class's OBJBLOCK closes. Used to resolve {@link #typedUsages}.
     */
    private final Map<String, Map<String, DetailAST>> privateFieldsByType = new HashMap<>();

    /**
     * Specify annotations canonical names which ignore variables in consideration.
     * A field is ignored either when the field itself carries a matching annotation,
     * or when its enclosing class, interface, enum, or record carries one (e.g. a
     * class-level Lombok {@code @Getter}).
     */
    private Set<String> ignoreAnnotationCanonicalNames = new HashSet<>(Set.of("java.io.Serial"));

    /**
     * Specify a regular expression pattern for field names to ignore.
     */
    private Pattern ignoredFieldPattern = Pattern.compile("serialVersionUID");

    /**
     * Set of ignore annotations short names.
     */
    private Set<String> ignoreAnnotationShortNames = new HashSet<>();

    /**
     * Creates a new {@code UnusedPrivateFieldCheck} instance with default values.
     *
     */
    public UnusedPrivateFieldCheck() {
        // default constructor
    }

    /**
     * Setter to specify annotations canonical names which ignore variables in consideration.
     *
     * @param annotationNames array of ignore annotations canonical names.
     * @since 14.1.0
     */
    public void setIgnoreAnnotationCanonicalNames(String... annotationNames) {
        ignoreAnnotationCanonicalNames = Set.of(annotationNames);
    }

    /**
     * Setter to specify a regular expression pattern for field names to ignore, even
     * if they otherwise satisfy this check's detection of an unused private field.
     * Note this replaces the default value entirely — to keep {@code serialVersionUID}
     * ignored alongside your own pattern, include it explicitly, e.g.
     * {@code ^(serialVersionUID|LOG|LOGGER)$}.
     *
     * @param pattern regular expression pattern for field names to ignore.
     * @since 14.1.0
     */
    public void setIgnoredFieldPattern(Pattern pattern) {
        ignoredFieldPattern = pattern;
    }

    @Override
    public int[] getAcceptableTokens() {
        return new int[] {
            TokenTypes.IMPORT,
            TokenTypes.OBJBLOCK,
            TokenTypes.VARIABLE_DEF,
            TokenTypes.PARAMETER_DEF,
            TokenTypes.PARAMETERS,
            TokenTypes.SLIST,
            TokenTypes.IDENT,
            TokenTypes.METHOD_DEF,
            TokenTypes.CTOR_DEF,
            TokenTypes.LAMBDA,
            TokenTypes.LITERAL_FOR,
            TokenTypes.LITERAL_CATCH,
        };
    }

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

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

    @Override
    public void beginTree(DetailAST rootAST) {
        privateFields.clear();
        enclosingTypeNames.clear();
        fieldUsages.clear();
        globalUsedFields.clear();
        pendingFields.clear();
        scopeStack.clear();
        scopeStackSnapshots.clear();
        typedUsages.clear();
        privateFieldsByType.clear();
        ignoreAnnotationShortNames = ignoreAnnotationCanonicalNames.stream()
                .map(CommonUtil::baseClassName)
                .collect(Collectors.toCollection(HashSet::new));
    }

    @Override
    public void visitToken(DetailAST ast) {
        switch (ast.getType()) {
            case TokenTypes.OBJBLOCK -> {
                privateFields.push(new HashMap<>());
                scopeStackSnapshots.push(new ArrayDeque<>(scopeStack));
                scopeStack.clear();
                final DetailAST typeDef = ast.getParent();
                final DetailAST nameIdent = typeDef.findFirstToken(TokenTypes.IDENT);
                if (nameIdent == null) {
                    enclosingTypeNames.push("");
                }
                else {
                    enclosingTypeNames.push(nameIdent.getText());
                }
            }
            case TokenTypes.PARAMETERS, TokenTypes.SLIST, TokenTypes.LITERAL_FOR,
                 TokenTypes.LITERAL_CATCH -> scopeStack.push(new HashMap<>());
            case TokenTypes.PARAMETER_DEF -> {
                final DetailAST ident = ast.findFirstToken(TokenTypes.IDENT);
                if (ident != null) {
                    scopeStack.peek().put(ident.getText(), resolveDeclaredTypeName(ast));
                }
            }
            case TokenTypes.VARIABLE_DEF -> handleVariableDef(ast);
            case TokenTypes.IDENT -> handleIdent(ast);
            default -> {
                // no action needed for other token types
            }
        }
    }

    @Override
    public void leaveToken(DetailAST ast) {
        switch (ast.getType()) {
            case TokenTypes.OBJBLOCK -> {
                final Map<String, DetailAST> classFields = privateFields.pop();
                privateFieldsByType.put(enclosingTypeNames.peek(), classFields);
                for (final Map.Entry<String, DetailAST> entry : classFields.entrySet()) {
                    pendingFields.add(new PendingField(entry));
                }
                final Deque<Map<String, String>> snapshot = scopeStackSnapshots.pop();
                snapshot.forEach(scopeStack::push);
                enclosingTypeNames.pop();
            }
            case TokenTypes.LAMBDA -> {
                if (ast.findFirstToken(TokenTypes.PARAMETERS) != null) {
                    scopeStack.pop();
                }
            }
            case TokenTypes.METHOD_DEF, TokenTypes.CTOR_DEF,
                 TokenTypes.SLIST, TokenTypes.LITERAL_FOR,
                 TokenTypes.LITERAL_CATCH -> scopeStack.pop();
            default -> {
                // no action needed for other token types
            }
        }
    }

    @Override
    public void finishTree(final DetailAST rootAST) {
        final Set<DetailAST> usedFieldIdents = new HashSet<>();
        fieldUsages.stream()
                .map(UnusedPrivateFieldCheck::resolveUsage)
                .forEach(usedFieldIdents::add);
        for (final TypedUsage typedUsage : typedUsages) {
            final Map<String, DetailAST> fields = privateFieldsByType.get(typedUsage.typeName());
            if (fields != null) {
                final DetailAST ident = fields.get(typedUsage.fieldName());
                usedFieldIdents.add(ident);

            }
        }
        for (final PendingField pending : pendingFields) {
            final Map.Entry<String, DetailAST> entry = pending.entry();
            final DetailAST ident = entry.getValue();
            final String name = entry.getKey();
            if (!usedFieldIdents.contains(ident) && !globalUsedFields.contains(name)) {
                log(ident, MSG_PRIVATE_FIELD, name);
            }
        }
    }

    /**
     * Resolves a recorded usage to the exact field declaration it refers to,
     * following the same shadowing rules Java itself applies.
     *
     * @param usage the recorded usage to resolve.
     * @return the DetailAST of the field it resolves to, or null if none.
     */
    private static DetailAST resolveUsage(FieldUsage usage) {
        DetailAST result = null;
        if (usage.qualifierTypeName() != null) {
            final int index = usage.ancestorTypeNames().indexOf(usage.qualifierTypeName());
            if (index != -1) {
                result = usage.ancestorFieldMaps().get(index).get(usage.name());
            }
        }
        else {
            for (final Map<String, DetailAST> level : usage.ancestorFieldMaps()) {
                result = level.get(usage.name());
                if (result != null) {
                    break;
                }
            }
        }
        return result;
    }

    /**
     * Collects private field declarations.
     *
     * @param ast for this method.
     */
    private void handleVariableDef(DetailAST ast) {
        final DetailAST parent = ast.getParent();

        if (parent.getType() == TokenTypes.OBJBLOCK) {
            final DetailAST modifiers = ast.findFirstToken(TokenTypes.MODIFIERS);
            final boolean isPrivateField = isPrivate(modifiers);
            final DetailAST ident = ast.findFirstToken(TokenTypes.IDENT);
            final boolean isIgnoredName =
                    ignoredFieldPattern.matcher(ident.getText()).matches();
            final boolean isIgnored = isIgnoredName || hasIgnoredAnnotation(ast);
            if (isPrivateField && !isIgnored) {
                privateFields.peek().put(ident.getText(), ident);
            }
        }
        else if (!scopeStack.isEmpty()) {
            final String localName =
                    ast.findFirstToken(TokenTypes.IDENT).getText();
            scopeStack.peek().put(localName, resolveDeclaredTypeName(ast));
        }
    }

    /**
     * Checks whether a field should be ignored because either the field itself or its
     * enclosing type (class, interface, enum, or record) carries an annotation present
     * in {@link #ignoreAnnotationCanonicalNames} (matched by canonical or short name).
     *
     * @param variableDef the VARIABLE_DEF node.
     * @return true if the field or its enclosing type has a matching ignore annotation.
     */
    private boolean hasIgnoredAnnotation(final DetailAST variableDef) {
        boolean result = isAnnotatedWithIgnoredAnnotation(variableDef);
        if (!result) {
            final DetailAST classDef = variableDef.getParent().getParent();
            result = isAnnotatedWithIgnoredAnnotation(classDef);
        }
        return result;
    }

    /**
     * Checks whether the given AST node (a field or a type definition) carries an
     * annotation present in {@link #ignoreAnnotationCanonicalNames}, matched either
     * by canonical name or by short name.
     *
     * @param ast the VARIABLE_DEF, CLASS_DEF, INTERFACE_DEF, ENUM_DEF, RECORD_DEF, or
     *            ANNOTATION_DEF node to inspect.
     * @return true if a matching ignore annotation is present directly on {@code ast}.
     */
    private boolean isAnnotatedWithIgnoredAnnotation(final DetailAST ast) {
        boolean result = false;
        final DetailAST holder = AnnotationUtil.getAnnotationHolder(ast);
        if (holder != null) {
            DetailAST child = holder.getFirstChild();
            while (child != null) {
                if (child.getType() == TokenTypes.ANNOTATION) {
                    final String name =
                            FullIdent.createFullIdent(
                                    child.getFirstChild().getNextSibling()).getText();
                    if (ignoreAnnotationCanonicalNames.contains(name)
                            || ignoreAnnotationShortNames.contains(name)) {
                        result = true;
                        break;
                    }
                }
                child = child.getNextSibling();
            }
        }
        return result;
    }

    /**
     * Records field usage, respecting local variable and parameter shadowing.
     * Resolution to a specific field declaration happens later, at
     * {@link #finishTree}.
     *
     * @param ast for handleIdent
     */
    private void handleIdent(DetailAST ast) {
        final DetailAST parent = ast.getParent();
        if (!isDeclarationParent(parent)) {
            final String name = ast.getText();
            final boolean shadowed =
                    scopeStack.stream().anyMatch(scope -> scope.containsKey(name));
            if (parent.getType() == TokenTypes.DOT) {
                handleDotAccess(parent, name);
            }
            else if (!shadowed) {
                recordUsage(name, null, false);
            }
        }
    }

    /**
     * Classifies a dot-qualified reference: {@code this.field} and
     * {@code ClassName.this.field} are resolved precisely; any other qualifier
     * (an arbitrary object or type reference) cannot be resolved without type
     * information, so it falls back to name-only matching via
     * {@link #globalUsedFields}.
     *
     * @param dot  the DOT node whose last child is the field IDENT.
     * @param name the field name being accessed.
     */
    private void handleDotAccess(DetailAST dot, String name) {
        final DetailAST qualifier = dot.getFirstChild();
        if (qualifier.getType() == TokenTypes.LITERAL_THIS) {
            recordUsage(name, null, true);
        }
        else if (qualifier.getType() == TokenTypes.DOT
                && qualifier.getLastChild().getType() == TokenTypes.LITERAL_THIS) {
            final String qualifiedName =
                    FullIdent.createFullIdent(qualifier.getFirstChild()).getText();
            final String simpleName =
                    qualifiedName.substring(qualifiedName.lastIndexOf('.') + 1);
            recordUsage(name, simpleName, false);
        }
        else if (findDeclaredType(qualifier.getText()) != null) {
            typedUsages.add(new TypedUsage(findDeclaredType(qualifier.getText()), name));
        }
        else {
            globalUsedFields.add(name);
        }
    }

    /**
     * Looks up the declared simple type name of a local variable or parameter
     * currently in scope.
     *
     * @param name the variable or parameter name.
     * @return its declared simple type name, or null if the name is not a
     *         tracked local/parameter, or its type could not be determined.
     */
    private String findDeclaredType(String name) {
        String result = null;
        for (final Map<String, String> scope : scopeStack) {
            final String type = scope.get(name);
            if (type != null) {
                result = type;
                break;
            }
        }
        return result;
    }

    /**
     * Extracts the declared simple type name of a VARIABLE_DEF or
     * PARAMETER_DEF, if determinable.
     *
     * @param varOrParamDef the VARIABLE_DEF or PARAMETER_DEF node.
     * @return the simple type name, or null if it could not be determined
     *         (e.g. primitive types, inferred/generic-only forms).
     */
    private static String resolveDeclaredTypeName(DetailAST varOrParamDef) {
        final DetailAST typeAst = varOrParamDef.findFirstToken(TokenTypes.TYPE);
        String result = null;
        final DetailAST identChild = typeAst.findFirstToken(TokenTypes.IDENT);
        if (identChild != null) {
            result = identChild.getText();
        }
        return result;
    }

    /**
     * Snapshots the currently open class chain (field maps and type names) so the
     * usage can be resolved later, once every class in the file is fully populated.
     *
     * @param name              the field name referenced.
     * @param qualifierTypeName the enclosing type name named in a
     *                          {@code ClassName.this.field} reference, or null.
     * @param bareThisQualified true for a {@code this.field} reference.
     */
    private void recordUsage(String name, String qualifierTypeName, boolean bareThisQualified) {
        fieldUsages.add(new FieldUsage(name,
                new ArrayList<>(privateFields),
                new ArrayList<>(enclosingTypeNames),
                qualifierTypeName,
                bareThisQualified));
    }

    /**
     * Checks whether the given parent node is a declaration site whose IDENT child
     * names the declared element itself (a variable, method, constructor, or type),
     * rather than referencing some other field.
     *
     * @param parent the parent of the IDENT being inspected.
     * @return true if the IDENT is a declaration name, not a usage.
     */
    private static boolean isDeclarationParent(DetailAST parent) {
        final int type = parent.getType();
        return type == TokenTypes.VARIABLE_DEF
                || type == TokenTypes.METHOD_DEF
                || type == TokenTypes.CLASS_DEF
                || type == TokenTypes.INTERFACE_DEF
                || type == TokenTypes.ENUM_DEF
                || type == TokenTypes.RECORD_DEF
                || type == TokenTypes.ANNOTATION_DEF;
    }

    /**
     * Checks whether a field is private.
     *
     * @param modifiers for isPrivate method.
     * @return modifiers of literal_private.
     */
    private static boolean isPrivate(final DetailAST modifiers) {
        return modifiers.findFirstToken(TokenTypes.LITERAL_PRIVATE) != null;
    }

    /**
     * Holds a private field entry, reported if never resolved to by any usage.
     *
     * @param entry The field name and its AST node.
     */
    private record PendingField(Map.Entry<String, DetailAST> entry) {
    }

    /**
     * A recorded field-name access on a qualifier whose declared type is
     * known precisely.
     *
     * @param typeName  the qualifier's declared simple type name.
     * @param fieldName the field name accessed on it.
     */
    private record TypedUsage(String typeName, String fieldName) {
    }

    /**
     * A recorded, not-yet-resolved reference to a field name, with enough context
     * to resolve it precisely once the whole file has been visited.
     *
     * @param name                the field name referenced.
     * @param ancestorFieldMaps   the currently open field maps at the time of the
     *                            reference, innermost first (index 0).
     * @param ancestorTypeNames   the currently open type names, parallel to
     *                            {@code ancestorFieldMaps}.
     * @param qualifierTypeName   the type name in a {@code ClassName.this.field}
     *                            reference, or null if not that form.
     * @param bareThisQualified   true for a {@code this.field} reference.
     */
    private record FieldUsage(String name, List<Map<String, DetailAST>> ancestorFieldMaps,
                              List<String> ancestorTypeNames, String qualifierTypeName,
                              boolean bareThisQualified) {
    }

}