Diagnostic codes
unresolved
! I could not resolve `validte_url` in this package, its imports, or builtins. Did you mean `validate_url`? --[R/a.R:2:22] 1 | validate_url <- function(x) TRUE 2 | check <- function(x) validte_url(x) | ^^^^^^^^^^^Every finding starts with its code, here unresolved. The code stays the same when the wording of
a message changes, so it is what you name in a suppression, in ry.toml, and in the JSON output.
! marks a warning and x an error (⚠ and × in a terminal). The carets underline exactly
what the finding is about, such as one name, not the whole statement.
Suppressing a finding
Section titled “Suppressing a finding”total = 1L # ry: allow(assignment-operator)
# ry: allow(unused, naming-style)scratchValue <- 1LA suppression covers its own line and the line below, so it works at the end of a line or on the line
above. allow(all) covers every code. There is no block or file scope, because a suppression marks
one exception you have reviewed and should not hide findings in code written later. To turn a code
off everywhere, use ry.toml, and to turn type checking off for one
file, put # typing: off in it.
The marker is found by scanning the line for its first #, so #ry:allow(x) and
# roughly: allow(x) work too, but a # inside a string earlier on the line hides it. Findings on
NAMESPACE, ry.toml, and stub files cannot be suppressed, because they have no R line to carry the
comment.
Some R idioms silence findings on their own:
utils::globalVariables(c("a", "b"))at the top level stopsaandbfrom being reported as unresolved, as it does forR CMD check.- In a file that calls
R6Class(),self,private, andsuperresolve. - A name created with
<<-anywhere in a file resolves in that file. - A name that starts with
.or_is never reported as unused.
Some findings carry a mechanical fix, which the editor offers as a quick fix and ry check --fix
applies. A fix is safe when it keeps what the code means, so --fix, the editor’s fix shortcut
and its “Apply all safe fixes” action apply it without asking. A fix is unsafe when it guesses
what you meant or silences a finding without handling it, so it needs --unsafe-fixes or a click.
| Code | Fix | Applicability |
|---|---|---|
assignment-operator |
= to <- |
safe |
boolean-shorthand |
T to TRUE, F to FALSE |
safe |
trailing-comma |
remove the comma | safe |
redundant-return |
return(x) to x |
safe |
any-is-na |
any(is.na(x)) to anyNA(x) |
safe |
paste-sep |
paste(..., sep = "") to paste0(...), when no comment sits inside the call |
safe |
literal-coercion |
as.integer(1) to 1L, and the like for other literals |
safe |
single-quotes |
'text' to "text", when the text holds no " or \' |
safe |
comparison-negation |
!(x == y) to x != y, and the like for other comparisons |
safe |
outer-negation |
all(!x) to !any(x), any(!x) to !all(x) |
safe |
which-grepl |
which(grepl(...)) to grep(...) |
safe |
length-levels |
length(levels(x)) to nlevels(x) |
safe |
numeric-leading-zero |
.5 to 0.5 |
safe |
while-true |
while (TRUE) to repeat, when no comment sits in the header |
safe |
empty-assignment |
x <- {} to x <- NULL |
safe |
unnecessary-concatenation |
c("a") to "a", c() to NULL, when no comment sits inside the call |
safe |
testthat-expectation |
expect_equal(x, NULL) and expect_true(is.null(x)) to expect_null(x) |
safe |
testthat-expectation |
expect_equal(x, TRUE) to expect_true(x), expect_true(!x) to expect_false(x), expect_equal(length(x), n) to expect_length(x, n), expect_equal(names(x), n) to expect_named(x, n), expect_true(inherits(x, "a")) to expect_s3_class(x, "a") |
unsafe |
condition-message |
stop(paste0(a, b)) to stop(a, b) |
unsafe |
fixed-regex |
add fixed = TRUE |
unsafe |
lengths |
sapply(x, length) to lengths(x) |
unsafe |
redundant-equals |
x == TRUE to x, x == FALSE to !x |
unsafe |
equals-na |
x == NA to is.na(x), x != NA to !is.na(x) |
unsafe |
vector-logic |
& to &&, ` |
to |
length-sequence |
1:length(x) to seq_along(x), 1:nrow(x) to seq_len(nrow(x)) |
unsafe |
class-equals |
class(x) == "a" to inherits(x, "a") |
unsafe |
length-test |
length(x == y) to length(x) == y |
unsafe |
scalar-in |
x %in% "a" to x == "a" |
unsafe |
order-subset |
x[order(x)] to sort(x, na.last = TRUE) |
unsafe |
matrix-apply |
apply(x, 1, sum) to rowSums(x), and colSums, rowMeans, colMeans alike |
unsafe |
unnecessary-lambda |
lapply(x, function(y) f(y)) to lapply(x, f) |
unsafe |
yoda-test |
expect_equal(2, x) to expect_equal(x, 2) |
unsafe |
nzchar |
nchar(x) == 0 to !nzchar(x), nchar(x) > 0 and != 0 to nzchar(x) |
unsafe |
sample-int |
sample(1:n, k) to sample.int(n, k) |
unsafe |
annotation-mismatch |
change the #: comment to the inline type, when ry uses the inline one and it names no type parameter |
safe |
unreachable-pattern |
remove the arm, when it has its lines to itself | safe |
unresolved, type-mismatch, annotation |
change a misspelled name, argument, field, column or type to the suggestion | unsafe |
non-exhaustive-match |
add an arm per missing case that calls stop("not handled yet") |
unsafe |
On by default
Section titled “On by default”syntax-error (error): code R would refuse to parse, or an assignment target R would refuse to
run, such as 1 + a <- 2. A parse error names what is missing, stays on the line that caused it, and
hides every other finding in the broken statement, because ry draws no conclusions from code it
could not read. Strict mode can still report an undetermined type there.
annotation (error): a #: comment that is malformed, names a type that does not exist, or
annotates nothing, an inline annotation whose type names something that does not exist or is
malformed in the same ways, and an unknown # typing: value. It is reported even in files with type
checking off, because a broken annotation is a mistake either way. A mistake in an inline type’s
grammar is a syntax-error instead, because it breaks the R statement it sits in.
annotation-mismatch (warning): a statement whose inline annotation and #: comment give the
same slot (the value, a parameter, the rest parameter, or the return) different types. It points at
both types and says which one ry uses, so a stale comment cannot silently contradict the code.
unresolved (warning): a name that is defined nowhere ry can see, with a suggestion for a near
miss. It also covers pkg::name where pkg does not export name, and an unknown package.
pkg:::name is exempt, because it reaches internal names on purpose. Inside a frame query such as
f[amuont > 1], a bare name that is neither a column of f nor defined anywhere is reported the
same way, with the closest column as the suggestion. In NAMESPACE, an
importFrom of a name the package does not export and an export of a name you never define are
errors, because R refuses to load such a package. Attaching a package ry knows nothing about turns
off this check for bare names, as stubs explains, and that includes a near
miss of one of your own names, because the package may export it.
unused (warning): an assignment nothing reads. In a package, top-level definitions are exempt,
because another file may use them. Some reads do not name the variable as code, and they count too:
- an assignment in tail position, which is the function’s value;
- a formal reassigned before
NextMethod()or an argument-lesscallGeneric(), which forward the formals’ current values; - a name inside a formula, such as
lm(ly ~ lx), which looks it up in the calling frame; - a string naming the variable in
get(),get0(),exists()orclusterExport(), or in the code thatparse(text = ...)orstr2lang()reads.
A function that hands out its own frame with environment() gets no finding at all, because the
caller can reach every local through it. Passing environment() to an accessor that names what it
reads, such as get() or clusterExport(), is not that.
duplicate (warning): a top-level name defined in more than one place in a package, where R
silently keeps whichever is collated last. Both definitions are reported. A rebinding is not a
duplicate when top-level code between the two reads the earlier value, as in x <- c(x, 3), and
neither is setGeneric("f") after f <- function(...), because it builds the generic from the
existing function. A read inside a function body does not count, since the body runs after both
bindings.
assignment-operator (warning): = used for assignment, where <- says unambiguously that the
line assigns rather than passes an argument.
boolean-shorthand (warning): T or F, which are ordinary variables that any code can
reassign, unlike TRUE and FALSE. A file that binds T or F itself, even as a parameter, gets
no finding for that name, because there it may mean the binding, and neither does the symbol in
quote(F).
trailing-comma (warning): a comma after a call’s last argument. R reads it as an empty
argument, which fails only when the callee evaluates it: c(1, 2, ) stops with “argument 3 is
empty”, while ngettext(2, "a", "b", ) runs, because the empty argument leaves domain at its
default. Empty arguments are allowed in alist(), where alist(x = ) declares a formal with no
default, and in a call whose arguments are all empty, such as xts(,).
equals-na (warning): a comparison with NA, such as x == NA, which gives NA whatever x
holds, so it never tests whether a value is missing. The fix to is.na(x) is unsafe because the
result changes from NA to TRUE or FALSE, which is the point but changes what the code does.
vector-logic (warning): & or | in an if or while condition, where && and || skip the right-hand side once the left decides the answer, and (since R 4.3)
stop with an error on a vector longer than one instead of looking at its first element. The fix
is unsafe because the right-hand side may no longer run. Inside a call such as any(x & y) the
operator is left alone, because there it works on vectors on purpose.
length-sequence (warning): 1:length(x), 1:nrow(x), 1:ncol(x), 1:NROW(x) or
1:NCOL(x), and the same counts in seq(length(x)). When the length is zero, 1:0 is c(1, 0), so a loop over it runs twice instead of
not at all. The fix to seq_along(x) or seq_len(nrow(x)) is unsafe because it changes what an
empty input does.
class-equals (warning): class(x) == "name" or !=, which misses an object whose class
vector has several entries: a tibble’s class is c("tbl_df", "tbl", "data.frame"), so the
comparison gives three values, and since R 4.2 an if on it stops with an error. The fix to inherits(x, "name") is unsafe because it changes the result for such
objects. A comparison inside any(), all() or which(), or behind a length(class(x)) == 1
guard, already handles several classes and is not reported.
unreachable-code (warning): statements after return(), stop(), break or next in the
same block, which never run. The range covers every statement from the first unreachable one to
the end of the block. A file that defines its own return or stop gets no finding for it, and
neither does a block inside quote(), bquote(), substitute() or expression().
sprintf-arguments (warning): a sprintf() or gettextf() call whose literal format wants a
different number of values than the call passes. Too few values stop R with “too few arguments”,
and an extra value is dropped with a warning. %% consumes nothing and * in a width or precision
consumes a value. A format with %1$s positions, a format that is not a literal, a ... argument,
or a named argument other than fmt turns the check off for that call.
! This format wants 2 values but sprintf() gets 1 value, so R stops with "too few arguments"length-test (warning): a comparison inside length(), such as length(x == 0). It counts
the comparison’s elements, which is length(x) when the right side is one value, so the comparison
was meant for the length. The fix moves it outside, and is unsafe because it changes the result.
! `length(x == 0)` is the length of the comparison, not a test of the length. Did you mean `length(x) == 0`?object-system (warning): a definition from S4, Reference Classes or R6, which is a call to
setClass, setGeneric, setMethod, setValidity, setRefClass or R6Class. That code still
runs, but ry checks records and tagged unions statically and
cannot see inside these classes, so it recommends those instead:
! `setClass` defines an S4 class. ry recommends a record or a tagged union insteadWith [check] object-systems = false, each definition is an error instead, whatever the [lint]
level says:
x S4 classes are turned off in this project (`[check] object-systems = false`), so `setClass` cannot define an S4 class. Use a record or a tagged union insteadstub (error): a line in your stubs/*.Rtypes files that ry could not load, so a broken
declaration is never dropped in silence.
inline-annotation (warning), while [check] inline-annotations = false: an inline annotation,
which then types nothing, and which R itself cannot run.
ry-syntax (warning), while [check] inline-annotations = false: a record, tuple, tag or
match, which R cannot run either. The value is still typed, but a match is not checked for
missing or unreachable cases.
! this record is ry syntax that R cannot run, and inline annotations are turned off (`[check] inline-annotations = false`) to keep code runnable by R. Rewrite it in plain R, or turn inline annotations back onconfig (error): invalid TOML or a value of the wrong type in ry.toml. The language server
marks the line in ry.toml, and ry check prints the finding and exits with status 2 without
checking any R.
Opt-in
Section titled “Opt-in”type-mismatch (error), with [check] typing = true or # typing: on: a value of the wrong
type, a call with the wrong arguments, a field or frame column that does not exist, a join of columns
that cannot be compared, a := that would convert a column’s values with loss, and every other rule in the
type system.
non-exhaustive-match (error), with typing on: a match that some value of the scrutinee’s
type reaches without a matching arm. The message names up to three missing cases as patterns, and
the range covers match (x). An arm with a guard does not count toward coverage, and a scrutinee
of unknown type is not checked.
x this `match` does not handle `:Empty`: add an arm for it, or a catch-all `_ => ...` armunreachable-pattern (warning), with typing on: an arm whose pattern the unguarded arms above
it already cover, so it never runs.
! this arm is unreachable: the arms above it already match every value its pattern matchesstrict (error), with [check] strict = true or # typing: strict: each place where a value’s
type could not be determined, each parameter nothing constrains, and each name that resolves only
because an unknown package was attached. In a file under R/, it also reports each top-level
statement that does more than define something, on the call, loop or assignment that has the effect,
and says where the code belongs (a package file’s top level):
x strict mode: this calls `cat`, which is not declared pure, so it runs every time the package loads. A file in `R/` may only define things at its top level: move the call into a function, `.onLoad`, or the script `ry run` startsIt also raises unresolved from a warning to an error, so a gate on --min-severity error counts it.
native (error), with [check] strict = true or # typing: strict: an R value in a
native function. A native function is one whose signature
is written entirely in ry types, and its body may hold only ry values, so the finding marks an R
value used outside a conversion or an R call nested in another R call’s arguments. Each message says
what to write instead. A function with an R type in its signature is not judged.
x `nchar` is an R function, and a native function holds only ry values, so its result cannot be used here. Convert the result where it returns: `Num.from_r(nchar(label))`interpreted (warning), in strict mode: a construct that sends a
native function to the interpreter because the native
compiler does not compile it yet. The program is legitimate ry and gives the same results. The
message names the construct and the way to write the step that compiles.
! this function runs in the interpreter, because `List.reverse` is not compiled natively yet. Write the step with a loop or another standard library functionmaybe-undefined (warning), with [check] maybe-undefined = true: a read that some path reaches
before any write, which R reports as object 'v' not found on that path. It is off because it treats
conditions that always agree as independent, so if (ok) v <- 1 followed by if (ok) print(v) is
reported although it is safe.
naming-style (warning), with [lint] naming-style = "snake_case" or "camelCase": a variable
or parameter in the other style. SCREAMING_SNAKE_CASE always conforms.
unused-parameter (off by default): a parameter the body never reads. S3 generics and methods
are exempt, because the generic dictates their parameters.
unused-import (off by default): an importFrom in NAMESPACE whose name your code never
mentions. Only ry check reports it.
shadows-builtin and shadows-namespace (off by default): a top-level name that hides a
function from base, or from another package, such as defining your own filter while
stats::filter exists.
data-table (off by default): a call that creates a data.table, which is data.table(),
fread(), as.data.table() or setDT(), bare or as data.table::. data.table code runs
unchanged, so this only helps you find the code to move to the typed
DataFrame when you choose to. A file that defines its own function of
that name is not flagged.
! `fread` creates a data.table. Its typed equivalent is `DataFrame.read_csv()`, see https://ry-lang.org/reference/from-data-table/redundant-return (off by default): return(x) as a function’s last expression, including
both branches of a trailing if, where x alone returns the same value. A file that defines its
own return gets no finding.
commented-code (off by default): a comment that parses as R and calls, assigns, defines,
branches, loops or indexes, such as # x <- compute(y). Prose rarely parses that way, and roxygen
(#'), plumber (#*), Quarto (#|), #! and #> output comments are skipped. Delete the code
instead: version control keeps it.
duplicate-argument (off by default): the same argument name twice in one call, which stops a
function with “formal argument matched by multiple actual arguments”. It is off because a function
that collects ... keeps both values on purpose, such as cli’s c("i" = ..., "i" = ...) bullets or
two HTML class attributes, and the lint cannot see which functions do. With type checking on,
a call that gives a known function’s parameter twice is a type-mismatch anyway, such as
paste(sep = "", sep = "-"). mutate(), transmute(),
summarise(), summarize() and reframe() are exempt, because there a repeated name updates a
column.
any-is-na, paste-sep, lengths, literal-coercion, redundant-equals and
single-quotes (off by default): spellings with a shorter or faster equivalent, listed with
their fixes under Fixes. redundant-equals and lengths have unsafe fixes, because
1 == TRUE is TRUE and sapply() on an empty list returns a list, not an integer vector.
testthat-expectation (off by default): a general testthat expectation where a specific one
exists, such as expect_equal(x, NULL) for expect_null(x). The specific one fails with a message
that says what went wrong. Most fixes are unsafe because the specific expectation accepts different
values: expect_false(x) passes only for FALSE, while expect_true(!x) also passes for 0.
condition-message (off by default): paste0(), or paste() with sep = "", inside stop(),
warning(), message() or packageStartupMessage(), which join their arguments themselves. R
translates a condition message argument by argument, so a pasted message cannot be translated. The
fix is unsafe because paste0() recycles vectors element by element where stop() joins them end
to end.
fixed-regex (off by default): a literal pattern with no regular expression syntax in grepl(),
grep(), sub(), gsub(), regexpr(), gregexpr(), regexec() or strsplit(), which
fixed = TRUE matches faster. Calls that already set fixed, perl or ignore.case are skipped,
and so are sub() and gsub() with a replacement that may hold a backreference. The fix is unsafe
because R can mark the encoding of a fixed match’s result differently.
browser-call (off by default): a browser() call, which pauses the code whenever it runs
interactively. A call inside quote(), bquote(), substitute() or expression() is skipped,
because there it is code built on purpose.
line-length (off by default): a line longer than [lint] max-line-length characters, 80
unless you set it. The formatter keeps your line breaks and never splits a line, so this lint is
what keeps lines short. It counts characters, not bytes, and reports from the first character past
the limit.
implicit-assignment (off by default): <-, <<- or -> inside an if or while
condition, such as if (x <- f()), where an assignment reads like a comparison. A function defined
inside the condition is skipped. while ((line <- next_line()) != "") is a common R idiom, which is
why the lint is opt-in.
scalar-in, order-subset, matrix-apply and unnecessary-lambda (off by
default): code with a simpler or faster equivalent whose fix can change the result in an edge
case, so each fix is unsafe. x %in% "a" is FALSE for an NA where x == "a" is NA.
x[order(x)] dispatches like [ where sort() dispatches on its own methods. apply() turns a
data frame into a matrix before rowSums() would, and a function passed by name receives the extra
arguments an apply function forwards, where an anonymous one with a single parameter would reject
them. matrix-apply covers sum and mean over margin 1 or 2, with an optional na.rm, and
unnecessary-lambda covers lapply(), sapply(), vapply(), Filter(), Map() and purrr’s
map() family, walk(), keep() and discard().
yoda-test (off by default): expect_equal() or expect_identical() with a constant first and
the value under test second. testthat reports the first argument as the actual value, so a failure
message reads backwards. The fix swaps them, and is unsafe because expect_equal() measures a
numeric tolerance relative to one of its two arguments.
nzchar and sample-int (off by default): nchar(x) == 0, which counts every string
only to test whether it is empty, and sample(1:n, k), which builds 1:n only to draw from it.
Both fixes are unsafe: nchar(NA) is 2 while nzchar(NA) is TRUE, and sample(1:0, 1) draws
from c(1, 0) where sample.int(0, 1) fails.
while-true, empty-assignment and unnecessary-concatenation (off by default):
while (TRUE), which repeat says directly, x <- {}, which assigns NULL, and c() around a
single constant or around nothing, which returns that constant or NULL. All three fixes are safe.
comparison-negation, outer-negation, which-grepl, length-levels and
numeric-leading-zero (off by default): more spellings with a shorter equivalent, each with a
safe fix under Fixes. A fix that would change how the surrounding expression parses gets
parentheses, so all(!x) + 1 becomes (!any(x)) + 1.
These lints take a level in [lint], such as "warn" or "error". An older missing-comma key is
still accepted and does nothing, because f(1 2) is now a syntax error, as it is in R.