cran-audit

name	cran-audit
description	Audit an R package against CRAN Repository Policy and submission requirements. Produces a gap report with Critical (must fix), Warnings (should fix), and pass/fail assessment per requirement type. Offers automated fixes where possible.

CRAN Submission Audit

Audit an R package against CRAN Repository Policy requirements and produce a structured gap report. This skill evaluates package structure, DESCRIPTION metadata, documentation, code quality, and test coverage against the full CRAN checklist.

Workflow

1. Locate the Package

Identify the R package to audit. Look for DESCRIPTION file in the current working directory or a specified path. If no R package is found, ask the user which package to audit.

1b. Load User Config

Read .claude/pub-pipeline.local.md if it exists (Read tool). Extract author metadata and package context from YAML frontmatter. If the file is missing, inform the user and offer to create one from the template at ${CLAUDE_PLUGIN_ROOT}/docs/user-config-template.md.

1c. Verify Dependency Availability

Before running the full audit, check that all dependencies are available on CRAN (Bash tool):

1. Parse Imports, Depends, and LinkingTo fields from DESCRIPTION
2. For each dependency that is not a base or recommended package, verify it exists on CRAN:

Rscript -e 'ap <- available.packages(); cat("PKG_NAME" %in% rownames(ap))'

3. For dependencies with version requirements (e.g., pkg (>= 2.0)), verify the requirement is satisfiable:

Rscript -e 'ap <- available.packages(); cat(ap["PKG_NAME", "Version"])'

Compare the available version against the minimum required version.

If any dependency is not on CRAN, flag it as a hard blocker in the gap report and stop here — the package cannot pass R CMD check --as-cran until all dependencies are available. Recommend the user publish the missing dependency first or switch to a CRAN-available alternative.

2. Gather Package State

Run these checks in parallel where possible:

Regenerate documentation (Bash tool): Run Rscript -e 'devtools::document()' to ensure NAMESPACE and man/ files are current before auditing them. This prevents false negatives from stale roxygen output.

Package metadata (Read tool):

• Read DESCRIPTION — check all required fields
• Read NAMESPACE — verify auto-generation by roxygen2
• Read LICENSE or LICENSE.md — verify OSI-approved license
• Check for NEWS.md, cran-comments.md, README.md

Code quality (Grep/Glob tools):

• Search for q() calls in R code
• Search for .Internal(), ::: accessing base internals
• Search for writes outside tempdir() / tools::R_user_dir()
• Check that Suggested packages are used conditionally (if (requireNamespace(...)))
• Verify no binary executables in source
• Search for options() or par() calls that don't restore state via on.exit() or withr
• Run urlchecker::url_check() to verify all URLs are valid and HTTPS

Documentation (Grep/Glob tools):

• Check all exported functions have @returns roxygen tag
• Check all exported functions have @examples roxygen tag
• Verify man/ directory exists with .Rd files

R CMD check (Bash tool):

cd /path/to/package && Rscript -e 'devtools::check(args = "--as-cran")'

Test coverage (Bash tool):

cd /path/to/package && Rscript -e 'covr::package_coverage()'

3. Evaluate Against Checklist

Score each item from the CRAN checklist as PASS, FAIL, or WARN. Consult the full checklist in ${CLAUDE_PLUGIN_ROOT}/docs/cran-reference.md for detailed requirements.

Key categories to evaluate:

Category	Key Checks
DESCRIPTION	Title case, no period, informative Description, Authors@R with roles, valid License
Dependencies	Imports from CRAN/Bioconductor only, conditional Suggests usage
Code behavior	No q(), no .Internal, no writing outside tempdir, no global env modification
Documentation	All exports have @returns and @examples, vignettes build
Examples	\dontrun{} only for truly non-runnable code; prefer \donttest{} for slow examples
Side effects	options()/par() restored via on.exit() or withr; no persistent state changes
Size	Tarball <10MB, data+docs <5MB, examples run in seconds
Cross-platform	Portable code, no OS-specific assumptions
Testing	R CMD check clean (0E/0W), notes explained
URLs	All URLs valid and using HTTPS

4. Produce Gap Report

Format the report as:

# CRAN Audit Report: {package name} v{version}

## Summary
- **Status**: READY / NEEDS WORK / NOT READY
- **Score**: X/Y checks passed
- **Blockers**: N critical issues

## Critical (Must Fix)
1. [Issue description] — [file:line] — [how to fix]

## Warnings (Should Fix)
1. [Issue description] — [file:line] — [recommendation]

## Passed
- [Check name] ✓

## R CMD Check Results
[Paste relevant output]

## Recommended Next Steps
1. [Ordered list of actions]

5. Offer to Fix

After presenting the report, offer to fix issues that can be automated:

• Add missing @returns tags
• Add cran-comments.md if missing
• Fix Title/Description formatting
• Add conditional requireNamespace() checks
• Create NEWS.md if missing
• Replace \dontrun{} with \donttest{} where appropriate

Reference Files

For the complete CRAN policy checklist and submission workflow, consult:

• ${CLAUDE_PLUGIN_ROOT}/docs/cran-reference.md — Full CRAN Repository Policy reference with pre-submission checklist, submission workflow, and common rejection reasons

Important Notes

• NAMESPACE is auto-generated by roxygen2 — never edit manually. Run devtools::document() after any roxygen changes.
• R CMD check --as-cran is the gold standard. If it passes with 0E/0W/0N, the package is very likely to be accepted.
• First-time submissions face heightened scrutiny. The Description field is especially important.
• CRAN reviewers are volunteers. Respect their time by fixing all automated issues before submission.