Introduce semantics-aware parsing of documentation

DESCRIPTION

@@ -27,4 +27,7 @@ Imports:
     utils,
     cli,
     roxygen2
-RoxygenNote: 7.2.3
+RoxygenNote: 7.3.2
+Suggests: 
+    testthat (>= 3.0.0)
+Config/testthat/edition: 3

NAMESPACE

@@ -4,6 +4,8 @@ S3method(check_linter,"function")
 S3method(check_linter,character)
 S3method(check_linter,default)
 S3method(check_linter,list)
+S3method(config_citations,cff)
+S3method(config_citations,default)
 S3method(lint_full_stop,character)
 S3method(lint_full_stop,default)
 S3method(lint_full_stop,roxy_tag)
@@ -19,6 +21,24 @@ S3method(lint_starts_lowercase,roxy_tag)
 S3method(lint_title_case,character)
 S3method(lint_title_case,default)
 S3method(lint_title_case,roxy_tag)
+S3method(rd_df,acronym)
+S3method(rd_df,cite)
+S3method(rd_df,code)
+S3method(rd_df,default)
+S3method(rd_df,dfn)
+S3method(rd_df,email)
+S3method(rd_df,env)
+S3method(rd_df,file)
+S3method(rd_df,href)
+S3method(rd_df,item)
+S3method(rd_df,itemize)
+S3method(rd_df,kbd)
+S3method(rd_df,option)
+S3method(rd_df,pkg)
+S3method(rd_df,preformatted)
+S3method(rd_df,roxy_tag)
+S3method(rd_df,url)
+S3method(rd_df,verb)
 S3method(roxygen2::roclet_output,roclet_roxylint)
 S3method(roxygen2::roclet_process,roclet_roxylint)
 export(check_linter)

R/check_linter.R

@@ -1,4 +1,4 @@
-#' Apply 'roxygen2' linters
+#' Apply 'roxygen2' Linters `r # nolint: sentence_case.`
 #'
 #' Provided a list of linters for a given tag, iterate over linters to raise
 #' alerts during the documentation process.
@@ -15,6 +15,8 @@
 #'
 #' @export
 check_linter <- function(linters, tag, ...) {
+  # content was generated automatically with no originating text
+  if (is.null(tag$raw)) return(invisible(TRUE))
   UseMethod("check_linter")
 }
 
@@ -40,7 +42,7 @@ check_linter.list <- function(linters, tag, ...) {
     linter <- linters[[i]]
     message <- names(linters[i])
     message <- if (!is.null(message) && nchar(message) > 0) message else NULL
-    check_linter(linter, tag, message = message)
+    check_linter(linter, tag, message = message, ...)
   }
   invisible(TRUE)
 }
@@ -63,7 +65,9 @@ check_linter.list <- function(linters, tag, ...) {
 #'
 #' @export
 check_linter.function <- function(linters, tag, ...) {
-  into_roxy_alert(tag, do.call(linters, append(list(tag), tag$val)))
+  args <- list(tag, ...)
+  args <- append(args, tag$val)  # append parsed terms from roxy tag
+  into_roxy_alert(tag, do.call(linters, args))
   invisible(TRUE)
 }
 

R/config.R

@@ -23,6 +23,11 @@ config_load <- function(path = getwd(), cache = TRUE) {
   roxylint <- new.env(parent = baseenv())
   local_config <- config_find_from(path)
 
+  # discover citations
+  if (length(list.files(path, pattern = "^CITATION")) > 0) {
+    roxylint$citations <- config_citations(path)
+  }
+
   # config linters
   for (tag in names(local_config$linters)) {
     add_linters(
@@ -34,7 +39,7 @@ config_load <- function(path = getwd(), cache = TRUE) {
   }
 
   # add non-linter config
-  local_config$lintesr <- NULL
+  local_config$linters <- NULL
   for (n in names(local_config)) {
     roxylint[[n]] <- local_config[[n]]
   }
@@ -121,3 +126,58 @@ config_from_file <- function(path) {
   res <- new.env()
   source(config_files[[1]], local = res)$value
 }
+
+config_citations <- function(path) {
+  UseMethod("config_citations")
+}
+
+#' @export
+config_citations.default <- function(path) {
+  if (file.info(path)$isdir) {
+    config_files <- list.files(
+      path,
+      pattern = "^CITATION",
+      full.names = TRUE,
+      recursive = TRUE
+    )
+
+    return(unlist(recursive = FALSE, lapply(config_files, function(f) {
+      config_citations(f)
+    })))
+  }
+
+  if (nchar(ext <- tools::file_ext(path)) > 0) {
+    class(path) <- c(tolower(ext), class(path))
+    config_citations(path)
+  }
+}
+
+#' @export
+config_citations.cff <- function(path) {
+  if (!requireNamespace("cffr", quietly = TRUE)) {
+    cli::cli_alert_info(
+      "Package {.pkg cffr} is required to use citations to inform lints."
+    )
+    return()
+  }
+
+  derive_citation_data(cffr::cff_read(as.character(path)))
+}
+
+derive_citation_data <- function(x) {
+  data <- list(cff = x)
+
+  # derive proper nouns from authors lists
+  ref_author_names <- function(ref) {
+    lapply(ref$authors, function(author) {
+      author[c("family-names", "given-names")]
+    })
+  }
+
+  data$names <- unique(c(
+    ref_author_names(x),
+    unlist(recursive = FALSE, lapply(x$references, ref_author_names))
+  ))
+
+  data
+}