Add maxRuleVersion configuration for version-based rule filtering

Based on #942

Author: Hugo Costa

CHANGELOG.md

@@ -7,6 +7,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+- Add maxRuleVersion configuration for version-based rule filtering [#943](https://github.com/JLLeitschuh/ktlint-gradle/pull/943)
+
 ## [13.1.0] - 2025-08-21
 
 - Gradle 9 Support [#937](https://github.com/JLLeitschuh/ktlint-gradle/pull/937)

README.md

@@ -309,6 +309,7 @@ ktlint {
         "max_line_length": "20"
     ]
     disabledRules = ["final-newline"] // not supported with ktlint 0.48+
+    maxRuleVersion = "1.0.0" // Only include rules introduced up to this version
     baseline = file("my-project-ktlint-baseline.xml")
     reporters {
         reporter "plain"
@@ -366,6 +367,7 @@ configure<org.jlleitschuh.gradle.ktlint.KtlintExtension> {
         )
     )
     disabledRules.set(setOf("final-newline")) // not supported with ktlint 0.48+
+    maxRuleVersion.set("1.0.0") // Only include rules introduced up to this version
     baseline.set(file("my-project-ktlint-baseline.xml"))
     reporters {
         reporter(ReporterType.PLAIN)

plugin/src/adapter100/kotlin/org/jlleitschuh/gradle/ktlint/worker/KtLintInvocation100.kt

@@ -7,15 +7,20 @@ import com.pinterest.ktlint.rule.engine.api.EditorConfigPropertyRegistry
 import com.pinterest.ktlint.rule.engine.api.KtLintRuleEngine
 import com.pinterest.ktlint.rule.engine.api.LintError
 import com.pinterest.ktlint.rule.engine.core.api.RuleProvider
+import com.pinterest.ktlint.rule.engine.core.api.SinceKtlint
+import net.swiftzer.semver.SemVer
 import java.io.File
 import java.util.ServiceLoader
 
 class KtLintInvocation100(
     private val engine: KtLintRuleEngine
 ) : KtLintInvocation {
     companion object Factory : KtLintInvocationFactory {
-        fun initialize(editorConfigOverrides: Map<String, String>): KtLintInvocation {
-            val ruleProviders = loadRuleSetsFromClasspathWithRuleSetProviderV3()
+        fun initialize(
+            editorConfigOverrides: Map<String, String>,
+            maxRuleVersion: String? = null
+        ): KtLintInvocation {
+            val ruleProviders = loadRuleSetsFromClasspathWithRuleSetProviderV3(maxRuleVersion)
             val editorConfigPropertyRegistry = EditorConfigPropertyRegistry(ruleProviders)
             val engine = if (editorConfigOverrides.isEmpty()) {
                 KtLintRuleEngine(ruleProviders = ruleProviders)
@@ -34,11 +39,62 @@ class KtLintInvocation100(
             return KtLintInvocation100(engine)
         }
 
-        private fun loadRuleSetsFromClasspathWithRuleSetProviderV3(): Set<RuleProvider> {
-            return ServiceLoader
+        private fun loadRuleSetsFromClasspathWithRuleSetProviderV3(maxRuleVersion: String?): Set<RuleProvider> {
+            val allRuleProviders = ServiceLoader
                 .load(RuleSetProviderV3::class.java)
                 .flatMap { it.getRuleProviders() }
                 .toSet()
+
+            return if (maxRuleVersion != null) {
+                filterRulesByVersion(allRuleProviders, maxRuleVersion)
+            } else {
+                allRuleProviders
+            }
+        }
+
+        private fun filterRulesByVersion(ruleProviders: Set<RuleProvider>, maxVersion: String): Set<RuleProvider> {
+            return ruleProviders.filter { ruleProvider ->
+                isRuleCompatibleWithVersion(ruleProvider, maxVersion)
+            }.toSet()
+        }
+
+        private fun isRuleCompatibleWithVersion(ruleProvider: RuleProvider, maxVersion: String): Boolean {
+            // Use reflection to check for @SinceKtlint annotation
+            val ruleClass = ruleProvider.createNewRuleInstance()::class.java
+            val sinceAnnotation = ruleClass.getAnnotation(SinceKtlint::class.java)
+
+            return if (sinceAnnotation != null) {
+                isVersionCompatible(sinceAnnotation.version, maxVersion)
+            } else {
+                // If no annotation, assume it's from an older ktlint version (before annotations were included
+                // at runtime) and include it for backward compatibility
+                true
+            }
+        }
+
+        /**
+         * Checks if a rule version is compatible with the specified maximum version.
+         *
+         * A rule is considered compatible if its version is less than or equal to the maximum version.
+         * Version comparison follows semantic versioning rules:
+         * - "0.46" <= "1.0.0" → true
+         * - "1.2.1" <= "1.2.0" → false
+         * - "1.0" <= "1.0.0" → true (missing parts treated as 0)
+         *
+         * @param ruleVersion The version when the rule was introduced (from @SinceKtlint annotation)
+         * @param maxVersion The maximum allowed version (from maxRuleVersion configuration)
+         * @return true if the rule version is compatible (should be included), false otherwise
+         */
+        private fun isVersionCompatible(ruleVersion: String, maxVersion: String): Boolean {
+            return try {
+                SemVer.parse(ruleVersion) <= SemVer.parse(maxVersion)
+            } catch (_: Exception) {
+                // If version parsing fails (invalid format), assume it's incompatible.
+                // We would only get to this point if the user is using a version with the runtime annotations
+                // and they are specifically asking for a lower version.
+                // All standard ktlint rules should have valid version formats.
+                false
+            }
         }
     }
 

plugin/src/main/kotlin/org/jlleitschuh/gradle/ktlint/KtlintExtension.kt

@@ -99,6 +99,18 @@ open class KtlintExtension @Inject internal constructor(
         set(false)
     }
 
+    /**
+     * Only include rules that were introduced in KtLint versions up to and including this version.
+     * When set, rules with @SinceKtlint annotations indicating they were added after this version will be excluded.
+     * Rules without the annotation (from older ktlint versions) are always included for backward compatibility.
+     *
+     * Format: "0.46.0", "0.47.1", etc.
+     * Default: null (no filtering - all rules are included)
+     *
+     * Example: `maxRuleVersion.set("0.46.0")` will exclude rules added in 0.47.0 and later.
+     */
+    val maxRuleVersion: Property<String> = objectFactory.property(String::class.java)
+
     /**
      * Provide additional `.editorconfig` properties, that are not in the project or project parent folders.
      */

plugin/src/main/kotlin/org/jlleitschuh/gradle/ktlint/TaskCreation.kt

@@ -136,6 +136,7 @@ private fun BaseKtLintCheckTask.configureBaseCheckTask(
     android.set(pluginHolder.extension.android)
     loadedReporters.set(pluginHolder.loadReportersTask.get().loadedReporters)
     enableExperimentalRules.set(pluginHolder.extension.enableExperimentalRules)
+    maxRuleVersion.set(pluginHolder.extension.maxRuleVersion)
 
     additionalTaskConfig()
 }

plugin/src/main/kotlin/org/jlleitschuh/gradle/ktlint/tasks/BaseKtLintCheckTask.kt

@@ -20,6 +20,7 @@ import org.gradle.api.tasks.Input
 import org.gradle.api.tasks.InputFile
 import org.gradle.api.tasks.InputFiles
 import org.gradle.api.tasks.Internal
+import org.gradle.api.tasks.Optional
 import org.gradle.api.tasks.OutputFile
 import org.gradle.api.tasks.PathSensitive
 import org.gradle.api.tasks.PathSensitivity
@@ -80,6 +81,10 @@ abstract class BaseKtLintCheckTask @Inject constructor(
     @get:Input
     internal abstract val enableExperimentalRules: Property<Boolean>
 
+    @get:Input
+    @get:Optional
+    internal abstract val maxRuleVersion: Property<String>
+
     /**
      * Max lint worker heap size. Default is "256m".
      */
@@ -279,6 +284,7 @@ abstract class BaseKtLintCheckTask @Inject constructor(
             ktLintVersion.set(task.ktLintVersion)
             editorconfigFilesWereChanged.set(editorConfigUpdated)
             this.formatSnapshot.set(formatSnapshot)
+            maxRuleVersion.set(task.maxRuleVersion)
         }
     }
 

plugin/src/main/kotlin/org/jlleitschuh/gradle/ktlint/worker/KtLintWorkAction.kt

@@ -29,7 +29,10 @@ abstract class KtLintWorkAction : WorkAction<KtLintWorkAction.KtLintWorkParamete
             val ktlintInvokerFactory = selectInvocation(parameters.ktLintVersion.get())
         ) {
             is KtLintInvocation100.Factory -> {
-                ktlintInvokerFactory.initialize(parameters.additionalEditorconfig.get())
+                ktlintInvokerFactory.initialize(
+                    parameters.additionalEditorconfig.get(),
+                    parameters.maxRuleVersion.orNull
+                )
             }
 
             else -> {
@@ -97,6 +100,7 @@ abstract class KtLintWorkAction : WorkAction<KtLintWorkAction.KtLintWorkParamete
         val ktLintVersion: Property<String>
         val editorconfigFilesWereChanged: Property<Boolean>
         val formatSnapshot: RegularFileProperty
+        val maxRuleVersion: Property<String>
     }
 
     /**

plugin/src/test/kotlin/org/jlleitschuh/gradle/ktlint/KtlintPluginTest.kt

@@ -716,4 +716,37 @@ dependencies {
             }
         }
     }
+
+    @DisplayName("Should allow setting maxRuleVersion")
+    @CommonTest
+    fun allowMaxRuleVersionConfiguration(gradleVersion: GradleVersion) {
+        project(gradleVersion) {
+            withCleanSources()
+            //language=Groovy
+            buildGradle.appendText(
+                """
+
+                ktlint {
+                    maxRuleVersion = "1.0.0"
+                }
+                """.trimIndent()
+            )
+
+            build(CHECK_PARENT_TASK_NAME) {
+                assertThat(task(":$mainSourceSetCheckTaskName")?.outcome).isEqualTo(TaskOutcome.SUCCESS)
+            }
+        }
+    }
+
+    @DisplayName("Should work without maxRuleVersion set")
+    @CommonTest
+    fun workWithoutMaxRuleVersion(gradleVersion: GradleVersion) {
+        project(gradleVersion) {
+            withCleanSources()
+
+            build(CHECK_PARENT_TASK_NAME) {
+                assertThat(task(":$mainSourceSetCheckTaskName")?.outcome).isEqualTo(TaskOutcome.SUCCESS)
+            }
+        }
+    }
 }