Update Regex to Support All ASDF Versions for the supported distributions in tool-versions File

[aparnajyothi-y]

Description:
This Pull request improves the regex pattern used in the tool-versions file to ensure compatibility with all ASDF versions across the supported distributions. The goal is to provide better flexibility and robustness when parsing tool version entries, handling variations in version formats more effectively.

Related issue:
#719

Check list:

• [ ✔️] Mark if documentation changes are required.

[rnorth]

@aparnajyothi-y we'd be very excited to see this get released - is there anything we can do to help? (testing?)

It looks like there's currently a check failing but it's apparently hitting a GitHub API rate limit. Presumably unrelated to the actual changes though:

Fetching version info for GraalVM EA builds from 'https://api.github.com/repos/graalvm/oracle-graalvm-ea-builds/contents/versions/24-ea.json?ref=main' failed with the error: API rate limit exceeded for 13.105.117.124. (But here's the good news: Authenticated requests get a higher rate limit. Check out the documentation for more details.)

[aparnajyothi-y]

Hello @rnorth, thank you again for your continued interest and support!

We’ve completed the regex and documentation updates, aiming for broad coverage of the formats in your test suite while clearly documenting known limitations such as jetbrains-21b212.1. As discussed earlier, we’ve prioritized maintainability and clarity over overfitting the regex to rare edge cases.

The recent failures appear to be caused by unauthenticated GitHub API rate limits and are unrelated to the core changes in this PR. That said, we’d greatly appreciate your feedback on whether the updated pattern works well against your test cases.

Please let us know if the current implementation meets your expectations so we can proceed with the review and merging process.

[rnorth]

Thanks @aparnajyothi-y

It looks like you've changed the regex a few times over the past few weeks, so I thought I should test it out.

I've tried the updated regex (source link):

/^java\s+(?:\S*-)?(?<version>\d+(?:\.\d+){0,2}(?:[+_]\d+)?)(?=(?:[-_](?!\d))|$)(?:[-_.](?:ea|LTS|beta|snapshot|internal|b\d+|\d+[a-z]*))*$/im;

I've tried this with @annettejanewilson's helpful jq command and by hand - unfortunately it seems like it's failing to match things like java temurin-21.0.0+35.0.LTS (or any other Temurin 21 releases).

Temurin is one of the most mainstream distributions, and 21 the most recent LTS version of it - so I'd say this is not just an edge case, but possibly one of the most important distribution versions to be able to match.

There are some other distribution/versions that fail to match that seem highly likely to catch people out:

• LTS versions of adoptopenjdk
• Any version of corretto

So I think it's unfortunate but the regex's changes since @annettejanewilson's comments seem to have reduced its coverage. 😬 I don't know the reasons for the changes, but they feel like a regression.

I'm wondering separately: looking at all the src/distributions/*/installer.ts files, it looks like after all this regex work is done there's corresponding code that has to convert the versions back into what seems like the original string from the .tool-versions file. I haven't got time to try it right now but maybe there's an obvious alternative way to approach this: parse the .tool-versions file just enough to get the distribution name, and then give the whole raw version part to the relevant installer.ts *Distribution to find and install. Maybe this should be considered if there are conflicting constraints stopping regex from working...

[aparnajyothi-y]

Hello @rnorth, Thanks for the thoughtful suggestion! We agree that splitting regex logic by distribution would improve readability and long-term maintainability. For now, we’ve updated the existing regex to support all known version formats across distributions, which addresses the immediate issue with minimal impact.

We acknowledge that the proposed refactor—maintaining a distribution-specific regex map and cleaner handling is a valuable direction. However, it would require broader testing and prioritization. We’ll consider it for a future iteration as we continue to refine the version resolution logic.
please feel free to reach us in case of any concerns/clarifications needed :)

[aparnajyothi-y]

Hello @rnorth, Please validate the above and let us know if you have any issues/clarifications needed.

[rnorth]

Thanks @aparnajyothi-y and I'm sorry for being slow to reply.

Yes, I've tried the new regex again with @annettejanewilson's jq command and it looks good to me - very broad coverage of the ASDF versions list. Thanks for your work on this!

[Copilot]

Pull Request Overview

This PR updates the regex pattern for parsing Java versions from .tool-versions files to improve compatibility with all ASDF versions and handle a wider variety of version formats. The change aims to better support different distribution naming schemes and version patterns.

Key changes:

• Replaces the existing regex pattern with a more flexible one that can handle complex version strings
• Adds documentation explaining the limitations and recommendations for version formatting
• Includes case-insensitive matching for improved parsing

Reviewed Changes

Copilot reviewed 2 out of 4 changed files in this pull request and generated 4 comments.

File	Description
src/util.ts	Updates the regex pattern for parsing Java versions from .tool-versions files to support more ASDF version formats
docs/advanced-usage.md	Adds documentation about supported version formats and notes limitations with complex version strings

[Copilot]

The regex pattern is extremely complex and hard to read/maintain. Consider breaking it down into smaller, named components or using multiple regex patterns with clear comments explaining each part's purpose.

[rnorth]

I'm itching to see this in a released version - is there an ETA?
Thank you 🙇