FR: Plugin suggests explicit versions when using a Platform for central version management

[loetifuss]

Problem Description

When using Gradle's Java Platform plugin for centralized version management, the projectHealth task suggests adding dependencies with explicit versions, even though the versions should be managed centrally through the platform.

This defeats the purpose of using a platform for centralized dependency version management and can lead to version conflicts or inconsistencies.

Current Behavior

See attached demo project:
dependency-analysis.zip

Setup:

• A multi-module Gradle project with:
  • A platform module using the java-platform plugin to define version constraints
  • An app module that depends on the platform and declares dependencies without versions

Platform module (platform/build.gradle):

plugins {
    id 'java-platform'
    id 'com.autonomousapps.dependency-analysis'
}

dependencies {
    constraints {
        api 'org.apache.commons:commons-lang3:3.12.0'
        api 'com.google.guava:guava:33.5.0-jre'
        api 'org.slf4j:slf4j-api:2.0.9'
    }
}

App module (app/build.gradle):

plugins {
    id 'java-library'
    id 'com.autonomousapps.dependency-analysis'
}

dependencies {
    implementation platform(project(':platform'))
    implementation 'com.google.guava:guava'  // No version - managed by platform
}

Code using transitive dependency (app/src/main/java/com/example/Foo.java):

package com.example;

import com.google.common.annotations.Beta;
import com.google.common.util.concurrent.internal.InternalFutures;
import org.jspecify.annotations.NonNull;

public class Foo {
    @NonNull
    @Beta
    String bar() {
        InternalFutures.tryInternalFastPathGetFailure(null);
        return "Hello World";
    }
}

Project Health Report Output:

These transitive dependencies should be declared directly:
  implementation 'com.google.guava:failureaccess:1.0.3'

Expected Behavior

The projectHealth task should detect that versions are managed through a platform and suggest dependencies without explicit versions:

These transitive dependencies should be declared directly:
  implementation 'com.google.guava:failureaccess'

Why This Matters

1. Version Management Consistency: Using explicit versions in consuming modules bypasses the platform's version constraints, creating potential version conflicts
2. Maintainability: One of the main benefits of using a platform is having a single source of truth for all dependency versions
3. Best Practices: Gradle's official documentation recommends managing versions through platforms, and the advice should align with this best practice

Proposed Solution

The plugin should:

1. Detect when a project uses a platform(...) dependency
2. Check if the suggested dependency's version is defined in the platform's constraints
3. If yes, suggest the dependency declaration without an explicit version

Alternatively, as a quick fix a flag could be added to suggest dependencies without versions

[autonomousapps]

Thanks for the issue. This is an interesting idea, but unfortunately I cannot prioritize it right now, unless someone decides to sponsor the work. PRs are welcome, of course.

---

Unrelated to the above, I have recently added a Code of Conduct. There is now an explicit prohibition on use of LLMs for issues or PRs. Since this issue predates the code of conduct, I will not close the issue. But in the future, issues that are in whole or in part generated with LLMs, or which contain LLM "analysis," will be summarily closed. I understand this might be considered extreme, but I am simply protecting myself. Thank you for your understanding.

[loetifuss]

OK, fair enough :-)
In hindsight the AI "analysis" seems indeed a bit patronising.

[loetifuss]

@autonomousapps

Together with @jjohannes I started working on a PR for this, it could be supported by a new flag printVersions:
see 1a49d89.

While writing tests for this I noticed that changes in scope (e.g. api->implementation) for an existing dependency are not printed in the advice if the version differs. Is this intended behaviour? If not, I could try to fix it by comparing dependencies without versions for change/removal.

Can be reproduced using this test:

@Test fun `prints versions for added and changed`() {
    val sourceFile = dir.resolve("build.gradle")
    sourceFile.writeText(
      """
      dependencies {
        api 'x:y:1.0'
      }
    """.trimIndent()
    )
    val advice = setOf(
      Advice.ofChange(Coordinates.of("x:y:2.0"), "api", "implementation"),
      Advice.ofAdd(Coordinates.of("c:d:3.0"), "implementation")
    )

    val parser = GroovyBuildScriptDependenciesRewriter.of(
      sourceFile,
      advice,
      AdvicePrinter(
        dslKind = DslKind.GROOVY,
        projectType = projectType,
        useTypesafeProjectAccessors = false,
      ),
    )

    assertThat(parser.rewritten().trimmedLines()).containsExactlyElementsIn(
      """
      dependencies {
        implementation 'x:y:2.0'
        implementation 'c:d:3.0'
      }
    """.trimIndent().trimmedLines()
    ).inOrder()
  }

Here, the change from api to implementation is not printed for 'x:y:2.0'.

See also:
loetifuss@70bc218#diff-51836c69c0bd01d00a09f524ec1bc0da57ac0fb72c3e6b811fa85b4a7eaf2504R671-R704

[autonomousapps]

I'm not sure about this printVersions API. It's not quite the same thing as only omitting "managed" versions. Quite a lot simpler to implement, but I'm not sure it's the right approach.

Out of curiosity, do you use version catalogs? If not, why not? If you did, then you wouldn't generally "see" the version information, since the plugin would print the version catalog identifier instead of the GAV.

While writing tests for this I noticed that changes in scope (e.g. api->implementation) for an existing dependency are not printed in the advice if the version differs. Is this intended behaviour?

I don't think that's exactly intentional, but there's something similar around versions that is (albeit slightly annoying). I forget exactly why it's done, but I think that if you changed that behavior, you'd see some tests fail. I can't find where that's happening right now.