cran-audit

What this skill does

# 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:
```bash
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:
```bash
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):
```bash
cd /path/to/package && Rscript -e 'devtools::check(args = "--as-cran")'
```

**Test coverage** (Bash tool):
```bash
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:

```markdown
# 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.