Gradle version catalogs: one model for settings and TOML

[jkschneider]

What's changed?

UpgradeDependencyVersion upgrades libraries declared in a Gradle version catalog, whether the
catalog is a dependencyResolutionManagement { versionCatalogs { ... } } block in
settings.gradle(.kts) or a gradle/libs.versions.toml file.

This brings together #8503 and #8699, which each modeled one of those. The first two commits are
those PRs squashed with their authors' attribution intact; the third reconciles them.

The model

VersionCatalog              the concept; how new versions are placed lives here
├─ SettingsVersionCatalog   declared in settings.gradle(.kts)      (package private)
└─ TomlVersionCatalog       declared in gradle/libs.versions.toml  (package private)
VersionCatalogLibrary       one [libraries] entry in a TOML catalog
VersionCatalogPlugin        one [plugins] entry in a TOML catalog

VersionCatalog.Matcher finds a catalog in either form, the way SpringBean.Matcher in
rewrite-spring finds a bean whether it is an XML <bean> or a @Bean method. A recipe starts from
one new VersionCatalog.Matcher().asVisitor(...) and gets a catalog at a libs { ... } call or at
a *.versions.toml document; the visitor it returns only accepts Gradle scripts and versions
files, so nothing else is walked. That is what UpgradeDependencyVersion now does, in place of a
TOML visitor plus a branch inside its script visitor. The two implementations are package private,
since the matcher is the way to one and neither is worth supporting as public API.

VersionCatalog reads as getLibraryVersions, getPluginVersions, getVersionDeclarations and
getVersion, and is edited through withVersions. Each implementation supplies the contents and
three primitive edits (set a library's own version, detach a library from a shared declaration, set
a declaration's value). The recipe selects a new version for each matching library and hands the
whole map to withVersions, the same for either kind of catalog.

The TOML entry traits edit their entries directly through TomlTableValue instead of running the
ChangeValue and DeleteKey recipes over them, which had left Changed markers on the tree.
TomlTableValue.withKey renames a property in place, so version.ref = "x" becomes
version = "1.2" with the entry's padding, commas and quote style intact, mirroring what the
settings side does with versionRef(...) and version(...).

Sharing

Where new versions go is decided once, on VersionCatalog, from everything a run is moving. A
shared version declaration changes in place when every entry referring to it is a library moving to
the same version; otherwise only the libraries that are moving get a version of their own, and the
declaration stays for the ones that are not. A recipe whose glob matches every sharer bumps the
declaration; a recipe matching one of them detaches that one.

A plugin can share a declaration with libraries, in the [plugins] table or as
plugin(alias, id).versionRef(...) in the settings DSL. A declaration a plugin refers to is never
moved, since this recipe moves no plugins, and the libraries that are moving detach instead.

#8503 produced the same results within a run and additionally across runs, by remembering the
original sharing in a marker it added during the run. That marker is gone here. Adding a marker at
run time changes the tree without changing the source, so a file reads as changed with nothing to
show for it, and nothing carries over between runs in any case. Two independent recipes each
targeting one sharer therefore do not converge on the shared declaration together: the first
detaches its library, and the last, finding its library is the declaration's only remaining
referrer, moves the declaration itself. Nothing is left stale, and the sequential tests from #8503
now assert that outcome.

Naming

A version catalog is a Gradle concept, so a Gradle prefix on the types said nothing. The two
implementations are named for where the catalog is declared, and the entry traits after the
tables they represent.

Repositories for a TOML catalog

A TOML document carries no GradleProject marker, so on its own it has nothing to resolve
latest.release or 30.x against. The scanner keeps the root project's marker if it is scanned
and otherwise the first one seen, and the catalog pass resolves with that project's repositories.
GradleSettings is deliberately not consulted: its repositories are the ones plugins resolve from,
so a library lookup through it would go to the wrong place. A settings-script catalog on a
settings file without a project marker resolves the same way. The symbolic-version test in
UpgradeDependencyVersionTomlCatalogTest exercises this through the tooling API, as #8503's did
for the settings form.

A library whose metadata can't be downloaded is left alone and the catalog is marked with the
MavenDownloadingException, as a dependency declared in a script already is. Only a catalog
carrying no warning gets one, because a repeated download failure reports itself differently the
second time around and the recipe would otherwise never stabilize.

Testing

VersionCatalogTest matches a settings catalog and a TOML catalog in one run through the one
matcher and reads a versionRef'd version from each. UpgradeDependencyVersionTomlCatalogTest
covers inline versions, string notation, detaching one of two sharers, bumping the shared
declaration when a glob matches both, a declaration a plugin shares, two sequential recipes leaving
the declaration to its last referrer, a symbolic version resolved through the build's repositories,
a library whose metadata can't be downloaded, and leaving a non-catalog TOML file alone. #8503's
UpgradeDependencyVersionVersionCatalogTest passes with its two sequential cases asserting the
behavior above and gains the plugin-sharing case in both DSLs, SettingsVersionCatalogTest
without its marker case, and #8699's trait tests unchanged apart from the renames and one case:
withGroupThenWithModuleUsesUpdatedSemanticCoordinate chained edits that netted out to the
original text, and it only passed single-cycle because the Changed markers short-circuited the
second cycle. It now chains to a real change. The full rewrite-gradle and rewrite-toml suites
pass.

Supersedes #8503 and #8699.

[shanman190]

Indentation seemed to get off here.

[kdvolder]

This is wrong, it should 'revert' back to using 'widgetVersion'.

[kdvolder]

Should use 'widgetVersion'