///////////////////////////////////////////////////////////////////////////////////////////////
// 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.ArrayList;
import java.util.HashSet;
import java.util.List;
import java.util.Set;

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.TokenTypes;
import com.puppycrawl.tools.checkstyle.utils.TokenUtil;

/**
 * <div>
 * Checks that a {@code permits} clause of a sealed class or interface is not
 * unnecessary, i.e. that it is not possible to omit the clause and have the
 * compiler infer the exact same set of permitted subtypes.
 * </div>
 *
 * <p>
 * See the <a href="https://docs.oracle.com/javase/specs/jls/se22/html/jls-13.html#jls-13.4.2">
 * Java Language Specification</a> for more information about sealed classes.
 * </p>
 *
 * <p>
 * This Check does not perform full type resolution. It determines whether a
 * permitted type is local to the file by comparing simple names against every
 * type declaration (class, interface, enum, or record) found
 * anywhere in the compilation unit, including nested and sibling top-level
 * types. As a result, a permitted type whose simple name coincidentally
 * matches an unrelated local type declaration could, in theory, be
 * misidentified as local. In practice this situation cannot occur in code
 * that compiles, since the Java compiler would not be able to resolve such an
 * ambiguous reference in the {@code permits} clause.
 * </p>
 *
 * @since 14.2.0
 */
@FileStatefulCheck
public class UnnecessaryPermitsClauseCheck extends AbstractCheck {

    /**
     * A key is pointing to the warning message text in "messages.properties" file.
     */
    public static final String MSG_KEY = "unnecessary.permits.clause";

    /**
     * A set of simple names of every type declared in the current compilation
     * unit, including nested types.
     */
    private final Set<String> localTypeNames = new HashSet<>();

    /**
     * A list of {@link TokenTypes#PERMITS_CLAUSE} nodes found in the current compilation unit.
     */
    private final List<DetailAST> permitsClauseAstList = new ArrayList<>();

    /**
     * Creates a new {@code UnnecessaryPermitsClauseCheck} instance.
     */
    public UnnecessaryPermitsClauseCheck() {
        // no code by default
    }

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

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

    @Override
    public int[] getRequiredTokens() {
        return new int[] {
            TokenTypes.CLASS_DEF,
            TokenTypes.INTERFACE_DEF,
            TokenTypes.ENUM_DEF,
            TokenTypes.RECORD_DEF,
            TokenTypes.PERMITS_CLAUSE,
        };
    }

    @Override
    public void beginTree(DetailAST rootAST) {
        localTypeNames.clear();
        permitsClauseAstList.clear();
    }

    @Override
    public void visitToken(DetailAST ast) {
        switch (ast.getType()) {
            case TokenTypes.CLASS_DEF,
                    TokenTypes.INTERFACE_DEF,
                    TokenTypes.ENUM_DEF,
                    TokenTypes.RECORD_DEF -> {
                final DetailAST nameAst = ast.findFirstToken(TokenTypes.IDENT);
                localTypeNames.add(nameAst.getText());
            }
            default -> permitsClauseAstList.add(ast);
        }
    }

    @Override
    public void finishTree(DetailAST rootAST) {
        for (DetailAST permitsClause : permitsClauseAstList) {
            if (isUnnecessary(permitsClause)) {
                log(permitsClause, MSG_KEY);
            }
        }
    }

    /**
     * Determines whether every type named in the given {@code permits} clause
     * is declared somewhere within the same compilation unit, and is therefore redundant.
     *
     * @param permitsClause the {@link TokenTypes#PERMITS_CLAUSE} node to inspect
     * @return {@code true} if the clause is unnecessary
     */
    private boolean isUnnecessary(DetailAST permitsClause) {
        boolean result = true;
        DetailAST permittedType = permitsClause.getFirstChild();
        while (permittedType != null) {
            if (isTypeName(permittedType)) {
                final String simpleName = getSimpleName(permittedType);
                if (!localTypeNames.contains(simpleName)) {
                    result = false;
                    break;
                }
            }
            permittedType = permittedType.getNextSibling();
        }
        return result;
    }

    /**
     * Checks whether the given direct child of a {@code permits} clause
     * represents a permitted type name, as opposed to a separating comma.
     *
     * @param ast the node to check
     * @return {@code true} if the node is a (possibly qualified) type name
     */
    private static boolean isTypeName(DetailAST ast) {
        return TokenUtil.isOfType(ast, TokenTypes.IDENT, TokenTypes.DOT);
    }

    /**
     * Extracts the simple (unqualified) name from a type name node, which is
     * either a single {@link TokenTypes#IDENT} or a {@link TokenTypes#DOT}
     * chain representing a qualified name.
     *
     * @param typeName the type name node
     * @return the simple name of the type
     */
    private static String getSimpleName(DetailAST typeName) {
        final String simpleName;
        if (typeName.getType() == TokenTypes.DOT) {
            simpleName = typeName.getLastChild().getText();
        }
        else {
            simpleName = typeName.getText();
        }
        return simpleName;
    }

}