Support for replacements in `buf.yaml`

[doriable]

Feature

We've seen a couple of cases where users are migrating their dependencies between modules that may have shared/renamed definitions. For example, there are 3 modules across different source repositories: moduleA, moduleB, moduleC. moduleB depends on moduleC. Let's say moduleA currently depends on https://buf.build/grpc-ecosystem/grpc-gateway/docs and both moduleB and moduleC depend on https://buf.build/grpc-ecosystem/protoc-gen-swagger/docs. If moduleA attempts to depend on moduleB, there would be a collision with annotations.proto, since one is a rename of the other. And moduleB cannot easily migrate to https://buf.build/grpc-ecosystem/grpc-gateway/docs because they would run into the same collision due to moduleB's dependency on moduleC.

It would be nice if we are able to have something like a replace_deps key in buf.yaml, if moduleA wants to take a dependency on moduleB e.g.:

deps:
  - buf.build/grpc-ecosystem/grpc-gateway
  - buf.build/owner/module-b
replace_deps:
  - buf.build/grpc-ecosystem/protoc-gen-swagger: buf.build/grpc-ecosystem/grpc-gateway

This would indicate that all transitive deps on protoc-gen-swagger would instead use grpc-gateway. It would be the user's responsibility to ensure compatibility when setting the replace_deps key -- buf would naively replace these module dependencies.

[doriable]

Floated the idea to @mfridman, some open questions from our chat:

• The replace directive would/should be reflected in buf.lock
• What should the behaviour with buf push be?
• What should the behaviour with buf dep {update, prune} be?

[doriable]

For the example provided in the description, buf.build/grpc-ecosystem/grpc-gateway for buf.build/grpc-ecosystem/protoc-gen-swagger, the module-level replacement is insufficient, since the proto packages have been renamed. This would need to handle package-level replacement.