Build a "cannot process this many items" count-cap message

When a unit of work (a repository, a codebook file, a survey) has more items than a count cap allows, the whole unit is skipped rather than truncated. Returns NULL when within the cap.

Usage

cap_gate_count(
  n_needed,
  param,
  current,
  unit = "item",
  context = NULL,
  action = "process"
)

Arguments

n_needed: the number of items the unit actually has
param: the name of the parameter that caps this (e.g. "codebook_max_calls")
current: the current value of that parameter
unit: a noun for one item (e.g. "tabular data file")
context: a label for the unit of work skipped (e.g. the repo URL)
action: the verb for what was skipped (e.g. "extract", "analyse")

Value

a single string, or NULL when n_needed <= current

Details

Note this is a COUNT cap, and skipping is the right response because the items are not independently useful — half a codebook's LLM chunks describe half its variables. Download SIZE limits behave differently: they fill to the budget smallest-file-first and report what was omitted (see download_repo_files()).

Examples

cap_gate_count(12, "codebook_max_calls", 10, unit = "codebook",
               context = "https://osf.io/abcde", action = "parse")
#> [1] "12 codebooks for https://osf.io/abcde exceed the `codebook_max_calls` cap of 10. Set `codebook_max_calls >= 12` to parse them; https://osf.io/abcde was skipped."
# within the cap: NULL
cap_gate_count(5, "codebook_max_calls", 10)
#> NULL