Implement buf format Gradle step

[andrewparmet]

Fixes #1207.

Adds a step and a Gradle Extension for formatting Protobuf using buf format.

Open questions:

• Is there an existing pattern I can copy to grab the Buf executable as part of a Gradle build? Unlike KtLint, for example, Buf is not distributed as a JAR, so I cannot use JarState. Or can JarState be used with a custom Ivy repository? I don't actually need this, as users of the buf-gradle-plugin can access its Buf executable with

configure<SpotlessExtension> {
    protobuf {
        buf().pathToExe(configurations.getByName(BUF_BINARY_CONFIGURATION_NAME).singleFile.absolutePath)
    }
}

• Should I tag these tests in a way similar to Clang, Black, etc.? How can I make sure buf is available for CI tests? It won't be, as in other "foreign" formatter steps.
• In BufStepTest I had to specify a much longer path to the proto file than other similar tests. Am I missing something?

[nedtwigg]

This PR is excellent and I'm happy to merge it as-is if you're ready. My only comments are minor docs and testing nits which can be easily fixed post merge-and-release.

[nedtwigg]

It doesn't really matter, but it should be okay for this to be new File("foo.proto"). If BufStep is implemented correctly (looks to me like it is), then the non-existent "foo.proto" isn't actually used to read any content from. The only significance of a formatter that takes the actual filename should be that formatting depends on the filename, such as package-info.java or something like that.

So it should be fine if "foo.proto" doesn't actually exist, because it's just a fake filename to pass around.

[andrewparmet]

I thought that might be the case, but I run into issues:

java.lang.RuntimeException: > arguments: [/usr/local/bin/buf, format, /Users/andrewparmet/.../spotless/testlib/foo.proto]
> exit code: 1
>    stdout: (empty)
>    stderr: Failure: input /Users/andrewparmet/.../spotless/testlib/foo.proto was not found - is the directory containing this file defined in your buf.work.yaml?

[nedtwigg]

Bummer, we've got a problem. Your answer about the test needing the file to exist made me suspicious, so I did a little digging.

On this line you are passing the file's content on stdin as input.getBytes(...) but the buf command is ignoring that and just reading the file content from disk. That breaks Spotless' model - for example, any steps that get applied before buf() will get wiped out, and our IDE integrations will also not work as expected.

Looks like this is a known issue, and they plan to add the ability to read buf from stdin: bufbuild/buf#1035

I'd like to delay merging this until buf adds this feature. If this delay would be a big hassle to your workflow, I'm okay merging this semi-broken feature in, with the promise that we'll stop supporting this version of buf once they release a version which supports stdin.

[andrewparmet]

Either is fine. I can use the buf-gradle-plugin in the meantime. Bummer to not be able to use spotlessApply for everything!

[nedtwigg]

Since the buf-gradle-plugin is already available and the buf team has accepted the feature request, I'll wait until it gets resolved rather than merge something half-broken.

[andrewparmet]

It doesn't seem like the Buf team is going to be taking on stdin support anytime soon. What are your thoughts on merging this semi-broken feature? Would it cause problems for any common formatting use cases besides license headers?

[andrewparmet]

Oh, and since I opened this PR the Buf team has begun publishing a Buf binary to Maven Central. Is there an existing pattern for locating a binary that way? The buf-gradle-plugin references it under the hood now, so it's also possible to let it be a transparent improvement here and leave the instructions here as they are.

[nedtwigg]

I'm okay merging this as-is.

Would it cause problems for any common formatting use cases

Main thing it breaks is idempotence. Most formatters have idempotency bugs, which Spotless quietly fixes, and that won't work here. It also means that things like replace, license, tabsToSpaces etc will only work if you put them after the buf step, they can't come before. Not great, but we can document it and point them to the buf issue to thumbs-up it.

publishing a Buf binary to Maven Central

I assume the binary has to be extracted from the jar? We don't have any formatters like that currently. I'd be happy to merge that in, but even happier to leave that up to some other plugin and document that in our docs. Let me know when you're ready to merge and we'll let it rip :)

[andrewparmet]

Ok - letting buf-gradle-plugin handle that is probably best. I corrected the docs pointing to it (Buf in-housed it earlier this year) but the instructions are the same otherwise. Extracting from the jar would mean writing code to support specifying a Maven artifact as a source for a binary and I don't think I want to tackle that at the moment given that it can be added later and we're going to put this behind common configuration code anyways.

I'm happy as this is! Should I take care of those doc notes? I checked the box to let you do it if you want to just do it quickly yourself.

[nedtwigg]

Released in plugin-gradle 6.20.0.