Document how to write custom Refaster rules

[mikybars]

Problem

I couldn't find any documentation on how to write and apply your own Refaster rules. I've tried adding and enabling your Refaster rule compiler to the build like this:

dependencies {
    annotationProcessor("tech.picnic.error-prone-support:refaster-compiler:$errorProneSupportVersion")
    // ...
}

tasks.withType<JavaCompile>().configureEach {
    options.compilerArgs.add("-Xplugin:RefasterRuleCompiler")
    // ...
}

Then I get my regular Java classes with @BeforeTemplate and @AfterTemplate compiled into .refaster files inside build/classes.

Unfortunately, even though I have the Refaster runner dependency as well, I cannot see any of my custom rules kicking in. I get all the error-prone-support checks tough.

Am I missing something here?

[Stephan202]

Hey @almibarss, thanks for reaching out!

I have ~zero experience with Gradle, but it sounds like (a) the Refaster rule compiler is properly picked up, since .refaster files are generated and (b) the Refaster bug checker is properly picked up, since the rules from this project are active.

My guess is then that that perhaps these two configurations are part of the same module? I don't expect that to work, because the Refaster check loads all *.refaster classpath resources during compilation of the first Java file, while RefasterRuleCompiler will only afterwards generate the custom *.refaster files.

A setup such as this one should work:

1. Define a module A that runs with -Xplugin:RefasterRuleCompiler, and place the custom Refaster rule classes in this module.
2. Define a module B that contains refaster-compiler and module A on the annotation processor classpath.

This way, during compilation of B, the rules defined by A should kick in.

I hope this helps! If not, I'd be happy to have a look at some reproduction code. (Though, given that I know little about Gradle, and looking at my TODO list, I wouldn't be able to commit to a timeline.)

[mikybars]

Hi @Stephan202, thank you for your prompt response!

Your guess was absolutely right. And I must admit that I was guessing sort of the same thing. The generation and collection of *.refaster files from the class path were kind of interleaving so I needed to introduce an explicit dependency via Gradle.

Here's the link to my repo where I've implemented a number of common scenarios such as custom rules:

https://github.com/almibarss/error-prone-gradle-demo

I still think there should exist some documentation somewhere because implementing your own rules sounds like a pretty essential feature and should be streamlined as much as possible.

[Stephan202]

@almibarss happy it worked out!

You're absolutely right about documentation! If you don't mind I'll reopen this issue to track that task. (Otherwise I can file a separate ticket and relabel this one as question.)