TL;DR

When building a native image, the user has no information about the elements that were included via the reachability metadata. This makes debugging and testing of reachability metadata hard.

To fix this, we will output all of the reachability metadata in the JSON format together with the image build. Each element in the reachability metadata will have an additional field reasons which contains the list of string reasons for the addition of this element. For example, a method can be added for multiple reasons which will be displayed in the output reflect-config.json as follows:

{
    "reasons": [ "app.Feature#beforeAnalysis", "jar://<path>/app.jar!META-INF/native-image/lib/reflect-config.json" ],
    "name": "sun.misc.Unsafe"
}

The reasons can be the following:

1. The element was added via a JSON file. In this case, the displayed reason will be the path to the file.
2. The element was added via a feature. In this case, the feature fully-qualified name will be displayed.
3. The element was added by analyzing patterns in the user code. In this case, the message displays the class and method where the method was included.
4. The element was included in the image heap. In this case, the message will display simply "Included in the image heap"

If the files are large, or the output is computationally complex, his feature could be placed behind a flag.

Goals

1. Make it easy to understand the reachability metadata of a project.
2. Make it possible to write tests for the reachability metadata.
3. Make it easy to debug problems with missing metadata in third-party programs.

Non-Goals

1. Make the image build slower.
2. Use the produced data in another image build.
3. Expose user-sensitive information in the output files.