Linting - API

gradle.properties

@@ -32,3 +32,4 @@ VER_JGIT=6.7.0.202309050840-r
 VER_JUNIT=5.10.2
 VER_ASSERTJ=3.26.0
 VER_MOCKITO=5.12.0
+VER_SELFIE=2.2.0

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

@@ -46,7 +46,7 @@ public boolean didNotConverge() {
 		return this == didNotConverge;
 	}
 
-	private byte[] canonicalBytes() {
+	byte[] canonicalBytes() {
 		if (canonicalBytes == null) {
 			throw new IllegalStateException("First make sure that {@code !isClean()} and {@code !didNotConverge()}");
 		}
@@ -81,7 +81,7 @@ public static class Calculation {
 		private final Formatter formatter;
 		private final File file;
 		private final byte[] rawBytes;
-		private final String raw;
+		final String raw;
 
 		private Calculation(Formatter formatter, File file, byte[] rawBytes) {
 			this.formatter = formatter;
@@ -101,10 +101,22 @@ private Calculation(Formatter formatter, File file, byte[] rawBytes) {
 		 * due to diverging idempotence.
 		 */
 		public DirtyState calculateDirtyState() {
+			ValuePerStep<Throwable> exceptionPerStep = new ValuePerStep<>(formatter);
+			DirtyState result = calculateDirtyState(exceptionPerStep);
+			LintPolicy.legacyBehavior(formatter, file, exceptionPerStep);
+			return result;
+		}
+
+		/**
+		 * 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.compute(rawUnix, file);
+			String formattedUnix = formatter.computeWithLint(rawUnix, file, exceptionPerStep);
 			// convert the line endings if necessary
 			String formatted = formatter.computeLineEndings(formattedUnix, file);
 
@@ -115,13 +127,13 @@ public DirtyState calculateDirtyState() {
 			}
 
 			// F(input) != input, so we'll do a padded check
-			String doubleFormattedUnix = formatter.compute(formattedUnix, file);
+			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);
+			PaddedCell cell = PaddedCell.check(formatter, file, rawUnix, exceptionPerStep);
 			if (!cell.isResolvable()) {
 				return didNotConverge;
 			}

lib/src/main/java/com/diffplug/spotless/FilterByContentPatternFormatterStep.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.
@@ -16,8 +16,8 @@
 package com.diffplug.spotless;
 
 import java.io.File;
+import java.util.List;
 import java.util.Objects;
-import java.util.regex.Matcher;
 import java.util.regex.Pattern;
 
 import javax.annotation.Nullable;
@@ -36,14 +36,24 @@ final class FilterByContentPatternFormatterStep extends DelegateFormatterStep {
 	public @Nullable String format(String raw, File file) throws Exception {
 		Objects.requireNonNull(raw, "raw");
 		Objects.requireNonNull(file, "file");
-		Matcher matcher = contentPattern.matcher(raw);
-		if (matcher.find() == (onMatch == OnMatch.INCLUDE)) {
+		if (contentPattern.matcher(raw).find() == (onMatch == OnMatch.INCLUDE)) {
 			return delegateStep.format(raw, file);
 		} else {
 			return raw;
 		}
 	}
 
+	@Override
+	public List<Lint> lint(String raw, File file) throws Exception {
+		Objects.requireNonNull(raw, "raw");
+		Objects.requireNonNull(file, "file");
+		if (contentPattern.matcher(raw).find() == (onMatch == OnMatch.INCLUDE)) {
+			return delegateStep.lint(raw, file);
+		} else {
+			return List.of();
+		}
+	}
+
 	@Override
 	public boolean equals(Object o) {
 		if (this == o) {

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016-2022 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.
@@ -16,6 +16,7 @@
 package com.diffplug.spotless;
 
 import java.io.File;
+import java.util.List;
 import java.util.Objects;
 
 import javax.annotation.Nullable;
@@ -39,6 +40,17 @@ final class FilterByFileFormatterStep extends DelegateFormatterStep {
 		}
 	}
 
+	@Override
+	public List<Lint> lint(String content, File file) throws Exception {
+		Objects.requireNonNull(content, "content");
+		Objects.requireNonNull(file, "file");
+		if (filter.accept(file)) {
+			return delegateStep.lint(content, file);
+		} else {
+			return List.of();
+		}
+	}
+
 	@Override
 	public boolean equals(Object o) {
 		if (this == o) {

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 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.
@@ -23,7 +23,7 @@
  * A policy for handling exceptions in the format.  Any exceptions will
  * halt the build except for a specifically excluded path or step.
  */
-public class FormatExceptionPolicyStrict extends NoLambda.EqualityBasedOnSerialization implements FormatExceptionPolicy {
+public class FormatExceptionPolicyStrict extends NoLambda.EqualityBasedOnSerialization {
 	private static final long serialVersionUID = 1L;
 
 	private final Set<String> excludeSteps = new TreeSet<>();
@@ -39,18 +39,17 @@ public void excludePath(String relativePath) {
 		excludePaths.add(Objects.requireNonNull(relativePath));
 	}
 
-	@Override
 	public void handleError(Throwable e, FormatterStep step, String relativePath) {
 		Objects.requireNonNull(e, "e");
 		Objects.requireNonNull(step, "step");
 		Objects.requireNonNull(relativePath, "relativePath");
 		if (excludeSteps.contains(step.getName())) {
-			FormatExceptionPolicyLegacy.warning(e, step, relativePath);
+			LintPolicy.warning(e, step, relativePath);
 		} else {
 			if (excludePaths.contains(relativePath)) {
-				FormatExceptionPolicyLegacy.warning(e, step, relativePath);
+				LintPolicy.warning(e, step, relativePath);
 			} else {
-				FormatExceptionPolicyLegacy.error(e, step, relativePath);
+				LintPolicy.error(e, step, relativePath);
 				throw ThrowingEx.asRuntimeRethrowError(e);
 			}
 		}

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

@@ -127,28 +127,51 @@ public String computeLineEndings(String unix, File file) {
 	 * is guaranteed to also have unix line endings.
 	 */
 	public String compute(String unix, File file) {
+		ValuePerStep<Throwable> exceptionPerStep = new ValuePerStep<>(this);
+		String result = computeWithLint(unix, file, exceptionPerStep);
+		LintPolicy.legacyBehavior(this, file, exceptionPerStep);
+		return result;
+	}
+
+	/**
+	 * Returns the result of calling all of the FormatterSteps, while also
+	 * tracking any exceptions which are thrown.
+	 * <p>
+	 * The input must have unix line endings, and the output
+	 * is guaranteed to also have unix line endings.
+	 * <p>
+	 * It doesn't matter what is inside `ValuePerStep`, the value at every index will be overwritten
+	 * when the method returns.
+	 */
+	String computeWithLint(String unix, File file, ValuePerStep<Throwable> exceptionPerStep) {
 		Objects.requireNonNull(unix, "unix");
 		Objects.requireNonNull(file, "file");
 
-		for (FormatterStep step : steps) {
+		for (int i = 0; i < steps.size(); ++i) {
+			FormatterStep step = steps.get(i);
+			Throwable storeForStep;
 			try {
 				String formatted = step.format(unix, file);
 				if (formatted == null) {
 					// This probably means it was a step that only checks
 					// for errors and doesn't actually have any fixes.
 					// No exception was thrown so we can just continue.
+					storeForStep = LintState.formatStepCausedNoChange();
 				} else {
 					// Should already be unix-only, but some steps might misbehave.
-					unix = LineEnding.toUnix(formatted);
+					String clean = LineEnding.toUnix(formatted);
+					if (clean.equals(unix)) {
+						storeForStep = LintState.formatStepCausedNoChange();
+					} else {
+						storeForStep = null;
+						unix = LineEnding.toUnix(formatted);
+					}
 				}
 			} catch (Throwable e) {
-				// TODO: this is bad, but it won't matter when add support for linting
-				if (e instanceof RuntimeException) {
-					throw (RuntimeException) e;
-				} else {
-					throw new RuntimeException(e);
-				}
+				// store the exception which was thrown and keep going
+				storeForStep = e;
 			}
+			exceptionPerStep.set(i, storeForStep);
 		}
 		return unix;
 	}

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

@@ -16,6 +16,7 @@
 package com.diffplug.spotless;
 
 import java.io.File;
+import java.util.List;
 import java.util.Objects;
 
 /**
@@ -32,6 +33,14 @@ default String apply(String unix, File file) throws Exception {
 		return apply(unix);
 	}
 
+	/**
+	 * Calculates a list of lints against the given content.
+	 * By default, that's just an throwables thrown by the lint.
+	 */
+	default List<Lint> lint(String content, File file) throws Exception {
+		return List.of();
+	}
+
 	/**
 	 * {@code Function<String, String>} and {@code BiFunction<String, File, String>} whose implementation
 	 * requires a resource which should be released when the function is no longer needed.
@@ -74,6 +83,14 @@ public String apply(String unix) throws Exception {
 		@FunctionalInterface
 		interface ResourceFunc<T extends AutoCloseable> {
 			String apply(T resource, String unix) throws Exception;
+
+			/**
+			 * Calculates a list of lints against the given content.
+			 * By default, that's just an throwables thrown by the lint.
+			 */
+			default List<Lint> lint(T resource, String unix) throws Exception {
+				return List.of();
+			}
 		}
 
 		/** Creates a {@link FormatterFunc.Closeable} which uses the given resource to execute the format function. */
@@ -101,6 +118,10 @@ public String apply(String unix) throws Exception {
 		@FunctionalInterface
 		interface ResourceFuncNeedsFile<T extends AutoCloseable> {
 			String apply(T resource, String unix, File file) throws Exception;
+
+			default List<Lint> lint(T resource, String content, File file) throws Exception {
+				return List.of();
+			}
 		}
 
 		/** Creates a {@link FormatterFunc.Closeable} which uses the given resource to execute the file-dependent format function. */
@@ -123,6 +144,11 @@ public String apply(String unix, File file) throws Exception {
 				public String apply(String unix) throws Exception {
 					return apply(unix, Formatter.NO_FILE_SENTINEL);
 				}
+
+				@Override
+				public List<Lint> lint(String content, File file) throws Exception {
+					return function.lint(resource, content, file);
+				}
 			};
 		}
 	}

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

@@ -17,6 +17,7 @@
 
 import java.io.File;
 import java.io.Serializable;
+import java.util.List;
 import java.util.Objects;
 
 import javax.annotation.Nullable;
@@ -46,6 +47,22 @@ public interface FormatterStep extends Serializable, AutoCloseable {
 	@Nullable
 	String format(String rawUnix, File file) throws Exception;
 
+	/**
+	 * Returns a list of lints against the given file content
+	 *
+	 * @param content
+	 *            the content to check
+	 * @param file
+	 *            the file which {@code content} was obtained from; never null. Pass an empty file using
+	 *            {@code new File("")} if and only if no file is actually associated with {@code content}
+	 * @return a list of lints
+	 * @throws Exception if the formatter step experiences a problem
+	 */
+	@Nullable
+	default List<Lint> lint(String content, File file) throws Exception {
+		return List.of();
+	}
+
 	/**
 	 * Returns a new {@code FormatterStep} which, observing the value of {@code formatIfMatches},
 	 * will only apply, or not, its changes to files which pass the given filter.

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

@@ -18,6 +18,7 @@
 import java.io.File;
 import java.io.Serializable;
 import java.util.Arrays;
+import java.util.List;
 
 import edu.umd.cs.findbugs.annotations.SuppressFBWarnings;
 
@@ -48,6 +49,14 @@ public String format(String rawUnix, File file) throws Exception {
 		return formatter.apply(rawUnix, file);
 	}
 
+	@Override
+	public List<Lint> lint(String content, File file) throws Exception {
+		if (formatter == null) {
+			formatter = stateToFormatter(state());
+		}
+		return formatter.lint(content, file);
+	}
+
 	@Override
 	public boolean equals(Object o) {
 		if (o == null) {