Example usage

The checkglobals-package contains a single wrapper function checkglobals() to inspect R-scripts, Rmd-documents, folders, R-code strings or R-packages. As an example, we consider the following R-script containing a demo Shiny application (source: https://raw.githubusercontent.com/rstudio/shiny-examples/main/004-mpg/app.R).

# scripts/app.R
library(shiny)
library(datasets)

# Data pre-processing ----
mpgData <- mtcars
mpgData$am <- factor(mpgData$am, labels = c("Automatic", "Manual"))

# Define UI for miles per gallon app ----
ui <- fluidPage(
  titlePanel("Miles Per Gallon"),
  sidebarLayout(
    sidebarPanel(
      selectInput("variable", "Variable:",
                  c("Cylinders" = "cyl",
                    "Transmission" = "am",
                    "Gears" = "gear")),
      checkboxInput("outliers", "Show outliers", TRUE)
    ),
    mainPanel(
      h3(textOutput("caption")),
      plotOutput("mpgPlot")
    )
  )
)

# Define server logic to plot various variables against mpg ----
server <- function(input, output) {
  formulaText <- reactive({
    paste("mpg ~", input$variable)
  })
  output$caption <- renderText({
    formulaText()
  })
  output$mpgPlot <- renderPlot({
    boxplot(as.formula(formulaText()),
            data = mpgData,
            outline = input$outliers,
            col = "#75AADB", pch = 19)
  })
}

# Create Shiny app ----
shinyApp(ui, server)

Calling checkglobals() with the argument file on the R-script saved as a local file returns as output:

Looking at the printed output of the object returned by checkglobals(), it lists the following information:

1. the name and location of all unrecognized global variables;
2. the name and location of all detected imported functions grouped by R-package.

The location app.R#36 lists the R-file name (app.R) and line number (36) of the detected variable or function. If cli is installed and cli-hyperlinks are supported, clicking the location links opens the source file pointing to the given line number. The bars and counts behind the imported package names highlight the number of function calls detected from each package.

More detailed information can be obtained by calling print() directly. For instance, we can print the referenced source code lines of the unrecognized global variables with:

The detection of imported functions and packages is an important motivation for the checkglobals-package. First, this allows us to validate the NAMESPACE file of a development R-package or check R-scripts for any additional packages that require installation before execution of the code. Second, this information can be used to get a better sense of the importance of an imported package, for instance to determine how much effort it would take to remove or replace it as a dependency. This is different from e.g. the codetools package, where findGlobals() or checkUsage() return an undefined variable name if a function import is not recognized, but do not return variable names that have been recognized as imports. The same is true for the convenience packages lintr (with object_usage_linter()) or globals which provide codetools wrappers producing similar results as returned by R CMD check. More similar is renv::dependencies(), which scans for all loaded and/or imported packages in an R project folder by analyzing the DESCRIPTION and NAMESPACE files of an R-package or by detecting calls to library(), require(), etc. in an R-script. Note that renv::dependencies() returns package names, but not the functions called from these packages.

An additional benefit of a minimal and efficient code analysis package is that we can significantly reduce the runtime required to inspect large R-packages or codebases allowing to quickly check the code interactively during development:

## absolute timings (seconds) for inspecting the shiny package 
## (100-fold relative time difference)
bench::mark(
  lint_package = lint_package("~/git/shiny", linters = list(object_usage_linter())),
  checkglobals = checkglobals(pkg = "~/git/shiny/"),
  iterations = 10,
  check = FALSE,
  time_unit = "s"
)
#> # A tibble: 2 × 6
#>   expression      min median `itr/sec` mem_alloc `gc/sec`
#>   <bch:expr>    <dbl>  <dbl>     <dbl> <bch:byt>    <dbl>
#> 1 lint_package 18.8   19.5      0.0508    1.33GB     2.42
#> 2 checkglobals  0.157  0.162    5.96     15.69MB     1.19

R Markdown files

The file argument also accepts R Markdown (.Rmd or .Rmarkdown) file locations. For R Markdown files, the R code chunks are first extracted into a temporary R-script with knitr::purl(), which is then analyzed by checkglobals(). Instead of a local file, the file argument in checkglobals() can also be a remote file location (e.g. a server or the web), in which case the remote file is first downloaded as a temporary file with download.file(). Below, we scan one of tidyr’s package vignettes (source: https://raw.githubusercontent.com/tidyverse/tidyr/main/vignettes/tidy-data.Rmd),

R-packages that are imported or loaded, but have no detected function imports are displayed with an n/a reference. This can happen when checkglobals() falsely ignores one or more imported functions from the given package or when the package is not actually needed as a dependency. In both cases this is useful information to have. In the above example, tibble is loaded in order to use tribble(), but the tribble() function is also exported by dplyr, so it shows up under the dplyr imports instead.

Folders

Folders containing R-scripts can be scanned with the dir argument, which inspects all R-scripts present in dir (and any of its subdirectories). The following example scans an R-Shiny app folder containing a ui.R and server.R file (source: https://github.com/rstudio/shiny-examples/tree/main/018-datatable-options),

If imports are detected from an R-package not installed in the current R-session, an alert is printed (as with the DT package above). Function calls accessing the missing R-package explicitly, using e.g. :: or :::, can still be fully identified as imported function names. Function calls with no reference to the missing R-package will be listed as unrecognized global variables.

R-packages

R-package folders can be scanned with the pkg argument. Conceptually, checkglobals() scans all files in the /R folder of the package and contrasts the detected (unrecognized) globals and imports against the imports listed in the NAMESPACE file of the package. R-scripts present elsewhere in the package (e.g. in the /inst folder) are not analyzed, as these are not covered by the package NAMESPACE file. To illustrate, we can run checkglobals() on its own package folder:

Known limitations

To conclude, we discuss some of the limitations of static code analysis with codetools and checkglobals. When using codetools (or R CMD check) there are several scenarios where the code inspection is known to skip undefined names that could potentially be detected. First, a variable that requires evaluation before it is defined may be missed, as codetools does not track in which order assignment and evaluation happen inside a local scope. Here is a minimal example using codetools::findGlobals():

## findGlobals requires a function as input
test1 <- function() {
  print(x)
  x <- 1
}

## calling this function generates an error
test1()
#> Error in test1(): object 'x' not found

library(codetools)

## x is not recognized as an undefined 
## variable at the moment of evaluation
findGlobals(test1)
#> [1] "{"     "<-"    "print"

Another quite common situation is the use of a character function name inside a functional, e.g. Reduce(), Filter(), Map() or the apply-family of functions. These function names are viewed by codetools as ordinary character strings:

test2 <- function() { 
  do.call("foo", 1) 
}

## foo is not recognized as an undefined
## variable since it is defined as a string
findGlobals(test2)
#> [1] "{"       "do.call"

Finally, more complex assignment statements may not always be handled as expected:

test3 <- function() { 
  assign(x = "x1", value = 1)
  assign(value = 2, x = "x2")
  c(x1, x2)
}

## assignment to x1 is recognized correctly, 
## but assignment to x2 is not
findGlobals(test3)
#> [1] "{"      "assign" "c"      "x2"

x <- NA
test4 <- function() { 
  x <<- 1
  x
}

## x is assigned in a different scope 
## but is available when evaluated
findGlobals(test4)
#> [1] "{"   "<<-" "x"

The checkglobals-package tries to address some of these use-cases, but due to R’s flexibility as a language, there are a number of use-cases we can think of that are either too ambiguous or complex to be analyzed without evaluation of the code itself. Below we list some of these cases, where checkglobals() fails to recognize a variable name (false negative) or falsely detects a global variable when it should not (false positive).

## this works (character arguments are recognized as functions)
checkglobals(text = 'do.call(args = list(1), what = "median")')
checkglobals(text = 'Map("g", 1, n = 1)')
checkglobals(text = 'stats::aggregate(x ~ ., data = y, FUN = "g")')

## this doesn't work (evaluation is required)
checkglobals(text = 'g <- "f"; Map(g, 1, n = 1)')
checkglobals(text = "eval(substitute(g))") ## same for ~, expression, quote, bquote, Quote, etc.

## this works (calling a function in an exotic way)
checkglobals(text = '"head"(1:10)')
checkglobals(text = '`::`("utils", "head")(1:10)')
checkglobals(text = 'list("function" = utils::head)$`function`(1:10)')

## this doesn't work (evaluation is required)
checkglobals(text = 'get("head")(1:10)')
checkglobals(text = 'methods::getMethod("f", signature = "ANY")')

## this works (simple evaluation of package names)
checkglobals(text = 'attachNamespace("utils"); head(1:10)')
checkglobals(text = 'pkg <- "utils"; library(pkg, character.only = TRUE); head(1:10)')

## this doesn't work (more complex evaluation is required)
checkglobals(text = 'pkg <- function() "utils"; library(pkg(), character.only = TRUE); head(1:10)')
checkglobals(text = 'loadPkg <- library; loadPkg(utils)')
checkglobals(text = 'box::use(utils[...])')

## this works (special functions self, private, super are recognized)
checkglobals(text = 'R6::R6Class("cl",
                   public = list(
                     initialize = function(...) self$f(...),
                     f = function(...) private$p
                   ),
                   private = list(
                     p = list()
                   ))')

## this doesn't work (data masking)
checkglobals(text = 'transform(mtcars, mpg2 = mpg^2)')
checkglobals(text = 'attach(iris); print(Sepal.Width)')

## this works (basic lazy evaluation)
checkglobals(text = '{
    addy <- function(y) x + y 
    x <- 0
    addy(1)
}')
checkglobals(
  text = 'function() { 
    on.exit(rm(x))
    x <- 0 
}')

## this doesn't work (lazy evaluation in external functions)
checkglobals(
  text = 'server <- function(input, output) {
    add1x <- shiny::reactive({
      add1(input$x)
    })
    add1 <- function(x) x + 1  
  }')