pkgcheck

https://docs.ropensci.org/pkgcheck/
Admin
pkgcheck is an R package that checks whether an R package is ready for submission to rOpenSci's peer...
Tokens:11,957
Snippets:123
Trust Score:9.8
Update:6 months ago
Show doc for...
Tokens:
Raw
### Example of read_pkg_guide

Source: https://docs.ropensci.org/pkgcheck/reference/read_pkg_guide.html

Demonstrates how to call the function to open the guide.

```R
if (FALSE) { # \dontrun{
read_pkg_guide ()
} # }
```

--------------------------------

### Run pkgcheck examples

Source: https://docs.ropensci.org/pkgcheck/reference/pkgcheck.html

Demonstrates running full checks versus skipping goodpractice checks. These examples are wrapped in a non-executable block.

```R
if (FALSE) { # \dontrun{
checks <- pkgcheck ("/path/to/my/package") # default full check
summary (checks)
# Or to run only checks implemented in 'pkgcheck' and not the
# additional \pkg{goodpractice} checks:
checks <- pkgcheck ("/path/to/my/package", goodpractice = FALSE)
summary (checks)
} # }
```

--------------------------------

### Example: Configure pkgcheck Action Inputs

Source: https://docs.ropensci.org/pkgcheck/reference/use_github_action_pkgcheck.html

Demonstrates how to pass a list of inputs to the pkgcheck GitHub Action. This example disables posting results to an issue.

```R
use_github_action_pkgcheck (inputs = list (`post-to-issue` = "false"))
```

--------------------------------

### Example: Specify Branch for pkgcheck Action

Source: https://docs.ropensci.org/pkgcheck/reference/use_github_action_pkgcheck.html

Shows how to specify a particular branch for the pkgcheck GitHub Action to run on. This example sets the branch to 'main'.

```R
use_github_action_pkgcheck (branch = "main")
```

--------------------------------

### Install pkgcheck from r-universe

Source: https://docs.ropensci.org/pkgcheck/index.html

Enable the rOpenSci review tools universe and install the pkgcheck package using install.packages().

```R
options (repos = c (
    ropenscireviewtools = "https://ropensci-review-tools.r-universe.dev",
    CRAN = "https://cloud.r-project.org"
))
install.packages ("pkgcheck")
```

--------------------------------

### Install pkgcheck from GitHub

Source: https://docs.ropensci.org/pkgcheck/index.html

Install the pkgcheck package directly from GitHub using either the remotes or pak package managers.

```R
remotes::install_github ("ropensci-review-tools/pkgcheck")
```

```R
pak::pkg_install ("ropensci-review-tools/pkgcheck")
```

--------------------------------

### Install pkgcheck from Git URL

Source: https://docs.ropensci.org/pkgcheck/index.html

Install the pkgcheck package from a Git repository URL using the remotes package.

```R
remotes::install_git ("https://codeberg.org/ropensci-review-tools/pkgcheck")
```

```R
remotes::install_git ("https://codefloe.com/ropensci-review-tools/pkgcheck")
```

--------------------------------

### Usage of read_pkg_guide

Source: https://docs.ropensci.org/pkgcheck/reference/read_pkg_guide.html

Opens the rOpenSci Package Development Guide in the default browser.

```R
read_pkg_guide(which = c("release", "dev"))
```

--------------------------------

### Run pkgcheck on a package

Source: https://docs.ropensci.org/pkgcheck/reference/print.pkgcheck.html

This example demonstrates how to run pkgcheck on a local package directory. Ensure the path is correct.

```R
if (FALSE) { # \dontrun{
checks <- pkgcheck ("/path/to/my/package")
print (checks) # print full checks, starting with summary
summary (checks) # print summary only
} # }
```

--------------------------------

### Guides

Source: https://docs.ropensci.org/pkgcheck/reference/index.html

Function to browse packaging guidelines.

```APIDOC
## read_pkg_guide()

### Description
Browse packaging guidelines.

### Method
Not applicable (R function)

### Endpoint
Not applicable (R function)
```

--------------------------------

### Read Package Development Guide

Source: https://docs.ropensci.org/pkgcheck/reference/read_pkg_guide.html

A convenience function to automatically open the web page of rOpenSci's "Package Development Guide" in the default browser.

```APIDOC
## read_pkg_guide

### Description
A convenience function to automatically open the web page of rOpenSci's "Package Development Guide" in the default browser.

### Usage
```R
read_pkg_guide(which = c("release", "dev"))
```

### Arguments

* **which** (character vector) - Whether to read the released or "dev" development version.

### Value
Nothing. Function called purely for side-effect of opening web page with package guidelines.

### Examples

```R
if (FALSE) { # \dontrun{
read_pkg_guide ()
}
}
```
```

--------------------------------

### Example usage of logfile_names

Source: https://docs.ropensci.org/pkgcheck/reference/logfile_names.html

Demonstrates how to call the function to retrieve log file paths.

```R
if (FALSE) { # \dontrun{
logfiles <- logfiles_namnes ("/path/to/my/package")
print (logfiles)
} # }
```

--------------------------------

### Example usage of render_md2html

Source: https://docs.ropensci.org/pkgcheck/reference/render_md2html.html

Demonstrates generating markdown from package checks and converting it to HTML.

```R
if (FALSE) { # \dontrun{
checks <- pkgcheck ("/path/to/my/package")
# Generate standard markdown-formatted character vector:
md <- checks_to_markdown (checks)

# Directly generate HTML output:
h <- checks_to_markdown (checks, render = TRUE) # HTML version

# Or convert markdown-formatted version to HTML:
h <- render_md2html (md)
} # }
```

--------------------------------

### Example usage of get_latest_commit

Source: https://docs.ropensci.org/pkgcheck/reference/get_latest_commit.html

Demonstrates how to call the function with an organization and repository name.

```R
if (FALSE) { # \dontrun{
org <- "ropensci-review-tools"
repo <- "pkgcheck"
commit <- get_latest_commit (org, repo)
} # }
```

--------------------------------

### Example usage of checks_to_markdown

Source: https://docs.ropensci.org/pkgcheck/reference/checks_to_markdown.html

Demonstrates generating a markdown report and optionally rendering it as HTML.

```R
if (FALSE) { # \dontrun{
checks <- pkgcheck ("/path/to/my/package")
md <- checks_to_markdown (checks) # markdown-formatted character vector
md <- checks_to_markdown (checks, render = TRUE) # HTML version
} # }
```

--------------------------------

### pkgcheck Coding Style Example

Source: https://docs.ropensci.org/pkgcheck/CONTRIBUTING.html

Illustrates the preferred pkgcheck coding style, which uses whitespace around parentheses for improved readability, differing from the tidyverse style.

```R
these <- three (words (x))
```

```R
this <- function ()
```

--------------------------------

### Run pkgcheck on a local tarball

Source: https://docs.ropensci.org/pkgcheck/articles/extending-checks.html

Extract a package tarball and run pkgcheck on it. This is useful for analyzing packages that are not yet installed.

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

--------------------------------

### List all pkgcheck checks

Source: https://docs.ropensci.org/pkgcheck/reference/list_pkgchecks.html

Call this function to get a character vector of all checks implemented in the pkgcheck package. Set `quiet = TRUE` to suppress console output.

```R
list_pkgchecks ()
```

--------------------------------

### GET /get_default_github_branch

Source: https://docs.ropensci.org/pkgcheck/reference/get_default_github_branch.html

Retrieves the name of the default branch for a specified GitHub repository.

```APIDOC
## GET /get_default_github_branch

### Description
Retrieves the name of the default branch on GitHub for a given organization and repository.

### Method
GET

### Endpoint
/get_default_github_branch

### Parameters
#### Query Parameters
- **org** (string) - Required - Github organization
- **repo** (string) - Required - Github repository

### Response
#### Success Response (200)
- **branch** (string) - Name of default branch on GitHub

### Response Example
{
  "branch": "main"
}
```

--------------------------------

### Define custom output for pkgcheck

Source: https://docs.ropensci.org/pkgcheck/articles/extending-checks.html

Define output functions for custom checks that start with 'output_pkgchk_'. These functions determine the check's pass/fail status and format the summary and print output.

```r
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)
}
```

--------------------------------

### Define a custom pkgcheck function

Source: https://docs.ropensci.org/pkgcheck/articles/extending-checks.html

Define a custom check function that starts with 'pkgchk_'. This function should return the package name to be used in output functions.

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

--------------------------------

### Get GitHub Token

Source: https://docs.ropensci.org/pkgcheck/reference/get_gh_token.html

Retrieves a GitHub access token from environment variables. This is useful for authenticating with GitHub API when performing package checks or other related operations.

```APIDOC
## GET /github/token

### Description
Retrieves a GitHub access token from environment variables.

### Method
GET

### Endpoint
/github/token

### Parameters
#### Query Parameters
- **token_name** (string) - Optional - The name of the token to use. If not provided, a default token will be used.

### Response
#### Success Response (200)
- **token** (string) - The value of the GitHub access token.

#### Response Example
```json
{
  "token": "your_github_access_token"
}
```
```

--------------------------------

### Get Latest Commit

Source: https://docs.ropensci.org/pkgcheck/reference/get_latest_commit.html

Retrieves the details of the latest commit from a specified GitHub repository and organization.

```APIDOC
## GET /api/github/latest_commit

### Description
Retrieves the details of the latest commit from a specified GitHub repository and organization.

### Method
GET

### Endpoint
/api/github/latest_commit

### Parameters
#### Query Parameters
- **org** (string) - Required - Github organization
- **repo** (string) - Required - Github repository
- **branch** (string) - Optional - Branch from which to get latest commit

### Response
#### Success Response (200)
- **oid** (string) - The OID hash of the latest commit.
- **message** (string) - The commit message.
- **author** (string) - The author of the commit.
- **date** (string) - The date of the commit.

### Request Example
```json
{
  "org": "ropensci-review-tools",
  "repo": "pkgcheck",
  "branch": "main"
}
```

### Response Example
```json
{
  "oid": "a1b2c3d4e5f678901234567890abcdef12345678",
  "message": "Update documentation",
  "author": "John Doe",
  "date": "2023-10-27T10:00:00Z"
}
```
```

--------------------------------

### Modify check data for test cases

Source: https://docs.ropensci.org/pkgcheck/articles/extending-checks.html

Example of manually overriding check data values to test specific output conditions.

```R
checks$checks$has_scrap <- "scrap"
```

--------------------------------

### Get Default GitHub Branch

Source: https://docs.ropensci.org/pkgcheck/reference/get_default_github_branch.html

Retrieves the name of the default branch for a given GitHub organization and repository. This function is intended for internal use within the plumber API and not for direct user calls.

```R
get_default_github_branch(org, repo)
```

```R
if (FALSE) { # \dontrun{ 
org <- "ropensci-review-tools"
repo <- "pkgcheck"
branch <- get_default_github_branch (org, repo)
} # }
```

--------------------------------

### Analyze a package repository with pkgcheck

Source: https://docs.ropensci.org/pkgcheck/index.html

Clone a repository, document it, and then use the pkgcheck() function to analyze its readiness for submission. The summary() method can be used to check submission readiness.

```R
mydir <- file.path (tempdir (), "srr-demo")
gert::git_clone ("https://github.com/mpadge/srr-demo", path = mydir)
devtools::document (mydir, quiet = TRUE) # Generate documentation entries in "/man" directory
x <- pkgcheck (mydir)
```

```R
summary (x)
```

--------------------------------

### Monitor and Retrieve Background pkgcheck Results

Source: https://docs.ropensci.org/pkgcheck/reference/pkgcheck_bg.html

After initiating a background pkgcheck process, you can monitor its status by printing the process object or reading its output file. Once the process is finished, retrieve the results using $get_result().

```R
ps # print status to screen, same as 'ps$print()'
f <- ps$get_output_file ()
readLines (f) # or directly open file with local file viewer
checks <- ps$get_result ()
```

--------------------------------

### Add pkgcheck GitHub action

Source: https://docs.ropensci.org/pkgcheck/index.html

Use `use_github_action_pkgcheck()` to download the workflow file for the pkgcheck GitHub action into your local .github/workflows folder. This allows running pkgcheck automatically on commits.

```R
usethis::use_github_action_check_standard()
```

--------------------------------

### Create pkgcheck Github Action Workflow

Source: https://docs.ropensci.org/pkgcheck/reference/use_github_action_pkgcheck.html

Use this function to generate a GitHub workflow file that integrates pkgcheck into your CI pipeline. Specify the directory, filename, and branch for the workflow. You can also provide custom inputs for the pkgcheck action.

```R
use_github_action_pkgcheck(
  dir = ".github/workflows",
  overwrite = FALSE,
  file_name = "pkgcheck.yaml",
  branch = gert::git_branch(),
  inputs = NULL
)
```

--------------------------------

### GitHub Action Inputs for pkgcheck

Source: https://docs.ropensci.org/pkgcheck/reference/use_github_action_pkgcheck.html

Configuration options for the `ropensci-review-tools/pkgcheck-action`. These inputs control how pkgcheck results are handled, including posting to issues and the format of the output.

```yaml
inputs:
  ref:
    description: "The ref to checkout and check. Set to empty string to skip checkout."
    default: "${{ github.ref }}"
    required: true
  post-to-issue:
    description: "Should the pkgcheck results be posted as an issue?"
    # If you use the 'pull_request' trigger and the PR is from outside the repo
    # (e.g. a fork), the job will fail due to permission issues
    # if this is set to 'true'. The default will prevent this.
    default: ${{ github.event_name != 'pull_request' }}
    required: true
  issue-title:
    description: "Name for the issue containing the pkgcheck results. Will be created or updated."
    # This will create a new issue for every branch, set it to something fixed
    # to only create one issue that is updated via edits.
    default: "pkgcheck results - ${{ github.ref_name }}"
    required: true
  summary-only:
    description: "Only post the check summary to issue. Set to false to get the full results in the issue."
    default: true
    required: true
  append-to-issue:
    description: "Should issue results be appended to existing issue, or posted in new issues."
    default: true
    required: true
```

--------------------------------

### Load pkgcheck package

Source: https://docs.ropensci.org/pkgcheck/index.html

Load the pkgcheck package into the R session for use.

```R
library (pkgcheck)
```

--------------------------------

### Initialize check data for testing

Source: https://docs.ropensci.org/pkgcheck/articles/extending-checks.html

Standard boilerplate for initializing check data and generating output for a specific check function.

```R
checks <- make_check_data ()
ci_out <- output_pkgchk_<fn-name> (checks)
```

--------------------------------

### pkgcheck GitHub Actions Badge

Source: https://docs.ropensci.org/pkgcheck/index.html

Add this line to your README file to include a badge that reflects the current state of your repository's pkgcheck results. Replace `<org>` and `<repo>` with your GitHub organization and repository names.

```Markdown
[![pkgcheck](https://github.com/<org>/<repo>/workflows/pkgcheck/badge.svg)](https://github.com/<org>/<repo>/actions?query=workflow%3Apkgcheck)
```

--------------------------------

### Generic print method for pkgcheck objects

Source: https://docs.ropensci.org/pkgcheck/reference/print.pkgcheck.html

Use this S3 method to print pkgcheck objects. Set 'deps' to TRUE to include dependency package details.

```R
print(x, deps = FALSE, ...)
```

--------------------------------

### Use pkgcheck Github Action

Source: https://docs.ropensci.org/pkgcheck/reference/use_github_action_pkgcheck.html

Creates a Github workflow file to integrate `pkgcheck()` into your CI. This function generates a YAML file in the specified directory that defines the GitHub Actions workflow.

```APIDOC
## POST /github/workflows/pkgcheck

### Description
Creates a Github workflow file in `dir` to integrate `pkgcheck()` into your CI.

### Method
POST

### Endpoint
`/github/workflows/pkgcheck`

### Parameters
#### Query Parameters
- **dir** (string) - Optional - Directory the file is written to. Defaults to ".github/workflows".
- **overwrite** (boolean) - Optional - Overwrite existing file? Defaults to `FALSE`.
- **file_name** (string) - Optional - Name of the workflow file. Defaults to "pkgcheck.yaml".
- **branch** (string) - Optional - Name of git branch for checks to run; defaults to currently active branch.
- **inputs** (list) - Optional - Named list of inputs to the `ropensci-review-tools/pkgcheck-action`. See details below.

### Request Example
```json
{
  "dir": ".github/workflows",
  "overwrite": false,
  "file_name": "pkgcheck.yaml",
  "branch": "main",
  "inputs": {
    "post-to-issue": "false"
  }
}
```

### Response
#### Success Response (200)
- **path** (string) - The path to the new file, invisibly.

#### Response Example
```json
{
  "path": ".github/workflows/pkgcheck.yaml"
}
```

### Details
For more information on the action and advanced usage visit the action repository.

### Inputs
Inputs with description and default values. Pass all values as strings, see examples.

#### Request Body (for `inputs` parameter)
- **ref** (string) - The ref to checkout and check. Set to empty string to skip checkout. Default: `${{ github.ref }}`. Required: true.
- **post-to-issue** (boolean) - Should the pkgcheck results be posted as an issue? Default: `${{ github.event_name != 'pull_request' }}`. Required: true.
- **issue-title** (string) - Name for the issue containing the pkgcheck results. Will be created or updated. Default: "pkgcheck results - ${{ github.ref_name }}". Required: true.
- **summary-only** (boolean) - Only post the check summary to issue. Set to false to get the full results in the issue. Default: true. Required: true.
- **append-to-issue** (boolean) - Should issue results be appended to existing issue, or posted in new issues. Default: true. Required: true.
```

--------------------------------

### Run pkgcheck as a Blocking Process

Source: https://docs.ropensci.org/pkgcheck/reference/pkgcheck_bg.html

Executes package compliance checks as a foreground, blocking process. This function will not return until all checks are completed. It is suitable for simpler workflows where concurrent tasks are not required.

```R
checks <- pkgcheck ("/path/to/my/package")
```

--------------------------------

### Output Scrap File Check - pkgcheck

Source: https://docs.ropensci.org/pkgcheck/articles/extending-checks.html

Generates output for the scrap file check. It determines `check_pass` based on the absence of scrap files. If scrap files are present, it populates `summary` and `print` fields to indicate the presence of unexpected files and lists them.

```R
output_pkgchk_has_scrap <- function (checks) {

    out <- list (
        check_pass = length (checks$checks$has_scrap) == 0L,
        summary = "",
        print = ""
    )

    if (!out$check_pass) {
        out$summary <- "Package contains unexpected files."
        out$print <- list (
            msg_pre = paste0 (
                "Package contains the ",
                "following unexpected files:"
            ),
            obj = checks$checks$has_scrap,
            msg_post = character (0)
        )
    }

    return (out)
}
```

--------------------------------

### Register a new check in the print method

Source: https://docs.ropensci.org/pkgcheck/articles/extending-checks.html

Add this line to the print.pkgcheck method to ensure the new check is included in the output summary.

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

--------------------------------

### Render markdown to HTML usage

Source: https://docs.ropensci.org/pkgcheck/reference/render_md2html.html

Basic usage of the render_md2html function.

```R
render_md2html(md, open = TRUE)
```

--------------------------------

### List All Implemented Checks

Source: https://docs.ropensci.org/pkgcheck/reference/list_pkgchecks.html

This function lists all the checks that are currently implemented in the pkgcheck package.

```APIDOC
## GET /list_pkgchecks

### Description
Lists all checks currently implemented in the pkgcheck package.

### Method
GET

### Endpoint
/list_pkgchecks

### Parameters
#### Query Parameters
- **quiet** (boolean) - Optional - If TRUE, print all checks to screen. Function invisibly returns list of checks regardless.

### Response
#### Success Response (200)
- **checks** (character vector) - A character vector of names of all implemented checks.

### Request Example
```json
{
  "quiet": false
}
```

### Response Example
```json
{
  "checks": [
    "pkgchk_branch_is_master",
    "pkgchk_ci_badges",
    "pkgchk_fns_have_exs",
    "pkgchk_fns_have_return_vals",
    "pkgchk_has_bugs",
    "pkgchk_has_citation",
    "pkgchk_has_contrib_md",
    "pkgchk_has_scrap",
    "pkgchk_has_url",
    "pkgchk_has_vignette",
    "pkgchk_left_assign",
    "pkgchk_license",
    "pkgchk_lintr",
    "pkgchk_num_imports",
    "pkgchk_obsolete_pkg_deps",
    "pkgchk_on_cran",
    "pkgchk_pkgname_available",
    "pkgchk_renv_activated",
    "pkgchk_srr_okay",
    "pkgchk_unique_fn_names",
    "pkgchk_uses_dontrun",
    "pkgchk_uses_roxygen2"
  ]
}
```
```

--------------------------------

### Access background pkgcheck results

Source: https://docs.ropensci.org/pkgcheck/index.html

After running pkgcheck_bg(), use the returned handle's get_result() method to access the check results once the process has finished. Alternatively, call pkgcheck() to load cached results.

```R
result <- pkgcheck_bg()
# To check status:
print(result)
# To get results when finished:
result$get_result()
```

--------------------------------

### Run pkgcheck in Background

Source: https://docs.ropensci.org/pkgcheck/reference/pkgcheck_bg.html

Initiates package compliance checks as a background process. Use this when you need to perform other tasks while the checks are running. The function returns a processx object to manage the background task.

```R
ps <- pkgcheck_bg ("/path/to/my/package")
```

--------------------------------

### Main pkgcheck Functions

Source: https://docs.ropensci.org/pkgcheck/reference/index.html

Functions for generating reports on package compliance with rOpenSci Statistical Software requirements.

```APIDOC
## pkgcheck()

### Description
Generate report on package compliance with rOpenSci Statistical Software requirements.

### Method
Not applicable (R function)

### Endpoint
Not applicable (R function)

## pkgcheck_bg()

### Description
Generate report on package compliance with rOpenSci Statistical Software requirements as background process.

### Method
Not applicable (R function)

### Endpoint
Not applicable (R function)

## print(_<pkgcheck>_)

### Description
Generic print method for 'pkgcheck' objects.

### Method
Not applicable (R function)

### Endpoint
Not applicable (R function)
```

--------------------------------

### Generic Print Method for pkgcheck Objects

Source: https://docs.ropensci.org/pkgcheck/reference/print.pkgcheck.html

This section details the generic print method for objects of class 'pkgcheck'. It allows users to print the results of package checks, with an option to include dependency details.

```APIDOC
## S3 method for class 'pkgcheck'
print(x, deps = FALSE, ...)

### Description
Generic print method for 'pkgcheck' objects.

### Method
S3 method

### Parameters
#### Arguments
- **x** (A 'pkgcheck' object) - The object to be printed.
- **deps** (boolean) - Optional. If 'TRUE', include details of dependency packages and function usage.
- **...** (any) - Further arguments pass to or from other methods (not used here).

### Value
Nothing. Method called purely for side-effect of printing to screen.

### Examples
__```
if (FALSE) { # \dontrun{
checks <- pkgcheck ("/path/to/my/package")
print (checks) # print full checks, starting with summary
summary (checks) # print summary only
} # } 
```
```

--------------------------------

### Run pkgcheck in the background

Source: https://docs.ropensci.org/pkgcheck/index.html

Use pkgcheck_bg() to run checks in the background, allowing you to continue working. The function returns a handle to the background process.

```R
pkgcheck_bg()
```

--------------------------------

### Implement Citation Check Function

Source: https://docs.ropensci.org/pkgcheck/articles/extending-checks.html

A simple check function that verifies the existence of a CITATION file in the inst directory. It returns a logical value indicating presence.

```R
#' Check whether a package has a `inst/CITATION` file.
#'
#' "CITATION" files are required for all rOpenSci packages, as documented [in
#' our "*Packaging
#' Guide*](https://devguide.ropensci.org/pkg_building.html#citation-file). This
#' does not check the contents of that file in any way.
#'
#' @param checks A 'pkgcheck' object with full \pkg{pkgstats} summary and
#' \pkg{goodpractice} results.
#' @noRd
pkgchk_has_citation <- function (checks) {

    "CITATION" %in% list.files (fs::path (checks$pkg$path, "inst"))
}
```

--------------------------------

### Output Citation Check - pkgcheck

Source: https://docs.ropensci.org/pkgcheck/articles/extending-checks.html

Generates output for the citation file check. It sets `check_pass` based on the presence of a 'CITATION' file. The `summary` field is conditionally populated, and the `print` field is set to an empty string, meaning no detailed print output is generated for this check.

```R
output_pkgchk_has_citation <- function (checks) {

    out <- list (
        check_pass = checks$checks$has_citation,
        summary = "",
        print = ""
    )

    # disabled:
    # https://github.com/ropensci-review-tools/pkgcheck/issues/115
    # out$summary <- paste0 (
    #    ifelse (out$check_pass, "has", "does not have"),
    #    " a 'CITATION' file."
    # )

    return (out)
}
```

--------------------------------

### pkgcheck_bg

Source: https://docs.ropensci.org/pkgcheck/reference/pkgcheck_bg.html

Generates a report on package compliance with rOpenSci Statistical Software requirements as a background process.

```APIDOC
## pkgcheck_bg

### Description
Generate report on package compliance with rOpenSci Statistical Software requirements as background process.

### Usage
pkgcheck_bg(path)

### Arguments
- **path** (string) - Required - Path to local repository.

### Value
A processx object connecting to the background process generating the main pkgcheck results.

### Note
The return object will by default display whether it is still running, or whether it has finished. Once it has finished, the results can be obtained by calling `$get_result()`, or the main pkgcheck function can be called to quickly retrieve the main results from local cache. This function does not accept the `extra_env` parameter of the main pkgcheck function, and can not be used to run extra, locally-defined checks.

### Request Example
```r
ps <- pkgcheck_bg ("/path/to/my/package")
```

### Response Example
```r
# Returns a processx object
# Use ps$get_result() to obtain results once finished
```
```

--------------------------------

### Logfile Names API

Source: https://docs.ropensci.org/pkgcheck/reference/logfile_names.html

This API endpoint retrieves the local paths to stdout and stderr cache files for the r_bg process used by pkgcheck.

```APIDOC
## GET /logfile_names

### Description
Retrieves the local paths to stdout and stderr cache files for the r_bg process.

### Method
GET

### Endpoint
/logfile_names

### Parameters
#### Query Parameters
- **path** (string) - Required - Path to local repository

### Response
#### Success Response (200)
- **stdout_path** (string) - The local path to the stdout cache file.
- **stderr_path** (string) - The local path to the stderr cache file.

### Response Example
{
  "stdout_path": "/path/to/cache/stdout.log",
  "stderr_path": "/path/to/cache/stderr.log"
}
```

--------------------------------

### Set GitHub Token Environment Variable

Source: https://docs.ropensci.org/pkgcheck/index.html

Set the GITHUB_TOKEN environment variable for the GitHub GraphQL API. This can also be set permanently in ~/.Renviron.

```R
Sys.setenv ("GITHUB_TOKEN" = "<my_token>")
```

--------------------------------

### Generate a pkgcheck report

Source: https://docs.ropensci.org/pkgcheck/reference/pkgcheck.html

Executes the primary package compliance check. The function returns a pkgcheck object containing assessment results.

```R
pkgcheck(
  path = ".",
  goodpractice = TRUE,
  use_cache = TRUE,
  extra_env = .GlobalEnv
)
```

--------------------------------

### pkgcheck Function

Source: https://docs.ropensci.org/pkgcheck/reference/pkgcheck.html

Generates a report on package compliance with rOpenSci Statistical Software requirements.

```APIDOC
## pkgcheck

### Description
Generate report on package compliance with rOpenSci Statistical Software requirements.

### Method
`pkgcheck`

### Endpoint
N/A (R function)

### Parameters
#### Arguments
- **path** (string) - Path to local repository
- **goodpractice** (boolean) - If `FALSE`, skip most goodpractice checks except lintr and 'DESCRIPTION' checks. May be useful in development stages to more quickly check other aspects. Defaults to `TRUE`.
- **use_cache** (boolean) - Checks are cached for rapid retrieval, and only re-run if the git hash of the local repository changes. Setting `use_cache` to `FALSE` will force checks to be re-run even if the git hash has not changed. Defaults to `TRUE`.
- **extra_env** (environment) - Additional environments from which to collate checks. Other package names may be appended using `c`, as in `c(.GlobalEnv, "mypkg")`. Defaults to `.GlobalEnv`.

### Value
A `pkgcheck` object detailing all package assessments automatically applied to packages submitted for peer review.

### Examples
```R
if (FALSE) { # \dontrun{
checks <- pkgcheck ("/path/to/my/package") # default full check
summary (checks)
# Or to run only checks implemented in 'pkgcheck' and not the
# additional \pkg{goodpractice} checks:
checks <- pkgcheck ("/path/to/my/package", goodpractice = FALSE)
summary (checks)
} # }
```
```

--------------------------------

### Structure of a pkgcheck object

Source: https://docs.ropensci.org/pkgcheck/articles/extending-checks.html

This output represents the internal structure of a pkgcheck object generated from a skeleton package.

```text
#> List of 4
#>  $ pkg   :List of 8
#>   ..$ name        : chr "dummypkg"
#>   ..$ path        : chr "/tmp/RtmpkguwJc/dummypkg"
#>   ..$ version     : chr "0.0.0.9000"
#>   ..$ url         : chr(0) 
#>   ..$ BugReports  : chr(0) 
#>   ..$ license     : chr "GPL-3"
#>   ..$ summary     :List of 12
#>   .. ..$ num_authors         : int 1
#>   .. ..$ num_vignettes       : int 0
#>   .. ..$ num_data            : int 0
#>   .. ..$ imported_pkgs       : int 1
#>   .. ..$ num_exported_fns    : int 1
#>   .. ..$ num_non_exported_fns: int 2
#>   .. ..$ num_src_fns         : int 2
#>   .. ..$ loc_exported_fns    : int 3
#>   .. ..$ loc_non_exported_fns: int 3
#>   .. ..$ loc_src_fns         : int 5
#>   .. ..$ num_params_per_fn   : int 0
#>   .. ..$ languages           : chr [1:2] "C++: 72%" "R: 28%"
#>   ..$ dependencies:'data.frame': 4 obs. of  2 variables:
#>   .. ..$ type   : chr [1:4] "depends" "imports" "suggests" "linking_to"
#>   .. ..$ package: chr [1:4] "NA" "Rcpp" "testthat" "Rcpp"
#>  $ info  :List of 5
#>   ..$ git         : list()
#>   ..$ srr         :List of 5
#>   .. ..$ message     : chr [1:108] "This package still has TODO standards and can not be submitted" "Package can not be submitted because the following standards [v0.1.0] are missing from your code:" "" "G1.0" ...
#>   .. ..$ categories  : chr "Regression and Supervised Learning"
#>   .. ..$ missing_stds: chr "G1.0, G1.4a, G1.6, G2.0a, G2.1a, G2.2, G2.3a, G2.3b, G2.4, G2.4a, G2.4b, G2.4c, G2.4d, G2.4e, G2.5, G2.6, G2.7,"| __truncated__
#>   .. ..$ report_file : chr "/home/smexus/.cache/pkgcheck/static/dummypkg_srr2021-10-15-16:46:34.html"
#>   .. ..$ okay        : logi FALSE
#>   ..$ pkgstats    :'data.frame': 25 obs. of  4 variables:
#>   .. ..$ measure   : chr [1:25] "files_R" "files_src" "files_vignettes" "files_tests" ...
#>   .. ..$ value     : num [1:25] 4 2 0 2 10 26 6 0 3 1 ...
#>   .. ..$ percentile: num [1:25] 23.284 77.356 0 64.15 0.445 ...
#>   .. ..$ noteworthy: chr [1:25] "" "" "TRUE" "" ...
#>   .. ..- attr(*, "language")= chr [1:2] "C++: 72%" "R: 28%"
#>   .. ..- attr(*, "files")= chr [1:2] "C++: 2" "R: 4"
#>   ..$ network_file: chr "/home/smexus/.cache/pkgcheck/static/dummypkg_pkgstats.html"
#>   ..$ badges      : list()
#>  $ checks:List of 12
#>   ..$ fns_have_exs     : Named logi FALSE
#>   .. ..- attr(*, "names")= chr "test_fn.Rd"
#>   ..$ has_bugs         : logi FALSE
```

--------------------------------

### Usage of logfile_names

Source: https://docs.ropensci.org/pkgcheck/reference/logfile_names.html

Generates paths for stdout and stderr files for a background process.

```R
logfile_names(path)
```

--------------------------------

### Retrieve GitHub Token

Source: https://docs.ropensci.org/pkgcheck/reference/get_gh_token.html

Use this function to extract a GitHub access token from environment variables. An optional token name can be specified.

```R
get_gh_token(token_name = "")
```

```R
if (FALSE) { # \dontrun{
token <- get_gh_token ()
} # }
```

--------------------------------

### Render check results to markdown

Source: https://docs.ropensci.org/pkgcheck/index.html

The `checks_to_markdown()` function can render check results in markdown format, suitable for pasting into GitHub issues. Set `render = TRUE` to automatically open an HTML-formatted representation in a browser.

```R
write_clip(md)
```

--------------------------------

### render_md2html Function

Source: https://docs.ropensci.org/pkgcheck/reference/render_md2html.html

Renders markdown-formatted check results into HTML.

```APIDOC
## render_md2html

### Description

Render markdown-formatted input into 'html'.

### Method

`render_md2html(md, open = TRUE)`

### Parameters

#### Arguments

- **md** (character) - Result of checks_to_markdown function.
- **open** (logical) - If TRUE, open html-rendered version in web browser.

### Value

(invisible) Location of .html-formatted version of input.

### See also

Other extra: `checks_to_markdown()`, `fn_names_on_cran()`, `list_pkgchecks()`, `logfile_names()`

### Examples

```R
if (FALSE) { # \dontrun{
checks <- pkgcheck ("/path/to/my/package")
# Generate standard markdown-formatted character vector:
md <- checks_to_markdown (checks)

# Directly generate HTML output:
h <- checks_to_markdown (checks, render = TRUE) # HTML version

# Or convert markdown-formatted version to HTML:
h <- render_md2html (md)
} # }
```
```

--------------------------------

### Additional Functions

Source: https://docs.ropensci.org/pkgcheck/reference/index.html

Utility functions for converting checks to markdown, checking function names on CRAN, listing checks, managing log files, and rendering markdown to HTML.

```APIDOC
## checks_to_markdown()

### Description
Converts package checks into a markdown-formatted report.

### Method
Not applicable (R function)

### Endpoint
Not applicable (R function)

## fn_names_on_cran()

### Description
Checks if a given function name exists in any of the packages available on CRAN.

### Method
Not applicable (R function)

### Endpoint
Not applicable (R function)

## list_pkgchecks()

### Description
Lists all the checks currently implemented within the pkgcheck package.

### Method
Not applicable (R function)

### Endpoint
Not applicable (R function)

## logfile_names()

### Description
Sets up stdout and stderr cache files for `r_bg` processes.

### Method
Not applicable (R function)

### Endpoint
Not applicable (R function)

## render_md2html()

### Description
Renders markdown-formatted input into HTML.

### Method
Not applicable (R function)

### Endpoint
Not applicable (R function)
```

--------------------------------

### Convert checks to markdown-formatted report

Source: https://docs.ropensci.org/pkgcheck/reference/checks_to_markdown.html

This function converts the results of pkgcheck into a markdown-formatted report. It can also render the report as an HTML document.

```APIDOC
## checks_to_markdown

### Description
Convert checks to markdown-formatted report

### Usage
```R
checks_to_markdown(checks, render = FALSE)
```

### Arguments

*   **checks** (any) - Result of main pkgcheck function
*   **render** (logical) - If `TRUE`, render output as `html` document and open in browser.

### Value
Markdown-formatted version of check report

### See also
Other extra: `fn_names_on_cran()`, `list_pkgchecks()`, `logfile_names()`, `render_md2html()`

### Examples

```R
if (FALSE) { # \dontrun{
checks <- pkgcheck ("/path/to/my/package")
md <- checks_to_markdown (checks) # markdown-formatted character vector
md <- checks_to_markdown (checks, render = TRUE) # HTML version
} # }

```

--------------------------------

### Usage of checks_to_markdown

Source: https://docs.ropensci.org/pkgcheck/reference/checks_to_markdown.html

Basic function signature for converting check results.

```R
checks_to_markdown(checks, render = FALSE)
```

--------------------------------

### GitHub-related Functions

Source: https://docs.ropensci.org/pkgcheck/reference/index.html

Functions for interacting with GitHub, such as retrieving default branches, tokens, and commit information.

```APIDOC
## get_default_github_branch()

### Description
Retrieves the default branch of a GitHub repository.

### Method
Not applicable (R function)

### Endpoint
Not applicable (R function)

## get_gh_token()

### Description
Retrieves the GitHub token for authentication.

### Method
Not applicable (R function)

### Endpoint
Not applicable (R function)

## get_latest_commit()

### Description
Retrieves the latest commit information from a GitHub repository.

### Method
Not applicable (R function)

### Endpoint
Not applicable (R function)

## use_github_action_pkgcheck()

### Description
Sets up the pkgcheck GitHub Action for a repository.

### Method
Not applicable (R function)

### Endpoint
Not applicable (R function)
```

--------------------------------

### Usage of get_latest_commit

Source: https://docs.ropensci.org/pkgcheck/reference/get_latest_commit.html

Defines the function signature for retrieving the latest commit from a GitHub repository.

```R
get_latest_commit(org, repo, branch = NULL)
```

--------------------------------

### Check CRAN function names usage

Source: https://docs.ropensci.org/pkgcheck/reference/fn_names_on_cran.html

Use this function to identify if a function name is present in other CRAN packages. The force_update parameter can be used to refresh the local cache of CRAN function names.

```R
fn_names_on_cran(fn_name, force_update = FALSE)
```

```R
fn_names_on_cran (c ("min", "max"))
#>       package version fn_name
#> 1    matlab2r   1.5.0     max
#> 2    matlab2r   1.5.0     min
#> 3      mosaic   1.9.2     max
#> 4      mosaic   1.9.2     min
#> 5 rapportools     1.2     max
#> 6 rapportools     1.2     min
#> 7      tidyna   0.4.0     max
#> 8      tidyna   0.4.0     min
```

--------------------------------

### Check Function Name Existence on CRAN

Source: https://docs.ropensci.org/pkgcheck/reference/fn_names_on_cran.html

This endpoint checks if a given function name exists in any of the packages available on CRAN. It can also update the local cache of CRAN package function names.

```APIDOC
## POST /api/check-unique-fn-names

### Description
Check whether a function name exists in any CRAN packages.

### Method
POST

### Endpoint
/api/check-unique-fn-names

### Parameters
#### Request Body
- **fn_name** (string array) - Required - A character vector of one or more function names to check.
- **force_update** (boolean) - Optional - If TRUE, locally-cached data of all function names from all CRAN packages will be updated to the latest version.

### Request Example
```json
{
  "fn_name": ["min", "max"],
  "force_update": false
}
```

### Response
#### Success Response (200)
- **package** (string) - The name of the package where the function was found.
- **version** (string) - The version of the package.
- **fn_name** (string) - The name of the function.

#### Response Example
```json
{
  "package": "matlab2r",
  "version": "1.5.0",
  "fn_name": "max"
}
```
```

--------------------------------

### Check if function names are on CRAN

Source: https://docs.ropensci.org/pkgcheck/index.html

Use `fn_names_on_cran` to check if proposed function names are already in use on CRAN. This helps avoid namespace conflicts before committing new functions.

```R
fn_names_on_cran (c ("min", "max"))
```

--------------------------------

### Define custom check output types

Source: https://docs.ropensci.org/pkgcheck/articles/extending-checks.html

Set the check_type attribute to control whether checks use default symbols or the watch symbol (👀).

```R
out$check_type <- "pass_watch"
```

```R
out$check_type <- "none_watch"
```

```R
out$check_type <- "watch_none"
```
Tokens:
Raw