Fix version catalog data loss and string corruption from comments and quotes (#3042)

Author: nedtwigg

CHANGES.md

@@ -11,6 +11,10 @@ We adhere to the [keepachangelog](https://keepachangelog.com/en/1.0.0/) format (
 
 ## [Unreleased]
 
+### Fixed
+- `VersionCatalogStep` preserves entries when comments contain unmatched brackets, preserves commas inside quoted strings, and keeps significant line boundaries in multiline entries. ([#3042](https://github.com/diffplug/spotless/pull/3042))
+- `VersionCatalogStep` now reports unfinished entries as lints at their starting line. These fail formatting by default, so upgrading may expose catalog errors that previously caused silent data loss. ([#3042](https://github.com/diffplug/spotless/pull/3042))
+
 ## [4.10.2] - 2026-09-04
 ### Fixed
 - `ShortenFullyQualifiedTypesStep` now shortens fully-qualified types used in expression contexts (such as static method calls, static fields, and enum constants) while avoiding imports that would change how existing unqualified type references resolve. ([#3039](https://github.com/diffplug/spotless/pull/3039))

lib/src/main/java/com/diffplug/spotless/toml/TODO.md

@@ -11,6 +11,10 @@ Tracked issues found during review against the TOML v1.1.0 spec (https://toml.io
 - [x] Multi-line inline tables are not parsed correctly (split across lines and corrupted)
 - [x] Long lines can be split into multi-line inline tables (configurable `maxLineLength`)
 - [x] Short multi-line inline tables are joined into single lines when they fit
+- [x] Commas inside literal strings and triple-quoted strings are preserved by `splitTopLevel`
+- [x] Escaped backslashes before closing quotes no longer confuse `splitTopLevel`
+- [x] Single-line strings cannot consume following entries across a newline; unfinished
+      entries report a lint at their starting line instead of returning a partial catalog
 
 ## TODO — TOML spec edge cases
 
@@ -27,10 +31,9 @@ addressed for full TOML spec compliance.
       (`[section.subsection]`) and quoted table headers (`["quoted.key"]`).
       Their entries are silently dropped.
 
-### String handling in `splitTopLevel`
+### Scanner and formatting improvements
 
-- [ ] Single-quoted (literal) strings `'...'` are not recognized — commas or `=` inside
-      them will incorrectly split or match.
-- [ ] Multiline string delimiters (`"""`, `'''`) confuse the single-char quote toggle.
-- [ ] Double-backslash before closing quote (`"value\\"`) is misidentified as an escaped
-      quote. Needs odd/even backslash counting instead of single-char lookbehind.
+- [ ] Carry scanner state across lines instead of rescanning the accumulated multiline
+      entry after each line; the current approach is quadratic for long entries.
+- [ ] Normalize trailing whitespace outside strings in preserved multiline entries;
+      whitespace inside multiline strings must remain unchanged.

lib/src/main/java/com/diffplug/spotless/toml/VersionCatalogStep.java

@@ -28,6 +28,7 @@
 
 import com.diffplug.spotless.FormatterFunc;
 import com.diffplug.spotless.FormatterStep;
+import com.diffplug.spotless.Lint;
 
 public final class VersionCatalogStep {
 	private VersionCatalogStep() {}
@@ -125,12 +126,15 @@ private static Map<String, List<Entry>> parseSections(String raw) {
 		List<Entry> currentEntries = null;
 		List<String> pendingComments = new ArrayList<>();
 		StringBuilder multiLineAccumulator = null;
+		int lineNumber = 0;
+		int entryStartLine = 0;
 
 		for (String line : raw.split("\n", -1)) {
+			lineNumber++;
 			String trimmed = line.trim();
 
 			if (multiLineAccumulator != null) {
-				multiLineAccumulator.append(' ').append(trimmed);
+				multiLineAccumulator.append('\n').append(line);
 				if (isBalanced(multiLineAccumulator.toString())) {
 					Entry entry = new Entry(multiLineAccumulator.toString(), new ArrayList<>(pendingComments));
 					currentEntries.add(entry);
@@ -153,7 +157,8 @@ private static Map<String, List<Entry>> parseSections(String raw) {
 				if (trimmed.isEmpty() || trimmed.startsWith("#")) {
 					pendingComments.add(trimmed);
 				} else if (!isBalanced(trimmed)) {
-					multiLineAccumulator = new StringBuilder(trimmed);
+					multiLineAccumulator = new StringBuilder(line.stripLeading());
+					entryStartLine = lineNumber;
 				} else {
 					Entry entry = new Entry(trimmed, new ArrayList<>(pendingComments));
 					currentEntries.add(entry);
@@ -162,30 +167,90 @@ private static Map<String, List<Entry>> parseSections(String raw) {
 			}
 		}
 
+		if (multiLineAccumulator != null) {
+			// Report the incomplete entry instead of silently returning a partially parsed catalog.
+			throw Lint.atLine(entryStartLine, "unterminatedEntry", "Unterminated version catalog entry in " + currentHeader).shortcut();
+		}
 		return sections;
 	}
 
 	private static boolean isBalanced(String text) {
 		int depth = 0;
-		boolean inQuote = false;
 
 		for (int i = 0; i < text.length(); i++) {
 			char c = text.charAt(i);
-			if (c == '"' && (i == 0 || text.charAt(i - 1) != '\\')) {
-				inQuote = !inQuote;
-			} else if (!inQuote) {
-				if (c == '{' || c == '[') {
-					depth++;
-				} else if (c == '}' || c == ']') {
-					depth--;
+			if (c == '"' || c == '\'') {
+				i = skipQuotedString(text, i);
+				if (i == text.length()) {
+					return false;
+				}
+			} else if (c == '#') {
+				i = text.indexOf('\n', i);
+				if (i == -1) {
+					break;
 				}
+			} else if (c == '{' || c == '[') {
+				depth++;
+			} else if (c == '}' || c == ']') {
+				depth--;
 			}
 		}
 		return depth == 0;
 	}
 
+	/** Returns the closing quote's index, or the text length if the string is unfinished. */
+	private static int skipQuotedString(String text, int start) {
+		char quote = text.charAt(start);
+		boolean multiline = isMultilineString(text, start);
+		for (int i = start + (multiline ? 3 : 1); i < text.length(); i++) {
+			char c = text.charAt(i);
+			if (!multiline && c == '\n') {
+				return text.length();
+			}
+			if (quote == '"' && c == '\\' && i + 1 < text.length() && text.charAt(i + 1) != '\n') {
+				i++;
+			} else if (c == quote) {
+				if (!multiline) {
+					return i;
+				}
+				if (i + 2 < text.length() && text.charAt(i + 1) == quote && text.charAt(i + 2) == quote) {
+					i += 2;
+					// A multiline string may end with one or two additional literal quotes.
+					while (i + 1 < text.length() && text.charAt(i + 1) == quote) {
+						i++;
+					}
+					return i;
+				}
+			}
+		}
+		return text.length();
+	}
+
+	/** Called only at an opening quote. */
+	private static boolean isMultilineString(String text, int start) {
+		char quote = text.charAt(start);
+		return start + 2 < text.length() && text.charAt(start + 1) == quote && text.charAt(start + 2) == quote;
+	}
+
+	private static boolean hasCommentsOrMultilineStrings(String text) {
+		for (int i = 0; i < text.length(); i++) {
+			char c = text.charAt(i);
+			if (c == '"' || c == '\'') {
+				if (isMultilineString(text, i)) {
+					return true;
+				}
+				i = skipQuotedString(text, i);
+			} else if (c == '#') {
+				return true;
+			}
+		}
+		return false;
+	}
+
 	private static String extractKey(String formattedEntry) {
-		Matcher matcher = ENTRY_LINE.matcher(formattedEntry);
+		int lineEnd = formattedEntry.indexOf('\n');
+		String firstLine = lineEnd == -1 ? formattedEntry : formattedEntry.substring(0, lineEnd);
+		Matcher matcher = ENTRY_LINE.matcher(firstLine);
 		if (!matcher.matches()) {
 			return formattedEntry;
 		}
@@ -197,7 +262,13 @@ private static String extractKey(String formattedEntry) {
 	}
 
 	static String formatEntry(String entry, boolean stripQuotedKeys) {
-		Matcher matcher = ENTRY_LINE.matcher(entry);
+		int lineEnd = entry.indexOf('\n');
+		// Preserve line boundaries that can be significant to comments or multiline strings.
+		boolean preserveLines = lineEnd != -1 && hasCommentsOrMultilineStrings(entry);
+		if (lineEnd != -1 && !preserveLines) {
+			entry = String.join(" ", entry.lines().map(String::trim).toList());
+		}
+		Matcher matcher = ENTRY_LINE.matcher(preserveLines ? entry.substring(0, lineEnd) : entry);
 		if (!matcher.matches()) {
 			return entry;
 		}
@@ -209,6 +280,10 @@ static String formatEntry(String entry, boolean stripQuotedKeys) {
 				key = bare;
 			}
 		}
+		if (preserveLines) {
+			// The first line starts at offset zero, so the match's value offset also applies to the full entry.
+			return key + " = " + entry.substring(matcher.start(2)).stripLeading();
+		}
 		String valueAndComment = matcher.group(2).trim();
 
 		String inlineComment = extractInlineComment(valueAndComment);
@@ -225,21 +300,18 @@ static String formatEntry(String entry, boolean stripQuotedKeys) {
 	}
 
 	private static String extractInlineComment(String valueAndComment) {
-		boolean inQuote = false;
 		int depth = 0;
 
 		for (int i = 0; i < valueAndComment.length(); i++) {
 			char c = valueAndComment.charAt(i);
-			if (c == '"' && (i == 0 || valueAndComment.charAt(i - 1) != '\\')) {
-				inQuote = !inQuote;
-			} else if (!inQuote) {
-				if (c == '{' || c == '[') {
-					depth++;
-				} else if (c == '}' || c == ']') {
-					depth--;
-				} else if (c == '#' && depth == 0) {
-					return valueAndComment.substring(i);
-				}
+			if (c == '"' || c == '\'') {
+				i = skipQuotedString(valueAndComment, i);
+			} else if (c == '{' || c == '[') {
+				depth++;
+			} else if (c == '}' || c == ']') {
+				depth--;
+			} else if (c == '#' && depth == 0) {
+				return valueAndComment.substring(i);
 			}
 		}
 		return null;
@@ -316,22 +388,19 @@ private static String formatInlineArray(String value) {
 	private static String[] splitTopLevel(String input, char delimiter) {
 		List<String> parts = new ArrayList<>();
 		int depth = 0;
-		boolean inQuote = false;
 		int start = 0;
 
 		for (int i = 0; i < input.length(); i++) {
 			char c = input.charAt(i);
-			if (c == '"' && (i == 0 || input.charAt(i - 1) != '\\')) {
-				inQuote = !inQuote;
-			} else if (!inQuote) {
-				if (c == '{' || c == '[') {
-					depth++;
-				} else if (c == '}' || c == ']') {
-					depth--;
-				} else if (c == delimiter && depth == 0) {
-					parts.add(input.substring(start, i));
-					start = i + 1;
-				}
+			if (c == '"' || c == '\'') {
+				i = skipQuotedString(input, i);
+			} else if (c == '{' || c == '[') {
+				depth++;
+			} else if (c == '}' || c == ']') {
+				depth--;
+			} else if (c == delimiter && depth == 0) {
+				parts.add(input.substring(start, i));
+				start = i + 1;
 			}
 		}
 		parts.add(input.substring(start));
@@ -345,7 +414,7 @@ private static boolean isBareKey(String key) {
 	}
 
 	private static final class State implements Serializable {
-		private static final long serialVersionUID = 3L;
+		private static final long serialVersionUID = 5L;
 
 		private final boolean stripQuotedKeys;
 

plugin-gradle/CHANGES.md

@@ -4,6 +4,10 @@ We adhere to the [keepachangelog](https://keepachangelog.com/en/1.0.0/) format (
 
 ## [Unreleased]
 
+### Fixed
+- `versionCatalog()` preserves entries when comments contain unmatched brackets, preserves commas inside quoted strings, and keeps significant line boundaries in multiline entries. ([#3042](https://github.com/diffplug/spotless/pull/3042))
+- `versionCatalog()` now reports unfinished entries as lints at their starting line. These fail formatting by default, so upgrading may expose catalog errors that previously caused silent data loss. ([#3042](https://github.com/diffplug/spotless/pull/3042))
+
 ## [8.10.2] - 2026-09-04
 ### Fixed
 - `shortenFullyQualifiedTypes()` now shortens fully-qualified types used in expression contexts (such as static method calls, static fields, and enum constants) while avoiding imports that would change how existing unqualified type references resolve. ([#3039](https://github.com/diffplug/spotless/pull/3039))

plugin-maven/CHANGES.md

@@ -4,6 +4,10 @@ We adhere to the [keepachangelog](https://keepachangelog.com/en/1.0.0/) format (
 
 ## [Unreleased]
 
+### Fixed
+- `<versionCatalog>` preserves entries when comments contain unmatched brackets, preserves commas inside quoted strings, and keeps significant line boundaries in multiline entries. ([#3042](https://github.com/diffplug/spotless/pull/3042))
+- `<versionCatalog>` now reports unfinished entries as lints at their starting line. These fail formatting by default, so upgrading may expose catalog errors that previously caused silent data loss. ([#3042](https://github.com/diffplug/spotless/pull/3042))
+
 ## [3.10.2] - 2026-09-04
 ### Fixed
 - `<shortenFullyQualifiedTypes>` now shortens fully-qualified types used in expression contexts (such as static method calls, static fields, and enum constants) while avoiding imports that would change how existing unqualified type references resolve. ([#3039](https://github.com/diffplug/spotless/pull/3039))