Merge branch 'feat/prepare-for-lint-take-2' into feat/lint-take-2

Author: nedtwigg

CHANGES.md

@@ -34,8 +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()`.
+* **BREAKING** Moved `PaddedCell.DirtyState` to its own top-level class with new methods. ([#2148](https://github.com/diffplug/spotless/pull/2148))
+  * **BREAKING** Removed `isClean`, `applyTo`, and `applyToAndReturnResultIfDirty` from `Formatter` because users should instead use `DirtyState`.
 
 ## [2.45.0] - 2024-01-23
 ### Added

CONTRIBUTING.md

@@ -10,21 +10,20 @@ In order to use and combine `FormatterStep`, you first create a `Formatter`, whi
 
 - an encoding
 - a list of `FormatterStep`
-- a line endings policy (`LineEnding.GIT_ATTRIBUTES` is almost always the best choice)
+- a line endings policy (`LineEnding.GIT_ATTRIBUTES_FAST_ALLSAME` is almost always the best choice)
 
-Once you have an instance of `Formatter`, you can call `boolean isClean(File)`, or `void applyTo(File)` to either check or apply formatting to a file.  Spotless will then:
+Once you have an instance of `Formatter`, you can call `DirtyState.of(Formatter, File)`. Under the hood, Spotless will:
 
 - parse the raw bytes into a String according to the encoding
 - normalize its line endings to `\n`
 - pass the unix string to each `FormatterStep` one after the other
+- check for idempotence problems, and repeatedly apply the steps until the [result is stable](PADDEDCELL.md). 
 - apply line endings according to the policy
 
 You can also use lower-level methods like `String compute(String unix, File file)` if you'd like to do lower-level processing.
 
 All `FormatterStep` implement `Serializable`, `equals`, and `hashCode`, so build systems that support up-to-date checks can easily and correctly determine if any actions need to be taken.
 
-Spotless also provides `PaddedCell`, which makes it easy to diagnose and correct idempotence problems.
-
 ## Project layout
 
 For the folders below in monospace text, they are published on MavenCentral at the coordinate `com.diffplug.spotless:spotless-${FOLDER_NAME}`.  The other folders are dev infrastructure.
@@ -39,15 +38,16 @@ For the folders below in monospace text, they are published on MavenCentral at t
 
 ## How to add a new FormatterStep
 
-The easiest way to create a FormatterStep is `FormatterStep createNeverUpToDate(String name, FormatterFunc function)`, which you can use like this:
+The easiest way to create a FormatterStep is to just create `class FooStep implements FormatterStep`. It has one abstract method which is the formatting function, and you're ready to tinker. To work with the build plugins, this class will need to
 
-```java
-FormatterStep identityStep = FormatterStep.createNeverUpToDate("identity", unixStr -> unixStr)
-```
+- implement equality and hashcode
+- support lossless roundtrip serialization
+
+You can use `StepHarness` (if you don't care about the `File` argument) or `StepHarnessWithFile` to test. The harness will roundtrip serialize your step, check that it's equal to itself, and then perform all tests on the roundtripped step.
 
-This creates a step which will fail up-to-date checks (it is equal only to itself), and will use the function you passed in to do the formatting pass.
+## Implementing equality in terms of serialization
 
-To create a step which can handle up-to-date checks properly, use the method `<State extends Serializable> FormatterStep create(String name, State state, Function<State, FormatterFunc> stateToFormatter)`.  Here's an example:
+Spotless has infrastructure which uses the serialized form of your step to implement equality for you. Here is an example:
 
 ```java
 public final class ReplaceStep {
@@ -62,10 +62,10 @@ public final class ReplaceStep {
   private static final class State implements Serializable {
     private static final long serialVersionUID = 1L;
 
-    private final CharSequence target;
-    private final CharSequence replacement;
+    private final String target;
+    private final String replacement;
 
-    State(CharSequence target, CharSequence replacement) {
+    State(String target, String replacement) {
       this.target = target;
       this.replacement = replacement;
     }
@@ -82,8 +82,6 @@ The `FormatterStep` created above implements `equals` and `hashCode` based on th
 Oftentimes, a rule's state will be expensive to compute. `EclipseFormatterStep`, for example, depends on a formatting file.  Ideally, we would like to only pay the cost of the I/O needed to load that file if we have to - we'd like to create the FormatterStep now but load its state lazily at the last possible moment.  For this purpose, each of the `FormatterStep.create` methods has a lazy counterpart.  Here are their signatures:
 
 ```java
-FormatterStep createNeverUpToDate    (String name, FormatterFunc function                  )
-FormatterStep createNeverUpToDateLazy(String name, Supplier<FormatterFunc> functionSupplier)
 FormatterStep create    (String name, State state                  , Function<State, FormatterFunc> stateToFormatter)
 FormatterStep createLazy(String name, Supplier<State> stateSupplier, Function<State, FormatterFunc> stateToFormatter)
 ```
@@ -101,7 +99,7 @@ Here's a checklist for creating a new step for Spotless:
 
 ### Serialization roundtrip
 
-In order to support Gradle's configuration cache, all `FormatterStep` must be round-trip serializable. This is a bit tricky because step equality is based on the serialized form of the state, and `transient` is used to take absolute paths out of the equality check. To make this work, roundtrip compatible steps actually have *two* states:
+In order to support Gradle's configuration cache, all `FormatterStep` must be round-trip serializable. This is a bit tricky because step equality is based on the serialized form of the state, and `transient` can be used to take absolute paths out of the equality check. To make this work, roundtrip compatible steps can actually have *two* states:
 
 - `RoundtripState` which must be roundtrip serializable but has no equality constraints
   - `FileSignature.Promised` for settings files and `JarState.Promised` for the classpath 

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

@@ -69,85 +69,52 @@ public static DirtyState clean() {
 	static final DirtyState didNotConverge = new DirtyState(null);
 	static final DirtyState isClean = new DirtyState(null);
 
-	public static Calculation of(Formatter formatter, File file) throws IOException {
+	public static DirtyState 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 DirtyState of(Formatter formatter, File file, byte[] rawBytes) {
+		String 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);
+		}
+
+		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;
+		}
 
-	public static class Calculation {
-		private final Formatter formatter;
-		private final File file;
-		private final byte[] rawBytes;
-		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);
-			}
+		// 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);
 		}
 
-		/**
-		 * 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() {
-			ValuePerStep<Throwable> exceptionPerStep = new ValuePerStep<>(formatter);
-			DirtyState result = calculateDirtyState(exceptionPerStep);
-			LintPolicy.legacyBehavior(formatter, file, exceptionPerStep);
-			return result;
+		PaddedCell cell = PaddedCell.check(formatter, file, rawUnix);
+		if (!cell.isResolvable()) {
+			return didNotConverge;
 		}
 
-		/**
-		 * 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.
-		 */
-		DirtyState calculateDirtyState(ValuePerStep<Throwable> exceptionPerStep) {
-			String rawUnix = LineEnding.toUnix(raw);
-
-			// enforce the format
-			String formattedUnix = formatter.computeWithLint(rawUnix, file, exceptionPerStep);
-			// 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.computeWithLint(formattedUnix, file, exceptionPerStep);
-			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, exceptionPerStep);
-			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;
-			}
+		// 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;
 		}
 	}
 }

plugin-gradle/src/main/java/com/diffplug/gradle/spotless/IdeHook.java

@@ -55,7 +55,7 @@ static void performHook(SpotlessTaskImpl spotlessTask) {
 				} else {
 					bytes = Files.readAllBytes(file.toPath());
 				}
-				DirtyState dirty = DirtyState.of(formatter, file, bytes).calculateDirtyState();
+				DirtyState dirty = DirtyState.of(formatter, file, bytes);
 				if (dirty.isClean()) {
 					dumpIsClean();
 				} else if (dirty.didNotConverge()) {

plugin-gradle/src/main/java/com/diffplug/gradle/spotless/SpotlessTaskImpl.java

@@ -102,7 +102,7 @@ void processInputFile(@Nullable GitRatchet ratchet, Formatter formatter, File in
 			dirtyState = DirtyState.clean();
 		} else {
 			try {
-				dirtyState = DirtyState.of(formatter, input).calculateDirtyState();
+				dirtyState = DirtyState.of(formatter, input);
 			} catch (IOException e) {
 				throw new IOException("Issue processing file: " + input, e);
 			} catch (RuntimeException e) {

plugin-maven/src/main/java/com/diffplug/spotless/maven/IdeHook.java

@@ -49,7 +49,7 @@ static void performHook(Iterable<File> projectFiles, Formatter formatter, String
 			} else {
 				bytes = Files.readAllBytes(file.toPath());
 			}
-			DirtyState dirty = DirtyState.of(formatter, file, bytes).calculateDirtyState();
+			DirtyState dirty = DirtyState.of(formatter, file, bytes);
 			if (dirty.isClean()) {
 				dumpIsClean();
 			} else if (dirty.didNotConverge()) {

plugin-maven/src/main/java/com/diffplug/spotless/maven/SpotlessApplyMojo.java

@@ -60,7 +60,7 @@ protected void process(String name, Iterable<File> files, Formatter formatter, U
 			}
 
 			try {
-				DirtyState dirtyState = DirtyState.of(formatter, file).calculateDirtyState();
+				DirtyState dirtyState = DirtyState.of(formatter, file);
 				if (!dirtyState.isClean() && !dirtyState.didNotConverge()) {
 					getLog().info(String.format("Writing clean file: %s", file));
 					dirtyState.writeCanonicalTo(file);

plugin-maven/src/main/java/com/diffplug/spotless/maven/SpotlessCheckMojo.java

@@ -78,7 +78,7 @@ protected void process(String name, Iterable<File> files, Formatter formatter, U
 			}
 			buildContext.removeMessages(file);
 			try {
-				DirtyState dirtyState = DirtyState.of(formatter, file).calculateDirtyState();
+				DirtyState dirtyState = DirtyState.of(formatter, file);
 				if (!dirtyState.isClean() && !dirtyState.didNotConverge()) {
 					problemFiles.add(file);
 					if (buildContext.isIncremental()) {