fix: prevent use_standalone() from downgrading version constraints

NEWS.md

@@ -1,5 +1,6 @@
 # usethis (development version)
 
+* `use_package()` gains a `downgrade` argument. When set to `FALSE`, a `min_version` lower than the currently recorded version is silently ignored rather than being written to `DESCRIPTION`. `use_standalone()` now passes `downgrade = FALSE` when recording its `imports:` dependencies, preventing a standalone file from inadvertently lowering a version constraint the package author has intentionally set higher.
 * `create_from_github()` now installs package dependencies by default, so you're set up to immediately start working on the package. Use `install_dependencies = FALSE` to suppress (#2186).
 * `learn_tidy_skill()` is an experimental new function that prints instructions for performing a specialized R package development task (like deprecating a function) the way the tidyverse team does. It's primarily designed to be called by AI coding agents, as directed by the `AGENTS.md` created by `use_tidy_agents()`.
 * `pr_init()` and other functions that check for uncommitted changes now offer a menu with four options: stash changes (and re-apply after), cancel, retry, or proceed anyway. Previously, the only options were to proceed or cancel (#1300).

R/helpers.R

@@ -1,6 +1,12 @@
-use_dependency <- function(package, type, min_version = NULL) {
+use_dependency <- function(
+  package,
+  type,
+  min_version = NULL,
+  downgrade = TRUE
+) {
   check_name(package)
   check_name(type)
+  check_bool(downgrade)
 
   if (package != "R") {
     check_installed(package)
@@ -70,18 +76,27 @@ use_dependency <- function(package, type, min_version = NULL) {
     delta == 0 && version_spec(version) != version_spec(existing_version)
   ) {
     if (version_spec(version) > version_spec(existing_version)) {
-      direction <- "Increasing"
+      ui_bullets(c(
+        "v" = "Increasing {.pkg {package}} version to {.val {version}} in
+               DESCRIPTION."
+      ))
+      desc$set_dep(package, type, version = version)
+      desc$write()
+      changed <- TRUE
+    } else if (downgrade) {
+      ui_bullets(c(
+        "v" = "Decreasing {.pkg {package}} version to {.val {version}} in
+               DESCRIPTION."
+      ))
+      desc$set_dep(package, type, version = version)
+      desc$write()
+      changed <- TRUE
     } else {
-      direction <- "Decreasing"
+      ui_bullets(c(
+        "!" = "Package {.pkg {package}} is already listed with version
+               {.val {existing_version}} in DESCRIPTION; no change made."
+      ))
     }
-
-    ui_bullets(c(
-      "v" = "{direction} {.pkg {package}} version to {.val {version}} in
-             DESCRIPTION."
-    ))
-    desc$set_dep(package, type, version = version)
-    desc$write()
-    changed <- TRUE
   } else if (delta > 0) {
     # moving from, e.g., Suggests to Imports
     ui_bullets(c(

R/package.R

@@ -25,6 +25,9 @@
 #' @param min_version Optionally, supply a minimum version for the package. Set
 #'   to `TRUE` to use the currently installed version or use a version string
 #'   suitable for [numeric_version()], such as "2.5.0".
+#' @param downgrade If `FALSE`, a minimum version that is lower than the
+#'   currently recorded version will be silently ignored. The default (`TRUE`)
+#'   preserves the historical behaviour of allowing the version to be lowered.
 #' @param remote By default, an `OWNER/REPO` GitHub remote is inserted.
 #'   Optionally, you can supply a character string to specify the remote, e.g.
 #'   `"gitlab::jimhester/covr"`, using any syntax supported by the [remotes
@@ -44,12 +47,23 @@
 #' # Depend on R version 4.1
 #' use_package("R", type = "Depends", min_version = "4.1")
 #' }
-use_package <- function(package, type = "Imports", min_version = NULL) {
+use_package <- function(
+  package,
+  type = "Imports",
+  min_version = NULL,
+  downgrade = TRUE
+) {
   if (type == "Imports") {
     refuse_package(package, verboten = c("tidyverse", "tidymodels"))
   }
+  check_bool(downgrade)
 
-  changed <- use_dependency(package, type, min_version = min_version)
+  changed <- use_dependency(
+    package,
+    type,
+    min_version = min_version,
+    downgrade = downgrade
+  )
   if (changed) {
     how_to_use(package, type)
   }

R/use_standalone.R

@@ -94,7 +94,7 @@ use_standalone <- function(repo_spec, file = NULL, ref = NULL, host = NULL) {
       ver <- import$ver
     }
     ui_silence(
-      use_package(import$pkg, min_version = ver)
+      use_package(import$pkg, min_version = ver, downgrade = FALSE)
     )
   }
 

tests/testthat/_snaps/helpers.md

@@ -62,6 +62,14 @@
       ! Package usethis is already listed in 'Imports' in DESCRIPTION; no change
         made.
 
+# use_dependency() respects downgrade = FALSE
+
+    Code
+      use_dependency("crayon", "Imports", min_version = "1.0.0", downgrade = FALSE)
+    Message
+      ! Package crayon is already listed with version ">= 2.0.0" in DESCRIPTION; no
+        change made.
+
 # can add LinkingTo dependency if other dependency already exists
 
     Code

tests/testthat/test-helpers.R

@@ -83,6 +83,22 @@ test_that("use_dependency() declines to downgrade a dependency", {
   expect_no_match(desc::desc_get("Suggests"), "usethis")
 })
 
+test_that("use_dependency() respects downgrade = FALSE", {
+  create_local_package()
+  withr::local_options(usethis.quiet = FALSE)
+
+  use_dependency("crayon", "Imports", min_version = "2.0.0")
+  expect_snapshot(
+    use_dependency(
+      "crayon",
+      "Imports",
+      min_version = "1.0.0",
+      downgrade = FALSE
+    )
+  )
+  expect_match(desc::desc_get("Imports"), ">= 2.0.0")
+})
+
 test_that("can add LinkingTo dependency if other dependency already exists", {
   create_local_package()
   use_dependency("rlang", "Imports")