cran-audit

name	cran-audit
description	This skill should be used when the user asks to "audit for CRAN", "check CRAN readiness", "prepare for CRAN submission", "CRAN check", "is my package CRAN ready", "submit to CRAN", or mentions CRAN submission compliance. It audits an R package against CRAN Repository Policy and submission requirements, producing a structured gap report with actionable fixes.

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.

2. Gather Package State

Run these checks in parallel where possible:

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.