fix(#135): evaluate @examples extraction without inline-R side effects (#136)

* fix(#135): evaluate @examples extraction without inline-R side effects

`att_from_examples()` delegated example extraction to
`roxygen2::parse_file()`, which unconditionally evaluates inline R
embedded in roxygen markdown tags such as ``@param x `r helper("x")` ``.
roxygen2 evaluates that R in the env returned by `roxy_meta_get("env")`,
which falls back to `baseenv()` outside a full `roxygenise()` context;
any package-local helper is therefore unresolvable, producing a cascade
of "could not find function" messages on every affected tag.

Replace the parse_file call with a focused regex extractor that pulls
`@examples` / `@examplesIf` blocks straight from the source. Example
detection no longer touches roxygen2's tokenizer, so inline R inside
unrelated tags is left strictly alone.

NAMESPACE auto-regen drops the now-unused `roxygen2::parse_file` and
`roxygen2::block_get_tag_value` imports.

Bumps version to 1.0.1 with a NEWS entry.

* fix(#135): mirror att_from_rscript() defensive read pattern

Address Copilot review on PR #136:

- `extract_examples_lines()` was hard-coding `encoding = "UTF-8"` and
  bare-calling `readLines()`. The sibling `att_from_rscript()` uses
  `getOption("encoding")` and a `tryCatch()` that warns + returns
  `character(0)` on read failure. Mirror that pattern so a single
  unreadable source file no longer aborts the whole `att_from_examples()`
  scan, and so non-UTF8 locales (Windows) are respected by default.
- Thread an `encoding` argument through `att_from_examples()` to expose
  the same knob users already have on `att_from_rscript()`.
- NEWS: clarify that roxygen2's inline-R fallback env is `baseenv()` —
  base R is reachable, only package-local helpers are not.

* fix(#135): handle @examplesIf condition + DCF blank line in test fixture

Address Copilot's second review on PR #136:

- `extract_examples_lines()` was including the payload of `@examplesIf`
  (a guard condition like `requireNamespace("foo")`) in the extracted
  example text, so any package mentioned only in the guard was falsely
  detected as a dependency. Split the tag detection so `@examplesIf`
  enters example mode but discards the condition; only the body lines
  that follow are captured.
- Add a focused test asserting the @examplesIf path: the body's deps
  must be detected, the guard's must not.
- The #135 regression test appended `Roxygen: list(markdown = TRUE)` to
  the dummypackage DESCRIPTION via `c(readLines(...), new_line)`, which
  preserved the file's trailing blank line and inserted the new field
  after a blank record separator. DCF parsers may then ignore it. Trim
  trailing empty lines first.

---------

Co-authored-by: Vincent Guyader <10470699+VincentGuyader@users.noreply.github.com>

Author: VincentGuyader

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: attachment
 Title: Deal with Dependencies
-Version: 1.0.0
+Version: 1.0.1
 Authors@R: c(
     person("Vincent", "Guyader", , "vincent@thinkr.fr", role = c("cre", "aut"),
            comment = c(ORCID = "0000-0003-0671-9270")),

NAMESPACE

@@ -29,8 +29,6 @@ importFrom(glue,glue)
 importFrom(glue,glue_collapse)
 importFrom(knitr,purl)
 importFrom(magrittr,"%>%")
-importFrom(roxygen2,block_get_tag_value)
-importFrom(roxygen2,parse_file)
 importFrom(roxygen2,roxygenise)
 importFrom(stats,na.omit)
 importFrom(stats,setNames)

NEWS.md

@@ -1,3 +1,18 @@
+# attachment 1.0.1
+
+## Bug fixes
+
+- `att_from_examples()` (and therefore `att_amend_desc()`) no longer chokes
+  on inline R inside roxygen2 markdown tags such as
+  `@param x \`r helper("x")\`` when `helper()` is a package-local function.
+  Previously, `att_from_examples()` delegated to `roxygen2::parse_file()`,
+  which evaluated inline R against `baseenv()` (roxygen2's fallback when
+  no package env is registered) — base R is reachable, but package-local
+  helpers are not, so each affected tag emitted
+  `could not find function "helper"`.
+  Example detection now uses a focused regex over the source instead of
+  the full roxygen2 tokenizer (#135).
+
 # attachment 1.0.0
 
 ## Detection — new foundation

R/add_from_examples.R

@@ -1,29 +1,29 @@
 #' Get all packages called in examples from R files
 #'
 #' @param dir.r path to directory with R scripts.
+#' @param encoding Encoding passed to [readLines()] when reading source files.
+#'  Defaults to `getOption("encoding")` so the system locale is respected,
+#'  matching [att_from_rscript()].
 #'
 #' @return Character vector of packages called with library or require.
-#' @importFrom roxygen2 parse_file block_get_tag_value
 #' @examples
 #' dummypackage <- system.file("dummypackage",package = "attachment")
 #'
 #' # browseURL(dummypackage)
 #' att_from_examples(dir.r = file.path(dummypackage,"R"))
 
 #' @export
-att_from_examples <- function(dir.r = "R") {
+att_from_examples <- function(dir.r = "R", encoding = getOption("encoding")) {
   rfiles <- list.files(dir.r, full.names = TRUE, pattern = "\\.r$", ignore.case = TRUE,recursive = FALSE)
 
   roxy_file <- tempfile("roxy.examples", fileext = ".R")
 
-  all_examples <- unlist(lapply(rfiles, function(the_file) {
-    file_roxytags <- roxygen2::parse_file(the_file)
-    res <- unlist(
-      lapply(file_roxytags,
-             function(x) roxygen2::block_get_tag_value(block = x, tag = "examples"))
-    )
-    res
-  }))
+  # Extract @examples / @examplesIf blocks via regex on the source instead of
+  # roxygen2::parse_file(). parse_file() unconditionally evaluates inline R
+  # found in roxygen markdown (e.g. `@param x \`r helper("x")\``), and the
+  # evaluation env defaults to baseenv() outside a full roxygenise() context,
+  # which makes any package-local helper unresolvable (issue #135).
+  all_examples <- unlist(lapply(rfiles, extract_examples_lines, encoding = encoding))
   # Clean \dontrun and \donttest, and replace with '{' on next line
   all_examples_clean <-
     gsub(pattern = "\\\\dontrun\\s*\\{|\\\\donttest\\s*\\{", replacement = "#ICI\n{", x = all_examples)
@@ -43,3 +43,57 @@ att_from_examples <- function(dir.r = "R") {
 
   return(all_deps)
 }
+
+# Extract @examples / @examplesIf blocks from a single R source file, returning
+# the example code with the leading `#' ` removed. Mirrors the relevant subset
+# of roxygen2::parse_file() + block_get_tag_value(tag = "examples") behaviour
+# without triggering inline R evaluation of @param markdown.
+#
+# `@examplesIf` is treated specially: the payload on the tag line is a guard
+# *condition*, not example code, so it is discarded — including the condition
+# in the extracted text would cause packages mentioned only in the guard to be
+# falsely picked up as dependencies. The example body that follows is captured
+# normally.
+extract_examples_lines <- function(rfile, encoding = getOption("encoding")) {
+  lines <- tryCatch(
+    readLines(rfile, warn = FALSE, encoding = encoding),
+    error = function(e) {
+      warning(
+        sprintf("Could not read R script '%s': %s", rfile, conditionMessage(e)),
+        call. = FALSE
+      )
+      character(0)
+    }
+  )
+  if (length(lines) == 0) return(character(0))
+
+  is_roxy <- grepl("^\\s*#'", lines)
+  is_tag  <- grepl("^\\s*#'\\s*@", lines)
+  is_example_tag   <- grepl("^\\s*#'\\s*@examples\\b",   lines)
+  is_examplesif_tag <- grepl("^\\s*#'\\s*@examplesIf\\b", lines)
+
+  out <- character()
+  in_example <- FALSE
+  for (i in seq_along(lines)) {
+    if (is_examplesif_tag[i]) {
+      in_example <- TRUE
+      next
+    }
+    if (is_example_tag[i]) {
+      in_example <- TRUE
+      first_payload <- sub("^\\s*#'\\s*@examples\\s*", "", lines[i])
+      if (nzchar(first_payload)) {
+        out <- c(out, first_payload)
+      }
+      next
+    }
+    if (in_example) {
+      if (!is_roxy[i] || is_tag[i]) {
+        in_example <- FALSE
+        next
+      }
+      out <- c(out, sub("^\\s*#'\\s?", "", lines[i]))
+    }
+  }
+  out
+}

man/att_from_examples.Rd

@@ -127,3 +127,116 @@ test_that("bad namespace can be corrected", {
 unlink(dummypackage, recursive = TRUE)
 unlink(tmpdir, recursive = TRUE)
 
+# Issue #135: inline R in @param must resolve package-local functions ----
+tmpdir <- tempfile(pattern = "pkginline")
+dir.create(tmpdir)
+file.copy(
+  system.file("dummypackage", package = "attachment"), tmpdir,
+  recursive = TRUE)
+dummypackage <- file.path(tmpdir, "dummypackage")
+
+# Enable roxygen markdown so inline R inside @param is actually evaluated.
+# Strip trailing blank lines from the dummypackage DESCRIPTION before
+# appending: in DCF format a blank line starts a new record, so an
+# unstripped append would silently produce a second record and tooling may
+# ignore the new field.
+desc_file <- file.path(dummypackage, "DESCRIPTION")
+desc_lines <- readLines(desc_file)
+while (length(desc_lines) > 0 && !nzchar(desc_lines[length(desc_lines)])) {
+  desc_lines <- desc_lines[-length(desc_lines)]
+}
+writeLines(c(desc_lines, "Roxygen: list(markdown = TRUE)"), desc_file)
+
+# Add an exported helper that the @param will call inline
+helper_file <- file.path(dummypackage, "R", "helper.R")
+writeLines(
+  c(
+    "#' Return a doc snippet",
+    "#' @param name a name",
+    "#' @return a string",
+    "#' @export",
+    "helper <- function(name) {",
+    "  paste('a', name, 'parameter')",
+    "}"
+  ),
+  helper_file
+)
+
+# Rewrite my_mean.R so its @param uses inline R calling the package-local helper
+my_mean_file <- file.path(dummypackage, "R", "my_mean.R")
+writeLines(
+  c(
+    "#' my_mean",
+    "#'",
+    "#' @param x `r helper(\"x\")`",
+    "#'",
+    "#' @export",
+    "#' @importFrom magrittr %>%",
+    "my_mean <- function(x){",
+    "  x <- x %>% stats::na.omit()",
+    "  sum(x) / base::length(x)",
+    "}"
+  ),
+  my_mean_file
+)
+
+test_that("inline R in @param resolves package-local functions (#135)", {
+  unlink(file.path(dummypackage, "man"), recursive = TRUE)
+
+  captured <- character()
+  withCallingHandlers(
+    att_amend_desc(dummypackage),
+    message = function(m) {
+      captured <<- c(captured, conditionMessage(m))
+      invokeRestart("muffleMessage")
+    },
+    warning = function(w) {
+      captured <<- c(captured, conditionMessage(w))
+      invokeRestart("muffleWarning")
+    }
+  )
+
+  expect_false(
+    any(grepl("could not find function", captured, fixed = TRUE)),
+    info = paste0(
+      "Inline R in @param failed to resolve `helper()`. Captured conditions:\n",
+      paste(captured, collapse = "\n")
+    )
+  )
+
+  rd_file <- file.path(dummypackage, "man", "my_mean.Rd")
+  expect_true(file.exists(rd_file))
+  rd_content <- paste(readLines(rd_file), collapse = "\n")
+  expect_match(rd_content, "a x parameter", fixed = TRUE)
+})
+
+unlink(tmpdir, recursive = TRUE)
+
+# @examplesIf condition payload must NOT be scanned for dependencies (#136 review) ----
+tmpdir <- tempfile(pattern = "pkgexamplesif")
+dir.create(tmpdir)
+ifpkg_dir <- file.path(tmpdir, "Rscripts")
+dir.create(ifpkg_dir)
+ifpkg_file <- file.path(ifpkg_dir, "fun.R")
+writeLines(
+  c(
+    "#' fun",
+    "#' @param x a value",
+    "#' @return x",
+    "#' @export",
+    "#' @examplesIf requireNamespace(\"fakeguardpkg\", quietly = TRUE)",
+    "#' library(magrittr)",
+    "#' x %>% identity()",
+    "fun <- function(x) x"
+  ),
+  ifpkg_file
+)
+
+test_that("att_from_examples ignores @examplesIf condition for dep detection (#136 review)", {
+  deps <- att_from_examples(dir.r = ifpkg_dir)
+  expect_true("magrittr" %in% deps)
+  expect_false("fakeguardpkg" %in% deps)
+})
+
+unlink(tmpdir, recursive = TRUE)
+