Allow more things to be marked deprecated through docstrings

[adhoc-bobcat]

Buildtools PR checklist

• The code in this PR is covered by unit/integration tests.
• I have tested these changes and provide testing instructions below.
• I have either responded to, or resolved all Gemini comments on the PR.
• I have read Google Eng Practices on Small Changes, this PR either follows these guidelines or the description provides reasoning for why they can not be followed.

Description

This change allows module extensions and their tags, along with rules to be marked as deprecated so that buildifier emits a warning if they are used.

This is aligned with the existing function deprecation check, where the tool looks for the text "Deprecated:" in the docstring.

Module extensions and rules have two places where they can be marked deprecated.

• When calling the global function to create the extension or rule, through a "doc" arg.
• Through the docstring of the implementation function.

These changes allow either place to be used.

These changes were tested using the following steps

$ bazelisk test //...

[gemini-code-assist]

Code Review

This pull request introduces new linter warnings for deprecated module extensions, module extension tags, and rules. It refactors the existing deprecation warning logic by splitting warn_deprecated.go into specialized files and adds comprehensive integration and unit tests. Documentation in WARNINGS.md and warnings.textproto has been updated to reflect these new categories. I have no feedback to provide.

[adhoc-bobcat]

I realized this evening there was something important missing.

More complicated Bazel modules implement their rules and extensions privately, and use a re-export pattern, such as:

# In a public file
load("//private:impl.bzl", _impl="impl")
impl = _impl

As my changes followed the pattern set by the deprecated function warning, the buildifier running on Bazel files that used the "public" version of impl would load the small public re-export file, and decide it wasn't deprecated, since the definition there doesn't have a docstring.

(And no, I'm not proposing to fix it by recurively scanning. That's pretty obviously not how buildifier is mean to work.)

I had some thoughts for how to fix this, and they would simplify the implementation.

1. The deprecation checks could look for an assignment to the global name of interest that looks like impl = _deprecated_impl in the loaded file. This is certainly simple, but might be a little too magical. It also requires module authors to do some renaming.

2. The deprecation check could look for an assignment to the global name of interest that looks like impl = _any_function(_impl), where _any_function(x) is just a decorator that returns x. If the docstring to that function had the "Deprecated:" substring, then buildifier would consider the name assigned to be deprecated.

   This aligns better with how buildifier currently works to decide if a function is deprecated, because that is what it looks for.

   It would mean a slightly larger (but still small) one-time runtime cost for Bazel, as it would have to evaluate the function call operation. That said, an advantage to this approach is that module authors could define a deprecation helper like this:

   def _deprecated(x, use_instead=None):
      """Deprecated: See the use_instead string."""
      return x
   
   impl = _deprecated(_impl, use_instead="Use other_impl")

   The disadvantage is that they'd have to reimplement that function in every file they needed to declare something as deprecated, since buildifier wouldn't visit the next level of loads.

Feel free to leave any thoughts here. I'll likely go ahead and implement (2), before removing the draft status I added on this PR. (I don't think it's really that large a change if I need to switch to (1), or even some third option.)