fix: align deprecation warnings with transition policy

NEWS.md

@@ -36,8 +36,9 @@
 - Added focused readers and computational names including `fetch_cases()`,
   `fetch_case_records()`, `fetch_climate()`, `estimate_rt()`,
   `nowcast_cases()`, `define_alert_rules()`, and `classify_alerts()`.
-- Legacy counterparts remain available as thin wrappers and emit staged
-  deprecation warnings through `lifecycle`.
+- Legacy counterparts remain available as thin wrappers. Per the approved
+  transition policy, `lifecycle` deprecation warnings begin in version 1.3.0;
+  version 1.2.0 does not warn ahead of that transition.
 - Added `upsert_alert_parameters()` for transactional parameter batches and a
   migration table documenting functions, arguments, schemas, and intentional
   differences.

R/api.R

@@ -468,7 +468,13 @@ classify_alerts <- function(data, rules, missing = FALSE, minimum_history = 8) {
 # Legacy wrappers ------------------------------------------------------------
 
 .deprecate_api <- function(old, replacement) {
-  lifecycle::deprecate_warn("1.1.0", old, replacement, user_env = parent.frame(2L))
+  warning_start <- package_version("1.3.0")
+  package_version <- utils::packageVersion("AlertTools")
+  if (package_version >= warning_start) {
+    lifecycle::deprecate_warn("1.3.0", old, replacement,
+                              user_env = parent.frame(2L))
+  }
+  invisible(NULL)
 }
 
 #' Legacy Rt estimator
@@ -494,9 +500,13 @@ adjustIncidence <- function(obj, datas = NULL, method = "none",
 }
 
 #' Legacy alert-rule constructor
-#' @param rule,values,delays Legacy arguments.
+#' @param rule,values Legacy arguments.
+#' @param delays Legacy list with turn-on and turn-off delays for yellow, orange,
+#'   and red criteria.
 #' @export
-setCriteria <- function(rule = NULL, values = NULL, delays = 3) {
+setCriteria <- function(rule = NULL, values = NULL,
+                        delays = list(delayy = c(0, 0), delayo = c(0, 0),
+                                      delayr = c(0, 0))) {
   .deprecate_api("setCriteria()", "define_alert_rules()")
   .define_alert_rules_impl(rule, values, delays)
 }

docs/refactoring/api-migration.md

@@ -1,6 +1,8 @@
 # Migração para a API `snake_case`
 
-Versão de início da depreciação: 1.1.0.
+Versão de início dos avisos formais de depreciação: 1.3.0, conforme
+`transition-policy.dcf`. Na versão 1.2.0, os wrappers continuam disponíveis sem
+antecipar esses avisos.
 
 A API nova separa leitura, cálculo e persistência. Funções experimentais estão
 identificadas na ajuda do pacote e podem receber ajustes compatíveis antes de
@@ -26,18 +28,18 @@ suporte ainda está proposta; nenhuma data de remoção foi aprovada.
 
 | API legada | API nova | Adaptação principal | Situação |
 |---|---|---|---|
-| `getCases()` | `fetch_cases()` | `datasource` → `conn`; `cities` → `geocodes`; `cid10` → `disease`; `firstday`/`lastday` → `start_date`/`end_date`; `dataini` → `case_date` | wrapper depreciado desde 1.1.0 |
-| `getCaseslist()` | `fetch_case_records()` | mesmos argumentos de conexão, local, doença e datas | wrapper depreciado desde 1.1.0 |
-| `getClima()` | `fetch_climate()` | `vars` → `climate_vars`; datas explícitas | wrapper depreciado desde 1.1.0 |
-| `read.parameters()` | `fetch_alert_parameters()` | `datasource` → `conn`; `cities` → `geocodes`; nomes de doenças aceitos | wrapper depreciado desde 1.1.0 |
-| `pipe_infodengue()` | `fetch_alert_inputs()` + `run_alert_pipeline()` | leitura e cálculo passam a ser chamadas separadas; escrita removida do cálculo | wrapper depreciado desde 1.1.0 |
-| `Rt()` | `estimate_rt()` | argumentos longos em `snake_case` | wrapper depreciado desde 1.1.0 |
-| `adjustIncidence()` | `nowcast_cases()` | `datas` → `case_records`; `nowSE` → `report_week` | wrapper depreciado desde 1.1.0 |
-| `setCriteria()` | `define_alert_rules()` | `delays` preservado | wrapper depreciado desde 1.1.0 |
-| `fouralert()` | `classify_alerts()` | `crit` → `rules`; `miss` → `missing`; `dy` → `minimum_history` | wrapper depreciado desde 1.1.0 |
-| `tabela_historico()` | `as_alert_history()` | `versao` → `version_date`; `iniSE`/`lastSE` → `start_week`/`end_week` | wrapper depreciado desde 1.1.0 |
-| `write_alerta()` | `write_alert_results()` | recebe diretamente `alerttools_result`; não exporta arquivo implicitamente | wrapper depreciado desde 1.1.0 |
-| `write_parameters()` | `upsert_alert_parameters()` | aceita lote; `overwrite` é substituído por `conflict` | wrapper depreciado desde 1.1.0 |
+| `getCases()` | `fetch_cases()` | `datasource` → `conn`; `cities` → `geocodes`; `cid10` → `disease`; `firstday`/`lastday` → `start_date`/`end_date`; `dataini` → `case_date` | aviso a partir de 1.3.0 |
+| `getCaseslist()` | `fetch_case_records()` | mesmos argumentos de conexão, local, doença e datas | aviso a partir de 1.3.0 |
+| `getClima()` | `fetch_climate()` | `vars` → `climate_vars`; datas explícitas | aviso a partir de 1.3.0 |
+| `read.parameters()` | `fetch_alert_parameters()` | `datasource` → `conn`; `cities` → `geocodes`; nomes de doenças aceitos | aviso a partir de 1.3.0 |
+| `pipe_infodengue()` | `fetch_alert_inputs()` + `run_alert_pipeline()` | leitura e cálculo passam a ser chamadas separadas; escrita removida do cálculo | aviso a partir de 1.3.0 |
+| `Rt()` | `estimate_rt()` | argumentos longos em `snake_case` | aviso a partir de 1.3.0 |
+| `adjustIncidence()` | `nowcast_cases()` | `datas` → `case_records`; `nowSE` → `report_week` | aviso a partir de 1.3.0 |
+| `setCriteria()` | `define_alert_rules()` | `delays` preservado | aviso a partir de 1.3.0 |
+| `fouralert()` | `classify_alerts()` | `crit` → `rules`; `miss` → `missing`; `dy` → `minimum_history` | aviso a partir de 1.3.0 |
+| `tabela_historico()` | `as_alert_history()` | `versao` → `version_date`; `iniSE`/`lastSE` → `start_week`/`end_week` | aviso a partir de 1.3.0 |
+| `write_alerta()` | `write_alert_results()` | recebe diretamente `alerttools_result`; não exporta arquivo implicitamente | aviso a partir de 1.3.0 |
+| `write_parameters()` | `upsert_alert_parameters()` | aceita lote; `overwrite` é substituído por `conflict` | aviso a partir de 1.3.0 |
 
 As demais funções legadas permanecem estáveis nesta fase porque não são
 necessárias ao fluxo mínimo comprovado. Novos nomes somente serão adicionados

tests/testthat/test-alert-rules.R

@@ -15,6 +15,17 @@ test_that("setCriteria validates inputs and returns the legacy structure", {
   expect_equal(lengths(criteria), c(crity = 3L, crito = 3L, critr = 3L))
 })
 
+test_that("setCriteria keeps its legacy delay-list default", {
+  expected_delays <- list(
+    delayy = c(0, 0),
+    delayo = c(0, 0),
+    delayr = c(0, 0)
+  )
+
+  expect_identical(eval(formals(setCriteria)$delays), expected_delays)
+  expect_identical(formals(define_alert_rules)$delays, 3)
+})
+
 test_that("alert rules preserve output structure and delayed levels", {
   withr::local_options(list(lifecycle_verbosity = "quiet"))
   cases <- read_fixture("cases.csv")

tests/testthat/test-api.R

@@ -86,50 +86,46 @@ test_that("new persistence API writes results and parameters explicitly", {
 
   withr::local_options(list(lifecycle_verbosity = "warning"))
   history <- as_alert_history(result, as.Date("2026-09-04"))
-  expect_warning(
-    write_alerta(history, datasource = connection, conflict = "update"),
-    "write_alert_results"
+  expect_no_warning(
+    write_alerta(history, datasource = connection, conflict = "update")
   )
 
   changed <- transform(parameter_fixture(), limiar_preseason = 23)
   persisted <- upsert_alert_parameters(connection, changed, conflict = "update")
   expect_equal(persisted$limiar_preseason, 23)
 })
 
-test_that("legacy wrappers warn and preserve argument and result adapters", {
+test_that("legacy wrappers preserve adapters without warning before 1.3.0", {
   withr::local_options(list(lifecycle_verbosity = "warning"))
   connection <- sqlite_fixture_connection(environment())
 
   modern_cases <- fetch_cases(
     connection, 3304557, "dengue",
     as.Date("2020-12-20"), as.Date("2021-01-09")
   )
-  expect_warning(
+  expect_no_warning(
     legacy_cases <- getCases(
       cities = 3304557, cid10 = "A90", firstday = as.Date("2020-12-20"),
       lastday = as.Date("2021-01-09"), dataini = "notific", datasource = connection
-    ),
-    "fetch_cases"
+    )
   )
   expect_identical(legacy_cases, modern_cases)
-  expect_warning(
+  expect_no_warning(
     legacy_records <- getCaseslist(
       3304557, firstday = as.Date("2020-12-20"),
       lastday = as.Date("2021-01-09"), datasource = connection
-    ),
-    "fetch_case_records"
+    )
   )
   expect_identical(
     legacy_records,
     fetch_case_records(connection, 3304557, start_date = as.Date("2020-12-20"),
                        end_date = as.Date("2021-01-09"))
   )
-  expect_warning(
+  expect_no_warning(
     legacy_climate <- getClima(
       3304557, vars = c("temp_min", "temp_max"), iniSE = 202052,
       finalday = as.Date("2021-01-02"), datasource = connection
-    ),
-    "fetch_climate"
+    )
   )
   expect_identical(
     legacy_climate,
@@ -138,22 +134,19 @@ test_that("legacy wrappers warn and preserve argument and result adapters", {
   )
 
   modern_parameters <- fetch_alert_parameters(connection, 3304557, "dengue")
-  expect_warning(
-    legacy_parameters <- read.parameters(3304557, cid10 = "A90", datasource = connection),
-    "fetch_alert_parameters"
+  expect_no_warning(
+    legacy_parameters <- read.parameters(3304557, cid10 = "A90", datasource = connection)
   )
   expect_identical(legacy_parameters, modern_parameters)
-  expect_warning(
+  expect_no_warning(
     write_parameters(3304557, "A90", modern_parameters, overwrite = TRUE,
-                     datasource = connection),
-    "upsert_alert_parameters"
+                     datasource = connection)
   )
-  expect_warning(
-    expect_error(
-      pipe_infodengue(3304557, datarelatorio = 202101, datasource = NULL),
-      "valid DBI connection"
+  expect_error(
+    expect_no_warning(
+      pipe_infodengue(3304557, datarelatorio = 202101, datasource = NULL)
     ),
-    "run_alert_pipeline"
+    "valid DBI connection"
   )
 })
 
@@ -208,30 +201,28 @@ test_that("snake_case computational aliases preserve baseline results", {
   expect_identical(rules, setCriteria("Af", criteria_values))
 })
 
-test_that("legacy computational wrappers identify replacements and remain equivalent", {
+test_that("legacy computational wrappers remain equivalent without early warnings", {
   withr::local_options(list(lifecycle_verbosity = "warning"))
   cases <- read_fixture("cases.csv")
   climate <- read_fixture("climate.csv")
   parameters <- read_fixture("parameters.csv", stringsAsFactors = FALSE)
 
   modern_rt <- estimate_rt(cases, count = "casos", distribution = "normal",
                            mean_generation_time = 3, sd_generation_time = 1)
-  expect_warning(
-    legacy_rt <- Rt(cases, count = "casos", gtdist = "normal", meangt = 3, sdgt = 1),
-    "estimate_rt"
+  expect_no_warning(
+    legacy_rt <- Rt(cases, count = "casos", gtdist = "normal", meangt = 3, sdgt = 1)
   )
   expect_identical(legacy_rt, modern_rt)
 
   modern_nowcast <- nowcast_cases(cases, method = "none", report_week = 202106)
-  expect_warning(
-    legacy_nowcast <- adjustIncidence(cases, method = "none", nowSE = 202106),
-    "nowcast_cases"
+  expect_no_warning(
+    legacy_nowcast <- adjustIncidence(cases, method = "none", nowSE = 202106)
   )
   expect_identical(legacy_nowcast, modern_nowcast)
 
   values <- structure(as.character(parameters[1, ]), names = names(parameters))
   modern_rules <- define_alert_rules("Af", values)
-  expect_warning(legacy_rules <- setCriteria("Af", values), "define_alert_rules")
+  expect_no_warning(legacy_rules <- setCriteria("Af", values))
   expect_identical(legacy_rules, modern_rules)
 
   result <- run_alert_pipeline(
@@ -240,15 +231,13 @@ test_that("legacy computational wrappers identify replacements and remain equiva
   )
   modern_alert <- classify_alerts(result$data, modern_rules,
                                    missing = "last", minimum_history = 4)
-  expect_warning(
-    legacy_alert <- fouralert(result$data, modern_rules, miss = "last", dy = 4),
-    "classify_alerts"
+  expect_no_warning(
+    legacy_alert <- fouralert(result$data, modern_rules, miss = "last", dy = 4)
   )
   expect_identical(legacy_alert, modern_alert)
   modern_history <- as_alert_history(result, as.Date("2026-09-04"))
-  expect_warning(
-    legacy_history <- tabela_historico(result, versao = as.Date("2026-09-04")),
-    "as_alert_history"
+  expect_no_warning(
+    legacy_history <- tabela_historico(result, versao = as.Date("2026-09-04"))
   )
   expect_identical(legacy_history, modern_history)
 })