Extending or modifying checks

3.1 New Local Checks (for package users)

The main pkgcheck() function has an additional parameter, extra_env which specifies,

Additional environments from which to collate checks. Other package names may be appended using c, as in c(.GlobalEnv, “mypkg”).

This allows specific checks to be defined locally, and run by passing the name of the environment in which those checks are defined in this parameter. This section illustrates the process using the bundled “tarball” (that is, .tar.gz file) of one version of the pkgstats package included with that package.

f <- system.file ("extdata", "pkgstats_9.9.tar.gz", package = "pkgstats")
path <- pkgstats::extract_tarball (f)
checks <- pkgcheck (path)
summary (checks)

#> 
#> ── pkgstats 9.9 ────────────────────────────────────────────────────────────────
#> 
#> ✔ Package name is available
#> ✖ does not have a 'codemeta.json' file.
#> ✖ does not have a 'contributing' file.
#> ✔ uses 'roxygen2'.
#> ✔ 'DESCRIPTION' has a URL field.
#> ✔ 'DESCRIPTION' has a BugReports field.
#> ✖ Package has no HTML vignettes
#> ✖ These functions do not have examples: [pkgstats_from_archive].
#> ✔ Package has continuous integration checks.
#> ✖ Package coverage failed
#> ✖ R CMD check found 1 error.
#> ✔ R CMD check found no warnings.
#> 
#> ℹ Current status:
#> ✖ This package is not ready to be submitted.

Let’s now presume I have a reputation in the R community for all of my packages starting with “aa”, to ensure they are always listed first. This section demonstrates how to implement a check that only passes if the first two letters of the package name are “aa”. The first step described above is to define the check itself via a function prefixed with pkgchk_. The easiest approach would be for the pkgcheck_ function to directly check the name, and return a logical flag indicating whether or not the same starts with “aa”. The resultant summary and print methods can, however, only use the information provided by the initial pkgchk_ function. That means if we want to print the actual name in the result of either of those functions, to show that it indeed does not form the desired patter, we need to return that information. The check function is then simply:

pkgchk_starts_with_aa <- function (checks) {
    checks$pkg$name
}

We then need to define the output functions:

output_pkgchk_starts_with_aa <- function (checks) {

    out <- list (
                 check_pass = grepl ("^aa",
                                     checks$checks$starts_with_aa,
                                     ignore.case = TRUE),
                 summary = "",
                 print = ""
    )

    out$summary <- paste0 ("Package name [",
                           checks$checks$starts_with_aa,
                           "] does ",
                           ifelse (out$check_pass,
                                   "",
                                   "NOT"),
                           " start with 'aa'")

    return (out)
}

If we simply define those function in the global workspace of our current R session, calling pkgcheck() again will automatically detect those checks and include them in our output:

#> 
#> ── pkgstats 9.9 ────────────────────────────────────────────────────────────────
#> 
#> ✔ Package name is available
#> ✖ does not have a 'codemeta.json' file.
#> ✖ does not have a 'contributing' file.
#> ✔ uses 'roxygen2'.
#> ✔ 'DESCRIPTION' has a URL field.
#> ✔ 'DESCRIPTION' has a BugReports field.
#> ✖ Package has no HTML vignettes
#> ✖ These functions do not have examples: [pkgstats_from_archive].
#> ✔ Package has continuous integration checks.
#> ✖ Package coverage failed
#> ✖ Package name [pkgstats] does NOT start with 'aa'
#> ✖ R CMD check found 1 error.
#> ✔ R CMD check found no warnings.
#> 
#> ℹ Current status:
#> ✖ This package is not ready to be submitted.

Customised personal checks can be incorporated by defining them in a local package, loading that into the workspace, and passing the name of the package to the extra_env parameter.

3.2 New pkgcheck Checks (for pkgcheck developers)

New checks can be added to this package by creating new files in the /R directory prefixed with pkgchk_, and including the two functions described above (a check and an output function). The check name will then need to be included in the order_checks() function in the R/summarise-checks.R file, which determines the order of checks in the summary output. Checks which are not defined in this ordering, including any defined via extra_env parameters, appear after all of the standard checks, and prior to the R CMD check results which always appear last. This order may only be modified by editing the list in that function. The order of check results in the print method is also hard-coded, defined in the main print.pkgcheck method. As explicitly stated in that function, any new checks should also be included in the print method just after the first reference to "misc_checks", via an additional line:

print_check_screen (x, "<name-of-new-check>", pkg_env)

The print_check_screen() function will then automatically activate the print method of any new checks. This line should be added even if a new check has no print method (as in the starts_with_aa example above), to provide an explicit record of all internally-defined miscellaneous checks.

Finally, any new checks also need to be included in tests. The test suites run on generic, mostly empty packages constructed with the srr::srr_stats_pkg_skeleton() function, as in the main test-pkgcheck.R test functions. Additional tests are also performed on the pkgstats tarball illustrated above. The default results of any new checks will be automatically tested by the existing test suite, but it is important to test all potential results. The test-extra-checks.R file is the main location for testing additional tests, with lines in that file demonstrating how the main results can be readily modified to reflect alternative outputs of check functions (such as pkgchk_has_scrap and pkgchk_obsolete_pkg_deps). The output functions defined as part of checks, including any new checks, do not need to be explicitly tested, as the entire output is tested via testthat snapshots. Snapshot results need to be updated to reflect any additional tests. Finally, the test-list-checks.R file tests the total number of internally-defined checks as expect_length (ncks, ..). The number tested there also needs to be incremented by one for each new check.