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

[slawekjaranowski]

We can move pattern compile to static filed

[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.

[gnodet]

Consider adding tests for multi-digit major versions to catch the regex bug above, e.g.:

matcher = RequirementMatcherFactory.createVersionMatcher("21.0.2");
assertTrue(matcher.matches("21"));     // major-only
assertTrue(matcher.matches("21.0"));   // major.minor
assertFalse(matcher.matches("21.1")); // wrong minor
assertFalse(matcher.matches("2"));     // wrong major

[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