feat: NACHO 3.0.0

.Rbuildignore

@@ -12,6 +12,12 @@
 ^CRAN-SUBMISSION$
 ^revdep$
 ^README\.Rmd$
-^man/figures/README-nacho_app\.gif$
+^man/figures/README-.*\.gif$
 ^LICENSE\.md$
 ^data-raw$
+^vignettes/articles$
+^\.superpowers$
+^\.kata\.toml$
+^\.ruff_cache$
+^\.roborev$
+\.DS_Store$

.github/ISSUE_TEMPLATE/bug.yml

@@ -40,7 +40,7 @@ body:
         - Data import (`load_rcc()`)
         - Normalisation (`normalise()`)
         - Plots (`autoplot()`)
-        - Outliers (`check_outliers()`)
+        - Quality control (`nacho_qc()`)
         - Report (`render()`)
         - Deployment (`deploy()`)
         - Other

.github/RELEASING.md

@@ -14,14 +14,20 @@ The checks still run on `main`, and the submission workflow checks the tarball a
 Tick "rhub" to run the R-hub checks as well.
 They're optional, and `cran-comments.md` only lists them when they run.
 
-Untick "auto-merge" when `cran-comments.md` needs a note, for example to explain breaking changes.
+Untick "auto-merge" when `cran-comments.md` needs a note, for example to explain breaking changes or a NOTE you expect from the check.
 The pull request is then assigned to you: edit the file on it and merge it yourself.
 
 ## 2. Submit to CRAN
 
 Merging the bump starts the "CRAN submission" workflow.
 It builds the tarball with the PDF manual and runs `R CMD check --as-cran`.
 
+The workflow then compares the check with the results line of `cran-comments.md`, for example `0 errors | 0 warnings | 1 note`.
+It stops before the upload only if `cran-comments.md` reports fewer errors, warnings or notes than the check found.
+A file that reports more problems than the check found passes.
+The check step before it already stops on any WARNING or ERROR, so the workflow lists only the NOTE sections that the file must explain.
+Open a pull request that explains each NOTE in `cran-comments.md` and corrects the results line, merge it, then run "CRAN submission" by hand from `main` with "dry run" unticked.
+
 It then waits for your approval on the `cran` environment.
 Approve it, and the workflow uploads the tarball and records the submission in `CRAN-SUBMISSION` on `main`.
 CRAN then emails the maintainer, and the submission only counts once you click the link in that email.
@@ -50,10 +56,13 @@ Once CRAN's acceptance email arrives, run the "CRAN post-release" workflow from
 
 It checks that CRAN serves the version, tags `vX.Y.Z` on the submitted commit, and publishes the "NACHO X.Y.Z" release with the notes from `NEWS.md`.
 The release deploys the pkgdown site.
+A draft release `vX.Y.Z` stops the run, so publish or delete it before you run the workflow again.
 It then opens a pull request that starts the next development version and removes `CRAN-SUBMISSION`.
 
 If CRAN doesn't serve the version yet, the workflow stops without changing anything, and you can run it again later.
 
+If a run stops after it published the release, run it again: it keeps the existing release when its tag points to the submitted commit, and goes on to the development version.
+
 ## Scripts and tests
 
 The workflows call the scripts in `.github/scripts/`.

.github/scripts/check-results.sh

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Compare the Status line of an R CMD check log with the results line of
+# cran-comments.md, so the file sent to CRAN never reports fewer problems
+# than the check found.
+# Usage: check-results.sh <00check.log> [cran-comments.md]
+
+log="${1:?Usage: check-results.sh <00check.log> [cran-comments.md]}"
+comments="${2:-cran-comments.md}"
+
+for file in "${log}" "${comments}"; do
+  if [ ! -f "${file}" ]; then
+    echo "::error::${file} does not exist." >&2
+    exit 1
+  fi
+done
+
+status="$(tr -d '\r' <"${log}" | sed -n 's/^Status:[[:space:]]*//p' | tail -n 1)"
+if [ -z "${status}" ]; then
+  echo "::error::${log} has no Status line, so the check did not finish." >&2
+  exit 1
+fi
+
+count() {
+  local n
+  n="$(grep -oE "[0-9]+ $1" <<<"${status}" | grep -oE '^[0-9]+' || true)"
+  echo "${n:-0}"
+}
+
+found="$(count ERROR) $(count WARNING) $(count NOTE)"
+claimed="$(tr -d '\r' <"${comments}" |
+  sed -nE 's/^([0-9]+) errors? \| ([0-9]+) warnings? \| ([0-9]+) notes?[[:space:]]*$/\1 \2 \3/p' |
+  head -n 1)"
+
+if [ -z "${claimed}" ]; then
+  echo "::error::${comments} has no line like '0 errors | 0 warnings | 0 notes'." >&2
+  exit 1
+fi
+
+read -r errors warnings notes <<<"${found}"
+read -r claimed_errors claimed_warnings claimed_notes <<<"${claimed}"
+summary="${errors} errors | ${warnings} warnings | ${notes} notes"
+claimed_summary="${claimed_errors} errors | ${claimed_warnings} warnings | ${claimed_notes} notes"
+if [ "${claimed_errors}" -lt "${errors}" ] ||
+  [ "${claimed_warnings}" -lt "${warnings}" ] ||
+  [ "${claimed_notes}" -lt "${notes}" ]; then
+  {
+    echo "::error::${comments} reports fewer problems than the check found. The check found ${summary}, but ${comments} says ${claimed_summary}. Explain each problem in ${comments}, correct its results line, and run the CRAN submission again."
+    tr -d '\r' <"${log}" | grep -E '\.\.\. .*(NOTE|WARNING|ERROR)$' || true
+  } >&2
+  exit 1
+fi
+
+echo "${comments} reports at least what the check found: check ${summary}, ${comments} ${claimed_summary}"

.github/scripts/release-guard.sh

@@ -2,7 +2,14 @@
 set -euo pipefail
 
 dir="${1:-.}"
-version="$(sed -n 's/^Version:[[:space:]]*//p' "${dir}/DESCRIPTION" 2>/dev/null || true)"
+
+field_value() {
+  sed -n "s/^$1:[[:space:]]*//p" "$2" 2>/dev/null |
+    tr -d '\r' |
+    sed 's/[[:space:]]*$//'
+}
+
+version="$(field_value Version "${dir}/DESCRIPTION" || true)"
 
 if [ -z "${version}" ]; then
   echo "::error::No Version field in ${dir}/DESCRIPTION." >&2
@@ -26,10 +33,10 @@ fi
 
 recorded_versions() {
   if [ -f "${dir}/CRAN-SUBMISSION" ]; then
-    sed -n 's/^Version:[[:space:]]*//p' "${dir}/CRAN-SUBMISSION"
+    field_value Version "${dir}/CRAN-SUBMISSION"
   fi
   git -C "${dir}" show origin/main:CRAN-SUBMISSION 2>/dev/null |
-    sed -n 's/^Version:[[:space:]]*//p' || true
+    field_value Version /dev/stdin || true
 }
 
 if grep -Fxq "${version}" <<<"$(recorded_versions)"; then

.github/scripts/release-tag.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Tell whether the tag v<version> exists, and stop when it points to another
+# commit than the one submitted to CRAN.
+# Usage: release-tag.sh <version> <sha> [dir]
+
+version="${1:-}"
+sha="${2:-}"
+dir="${3:-.}"
+
+if [ -z "${version}" ] || [ -z "${sha}" ]; then
+  echo "::error::Usage: release-tag.sh <version> <sha> [dir]" >&2
+  exit 1
+fi
+
+tagged="$(git -C "${dir}" rev-parse -q --verify "refs/tags/v${version}^{commit}" || true)"
+if [ -z "${tagged}" ]; then
+  echo "tagged=false"
+  exit 0
+fi
+
+submitted="$(git -C "${dir}" rev-parse --verify "${sha}^{commit}")"
+if [ "${tagged}" != "${submitted}" ]; then
+  echo "::error::v${version} points to ${tagged}, not to the submitted commit ${submitted}. Check the tag by hand before you run this again." >&2
+  exit 1
+fi
+
+echo "tagged=true"

.github/scripts/tests/test-release-scripts.sh

@@ -65,6 +65,32 @@ out="$("${scripts}/release-guard.sh" "${tmp}/rerun")"
 check "guard skips a version recorded on origin/main" false \
   "$(field submit <<<"${out}")"
 
+make_repo "${tmp}/crlf" 2.0.7
+printf 'Package: NACHO\r\nVersion: 2.0.7 \r\n' >"${tmp}/crlf/DESCRIPTION"
+out="$("${scripts}/release-guard.sh" "${tmp}/crlf")"
+check "guard reads a version with CRLF line ends" 2.0.7 \
+  "$(field version <<<"${out}")"
+check "guard submits a CRLF release version" true \
+  "$(field submit <<<"${out}")"
+
+printf 'Version: 2.0.7\r\nDate: 2026-10-01 10:00:00 UTC\r\nSHA: abc\r\n' \
+  >"${tmp}/crlf/CRAN-SUBMISSION"
+out="$("${scripts}/release-guard.sh" "${tmp}/crlf")"
+check "guard skips a CRLF submission record" false \
+  "$(field submit <<<"${out}")"
+
+make_repo "${tmp}/upstream-crlf" 2.0.7
+git clone -q "${tmp}/upstream-crlf" "${tmp}/rerun-crlf"
+printf 'Version: 2.0.7\r\nDate: 2026-10-01 10:00:00 UTC\r\nSHA: abc\r\n' \
+  >"${tmp}/upstream-crlf/CRAN-SUBMISSION"
+git -C "${tmp}/upstream-crlf" add CRAN-SUBMISSION
+git -C "${tmp}/upstream-crlf" -c user.name=test -c user.email=test@example.com \
+  -c commit.gpgsign=false commit -q -m record
+git -C "${tmp}/rerun-crlf" fetch -q origin
+out="$("${scripts}/release-guard.sh" "${tmp}/rerun-crlf")"
+check "guard skips a CRLF version recorded on origin/main" false \
+  "$(field submit <<<"${out}")"
+
 mkdir -p "${tmp}/empty"
 check "guard fails without a version" 1 \
   "$(status_of "${scripts}/release-guard.sh" "${tmp}/empty")"
@@ -188,6 +214,56 @@ check "bump rejects a malformed version" 1 \
 check "bump fails without DESCRIPTION" 1 \
   "$(status_of "${scripts}/bump-version.sh" patch "${tmp}/missing")"
 
+printf '* checking CRAN incoming feasibility ... NOTE\nMaintainer: x\n* DONE\n\nStatus: 2 NOTEs\n' \
+  >"${tmp}/check-notes.log"
+printf '* DONE\n\nStatus: OK\n' >"${tmp}/check-ok.log"
+printf '* DONE\n\nStatus: 1 WARNING, 1 NOTE\n' >"${tmp}/check-warn.log"
+printf '## R CMD check results\n\n0 errors | 0 warnings | 0 notes\n' \
+  >"${tmp}/comments-clean.md"
+printf '## R CMD check results\n\n0 errors | 0 warnings | 2 notes\n\n- NOTE one.\n' \
+  >"${tmp}/comments-notes.md"
+printf '## R CMD check results\r\n\r\n0 errors | 0 warnings | 0 notes\r\n' \
+  >"${tmp}/comments-crlf.md"
+printf '## R CMD check results\n' >"${tmp}/comments-none.md"
+
+check "results match a clean check" 0 \
+  "$(status_of "${scripts}/check-results.sh" "${tmp}/check-ok.log" "${tmp}/comments-clean.md")"
+check "results match a CRLF cran-comments.md" 0 \
+  "$(status_of "${scripts}/check-results.sh" "${tmp}/check-ok.log" "${tmp}/comments-crlf.md")"
+check "results stop on notes cran-comments.md leaves out" 1 \
+  "$(status_of "${scripts}/check-results.sh" "${tmp}/check-notes.log" "${tmp}/comments-clean.md")"
+check "results match notes cran-comments.md explains" 0 \
+  "$(status_of "${scripts}/check-results.sh" "${tmp}/check-notes.log" "${tmp}/comments-notes.md")"
+printf '## R CMD check results\n\n0 errors | 0 warnings | 1 note\n\n- NOTE one.\n' \
+  >"${tmp}/comments-one-note.md"
+check "results accept a note cran-comments.md explains but the check did not find" 0 \
+  "$(status_of "${scripts}/check-results.sh" "${tmp}/check-ok.log" "${tmp}/comments-one-note.md")"
+check "results stop on a warning" 1 \
+  "$(status_of "${scripts}/check-results.sh" "${tmp}/check-warn.log" "${tmp}/comments-notes.md")"
+check "results stop without a results line" 1 \
+  "$(status_of "${scripts}/check-results.sh" "${tmp}/check-ok.log" "${tmp}/comments-none.md")"
+check "results stop without a check log" 1 \
+  "$(status_of "${scripts}/check-results.sh" "${tmp}/missing.log" "${tmp}/comments-clean.md")"
+out="$("${scripts}/check-results.sh" "${tmp}/check-notes.log" "${tmp}/comments-clean.md" 2>&1 || true)"
+check "results name the NOTE section" 1 \
+  "$(grep -c 'checking CRAN incoming feasibility' <<<"${out}")"
+
+make_repo "${tmp}/tag" 2.0.7
+first="$(git -C "${tmp}/tag" rev-parse HEAD)"
+out="$("${scripts}/release-tag.sh" 2.0.7 "${first}" "${tmp}/tag")"
+check "tag check reports a missing tag" false "$(field tagged <<<"${out}")"
+git -C "${tmp}/tag" -c tag.gpgSign=false tag v2.0.7
+out="$("${scripts}/release-tag.sh" 2.0.7 "${first}" "${tmp}/tag")"
+check "tag check accepts a tag on the submitted commit" true \
+  "$(field tagged <<<"${out}")"
+git -C "${tmp}/tag" -c user.name=test -c user.email=test@example.com \
+  -c commit.gpgsign=false commit -q --allow-empty -m later
+second="$(git -C "${tmp}/tag" rev-parse HEAD)"
+check "tag check stops on a tag on another commit" 1 \
+  "$(status_of "${scripts}/release-tag.sh" 2.0.7 "${second}" "${tmp}/tag")"
+check "tag check fails without a version" 1 \
+  "$(status_of "${scripts}/release-tag.sh" "" "${first}" "${tmp}/tag")"
+
 if [ "${failures}" -gt 0 ]; then
   printf '%s check(s) failed\n' "${failures}"
   exit 1

.github/workflows/R-CMD-check.yml

@@ -38,12 +38,17 @@ jobs:
     env:
       GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
       R_KEEP_PKG_SOURCE: yes
+      NACHO_REQUIRE_QUARTO: "true"
 
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - uses: r-lib/actions/setup-pandoc@f9a764fea8d5c63df6ef9a5c7795bf7deb5d7e05 # v2.14.0
 
+      - uses: quarto-dev/quarto-actions/setup@8a96df13519ee81fd526f2dfca5962811136661b # v2.2.0
+        with:
+          version: release
+
       - uses: r-lib/actions/setup-r@f9a764fea8d5c63df6ef9a5c7795bf7deb5d7e05 # v2.14.0
         with:
           r-version: ${{ matrix.config.r }}
@@ -55,11 +60,33 @@ jobs:
           extra-packages: any::rcmdcheck
           needs: check
 
+      - name: Install HTML Tidy
+        if: runner.os == 'Linux'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y tidy
+
       - uses: r-lib/actions/check-r-package@f9a764fea8d5c63df6ef9a5c7795bf7deb5d7e05 # v2.14.0
         with:
           upload-snapshots: true
           build_args: 'c("--no-manual","--compact-vignettes=gs+qpdf")'
 
+      - name: Check the tarball stays under 5 MB
+        if: runner.os == 'Linux' && matrix.config.r == 'release'
+        run: |
+          set -euo pipefail
+          tarball=$(find check -maxdepth 1 -name 'NACHO_*.tar.gz' -print -quit)
+          if [ -z "$tarball" ]; then
+            echo "::error::No NACHO tarball in check/; the check-r-package step must have changed where it builds."
+            exit 1
+          fi
+          size=$(stat -c %s "$tarball")
+          echo "Tarball size: ${size} bytes"
+          if [ "$size" -ge 5000000 ]; then
+            echo "::error::${tarball} is ${size} bytes, over the 5 MB CRAN guidance."
+            exit 1
+          fi
+
   test-coverage:
     needs: r-cmd-check
     runs-on: ubuntu-latest

.github/workflows/cran-post-release.yml

@@ -58,14 +58,23 @@ jobs:
           VERSION: ${{ steps.accepted.outputs.version }}
           SHA: ${{ steps.accepted.outputs.sha }}
         run: |
+          TAG_OUTPUT="$(.github/scripts/release-tag.sh "${VERSION}" "${SHA}")"
           if gh release view "v${VERSION}" > /dev/null 2>&1; then
-            echo "::error::The release v${VERSION} already exists."
-            exit 1
+            if [ "$(gh release view "v${VERSION}" --json isDraft --jq .isDraft)" = "true" ]; then
+              echo "::error::The release v${VERSION} is a draft. Publish or delete it, then run this again."
+              exit 1
+            fi
+            if grep -Fxq "tagged=false" <<<"${TAG_OUTPUT}"; then
+              echo "::error::The release v${VERSION} exists without its tag. Delete the release, then run this again."
+              exit 1
+            fi
+            echo "The release v${VERSION} already exists on ${SHA}; going on to the development version."
+          else
+            gh release create "v${VERSION}" \
+              --target "${SHA}" \
+              --title "NACHO ${VERSION}" \
+              --notes-file "${RUNNER_TEMP}/release-notes.md"
           fi
-          gh release create "v${VERSION}" \
-            --target "${SHA}" \
-            --title "NACHO ${VERSION}" \
-            --notes-file "${RUNNER_TEMP}/release-notes.md"
 
       - name: Start the next development version
         id: dev
@@ -76,6 +85,10 @@ jobs:
           BRANCH="ci/dev-version-${VERSION//./-}"
           .github/scripts/bump-version.sh dev
           git rm -q CRAN-SUBMISSION
+          if git ls-remote --exit-code --heads origin "${BRANCH}" > /dev/null 2>&1; then
+            echo "::error::${BRANCH} already exists. Merge or close its pull request, delete the branch, then run this again."
+            exit 1
+          fi
           git switch -c "${BRANCH}"
           git add DESCRIPTION NEWS.md
           git commit -m "chore: start development after NACHO ${VERSION}"

.github/workflows/cran-submit.yml

@@ -92,12 +92,20 @@ jobs:
           mkdir -p cran
           Rscript -e 'path <- pkgbuild::build(".", dest_path = "cran", manual = TRUE); cat("tarball=", path, "\n", sep = "", file = Sys.getenv("GITHUB_OUTPUT"), append = TRUE)'
 
+      - name: Install HTML Tidy
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y tidy
+
       - name: Run R CMD check --as-cran
         env:
           TARBALL: ${{ steps.build.outputs.tarball }}
         run: |
           Rscript -e 'rcmdcheck::rcmdcheck(Sys.getenv("TARBALL"), args = "--as-cran", error_on = "warning", check_dir = "check")'
 
+      - name: Compare the check with cran-comments.md
+        run: .github/scripts/check-results.sh check/NACHO.Rcheck/00check.log cran-comments.md
+
       - name: Upload the tarball
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with: