Skip to content

Improve dependency scope validation error messages for import scope #10991

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: master
Choose a base branch
from

Conversation

gnodet
Copy link
Contributor

@gnodet gnodet commented Jul 23, 2025

Summary

This PR improves Maven's dependency scope validation error messages to provide clearer guidance when the import scope is used incorrectly.

Problem

Currently, when a user incorrectly uses import scope in a regular <dependencies> section, Maven shows a confusing error message:

'dependencies.dependency.scope' must be one of [provided, compile, runtime, test, system] but is 'import'.

This message is misleading because it suggests that import scope is never valid, when in fact it is valid in <dependencyManagement> sections with <type>pom</type>.

Solution

The PR enhances the error message to provide context-aware guidance:

'dependencies.dependency.scope' has scope 'import'. The 'import' scope is only valid in <dependencyManagement> sections.

Key Improvements:

  1. Context-aware validation: Different error messages for regular dependencies vs. dependency management
  2. Clear guidance: Explicitly tells users where import scope is valid
  3. Focused messaging: Removes confusing list of valid scopes and focuses on the specific problem
  4. Consistent implementation: Applied to both Maven 3 (compat) and Maven 4 (impl) for consistency

Changes Made

Core Changes

  • Added validateDependencyScope() method in both implementations that provides context-aware error messages
  • Enhanced error messages with specific guidance for import scope misuse
  • Maintained backward compatibility - only error messages are improved, no functional changes

Files Modified

  • compat/maven-model-builder/src/main/java/org/apache/maven/model/validation/DefaultModelValidator.java
  • compat/maven-model-builder/src/test/java/org/apache/maven/model/validation/DefaultModelValidatorTest.java
  • impl/maven-impl/src/main/java/org/apache/maven/impl/model/DefaultModelValidator.java
  • impl/maven-impl/src/test/java/org/apache/maven/impl/model/DefaultModelValidatorTest.java

Additional Improvements

  • Fixed grammar in comments (don'tnot)
  • Updated tests to verify the improved error messages
  • Applied spotless formatting for code consistency

Example Impact

This change helps users quickly understand how to fix their Maven configuration:

❌ Incorrect usage (triggers new helpful error):

<dependencies>
  <dependency>
    <groupId>org.example</groupId>
    <artifactId>bom</artifactId>
    <version>1.0</version>
    <type>pom</type>
    <scope>import</scope>  <!-- ❌ Invalid here -->
  </dependency>
</dependencies>

✅ Correct usage:

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.example</groupId>
      <artifactId>bom</artifactId>
      <version>1.0</version>
      <type>pom</type>
      <scope>import</scope>  <!-- ✅ Valid here -->
    </dependency>
  </dependencies>
</dependencyManagement>

Related Issues

Addresses the confusion reported in faktorips/faktorips.base#70

Testing

  • ✅ All existing tests pass (161 tests, 0 failures)
  • ✅ Updated tests verify the improved error messages
  • ✅ Code compiles successfully with JDK 21
  • ✅ Spotless formatting applied
  • ✅ No checkstyle violations

The validation logic remains unchanged - only the error messages are enhanced to be more helpful and educational.

@gnodet gnodet force-pushed the improve-dependency-scope-validation-messages branch from c8519ab to 5d2db36 Compare July 23, 2025 10:20
- Enhance error message when 'import' scope is used incorrectly in regular dependencies
- Provide clear guidance that 'import' scope is only valid in <dependencyManagement> sections
- Replace generic error message with context-aware validation
- Update both Maven 3 (compat) and Maven 4 (impl) implementations for consistency
- Update tests to verify the improved error messages
- Fix grammar in comments (don't -> not)
- Apply spotless formatting

Before: 'dependencies.dependency.scope' must be one of [provided, compile, runtime, test, system] but is 'import'.
After:  'dependencies.dependency.scope' has scope 'import'. The 'import' scope is only valid in <dependencyManagement> sections.

This addresses the confusion reported in faktorips/faktorips.base#70
where users receive misleading error messages that suggest 'import' scope is never valid,
when it's actually valid in dependency management sections with type=pom.
@gnodet gnodet force-pushed the improve-dependency-scope-validation-messages branch from 6c749dc to 3647fe8 Compare July 23, 2025 14:12
@cstamas
Copy link
Member

cstamas commented Aug 5, 2025

The deprecated code and impl code is diverging (like new maven4 scopes cannot be validated with deprecated code). If this is not a concern, am ok.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants