Redux: Dependency Cooldowns, post #3787

modules/benchmark/src/main/scala/org/scalasteward/benchmark/UpdatesConfigBenchmark.scala

@@ -21,6 +21,7 @@ import org.openjdk.jmh.annotations.{Benchmark, BenchmarkMode, Mode, OutputTimeUn
 import org.scalasteward.core.data.*
 import org.scalasteward.core.repoconfig.{UpdatePattern, UpdatesConfig, VersionPattern}
 import org.scalasteward.core.util.Nel
+import org.scalasteward.core.coursier.VersionsCache.VersionWithFirstSeen
 
 @BenchmarkMode(Array(Mode.AverageTime))
 class UpdatesConfigBenchmark {
@@ -32,7 +33,7 @@ class UpdatesConfigBenchmark {
     val dependency = CrossDependency(Dependency(groupId, ArtifactId("artifact"), Version("1.0.0")))
     val newerVersions = Nel
       .of("2.0.0", "2.1.0", "2.1.1", "2.2.0", "3.0.0", "3.1.0", "3.2.1", "3.3.3", "4.0", "5.0")
-      .map(Version.apply)
+      .map(v => VersionWithFirstSeen(Version(v), None))
     val update = ArtifactUpdateCandidates(ArtifactForUpdate(dependency), newerVersions)
 
     UpdatesConfig().keep(update)

modules/core/src/main/scala/org/scalasteward/core/buildtool/sbt/SbtAlg.scala

@@ -129,7 +129,7 @@ final class SbtAlg[F[_]](defaultResolvers: List[Resolver], ignoreOptsFiles: Bool
   private def latestSbtScalafixVersion: F[Option[Version]] =
     versionsCache
       .getVersions(Scope(sbtScalafixDependency, defaultResolvers), None)
-      .map(_.lastOption)
+      .map(_.lastOption.map(_.version))
 
   private def runBuildMigration(buildRoot: BuildRoot, migration: ScalafixMigration): F[Unit] =
     for {

modules/core/src/main/scala/org/scalasteward/core/coursier/VersionsCache.scala

@@ -18,12 +18,13 @@ package org.scalasteward.core.coursier
 
 import cats.implicits.*
 import cats.{MonadThrow, Parallel}
-import io.circe.generic.semiauto.deriveCodec
-import io.circe.{Codec, KeyEncoder}
-import org.scalasteward.core.coursier.VersionsCache.{Key, Value}
+import io.circe.generic.semiauto.{deriveCodec, deriveDecoder, deriveEncoder}
+import io.circe.{Codec, Decoder, Encoder, KeyEncoder}
+import org.scalasteward.core.coursier.VersionsCache.{Key, Value, VersionWithFirstSeen}
 import org.scalasteward.core.data.{Dependency, Resolver, Scope, Version}
 import org.scalasteward.core.persistence.KeyValueStore
 import org.scalasteward.core.util.{DateTimeAlg, Timestamp}
+
 import scala.concurrent.duration.FiniteDuration
 
 final class VersionsCache[F[_]](
@@ -35,16 +36,19 @@ final class VersionsCache[F[_]](
     parallel: Parallel[F],
     F: MonadThrow[F]
 ) {
-  def getVersions(dependency: Scope.Dependency, maxAge: Option[FiniteDuration]): F[List[Version]] =
+  def getVersions(
+      dependency: Scope.Dependency,
+      maxAge: Option[FiniteDuration]
+  ): F[List[VersionWithFirstSeen]] =
     dependency.resolvers
       .parFlatTraverse(getVersionsImpl(dependency.value, _, maxAge.getOrElse(cacheTtl)))
-      .map(_.distinct.sorted)
+      .map(_.distinct.sortBy(_.version))
 
   private def getVersionsImpl(
       dependency: Dependency,
       resolver: Resolver,
       maxAge: FiniteDuration
-  ): F[List[Version]] =
+  ): F[List[VersionWithFirstSeen]] =
     dateTimeAlg.currentTimestamp.flatMap { now =>
       val key = Key(dependency, resolver)
       store.get(key).flatMap {
@@ -53,7 +57,18 @@ final class VersionsCache[F[_]](
         case maybeValue =>
           coursierAlg.getVersions(dependency, resolver).attempt.flatMap {
             case Right(versions) =>
-              store.put(key, Value(now, versions, None)).as(versions)
+              val existingFirstSeenByVersion: Map[Version, Timestamp] =
+                maybeValue
+                  .map(_.versions.flatMap(vwfs => vwfs.firstSeen.map(vwfs.version -> _)).toMap)
+                  .getOrElse(Map.empty)
+              val updatedVersionsWithFirstSeen =
+                versions.map(v =>
+                  VersionWithFirstSeen(v, Some(existingFirstSeenByVersion.getOrElse(v, now)))
+                )
+
+              store
+                .put(key, Value(now, updatedVersionsWithFirstSeen, None))
+                .as(updatedVersionsWithFirstSeen)
             case Left(throwable) =>
               val versions = maybeValue.map(_.versions).getOrElse(List.empty)
               store.put(key, Value(now, versions, Some(throwable.toString))).as(versions)
@@ -79,7 +94,7 @@ object VersionsCache {
 
   final case class Value(
       updatedAt: Timestamp,
-      versions: List[Version],
+      versions: List[VersionWithFirstSeen],
       maybeError: Option[String]
   ) {
     def maxAgeFactor: Long =
@@ -90,4 +105,18 @@ object VersionsCache {
     implicit val valueCodec: Codec[Value] =
       deriveCodec
   }
+
+  final case class VersionWithFirstSeen(
+      version: Version,
+      firstSeen: Option[Timestamp]
+  )
+
+  object VersionWithFirstSeen {
+    implicit val valueEncoder: Encoder[VersionWithFirstSeen] = deriveEncoder
+    implicit val valueDecoder: Decoder[VersionWithFirstSeen] = {
+      val legacyVersionStringDecoder = Decoder[Version].map(VersionWithFirstSeen(_, None))
+
+      deriveDecoder[VersionWithFirstSeen].or(legacyVersionStringDecoder)
+    }
+  }
 }

modules/core/src/main/scala/org/scalasteward/core/data/Update.scala

@@ -22,6 +22,7 @@ import io.circe.{Decoder, Encoder}
 import org.scalasteward.core.repoconfig.PullRequestGroup
 import org.scalasteward.core.util
 import org.scalasteward.core.util.Nel
+import org.scalasteward.core.coursier.VersionsCache.VersionWithFirstSeen
 
 case class ArtifactForUpdate(
     crossDependency: CrossDependency,
@@ -34,7 +35,7 @@ case class ArtifactForUpdate(
   def currentVersion: Version = headDependency.version
 }
 
-trait ArtifactUpdateVersions {
+trait ArtifactUpdateVersions[V] {
   val artifactForUpdate: ArtifactForUpdate
 
   val refersToUpdateVersions: Nel[Version]
@@ -49,15 +50,17 @@ trait ArtifactUpdateVersions {
   */
 case class ArtifactUpdateCandidates(
     artifactForUpdate: ArtifactForUpdate,
-    newerVersions: Nel[Version]
-) extends ArtifactUpdateVersions {
+    newerVersionsWithFirstSeen: Nel[VersionWithFirstSeen]
+) extends ArtifactUpdateVersions[VersionWithFirstSeen] {
+  val newerVersions: Nel[Version] = newerVersionsWithFirstSeen.map(_.version)
+
   override val refersToUpdateVersions: Nel[Version] = newerVersions
 
   def asSpecificUpdate(nextVersion: Version): Update.ForArtifactId =
     Update.ForArtifactId(artifactForUpdate, nextVersion)
 
   override def show: String =
-    s"${artifactForUpdate.groupId}:${artifactForUpdate.crossDependency.showArtifactNames} : ${Version.show((artifactForUpdate.currentVersion +: refersToUpdateVersions.toList)*)}"
+    s"${artifactForUpdate.groupId}:${artifactForUpdate.crossDependency.showArtifactNames} : ${Version.show((artifactForUpdate.currentVersion +: newerVersionsWithFirstSeen.map(_.version).toList)*)}"
 }
 
 sealed trait Update {
@@ -124,7 +127,7 @@ object Update {
       artifactForUpdate: ArtifactForUpdate,
       nextVersion: Version
   ) extends Single
-      with ArtifactUpdateVersions {
+      with ArtifactUpdateVersions[Version] {
     val crossDependency: CrossDependency = artifactForUpdate.crossDependency
 
     override val refersToUpdateVersions: Nel[Version] = Nel.one(nextVersion)

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

@@ -0,0 +1,37 @@
+/*
+ * 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.
+ */
+
+package org.scalasteward.core.repoconfig
+
+import io.circe.{Codec, Decoder, Encoder}
+import io.circe.generic.semiauto.deriveCodec
+import scala.concurrent.duration.FiniteDuration
+import cats.syntax.either.*
+
+import org.scalasteward.core.util.dateTime.parseFiniteDuration
+
+final case class CooldownConfig(
+    age: FiniteDuration,
+    artifacts: List[UpdatePattern] = List.empty
+)
+
+object CooldownConfig {
+  implicit val codec: Codec[CooldownConfig] = deriveCodec
+  implicit val finiteDurationDecoder: Decoder[FiniteDuration] =
+    Decoder[String].emap(s => parseFiniteDuration(s).leftMap(_.toString))
+  implicit val finiteDurationEncoder: Encoder[FiniteDuration] =
+    Encoder[String].contramap(_.toString)
+}

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

@@ -19,7 +19,8 @@ package org.scalasteward.core.repoconfig
 import cats.syntax.all.*
 import io.circe.Codec
 import io.circe.generic.semiauto.*
-import org.scalasteward.core.data.{ArtifactUpdateVersions, GroupId, Version}
+import org.scalasteward.core.coursier.VersionsCache.VersionWithFirstSeen
+import org.scalasteward.core.data.{ArtifactUpdateVersions, GroupId}
 
 final case class UpdatePattern(
     groupId: GroupId,
@@ -32,20 +33,26 @@ final case class UpdatePattern(
 object UpdatePattern {
   final case class MatchResult(
       byArtifactId: List[UpdatePattern],
-      filteredVersions: List[Version]
+      filteredVersions: List[VersionWithFirstSeen]
   )
 
-  def findMatch(
+  def findMatch[V](
       patterns: List[UpdatePattern],
-      update: ArtifactUpdateVersions,
-      include: Boolean
+      update: ArtifactUpdateVersions[V],
+      include: Boolean,
+      versionPredicate: V => Boolean = _ => true
   ): MatchResult = {
     val artifactForUpdate = update.artifactForUpdate
     val byGroupId = patterns.filter(_.groupId === artifactForUpdate.groupId)
     val byArtifactId =
       byGroupId.filter(_.artifactId.forall(_ === artifactForUpdate.artifactId.name))
     val filteredVersions = update.refersToUpdateVersions.filter(newVersion =>
-      byArtifactId.exists(_.version.forall(_.matches(newVersion.value))) === include
+      (byArtifactId.exists(
+        _.version.forall(_.matches(newVersion.version.value))
+      ) && versionPredicate(
+        newVersion
+      ))
+        === include
     )
     MatchResult(byArtifactId, filteredVersions)
   }

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

@@ -40,7 +40,8 @@ final case class UpdatesConfig(
     private val ignore: Option[List[UpdatePattern]] = None,
     private val retracted: Option[List[RetractedArtifact]] = None,
     limit: Option[NonNegInt] = UpdatesConfig.defaultLimit,
-    private val fileExtensions: Option[List[String]] = None
+    private val fileExtensions: Option[List[String]] = None,
+    private val cooldown: Option[List[CooldownConfig]] = None
 ) {
   private[repoconfig] def pinOrDefault: List[UpdatePattern] =
     pin.getOrElse(Nil)
@@ -76,7 +77,7 @@ final case class UpdatesConfig(
   private def isAllowed(update: ArtifactUpdateCandidates): FilterResult = {
     val m = UpdatePattern.findMatch(allowOrDefault, update, include = true)
     if (m.filteredVersions.nonEmpty)
-      Right(update.copy(newerVersions = Nel.fromListUnsafe(m.filteredVersions)))
+      Right(update.copy(newerVersionsWithFirstSeen = Nel.fromListUnsafe(m.filteredVersions)))
     else if (allowOrDefault.isEmpty)
       Right(update)
     else Left(NotAllowedByConfig(update))
@@ -85,7 +86,7 @@ final case class UpdatesConfig(
   private def isPinned(update: ArtifactUpdateCandidates): FilterResult = {
     val m = UpdatePattern.findMatch(pinOrDefault, update, include = true)
     if (m.filteredVersions.nonEmpty)
-      Right(update.copy(newerVersions = Nel.fromListUnsafe(m.filteredVersions)))
+      Right(update.copy(newerVersionsWithFirstSeen = Nel.fromListUnsafe(m.filteredVersions)))
     else if (m.byArtifactId.isEmpty)
       Right(update)
     else Left(VersionPinnedByConfig(update))
@@ -94,7 +95,7 @@ final case class UpdatesConfig(
   private def isIgnored(update: ArtifactUpdateCandidates): FilterResult = {
     val m = UpdatePattern.findMatch(ignoreOrDefault, update, include = false)
     if (m.filteredVersions.nonEmpty)
-      Right(update.copy(newerVersions = Nel.fromListUnsafe(m.filteredVersions)))
+      Right(update.copy(newerVersionsWithFirstSeen = Nel.fromListUnsafe(m.filteredVersions)))
     else
       Left(IgnoredByConfig(update))
   }

modules/core/src/main/scala/org/scalasteward/core/update/FilterAlg.scala

@@ -43,7 +43,7 @@ object FilterAlg {
   type FilterResult = Either[RejectionReason, ArtifactUpdateCandidates]
 
   sealed trait RejectionReason {
-    def update: ArtifactUpdateVersions
+    def update: ArtifactUpdateVersions[?]
     def show: String =
       this match {
         case IgnoredByConfig(_)         => "ignored by config"
@@ -79,9 +79,10 @@ object FilterAlg {
         // already on Scala Next
         Right(update)
       } else {
-        val filteredVersions = update.newerVersions.filterNot(_ >= scalaNextMinVersion)
+        val filteredVersions =
+          update.newerVersionsWithFirstSeen.filterNot(v => v.version >= scalaNextMinVersion)
         if (filteredVersions.nonEmpty)
-          Right(update.copy(newerVersions = Nel.fromListUnsafe(filteredVersions)))
+          Right(update.copy(newerVersionsWithFirstSeen = Nel.fromListUnsafe(filteredVersions)))
         else
           Left(IgnoreScalaNext(update))
       }

modules/core/src/main/scala/org/scalasteward/core/update/UpdateAlg.scala

@@ -84,9 +84,9 @@ final class UpdateAlg[F[_]](implicit
   private def findNewerVersions(
       dependency: Scope[Dependency],
       maxAge: Option[FiniteDuration]
-  ): OptionT[F, Nel[Version]] =
+  ): OptionT[F, Nel[VersionsCache.VersionWithFirstSeen]] =
     OptionT(versionsCache.getVersions(dependency, maxAge).map { versions =>
-      Nel.fromList(versions.filter(_ > dependency.value.version))
+      Nel.fromList(versions.filter(v => v.version > dependency.value.version))
     })
 }
 

modules/core/src/test/resources/versions-cache-value-with-first-seen.json

@@ -0,0 +1,8 @@
+{
+    "updatedAt": 10002,
+    "versions": [
+        { "version": "1.0.0", "firstSeen": 10000 },
+        { "version": "1.0.1", "firstSeen": 10001 }
+    ],
+    "maybeError": null
+}

modules/core/src/test/resources/versions-cache-value-without-first-seen.json

@@ -0,0 +1,5 @@
+{
+    "updatedAt": 1000,
+    "versions": ["1.0.0", "1.0.1"],
+    "maybeError": null
+}

modules/core/src/test/scala/org/scalasteward/core/TestSyntax.scala

@@ -3,6 +3,7 @@ package org.scalasteward.core
 import org.scalasteward.core.data.*
 import org.scalasteward.core.data.Resolver.IvyRepository
 import org.scalasteward.core.util.Nel
+import org.scalasteward.core.coursier.VersionsCache.VersionWithFirstSeen
 
 object TestSyntax {
   val sbtPluginReleases: IvyRepository = {
@@ -19,6 +20,7 @@ object TestSyntax {
     def g: GroupId = GroupId(self)
     def a: ArtifactId = ArtifactId(self)
     def v: Version = Version(self)
+    def vfs: VersionWithFirstSeen = VersionWithFirstSeen(Version(self), None)
   }
 
   implicit class StringTupleOps(private val self: (String, String)) extends AnyVal {

modules/core/src/test/scala/org/scalasteward/core/coursier/VersionsCacheTest.scala

@@ -0,0 +1,37 @@
+package org.scalasteward.core.coursier
+
+import io.circe.parser
+import munit.FunSuite
+import org.scalasteward.core.coursier.VersionsCache.{Value, VersionWithFirstSeen}
+import org.scalasteward.core.data.Version
+import org.scalasteward.core.util.Timestamp
+
+import scala.io.Source
+
+class VersionsCacheTest extends FunSuite {
+  test("version cache deserialisation without first seen") {
+    val input = Source.fromResource("versions-cache-value-without-first-seen.json").mkString
+    val expected = Value(
+      Timestamp(1000),
+      List(
+        VersionWithFirstSeen(Version("1.0.0"), None),
+        VersionWithFirstSeen(Version("1.0.1"), None)
+      ),
+      None
+    )
+    assertEquals(parser.decode[Value](input), Right(expected))
+  }
+
+  test("version cache deserialisation with first seen") {
+    val input = Source.fromResource("versions-cache-value-with-first-seen.json").mkString
+    val expected = Value(
+      Timestamp(10002),
+      List(
+        VersionWithFirstSeen(Version("1.0.0"), Some(Timestamp(10000))),
+        VersionWithFirstSeen(Version("1.0.1"), Some(Timestamp(10001)))
+      ),
+      None
+    )
+    assertEquals(parser.decode[Value](input), Right(expected))
+  }
+}

modules/core/src/test/scala/org/scalasteward/core/update/FilterAlgTest.scala

@@ -292,7 +292,10 @@ class FilterAlgTest extends FunSuite {
         "3.3.3",
         "3.4.0"
       )).single
-    assertEquals(scalaLTSFilter(update), Right(update.copy(newerVersions = Nel.of("3.3.3".v))))
+    assertEquals(
+      scalaLTSFilter(update),
+      Right(update.copy(newerVersionsWithFirstSeen = Nel.of("3.3.3".vfs)))
+    )
   }
 
   test("scalaLTSFilter: Next") {