Build library with Java version specified in .tool-versions

[rtyley]

This allows projects to specify, with an asdf-formatted .tool-versions file, the Java version to be used by the workflow for building the project- gha-scala-library-release-workflow has always used a recent LTS version Java for the build (eg Java 17), and this has sometimes been too recent for some projects at the Guardian.

We want projects to update to Java 21 (see guardian/support-frontend#5792, guardian/scala-steward-public-repos#67 etc), but tying dozens of projects tightly to what gha-scala-library-release-workflow is using will make updating that version pretty hard. If, at some later point, some projects want to experiment with Java 25, we shouldn't have to force all other projects to be compatible with that first.

How to express the version of Java required...

Configuration proliferation is a problem...

One option would have been to simply add a new input parameter to the workflow, specifying the required Java version, but that has a downside: it proliferates the number of places in a project where the desired Java version is declared - and there are many in use at the Guardian, with no well-agreed canonical source-of-truth:

• GHA ci.yml, in the java-version field of actions/setup-java - this has been my favourite in the past, as whatever CI runs with is usually pretty close to the truth
• In sbt, the scalacOptions of -target, -release, -java-output-version (currently -release preferred, tho' once support is pervasive, -java-output-version is probably best) and the javacOptions of -target & -source - these all effectively set lower-bounds on the version of Java supported, rather than guaranteeing a minimum upper bound of Java version the way CI does.
• In apps running on Amigo AMI images; the Java version baked into the AMI, usually referenced by riff-raff.yaml
• In AWS Lambdas; the cloudformation Runtime parameter, often set by CDK

...asdf's .tool-versions flle offers some consolidation

Benefits of using .tool-versions:

• Developers will automatically get the right Java version if they have asdf installed
• Added .tool-versions file support actions/setup-java#606 has added early support for reading the version of Java used in CI by setup-java from the .tool-versions flle - unfortunately, it's of limited use to us at the moment because of java-version-file with asdf's .tool-versions fails for Corretto, also non-strict semver versions actions/setup-java#615, but it's a promising start (setup-java also has support for jEnv files, but they are not commonly used at the Guardian)
• Format of the file is simple enough that it can be easily understood and used, even if asdf is not in use - including the file doesn't force developers to use asdf (I know some devs have been having some problems with it, and maybe there are/will be better alternatives out there), but it clearly documents the Java version to be used.

This does mean that all library repos need to add a .tool-versions file before this PR is merged. Helpful error messaging has been added with this PR to handle cases where the file is missing or invalid:

Only Java major version is guaranteed

Note that although asdf requires a fully-specified Java version (eg 21.0.3.9.1) in the .tool-versions file, currently the workflow will only match the major version of Java specified in the file (eg 21), and will always use the AWS Corretto distribution of Java. This is due to limitations in actions/setup-java.

[rtyley]

This regex has been manually checked by running it on the output of asdf list-all java (1238 versions), ie:

asdf list-all java | sed -e 's/^/java /' | grep -Eo 'java [[:alnum:]-]+-[[:digit:]]+' | rev | cut -d'-' -f1 | rev > major-java-versions.csv

The spreadsheet of the results is here - a quick skim through doesn't show any obvious problems to me.