Integrate Java compiler with the problems API

[hegyibalint]

Goal

The Java compiler outputs compilation problems directly to the standard output. The problem with that is that the information is buried in the build output, and users must scroll up in the build log to figure out what made the build fail. This is a subpar experience, which we could improve by integrating the compiler task with the Problems API. By using the API, we can create a comprehensive report at the end of the build.

In addition to the reporting capabilities, structured problems could help IDEs and tools establish what went wrong and where. This is already the case in some of the tools, but it relies on parsing the console output vs. receiving well-defined, structured information about what happened. As an example, build scans can render a separated, focused report about compilation problems, which doesn't rely on the console output.

Resources

• Specification - Java Compiler Diagnostics as Problems

Deliverables

• Custom DiagnosticListener for the Java compiler task emitting Problem events and delegate to default rendering
  • Problem reports describing individual compiler warnings/errors/notes/etc.
  • Problem reports describing problems with the compilation process itself
    • compileJava tasks fails because there were warnings and -Werror is specified.
    • compileJava tasks fails because of invalid compiler argument problems: javac -source -1
• Describe new feature in release notes (IDE Integration improvements section)

Acceptance criteria

• Stakeholders are informed about the new features
• Our team in 👍 on the data as it will be the input for the upcoming compilation build failure console rendering improvements.

Stakeholders

• BT JVM team (as code-owners for the java compilation component)
• Piotr
• JetBrains
• Google
• Microsoft VSCode team

Communication plan

• JVM team
  • get buy-in on planned feature
  • update them weekly on progress
• JB/Google/Microsoft:
  • notify them about deliverables when something changes
  • keep them updated on regressions/etc

Associated tasks

Tasks and issues

Beta Give feedback

1. Add worker support for Problems API #25707
   30 min review @ide-experience build-script-change platform:bt_ge_build_cache platform:core_configuration platform:core_execution platform:core_runtime platform:ide platform:jvm platform:software +10
   
2. Java compiler warnings and errors should be exposed via the problems API #26529
   a:feature in:problems +2
   
3. Discuss what should be the java compilation problem severity when -Werror flag is used #27770
   a:feature in:java-plugins in:problems +3
   
4. Re-implement replacement for null diagnosticlistener #27823
   a:regression in:java-plugins in:problems +3
   
5. Improve Problems API Java file location information #27829
   a:feature in:problems +2
   
6. Convert int location types to long #27998
   stale +1
   
7. Fix the performance regressions caused by exposing compile diagnostics as problems #27693
   a:bug closed:invalid in:execution-engine +3
   
8. The -Werror flag should transform warnings to errors #27948
   a:feature closed:not-fixed in:java-plugins in:problems +4
   
9. Replace hand-made categories, and utilize diagnostic codes supplied by diagnostics #27960
   a:feature in:java-plugins in:problems +3
   
10. Remove unnecessary feature flag #29080
    1 min review in:java-plugins in:problems +3
    
11. Implement diagnostic to problem conversion using internal compiler APIs #28281
    20 min review a:feature in:java-plugins in:problems +4
    
12. Incorrect java warning/error location in new Problems API #28554
    a:bug has:reproducer in:problems +3
    
13. Fix incorrect problem length when reporting compilation problems #29063
    1 min review in:java-plugins in:problems +3
    
14. Problem-reporting capable compilation doesn't emit error count #28930
    a:regression in:java-plugins in:problems +3
    
15. Compiler problem reporting causes IllegalArgumentException with Java 8 is used with an annotation processor present #29113
    0 of 1
    a:bug in:java-plugins in:problems +3
    
16. Check if compileJava tasks fails because of invalid compiler argument problems #29406
    a:chore in:java-plugins in:problems +3
    
17. Lower the log level of the message informing about failing to get the DiagnosticFormatter #29352
    in:problems +1
    
18. Compiler exceptions should be mapped to problems #29423
    a:investigation in:problems +2
    
19. Improve JDK8 corner-case test #29421
    in:java-plugins in:problems +2
    
20. Create release notes for the new Java compiler integration with the Problems API #29493
    a:documentation in:java-plugins in:problems +3
    
21. Formatting should be the same with JDK8 compiler reports as with other compilers #29501
    a:bug in:java-plugins in:problems +3
22. Use contextualLabel instead of details in Java problems #29605
    a:chore in:java-plugins in:problems +3
    
23. TestKit is broken when tests execute Java compilation and debugging is turned on #29696
    a:bug in:test-kit +2
    

[AndreasTu]

It would be great if that new API is also exposed to Gradle-Plugins not only Tooling API (like. IDEs).

Usecase:
I would like to implement a GradlePlugin which tracks the Java compile warnings and let the build fail if new warnings are added, but existing warnings are "accepted" for the time being. This would allow projects to gradually migrate to the -Werror without enforcing to fix all warnings at once. The Plugin would then update the accepted warnings during build, when old warnings are fixed. If the warning count drops to zero the -Werror flag will be enforced.

The API would allow me to implement such a thing, because it would be able to track the occurred warnings reliably.

[tbroyer]

Might be a moonshot but it could be a good idea to define a "standard" API for diagnostics to allow passing fix suggestions to the Problems API, so that IDEs could provide a "quick fix" action for example.

Error Prone for instance produces such suggestions, and having them surfaced somehow down to the Problems API through the compiler diagnostics could allow IDEs to propose them as "quick fixes" directly.
I made some research and a POC last year that was Error Prone specific but could likely be turned into some "standard" API: the idea was putting those fixes into an object passed as first argument to the diagnostic message; without a specific diagnostic listener, the object's toString() is called when the message is formatted and you get an standard message, but with a specific diagnostic listener it can cast the argument to that "standard" API and extract structured information out of it. The POC relied on the very few message-bundle keys used by Error Prone to detect when such a structured-information would be known to be available.
This would of course require tools like Error Prone to collaborate and use your "standard API" though.

The feature request for the Gradle GitHub Action to surface problems reported through the Problems API as comments on pull request (gradle/actions#30) could take advantage of such structured information to add GitHub suggestions to the comments as equivalent to IDE "quick fixes" too.