feat: Improve the matching of required versions

[nielsbasjes]

@cstamas Followup of this discussion on Slack https://the-asf.slack.com/archives/C7Q9JB404/p1773056234905829?thread_ts=1773053661.648449&cid=C7Q9JB404

When people write in (for example) the maven-invoker-plugin something like invoker.toolchain.jdk.version = 11 it is implemented as an exact match on the mentioned version specified in the toolchains.xml .
Historically people would write this config manually and then the exact version 11 works as expected.

With the automatic generation of the toolchains.xml more places will contain the full version of the JDK like <version>11.0.29</version> instead of the more simple <version>11</version>.

The effect of people using these automatically generated toolchains.xml files is that now things still work as designed, but not as expected.

This is a quick implementation of my proposal to simply treat the requirement of a single number X as "the major version must be X".
I have also included the same for a "major.minor" requirement to accept all patch versions under that also.

This means a change from a mismatch to a match in cases like this:

matcher = RequirementMatcherFactory.createVersionMatcher("1.5.2");
matcher.matches("1.5");

I'm unsure if this change is "too breaking" to be implemented.

Following this checklist to help us incorporate your contribution quickly and easily:

• Your pull request should address just one issue, without pulling in other changes.

• Write a pull request description that is detailed enough to understand what the pull request does, how, and why.

• Each commit in the pull request should have a meaningful subject line and body.
  Note that commits might be squashed by a maintainer on merge.

• Write unit tests that match behavioral changes, where the tests fail if the changes to the runtime are not applied.
  This may not always be possible but is a best-practice.

• Run mvn verify to make sure basic checks pass.
  A more thorough check will be performed on your pull request automatically.

• You have run the Core IT successfully.

• I hereby declare this contribution to be licenced under the Apache License Version 2.0, January 2004

• In any other case, please file an Apache Individual Contributor License Agreement.

[cstamas]

Take a peek at "counter pr" #11786

[gnodet]

Claude Code on behalf of Guillaume Nodet

Nice idea to make toolchain version matching more lenient for the auto-generated toolchains.xml use case. Two issues I spotted:

1. Regex bug: The major.minor pattern only allows a single-digit major version, so "21.3" would not match. Needs [0-9]+ for the major part too.
2. Pattern precompilation: As @slawekjaranowski already noted, the patterns should be compiled once into static fields.
3. Missing test coverage: No tests for multi-digit major versions (e.g., requirement "21" against version "21.0.2", or "21.3" against "21.3.1").

[gnodet]

Bug: the major version part is [0-9] (single digit only), so a requirement like "21.3" would silently fall through to the default path and be treated as an exact match. It should be [0-9]+ to mirror the first pattern.

Suggested change

	if (Pattern.matches("^[0-9]\\.[0-9]+$", requirement)) {
	if (Pattern.matches("^[0-9]+\\.[0-9]+$", requirement)) {

Also, as @slawekjaranowski mentioned, both patterns should be pre-compiled into private static final Pattern fields to avoid recompilation on every call.

[nielsbasjes]

Yes, good catch. Fixed.

[gnodet]

Review Summary

This PR improves toolchain version requirement matching so that a simple requirement like "11" matches version "11.0.29", and "1.5" matches "1.5.2". This is a reasonable enhancement motivated by auto-generated toolchains.xml files containing full JDK versions.

However, there are several issues that need addressing — most of which were already flagged by @slawekjaranowski and @gnodet in their earlier reviews.

Issues

1. Regex bug — multi-digit major versions don't match (critical)
The major.minor pattern on line 96 uses [0-9] (single digit) instead of [0-9]+ for the major version:

Pattern.matches("^[0-9]\\.[0-9]+$", requirement)

A requirement like "21.3" won't match this pattern and will fall through to exact-match behavior — which is the most common real-world scenario (JDK 11, 17, 21, 25). The major-only pattern on line 89 correctly uses [0-9]+.

(Already noted by @gnodet on 2026-05-21)

2. Pattern precompilation (major)
Both Pattern.matches() calls recompile the regex on every invocation. These should be extracted to private static final Pattern fields:

private static final Pattern MAJOR_ONLY = Pattern.compile("[0-9]+");
private static final Pattern MAJOR_MINOR = Pattern.compile("[0-9]+\\.[0-9]+");

(Already noted by @slawekjaranowski on 2026-04-20 and @gnodet on 2026-05-21)

3. Missing test coverage for multi-digit versions (major)
The test only uses version "1.5.2" (single-digit major). There are no test cases with multi-digit versions like "21.0.2", which would expose the regex bug above. @gnodet's suggested test additions from 2026-05-21 would cover this gap.

Note

This review reinforces the feedback already provided by @slawekjaranowski and @gnodet. The existing review comments contain concrete suggestions — addressing them would make this PR ready for another look.

---

This review was generated by an AI agent and may contain inaccuracies. Please verify all suggestions before applying.

Claude Code on behalf of Guillaume Nodet

[gnodet]

The version-matching improvement looks useful — prefix matching for major-only and major.minor requirements is a nice addition. However, there is a regex bug that breaks the most common modern JDK versions (11, 17, 21, 25), plus a few minor items.

Verified findings (2 of 6 original findings were false positives removed):

1. Regex bug (high) — The major.minor pattern ^[0-9]\.[0-9]+$ only matches single-digit major versions. Requirements like "21.3" or "17.0" won't get prefix-matching behavior. The major-only pattern correctly uses [0-9]+.
2. Pattern precompilation (low) — Pattern.matches() recompiles the regex on every call. Pre-compiling to private static final Pattern fields would be cleaner, though this is not a hot path. (Already noted by @slawekjaranowski.)
3. Missing test coverage (medium) — Tests only use version "1.5.2" (single-digit major). Adding a test with e.g. "21.0.2" and requirements "21" / "21.3" would immediately expose the regex bug.
4. Static method (low) — convertRequirementToVersionRange doesn't reference instance state and could be static. Very minor.

This review was generated by an AI agent and may contain inaccuracies. Please verify all suggestions before applying.

Claude Code on behalf of gnodet

[gnodet]

Consider adding test cases with multi-digit major versions to cover the regex bug above. For example:

matcher = RequirementMatcherFactory.createVersionMatcher("21.0.2");
assertTrue(matcher.matches("21"));    // Major-only
assertTrue(matcher.matches("21.0"));  // Major.minor
assertFalse(matcher.matches("17"));   // Wrong major

This would immediately expose the single-digit regex limitation.

[gnodet]

Re-review after commit f4fdc9b ("fix: Compile regexes only once")

The pattern precompilation is a good improvement — thanks for addressing that feedback. However, the regex bug flagged in all three prior reviews is still present:

PATTERN_MAJOR_MINOR_VERSION uses [0-9] (single digit) for the major version instead of [0-9]+. This means requirements like "21.0", "17.0", and "11.0" silently fall through to exact-match behavior — exactly the modern JDK versions this feature is meant to help with.

The fix is a single character — adding + after [0-9] on line 85. The major-only pattern on line 84 already uses [0-9]+ correctly.

Also, the test suite only uses "1.5.2" (single-digit major), so it doesn't catch this. Adding a test with e.g. "21.0.2" would immediately expose it.

This review was generated by an AI agent and may contain inaccuracies. Please verify all suggestions before applying.

Claude Code on behalf of gnodet

[gnodet]

This still uses [0-9] (single digit) for the major version. Requirements like "21.0" or "17.0" won't match this pattern. Compare with PATTERN_MAJOR_VERSION on the line above which correctly uses [0-9]+.

Suggested change

	private static final Pattern PATTERN_MAJOR_MINOR_VERSION = Pattern.compile("^[0-9]\\.[0-9]+$");
	private static final Pattern PATTERN_MAJOR_MINOR_VERSION = Pattern.compile("^[0-9]+\\.[0-9]+$");

[nielsbasjes]

You're quick :)
I was going through the comments step by step.
Just fixed this.

Also note that the AI generated improvement is incorrect (missing '^' and '$'):

private static final Pattern MAJOR_ONLY = Pattern.compile("[0-9]+");
private static final Pattern MAJOR_MINOR = Pattern.compile("[0-9]+\\.[0-9]+");

[gnodet]

Re-review after commit 8c439aa ("fix: Regex bug not supporting multi digit major versions")

All previously flagged issues are now resolved:

1. ✅ Regex bug fixed — PATTERN_MAJOR_MINOR_VERSION now correctly uses [0-9]+ for the major version, matching the already-correct PATTERN_MAJOR_VERSION pattern.
2. ✅ Multi-digit test coverage added — new testCreateVersionMatcherMultiDigit test with "11.55.22" would have caught the original bug.
3. ✅ Pattern precompilation — patterns extracted to private static final fields.

Looks good to merge. 🎉

This review was generated by an AI agent and may contain inaccuracies. Please verify all suggestions before applying.

Claude Code on behalf of gnodet