Introduce and document .ci/lint.R

For use in both .github/workflows/code-quality.yaml and manually,
especially when developing the linters.

Author: aitap

.ci/README.md

@@ -49,6 +49,33 @@ Base R implemented helper script, [originally proposed to base R](https://svn.r-
 
 Base R implemented helper script to orchestrate generation of most artifacts and to arrange them nicely. It is being used only in [_integration_ stage in GitLab CI pipeline](./../.gitlab-ci.yml).
 
+### [`lint.R`](./lint.R)
+
+Base R runner for the manual (non-`lintr`) lint checks to be run from GitHub Actions during the code quality check. The command line arguments are as follows:
+1. Path to the directory containing files defining the linters. A linter is a function that accepts one argument (typically the path to the file) and signals an error if it fails the lint check.
+2. Path to the directory containing files to check.
+3. A regular expression matching the files to check.
+4. An R expression evaluating to a function that processes a single file path into a form understood by the lint functions. Additionally, the function may return `NULL` to indicate that the file must be skipped.
+
+Example command lines:
+
+```sh
+# C linters expect a three-element named list, not the file path
+Rscript .ci/lint.R .ci/linters/c src '[.][ch]$' '
+  function (f) list(
+    c_obj = f, lines = readLines(f),
+    preprocessed = system2("gcc", shQuote(c("-fpreprocessed", "-E", f)), stdout = TRUE, stderr = FALSE)
+  )
+'
+# po linters must skip files that don't differ from master
+Rscript .ci/lint.R .ci/linters/po po '[.]po$' '
+  function (f) {
+    diff_v_master = system2("git", c("diff", "master", f), stdout=TRUE)
+    if (length(diff_v_master)) f
+  }
+'
+```
+
 ## GitLab Open Source Program
 
 We are currently part of the [GitLab for Open Source Program](https://about.gitlab.com/solutions/open-source/). This gives us 50,000 compute minutes per month for our GitLab CI. Our license needs to be renewed yearly (around July) and is currently managed by @ben-schwen.

.ci/lint.R

@@ -0,0 +1,38 @@
+#!/usr/bin/Rscript
+# Runner for the manual lint checks in .ci/linters
+args = commandArgs(TRUE)
+if (identical(args, '--help')) {
+  writeLines(c(
+    'Usage: Rscript .ci/lint.R .ci/linters/<KIND> <WHERE> <WHAT> [PREPROCESS]',
+    'KIND must name the directory containing the *.R files defining the linter functions.',
+    'WHERE must name the directory containing the files to lint, e.g. "po", or "src".',
+    "WHAT must contain the regular expression matching the files to lint, e.g., '[.]po$', or '[.][ch]$'.",
+    'PREPROCESS is an optional R function that accepts a file path and returns an R object accepted by the lint functions, or NULL to skip the file.'
+  ))
+  q('no')
+}
+stopifnot(`Invalid arguments, see .ci/lint.R --help` = length(args) %in% 3:4)
+
+linter_env = new.env()
+for (f in list.files(args[[1]], full.names=TRUE)) sys.source(f, linter_env)
+if (!length(ls(linter_env))) stop(
+  "No linters found after sourcing files in ", dQuote(args[[1]])
+)
+
+sources = list.files(args[[2]], pattern = args[[3]], full.names = TRUE, recursive = TRUE)
+if (!length(sources)) stop(
+  "No files to lint found in directory ", dQuote(args[[2]]), " for mask ", dQuote(args[[3]])
+)
+preprocess = if (length(args) == 4) eval(parse(text = args[[4]])) else identity
+sources = Filter(Negate(is.null), lapply(setNames(nm = sources), preprocess))
+
+okay = TRUE
+for (src in names(sources))
+for (linter in ls(linter_env)) tryCatch(
+  linter_env[[linter]](sources[[src]]),
+  error = function(e) {
+    message('Source file ', dQuote(src), ' failed lint check ', dQuote(linter), ': ', conditionMessage(e))
+    okay <<- FALSE
+  }
+)
+stopifnot(`Please fix the issues above.` = okay)