Linting - breaking changes to internal API to prepare

CHANGES.md

@@ -34,6 +34,8 @@ We adhere to the [keepachangelog](https://keepachangelog.com/en/1.0.0/) format (
 * **BREAKING** Remove `JarState.getMavenCoordinate(String prefix)`. ([#1945](https://github.com/diffplug/spotless/pull/1945))
 * **BREAKING** Replace `PipeStepPair` with `FenceStep`. ([#1954](https://github.com/diffplug/spotless/pull/1954))
 * **BREAKING** Fully removed `Rome`, use `Biome` instead. ([#2119](https://github.com/diffplug/spotless/pull/2119))
+* **BREAKING** Moved `PaddedCell.DirtyState` to its own top-level class with new methods.
+* **BREAKING** Removed `isClean`, `applyTo`, and `applyToAndReturnResultIfDirty` from `Formatter` because users should instead use `PaddedCell.check()`.
 
 ## [2.45.0] - 2024-01-23
 ### Added

lib-extra/src/main/java/com/diffplug/spotless/extra/integration/DiffMessageFormatter.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016-2023 DiffPlug
+ * Copyright 2016-2024 DiffPlug
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -58,15 +58,17 @@ interface CleanProvider {
 	}
 
 	private static class CleanProviderFormatter implements CleanProvider {
+		private final Path rootDir;
 		private final Formatter formatter;
 
-		CleanProviderFormatter(Formatter formatter) {
+		CleanProviderFormatter(Path rootDir, Formatter formatter) {
+			this.rootDir = Objects.requireNonNull(rootDir);
 			this.formatter = Objects.requireNonNull(formatter);
 		}
 
 		@Override
 		public Path getRootDir() {
-			return formatter.getRootDir();
+			return rootDir;
 		}
 
 		@Override
@@ -123,8 +125,8 @@ public Builder runToFix(String runToFix) {
 			return this;
 		}
 
-		public Builder formatter(Formatter formatter) {
-			this.formatter = new CleanProviderFormatter(formatter);
+		public Builder formatter(Path rootDir, Formatter formatter) {
+			this.formatter = new CleanProviderFormatter(rootDir, formatter);
 			return this;
 		}
 
@@ -244,8 +246,8 @@ private String diff(File file) throws IOException {
 	 * look like if formatted using the given formatter. Does not end with any newline
 	 * sequence (\n, \r, \r\n). The key of the map entry is the 0-based line where the first difference occurred.
 	 */
-	public static Map.Entry<Integer, String> diff(Formatter formatter, File file) throws IOException {
-		return diff(new CleanProviderFormatter(formatter), file);
+	public static Map.Entry<Integer, String> diff(Path rootDir, Formatter formatter, File file) throws IOException {
+		return diff(new CleanProviderFormatter(rootDir, formatter), file);
 	}
 
 	private static Map.Entry<Integer, String> diff(CleanProvider formatter, File file) throws IOException {

lib-extra/src/test/java/com/diffplug/spotless/extra/groovy/GrEclipseFormatterStepSpecialCaseTest.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2023 DiffPlug
+ * Copyright 2023-2024 DiffPlug
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.

lib/src/main/java/com/diffplug/spotless/DirtyState.java

@@ -0,0 +1,141 @@
+/*
+ * Copyright 2022-2024 DiffPlug
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.diffplug.spotless;
+
+import java.io.File;
+import java.io.IOException;
+import java.io.OutputStream;
+import java.nio.file.Files;
+import java.util.Arrays;
+
+import javax.annotation.Nullable;
+
+/**
+ * The clean/dirty state of a single file.  Intended use:
+ * - {@link #isClean()} means that the file is is clean, and there's nothing else to say
+ * - {@link #didNotConverge()} means that we were unable to determine a clean state
+ * - once you've tested the above conditions and you know that it's a dirty file with a converged state,
+ * then you can call {@link #writeCanonicalTo(OutputStream)} to get the canonical form of the given file.
+ */
+public class DirtyState {
+	@Nullable
+	private final byte[] canonicalBytes;
+
+	DirtyState(@Nullable byte[] canonicalBytes) {
+		this.canonicalBytes = canonicalBytes;
+	}
+
+	public boolean isClean() {
+		return this == isClean;
+	}
+
+	public boolean didNotConverge() {
+		return this == didNotConverge;
+	}
+
+	private byte[] canonicalBytes() {
+		if (canonicalBytes == null) {
+			throw new IllegalStateException("First make sure that {@code !isClean()} and {@code !didNotConverge()}");
+		}
+		return canonicalBytes;
+	}
+
+	public void writeCanonicalTo(File file) throws IOException {
+		Files.write(file.toPath(), canonicalBytes());
+	}
+
+	public void writeCanonicalTo(OutputStream out) throws IOException {
+		out.write(canonicalBytes());
+	}
+
+	/** Returns the DirtyState which corresponds to {@code isClean()}. */
+	public static DirtyState clean() {
+		return isClean;
+	}
+
+	static final DirtyState didNotConverge = new DirtyState(null);
+	static final DirtyState isClean = new DirtyState(null);
+
+	public static Calculation of(Formatter formatter, File file) throws IOException {
+		return of(formatter, file, Files.readAllBytes(file.toPath()));
+	}
+
+	public static Calculation of(Formatter formatter, File file, byte[] rawBytes) {
+		return new Calculation(formatter, file, rawBytes);
+	}
+
+	public static class Calculation {
+		private final Formatter formatter;
+		private final File file;
+		private final byte[] rawBytes;
+		private final String raw;
+
+		private Calculation(Formatter formatter, File file, byte[] rawBytes) {
+			this.formatter = formatter;
+			this.file = file;
+			this.rawBytes = rawBytes;
+			this.raw = new String(rawBytes, formatter.getEncoding());
+			// check that all characters were encodable
+			String encodingError = EncodingErrorMsg.msg(raw, rawBytes, formatter.getEncoding());
+			if (encodingError != null) {
+				throw new IllegalArgumentException(encodingError);
+			}
+		}
+
+		/**
+		 * Calculates whether the given file is dirty according to a PaddedCell invocation of the given formatter.
+		 * DirtyState includes the clean state of the file, as well as a warning if we were not able to apply the formatter
+		 * due to diverging idempotence.
+		 */
+		public DirtyState calculateDirtyState() {
+			String rawUnix = LineEnding.toUnix(raw);
+
+			// enforce the format
+			String formattedUnix = formatter.compute(rawUnix, file);
+			// convert the line endings if necessary
+			String formatted = formatter.computeLineEndings(formattedUnix, file);
+
+			// if F(input) == input, then the formatter is well-behaving and the input is clean
+			byte[] formattedBytes = formatted.getBytes(formatter.getEncoding());
+			if (Arrays.equals(rawBytes, formattedBytes)) {
+				return isClean;
+			}
+
+			// F(input) != input, so we'll do a padded check
+			String doubleFormattedUnix = formatter.compute(formattedUnix, file);
+			if (doubleFormattedUnix.equals(formattedUnix)) {
+				// most dirty files are idempotent-dirty, so this is a quick-short circuit for that common case
+				return new DirtyState(formattedBytes);
+			}
+
+			PaddedCell cell = PaddedCell.check(formatter, file, rawUnix);
+			if (!cell.isResolvable()) {
+				return didNotConverge;
+			}
+
+			// get the canonical bytes
+			String canonicalUnix = cell.canonical();
+			String canonical = formatter.computeLineEndings(canonicalUnix, file);
+			byte[] canonicalBytes = canonical.getBytes(formatter.getEncoding());
+			if (!Arrays.equals(rawBytes, canonicalBytes)) {
+				// and write them to disk if needed
+				return new DirtyState(canonicalBytes);
+			} else {
+				return isClean;
+			}
+		}
+	}
+}