[Feature] Parameter precondition attribute for simplifying performing hierarchical operations within a guild

[zobweyt]

Description

The attribute like this one was really needed by the community. I often saw discussions about how to handle hierarchical operations correctly, but it was all too cumbersome and everyone had to create it themselves.

This is very useful when you need to perform hierarchical operations within a guild, such as managing roles or users. Here's a brief example of how you can check the hierarchy now:

[RequireContext(ContextType.Guild)]
[RequireBotPermission(GuildPermission.ManageRoles)]
[RequireUserPermission(GuildPermission.ManageRoles)]
[SlashCommand("role", "Adds a role to a user within a guild.")]
public async Task RoleAsync(IGuildUser user, [DoHierarchyCheck] IRole role)
{
    if (user.RoleIds.Any(id => id == role.Id))
    {
        await RespondAsync($"{user.Mention} already has {role.Mention}!");
        return;
    }

    await user.AddRoleAsync(role);
    await RespondAsync($"Added {role.Mention} to {user.Mention}.");
}

Changes

• Add DoHierarchyCheckAttribute to the Discord.Interactions. (9c3cc4b)
• Update bundled preconditions docs for the Discord.Interactions. (9c3cc4b)
• Add DoHierarchyCheckAttribute to the Discord.Commands. (0173b20)
• Update bundled preconditions docs for the Discord.Commands. (0173b20)

Related Issues

Now, there will be less issues like:

• [Bug]: There doesn't seem to be a way to get a user's top role? #2396
• KickAsync Leads to HTTPException #1446
• 403 Forbidden Error when assigning roles to a user #921
• Cannot change nickname #879
• Hierarchy Helper? #248