Add dependency-cooldowns / minimum-artifact-age

docs/repo-specific-configuration.md

@@ -109,6 +109,15 @@ updates.pin  = [ { groupId = "com.example", artifactId="foo", version = "1.1." }
 # Defaults to empty `[]` which mean Scala Steward will not ignore dependencies.
 updates.ignore = [ { groupId = "org.acme", artifactId="foo", version = "1.0" } ]
 
+# Scala Steward will ignore dependency update versions while they are newer than
+# the specified minimum age.
+#
+# Scala Steward records the first time it sees any artefact version and calculates
+# the artefact version's age from that time.
+updates.cooldown = {
+  minimumAge: "7 days"
+}
+
 # The dependencies which match the given pattern are retracted. Their existing pull-request will be closed.
 #
 # Each entry must have a `reason`, a `doc` URL and a list of dependency patterns.

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

@@ -20,7 +20,8 @@ import java.util.concurrent.TimeUnit
 import org.openjdk.jmh.annotations.{Benchmark, BenchmarkMode, Mode, OutputTimeUnit}
 import org.scalasteward.core.data.*
 import org.scalasteward.core.repoconfig.{UpdatePattern, UpdatesConfig, VersionPattern}
-import org.scalasteward.core.util.Nel
+import org.scalasteward.core.util.{Nel, Timestamp}
+import org.scalasteward.core.coursier.VersionsCache.VersionWithFirstSeen
 
 @BenchmarkMode(Array(Mode.AverageTime))
 class UpdatesConfigBenchmark {
@@ -32,13 +33,14 @@ 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)
+    val currentTime = Timestamp(millis = 0)
 
-    UpdatesConfig().keep(update)
-    UpdatesConfig(allow = Some(List(UpdatePattern(groupId, None, None)))).keep(update)
+    UpdatesConfig().keep(update, currentTime)
+    UpdatesConfig(allow = Some(List(UpdatePattern(groupId, None, None)))).keep(update, currentTime)
     UpdatesConfig(allow =
       Some(List(UpdatePattern(groupId, None, Some(VersionPattern(prefix = Some("6.0"))))))
-    ).keep(update)
+    ).keep(update, currentTime)
   }
 }

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,21 @@ object VersionsCache {
     implicit val valueCodec: Codec[Value] =
       deriveCodec
   }
+
+  final case class VersionWithFirstSeen(
+      version: Version,
+      firstSeen: Option[Timestamp]
+  ) {
+    def isOlderThan(age: FiniteDuration, currentTime: Timestamp): Boolean =
+      firstSeen.exists(_.until(currentTime) > age)
+  }
+
+  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,
@@ -49,15 +50,27 @@ trait ArtifactUpdateVersions {
   */
 case class ArtifactUpdateCandidates(
     artifactForUpdate: ArtifactForUpdate,
-    newerVersions: Nel[Version]
+    newerVersionsWithFirstSeen: Nel[VersionWithFirstSeen]
 ) extends ArtifactUpdateVersions {
+  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 +: newerVersions.toList)*)}"
+
+  def filterVersions(p: Version => Boolean): Option[ArtifactUpdateCandidates] =
+    filterVersionsWithFirstSeen(vwfs => p(vwfs.version))
+
+  def filterVersionsWithFirstSeen(
+      p: VersionWithFirstSeen => Boolean
+  ): Option[ArtifactUpdateCandidates] =
+    Nel
+      .fromList(newerVersionsWithFirstSeen.filter(p))
+      .map(x => copy(newerVersionsWithFirstSeen = x))
 }
 
 sealed trait Update {

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

@@ -0,0 +1,44 @@
+/*
+ * 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 cats.implicits.*
+import io.circe.generic.semiauto.deriveCodec
+import io.circe.{Codec, Decoder, Encoder}
+import org.scalasteward.core.data.ArtifactUpdateCandidates
+import org.scalasteward.core.util.Timestamp
+import org.scalasteward.core.util.dateTime.parseFiniteDuration
+
+import scala.concurrent.duration.FiniteDuration
+
+final case class CooldownConfig(
+    minimumAge: FiniteDuration
+) {
+  def filterForAge(
+      updateCandidates: ArtifactUpdateCandidates,
+      currentTime: Timestamp
+  ): Option[ArtifactUpdateCandidates] =
+    updateCandidates.filterVersionsWithFirstSeen(_.isOlderThan(minimumAge, currentTime))
+}
+
+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

@@ -32,7 +32,7 @@ final case class UpdatePattern(
 object UpdatePattern {
   final case class MatchResult(
       byArtifactId: List[UpdatePattern],
-      filteredVersions: List[Version]
+      filteredVersions: Set[Version]
   )
 
   def findMatch(
@@ -47,7 +47,7 @@ object UpdatePattern {
     val filteredVersions = update.refersToUpdateVersions.filter(newVersion =>
       byArtifactId.exists(_.version.forall(_.matches(newVersion.value))) === include
     )
-    MatchResult(byArtifactId, filteredVersions)
+    MatchResult(byArtifactId, filteredVersions.toSet)
   }
 
   implicit val updatePatternCodec: Codec[UpdatePattern] =

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

@@ -25,13 +25,8 @@ import io.circe.{Codec, Decoder}
 import org.scalasteward.core.buildtool.{gradle, maven, mill, sbt}
 import org.scalasteward.core.data.{ArtifactUpdateCandidates, GroupId}
 import org.scalasteward.core.scalafmt
-import org.scalasteward.core.update.FilterAlg.{
-  FilterResult,
-  IgnoredByConfig,
-  NotAllowedByConfig,
-  VersionPinnedByConfig
-}
-import org.scalasteward.core.util.{combineOptions, intellijThisImportIsUsed, Nel}
+import org.scalasteward.core.update.FilterAlg.*
+import org.scalasteward.core.util.{combineOptions, intellijThisImportIsUsed, Timestamp}
 
 final case class UpdatesConfig(
     private val pin: Option[List[UpdatePattern]] = None,
@@ -40,7 +35,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[CooldownConfig] = None
 ) {
   private[repoconfig] def pinOrDefault: List[UpdatePattern] =
     pin.getOrElse(Nil)
@@ -60,8 +56,8 @@ final case class UpdatesConfig(
   def fileExtensionsOrDefault: Set[String] =
     fileExtensions.fold(UpdatesConfig.defaultFileExtensions)(_.toSet)
 
-  def keep(update: ArtifactUpdateCandidates): FilterResult =
-    isAllowed(update).flatMap(isPinned).flatMap(isIgnored)
+  def keep(update: ArtifactUpdateCandidates, currentTime: Timestamp): FilterResult =
+    isAllowed(update).flatMap(isPinned).flatMap(isIgnored).flatMap(isTooRecent(_, currentTime))
 
   def preRelease(update: ArtifactUpdateCandidates): FilterResult =
     isAllowedPreReleases(update)
@@ -73,31 +69,28 @@ final case class UpdatesConfig(
     else Left(NotAllowedByConfig(update))
   }
 
-  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)))
-    else if (allowOrDefault.isEmpty)
-      Right(update)
-    else Left(NotAllowedByConfig(update))
-  }
+  private def isAllowed(update: ArtifactUpdateCandidates): FilterResult =
+    if (allowOrDefault.isEmpty) Right(update)
+    else {
+      val m = UpdatePattern.findMatch(allowOrDefault, update, include = true)
+      update.filterVersions(m.filteredVersions.contains).toRight(NotAllowedByConfig(update))
+    }
 
   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)))
-    else if (m.byArtifactId.isEmpty)
-      Right(update)
-    else Left(VersionPinnedByConfig(update))
+    if (m.byArtifactId.isEmpty) Right(update)
+    else update.filterVersions(m.filteredVersions.contains).toRight(VersionPinnedByConfig(update))
   }
 
   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)))
-    else
-      Left(IgnoredByConfig(update))
+    update.filterVersions(m.filteredVersions.contains).toRight(IgnoredByConfig(update))
   }
+
+  private def isTooRecent(update: ArtifactUpdateCandidates, currentTime: Timestamp): FilterResult =
+    cooldown
+      .map(_.filterForAge(update, currentTime).toRight(TooRecentForCooldown(update)))
+      .getOrElse(Right(update))
 }
 
 object UpdatesConfig {
@@ -138,7 +131,8 @@ object UpdatesConfig {
           ignore = mergeIgnore(x.ignore, y.ignore),
           retracted = x.retracted |+| y.retracted,
           limit = x.limit.orElse(y.limit),
-          fileExtensions = mergeFileExtensions(x.fileExtensions, y.fileExtensions)
+          fileExtensions = mergeFileExtensions(x.fileExtensions, y.fileExtensions),
+          cooldown = mergeCooldown(x.cooldown, y.cooldown)
         )
     )
 
@@ -232,5 +226,10 @@ object UpdatesConfig {
   ): Option[List[String]] =
     combineOptions(x, y)(_.intersect(_))
 
+  private[repoconfig] def mergeCooldown(
+      x: Option[CooldownConfig],
+      y: Option[CooldownConfig]
+  ): Option[CooldownConfig] = (y ++ x).headOption // for now, simply let local override global
+
   intellijThisImportIsUsed(refinedDecoder: Decoder[NonNegInt])
 }