From 8dd7e5a44ab9c0b27a7dccbdad8d8935fc69df59 Mon Sep 17 00:00:00 2001 From: Davis Vaughan Date: Tue, 20 Jan 2026 15:03:10 -0500 Subject: [PATCH 1/2] `use_claude_code()` --- .Rbuildignore | 1 + .claude/.gitignore | 1 + .claude/CLAUDE.md | 82 ++++++ .claude/settings.json | 31 +++ .../skills/tidy-argument-checking/SKILL.md | 250 ++++++++++++++++++ .../skills/tidy-deprecate-function/SKILL.md | 156 +++++++++++ 6 files changed, 521 insertions(+) create mode 100644 .claude/.gitignore create mode 100644 .claude/CLAUDE.md create mode 100644 .claude/settings.json create mode 100644 .claude/skills/tidy-argument-checking/SKILL.md create mode 100644 .claude/skills/tidy-deprecate-function/SKILL.md diff --git a/.Rbuildignore b/.Rbuildignore index f9f3167d..5c2981ec 100644 --- a/.Rbuildignore +++ b/.Rbuildignore @@ -32,3 +32,4 @@ script.R ^\.cache$ ^docs$ ^pkgdown$ +^\.claude$ diff --git a/.claude/.gitignore b/.claude/.gitignore new file mode 100644 index 00000000..93c0f73f --- /dev/null +++ b/.claude/.gitignore @@ -0,0 +1 @@ +settings.local.json diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md new file mode 100644 index 00000000..5e261702 --- /dev/null +++ b/.claude/CLAUDE.md @@ -0,0 +1,82 @@ +## R package development + +### Key commands + +``` +# To run code +Rscript -e "devtools::load_all(); code" + +# To run all tests +Rscript -e "devtools::test()" + +# To run all tests for files starting with {name} +Rscript -e "devtools::test(filter = '^{name}')" + +# To run all tests for R/{name}.R +Rscript -e "devtools::test_active_file('R/{name}.R')" + +# To run a single test "blah" for R/{name}.R +Rscript -e "devtools::test_active_file('R/{name}.R', desc = 'blah')" + +# To redocument the package +Rscript -e "devtools::document()" + +# To check pkgdown documentation +Rscript -e "pkgdown::check_pkgdown()" + +# To check the package with R CMD check +Rscript -e "devtools::check()" + +# To format code +air format . +``` + +### Coding + +* Always run `air format .` after generating code +* Use the base pipe operator (`|>`) not the magrittr pipe (`%>%`) +* Don't use `_$x` or `_$[["x"]]` since this package must work on R 4.1. +* Use `\() ...` for single-line anonymous functions. For all other cases, use `function() {...}` + +### Testing + +- Tests for `R/{name}.R` go in `tests/testthat/test-{name}.R`. +- All new code should have an accompanying test. +- If there are existing tests, place new tests next to similar existing tests. +- Strive to keep your tests minimal with few comments. + +### Documentation + +- Every user-facing function should be exported and have roxygen2 documentation. +- Wrap roxygen comments at 80 characters. +- Internal functions should not have roxygen documentation. +- Whenever you add a new (non-internal) documentation topic, also add the topic to `_pkgdown.yml`. +- Always re-document the package after changing a roxygen2 comment. +- Use `pkgdown::check_pkgdown()` to check that all topics are included in the reference index. + +### `NEWS.md` + +- Every user-facing change should be given a bullet in `NEWS.md`. Do not add bullets for small documentation changes or internal refactorings. +- Each bullet should briefly describe the change to the end user and mention the related issue in parentheses. +- A bullet can consist of multiple sentences but should not contain any new lines (i.e. DO NOT line wrap). +- If the change is related to a function, put the name of the function early in the bullet. +- Order bullets alphabetically by function name. Put all bullets that don't mention function names at the beginning. + +### GitHub + +- If you use `gh` to retrieve information about an issue, always use `--comments` to read all the comments. + +### Writing + +- Use sentence case for headings. +- Use US English. + +### Proofreading + +If the user asks you to proofread a file, act as an expert proofreader and editor with a deep understanding of clear, engaging, and well-structured writing. + +Work paragraph by paragraph, always starting by making a TODO list that includes individual items for each top-level heading. + +Fix spelling, grammar, and other minor problems without asking the user. Label any unclear, confusing, or ambiguous sentences with a FIXME comment. + +Only report what you have changed. diff --git a/.claude/settings.json b/.claude/settings.json new file mode 100644 index 00000000..6aaf8495 --- /dev/null +++ b/.claude/settings.json @@ -0,0 +1,31 @@ +{ + "permissions": { + "$schema": "https://json.schemastore.org/claude-code-settings.json", + "defaultMode": "acceptEdits", + "allow": [ + "Bash(air:*)", + "Bash(cat:*)", + "Bash(find:*)", + "Bash(gh issue list:*)", + "Bash(gh issue view:*)", + "Bash(gh pr diff:*)", + "Bash(gh pr view:*)", + "Bash(git checkout:*)", + "Bash(git grep:*)", + "Bash(grep:*)", + "Bash(ls:*)", + "Bash(R:*)", + "Bash(rm:*)", + "Bash(Rscript:*)", + "Bash(sed:*)", + "Skill(*)", + "WebFetch(domain:cran.r-project.org)", + "WebFetch(domain:github.com)", + "WebFetch(domain:raw.githubusercontent.com)" + ], + "deny": [ + "Read(.Renviron)", + "Read(.env)" + ] + } +} diff --git a/.claude/skills/tidy-argument-checking/SKILL.md b/.claude/skills/tidy-argument-checking/SKILL.md new file mode 100644 index 00000000..ed46c19e --- /dev/null +++ b/.claude/skills/tidy-argument-checking/SKILL.md @@ -0,0 +1,250 @@ +--- +name: types-check +description: Validate function inputs in R using a standalone file of check_* functions. Use when writing exported R functions that need input validation, reviewing existing validation code, or when creating new input validation helpers. +--- + +# Input validation in R functions + +This skill describes tidyverse style for validating function inputs. It focuses on rlang's exported type checkers along with the standalone file of `check_*` functions. These functions are carefully designed to produce clear, actionable error messages: + +```r +check_string(123) +#> Error: `123` must be a single string, not the number 123. + +check_number_whole(3.14, min = 1, max = 10) +#> Error: `3.14` must be a whole number, not the number 3.14. +``` + +It assumes that the user has already run `usethis::use_standalone("r-lib/rlang", "types-check")`, and imports rlang in their package. If not, confirm with the user before continuing. + +## Function reference + +### Scalars (single values) + +Use scalar checkers when arguments parameterise the function (configuration flags, names, single counts), rather than represent vectors of user data. They all assert a single value. + +- `check_bool()`: Single TRUE/FALSE (use for flags/options) +- `check_string()`: Single string (allows empty `""` by default) +- `check_name()`: Single non-empty string (for variable names, symbols as strings) +- `check_number_whole()`: Single integer-like numeric value +- `check_number_decimal()`: Single numeric value (allows decimals) + +By default, scalar checkers do _not_ allow `NA` elements (`allow_na = FALSE`). Set `allow_na = TRUE` when missing values are allowed. + +With the number checkers you can use `min` and `max` arguments for range validation, and `allow_infinite` (default `TRUE` for decimals, `FALSE` for whole numbers). + +### Vectors + +- `check_logical()`: Logical vector of any length +- `check_character()`: Character vector of any length +- `check_data_frame()`: A data frame object + +By default, vector checkers allow `NA` elements (`allow_na = TRUE`). Set `allow_na = FALSE` when missing values are not allowed. + +### Optional values: `allow_null` + +Use `allow_null = TRUE` when `NULL` represents a valid "no value" state, similar to `Option` in Rust or `T | null` in TypeScript: + +```r +# NULL means "use default timeout" +check_number_decimal(timeout, allow_null = TRUE) +``` + +The tidyverse style guide recommends using `NULL` defaults instead of `missing()` defaults, so this pattern comes up often in practice. + +## Other helpers + +These functions are exported by rlang. + +- `arg_match()`: Validates enumerated choices. Use when an argument must be one of a known set of strings. + + ```r + # Validates and returns the matched value + my_plot <- function(color = c("red", "green", "blue")) { + color <- rlang::arg_match(color) + # ... + } + + my_plot("redd") + #> Error in `my_plot()`: + #> ! `color` must be one of "red", "green", or "blue", not "redd". + #> ℹ Did you mean "red"? + ``` + + Note that partial matching is an error, unlike `base::match.arg()`. + +- `check_exclusive()` ensures only one of two arguments can be supplied. Supplying both together (i.e. both of them are non-`NULL`) is an error. Use `.require = TRUE` if both can be omitted. + +- `check_required()`: Nice error message if required argument is not supplied. + +## `call` and `arg` arguments + +All check functions have `call` and `arg` arguments, but you should never use these unless you are creating your own `check_` function (see below for more details). + +## When to validate inputs + +**Validate at entry points, not everywhere.** + +Input validation should happen at the boundary between user code and your package's internal implementation: + +- **Exported functions**: Functions users call directly +- **Functions accepting user data**: Even internal functions if they directly consume user input, or external data (e.g. unserialised data) + +Once inputs are validated at these entry points, internal helper functions can trust the data they receive without checking again. + +A good analogy to keep in mind is gradual typing. Think of input validation like TypeScript type guards. Once you've validated data at the boundary, you can treat it as "typed" within your internal functions. Additional runtime checks are not needed. The entry point validates once, and all downstream code benefits. + +Exception: Validate when in doubt. Do validate in internal functions if: +- The cost of invalid data is high (data corruption, security issues) +- The function or context is complex and you want defensive checks + +Example of validating arguments of an exported function: + +```r +# Exported function: VALIDATE +#' @export +create_report <- function(title, n_rows) { + check_string(title) + check_number_whole(n_rows, min = 1) + + # Now call helpers with validated data + data <- generate_data(n_rows) + format_report(title, data) +} +``` + +Once data is validated at the entry point, internal helpers can skip validation: + +```r +# Internal helper: NO VALIDATION NEEDED +generate_data <- function(n_rows) { + # n_rows is already validated, just use it + data.frame( + id = seq_len(n_rows), + value = rnorm(n_rows) + ) +} + +# Internal helper: NO VALIDATION NEEDED +format_report <- function(title, data) { + # title and data are already validated, just use them + list( + title = title, + summary = summary(data), + rows = nrow(data) + ) +} +``` + +Note how the `data` generated by `generate_data()` doesn't need validation either. Internal code creating data in a trusted way (e.g. because it's simple or because it's covered by unit tests) doesn't require internal checks. + +## Early input checking + +Always validate inputs at the start of user-facing functions, before doing any work: + +```r +my_function <- function(x, name, env = caller_env()) { + check_logical(x) + check_name(name) + check_environment(env) + + # ... function body +} +``` + +Benefits: + +- This self-documents the types of the arguments +- Eager evaluation also reduces the risk of confusing lazy evaluation effects + +## Custom validation functions + +Most packages will need one or more unique checker functions. Sometimes it's sufficient to wrap existing check functions with custom arguments. In this case you just need to carefully pass through the `arg` and `call` arguments. In other cases, you want a completely new check in which case you can call `stop_input_type` with your own arguments. + +### Wrapping existing `check_` functions + +When creating a wrapper or helper function that calls `check_*` functions on behalf of another function, you **must** propagate the caller context. Otherwise, errors will point to your wrapper function instead of the actual entry point. + +Without proper propagation, error messages show the wrong function and argument names: + +```r +# WRONG: errors will point to check_positive's definition +check_positive <- function(x) { + check_number_whole(x, min = 1) +} + +my_function <- function(count) { + check_positive(count) +} + +my_function(-5) +#> Error in `check_positive()`: # Wrong! Should say `my_function()` +#> ! `x` must be a whole number larger than or equal to 1. # Wrong! Should say `count` +``` + +With proper propagation, errors correctly identify the entry point and argument: + +```r +# CORRECT: propagates context from the entry point +check_positive <- function(x, arg = caller_arg(x), call = caller_env()) { + check_number_whole(x, min = 1, arg = arg, call = call) +} + +my_function <- function(count) { + check_positive(count) +} + +my_function(-5) +#> Error in `my_function()`: # Correct! +#> ! `count` must be a whole number larger than or equal to 1. # Correct! +``` + +Note how `arg` and `call` are part of the function signature. That allows them to be wrapped again by another checking function that can pass down its own context. + +### Creating a new `check_` function + +When constructing your own `check_` function you can call `stop_input_type()` to take advantage of the existing infrastructure for generating error messages. +For example, imagine we wanted to create a function that checked that the input was a single date: + +```R +check_date <- function(x, ..., allow_null = FALSE, arg = caller_arg(x), call = caller_env()) { + if (!missing(x) && is.Date(x) && length(x) == 1) { + return(invisible()) + } + + stop_input_type( + x, + "a single Date", + ..., + allow_null = allow_null, + arg = arg, + call = call + ) +} +``` + +Note you must always check first that the input is not missing, as `stop_input_type()` handles this case specially. + +Sometimes you want to check if something is a compound type: + +```R +check_string_or_bool <- function(x, ..., arg = caller_arg(x), call = caller_env()) { + if (!missing(x)) { + if (is_string(x) || isTRUE(x) || isFALSE(x)) { + return(invisible()) + } + } + + stop_input_type( + x, + c("a string", "TRUE", "FALSE"), + ..., + arg = arg, + call = call + ) +} +``` + +Note that the second argument to `stop_input_type()` can take a vector, and it will automatically places commas and "and" in the appropriate locations. + +Generally, you should place this `check_` function close to the function that is usually used to construct the object being checked (e.g. close to the S3/S4/S7 constructor.) diff --git a/.claude/skills/tidy-deprecate-function/SKILL.md b/.claude/skills/tidy-deprecate-function/SKILL.md new file mode 100644 index 00000000..b2dfeb30 --- /dev/null +++ b/.claude/skills/tidy-deprecate-function/SKILL.md @@ -0,0 +1,156 @@ +--- +name: tidy-deprecate-function +description: Guide for deprecating R functions/arguments. Use when a user asks to deprecate a function or parameter, including adding lifecycle warnings, updating documentation, adding NEWS entries, and updating tests. +--- + +# Deprecate functions and function arguments + +Use this skill when deprecating functions or function parameters in this package. + +## Overview + +This skill guides you through the complete process of deprecating a function or parameter, ensuring all necessary changes are made consistently: + +1. Add deprecation warning using `lifecycle::deprecate_warn()`. +2. Silence deprecation warnings in existing tests. +3. Add lifecycle badge to documentation. +4. Add bullet point to NEWS.md. +5. Create test for deprecation warning. + +## Workflow + +### Step 1: Determine deprecation version + +Read the current version from DESCRIPTION and calculate the deprecation version: + +- Current version format: `MAJOR.MINOR.PATCH.9000` (development). +- Deprecation version: Next minor release `MAJOR.(MINOR+1).0`. +- Example: If current version is `2.5.1.9000`, deprecation version is `2.6.0`. + +### Step 2: Add `lifecycle::deprecate_warn()` call + +Add the deprecation warning to the function: + +```r +# For a deprecated function: +function_name <- function(...) { + lifecycle::deprecate_warn("X.Y.0", "function_name()", "replacement_function()") + # rest of function +} + +# For a deprecated parameter: +function_name <- function(param1, deprecated_param = deprecated()) { + if (lifecycle::is_present(deprecated_param)) { + lifecycle::deprecate_warn("X.Y.0", "function_name(deprecated_param)") + } + # rest of function +} +``` + +Key points: + +- First argument is the deprecation version string (e.g., "2.6.0"). +- Second argument describes what is deprecated (e.g., "function_name(param)"). +- Optional third argument suggests replacement. +- Use `lifecycle::is_present()` to check if a deprecated parameter was supplied. + +### Step 3: Update tests + +Find all existing tests that use the deprecated function or parameter and silence lifecycle warnings. Add at the beginning of test blocks that use the deprecated feature: + +```r +test_that("existing test with deprecated feature", { + withr::local_options(lifecycle_verbosity = "quiet") + + # existing test code +}) +``` + +Then add a new test to verify the deprecation message in the appropriate test file (usually `tests/testthat/test-{name}.R`): + +```r +test_that("function_name(deprecated_param) is deprecated", { + expect_snapshot(. <- function_name(deprecated_param = value)) +}) +``` + +You'll need to supply any additional arguments to create a valid call. + +Then run the tests and verify they pass. + +### Step 4: Update documentation + +For function deprecation, add to the description section: + +```r +#' @description +#' `r lifecycle::badge("deprecated")` +#' +#' This function is deprecated. Please use [replacement_function()] instead. +``` + +If the documentation does not already contain `@description`, you will need to add it. + +For argument deprecation, add to the appropriate `@param` tag: + +```r +#' @param deprecated_param `r lifecycle::badge("deprecated")` +``` + +When deprecating a function or parameter in favor of a replacement, add old/new examples to the `@examples` section to help users migrate. These should relace all existing examples. + +```r +#' @examples +#' # Old: +#' old_function(arg1, arg2) +#' # New: +#' replacement_function(arg1, arg2) +#' +#' # Old: +#' x <- "value" +#' old_function("prefix", x, "suffix") +#' # New: +#' replacement_function("prefix {x} suffix") +``` + +Key points: + +- Use "# Old:" and "# New:" comments to clearly show the transition. +- Include 2-3 practical examples covering common use cases. +- Make examples runnable and self-contained. +- Show how the new syntax differs from the old. + +Then re-document the package. + +### Step 5: Add NEWS entry + +Add a bullet point to the top of the "# packagename (development version)" section in NEWS.md: + +```markdown +# packagename (development version) + +* `function_name(parameter)` is deprecated and will be removed in a future + version. +* `function_name()` is deprecated. Use `replacement_function()` instead. +``` + +Place the entry: + +- In the lifecycle subsection if it exists, otherwise at the top level under development version. +- Include the replacement if known. +- Keep entries concise and actionable. + +## Implementation checklist + +When deprecating a function or parameter, ensure you: + +- [ ] Read DESCRIPTION to determine deprecation version. +- [ ] Add `lifecycle::deprecate_warn()` call in the function. +- [ ] Add `withr::local_options(lifecycle_verbosity = "quiet")` to existing tests. +- [ ] Create new test for deprecation warning using `expect_snapshot()`. +- [ ] Run tests to verify everything works. +- [ ] Add lifecycle badge to roxygen documentation. +- [ ] Add migration examples to `@examples` section (for function deprecation). +- [ ] Run `devtools::document()` to update documentation. +- [ ] Add bullet point to NEWS.md. +- [ ] Run `air format .` to format code. From 0b3b78ff126dc993cb66639874b2cc5066fdcbe3 Mon Sep 17 00:00:00 2001 From: Davis Vaughan Date: Wed, 21 Jan 2026 09:47:54 -0500 Subject: [PATCH 2/2] cpp11 specific tweaks --- .claude/CLAUDE.md | 23 ++++++++++++++++------- 1 file changed, 16 insertions(+), 7 deletions(-) diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index 5e261702..b3c151f9 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -6,8 +6,17 @@ # To run code Rscript -e "devtools::load_all(); code" -# To run all tests -Rscript -e "devtools::test()" +# To run R specific tests +Rscript -e " + devtools::test() +" + +# To run C++ specific tests +Rscript -e " + devtools::install() + devtools::clean_dll('./cpp11test') + devtools::test('./cpp11test') +" # To run all tests for files starting with {name} Rscript -e "devtools::test(filter = '^{name}')" @@ -36,11 +45,11 @@ air format . * Always run `air format .` after generating code * Use the base pipe operator (`|>`) not the magrittr pipe (`%>%`) * Don't use `_$x` or `_$[["x"]]` since this package must work on R 4.1. -* Use `\() ...` for single-line anonymous functions. For all other cases, use `function() {...}` +* Use `\() ...` for single-line anonymous functions. For all other cases, use `function() {...}` ### Testing -- Tests for `R/{name}.R` go in `tests/testthat/test-{name}.R`. +- Tests for `R/{name}.R` go in `tests/testthat/test-{name}.R`. - All new code should have an accompanying test. - If there are existing tests, place new tests next to similar existing tests. - Strive to keep your tests minimal with few comments. @@ -50,7 +59,7 @@ air format . - Every user-facing function should be exported and have roxygen2 documentation. - Wrap roxygen comments at 80 characters. - Internal functions should not have roxygen documentation. -- Whenever you add a new (non-internal) documentation topic, also add the topic to `_pkgdown.yml`. +- Whenever you add a new (non-internal) documentation topic, also add the topic to `_pkgdown.yml`. - Always re-document the package after changing a roxygen2 comment. - Use `pkgdown::check_pkgdown()` to check that all topics are included in the reference index. @@ -73,9 +82,9 @@ air format . ### Proofreading -If the user asks you to proofread a file, act as an expert proofreader and editor with a deep understanding of clear, engaging, and well-structured writing. +If the user asks you to proofread a file, act as an expert proofreader and editor with a deep understanding of clear, engaging, and well-structured writing. -Work paragraph by paragraph, always starting by making a TODO list that includes individual items for each top-level heading. +Work paragraph by paragraph, always starting by making a TODO list that includes individual items for each top-level heading. Fix spelling, grammar, and other minor problems without asking the user. Label any unclear, confusing, or ambiguous sentences with a FIXME comment.