Introduce Gradle version catalog traits by KamilPatora · Pull Request #8376 · openrewrite/rewrite

KamilPatora · 2026-08-04T13:27:07Z

What's changed?

Added document, library, and plugin traits for TOML catalogs.
Supported string and inline-table dependency/plugin entries.
Coordinated shared version.ref updates.
Centralized TOML table lookup and string accessors.
Preserved TOML formatting during updates.
Added validation for malformed module notation and versionless entries.

What's your motivation?

Provide a reusable, formatting-preserving semantic model for Gradle version catalogs and enable safe dependency, plugin, and shared-version updates.

Anything in particular you'd like reviewers to focus on?

Probably whole pr

Anyone you would like to review specifically?

Have you considered any alternatives or workarounds?

We do have our open-source 'version' of openrewrite where we handle TOML values: https://github.com/allegro/allwrite

Any additional context

Added positive and negative coverage for custom catalog paths, missing version references, versionless notation, malformed coordinates, visitor composition, and TOML quote preservation.
Created from this PR #8274

Checklist

I've added unit tests to cover both positive and negative cases
I've read and applied the recipe conventions and best practices
I've used the IntelliJ IDEA auto-formatter on affected files

- Add document, library, and plugin traits for TOML catalogs - Support string and inline-table dependency/plugin entries - Coordinate shared version.ref updates - Centralize TOML table lookup and string accessors - Preserve TOML formatting during updates

shanman190 · 2026-08-08T17:59:55Z

+        /**
+         * Finds a top-level table with the supplied name.
+         *
+         * @param name the table name to find
+         * @return the matching table, or {@code null} when it is absent
+         */
+        public @Nullable Table findTable(String name) {
+            for (TomlValue value : values) {
+                if (!(value instanceof Table)) {
+                    continue;
+                }
+                Table table = (Table) value;
+                Identifier tableName = table.getName();
+                if (tableName != null && name.equals(tableName.getName())) {
+                    return table;
+                }
+            }
+            return null;
+        }


We don't normally put finders like this off of the LST model itself. When interacting with the LST model normally, you'd override the visitTable and interact with the named table that you're interested in.

gotcha, Im more or less rich domain guy. Doing 'table.find("version")' looks better for me than 'TomlTableValue.find(table, "version")' etc...

changed it

shanman190 · 2026-08-08T18:00:11Z

+        public @Nullable KeyValue find(String key) {
+            for (Toml value : getValues()) {
+                if (!(value instanceof KeyValue)) {
+                    continue;
+                }
+                KeyValue keyValue = (KeyValue) value;
+                if (!(keyValue.getKey() instanceof Identifier) ||
+                        !key.equals(((Identifier) keyValue.getKey()).getName())) {
+                    continue;
+                }
+                return keyValue;
+            }
+            return null;
+        }
+
+        public @Nullable String getString(String key) {
+            KeyValue keyValue = find(key);
+            if (keyValue == null || !(keyValue.getValue() instanceof Literal)) {
+                return null;
+            }
+            Object value = ((Literal) keyValue.getValue()).getValue();
+            return value instanceof String ? (String) value : null;
+        }


shanman190 · 2026-08-08T18:34:04Z

+     *       has neither a {@code version} nor a {@code version.ref} key, the {@code version} key is added.</li>
+     * </ul>
+     */
+    public Toml.KeyValue withCoordinatesAndVersion(


I think this may be better modeled as something like this:

GradleVersionCatalogDependency withGroup(String); GradleVersionCatalogDependency withName(String); GradleVersionCatalogDependency withModule(String); GradleVersionCatalogDependency withVersion(String);

This allows modifying the pieces in a chain.

Usage:

GradleVersionCatalogDependency dependency; Toml.KeyValue entry = dependency.withGroup("com.example") .withName("example-lib") .withVersion("1.0") .getValue()

shanman190 · 2026-08-08T18:38:12Z

+         * {@code with*} methods; the updated {@link Toml.KeyValue} should be used as the replacement
+         * value in the enclosing map operation.
+         */
+        public static @Nullable GradleVersionCatalogDependency extract(


This is already supported by the matcher and doesn't lose the ancestry.

shanman190 · 2026-08-08T18:59:35Z

+    public boolean hasUnsupportedVersionDeclaration() {
+        if (!(getTree().getValue() instanceof Toml.Table)) {
+            return false;
+        }
+        Toml.Table table = (Toml.Table) getTree().getValue();
+        return table.find("version") != null && version == null ||
+                table.find("version.ref") != null && versionRef == null;
+    }


This feels like something a recipe should be knowledgeable about reconciling when it manifests to achieve a correct end state that is logically consistent. As in I'm not sure that it belongs here.

shanman190 · 2026-08-08T19:15:00Z

+            return extractWithCursor(syntheticCursor, kv, groupPattern, artifactPattern);
+        }
+
+        private static @Nullable GradleVersionCatalogDependency extractWithCursor(


When we remove extract, then this can be inlined into test.

shanman190 · 2026-08-08T19:25:12Z

+        }
+
+        private static boolean matches(String pluginId, @Nullable String pattern) {
+            return StringUtils.isBlank(pattern) || matchesGlob(pluginId, pattern);


Suggested change

return StringUtils.isBlank(pattern) || matchesGlob(pluginId, pattern);

return pattern == null || matchesGlob(pluginId, pattern);

This matches consistently with what we do elsewhere.

shanman190 · 2026-08-08T19:47:42Z

+        private static boolean matchesPatterns(
+                @Nullable String groupId, @Nullable String artifactId,
+                @Nullable String groupPattern, @Nullable String artifactPattern) {
+            if (groupPattern != null && !matchesGlob(groupId, groupPattern)) {
+                return false;
+            }
+            return artifactPattern == null || matchesGlob(artifactId, artifactPattern);
+        }


This can be replaced with DependencyMatcher.

shanman190 · 2026-08-08T19:51:04Z

+     * Entries using {@code version.ref} are intentionally unchanged; their shared version
+     * entry is updated by the recipe after selecting a version.
+     */
+    public Toml.KeyValue withVersion(String newVersion) {


This benefits with a similar API as discussed in the dependency trait.

GradleVersionCatalogPlugin withVersion(String)

shanman190 · 2026-08-08T20:04:10Z

+    public Toml.KeyValue withVersion(String newVersion) {
+        if (newVersion.equals(version) || versionRef != null) {
+            return getTree();
+        }
+        Toml.KeyValue kv = getTree();
+        if (kv.getValue() instanceof Toml.Literal) {
+            Toml.Literal literal = (Toml.Literal) kv.getValue();
+            if (!(literal.getValue() instanceof String)) {
+                return kv;
+            }
+            Dependency dependency = DependencyNotation.parse((String) literal.getValue());
+            if (dependency == null) {
+                return kv;
+            }
+            String notation = DependencyNotation.toStringNotation(dependency.withGav(dependency.getGav().withVersion(newVersion)));
+            return kv.withValue(literal.withSource(TomlTableValue.quoted(literal, notation)).withValue(notation));
+        }
+        if (kv.getValue() instanceof Toml.Table) {
+            Toml.Table inline = (Toml.Table) kv.getValue();
+            return kv.withValue(inline.find("version") == null ?
+                    TomlTableValue.withStringOrAdd(inline, "version", newVersion) :
+                    TomlTableValue.withString(inline, "version", newVersion));
+        }
+        return kv;
+    }


I would imagine that these become simpler by reusing the TOML visitors, such as ChangeValue. There also exists DeleteKey and it's synonym AddKey/AddKeyVisitor (if we don't want a recipe right now) would likely be particularly useful.

Usage:

Toml.KeyValue keyValue = getValue(); Toml.KeyValue updated = new ChangeValue("version", newVersion).getVisitor().visitNonNull(entry, new InMemoryExecutionContext()); // this may need to come in as a method argument, but for now this is fine.

I think I got it, changed

shanman190 · 2026-08-08T20:06:16Z

Thanks @KamilPatora for the start on this! I've left some comments about various improvements. Let us know if you have any questions.

…move unsupported version checks

…hing logic

…n to enhance value updating logic and streamline key management

…updates and improve dependency matching logic

KamilPatora · 2026-08-18T08:12:56Z

Bump @shanman190 @timtebeek

KamilPatora · 2026-08-25T13:23:52Z

bump bump

timtebeek · 2026-08-25T21:48:17Z

I'm not getting to a review here @KamilPatora , and will be out for a prolonged time, so I've unassigned myself from review. Hoping my colleagues can step in.

KamilPatora · 2026-08-28T12:24:24Z

Sure @timtebeek , no worries. I've moved this PR to #8699
as here I did the PR from the main branch of the fork...

github-project-automation Bot added this to OpenRewrite Aug 4, 2026

github-project-automation Bot moved this to In Progress in OpenRewrite Aug 4, 2026

moderne-meeseeks Bot assigned KamilPatora Aug 4, 2026

KamilPatora mentioned this pull request Aug 4, 2026

4400 - gradle toml version catalogs #8274

Closed

Merge branch 'main' into main

5a8cec3

timtebeek requested review from shanman190 and timtebeek August 4, 2026 16:17

KamilPatora added 2 commits August 5, 2026 08:49

Enhance Gradle version catalog to handle resolution failures

f4c99db

Merge branch 'main' into main

bd01806

shanman190 reviewed Aug 8, 2026

View reviewed changes

timtebeek mentioned this pull request Aug 8, 2026

Support updating Gradle programmatic Version Catalogs #4852

Open

KamilPatora added 6 commits August 10, 2026 12:24

Refactor Gradle version catalog to use TomlTableValue for key retrieval

7fae459

Refactor Gradle version catalog to improve dependency matching and re…

336824a

…move unsupported version checks

Merge branch 'main' into main

67c74eb

Refactor GradleVersionCatalogDependency to streamline dependency matc…

4316b4a

…hing logic

Refactor GradleVersionCatalogDependency and GradleVersionCatalogPlugi…

28f4a6c

…n to enhance value updating logic and streamline key management

Refactor GradleVersionCatalogDependency to enhance module coordinate …

655b3d7

…updates and improve dependency matching logic

KamilPatora requested a review from shanman190 August 10, 2026 12:44

KamilPatora added 2 commits August 10, 2026 15:42

Merge branch 'main' into main

ef6e532

Merge branch 'main' into main

c65969e

Merge branch 'main' into main

5e64183

timtebeek removed their request for review August 25, 2026 21:47

KamilPatora closed this Aug 28, 2026

github-project-automation Bot moved this from In Progress to Done in OpenRewrite Aug 28, 2026

KamilPatora mentioned this pull request Aug 28, 2026

Kamil/gradle version catalog traits #8699

Open

3 tasks

	return StringUtils.isBlank(pattern) \|\| matchesGlob(pluginId, pattern);
	return pattern == null \|\| matchesGlob(pluginId, pattern);

Uh oh!

Conversation

KamilPatora commented Aug 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What's changed?

What's your motivation?

Anything in particular you'd like reviewers to focus on?

Anyone you would like to review specifically?

Have you considered any alternatives or workarounds?

Any additional context

Checklist

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

shanman190 commented Aug 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

KamilPatora commented Aug 18, 2026

Uh oh!

KamilPatora commented Aug 25, 2026

Uh oh!

timtebeek commented Aug 25, 2026

Uh oh!

KamilPatora commented Aug 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

KamilPatora commented Aug 4, 2026 •

edited

Loading

shanman190 commented Aug 8, 2026 •

edited

Loading

KamilPatora commented Aug 28, 2026 •

edited

Loading