Verify the example .scala-steward.conf (#3571)

* Verify the example `.scala-steward.conf`

This checks that the example `.scala-steward.conf` in the docs is equivalent
to the JSON one gets when parsing, decoding and encoding that example.

With this change, the `docs/mdoc` task fails currently with:
```diff
error: repo-specific-configuration.md:211:1: Diff between parsed input (-) and encoded object (+):
         "groupId" : "com.example",
-        "version" : "2."
+        "version" : {
+          "prefix" : "2."
+        }
       },
       "pullRequests" : {
-        "frequency" : "30 day"
+        "frequency" : "30 days"
       }
       "pullRequests" : {
-        "frequency" : "14 day"
+        "frequency" : "14 days"
       }
   "signoffCommits" : true,
-  "updatePullRequests" : "always | on-conflicts | never",
+  "updatePullRequests" : "on-conflicts",
   "updates" : {
         "groupId" : "org.acme",
-        "version" : "1.0"
+        "version" : {
+          "prefix" : "1.0"
+        }
       }
         "groupId" : "com.example",
-        "version" : "1.1."
+        "version" : {
+          "prefix" : "1.1."
+        }
       }
```
In subsequent commits I'll will fix these reported differences.

Closes: #1341

* Change "day" to "days" if the value > 1

* Encode `VersionPattern` as `String` if only `prefix` is defined

* Use a valid value for `updatePullRequests`

Author: fthomas

build.sbt

@@ -1,7 +1,7 @@
 import com.typesafe.sbt.packager.docker.*
-import sbtcrossproject.{CrossProject, CrossType, Platform}
 import org.typelevel.sbt.gha.JavaSpec.Distribution.Temurin
 import org.typelevel.scalacoptions.ScalacOptions
+import sbtcrossproject.{CrossProject, CrossType, Platform}
 
 /// variables
 
@@ -250,7 +250,9 @@ lazy val docs = myCrossProject("docs")
   .enablePlugins(MdocPlugin)
   .settings(noPublishSettings)
   .settings(
+    libraryDependencies ++= Seq(Dependencies.munitDiff),
     scalacOptions += "-Ytasty-reader",
+    tpolecatExcludeOptions := Set(ScalacOptions.fatalWarnings),
     mdocIn := baseDirectory.value / ".." / "mdoc",
     mdocOut := (LocalRootProject / baseDirectory).value / "docs",
     mdocVariables := Map(

docs/repo-specific-configuration.md

@@ -139,7 +139,7 @@ updates.fileExtensions = [".scala", ".sbt", ".sbt.shared", ".sc", ".yml", ".md",
 # you don't change it yourself.
 # If "never", Scala Steward will never update the PR
 # Default: "on-conflicts"
-updatePullRequests = "always" | "on-conflicts" | "never"
+updatePullRequests = "always"
 
 # If set, Scala Steward will use this message template for the commit messages and PR titles.
 # Supported variables: ${artifactName}, ${currentVersion}, ${nextVersion} and ${default}
@@ -180,11 +180,11 @@ dependencyOverrides = [
   },
   {
     dependency = { groupId = "com.example", artifactId = "foo" },
-    pullRequests = { frequency = "30 day" },
+    pullRequests = { frequency = "30 days" },
   },
   {
     dependency = { groupId = "com.example" },
-    pullRequests = { frequency = "14 day" },
+    pullRequests = { frequency = "14 days" },
   }
 ]
 

modules/core/src/main/scala/org/scalasteward/core/repoconfig/VersionPattern.scala

@@ -32,6 +32,10 @@ final case class VersionPattern(
       suffix.forall(version.endsWith) &&
       exact.forall(_ === version) &&
       contains.forall(version.contains)
+
+  /** Returns `true` if only `prefix` is defined. */
+  private def isPrefixPattern: Boolean =
+    prefix.isDefined && suffix.isEmpty && exact.isEmpty && contains.isEmpty
 }
 
 object VersionPattern {
@@ -41,6 +45,9 @@ object VersionPattern {
   implicit val versionPatternDecoder: Decoder[VersionPattern] =
     deriveDecoder[VersionPattern].or(Decoder[String].map(s => VersionPattern(prefix = Some(s))))
 
-  implicit val versionPatternEncoder: Encoder[VersionPattern] =
-    deriveEncoder
+  implicit val versionPatternEncoder: Encoder[VersionPattern] = {
+    val prefixEncoder = Encoder.encodeOption[String]
+    val vpEncoder = deriveEncoder[VersionPattern]
+    Encoder.instance(vp => if (vp.isPrefixPattern) prefixEncoder(vp.prefix) else vpEncoder(vp))
+  }
 }

modules/docs/mdoc/repo-specific-configuration.md

@@ -5,12 +5,11 @@ The `[.]scala-steward.conf` configuration file can be located in the root of you
 If a configuration file exists in more than one location, only the first found file is taken into account.
 
 ```scala mdoc:passthrough
-import io.circe.refined._
-import io.circe.syntax._
-import org.scalasteward.core.repoconfig._
+import io.circe.refined.*
+import io.circe.syntax.*
+import org.scalasteward.core.repoconfig.*
 
-print("```properties")
-print(s"""
+val input = s"""
 # pullRequests.frequency allows to control how often or when Scala Steward
 # is allowed to create pull requests.
 #
@@ -145,7 +144,7 @@ updates.fileExtensions = [".scala", ".sbt", ".sbt.shared", ".sc", ".yml", ".md",
 # you don't change it yourself.
 # If "never", Scala Steward will never update the PR
 # Default: ${PullRequestUpdateStrategy.default.asJson.noSpaces}
-updatePullRequests = "always" | "on-conflicts" | "never"
+updatePullRequests = "always"
 
 # If set, Scala Steward will use this message template for the commit messages and PR titles.
 # Supported variables: $${artifactName}, $${currentVersion}, $${nextVersion} and $${default}
@@ -186,11 +185,11 @@ dependencyOverrides = [
   },
   {
     dependency = { groupId = "com.example", artifactId = "foo" },
-    pullRequests = { frequency = "30 day" },
+    pullRequests = { frequency = "30 days" },
   },
   {
     dependency = { groupId = "com.example" },
-    pullRequests = { frequency = "14 day" },
+    pullRequests = { frequency = "14 days" },
   }
 ]
 
@@ -207,7 +206,12 @@ reviewers = [ "username1", "username2" ]
 # If true, Scala Steward will sign off all commits (e.g. `git --signoff`).
 # Default: false
 signoffCommits = true
-""")
+"""
+
+DocChecker.verifyParsedEqualsEncoded[RepoConfig](input)
+
+print("```properties")
+print(input)
 println("```")
 ```
 

modules/docs/src/main/scala/DocChecker.scala

@@ -0,0 +1,42 @@
+/*
+ * Copyright 2018-2025 Scala Steward contributors
+ *
+ * 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.
+ */
+
+import io.circe.config.parser
+import io.circe.{Decoder, Encoder}
+import munit.diff.Diff
+
+object DocChecker {
+  def verifyParsedEqualsEncoded[A](input: String)(implicit
+      decoder: Decoder[A],
+      encoder: Encoder[A]
+  ): Unit = {
+    val res = parser.parse(input).flatMap { jsonFromStr =>
+      decoder.decodeJson(jsonFromStr).flatMap { a =>
+        val jsonFromObj = encoder.apply(a)
+        val diff = Diff(
+          jsonFromObj.deepDropNullValues.spaces2SortKeys,
+          jsonFromStr.deepDropNullValues.spaces2SortKeys
+        )
+        if (diff.isEmpty) Right(())
+        else {
+          val msg = "Diff between parsed input (-) and encoded object (+):\n" + diff.unifiedDiff
+          Left(new Throwable(msg))
+        }
+      }
+    }
+    res.fold(throw _, identity)
+  }
+}

project/Dependencies.scala

@@ -36,6 +36,7 @@ object Dependencies {
   val monocleCore = "dev.optics" %% "monocle-core" % "3.3.0"
   val munit = "org.scalameta" %% "munit" % "1.1.0"
   val munitCatsEffect = "org.typelevel" %% "munit-cats-effect" % "2.0.0"
+  val munitDiff = "org.scalameta" %% "munit-diff" % munit.revision
   val munitScalacheck = "org.scalameta" %% "munit-scalacheck" % "1.1.0"
   val refined = "eu.timepit" %% "refined" % "0.11.3"
   val refinedScalacheck = "eu.timepit" %% "refined-scalacheck" % refined.revision