biome step: Allow specifying path to JSON config file directly, requires biome 2.0 or higher

Author: awa-xima

CHANGES.md

@@ -10,6 +10,8 @@ This document is intended for Spotless developers.
 We adhere to the [keepachangelog](https://keepachangelog.com/en/1.0.0/) format (starting after version `1.27.0`).
 
 ## [Unreleased]
+### Added
+* Allow specifying path to Biome JSON config file directly in `biome` step. Requires biome 2.x.
 
 ## [3.2.0] - 2025-07-07
 ### Added

CONTRIBUTING.md

@@ -163,7 +163,7 @@ If you get something running, we'd love to host your plugin within this repo as
 
 To run all tests, simply do
 
-> gradlew test
+> ./gradlew test
 
 Since that takes some time, you might only want to run the tests
 concerning what you are working on:

lib/src/main/java/com/diffplug/spotless/biome/BiomeSettings.java

@@ -15,10 +15,15 @@
  */
 package com.diffplug.spotless.biome;
 
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
 /**
  * Settings and constants for Biome to use.
  */
 public final class BiomeSettings {
+	private static final Logger logger = LoggerFactory.getLogger(BiomeSettings.class);
+
 	private final static String CONFIG_NAME = "biome.json";
 	private final static String DEFAULT_VERSION = "1.2.0";
 	private final static String DOWNLOAD_FILE_PATTERN = "biome-%s-%s-%s";
@@ -72,4 +77,37 @@ public static String getUrlPattern(String version) {
 	public static String shortName() {
 		return SHORT_NAME;
 	}
+
+	/**
+	 * Checks if the version of Biome is equal to or higher than the given major, minor, and patch version.
+	 * @param version The version string to check, e.g. "1.2.3".
+	 * @param major The major version to compare against.
+	 * @param minor The minor version to compare against.
+	 * @param patch The patch version to compare against.
+	 * @return true if the version is higher than or equal to the given major, minor, and patch version,
+	 */
+	public static boolean versionHigherThanOrEqualTo(String version, int major, int minor, int patch) {
+		try {
+			final var versionParts = version.split("\\.");
+			if (versionParts.length < 3) {
+				return false;
+			}
+			final var actualMajor = Integer.parseInt(versionParts[0]);
+			final var actualMinor = Integer.parseInt(versionParts[1]);
+			final var actualPatch = Integer.parseInt(versionParts[2]);
+			if (actualMajor > major) {
+				return true;
+			}
+			if (actualMajor == major && actualMinor > minor) {
+				return true;
+			}
+			if (actualMajor == major && actualMinor == minor && actualPatch > patch) {
+				return true;
+			}
+			return actualMajor == major && actualMinor == minor && actualPatch == patch;
+		} catch (final Exception e) {
+			logger.warn("Failed to parse biome version string '{}'. Expected format is 'major.minor.patch'.", version, e);
+			return false;
+		}
+	}
 }

lib/src/main/java/com/diffplug/spotless/biome/BiomeStep.java

@@ -191,18 +191,21 @@ private static String resolveNameAgainstPath(String name) throws IOException, In
 	/**
 	 * Checks the Biome config path. When the config path does not exist or when it
 	 * does not contain a file named {@code biome.json}, an error is thrown.
+	 * @param configPath The path to validate.
+	 * @param version The version of Biome.
 	 */
-	private static void validateBiomeConfigPath(String configPath) {
+	private static void validateBiomeConfigPath(String configPath, String version) {
 		if (configPath == null) {
 			return;
 		}
+		var atLeastV2 = BiomeSettings.versionHigherThanOrEqualTo(version, 2, 0, 0);
 		var path = Paths.get(configPath);
-		var config = path.resolve(BiomeSettings.configName());
+		var configFile = Files.isRegularFile(path) && atLeastV2 ? path : path.resolve(BiomeSettings.configName());
 		if (!Files.exists(path)) {
 			throw new IllegalArgumentException("Biome config directory does not exist: " + path);
 		}
-		if (!Files.exists(config)) {
-			throw new IllegalArgumentException("Biome config does not exist: " + config);
+		if (!Files.exists(configFile)) {
+			throw new IllegalArgumentException("Biome config does not exist: " + configFile);
 		}
 	}
 
@@ -240,11 +243,10 @@ public FormatterStep create() {
 	}
 
 	/**
-	 * Sets the path to the directory with the {@code biome.json} config file. When
-	 * no config path is set, the default configuration is used.
+	 * Sets the path to the Biome configuration. Must be either a directory with a file named {@code biome.json}, or
+	 * a file with the Biome config as JSON. When no config path is set, the default configuration is used.
 	 *
-	 * @param configPath Config path to use. Must point to a directory which contains
-	 *                   a file named {@code biome.json}.
+	 * @param configPath Config path to use.
 	 * @return This builder instance for chaining method calls.
 	 */
 	public BiomeStep withConfigPath(String configPath) {
@@ -296,7 +298,7 @@ public BiomeStep withLanguage(String language) {
 	private State createState() throws IOException, InterruptedException {
 		var resolvedPathToExe = resolveExe();
 		validateBiomeExecutable(resolvedPathToExe);
-		validateBiomeConfigPath(configPath);
+		validateBiomeConfigPath(configPath, version);
 		logger.debug("Using Biome executable located at  '{}'", resolvedPathToExe);
 		var exeSignature = FileSignature.signAsList(Collections.singleton(new File(resolvedPathToExe)));
 		makeExecutable(resolvedPathToExe);

plugin-gradle/CHANGES.md

@@ -3,6 +3,8 @@
 We adhere to the [keepachangelog](https://keepachangelog.com/en/1.0.0/) format (starting after version `3.27.0`).
 
 ## [Unreleased]
+### Added
+* Allow specifying path to Biome JSON config file directly in `biome` step. Requires biome 2.x.
 
 ## [7.1.0] - 2025-07-07
 ### Added

plugin-gradle/README.md

@@ -1432,14 +1432,14 @@ spotless {
     target 'src/*/webapp/**/*.js'
 
     // Download Biome from the network if not already downloaded, see below for more info
-    biome('1.2.0')
+    biome('2.1.0')
 
     // (optional) Path to the directory with the biome.json conig file
-    biome('1.2.0').configPath("path/config/dir")
+    biome('2.1.0').configPath("path/config/dir")
 
     // (optional) Biome will auto detect the language based on the file extension.
     // See below for possible values.
-    biome('1.2.0').language("js")
+    biome('2.1.0').language("js")
   }
 }
 ```
@@ -1451,15 +1451,15 @@ more formats:
 spotless {
   format 'biome-js', {
     target '**/*.js'
-    biome('1.2.0')
+    biome('2.1.0')
   }
   format 'biome-ts', {
     target '**/*.ts'
-    biome('1.2.0')
+    biome('2.1.0')
   }
   format 'biome-json', {
     target '**/*.json'
-    biome('1.2.0')
+    biome('2.1.0')
   }
 }
 ```
@@ -1476,6 +1476,7 @@ Note: Due to a limitation of biome, if the name of a file matches a pattern in
 the `ignore` option of the specified `biome.json` configuration file, it will not be
 formatted, even if included in the biome configuration section of the Gradle settings
 file.
+
 You could specify a different `biome.json` configuration file without an `ignore`
 pattern to circumvent this.
 
@@ -1553,7 +1554,29 @@ spotless {
     target '**/*.js','**/*.ts','**/*.json'
     // Must point to the directory with the "biome.json" config file -->
     // Relative paths are resolved against the project's base directory -->
-    biome('1.2.0').configPath('./config')
+    biome('2.1.0').configPath('./config')
+  }
+}
+```
+
+__If spotless does not format any files__, this might be because you excluded those files in you biome.json
+configuration file. If you are using biome 2.x, you can create a custom config file for spotless and inherit from
+your main config file like this:
+
+```jsonc
+// biome-spotless.json
+{
+  "extends": "./biome.json",
+  "include": ["**"]
+}
+```
+
+Then simply specify the path to this file in your spotless configuration:
+
+```gradle
+spotless {
+  format 'biome', {
+    biome('2.1.0').configPath('./config/biome-spotless.json')
   }
 }
 ```

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

@@ -31,10 +31,9 @@
 
 public abstract class BiomeStepConfig<Self extends BiomeStepConfig<Self>> {
 	/**
-	 * Optional path to the directory with configuration file for Biome. The file
-	 * must be named {@code biome.json}. When none is given, the default
-	 * configuration is used. If this is a relative path, it is resolved against the
-	 * project's base directory.
+	 * Optional path to the configuration file for Biome. Must be either a directory that contains a file named
+	 * {@code biome.json}, or a file that contains the Biome config as JSON. When none is given, the default
+	 * configuration is used. If this is a relative path, it is resolved against the project's base directory.
 	 */
 	@Nullable private Object configPath;
 

plugin-gradle/src/test/java/com/diffplug/gradle/spotless/BiomeIntegrationTest.java

@@ -19,6 +19,8 @@
 import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertTrue;
 
+import java.io.File;
+
 import org.junit.jupiter.api.Test;
 import org.owasp.encoder.Encode;
 
@@ -230,6 +232,34 @@ void configPathAbsolute() throws Exception {
 		assertFile("biome_test.js").sameAsResource("biome/js/longLineAfter120.js");
 	}
 
+	/**
+	 * Tests that a path to a Biome config JSON file can be specified (requires biome 2.x).
+	 *
+	 * @throws Exception When a test failure occurs.
+	 */
+	@Test
+	void configPathFile() throws Exception {
+		var path = newFile("configs").getAbsolutePath();
+		var file = new File(path, "biome.json").getAbsolutePath();
+		setFile("build.gradle").toLines(
+				"plugins {",
+				"    id 'com.diffplug.spotless'",
+				"}",
+				"repositories { mavenCentral() }",
+				"spotless {",
+				"    format 'mybiome', {",
+				"        target '**/*.js'",
+				"        biome('2.1.0').configPath('" + Encode.forJava(file) + "')",
+				"    }",
+				"}");
+		setFile("biome_test.js").toResource("biome/js/longLineBefore.js");
+		setFile("configs/biome.json").toResource("biome/config/line-width-120.json");
+
+		var spotlessApply = gradleRunner().withArguments("--stacktrace", "spotlessApply").build();
+		assertThat(spotlessApply.getOutput()).contains("BUILD SUCCESSFUL");
+		assertFile("biome_test.js").sameAsResource("biome/js/longLineAfter120.js");
+	}
+
 	/**
 	 * Tests that a path to the directory with the biome.json config file can be
 	 * specified. Uses a config file with a line width of 120.

plugin-maven/CHANGES.md

@@ -3,6 +3,8 @@
 We adhere to the [keepachangelog](https://keepachangelog.com/en/1.0.0/) format (starting after version `1.27.0`).
 
 ## [Unreleased]
+### Added
+* Allow specifying path to Biome JSON config file directly in `biome` step. Requires biome 2.x.
 
 ## [2.45.0] - 2025-07-07
 ### Added

plugin-maven/README.md

@@ -1530,9 +1530,9 @@ Note regarding CSS: Biome supports formatting CSS as of 1.8.0 (experimental, opt
 
       <biome>
         <!-- Download Biome from the network if not already downloaded, see below for more info  -->
-        <version>1.2.0</version>
+        <version>2.1.1</version>
 
-        <!-- (optional) Path to the directory with the biome.json conig file -->
+        <!-- (optional) Path to the directory with the biome.json config file -->
         <configPath>${project.basedir}/path/to/config/dir</configPath>
 
         <!-- (optional) Biome will auto-detect the language based on the file extension. -->
@@ -1583,7 +1583,7 @@ To download the Biome binary from the network, just specify a version:
 
 ```xml
 <biome>
-  <version>1.2.0</version>
+  <version>2.1.0</version>
 </biome>
 ```
 
@@ -1594,7 +1594,7 @@ Biome binaries (defaults to `~/.m2/repository/com/diffplug/spotless/spotless-dat
 
 ```xml
 <biome>
-  <version>1.2.0</version>
+  <version>2.1.0</version>
   <!-- Relative paths are resolved against the project's base directory -->
   <downloadDir>${user.home}/biome</downloadDir>
 </biome>
@@ -1631,10 +1631,31 @@ Biome is used. To use a custom configuration:
 <biome>
   <!-- Must point to the directory with the "biome.json" config file -->
   <!-- Relative paths are resolved against the project's base directory -->
+  <!-- Starting with biome 2.x, you can also pass the path to a JSON config file directly. -->
   <configPath>${project.basedir}</configPath>
 </biome>
 ```
 
+__If spotless does not format any files__, this might be because you excluded those files in you biome.json
+configuration file. If you are using biome 2.x, you can create a custom config file for spotless and inherit from
+your main config file like this:
+
+```jsonc
+// biome-spotless.json
+{
+  "extends": "./biome.json",
+  "include": ["**"]
+}
+```
+
+Then simply specify the path to this file in your spotless configuration:
+
+```xml
+<biome>
+  <configPath>${project.basedir}/biome-spotless.json</configPath>
+</biome>
+```
+
 ### Biome input language
 
 By default, Biome detects the language / syntax of the files to format