feat(spotless/gradle-plugin): Allow `SpotlessApply` to notify when/what work was done

[ffluk3]

Hello Spotless team! We're very thankful for your work on this tool. Seeking review on a proposed feature that we are happy to help incorporate into the project if it sounds like a desirable enhancement.

TL;DR:

We'd like to expose information on which files were auto-fixed by SpotlessApply to propagate that information to our developer experience

Problem Statement

Our current team's workflow is as such for running Spotless:

• On CI, our invocation of gradle build runs spotlessCheck, as is configured by default. All failures are reported by CI and require manual updates
• In local use cases, gradle build will instead run spotlessApply to automatically fix issues. This is biased toward improving the UX during local development

In this case, the developer experience is enhanced by the automatic fixing, however it is less clear when spotlessApply is run on the user's behalf.

It would be preferable to do something more targeted. In this case, we'd prefer to have SpotlessApply (or a finalizer task) only print information in the event that Spotless performed work.

[!NOTE] In an ideal world, we'd also be able to show the violations that were fixed during the auto-fix phase, such that we could demonstrate to developers "there were X and Y issues, and we've auto-fixed them". This may be out of scope of this more immediate enhancement, but may be interesting to provide.

(Potential) Design

Enhance the SpotlessApply task to output a simple report containing a manifest of all files it copied in on the most recent execution. This output location can be exposed by the task for the specific gradle build, read, and used to provide a more detailed listing of the edited files.

Note: Theoretical Workaround

We've attempted what we thought would be a suitable workaround for the time being:

// build.gradle.kts (or in convention plugin)
tasks.withType<SpotlessApply>() {
    doLast {
      if(didWork) {
         logger.lifecycle("code auto-formatted by spotlessApply")
      }
    }
}

Unfortunately, even for cases where there are no changes to any of the source files, the SpotlessApply task is still labeled as didWork == true. If we should file this separately as a "bug", please let us know!

[nedtwigg]

Enhance the SpotlessApply task to output a simple report containing a manifest of all files it copied in on the most recent execution.

We would welcome this contribution.

no changes to any of the source files, the SpotlessApply task is still labeled as didWork == true

No need for a separate bug. Feel free to fix this if you'd like while working on the report feature you want. I'm not sure what's going on, but this might be load-bearing. We definitely have a hint to the check task that if the apply task has already run, then it doesn't need to do anything. Open to revisiting this.

• https://github.com/diffplug/spotless/blob/a2ce4e2d61e310e02bfb93c230363f1074833e52/plugin-gradle/src/main/java/com/diffplug/gradle/spotless/SpotlessApply.java#L32-L34
• https://github.com/diffplug/spotless/blob/a2ce4e2d61e310e02bfb93c230363f1074833e52/plugin-gradle/src/main/java/com/diffplug/gradle/spotless/SpotlessCheck.java#L65-L67