joss-audit

JOSS Submission Audit

Evaluate an R package against the complete JOSS reviewer checklist and produce a structured gap report. This covers software quality, documentation, development history, and paper.md format compliance.

Workflow

1. Locate the Package and Paper

Identify the R package root (look for DESCRIPTION). Then search for paper.md — check root, paper/, joss/, and inst/paper/. If no paper.md exists, note this as a critical gap.

1b. Load User Config

Read .claude/pub-pipeline.local.md if it exists (Read tool). Extract author metadata (ORCID, affiliation) 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. Check Software Requirements

License (Read tool):

• Verify a plain-text LICENSE or LICENSE.md file exists
• Confirm it's an OSI-approved license (MIT, GPL-2, GPL-3, Apache-2.0, BSD, etc.)

Repository quality (Bash tool):

# Development history: 6+ months of commits
git log --oneline --since="6 months ago" | wc -l

# Multiple contributors
git shortlog -sn --all | head -10

# Issues/PRs activity
gh issue list --state all --limit 5
gh pr list --state all --limit 5

# Tags/releases
git tag -l | tail -5

Documentation (Glob/Read tools):

• README.md exists with installation instructions
• Usage examples present (in README, vignettes, or both)
• API documentation exists (man/ directory with .Rd files)
• Contributing guidelines (CONTRIBUTING.md or in README)
• Issue reporting instructions

Testing (Bash/Glob tools):

• Test directory exists (tests/testthat/ or tests/)
• Tests actually run: Rscript -e 'devtools::test()'
• Coverage check: Rscript -e 'covr::package_coverage()'

Installation (Bash tool):

• Verify package installs cleanly: Rscript -e 'devtools::install()'

3. Check Paper Format

If paper.md exists, validate against JOSS format requirements.