/*
 * Copyright 2025 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

// ***********************************************************************************
// MAINTAINED AND TESTED IN THE R8 REPO. PLEASE MAKE CHANGES THERE AND REPLICATE.
// ***********************************************************************************

package androidx.annotation.keep

/**
 * Usage constraints for how a target is used and what must be kept.
 *
 * <p>Providing the constraints on how an item is being used allows shrinkers to optimize or remove
 * aspects of the item that do not change that usage constraint.
 *
 * <p>For example, invoking a method reflectively does not use any annotations on that method, and
 * it is safe to remove the annotations. However, it would not be safe to remove parameters from the
 * method.
 */
public enum class KeepConstraint {
    /**
     * Indicates that the target item is being looked up reflectively.
     *
     * <p>Looking up an item reflectively requires that it remains on its expected context, which
     * for a method or field means it must remain on its defining class. In other words, the item
     * cannot be removed or moved.
     *
     * <p>Note that looking up a member does not imply that the holder class of the member can be
     * looked up. If both the class and the member need to be looked, make sure to have a target for
     * both.
     *
     * <p>Note also that the item can be looked up within its context but no constraint is placed on
     * its name, accessibility or any other properties of the item.
     *
     * <p>If assumptions are being made about other aspects, additional constraints and targets
     * should be added to the keep annotation.
     */
    LOOKUP,

    /**
     * Indicates that the name of the target item is being used.
     *
     * <p>This usage constraint is needed if the target is being looked up reflectively by using its
     * name. Setting it will prohibit renaming of the target item.
     *
     * <p>Note that preserving the name of a member does not imply that the holder class of the
     * member will preserve its qualified or simple name. If both the class and the member need to
     * preserve their names, make sure to have a target for both.
     *
     * <p>Note that preserving the name of a member does not preserve the types of its parameters or
     * its return type for methods or the type for fields.
     */
    NAME,

    /**
     * Indicates that the visibility of the target must be at least as visible as declared.
     *
     * <p>Setting this constraint ensures that any (reflective) access to the target that is allowed
     * remains valid. In other words, a public class, field or method must remain public. For a
     * non-public target its visibility may be relaxed in the direction: {@code private ->
     * package-private -> protected -> public}.
     *
     * <p>Note that this constraint does not place any restrictions on any other accesses flags than
     * visibility. In particular, flags such a static, final and abstract may change.
     *
     * <p>Used together with {@link #VISIBILITY_RESTRICT} the visibility will remain invariant.
     */
    VISIBILITY_RELAX,

    /**
     * Indicates that the visibility of the target must be at most as visible as declared.
     *
     * <p>Setting this constraint ensures that any (reflective) access to the target that would fail
     * will continue to fail. In other words, a private class, field or method must remain private.
     * Concretely the visibility of the target item may be restricted in the direction: {@code
     * public -> protected -> package-private -> private}.
     *
     * <p>Note that this constraint does not place any restrictions on any other accesses flags than
     * visibility. In particular, flags such a static, final and abstract may change.
     *
     * <p>Used together with {@link #VISIBILITY_RELAX} the visibility will remain invariant.
     */
    VISIBILITY_RESTRICT,

    /**
     * Indicates that the visibility of the target must remain as declared.
     *
     * <p>Note that this constraint does not place any restrictions on any other accesses flags than
     * visibility. In particular, flags such a static, final and abstract may change.
     *
     * <p>This is equivalent to using both {@link #VISIBILITY_RELAX} and
     * {@link #VISIBILITY_RESTRICT}.
     */
    VISIBILITY_INVARIANT,

    /**
     * Indicates that the class target is being instantiated reflectively.
     *
     * <p>This usage constraint is only valid on class targets.
     *
     * <p>Being instantiated prohibits reasoning about the class instances at compile time. In other
     * words, the compiler must assume the class to be possibly instantiated at all times.
     *
     * <p>Note that the constraint {@link KeepConstraint#LOOKUP} is needed to reflectively obtain a
     * class. This constraint only implies that if the class is referenced in the program it may be
     * instantiated.
     */
    CLASS_INSTANTIATE,

    /**
     * Indicates that the method target is being invoked reflectively.
     *
     * <p>This usage constraint is only valid on method targets.
     *
     * <p>To be invoked reflectively the method must retain the structure of the method. Thus,
     * unused arguments cannot be removed. However, it does not imply preserving the types of its
     * parameters or its return type. If the parameter types are being obtained reflectively then
     * those need a keep target independent of the method.
     *
     * <p>Note that the constraint {@link KeepConstraint#LOOKUP} is needed to reflectively obtain a
     * method reference. This constraint only implies that if the method is referenced in the
     * program it may be reflectively invoked.
     */
    METHOD_INVOKE,

    /**
     * Indicates that the field target is reflectively read from.
     *
     * <p>This usage constraint is only valid on field targets.
     *
     * <p>A field that has its value read from, requires that the field value must remain. Thus, if
     * field remains, its value cannot be replaced. It can still be removed in full, be inlined and
     * its value reasoned about at compile time.
     *
     * <p>Note that the constraint {@link KeepConstraint#LOOKUP} is needed to reflectively obtain
     * access to the field. This constraint only implies that if a field is referenced then it may
     * be reflectively read.
     */
    FIELD_GET,

    /**
     * Indicates that the field target is reflectively written to.
     *
     * <p>This usage constraint is only valid on field targets.
     *
     * <p>A field that has its value written to, requires that the field value must be treated as
     * unknown.
     *
     * <p>Note that the constraint {@link KeepConstraint#LOOKUP} is needed to reflectively obtain
     * access to the field. This constraint only implies that if a field is referenced then it may
     * be reflectively written.
     */
    FIELD_SET,

    /**
     * Indicates that the target method can be replaced by an alternative definition at runtime.
     *
     * <p>This usage constraint is only valid on method targets.
     *
     * <p>Replacing a method implies that the concrete implementation of the target cannot be known
     * at compile time. Thus, it cannot be moved or otherwise assumed to have particular properties.
     * Being able to replace the method still allows the compiler to fully remove it if it is
     * statically found to be unused.
     *
     * <p>Note also that no restriction is placed on the method name. To ensure the same name add
     * {@link #NAME} to the constraint set.
     */
    METHOD_REPLACE,

    /**
     * Indicates that the target field can be replaced by an alternative definition at runtime.
     *
     * <p>This usage constraint is only valid on field targets.
     *
     * <p>Replacing a field implies that the concrete implementation of the target cannot be known
     * at compile time. Thus, it cannot be moved or otherwise assumed to have particular properties.
     * Being able to replace the method still allows the compiler to fully remove it if it is
     * statically found to be unused.
     *
     * <p>Note also that no restriction is placed on the field name. To ensure the same name add
     * {@link #NAME} to the constraint set.
     */
    FIELD_REPLACE,

    /**
     * Indicates that the target item must never be inlined or merged.
     *
     * <p>This ensures that if the item is actually used in the program it will remain in some form.
     * For example, a method may still be renamed, but it will be present as a frame in stack traces
     * produced by the runtime (before potentially being retraced). For classes, they too may be
     * renamed, but will not have been merged with other classes or have their allocations fully
     * eliminated (aka class inlining).
     *
     * <p>For members this also ensures that the field value or method body cannot be reasoned about
     * outside the item itself. For example, a field value cannot be assumed to be a particular
     * value, and a method cannot be assumed to have particular properties for callers, such as
     * always throwing or a constant return value.
     */
    NEVER_INLINE,

    /**
     * Indicates that the class hierarchy below the target class may be extended at runtime.
     *
     * <p>This ensures that new subtypes of the target class can later be linked and/or class loaded
     * at runtime.
     *
     * <p>This does not ensure that the class remains if it is otherwise dead code and can be fully
     * removed.
     *
     * <p>Note that this constraint does not ensure that particular methods remain on the target
     * class. If methods or fields of the target class are being targeted by a subclass that was
     * classloaded or linked later, then keep annotations are needed for those targets too. Such
     * non-visible uses requires the same annotations to preserve as for reflective uses.
     */
    CLASS_OPEN_HIERARCHY,

    /**
     * Indicates that the target item must retain its generic signature if present.
     *
     * <p>This ensures that the generic signature remains, but does not prohibit rewriting of the
     * generic signature. For example, if a type present in the generic signature is renamed, the
     * generic signature will also be updated to now refer to the type by its renamed name.
     *
     * <p>Note that this constraint does not otherwise restrict what can be done to the target, such
     * as removing the target completely, inlining it, etc.
     */
    GENERIC_SIGNATURE,
}