add a validation re. the GitHub issue in the register and fix some test failures, add quick start

Author: nuest

.claude/settings.local.json

@@ -29,7 +29,9 @@
       "Bash(do echo \"=== $file ===\")",
       "Bash(done)",
       "Bash(1)",
-      "Bash(tee:*)"
+      "Bash(tee:*)",
+      "Bash(xelatex:*)",
+      "Bash(echo:*)"
     ],
     "deny": [],
     "ask": []

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

@@ -28,6 +28,7 @@ jobs:
     env:
       R_REMOTES_NO_ERRORS_FROM_WARNINGS: true
       RSPM: ${{ matrix.config.rspm }}
+      GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
 
     steps:
       - uses: actions/checkout@v4

CLAUDE.md

@@ -80,6 +80,7 @@ When bumping the version in `DESCRIPTION`, add a new section to `NEWS.md` with t
 - `validate_codecheck_yml_crossref()` - Validates paper metadata against CrossRef API; compares title and author information with CrossRef data
 - `validate_codecheck_yml_orcid()` - Validates author and codechecker names against ORCID API; queries ORCID records using rorcid package; compares names in ORCID records with local metadata; requires ORCID authentication by default (set `skip_on_auth_error = TRUE` to skip validation when authentication is unavailable)
 - `validate_contents_references()` - Comprehensive validation wrapper; runs both CrossRef and ORCID validations; provides unified summary; supports strict mode for certificate rendering; requires ORCID authentication by default (users can opt-in to skipping via `skip_on_auth_error = TRUE`)
+- `validate_certificate_github_issue()` - Validates certificate identifier exists in GitHub register issues; checks issue state (warns if closed) and assignment (warns if unassigned); stops with error if no matching issue found; supports strict mode where warnings become errors; automatically skips validation for placeholder certificates (R/validation.R:1204)
 
 **Zenodo integration**: Functions for uploading certificates to Zenodo:
 

NAMESPACE

@@ -27,6 +27,7 @@ export(update_codecheck_yml_from_lifecycle)
 export(upload_zenodo_certificate)
 export(upload_zenodo_metadata)
 export(validate_certificate_for_rendering)
+export(validate_certificate_github_issue)
 export(validate_codecheck_yml)
 export(validate_codecheck_yml_crossref)
 export(validate_codecheck_yml_orcid)

NEWS.md

@@ -1,5 +1,15 @@
 # codecheck (development version)
 
+## GitHub Issue Validation
+
+* **New validation function**: Added `validate_certificate_github_issue()` to verify that certificate identifiers exist in the codecheckers/register GitHub repository
+* **Issue state checking**: Warns if the certificate's GitHub issue is closed (indicating the CODECHECK is already complete and published)
+* **Assignment validation**: Warns if the certificate's GitHub issue is unassigned (no codechecker assigned yet)
+* **Strict mode**: Optional strict mode (`strict = TRUE`) treats warnings as errors, stopping certificate processing if issues are found
+* **Placeholder handling**: Automatically skips validation for placeholder certificate identifiers
+* **Comprehensive error handling**: Provides clear error messages for missing issues, API rate limits, and authentication problems
+* **GitHub Actions integration**: Updated R-CMD-check workflow to include GITHUB_PAT token for API access during testing
+
 ## ORCID Validation Improvements
 
 * **Graceful authentication handling**: ORCID validation functions now handle authentication failures gracefully with clear error messages instead of requiring interactive login

R/latex.R

@@ -185,14 +185,11 @@ cite_certificate <- function(metadata) {
 ##' @return NULL (outputs directly via cat() for knitr/rmarkdown)
 ##' @keywords internal
 render_error_box <- function(filename, error_msg) {
-  cat("\\begin{center}\n")
-  cat("\\fcolorbox{red}{yellow!20}{\\parbox{0.9\\textwidth}{\n")
-  cat("\\textbf{\\textcolor{red}{\\Large \\ding{56}} Cannot include file: \\texttt{",
-      filename, "}}\\\\\n", sep = "")
-  cat("\\vspace{0.2cm}\n")
-  cat("\\textbf{Error:} ", gsub("_", "\\\\_", error_msg, fixed = TRUE), "\n", sep = "")
-  cat("}}\n")
-  cat("\\end{center}\n\n")
+  # Use simple markdown formatting that will be reliably converted by pandoc
+  # Avoid complex LaTeX to prevent compilation errors
+  cat("**ERROR: Cannot include file:** `", filename, "`\n\n", sep = "")
+  cat("**Reason:** ", error_msg, "\n\n", sep = "")
+  cat("---\n\n")
 }
 
 ##' Render single-page image for certificate output
@@ -235,12 +232,17 @@ render_manifest_image <- function(path, comment) {
                       paste("Failed to convert", format_name, "image:", e$message))
     })
   } else {
-    # PNG, JPG, JPEG - include directly
+    # PNG, JPG, JPEG - validate image before including
     tryCatch({
+      # Validate that the file is actually a valid image using magick
+      # This prevents LaTeX compilation errors from corrupted image files
+      img <- magick::image_read(path)
+
+      # If validation succeeds, include the image
       cat(paste0("![", comment, "](", path, ")\n"))
     }, error = function(e) {
       render_error_box(basename(path),
-                      paste("Failed to include image:", e$message))
+                      paste("Failed to read image file (possibly corrupted):", e$message))
     })
   }
 }

R/manifest.R

@@ -23,10 +23,12 @@ copy_manifest_files <- function(root, metadata, dest_dir,
   outputs = sapply(manifest, function(x) x$file)
   src_files = file.path(root, outputs)
   missing = !file.exists(src_files)
+
+  # Warn about missing files but continue processing
   if (any(missing)) {
-    err = paste("Manifest files missing:\n",
-                paste(src_files[missing], sep='\n'))
-    stop(err)
+    warning("Manifest files missing:\n",
+            paste(src_files[missing], collapse='\n'),
+            "\nThese files will be marked as missing in the certificate.")
   }
 
   dest_files = file.path(dest_dir,
@@ -41,13 +43,23 @@ copy_manifest_files <- function(root, metadata, dest_dir,
     }
   }
 
-  if (overwrite) message("Overwriting output files: ", toString(dest_files))
-  file.copy(src_files, dest_files, overwrite = overwrite)
+  # Only copy files that exist
+  existing_files = !missing
+  if (any(existing_files)) {
+    if (overwrite && any(file.exists(dest_files[existing_files]))) {
+      message("Overwriting output files: ", toString(dest_files[existing_files]))
+    }
+    file.copy(src_files[existing_files], dest_files[existing_files], overwrite = overwrite)
+  }
+
+  # Get file sizes, using NA for missing files
+  file_sizes = rep(NA_real_, length(dest_files))
+  file_sizes[existing_files] = file.size(dest_files[existing_files])
 
   manifest_df = data.frame(output=outputs,
                            comment=sapply(manifest, function(x) x$comment),
                            dest=dest_files,
-                           size=file.size(dest_files),
+                           size=file_sizes,
                            stringsAsFactors = FALSE)
   manifest_df
 }

R/validation.R

@@ -1158,3 +1158,205 @@ validate_certificate_for_rendering <- function(yml_file = "codecheck.yml",
 
   return(invisible(TRUE))
 }
+
+#' Validate certificate identifier exists in GitHub register issues
+#'
+#' Checks if the certificate identifier from a codecheck.yml file has a corresponding
+#' issue in the codecheckers/register GitHub repository. This function validates that:
+#' \itemize{
+#'   \item A matching issue exists for the certificate identifier
+#'   \item Warns if the issue is closed (certificate already completed)
+#'   \item Warns if the issue is unassigned (no codechecker assigned yet)
+#'   \item Stops with error if no matching issue is found
+#' }
+#'
+#' @param yml_file Path to the codecheck.yml file (defaults to "./codecheck.yml")
+#' @param metadata Optional. Pre-loaded metadata list. If NULL, will be loaded from yml_file
+#' @param repo GitHub repository in format "owner/repo". Defaults to "codecheckers/register"
+#' @param strict Logical. If TRUE, treats warnings as errors. Default is FALSE
+#'
+#' @return Invisibly returns a list with the validation result:
+#'   \describe{
+#'     \item{valid}{Logical indicating if validation passed}
+#'     \item{certificate}{The certificate identifier checked}
+#'     \item{issue_number}{GitHub issue number if found, otherwise NULL}
+#'     \item{issue_state}{Issue state ("open" or "closed") if found}
+#'     \item{issue_assignees}{List of assignees if found}
+#'     \item{warnings}{Character vector of warning messages}
+#'     \item{errors}{Character vector of error messages}
+#'   }
+#'
+#' @examples
+#' \dontrun{
+#' # Validate certificate in current directory
+#' validate_certificate_github_issue()
+#'
+#' # Validate with strict mode (warnings become errors)
+#' validate_certificate_github_issue(strict = TRUE)
+#'
+#' # Validate specific file
+#' validate_certificate_github_issue("path/to/codecheck.yml")
+#' }
+#'
+#' @author Daniel Nüst
+#' @importFrom gh gh
+#' @export
+validate_certificate_github_issue <- function(yml_file = "codecheck.yml",
+                                               metadata = NULL,
+                                               repo = "codecheckers/register",
+                                               strict = FALSE) {
+
+  # Load metadata if not provided
+  if (is.null(metadata)) {
+    if (!file.exists(yml_file)) {
+      stop("codecheck.yml file not found at: ", yml_file)
+    }
+    metadata <- yaml::read_yaml(yml_file)
+  }
+
+  # Get certificate identifier
+  certificate <- metadata$certificate
+
+  if (is.null(certificate) || certificate == "") {
+    stop("Certificate identifier not found in codecheck.yml",
+         call. = FALSE)
+  }
+
+  # Check if certificate is a placeholder
+  if (is_placeholder_certificate(yml_file = yml_file,
+                                  metadata = metadata,
+                                  strict = FALSE)) {
+    message("Certificate identifier '", certificate, "' appears to be a placeholder. ",
+            "Skipping GitHub issue validation.")
+    return(invisible(list(
+      valid = TRUE,
+      certificate = certificate,
+      issue_number = NULL,
+      issue_state = NULL,
+      issue_assignees = NULL,
+      warnings = character(0),
+      errors = character(0),
+      skipped = TRUE
+    )))
+  }
+
+  # Split repo into owner and name
+  repo_parts <- strsplit(repo, "/")[[1]]
+  if (length(repo_parts) != 2) {
+    stop("repo must be in format 'owner/repo'", call. = FALSE)
+  }
+
+  # Certificate pattern in issue titles: YYYY-NNN
+  cert_pattern <- paste0("\\b", gsub("-", "-", certificate), "\\b")
+
+  # Search for issues with the certificate ID (search all states)
+  tryCatch({
+    # Search in all issues (open + closed)
+    all_issues <- gh::gh("GET /repos/:owner/:repo/issues",
+                         owner = repo_parts[1],
+                         repo = repo_parts[2],
+                         state = "all",
+                         per_page = 100)
+
+    # Find matching issue
+    matching_issue <- NULL
+    for (issue in all_issues) {
+      if (grepl(cert_pattern, issue$title)) {
+        matching_issue <- issue
+        break
+      }
+    }
+
+    # Initialize result
+    warnings <- character(0)
+    errors <- character(0)
+    valid <- TRUE
+
+    # Check if issue was found
+    if (is.null(matching_issue)) {
+      error_msg <- paste0(
+        "No GitHub issue found for certificate '", certificate, "' ",
+        "in repository '", repo, "'. ",
+        "Please ensure an issue exists in the register before proceeding."
+      )
+      errors <- c(errors, error_msg)
+      stop(error_msg, call. = FALSE)
+    }
+
+    issue_number <- matching_issue$number
+    issue_state <- matching_issue$state
+    issue_assignees <- matching_issue$assignees
+
+    # Check if issue is closed
+    if (issue_state == "closed") {
+      warning_msg <- paste0(
+        "GitHub issue #", issue_number, " for certificate '", certificate, "' ",
+        "is already CLOSED. This usually means the CODECHECK has been completed and published. ",
+        "If you are still working on it, consider reopening the issue."
+      )
+      warnings <- c(warnings, warning_msg)
+      warning(warning_msg, call. = FALSE)
+
+      if (strict) {
+        valid <- FALSE
+      }
+    }
+
+    # Check if issue is unassigned
+    if (length(issue_assignees) == 0) {
+      warning_msg <- paste0(
+        "GitHub issue #", issue_number, " for certificate '", certificate, "' ",
+        "is UNASSIGNED. Please assign a codechecker to this issue."
+      )
+      warnings <- c(warnings, warning_msg)
+      warning(warning_msg, call. = FALSE)
+
+      if (strict) {
+        valid <- FALSE
+      }
+    }
+
+    # If strict mode and we have warnings, stop
+    if (strict && !valid) {
+      stop("Certificate validation failed in strict mode: ",
+           paste(warnings, collapse = "; "),
+           call. = FALSE)
+    }
+
+    # Success message
+    if (valid && length(warnings) == 0) {
+      message("Certificate '", certificate, "' validated: ",
+              "Found in GitHub issue #", issue_number, " (", issue_state, ")")
+    }
+
+    return(invisible(list(
+      valid = valid,
+      certificate = certificate,
+      issue_number = issue_number,
+      issue_state = issue_state,
+      issue_assignees = issue_assignees,
+      issue_title = matching_issue$title,
+      warnings = warnings,
+      errors = errors,
+      skipped = FALSE
+    )))
+
+  }, error = function(e) {
+    # Handle GitHub API errors
+    if (grepl("HTTP 404", e$message) || grepl("Not Found", e$message)) {
+      stop("GitHub repository '", repo, "' not found or not accessible. ",
+           "Please check the repository name and your access permissions.",
+           call. = FALSE)
+    } else if (grepl("API rate limit", e$message) || grepl("403", e$message)) {
+      stop("GitHub API rate limit exceeded. ",
+           "Please set a GITHUB_PAT environment variable with a valid GitHub token.",
+           call. = FALSE)
+    } else {
+      # Re-throw if already our custom error
+      if (grepl("No GitHub issue found", e$message)) {
+        stop(e)
+      }
+      stop("Error accessing GitHub API: ", e$message, call. = FALSE)
+    }
+  })
+}

README.Rmd

@@ -21,25 +21,50 @@ knitr::opts_chunk$set(
 [![DOI](https://zenodo.org/badge/256862293.svg)](https://zenodo.org/badge/latestdoi/256862293)
 <!-- badges: end -->
 
-`codecheck` is an assistant for conducting CODECHECKs, written in the R language and distributed as an R package.
-The goal of codecheck is to ease the process to create a CODECHECK-ready workspace, and to conduct the actual CODECHECK.
-Furthermore, the package contains some helper functions for managing the [CODECHECK register](https://codecheck.org.uk/register/).
+`codecheck` is an R package to assist codecheckers in creating CODECHECK-ready workspaces and conducting codechecks. This package focuses on the technical workflow for codecheckers using R. It also contains helper functions for managing the [CODECHECK register](https://codecheck.org.uk/register/).
 
-**Learn more about CODECHECK on [https://codecheck.org.uk/](https://codecheck.org.uk/).**
+For general information about the CODECHECK initiative and community processes, visit [https://codecheck.org.uk/](https://codecheck.org.uk/).
 
 ## Installation
 
 The package is not on [CRAN](https://CRAN.R-project.org) yet.
-Install the development version from [GitHub](https://github.com/codecheckers/codecheck) with:
+Install the current version from [GitHub](https://github.com/codecheckers/codecheck) with:
 
 ``` r
 # install.packages("remotes")
 remotes::install_github("codecheckers/codecheck")
 ```
 
+## Quick Start
+
+For first-time codecheckers using this R package:
+
+1. **Fork the research repository** - Fork to the [codecheckers organization](https://github.com/codecheckers) on GitHub
+2. **Clone and navigate to the repository root** - Run R from the top-level directory of the research project
+3. **Create CODECHECK files** - Run `codecheck::create_codecheck_files()` to generate:
+   - A `codecheck.yml` configuration file with metadata (certificate ID, authors, manifest, etc.)
+   - A `codecheck/` directory with report templates
+4. **Define the manifest** - List all computational outputs (figures, tables, data files) that you've successfully reproduced in the `manifest` section of `codecheck.yml`
+5. **Complete the certificate** - Fill in the report template and render it
+6. **Create a record on Zenodo** (or OSF, or ResearchEquals) and submit the draft for feedback to your CODECHECK editor/contact person, e.g., via a sharing link or the CODECHECK Zenodo community; push the `codecheck.yml` to the repository
+
+## Key Concepts
+
+- **Certificate** - The final report documenting your CODECHECK, which includes metadata, the manifest, and your assessment.
+- **codecheck.yml** - The configuration file containing all CODECHECK metadata (paper details, authors, manifest, etc.)
+- **Manifest** - A list of computational output files (figures, data files, tables) that you have successfully reproduced during the CODECHECK. Each manifest entry includes the file path and a brief description. The manifest is defined in the `codecheck.yml`.
+
 ## Usage
 
-See the [main vignette](https://github.com/codecheckers/codecheck/blob/master/vignettes/codecheck_overview.Rmd).
+See the [getting started guide](https://codecheck.org.uk/codecheck/articles/codecheck_overview.html) for step-by-step instructions on using the template and the [workflow descriptions](https://codecheck.org.uk/workflows/) on the overall procedures.
+
+**Note on certificate templates**: The R Markdown template created by this package can be used in multiple ways:
+
+- Execute code in various languages (R, Python, bash, etc.) using knitr's language engines
+- Simply write your certificate narrative without executing any code
+- Mix both approaches as needed
+
+If you prefer working with Jupyter Notebooks (especially for Python-based projects), see the [Python CODECHECK template](https://github.com/codecheckers/codecheck-py) based on a Jupyter Notebook.
 
 ## Development