Clarify `reason` output. Rearrange sections, add more explanatory narrative.

[jolaf]

Plugin version 2.16.0

Gradle version 8.13

JDK version 17

Kotlin and Kotlin Gradle Plugin (KGP) version 2.1.20

Android Gradle Plugin (AGP) version 8.9.1

reason output for bugs relating to incorrect advice

> Task :app:reason

------------------------------------------------------------
You asked about the dependency 'androidx.activity:activity:1.8.0'.
You have been advised to add this dependency to 'implementation'.
------------------------------------------------------------

Shortest path from :app to androidx.activity:activity:1.8.0 for releaseCompileClasspath:
:app
\--- com.google.android.material:material:1.13.0-alpha12
      \--- androidx.activity:activity:1.8.0

Shortest path from :app to androidx.activity:activity:1.8.0 for releaseRuntimeClasspath:
:app
\--- com.google.android.material:material:1.13.0-alpha12
      \--- androidx.activity:activity:1.8.0

Source: release, main
---------------------
* Uses 9 classes, 5 of which are shown: androidx.activity.OnBackPressedCallback, androidx.activity.OnBackPressedDispatcher, androidx.activity.result.ActivityResult, androidx.activity.result.ActivityResultCallback, androidx.activity.result.ActivityResultLauncher (implies implementation).
* Provides 1 lint registry: # (implies implementation).

Describe the bug A module in my Android Studio Kotlin project has the following dependency:

dependencies {
    ...
    implementation("com.google.android.material:material:1.13.0-alpha12")
    ...
}

./gradlew buildHealth produces the following output:

Advice for :app
These transitive dependencies should be declared directly:
  implementation("androidx.activity:activity:1.8.0")

If this dependency is only used by com.google.android.material:material, then why should I declare it directly?

To Reproduce I suppose, any project with this particular dependency would cause this problem.

Expected behavior No advice on declaring the dependency directly should be produced.

Additional context The project code is not publicly available yet, so I can't provide any links.

NOTE Exactly similar problems exist in my project for the following dependencies:

androidx.appcompat:appcompat:1.7.0 \ androidx.lifecycle:lifecycle-common:2.8.7

androidx.lifecycle:lifecycle-viewmodel-ktx:2.8.7 \ androidx.lifecycle:lifecycle-viewmodel:2.8.7

androidx.test.ext:junit:1.2.1 \ androidx.test:monitor:1.7.1

androidx.test.ext:junit:1.2.1 \ junit:junit:4.13.2

androidx.test.espresso:espresso-core:3.6.1 \ androidx.test:runner:1.6.1

androidx.test.espresso:espresso-core:3.6.1 \ org.hamcrest:hamcrest-core:1.3

com.google.android.material:material:1.13.0-alpha12 \ androidx.annotation:annotation:1.8.1

com.google.android.material:material:1.13.0-alpha12 \ androidx.coordinatorlayout:coordinatorlayout:1.1.0

com.google.android.material:material:1.13.0-alpha12 \ androidx.fragment:fragment:1.5.4

com.google.android.material:material:1.13.0-alpha12\ androidx.lifecycle:lifecycle-livedata-core:2.8.7

com.google.android.material:material:1.13.0-alpha12 \ androidx.viewpager2:viewpager2:1.1.0-beta02

com.google.android.play:app-update:2.1.0 ->com.google.android.gms:play-services-tasks:18.0.2

com.google.dagger:dagger:2.56.1 \ javax.inject:javax.inject:1

com.journeyapps:zxing-android-embedded:4.3.0 \ com.google.zxing:core:3.4.1

com.louiscad.splitties:splitties-views:3.0.0 \ com.louiscad.splitties:splitties-resources:3.0.0

com.louiscad.splitties:splitties-views:3.0.0 \ com.louiscad.splitties:splitties-systemservices:3.0.0

dev.chrisbanes.insetter:insetter:0.6.1 \ androidx.core:core:1.16.0

org.jetbrains.kotlinx:kotlinx-coroutines-android:1.10.2 \ org.jetbrains.kotlinx:kotlinx-coroutines-core:1.10.2

[autonomousapps]

Uses 9 classes, 5 of which are shown: androidx.activity.OnBackPressedCallback, androidx.activity.OnBackPressedDispatcher, androidx.activity.result.ActivityResult, androidx.activity.result.ActivityResultCallback, androidx.activity.result.ActivityResultLauncher (implies implementation).

[jolaf]

Sorry, could you please explain your answer?

[autonomousapps]

You asked "why." You also included the output of the reason task, which explains why. You are using several classes from the dependency in question. So therefore this question:

If this dependency is only used by com.google.android.material:material, then why should I declare it directly?

has a faulty premise. The dependency is not only used by the com.google.android.material lib.

[jolaf]

Oh, now I see, thank you!

I didn't understand what that "Uses" statement means without a subject.

[autonomousapps]

I didn't understand what that "Uses" statement means without a subject.

I'd be happy to update the text if there were a way to make it more clear to non-native English speakers. Any suggestions?

[jolaf]

Well, I'd say Shortest path is misleading. If the shortest path is through another dependency, then It's implied, from my perspective, that there's no direct usage.

I would probably move Uses/Provides section above the Shortest path section. Because if the package is used directly, paths through other dependencies are not that relevant.

Also I would add subject for clarity, like "Dependency androidx.activity:activity:1.8.0 uses" or "This source uses from dependency androidx.activity:activity:1.8.0", something like that.

[autonomousapps]

The shortest path is about how the dependency ends up on your classpath, it doesn't reflect usage of that dependency. Usage information is at the bottom.

I think it would make sense to rearrange those sections and put usage at top, which is more interesting anyway. And maybe also add more descriptive text to each section explaining the information being conveyed. Thanks for the feedback.